@volter/twin-stripe 2.0.0 → 2.0.1

package/src/index.ts

@@ -93,7 +93,7 @@ export const pack: TwinPack = {
   // 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.
@@ -101,15 +101,17 @@ export const pack: TwinPack = {
     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/src/manifest.ts

@@ -567,6 +567,11 @@ export const manifest: DerivedManifest = {
       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'],
@@ -578,9 +583,9 @@ export const manifest: DerivedManifest = {
       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/src/screens/checkout.tsx

@@ -111,6 +111,15 @@ function afterTrial(session: Row): number {
   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: Row): string | undefined {
+  const email = (session._customer as Row | undefined)?.email;
+  return typeof email === 'string' && EMAIL.test(email) ? email : undefined;
+}
+
 function page(session: Row, id: string, now: number, values: Record<string, string> = {}, error?: string): Response {
   const lines = (((session.line_items as { data?: Row[] } | undefined)?.data) ?? []).map((item) => ({
     name: String(item.description ?? 'Item'),
@@ -122,9 +131,12 @@ function page(session: Row, id: string, now: number, values: Record<string, stri
   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: PaymentField[] = 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: PaymentField[] = 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: PaymentField[] = [
     { 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' },
@@ -191,9 +203,10 @@ export function cardAnswer(v: Record<string, string>, nowSeconds: number, charge
 }
 
 async function pay(ctx: SemanticsContext, id: string, session: Row, v: Record<string, string>): Promise<Response> {
-  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)) return page(session, id, Number(ctx.now()), v, 'Your email address is incomplete.');
+    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
   const oneTimeDue = (((session.line_items as { data?: Row[] } | undefined)?.data) ?? []).some((it, i) => isOneTime(it, inlineOf(session, i)));
@@ -207,6 +220,8 @@ async function pay(ctx: SemanticsContext, id: string, session: Row, v: Record<st
     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: Row = {
     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 } : {}),
@@ -246,7 +261,7 @@ export function stripeCheckoutFlow(scope: { root?: string; clock?: () => string
     if (session.status !== 'open' && (request.method === 'GET' || ctx.legal(CS, 'status', COMPLETE_OPERATION.id, String(session.status), 'complete', id, 'external'))) return gone();
     const stored = ctx.row(CS, id) ?? {};
     const coupon = (stored._discount as Row | undefined)?.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/src/screens/connect-oauth.tsx

@@ -0,0 +1,400 @@
+// 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, type 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.ts';
+import { created, type Row } from '../semantics/shared.ts';
+import { OAUTH_CONNECTIONS, publicBusinessName } from '../stripe-shared.ts';
+import { accountSettings, afterStripeWrite, PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
+import { formOf, seeOther, STRIPE_CONSENT_SKIN } from './consent-skin.ts';
+import { connectOAuthSettings, PLATFORM_CLIENT_ID, SETTINGS_URL } from './connect-settings.tsx';
+
+const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).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'] as const;
+type Scope = (typeof SCOPES)[number];
+
+type Scoped = { root?: string; clock?: () => string };
+const json = (body: Row, status = 200): Response => Response.json(body, { status, headers: { 'request-id': 'req_twin', 'cache-control': 'no-store' } });
+const oauthError = (error: string, description: string, status = 400, extra: Row = {}): Response => 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: SemanticsContext, account: string): boolean {
+  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: SemanticsContext, key: string): { account: string; scope: string } | null | undefined {
+  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: URLSearchParams, k: string): string | undefined => { const v = q.get(k); return v === null || v === '' ? undefined : v; };
+
+type Authorize = { redirect: string; scope: Scope; state: string | undefined };
+
+/** The authorize request checked as Stripe checks it, or the JSON error it answers. */
+function checked(ctx: SemanticsContext, q: URLSearchParams): Authorize | Response {
+  const state = param(q, 'state');
+  const fail = (error: string, description: string) => 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: string | undefined;
+  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 as readonly string[]).includes(scope)) return fail('invalid_scope', `Invalid scope parameter provided: '${scope}'. Accepted scopes are 'read_write' or 'read_only'.`);
+  return { redirect, scope: scope as Scope, state };
+}
+
+/** The redirect_uri with these parameters added, each percent-encoded (a space as %20, as Stripe's examples show). */
+function withParams(uri: string, params: Array<[string, string | undefined]>): string {
+  const [base, fragment] = uri.split('#', 2) as [string, string | undefined];
+  const added = params.filter((p): p is [string, string] => 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: URLSearchParams): Record<string, string> {
+  const v = (k: string) => param(q, `stripe_user[${k}]`)?.trim() || undefined;
+  const out: Record<string, string> = {};
+  const keep = (k: string, ok: (s: string) => boolean = () => 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: Record<string, string> = { 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: Record<string, string> = { 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: SemanticsContext, p: Record<string, string>): Promise<string> {
+  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: SemanticsContext): Row {
+  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: SemanticsContext, type: 'account.application.authorized' | 'account.application.deauthorized', account: string): Promise<void> {
+  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: string): string => code.replace(/^ac_twin_/, '');
+
+function page(ctx: SemanticsContext, action: string, a: Authorize, p: Record<string, string>): Response {
+  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: (
+      <Consent
+        heading={`Connect your Stripe account to ${name}`}
+        app={{ name }}
+        request="wants to connect to your Stripe account · 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: SemanticsContext, a: Authorize, p: Record<string, string>): Promise<Response> {
+  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: Request, scope: Scoped): Promise<Response> {
+  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: Request): Promise<Record<string, string>> {
+  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) as Row).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: Request, params: Record<string, string>): string | undefined {
+  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: string): string => {
+  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: string | undefined): Response | undefined {
+  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: string): boolean => /^(sk|rk)_live_/.test(key);
+
+/** A new access token for a connection: its generation counted from the ones it had. */
+const accessToken = (account: string, n: number): string => `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: SemanticsContext, account: string): Promise<boolean> {
+  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: Request, scope: Scoped): Promise<Response> {
+  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.`);
+    // a code is spent once: the read and the spend are one move, so two exchanges at once cannot both succeed
+    type Redeemed = { outcome: 'missing' } | { outcome: 'used' | 'expired' | 'ok'; row: Row };
+    const found = await ctx.atomically<Redeemed>((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) as 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 as readonly string[]).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 as Scope));
+}
+
+/** The token endpoint's answer, as the reference lists it. */
+function tokenBody(c: Row, scope: Scope): Row {
+  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: Request, scope: Scoped): Promise<Response> {
+  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: Scoped): (request: Request) => Promise<Response | undefined> {
+  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;
+  };
+}