@volter/twin-stripe 2.0.0 → 2.0.2

package/README.md

@@ -54,6 +54,32 @@ hand-made in-process mock).
   per World (`evt_twin_<n>`) and is the delivered webhook's id and the stored event's alike (`stripe.events.ids`).
   `world-stripe emit` re-fires a connected account's object with its `account`; it does not yet route it to Connect
   endpoints only (the kernel's emit seam has no endpoint scope).
+- **Connect OAuth (Standard accounts)** (`src/screens/connect-oauth.tsx`, `src/screens/connect-settings.tsx`;
+  docs.stripe.com/connect/oauth-reference). The platform's **client_id is `ca_twin_self`** in every World (a test
+  client_id; the platform account is `acct_twin_self`), shown on the Dashboard's Connect OAuth settings page,
+  `dashboard.stripe.com/settings/connect/onboarding-options/oauth` (also `/settings/connect` and the `/test/…` link),
+  in `<code data-testid="connect-client-id">`. OAuth starts **off**: a runner POSTs that page as a browser does,
+  `oauth_enabled=on&redirect_uris=<one per line>` (303 to `?saved=1`), and the saved URIs are listed in
+  `data-testid="connect-redirect-uri"` items. `GET connect.stripe.com/oauth/authorize` checks client_id (unknown:
+  `invalid_client`), OAuth on, `redirect_uri` (must exactly match a registered one; absent: the first; http and
+  localhost allowed, as Stripe's test client_id allows), `response_type=code` and `scope` (`read_write` | `read_only`,
+  default `read_only`), each refusal a 400 JSON `{error, error_description, state}` as the reference says (no
+  redirect). The page offers the test-mode **Skip this form**, which creates a new Standard account (controller type
+  `account`, prefilled from valid `stripe_user[...]` values, charges and payouts enabled) and redirects with
+  `scope`, `code` and `state`, and **Deny access**, which redirects with
+  `error=access_denied&error_description=The%20user%20denied%20your%20request&state=…`. `POST
+  connect.stripe.com/oauth/token` (the secret key as Bearer, Basic or `client_secret`) exchanges a code once, within 5
+  minutes, into `{access_token, livemode, refresh_token, scope, stripe_publishable_key, stripe_user_id, token_type}`;
+  a reused code is `invalid_grant` and revokes the connection; `refresh_token` grants an equal or lesser scope.
+  `POST connect.stripe.com/oauth/deauthorize` answers `{stripe_user_id}`, after which the Stripe-Account header (and
+  `/v1/accounts/{id}`) for that account is refused 403 `account_invalid`. `account.application.authorized` /
+  `.deauthorized` reach Connect endpoints with the account; once revoked, `GET /v1/accounts` no longer lists it and its own events (payouts, balance) stop reaching the platform. The token answer's
+  deprecated `access_token` and `stripe_publishable_key` act as the connected account (as the Stripe-Account header
+  does, as Bearer or Basic; `GET /v1/account` then answers it), a token replaced by a refresh or revoked is a 401 invalid API key, and it is never the platform's key at `/oauth/token` or `/oauth/deauthorize`. The
+  application's own setting of its client_id (Cal.com's `client_id` app key, `STRIPE_CLIENT_ID`) is the runner's to
+  set to `ca_twin_self`; the World does not provision it. Where the docs stop, the twin decides (the file header lists
+  each): connecting an existing Stripe account, the full account application form, and holding a `read_only`
+  connection to reads are not modelled (todos in `stripe-capabilities.ts`).
 - **Signing secrets in a World**: Stripe mints an endpoint's `secret`; in a World the app's env is the World's, so an
   endpoint is given the World's value, which the app already verifies with: `STRIPE_WEBHOOK_SECRET` (or
   `STRIPE_WEBHOOK_SIGNING_SECRET`, `STRIPE_ENDPOINT_SECRET`, `STRIPE_WEBHOOK_SECRET_KEY`,
@@ -87,6 +113,12 @@ Point the real `stripe` SDK at it with `{ host, port, protocol: 'http' }`.
    each payout that arrived, a connected account's with its `account` to its Connect endpoints
    (`stripe.events.time_drain`). A read sees time's moves without it; a runner's drainer calls it so the events
    arrive, as the qstash and vercel twins' drain doors do.
+   Test mode keeps live timing except where Stripe documents otherwise: a card charge's funds are pending two days,
+   except the cards that bypass the pending balance (4000000000000077, 4000003720000278, `pm_card_bypassPending*`,
+   `tok_bypassPending*`, and a PaymentMethod saved from one) and US bank account debits ("Test transactions settle
+   instantly"), whose funds, and a `source_transaction` transfer's from them, are available at once; every credit
+   available at once is sent as `balance.available` at the next drain; a test payout is paid at its `arrival_date`
+   (`stripe.balance.test_mode_bypass_pending`; sources in `src/semantics/ledger.ts`).
 
 (See Getting Started → "Twin interaction surfaces".)
 
@@ -111,7 +143,7 @@ destination; a new account starts un-onboarded with charges/payouts disabled + a
 hash; a transfer's `source_transaction` waives the balance check only while its charge is unsettled,
 takes the charge's `transfer_group` or writes `group_<payment intent>` onto both, and counts reversals
 back as room; connected-account balances, payouts (manual and automatic) and payout reversal, top-ups,
-account sessions, persons, external accounts, application fees and hosted onboarding), plus **ephemeral_keys**, **identity verification_sessions**, **file_links**
+account sessions, persons, external accounts, application fees, hosted onboarding and Connect OAuth for Standard accounts), plus **ephemeral_keys**, **identity verification_sessions**, **file_links**
 (synthesized) and **coupons**/**promotion_codes** (retrieve/list, seed-only). Cursor pagination
 (`limit`/`starting_after`/`ending_before` + `has_more`); per-resource list filters; `expand[]`
 on the modeled paths; vendor-faithful **test-card declines** (`4242…` succeeds; documented

package/dist/src/index.js

@@ -50,7 +50,7 @@ export const pack = {
     // one live API host — declared HERE, not in the central maps (descriptor-first exemplar (adding-a-twin.md §3);
     // the pack-facts artifact carries them to covers/inspect-project and inject.cjs).
     // NEXT_PRIVATE_STRIPE_* joined the stem list in the adoption-facts sweep 2026-08-31.
-    // `stripeconnect` is deliberately NOT claimed: the Connect area is unmodeled, so a repo
+    // `stripeconnect` is deliberately NOT claimed: no Connect-only credential stem is modeled, so a repo
     // holding only that credential is build-surface, not coverage this twin can honor.
     adoption: {
         // Stripe's official Python bindings.
@@ -58,15 +58,17 @@ export const pack = {
         sdks: ['stripe'], envStems: ['STRIPE', 'NEXTPRIVATESTRIPE'],
     },
     // The API and the hosted flows (src/screens): checkout.stripe.com's payment page, billing.stripe.com's customer
-    // portal, connect.stripe.com's onboarding, verify.stripe.com's identity check and the bank-linking flow Stripe.js
+    // portal, connect.stripe.com's onboarding and its OAuth endpoints (/oauth/authorize, /oauth/token, /oauth/deauthorize:
+    // src/screens/connect-oauth.tsx), verify.stripe.com's identity check and the bank-linking flow Stripe.js
     // opens: an application that sends a person to one of their urls lands in the World. dashboard.stripe.com serves the
-    // Dashboard's Public details page (src/screens/public-details.tsx), where the operator sets the name customers see;
+    // Dashboard's Public details page (src/screens/public-details.tsx), where the operator sets the name customers see,
+    // and its Connect OAuth settings (src/screens/connect-settings.tsx: the client_id, OAuth on, the redirect URIs);
     // claiming the host makes every other dashboard.stripe.com path an unclaimed path on a twinned host, refused in a
     // World rather than sent to the real Dashboard. js.stripe.com also serves
     // Stripe.js itself, the client library an application's page loads (stripe-js.ts): /v3/, /v3/stripe.js and /<release train>/stripe.js.
     hosts: [
         { host: 'api.stripe.com' }, { host: 'checkout.stripe.com', pathPattern: '^/c/pay/' }, { host: 'billing.stripe.com', pathPattern: '^/p/session/' },
-        { host: 'connect.stripe.com', pathPattern: '^/setup/' }, { host: 'dashboard.stripe.com', pathPattern: '^/settings/public/?$' }, { host: 'verify.stripe.com', pathPattern: '^/start/' }, { host: 'js.stripe.com', pathPattern: '^/v3/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
+        { host: 'connect.stripe.com', pathPattern: '^/setup/|^/oauth/(authorize|token|deauthorize)/?$' }, { host: 'dashboard.stripe.com', pathPattern: '^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$' }, { host: 'verify.stripe.com', pathPattern: '^/start/' }, { host: 'js.stripe.com', pathPattern: '^/v3/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
     ],
     // DELIVER support: signed event synthesis from twin state (`world-stripe emit`).
     emitter: stripeEmitter,

package/dist/src/manifest.js

@@ -535,6 +535,11 @@ export const manifest = {
             demand: '3 of 85 applications onboard connected accounts with Account Links', controls: ['Agree and submit', '← Return to platform'],
             source: 'https://docs.stripe.com/connect/hosted-onboarding',
         },
+        {
+            id: 'connect-oauth', kind: 'flow', host: 'connect.stripe.com', path: '/oauth/authorize', status: 'done',
+            demand: "Cal.com's Stripe app connects each organizer's Standard account through Connect OAuth", controls: ['Skip this form', 'Deny access'],
+            source: 'https://docs.stripe.com/connect/oauth-reference',
+        },
         {
             id: 'identity-verification', kind: 'flow', host: 'verify.stripe.com', path: '/start/{verification_session}', status: 'done',
             demand: 'a verification report is written only when a person completes this page', controls: ['Verify', 'Fail verification'],
@@ -546,9 +551,9 @@ export const manifest = {
             source: 'https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts',
         },
         {
-            id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/test/{section}; /settings/public', status: 'done',
-            demand: 'testers and agents inspect payments, customers and subscriptions; an operator sets the business name Checkout shows (Public details)',
-            controls: ['Business name', 'Save'], source: 'https://docs.stripe.com/dashboard/basics',
+            id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/test/{section}; /settings/public; /settings/connect/onboarding-options/oauth', status: 'done',
+            demand: 'testers and agents inspect payments, customers and subscriptions; an operator sets the business name Checkout shows (Public details) and a Connect platform its OAuth client_id and redirect URIs',
+            controls: ['Business name', 'Save', 'Enable OAuth for Standard accounts', 'Redirect URIs'], source: 'https://docs.stripe.com/dashboard/basics',
         },
     ],
     resources: {

package/dist/src/screens/checkout.js

@@ -104,6 +104,13 @@ function afterTrial(session) {
     const coupon = session._coupon;
     return subtotal - (coupon && coupon.duration !== 'once' ? applyCouponDiscount(subtotal, coupon) : 0);
 }
+const EMAIL = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+/** The email of the session's customer when it has a valid one: "If the Customer already has a valid email set, the email
+ *  will be prefilled and not editable in Checkout" (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-customer). */
+function customerEmailOf(session) {
+    const email = session._customer?.email;
+    return typeof email === 'string' && EMAIL.test(email) ? email : undefined;
+}
 function page(session, id, now, values = {}, error) {
     const lines = ((session.line_items?.data) ?? []).map((item) => ({
         name: String(item.description ?? 'Item'),
@@ -115,9 +122,12 @@ function page(session, id, now, values = {}, error) {
     const trial = trialOf(session, now);
     const submit = mode === 'setup' ? 'Save card' : mode === 'subscription' ? (trial ? 'Start trial' : 'Subscribe') : 'Pay';
     const trialText = trial ? trialSummary(session, trial) : undefined;
-    const contact = typeof session.customer_email === 'string'
-        ? [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', value: session.customer_email }]
-        : [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', placeholder: 'email@example.com', value: values.email ?? '' }];
+    const onFile = customerEmailOf(session);
+    const contact = onFile
+        ? [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', value: onFile, readOnly: true }]
+        : typeof session.customer_email === 'string'
+            ? [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', value: session.customer_email }]
+            : [{ id: 'email', label: 'Email', type: 'email', autoComplete: 'email', placeholder: 'email@example.com', value: values.email ?? '' }];
     const card = [
         { id: 'cardNumber', label: 'Card number', autoComplete: 'cc-number', placeholder: '1234 1234 1234 1234', value: values.cardNumber ?? '' },
         { id: 'cardExpiry', label: 'Expiration', autoComplete: 'cc-exp', placeholder: 'MM / YY', value: values.cardExpiry ?? '', format: 'card-expiry' },
@@ -176,9 +186,10 @@ export function cardAnswer(v, nowSeconds, chargesNow) {
     return undefined;
 }
 async function pay(ctx, id, session, v) {
-    const email = typeof session.customer_email === 'string' ? session.customer_email : (v.email ?? '').trim();
+    const onFile = customerEmailOf(session);
+    const email = onFile ?? (typeof session.customer_email === 'string' ? session.customer_email : (v.email ?? '').trim());
     if (session.mode !== 'setup' || !session.customer) {
-        if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email))
+        if (!EMAIL.test(email))
             return page(session, id, Number(ctx.now()), v, 'Your email address is incomplete.');
     }
     // a trial charges nothing now unless a one-time price is on the first invoice
@@ -194,6 +205,9 @@ async function pay(ctx, id, session, v) {
         const customer = await created(ctx, 'customer', { id: cid, email, ...(v.billingName ? { name: v.billingName } : {}) }, { livemode: false, ...newCustomer(cid) });
         existing = { ...session, customer: customer.id };
     }
+    // "If the Customer does not have a valid email, Checkout will set the email entered during the session on the Customer" (the same page)
+    if (typeof session.customer === 'string' && !onFile && EMAIL.test(email))
+        await ctx.write('customer', session.customer, { email }, 'customer.update');
     const details = {
         customer_details: { email, name: v.billingName || null, address: { country: v.billingCountry || null, postal_code: v.billingPostalCode || null, city: null, line1: null, line2: null, state: null }, phone: null, tax_exempt: 'none', tax_ids: [] },
         ...(existing.customer !== session.customer ? { customer: existing.customer } : {}),
@@ -235,7 +249,7 @@ export function stripeCheckoutFlow(scope) {
             return gone();
         const stored = ctx.row(CS, id) ?? {};
         const coupon = stored._discount?.coupon;
-        const full = { ...session, _subscription_data: stored._subscription_data, _price_data: stored._price_data, _merchant: merchantOf(ctx, stored), _coupon: typeof coupon === 'string' ? ctx.get('coupon', coupon) : undefined };
+        const full = { ...session, _subscription_data: stored._subscription_data, _price_data: stored._price_data, _merchant: merchantOf(ctx, stored), _coupon: typeof coupon === 'string' ? ctx.get('coupon', coupon) : undefined, _customer: typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined };
         return request.method === 'GET' ? page(full, id, Number(ctx.now())) : pay(ctx, id, full, values);
     };
 }

package/dist/src/screens/connect-oauth.d.ts

@@ -0,0 +1,27 @@
+import { type SemanticsContext } from '@volter/world-core';
+/** A code "expires in 5 minutes". */
+export declare const CODE_TTL_SECONDS = 300;
+/** One connection per connected account (the twin's one platform): its scope, tokens, and whether it was revoked. */
+export declare const CONNECTIONS = "_oauth_connection";
+type Scoped = {
+    root?: string;
+    clock?: () => string;
+};
+/** Whether a connected account's OAuth connection to the platform was revoked (deauthorized, or its code reused). */
+export declare function connectionRevoked(ctx: SemanticsContext, account: string): boolean;
+/** The connected account an OAuth key acts as — the connection's current access_token (sk_test_oauth_…) or its
+ *  stripe_publishable_key (pk_test_oauth_…) — with the scope it was issued; undefined for any other key, and null for an
+ *  OAuth-shaped key no live connection holds (revoked, replaced by a refresh, or never issued). */
+export declare function oauthKeyAccount(ctx: SemanticsContext, key: string): {
+    account: string;
+    scope: string;
+} | null | undefined;
+/** The prefill the request carries, invalid values silently dropped (docs.stripe.com/connect/oauth-reference). Only
+ *  what the new account's object shows the platform, or the page shows the person, is read: the person's birth date and
+ *  the business address are the account application's, which the twin does not model (the test-mode skip). */
+export declare function prefill(q: URLSearchParams): Record<string, string>;
+/** A key shown the way Stripe's errors show one: its prefix and its last four. */
+export declare const redactKey: (key: string) => string;
+/** connect.stripe.com's OAuth endpoints, or undefined for any other request. */
+export declare function stripeConnectOAuthFlow(scope: Scoped): (request: Request) => Promise<Response | undefined>;
+export {};

package/dist/src/screens/connect-oauth.js

@@ -0,0 +1,414 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// STRIPE CONNECT OAUTH (Standard accounts) — a hosted flow (docs/contributing/architecture.md, "Screens") and the two
+// connect.stripe.com endpoints behind it, as docs.stripe.com/connect/oauth-reference and
+// docs.stripe.com/connect/oauth-standard-accounts describe them. A platform sends a person to
+// GET connect.stripe.com/oauth/authorize with its client_id; the person connects (in test mode Stripe lets them "Force-skip
+// the account form", docs.stripe.com/connect/testing#using-oauth) or denies; Stripe sends them back to the redirect_uri
+// with a `code`, the `scope` granted and the `state` (or `error=access_denied`); the platform's server turns the code into
+// the connection with POST connect.stripe.com/oauth/token, authenticated by its secret key, and learns the account id
+// (`stripe_user_id`) it then acts as with the Stripe-Account header. POST connect.stripe.com/oauth/deauthorize revokes the
+// connection. The page is @volter/world-ui's consent piece under Stripe's skin; nothing of Stripe's page is copied.
+//
+// What the documentation says and the twin keeps:
+// - authorize: `client_id` is the platform's (its Connect OAuth settings, ./connect-settings.tsx, where OAuth is enabled
+//   and the redirect URIs are registered); `response_type` "The only option at the moment is code"; `redirect_uri`, "If
+//   provided, this must exactly match one of the ... redirect_uri values in your application settings" and "Defaults to
+//   the redirect_uri in your application settings" ("the first URI configured"); `scope` read_write or read_only,
+//   "Defaults to read_only"; `state` passed back. `stripe_user[...]` prefills the new account, and "Any parameters with
+//   invalid values are silently ignored". Errors: "the user's browser won't be redirected except in the case of
+//   access_denied. Instead, errors will be returned in a JSON dictionary" of error, error_description and state, with
+//   the codes invalid_scope, invalid_redirect_uri, invalid_request (Missing response_type) and unsupported_response_type.
+//   Denied: `error=access_denied&error_description=The%20user%20denied%20your%20request`. Success: code, scope, state.
+// - token: the code "can only be used once and expires in 5 minutes"; "Consuming an authorization code more than once
+//   revokes the account connection"; grant_type authorization_code or refresh_token; a refresh `scope` of "equal or lesser
+//   scope" and "Any existing access token with the same scope and mode ... is revoked"; the response's scope,
+//   stripe_user_id, livemode, token_type "bearer", access_token, stripe_publishable_key and refresh_token; errors
+//   invalid_request, invalid_grant ("Authorization code does not exist: {AUTHORIZATION_CODE}", verbatim from the guide),
+//   unsupported_grant_type and invalid_scope as `{ error, error_description }`.
+// - deauthorize: client_id and stripe_user_id, answered `{ stripe_user_id }`; errors invalid_request and invalid_client
+//   ("stripe_user_id doesn't exist or isn't connected to your application"); afterwards "the account can't be accessed by
+//   your platform ... through the API" (stripe-server.ts refuses the Stripe-Account header for it, account_invalid).
+// - events: account.application.authorized when the person connects and account.application.deauthorized when the
+//   connection is revoked, each the connected account's (top-level `account`, Connect endpoints), carrying the
+//   `application` object ({ id: the client_id, object: 'application', name }).
+//
+// Where the documentation stops and the twin decides:
+// - the twin is a test-mode Stripe: its client_id is a test one (./connect-settings.tsx PLATFORM_CLIENT_ID), redirect
+//   URIs may be http and localhost ("Your test client_id allows you to ... Set your redirect_uri to a non-HTTPS URL /
+//   to localhost"), a code, token and connection are livemode false, and a live secret key (sk_live_) is refused as the
+//   documented mode mismatch (invalid_grant at token, invalid_client at deauthorize).
+// - the only way through the page is the test-mode skip: it creates a NEW Standard account from the prefill and connects
+//   it; logging in to connect an existing Stripe account is not modelled. A skipped test account can take payments at
+//   once (charges and payouts enabled, card_payments and transfers active, nothing due), and controls itself (controller
+//   type `account`), since the platform did not create it.
+// - an unknown client_id answers invalid_client "No application matches the supplied client identifier", and a
+//   platform that has not enabled OAuth invalid_client naming its settings page; a missing client_id is invalid_request.
+//   The JSON errors are HTTP 400; the order of the checks is client_id, OAuth enabled, redirect_uri, response_type,
+//   scope. With no redirect URI registered and none given, invalid_redirect_uri. read_only is accepted from any platform
+//   (the docs limit it to extensions; the twin does not tell a platform from an extension).
+// - the secret key may come as Bearer, as Basic's user, or as the `client_secret` parameter (the reference's curl uses
+//   `-u`, stripe-node a Bearer header); without one the answer is 401 invalid_request, and a key that is not a secret
+//   key (sk_…/rk_…) 401 invalid_request too. The token and deauthorize wording other than the one quoted above is the
+//   twin's. An expired code is invalid_grant "Authorization code expired: {code}"; a reused one invalid_grant "This
+//   authorization code has already been used. All tokens issued with this code have been revoked." and revokes.
+// - tokens are deterministic, not secret: access_token `sk_test_oauth_{account}_{n}`, refresh_token `rt_twin_{n}`,
+//   stripe_publishable_key `pk_test_oauth_{account}`; a refresh answers the same refresh_token (`rt_twin_{n}` of the code
+//   `ac_twin_{n}` that made the connection). The access_token and publishable key are deprecated by Stripe (use the
+//   Stripe-Account header) and act as the account (stripe-server.ts actingAsOAuthKey); a read_only one is not held to
+//   reads (manifest todo `stripe.connect.oauth_scope_enforcement`).
+// - concurrency: a code's number is taken with its write in one move; a code redeemed twice at once lets one exchange
+//   win, and whichever of the two finishes last revokes the connection, so a double exchange always ends revoked.
+import { semanticsContext } from '@volter/world-core';
+import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "../manifest.js";
+import { created } from "../semantics/shared.js";
+import { OAUTH_CONNECTIONS, publicBusinessName } from "../stripe-shared.js";
+import { accountSettings, afterStripeWrite, PLATFORM_ACCOUNT_ID } from "../stripe-twin.js";
+import { formOf, seeOther, STRIPE_CONSENT_SKIN } from "./consent-skin.js";
+import { connectOAuthSettings, PLATFORM_CLIENT_ID, SETTINGS_URL } from "./connect-settings.js";
+const OPERATION = surface.operations.find((o) => o.id === 'PostAccountsAccount');
+/** A code "expires in 5 minutes". */
+export const CODE_TTL_SECONDS = 300;
+const CODES = '_oauth_code';
+/** One connection per connected account (the twin's one platform): its scope, tokens, and whether it was revoked. */
+export const CONNECTIONS = OAUTH_CONNECTIONS;
+const SCOPES = ['read_write', 'read_only'];
+const json = (body, status = 200) => Response.json(body, { status, headers: { 'request-id': 'req_twin', 'cache-control': 'no-store' } });
+const oauthError = (error, description, status = 400, extra = {}) => json({ error, error_description: description, ...extra }, status);
+/** Whether a connected account's OAuth connection to the platform was revoked (deauthorized, or its code reused). */
+export function connectionRevoked(ctx, account) {
+    return ctx.rowsRaw(CONNECTIONS).some((c) => c.id === account && c.revoked === true);
+}
+/** The connected account an OAuth key acts as — the connection's current access_token (sk_test_oauth_…) or its
+ *  stripe_publishable_key (pk_test_oauth_…) — with the scope it was issued; undefined for any other key, and null for an
+ *  OAuth-shaped key no live connection holds (revoked, replaced by a refresh, or never issued). */
+export function oauthKeyAccount(ctx, key) {
+    if (!/^(sk|pk)_test_oauth_/.test(key))
+        return undefined;
+    const held = ctx.rowsRaw(CONNECTIONS).find((c) => c.revoked !== true && (c.access_token === key || c.publishable_key === key));
+    return held ? { account: String(held.id), scope: String(key.startsWith('pk_') ? held.scope : held.access_scope ?? held.scope) } : null;
+}
+// ── authorize ──
+/** A query parameter, or undefined when absent (an empty value is absent too, as a browser form sends one). */
+const param = (q, k) => { const v = q.get(k); return v === null || v === '' ? undefined : v; };
+/** The authorize request checked as Stripe checks it, or the JSON error it answers. */
+function checked(ctx, q) {
+    const state = param(q, 'state');
+    const fail = (error, description) => oauthError(error, description, 400, state !== undefined ? { state } : {});
+    const client = param(q, 'client_id');
+    if (!client)
+        return fail('invalid_request', 'No client_id provided.');
+    if (client !== PLATFORM_CLIENT_ID)
+        return fail('invalid_client', 'No application matches the supplied client identifier');
+    const settings = connectOAuthSettings(ctx);
+    if (!settings.oauth_enabled)
+        return fail('invalid_client', `OAuth is not enabled for this application. Enable it in your Connect OAuth settings (${SETTINGS_URL}).`);
+    const given = q.get('redirect_uri');
+    let redirect;
+    if (given !== null) {
+        if (!settings.redirect_uris.includes(given))
+            return fail('invalid_redirect_uri', `Invalid redirect URI '${given}'. Ensure this uri exactly matches one of the uris specified in your application settings`);
+        redirect = given;
+    }
+    else {
+        redirect = settings.redirect_uris[0];
+        if (!redirect)
+            return fail('invalid_redirect_uri', 'No redirect URI is configured in your application settings');
+    }
+    const type = q.get('response_type');
+    if (type === null || type === '')
+        return fail('invalid_request', 'Missing response_type parameter.');
+    if (type !== 'code')
+        return fail('unsupported_response_type', `Unsupported response_type parameter: ${type}. Currently the only supported response_type is code.`);
+    const scope = param(q, 'scope') ?? 'read_only';
+    if (!SCOPES.includes(scope))
+        return fail('invalid_scope', `Invalid scope parameter provided: '${scope}'. Accepted scopes are 'read_write' or 'read_only'.`);
+    return { redirect, scope: scope, state };
+}
+/** The redirect_uri with these parameters added, each percent-encoded (a space as %20, as Stripe's examples show). */
+function withParams(uri, params) {
+    const [base, fragment] = uri.split('#', 2);
+    const added = params.filter((p) => p[1] !== undefined).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+    return `${base}${base.includes('?') ? (base.endsWith('?') || base.endsWith('&') ? '' : '&') : '?'}${added}${fragment !== undefined ? `#${fragment}` : ''}`;
+}
+/** The prefill the request carries, invalid values silently dropped (docs.stripe.com/connect/oauth-reference). Only
+ *  what the new account's object shows the platform, or the page shows the person, is read: the person's birth date and
+ *  the business address are the account application's, which the twin does not model (the test-mode skip). */
+export function prefill(q) {
+    const v = (k) => param(q, `stripe_user[${k}]`)?.trim() || undefined;
+    const out = {};
+    const keep = (k, ok = () => true) => { const s = v(k); if (s !== undefined && ok(s))
+        out[k] = s; };
+    keep('email', (s) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s));
+    keep('url', (s) => /^https?:\/\/\S+$/i.test(s));
+    keep('country', (s) => /^[A-Z]{2}$/.test(s));
+    keep('phone_number', (s) => /^\d{10}$/.test(s) && out.country !== undefined);
+    keep('business_name');
+    keep('business_type', (s) => ['sole_prop', 'corporation', 'non_profit', 'partnership', 'llc'].includes(s));
+    keep('first_name');
+    keep('last_name');
+    keep('product_description');
+    keep('currency', (s) => /^[a-z]{3}$/.test(s) && out.country !== undefined);
+    return out;
+}
+// the default currency of an account in a country, where the prefill names none (docs.stripe.com/connect/currencies:
+// the account's default is its country's currency); a country outside this list is given usd
+const COUNTRY_CURRENCY = { US: 'usd', CA: 'cad', GB: 'gbp', AU: 'aud', NZ: 'nzd', JP: 'jpy', SG: 'sgd', HK: 'hkd', CH: 'chf', SE: 'sek', NO: 'nok', DK: 'dkk', PL: 'pln', MX: 'mxn', BR: 'brl', IN: 'inr', DE: 'eur', FR: 'eur', ES: 'eur', IT: 'eur', NL: 'eur', IE: 'eur', BE: 'eur', AT: 'eur', PT: 'eur', FI: 'eur' };
+const BUSINESS_TYPE = { sole_prop: 'individual', corporation: 'company', llc: 'company', partnership: 'company', non_profit: 'non_profit' };
+/** The Standard account the skipped form creates, from the prefill. */
+async function createAccount(ctx, p) {
+    const country = p.country ?? 'US';
+    const id = ctx.mint('account');
+    const none = { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] };
+    await created(ctx, 'account', { id }, {
+        type: 'standard', country, default_currency: p.currency ?? COUNTRY_CURRENCY[country] ?? 'usd', email: p.email ?? null,
+        business_type: p.business_type ? BUSINESS_TYPE[p.business_type] ?? null : null,
+        business_profile: { name: p.business_name ?? null, url: p.url ?? null, product_description: p.product_description ?? null, support_phone: p.phone_number ?? null, mcc: null },
+        charges_enabled: true, payouts_enabled: true, details_submitted: true,
+        capabilities: { card_payments: 'active', transfers: 'active' },
+        controller: { type: 'account' },
+        requirements: none, future_requirements: none,
+        settings: accountSettings(undefined, p.business_name ? { dashboard: { display_name: p.business_name, timezone: 'Etc/UTC' } } : undefined),
+        external_accounts: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/accounts/${id}/external_accounts` },
+        tos_acceptance: { date: null, ip: null, user_agent: null }, metadata: {}, livemode: false,
+    }, { operation: 'account.oauth_connect' });
+    return id;
+}
+/** The platform's application as the account.application.* events carry it. */
+function application(ctx) {
+    return { id: PLATFORM_CLIENT_ID, object: 'application', name: publicBusinessName(ctx.get('account', PLATFORM_ACCOUNT_ID)) };
+}
+/** Send one of the account.application.* events as the connected account's. */
+async function applicationEvent(ctx, type, account) {
+    await afterStripeWrite('application', type, application(ctx), ctx.root, ctx.occurredAt, undefined, account);
+}
+/** A code's number: `ac_twin_{n}`, the refresh token its exchange mints being `rt_twin_{n}`, so the one follows the
+ *  other and neither is counted separately. */
+const codeNumber = (code) => code.replace(/^ac_twin_/, '');
+function page(ctx, action, a, p) {
+    const name = publicBusinessName(ctx.get('account', PLATFORM_ACCOUNT_ID));
+    const who = [p.email, [p.first_name, p.last_name].filter(Boolean).join(' '), p.business_name].filter((s) => s).join(' · ');
+    return flowPage({
+        title: `Connect to ${name} – Stripe`,
+        css: [CONSENT_CSS, STRIPE_CONSENT_SKIN],
+        body: (_jsx(Consent, { heading: `Connect your Stripe account to ${name}`, app: { name }, request: "wants to connect to your Stripe account \u00B7 test mode", permissions: [
+                a.scope === 'read_write'
+                    ? { title: 'Read and write access', detail: 'Create payments, customers and other data on your account, and read its data' }
+                    : { title: 'Read-only access', detail: 'Read your account’s data' },
+                { title: 'A new test account', detail: who || 'No details prefilled' },
+            ], action: action, fields: {}, deny: { name: 'decision', value: 'deny', label: 'Deny access' }, allow: { name: 'decision', value: 'skip', label: 'Skip this form' }, note: `Test mode: skipping the form creates a new test account and connects it. You will be returned to ${new URL(a.redirect).host}.` })),
+    });
+}
+/** The person connects: a new Standard account, its connection's code, the authorized event, and the redirect. */
+async function connect(ctx, a, p) {
+    const account = await createAccount(ctx, p);
+    // the code's number is taken and its row written in one move, so two people connecting at once get two codes
+    const fields = { client_id: PLATFORM_CLIENT_ID, account, scope: a.scope, redirect_uri: a.redirect, expires_at: Number(ctx.now()) + CODE_TTL_SECONDS, used: false, livemode: false };
+    const code = await ctx.atomically((rows) => {
+        const id = `ac_twin_${rows(CODES).length + 1}`;
+        return { value: id, write: { resource: CODES, id, fields, operation: 'oauth_code.issue' } };
+    });
+    await applicationEvent(ctx, 'account.application.authorized', account);
+    return seeOther(withParams(a.redirect, [['scope', a.scope], ['code', code], ['state', a.state]]));
+}
+async function authorize(request, scope) {
+    const url = new URL(request.url);
+    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+    const a = checked(ctx, url.searchParams);
+    if (a instanceof Response)
+        return a;
+    const p = prefill(url.searchParams);
+    if (request.method === 'GET')
+        return page(ctx, `${url.pathname}${url.search}`, a, p);
+    if (form.decision === 'deny')
+        return seeOther(withParams(a.redirect, [['error', 'access_denied'], ['error_description', 'The user denied your request'], ['state', a.state]]));
+    if (form.decision === 'skip')
+        return connect(ctx, a, p);
+    return page(ctx, `${url.pathname}${url.search}`, a, p);
+}
+// ── token and deauthorize ──
+/** The request's parameters: a form, as stripe-node and curl send them, or JSON. */
+async function bodyOf(request) {
+    const text = await request.clone().text();
+    if ((request.headers.get('content-type') ?? '').includes('json') || text.trim().startsWith('{')) {
+        try {
+            return Object.fromEntries(Object.entries(JSON.parse(text)).map(([k, v]) => [k, String(v)]));
+        }
+        catch {
+            return {};
+        }
+    }
+    return Object.fromEntries(new URLSearchParams(text));
+}
+/** The secret key a request carries: Bearer, Basic's user, or the client_secret parameter. */
+function secretKey(request, params) {
+    const header = request.headers.get('authorization') ?? '';
+    const bearer = /^bearer\s+(\S+)/i.exec(header)?.[1];
+    if (bearer)
+        return bearer;
+    const basic = /^basic\s+(\S+)/i.exec(header)?.[1];
+    if (basic) {
+        try {
+            const user = atob(basic).split(':')[0];
+            if (user)
+                return user;
+        }
+        catch { /* not base64 */ }
+    }
+    return params.client_secret || undefined;
+}
+/** A key shown the way Stripe's errors show one: its prefix and its last four. */
+export const redactKey = (key) => {
+    const prefix = /^(sk|rk|pk)_(test|live)_/.exec(key)?.[0] ?? '';
+    const rest = key.slice(prefix.length);
+    return rest.length > 4 ? `${prefix}${'*'.repeat(rest.length - 4)}${rest.slice(-4)}` : `${prefix}${'*'.repeat(rest.length)}`;
+};
+/** The refusal of a request without a usable secret key, or undefined when it has one (answered with whether it is live). */
+function keyRefused(key) {
+    if (!key)
+        return oauthError('invalid_request', 'No API key provided. Provide your secret key in the Authorization header, using Bearer auth (e.g. \'Authorization: Bearer YOUR_SECRET_KEY\').', 401);
+    if (!/^(sk|rk)_(test|live)_/.test(key))
+        return oauthError('invalid_request', `Invalid API Key provided: ${redactKey(key)}. This endpoint requires a secret key.`, 401);
+    // a connected account's access_token is that account's key, never the platform's ("Make this call using your secret API
+    // key", the reference): it neither exchanges codes nor refreshes nor deauthorizes
+    if (/^sk_test_oauth_/.test(key))
+        return oauthError('invalid_request', `Invalid API Key provided: ${redactKey(key)}. This endpoint requires your platform's secret key.`, 401);
+    return undefined;
+}
+const live = (key) => /^(sk|rk)_live_/.test(key);
+/** A new access token for a connection: its generation counted from the ones it had. */
+const accessToken = (account, n) => `sk_test_oauth_${account}_${n}`;
+/** Revoke an account's connection, once: the check and the write are one move, and only the move that revoked it sends
+ *  account.application.deauthorized. Answers whether this call revoked it. */
+async function revoke(ctx, account) {
+    const revoked = await ctx.atomically((rows) => {
+        const held = rows(CONNECTIONS).find((c) => c.id === account);
+        if (!held || held.revoked === true)
+            return { value: false };
+        return { value: true, write: { resource: CONNECTIONS, id: account, fields: { revoked: true, access_token: null, revoked_at: Number(ctx.now()) }, operation: 'oauth_connection.revoke' } };
+    });
+    if (revoked)
+        await applicationEvent(ctx, 'account.application.deauthorized', account);
+    return revoked;
+}
+async function token(request, scope) {
+    const params = await bodyOf(request);
+    const key = secretKey(request, params);
+    const refused = keyRefused(key);
+    if (refused)
+        return refused;
+    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+    const grant = params.grant_type;
+    if (!grant)
+        return oauthError('invalid_request', 'No grant type specified');
+    if (grant !== 'authorization_code' && grant !== 'refresh_token')
+        return oauthError('unsupported_grant_type', `Unsupported grant type: ${grant}. The only currently supported types are authorization_code and refresh_token.`);
+    if (grant === 'authorization_code') {
+        const code = params.code;
+        if (!code)
+            return oauthError('invalid_request', 'No authorization code provided');
+        if (live(key))
+            return oauthError('invalid_grant', `Authorization code provided does not belong to the livemode of the API key: ${code} is a test mode code, but a live mode key was used.`);
+        const found = await ctx.atomically((rows) => {
+            const row = rows(CODES).find((r) => r.id === code);
+            if (!row)
+                return { value: { outcome: 'missing' } };
+            // a second use is marked in the same move, so the exchange that spent it sees it after writing its connection
+            if (row.used === true)
+                return { value: { outcome: 'used', row }, write: { resource: CODES, id: code, fields: { reused: true }, operation: 'oauth_code.reuse' } };
+            if (Number(ctx.now()) >= Number(row.expires_at))
+                return { value: { outcome: 'expired', row } };
+            return { value: { outcome: 'ok', row }, write: { resource: CODES, id: code, fields: { used: true, used_at: Number(ctx.now()) }, operation: 'oauth_code.redeem' } };
+        });
+        if (found.outcome === 'missing')
+            return oauthError('invalid_grant', `Authorization code does not exist: ${code}`);
+        const account = String(found.row.account);
+        if (found.outcome === 'used') {
+            // "Consuming an authorization code more than once revokes the account connection"
+            await revoke(ctx, account);
+            return oauthError('invalid_grant', 'This authorization code has already been used. All tokens issued with this code have been revoked.');
+        }
+        if (found.outcome === 'expired')
+            return oauthError('invalid_grant', `Authorization code expired: ${code}`);
+        const granted = String(found.row.scope);
+        const refresh = `rt_twin_${codeNumber(code)}`;
+        const connection = { client_id: PLATFORM_CLIENT_ID, account, scope: granted, code, refresh_token: refresh, access_token: accessToken(account, 1), access_scope: granted, generation: 1, publishable_key: `pk_test_oauth_${account}`, revoked: false, livemode: false };
+        await ctx.record(CONNECTIONS, connection, account);
+        // the code used again while this exchange was writing: that use found no connection to revoke, so this one does
+        if (ctx.rowsRaw(CODES).some((r) => r.id === code && r.reused === true)) {
+            await revoke(ctx, account);
+            return oauthError('invalid_grant', 'This authorization code has already been used. All tokens issued with this code have been revoked.');
+        }
+        return json(tokenBody(connection, granted));
+    }
+    const refresh = params.refresh_token;
+    if (!refresh)
+        return oauthError('invalid_request', 'No refresh token provided');
+    const held = ctx.rowsRaw(CONNECTIONS).find((c) => c.refresh_token === refresh && c.revoked !== true);
+    if (!held)
+        return oauthError('invalid_grant', `Refresh token does not exist: ${refresh}`);
+    if (live(key))
+        return oauthError('invalid_grant', 'The refresh token provided does not belong to the livemode of the API key.');
+    const asked = params.scope || String(held.scope);
+    if (!SCOPES.includes(asked))
+        return oauthError('invalid_scope', `Invalid scope parameter provided: '${asked}'. Accepted scopes are 'read_write' or 'read_only'.`);
+    if (asked === 'read_write' && held.scope !== 'read_write')
+        return oauthError('invalid_scope', `The requested scope 'read_write' is greater than the scope of the refresh token ('${String(held.scope)}').`);
+    const account = String(held.id);
+    // "Any existing access token with the same scope and mode ... is revoked": the connection holds the one now issued; the
+    // generation is read and written in one move, so two refreshes at once issue two tokens, and a refresh never lands
+    // on a connection revoked meanwhile
+    const renewed = await ctx.atomically((rows) => {
+        const now = rows(CONNECTIONS).find((c) => c.id === account && c.revoked !== true);
+        if (!now)
+            return { value: undefined };
+        const generation = Number(now.generation ?? 1) + 1;
+        const fields = { access_token: accessToken(account, generation), access_scope: asked, generation };
+        return { value: { ...now, ...fields }, write: { resource: CONNECTIONS, id: account, fields, operation: 'oauth_connection.refresh' } };
+    });
+    if (!renewed)
+        return oauthError('invalid_grant', `Refresh token does not exist: ${refresh}`);
+    return json(tokenBody(renewed, asked));
+}
+/** The token endpoint's answer, as the reference lists it. */
+function tokenBody(c, scope) {
+    return { access_token: c.access_token, livemode: false, refresh_token: c.refresh_token, scope, stripe_publishable_key: c.publishable_key, stripe_user_id: c.account ?? c.id, token_type: 'bearer' };
+}
+async function deauthorize(request, scope) {
+    const params = await bodyOf(request);
+    const key = secretKey(request, params);
+    const refused = keyRefused(key);
+    if (refused)
+        return refused;
+    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+    const client = params.client_id;
+    const account = params.stripe_user_id;
+    if (!client)
+        return oauthError('invalid_request', 'No client_id provided');
+    if (!account)
+        return oauthError('invalid_request', 'No stripe_user_id provided');
+    if (client !== PLATFORM_CLIENT_ID)
+        return oauthError('invalid_client', `No such application: '${client}'`);
+    if (live(key))
+        return oauthError('invalid_client', `The API key mode (live) does not match the mode of the client_id ${client} (test).`);
+    // the check and the revocation are one move (revoke): of two deauthorizations at once, one revokes and the other finds
+    // the account no longer connected
+    if (!(await revoke(ctx, account)))
+        return oauthError('invalid_client', `This application is not connected to stripe account ${account}, or that account does not exist.`);
+    return json({ stripe_user_id: account });
+}
+/** connect.stripe.com's OAuth endpoints, or undefined for any other request. */
+export function stripeConnectOAuthFlow(scope) {
+    return async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '');
+        if (path === '/oauth/authorize' && (request.method === 'GET' || request.method === 'POST'))
+            return authorize(request, scope);
+        if (path === '/oauth/token' && request.method === 'POST')
+            return token(request, scope);
+        if (path === '/oauth/deauthorize' && request.method === 'POST')
+            return deauthorize(request, scope);
+        return undefined;
+    };
+}