@stacksjs/defaults 0.75.227 → 0.75.229

package/ai/skills/stacks-payments/SKILL.md

@@ -136,8 +136,9 @@ const changed = await Payment.changeSubscription(user, 'enterprise-monthly')
 ```typescript
 import { manageConnectedAccount, manageDestinationCharge, manageDestinationSubscription } from '@stacksjs/payments'
 
-// Onboard: create once (deterministic idempotency key), then a hosted onboarding link
-const account = await manageConnectedAccount.createConnectedAccount(user)
+// Onboard: create once (deterministic idempotency key), then a hosted onboarding link.
+// `reference` names which of the user's accounts this is (a gym, a coach storefront).
+const account = await manageConnectedAccount.createConnectedAccount(user, {}, { reference: `gym:${gym.id}` })
 const link = await manageConnectedAccount.accountOnboardingLink(account.id, { refreshUrl, returnUrl })
 const status = await manageConnectedAccount.accountStatus(account.id) // chargesEnabled, payoutsEnabled, currentlyDue...
 
@@ -156,11 +157,118 @@ const session = await manageDestinationSubscription.checkout(user, {
 })
 ```
 
+- `createConnectedAccount(user, params?, { reference? })` and `createTestConnectedAccount` key their idempotency on the user, `reference` and a fingerprint of the merged creation params (`connectedAccountIdempotencyKey`). A retry of the same call returns the original account; another reference or other params create another. Keyed by user alone, a user's second account inside Stripe's 24-hour window collided with the first. Pass a stable `reference` whenever one user can own more than one account.
 - A destination subscription lives on the platform with `transfer_data.destination`, so renewals (`invoice.paid`), failed payments (`invoice.payment_failed`), status changes and cancellation (`customer.subscription.updated` / `.deleted`) arrive on the platform's normal webhook endpoint, not the Connect one. `destinationOf(subscription)` (also `connect.subscriptionDestination`) tells a merchant's subscription from the platform's own.
 - Its fee is `application_fee_percent` (`feePercentFor`, at most two decimals; 0 sends no fee field), applied to every invoice, unlike a charge's fee amount.
 - Cancel, resume and read it with `manageSubscription` (`cancelAtPeriodEnd`, `resume`, `cancel`); entitlement from `subscriptionGrantsAccess(status)` and dates from `subscriptionPeriod(subscription)`.
 - Events about a connected account itself (`account.updated`, `payout.*`) come to the Connect endpoint with `event.account`; read it with `getConnectedAccountId(event)`.
 
+#### Destination-charge params (pure)
+
+When you build the Stripe call yourself (a Checkout with your own line items, a
+subscription for a member who already has a card on file), spread the Connect
+fields from these builders instead of hand-writing them. They validate, read no
+config, call no API, and are typed with Stripe's own params (`src/connect/destination.ts`).
+
+```typescript
+import {
+  checkoutLineItemsTotal,
+  destinationCheckoutPaymentData,
+  destinationCheckoutSubscriptionData,
+  destinationPaymentIntentParams,
+  destinationSubscriptionParams,
+  stripe,
+} from '@stacksjs/payments'
+
+const connect = { destination: 'acct_gym', feePercent: 5, rounding: 'round' as const, onBehalfOf: false }
+
+// Checkout, mode: 'payment': the fee is an amount, worked out from the line items
+await stripe.checkout.sessions.create({
+  mode: 'payment',
+  line_items,
+  payment_intent_data: destinationCheckoutPaymentData(checkoutLineItemsTotal(line_items), connect, { metadata }),
+  success_url, cancel_url,
+})
+
+// Checkout, mode: 'subscription': the fee is a percent of every invoice
+await stripe.checkout.sessions.create({ mode: 'subscription', line_items, subscription_data: destinationCheckoutSubscriptionData(connect, { metadata }), success_url, cancel_url })
+
+// Direct API calls
+await stripe.subscriptions.create({ customer, items: [{ price }], ...destinationSubscriptionParams(connect) })
+await stripe.paymentIntents.create({ amount: 4900, currency: 'eur', customer, ...destinationPaymentIntentParams(4900, { destination: 'acct_gym', feeCents: 250 }) })
+```
+
+| Option | Meaning |
+|---|---|
+| `destination` | `acct_...`; anything else throws (`requireAccountId`) |
+| `feePercent` | 0 to 100. One-off charges turn it into an amount; subscriptions send `application_fee_percent` (at most two decimals; float sums like `0.1 + 0.2` are snapped) |
+| `feeCents` | Exact fee in minor units; wins on one-off charges, refused on subscriptions |
+| `rounding` | `'floor'` (default, as `applicationFeeFor`) or `'round'` (nearest cent). Never exceeds the charge |
+| `onBehalfOf` | Sets `on_behalf_of` to the destination (the merchant's descriptor and settlement country) |
+| `transferGroup` | One-off charges only |
+
+A zero or missing fee sends no fee field. `destinationFeeCents(amount, opts)` and
+`destinationFeePercent(opts)` expose the fee arithmetic alone. The third
+argument of the Checkout builders carries the session's other fields (metadata,
+`trial_period_days`); the Connect fields win over it. `checkoutLineItemsTotal`
+counts `price_data` lines and refuses a catalog `price` (its amount is unknown
+here).
+
+`splitFee(cents, weights, fallback?)` splits a fee into named shares that always
+add up to it (largest remainder, ties to the earlier key; a negative amount, a
+refunded fee, splits the same way negated; all-zero weights give it all to
+`fallback`, default the first key): `splitFee(101, { tip: 2, planet: 1 })` is
+`{ tip: 67, planet: 34 }`.
+
+#### Connect-aware refunds
+
+Refunding a destination charge like any other pays the buyer out of the
+PLATFORM's balance and leaves the merchant the sale and the platform its fee.
+Stripe reverses both only when asked:
+
+```typescript
+import { connectRefund, connectRefundParams, isDestinationCharge } from '@stacksjs/payments'
+
+// Retrieves the PaymentIntent (latest_charge expanded) or Charge, then refunds
+await connectRefund('pi_xxx', { amount: 500, reason: 'requested_by_customer', idempotencyKey: `refund:${row.id}` })
+
+// Pure, when you already hold the object
+const intent = await stripe.paymentIntents.retrieve(id, { expand: ['latest_charge'] })
+await stripe.refunds.create(connectRefundParams(intent, { amount: 500 }), { idempotencyKey })
+```
+
+`reverse_transfer` is set on a destination charge (`transfer_data.destination`
+on the intent or charge, or a charge's `transfer`); `refund_application_fee`
+when it also took a fee. `reverseTransfer: false` / `refundApplicationFee: false`
+opt out (a platform that keeps its fee on refunds). A platform charge refunds
+plainly. Pass a deterministic `idempotencyKey`; without one each call is a new
+refund. Also `Payment.connect.refund` / `.refundParams` / `.isDestinationCharge`.
+
+#### Checkout outcomes: `checkoutOutcome(event)`
+
+```typescript
+import { checkoutOutcome } from '@stacksjs/payments'
+
+const outcome = checkoutOutcome(event) // null for anything but checkout.session.*
+if (outcome?.status === 'paid') await fulfil(outcome.reference, outcome.paymentIntentId)
+else if (outcome?.status === 'processing') await markPending(outcome.reference, outcome.subscriptionId)
+else if (outcome?.status === 'failed' || outcome?.status === 'expired') await release(outcome.reference)
+```
+
+| Event | `payment_status` | `status` |
+|---|---|---|
+| `checkout.session.completed` | `paid` / `no_payment_required` | `paid` |
+| `checkout.session.completed` | `unpaid` (SEPA, Bacs, ACH, bank redirect) | `processing` |
+| `checkout.session.async_payment_succeeded` | `paid` | `paid` |
+| `checkout.session.async_payment_failed` | any | `failed` |
+| `checkout.session.expired` | any | `expired` |
+
+The outcome also carries `session`, `sessionId`, `reference`
+(`client_reference_id`), `paymentIntentId`, `subscriptionId`, `customerId` (ids
+whether expanded or not), `mode`, `amountTotal`, `currency` (lower case) and
+`metadata`. It reads only the event: verify the signature and match the session
+to your own record before acting. Fulfil on `paid` only.
+
 ### Bank debits (SEPA Direct Debit, Bacs, ACH, BECS)
 
 `src/direct-debit.ts` (also `@stacksjs/payments/direct-debit`, pure and browser-safe) holds what a debit needs next to cards:
@@ -376,7 +484,8 @@ Payment.onCharge({
 const result = await Payment.processWebhook(rawPayload, signatureHeader, {
   secret: 'whsec_xxx', tolerance: 300
 })
-// Returns: { success: boolean, eventType?: string, error?: string }
+// Returns: { success: boolean, eventType?: string, error?: string, duplicate?: true }
+// Answer 2xx on success (a duplicate is a success), non-2xx otherwise so Stripe retries.
 
 // Low-level: register any event type
 Payment.webhook.onWebhookEvent('payment_method.attached', handler)
@@ -386,6 +495,12 @@ Payment.webhook.registerWebhookHandlers({ 'payment_intent.succeeded': handler })
 import { getPaymentIntent, getSubscription, getInvoice, getCheckoutSession, getCharge, getCustomer } from '@stacksjs/payments'
 ```
 
+Replays run once. Stripe delivers at least once, so `handleWebhookEvent` (and `processWebhook` through it) skips an event whose `evt_` id already ran its handlers and answers `duplicate: true`. The id is recorded only after every handler for it succeeded: a handler that throws leaves the event unrecorded, `processWebhook` reports `success: false`, and the provider's retry runs the handlers again (all of them, so keep each one safe to repeat). A second delivery arriving while the first is still running waits for it. Events without an id and events with no registered handler are not recorded.
+
+- Store: `payment_webhook_events` under provider `stripe:handlers` (`WEBHOOK_HANDLERS_PROVIDER`), apart from commerce's `stripe` rows so the two paths never skip each other's events. Before the table is migrated it falls back to an in-process memory store with a TTL (warns once). Another database error throws, so `processWebhook` answers failure and Stripe retries.
+- Opt out per call with `{ dedupe: false }` (`processWebhook` config or `handleWebhookEvent(event, options)`). Swap the store with `setWebhookEventStore(store)` or per call with `{ store }`; `memoryWebhookEventStore({ ttlSeconds, maxEntries })` and `databaseWebhookEventStore(provider?)` are exported.
+- Tolerance: `processWebhook` passes `tolerance` to verification, and the driver path (`paymentDriver().verifyWebhook`) reads `payment.stripe.webhookTolerance`, then `payment.webhook.tolerance`, then Stripe's 300 s default. It used to drop it.
+
 Supported webhook event types: `payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.created`, `payment_intent.canceled`, `customer.subscription.created/updated/deleted`, `customer.subscription.trial_will_end`, `customer.created/updated/deleted`, `invoice.paid/payment_failed/finalized/created`, `checkout.session.completed/expired`, `charge.succeeded/failed/refunded`, `charge.dispute.created/closed`, `payment_method.attached/detached`, `setup_intent.succeeded/setup_failed`, plus any string.
 
 ### Setup Products from SaaS Config
@@ -589,7 +704,7 @@ for the plans it is meant for.
 - `payment_methods` -- columns: `id`, `type`, `last_four`, `brand`, `exp_year`, `exp_month`, `user_id`, `provider_id`, `is_default`
 - `payment_products` -- columns: `id`, `name`, `unit_price`
 - `payment_transactions` -- columns: `id`, `name`, `description`, `amount`, `brand`, `type`, `provider_id`, `user_id`
-- `payment_webhook_events` -- columns: `provider`, `event_id` (unique together), `processed_at`; commerce's webhook dedup
+- `payment_webhook_events` -- columns: `provider`, `event_id` (unique together), `processed_at`; commerce's webhook dedup (provider = driver name) and the handler registry's (provider `stripe:handlers`)
 
 ## User Model Requirements
 The `UserModel` must have:
@@ -663,4 +778,4 @@ The instance methods are exactly the keys of `createBillableMethods` in
 - Subscription status checks query the local database, not Stripe directly
 - `list()` on products defaults to `active: true` only
 - Webhook handlers are stored in an in-memory Map -- register them on application startup
-- `processWebhook()` uses `stripe.webhooks.constructEvent()` for signature verification
+- `processWebhook()` verifies with `stripe.webhooks.constructEventAsync()` (async on every runtime) and dedupes by event id; see Webhooks

package/ai/skills/stacks-router/SKILL.md

@@ -61,6 +61,25 @@ route.get('/admin', handler)
   .name('admin.dashboard')
 ```
 
+### Rate limits and the client address
+
+`.rateLimit(max, 'minute' | seconds)` on a route and `await rateLimit(key, max,
+{ identity? }).per('hour')` in an action count in the configured Redis cache
+when `config/cache.ts` selects Redis (one budget across every worker and
+instance), otherwise, and while Redis is unreachable (warned once), in process
+memory. `useRateLimitStorage(storage | null)` installs any ts-rate-limiter
+`StorageProvider` (call `resetRateLimiters()` after). Every `max`, the Throttle
+middleware's and the login lockout's are multiplied by
+`config.security.rateLimit.scale` (`STACKS_RATE_LIMIT_SCALE`, default 1):
+raise it in a test suite instead of turning limits off.
+
+The anonymous identity is `clientAddress(req)` from `@stacksjs/router`, which
+shadows bun-router's export and believes forwarding headers only from
+`config.security.trustedProxies` (unset: loopback, private and link-local
+networks; `[]`: none). Set it to the load balancer's ranges when other hosts
+share the private network. bun-router's own `request.ip()` and the server
+package's maintenance allow-list still use the bun-router default.
+
 ### Route Groups
 ```typescript
 route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
@@ -336,6 +355,9 @@ bundles, and feature gates decide the mounted surface; inspect `buddy route:list
 - `POST /login`, `POST /register`, `POST /auth/refresh`, `POST /auth/token`
 - `GET /auth/tokens`, `DELETE /auth/tokens/{id}` (auth)
 - `GET /me`, `POST /logout` (auth)
+- Social bundle: `GET /auth/{provider}`, `GET|POST /auth/{provider}/callback`
+  (POST skips CSRF; the browser-bound OAuth state is checked instead),
+  `POST /auth/handoff` (redeems the callback's one-use code)
 
 ### Email
 - `POST /api/email/subscribe`, `GET /api/email/unsubscribe`
@@ -375,7 +397,7 @@ url('user.show', { id: 42 })             // '/users/42'
 
 ## Gotchas
 - Routes use `@stacksjs/bun-router` under the hood
-- Rate limiting via `ts-rate-limiter` is built into the router
+- Rate limiting via `ts-rate-limiter` is built into the router; it is shared through Redis only when the cache driver is Redis
 - Route registry in `app/Routes.ts` maps file names to URL prefixes
 - String-based handlers (`'Actions/MyAction'`) are dynamically imported
 - Middleware priority: lower number = runs first

package/ai/skills/stacks-security/SKILL.md

@@ -101,6 +101,12 @@ interface HashMakeOptions {
 ## config/security.ts
 ```typescript
 {
+  // Application rate limits and the login lockout are multiplied by this.
+  // Keep 1 in production; tests raise it (or STACKS_RATE_LIMIT_SCALE).
+  rateLimit: { scale: 1 },
+  // Proxies whose forwarding headers name the client (clientAddress()).
+  // Unset = loopback/private/link-local; [] = trust none.
+  trustedProxies: ['10.0.0.0/8'],
   firewall: {
     enabled: true,
     countryCodes: [],                // block by country
@@ -151,7 +157,8 @@ import { eraseSubject, exportSubjectData, pruneRetainedData } from '@stacksjs/or
 - Base64 is encoding, not hashing. Never use `base64Encode()` for credentials.
 - MD5 and base64 password verification are intentionally absent from the main security API.
 - The firewall config is used by cloud deployment for WAF rules
-- Rate limiting is per-minute per-IP (500 default)
+- The firewall rate limit is per-minute per-IP at the WAF (`firewall.rateLimitPerMinute`)
+- Application rate limits (`.rateLimit()`, `rateLimit()`, the login lockout) share the Redis cache when it is configured and count per process otherwise; see `stacks-router`
 
 
 ## Encryption and webhook contracts
@@ -208,3 +215,39 @@ endpoints; a cloud WAF setting does not implement model row authorization.
 Capability/config validation and credential recovery have separate tests and
 failure contracts; propagate their real errors rather than interpreting an
 awaited call as proof that a security state transition persisted.
+
+## Shadowed security defaults
+
+`app/` wins resolution over `storage/framework/defaults/app/`, so an app copy of
+a security default freezes that code: framework security fixes to it never run.
+The API server (`buddy dev` and `serve`) warns once at boot, and `buddy doctor`
+reports a "Security overrides" warning, for every file in
+`SECURITY_DEFAULT_FILES` (`@stacksjs/server`) that the app shadows. That list
+covers the Auth, Guest, Csrf, Cors, Throttle, Signed, Abilities, Can,
+Permission, Role and EnsureEmailIsVerified middleware; the sign-in, session,
+token, OAuth, passkey, magic-link, social and session-handoff actions with their
+helpers; and the password-reset actions.
+
+- `identical`: a byte-for-byte copy. Delete it, since it does nothing except
+  block fixes.
+- `modified`: diff it against the current default and port any fixes. Once
+  reviewed, add `// stacks-reviewed-default: <fingerprint>` (the warning prints
+  the value). The fingerprint is a hash of the default, so the warning comes
+  back when the framework changes that default.
+
+Set `STACKS_SHADOWED_DEFAULTS_WARN=false` to silence it. To check
+programmatically, call `findShadowedSecurityDefaults(appDir, defaultsDir)`,
+which returns `{ path, kind, appFile, defaultFile, fingerprint }[]`. Keep app
+hooks in events or app-owned actions rather than copying these files.
+
+## Credential and sign-in hardening
+
+- Social sign-in state is single use, browser bound and stored as a digest
+  (`issueOAuthFlow` / `consumeOAuthFlow`, `stacks-socials`); the callback hands
+  over a one-use code, never tokens in a URL (`createSessionHandoff`,
+  `stacks-auth`).
+- Any change to how an account proves who it is runs
+  `revokeAccountCredentials()` (`stacks-auth`): stamp, then revoke challenges,
+  magic links, OAuth grants, tokens and sessions in one transaction.
+- SMS STOP is never bypassed by `ignorePreferences`; only an explicit
+  `ignoreOptOut` for legally required messages (`stacks-notifications`).

package/ai/skills/stacks-socials/SKILL.md

@@ -27,29 +27,64 @@ provider test before handling one-time Apple name data or ID-token verification.
 Meta API version is centralized in meta-graph.ts rather than an obsolete v18
 copied into every example.
 
-Scopes/setScopes/with/setRedirectUrl belong to AbstractProvider. Providers read
-their actual services config and impose provider-specific scope and credential
-rules. withState supplies the flow's state and validateState checks the expected
-and returned values; persist expected state in the native callback session.
-Twitter sign-in keeps a PKCE verifier on its instance; getAuthUrl must
-precede its exchange on the same stateful flow. Persist and validate state/PKCE
-through the native callback path before minting an app credential; low-level
-getUserByToken alone does not prove the browser initiated a login.
+Scopes/setScopes/with/setRedirectUrl/withState belong to AbstractProvider and
+are on ProviderInterface, so the registry's `socialProvider()` result can be
+driven without casts. Every OAuth2 driver honours withState, with() and an
+instance redirect. X always uses PKCE; its verifier lives in the base class
+(getPkceVerifier/withCodeVerifier), so a callback on a fresh instance can
+restore it. Registry descriptors say `pkce` (X) and `nonce` (Apple).
+
+## Flow state (login CSRF)
+
+A callback that exchanges any `code` signs the victim into the attacker's
+account. Start every flow with
+`issueOAuthFlow({ purpose, userId?, data?, ttlMs, bindBrowser?, challenge?, nonce?, cookie? })`,
+which returns `{ state, cookie, secret, nonce?, expiresAt }`: a random state for
+`withState()`, and a `Set-Cookie` (HttpOnly, per-flow `stacks_oauth_*` name,
+`SameSite=Lax`, or `None; Secure` for Apple's cross-site form_post) binding it
+to the browser. Only SHA-256 digests are stored, in the auth-owned
+`oauth_flows` table (`buddy migrate`). On the callback,
+`consumeOAuthFlow(state, { purpose, browserSecret })` returns
+`{ purpose, userId, nonce, data, expiresAt }` once, or null for an unknown,
+spent, expired, foreign-purpose or other-browser state; a mismatch does not burn
+the real flow. Read the secret with `readOAuthFlowCookie(cookieHeader, state)`
+and clear it on every outcome with `clearOAuthFlowCookie(state, cookieOptions)`.
+`challenge` binds to the SHA-256 hex of a native client's verifier instead of a
+cookie. `nonce: true` mints an OIDC nonce: pass it with `with({ nonce })` and
+to `getUserByToken(token, { nonce })`, which refuses a mismatched id_token.
+`useOAuthFlowStore(memoryOAuthFlowStore())` swaps storage in tests;
+`validateState()` remains for callers holding their own expected value.
+
+The default routes do all of this: `GET /auth/{provider}` (optional
+`?redirect_to=/path`, same-origin only) and `GET|POST /auth/{provider}/callback`
+(POST skips CSRF, since the bound state is the defence). Read
+`defaults/app/Actions/Auth/SocialRedirectAction.ts` and
+`SocialCallbackAction.ts` before writing a custom callback.
 
 SocialUser includes emailVerified. Respect the provider's verification signal
 and the configured account-linking policy, using auth's resolveSocialSignIn
-instead of attaching any equal email address to an existing account. Provider
-errors and ConfigException/InvalidStateException are different from successful
-profile retrieval. Never log raw credential fields.
+instead of attaching any equal email address to an existing account; it also
+refuses to link onto a local account that never verified its address
+(`'unverified-local-email'`). Provider errors and
+ConfigException/InvalidStateException are different from successful profile
+retrieval. Never log raw credential fields.
 
 ## Session handoff
 
-socialHandoffRedirect(pack, { redirectTo?, allowedHosts? }) emits a no-store
-redirect with the native encoded session handoff. Browser useAuth's
-completeSocialLogin consumes it and removes the fragment. isSafeHandoffTarget
-checks permitted redirect shape; choose a server-owned landing path. The helper
-also supplies a failed-sign-in redirect. These are separate from provider token
-exchange and the auth cookie/session issuance policy.
+The default callback mints no session and puts no token in the URL. It calls
+`createSessionHandoff(userId, { bindTo: 'cookie' })` (`@stacksjs/auth`) and
+returns `socialHandoffCodeRedirect(code, { redirectTo?, allowedHosts? })`, a
+no-store 302 to `redirectTo#stx_handoff=<code>` plus the binding cookie.
+Browser `useAuth().completeSocialLogin()` strips the fragment and POSTs the code
+to `POST /auth/handoff`, which redeems it once (60 seconds, this browser only)
+and answers with the token pack and auth cookie. Native apps bind with
+`{ challenge }` and redeem with `{ code, verifier }`.
+
+socialHandoffRedirect(pack, ...) still emits the older fragment carrying the
+bearer and refresh tokens (`stx_auth`); avoid it for new flows, since browser
+history keeps the fragment. isSafeHandoffTarget checks permitted redirect
+shape; choose a server-owned landing path. socialHandoffFailureRedirect supplies
+the failed-sign-in redirect (`?social_error=`).
 
 ## Named publishing identities
 
@@ -83,8 +118,9 @@ conformance or successful publication for arbitrary accounts.
 
 ## Source and evidence
 
-`storage/framework/core/socials/src/index.ts`, registry.ts, abstract.ts,
+`storage/framework/core/socials/src/index.ts`, registry.ts, abstract.ts, flows.ts,
 handoff.ts, identities.ts, publish.ts, authorize.ts, meta-graph.ts and drivers/.
-Tests: registry.test.ts, apple.test.ts, session-handoff.test.ts,
+Tests: registry.test.ts, apple.test.ts, session-handoff.test.ts, oauth-flows.test.ts,
+provider-flow-state.test.ts, auth/tests/social-callback-flow.test.ts,
 identities.test.ts, publish.test.ts, authorize.test.ts,
 credentials-stay-out-of-output.test.ts and meta-graph.test.ts.

package/ai/skills/stacks-storage/SKILL.md

@@ -24,6 +24,7 @@ File system abstraction with a Laravel-style Storage facade, local/S3/Azure adap
 - Bun adapter: `storage/framework/core/storage/src/adapters/bun.ts`
 - File utilities: `storage/framework/core/storage/src/files.ts`
 - Bounded local text reads: `storage/framework/core/storage/src/bounded-text-file.ts`
+- Completed local artifacts: `storage/framework/core/storage/src/completed-artifact-directory.ts`
 - Folder utilities: `storage/framework/core/storage/src/folders.ts`
 - Copy: `storage/framework/core/storage/src/copy.ts`
 - Move: `storage/framework/core/storage/src/move.ts`
@@ -71,6 +72,19 @@ import * as storage from '@stacksjs/storage'
 
 ## Storage Facade (StorageManager)
 
+### Completed local artifacts
+
+Use `writeCompletedArtifact` from `@stacksjs/storage/completed-artifact-directory`
+for a bounded, new local output directory containing data files and a JSON
+completion manifest. Pass `(directory, [{ path, contents }], manifestJson)`;
+optional `{ directories: ['images'] }` creates empty folders. It snapshots bytes,
+validates paths/collisions/budgets, writes private exclusive files, syncs files
+and directories, then hard-links the synced manifest to its completion name.
+Read the package README for exact limits and failure behavior. Callers own
+parent-directory authorization and domain validation. This is a local hard-link
+and directory-fsync protocol, not a cloud-adapter transaction or tested hardware
+power-loss guarantee.
+
 ### Recoverable temporary workspaces
 
 Use `TemporaryWorkspaceJournal` for workers that recover temporary directories after a process interruption. Keep its private journal outside job-controlled checkouts and separate it by stable worker and controller identity. `create(key)` returns a frozen live ownership handle; stop its resources, then call `complete(handle)` for normal disposal. A restarted instance cannot forge this capability from a listed record.

package/ai/skills/stacks-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-testing
-description: Use when writing or running tests in Stacks - test setup, database test utilities (setup, refresh, truncate), DynamoDB testing, feature test patterns, the test CLI commands, test configuration in bunfig.toml, or test environment setup. Covers @stacksjs/testing and tests/.
+description: Use when writing or running tests in Stacks - test setup, database test utilities (setup, refresh, truncate), disposable SQLite/Postgres databases, running a test in an isolated child process, headless Chrome browser tests and page audits, DynamoDB testing, feature test patterns, the test CLI commands, test configuration in bunfig.toml, or test environment setup. Covers @stacksjs/testing and tests/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -168,9 +168,95 @@ expect(result.exitCode).toBe(0)
 ```
 
 Retained implementation evidence lives under `core/testing/tests/`:
-`http-client`, `acting-as`, `database-assertions`, `events`, `mail`, `time`
-and `console` test files. Fixture mechanics live in `core/testing/src/`;
-`package.json` declares the root and database/DynamoDB export boundaries.
+`http-client`, `acting-as`, `database-assertions`, `events`, `mail`, `time`,
+`console`, `isolated`, `disposable-database` and `browser` test files. Fixture mechanics live in `core/testing/src/`;
+`package.json` declares the root and database/DynamoDB/browser export boundaries.
+
+## Isolated processes and disposable databases
+
+`bun test` runs every file in one process, and `mock.module()` replaces a
+module for the rest of that run, so a mock in one file leaks into the next. A
+framework booted against one database also stays booted. When a test needs a
+clean process, run it in a child (`src/isolated.ts`); when it needs real rows,
+give it a database nobody else uses (`src/disposable-database.ts`). Both are on
+the root, with no framework import.
+
+```ts
+import { assertIsolatedOk, disposablePostgresUrl, runIsolated, test, withDisposableDatabase } from '@stacksjs/testing'
+
+for (const dialect of ['sqlite', 'postgres'] as const) {
+  test.skipIf(dialect === 'postgres' && !disposablePostgresUrl())(`${dialect} checkout flow`, async () => {
+    await withDisposableDatabase(dialect, async (database) => {
+      const result = await runIsolated('tests/fixtures/checkout-flow.ts', {
+        env: { APP_ENV: 'test', ...database.env },
+        timeoutMs: 45_000,
+        envFile: false,      // --no-env-file
+        preload: [],         // replace bunfig preloads (none)
+      })
+      assertIsolatedOk(result, 'checkout flow OK') // throws with stdout + stderr otherwise
+    })
+  }, 50_000)
+}
+```
+
+- `runIsolated(file, { env, timeoutMs = 60_000, args, cwd, mode, preload, envFile, inheritEnv, stdin })`
+  resolves `{ code, signal, stdout, stderr, timedOut, durationMs, command }`. `mode: 'auto'` runs
+  `*.test.*` / `*.spec.*` with `bun test`, anything else as a script; `env` values of `undefined`
+  remove a variable. The watchdog sends SIGTERM at the timeout and SIGKILL 2 s later.
+- `withDisposableDatabase(dialect, fn, { url?, prefix? })`: SQLite is a file in a fresh temp
+  directory; Postgres is `CREATE DATABASE` on `url` or `STACKS_TEST_POSTGRES_URL`, dropped with
+  `DROP DATABASE ... WITH (FORCE)` after `fn`, even when it throws (the test's error wins over a
+  cleanup error). Only `localhost`, `127.0.0.1` and `::1` are accepted. `database.env` holds the
+  `DB_*` variables (`DB_CONNECTION`, `DB_DATABASE_PATH` or `DB_HOST`/`DB_PORT`/`DB_DATABASE`/
+  `DB_USERNAME`/`DB_PASSWORD`); `database.directory` is removed with it.
+- `createDisposableDatabase` returns the same with `drop()` and `Symbol.asyncDispose`
+  (`await using`), for setups that span hooks.
+
+## Browser tests: `@stacksjs/testing/browser`
+
+Headless Chrome over the DevTools Protocol with no browser package: the installed
+Chrome and Bun's WebSocket (`src/browser.ts`). A subpath so tests that never drive
+a browser never load it.
+
+```ts
+import { auditPage, launch, navigate, pageAuditClean, settle } from '@stacksjs/testing/browser'
+
+const { cdp, close } = await launch({ viewport: { width: 390, height: 844, mobile: true } })
+try {
+  const off = cdp.on('Network.requestWillBeSent', params => requests.push(params.request.url))
+  await navigate(cdp, 'http://localhost:3000/dashboard')   // settles: loaded + network quiet 1 s
+  expect(await cdp.evaluate('document.title')).toBe('Dashboard')
+  expect(cdp.errors).toEqual([])                          // exceptions, console.error, failed requests, dialogs
+  off()
+}
+finally { await close() }
+
+const report = await auditPage('http://localhost:3000/pricing') // launches its own Chrome, or pass { cdp }
+expect(pageAuditClean(report)).toBe(true) // no duplicate /api/ requests, failed same-origin requests or errors
+```
+
+- `Cdp`: `send`, `evaluate`, `on(method, fn)` (any number of listeners per method; returns an
+  unsubscribe), `off`, `once(method, match?, timeoutMs?)`, `errors`, `inFlight` (event streams
+  leave it when their response starts, so a page with live updates can still settle), `closed`
+  (every pending command fails at once when Chrome goes away).
+- `launch(options)` enables Page/Runtime/Network/Log, sets a 1440x1000 viewport, answers stx's
+  live-reload stream (`*/_stx/hmr*`) with a day-long retry so a save mid-run cannot reload the
+  page, accepts JavaScript dialogs and records them in `errors`, removes "HeadlessChrome" from the
+  user agent, and passes `--use-mock-keychain`. `profile` keeps one profile across relaunches.
+- `settle(cdp, { quietMs, timeoutMs })` resolves false (not throws) when a page never goes quiet.
+- `auditPage(url, { cdp?, launch?, viewport?, isApiRequest?, beforeNavigate?, quietMs, timeoutMs })`
+  returns `{ apiRequests, duplicates, failed, errors, settled, durationMs }` and never throws for a
+  page problem. `beforeNavigate` is where to seed a token (`Page.addScriptToEvaluateOnNewDocument`).
+  `formatPageAudit(report)` prints one line.
+- **macOS: the installed Chrome quits about 30 s in.** GoogleUpdater SIGTERMs every process with
+  Chrome's bundle id while an update is pending; to a test that looks like a hung page. When
+  `CHROME_PATH` is not set, `launch()` runs `prepareMacChrome()`: a `cp -cR` clone in the temp
+  directory with the `KS*` updater keys deleted from `Info.plist`, its own `CFBundleIdentifier`,
+  and `codesign --force --deep --sign -`, reused per Chrome version. `--use-mock-keychain` is what
+  keeps that clone from hanging on an invisible "Chrome Safe Storage" Keychain prompt at its first
+  http page. Measured: the installed Chrome closed at 32 s, the clone kept navigating past 60 s.
+- The package's own real-Chrome tests (`core/testing/tests/browser.test.ts`) run wherever a Chrome
+  is found, except in CI unless `STACKS_BROWSER_TESTS=1`; `STACKS_BROWSER_TESTS=0` skips them locally.
 
 ## CLI Commands
 
@@ -182,8 +268,13 @@ bun run test                  # via npm script
 bun run test:ui               # UI tests
 bun run test:coverage         # with coverage
 bun run test:types            # type tests
+buddy test:page-audit --url /,/dashboard --base http://localhost:3000  # duplicate API requests, failures, console errors
+buddy test:page-audit --url http://localhost:3000/pricing --mobile --json
 ```
 
+`test:page-audit` exits 1 when any page has duplicates, failed same-origin requests or errors, or
+never settles.
+
 ## Configuration (bunfig.toml)
 
 ```toml

package/app/Actions/Auth/SessionHandoffAction.ts

@@ -0,0 +1,65 @@
+import { Action } from '@stacksjs/actions/runtime'
+import { Auth, authCookieForBrowserSession, clearSessionHandoffCookie, readSessionHandoffCookie, redeemSessionHandoff, resolveBrowserSessionPolicy } from '@stacksjs/auth'
+
+/**
+ * `POST /auth/handoff` — trade a one-use sign-in code for a session.
+ *
+ * SocialCallbackAction ends by redirecting with a 60-second code in the URL
+ * fragment and a matching HttpOnly cookie. `useAuth().completeSocialLogin()`
+ * posts the code here. The code redeems once, and only with the cookie that
+ * was set beside it (or, for a native app whose sign-in sheet has its own
+ * cookie jar, the `verifier` behind the challenge it started with). A code
+ * copied out of history, a log or another browser answers 401.
+ *
+ * The answer is LoginAction's: an OAuth2-shaped token pack plus the auth
+ * cookie for server-rendered pages.
+ *
+ * CSRF is skipped on the route because the binding cookie is the proof a
+ * CSRF token would add: a cross-site page can neither read the code nor make
+ * the browser present someone else's binding cookie.
+ */
+export default new Action({
+  name: 'SessionHandoffAction',
+  description: 'Redeems a one-use sign-in handoff code for a session.',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const code = String(request.get('code') ?? '')
+    const verifier = request.get('verifier')
+    const secret = typeof verifier === 'string' && verifier
+      ? verifier
+      : readSessionHandoffCookie(request.headers.get('cookie'), code)
+
+    const headers = new Headers({ 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' })
+    if (/^[a-f0-9]{64}$/.test(code))
+      headers.append('Set-Cookie', await clearSessionHandoffCookie(code))
+
+    const handoff = await redeemSessionHandoff(code, secret)
+    if (!handoff)
+      return Response.json({ error: 'This sign-in expired or was started in another browser. Please try again.' }, { status: 401, headers })
+
+    // The baseline (not remembered) browser session, as the other sign-in paths issue.
+    const policy = resolveBrowserSessionPolicy(false)
+    const result = await Auth.loginUsingId(handoff.userId, {
+      expiresInMinutes: policy.expiresInMinutes,
+      withRefreshToken: policy.withRefreshToken,
+    })
+    if (!result?.token)
+      return Response.json({ error: 'Sign-in could not be completed. Please try again.' }, { status: 401, headers })
+
+    headers.append('Set-Cookie', authCookieForBrowserSession(result.token, result.expiresIn))
+    const user = result.user
+    return Response.json({
+      access_token: result.token,
+      refresh_token: result.refreshToken,
+      token_type: 'Bearer',
+      expires_in: result.expiresIn,
+      token: result.token,
+      user: {
+        id: user?.id,
+        email: user?.email,
+        name: user?.name,
+      },
+    }, { headers })
+  },
+})