@volter/twin-stripe 2.0.0 → 2.0.2

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;
+  };
+}

package/src/screens/connect-settings.tsx

@@ -0,0 +1,121 @@
+// THE DASHBOARD'S CONNECT OAUTH SETTINGS — a workspace page (docs/contributing/architecture.md, "Screens") of the
+// Dashboard (manifest screen `dashboard`), at dashboard.stripe.com/settings/connect/onboarding-options/oauth, where a
+// platform starts an OAuth integration: "Enable onboarding accounts with OAuth", "Copy your client_id, a unique
+// identifier for your platform that's generated by Stripe", and "Set your redirect_uri ... You must specify all redirect
+// URLs in your platform settings. If you don't include the redirect_uri parameter in your request, Stripe defaults to
+// using the first address you've configured" (docs.stripe.com/connect/oauth-standard-accounts). The test client_id
+// "allows you to: Set your redirect_uri to a non-HTTPS URL; Set your redirect_uri to localhost"
+// (docs.stripe.com/connect/testing#using-oauth). Stripe's API has no call that reads or changes these settings (GET
+// /v1/account does not carry the client_id), so this page is the only way to them, and connect.stripe.com/oauth/authorize
+// (./connect-oauth.tsx) reads what it saves. Authored from plain markup under Stripe's type; nothing of Stripe's page is
+// copied.
+//
+// Where the documentation stops and the twin decides: the World has one platform, and its test client_id is
+// `ca_twin_self` (PLATFORM_CLIENT_ID; the platform account is acct_twin_self), the same in every World, shown on the
+// page in an element a runner reads (data-testid="connect-client-id"). OAuth starts disabled. The page is served at
+// the docs' address, at /test/… (the docs' test-mode link) and at /settings/connect (the address Cal.com's setup
+// guide gives). The redirect URIs are one form field, one per line (or comma-separated, as the reference describes
+// them), saved whole: each an absolute http or https URL without a fragment; http and localhost are allowed, as the
+// test client_id allows them. No sign-in guards the page, as none guards the Dashboard mirror. The form posts to the
+// page's own address and the save redirects to it.
+import { semanticsContext, type SemanticsContext } from '@volter/world-core';
+import { flowPage } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from '../manifest.ts';
+import { formOf } from './consent-skin.ts';
+
+/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
+export const PLATFORM_CLIENT_ID = 'ca_twin_self';
+export const SETTINGS_URL = 'https://dashboard.stripe.com/settings/connect/onboarding-options/oauth';
+/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
+export const CONNECT_SETTINGS_PATH = /^\/(test\/)?settings\/connect(\/onboarding-options\/oauth)?\/?$/;
+const SETTINGS = '_connect_oauth_settings';
+const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostAccountsAccount')!;
+
+export type ConnectOAuthSettings = { oauth_enabled: boolean; redirect_uris: string[] };
+
+/** What the platform saved, or the settings a new platform starts with (OAuth off, no redirect URI). */
+export function connectOAuthSettings(ctx: SemanticsContext): ConnectOAuthSettings {
+  const row = ctx.rowsRaw(SETTINGS).find((r) => r.id === PLATFORM_CLIENT_ID);
+  return { oauth_enabled: row?.oauth_enabled === true, redirect_uris: Array.isArray(row?.redirect_uris) ? (row!.redirect_uris as string[]) : [] };
+}
+
+/** The redirect URIs a form's field names, or the first one refused and why. */
+export function redirectUris(field: string): { uris: string[] } | { refused: string } {
+  const uris = [...new Set(field.split(/[\n,]/).map((s) => s.trim()).filter(Boolean))];
+  for (const uri of uris) {
+    let url: URL;
+    try { url = new URL(uri); } catch { return { refused: `${uri} is not a valid URL.` }; }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return { refused: `${uri} must use http or https.` };
+    if (uri.includes('#')) return { refused: `${uri} must not contain a fragment.` };
+  }
+  return { uris };
+}
+
+const CSS = `
+* { box-sizing: border-box; }
+body { margin: 0; background: #f6f8fa; color: #1a1f36; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Ubuntu, sans-serif; font-size: 14px; }
+.co { max-width: 680px; margin: 48px auto; padding: 0 16px; }
+.co h1 { font-size: 28px; margin: 16px 0 4px; }
+.co-lead { color: #697386; margin: 0 0 24px; }
+.co-card { background: #ffffff; border: 1px solid #e3e8ee; border-radius: 8px; padding: 24px; margin-bottom: 16px; }
+.co-card h2 { font-size: 16px; margin: 0 0 12px; }
+.co-card label { display: block; font-weight: 600; margin-bottom: 6px; }
+.co-card small { display: block; color: #697386; margin-bottom: 8px; }
+.co-card textarea { width: 100%; min-height: 96px; padding: 8px 10px; border: 1px solid #c1c9d2; border-radius: 6px; font: 13px ui-monospace, Menlo, monospace; }
+.co-id { font: 14px ui-monospace, Menlo, monospace; background: #f6f8fa; border: 1px solid #e3e8ee; border-radius: 6px; padding: 6px 10px; display: inline-block; }
+.co-toggle { display: flex; gap: 8px; align-items: center; font-weight: 600; }
+.co-actions { display: flex; justify-content: flex-end; }
+.co-actions button { background: #635bff; color: #ffffff; border: 0; border-radius: 6px; padding: 8px 16px; font: inherit; font-weight: 600; cursor: pointer; }
+.co-notice { padding: 10px 12px; border-radius: 6px; margin-bottom: 16px; }
+.co-error { background: #fff0f3; color: #df1b41; }
+.co-saved { background: #e7f8ef; color: #0e6245; }
+.co-uris { margin: 0; padding-left: 18px; }
+`;
+
+function page(s: ConnectOAuthSettings, opts: { value?: string; enabled?: boolean; error?: string; saved?: boolean } = {}): Response {
+  const enabled = opts.enabled ?? s.oauth_enabled;
+  return flowPage({
+    title: 'OAuth – Connect settings – Stripe',
+    css: [CSS],
+    ...(opts.error ? { status: 400 } : {}),
+    body: (
+      <main className="co">
+        <h1>OAuth</h1>
+        <p className="co-lead">Onboard Standard accounts by sending them to Stripe's OAuth flow. Test mode.</p>
+        {opts.error ? <p className="co-notice co-error" role="alert">{opts.error}</p> : null}
+        {opts.saved ? <p className="co-notice co-saved" role="status">Your OAuth settings were saved.</p> : null}
+        <section className="co-card">
+          <h2>Test mode client ID</h2>
+          <small>The client_id your platform sends to connect.stripe.com/oauth/authorize.</small>
+          <code className="co-id" data-testid="connect-client-id">{PLATFORM_CLIENT_ID}</code>
+          <p data-testid="connect-oauth-status">{s.oauth_enabled ? 'OAuth is enabled.' : 'OAuth is disabled.'}</p>
+          {s.redirect_uris.length ? <ul className="co-uris">{s.redirect_uris.map((u) => <li key={u} data-testid="connect-redirect-uri">{u}</li>)}</ul> : <p>No redirect URIs.</p>}
+        </section>
+        <form className="co-card" method="post">
+          <label className="co-toggle" htmlFor="oauth_enabled"><input type="checkbox" id="oauth_enabled" name="oauth_enabled" value="on" defaultChecked={enabled} /> Enable OAuth for Standard accounts</label>
+          <label htmlFor="redirect_uris">Redirect URIs</label>
+          <small>One per line. The first is used when a request names none. http and localhost are allowed in test mode.</small>
+          <textarea id="redirect_uris" name="redirect_uris" defaultValue={opts.value ?? s.redirect_uris.join('\n')} />
+          <div className="co-actions"><button type="submit">Save</button></div>
+        </form>
+      </main>
+    ),
+  });
+}
+
+export function stripeConnectSettingsFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
+  return async (request) => {
+    const url = new URL(request.url);
+    if (!CONNECT_SETTINGS_PATH.test(url.pathname) || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
+    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+    const held = connectOAuthSettings(ctx);
+    if (request.method === 'GET') return page(held, { saved: url.searchParams.has('saved') });
+    const enabled = form.oauth_enabled === 'on' || form.oauth_enabled === 'true';
+    const parsed = redirectUris(form.redirect_uris ?? '');
+    if ('refused' in parsed) return page(held, { value: form.redirect_uris ?? '', enabled, error: parsed.refused });
+    await ctx.record(SETTINGS, { oauth_enabled: enabled, redirect_uris: parsed.uris }, PLATFORM_CLIENT_ID);
+    return new Response(null, { status: 303, headers: { location: '?saved=1' } });
+  };
+}

package/src/screens/portal.tsx

@@ -21,6 +21,7 @@ import { flowPage, Portal, PORTAL_CSS, type PaymentField, type PortalItem } from
 import surface from '../generated/surface.gen.json' with { type: 'json' };
 import { manifest } from '../manifest.ts';
 import { payerOf, payOpenInvoice } from '../semantics/renewals.ts';
+import { afterSuccessOf } from '../semantics/after-payment.ts';
 import { created, type Row } from '../semantics/shared.ts';
 import { publicBusinessName } from '../stripe-shared.ts';
 import { declineFor, paymentMethodSubObject, PLATFORM_ACCOUNT_ID } from '../stripe-twin.ts';
@@ -176,6 +177,7 @@ async function updatePaymentMethod(ctx: SemanticsContext, id: string, session: R
     type: 'card', customer, livemode: false,
     billing_details: { address: { country: v.billingCountry || null, postal_code: v.billingPostalCode || null, city: null, line1: null, line2: null, state: null }, email: null, name: v.billingName || null, phone: null },
     ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null,
+    ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}),
   });
   const holder = ctx.get('customer', customer) ?? {};
   await ctx.write('customer', customer, { invoice_settings: { ...((holder.invoice_settings as Row | undefined) ?? {}), default_payment_method: pm.id } }, 'customer.update');

package/src/semantics/after-payment.ts

@@ -17,9 +17,10 @@
 import type { SemanticsContext } from '@volter/world-core';
 import { disputeEvidence } from '../stripe-twin.ts';
 import { actingAccount, settleApplicationFee, settleDispute, settleTransfer } from './ledger.ts';
+import { BYPASS_PENDING_CARDS } from './test-cards.ts';
 import { created, type Row } from './shared.ts';
 
-type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review';
+type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review' | 'available';
 const DAY = 86_400;
 
 /** The test cards whose success Stripe follows with its own act, by number and by their documented test names. */
@@ -28,12 +29,16 @@ export const AFTER_SUCCESS_CARDS: Record<string, { brand: string; number: string
   pm_card_createDisputeProductNotReceived: { brand: 'visa', number: '4000000000002685', outcome: 'dispute_not_received' },
   pm_card_createDisputeInquiry: { brand: 'visa', number: '4000000000001976', outcome: 'inquiry' },
   pm_card_riskLevelElevated: { brand: 'visa', number: '4000000000009235', outcome: 'review' },
+  // its funds go straight to the available balance (ledger.ts reads it; no act follows here)
+  ...Object.fromEntries(Object.entries(BYPASS_PENDING_CARDS).map(([name, c]) => [name, { ...c, outcome: 'available' as const }])),
 };
 const BY_NUMBER: Record<string, Outcome> = Object.fromEntries(Object.values(AFTER_SUCCESS_CARDS).map((c) => [c.number, c.outcome]));
 
 /** What Stripe does after a card succeeds: from a raw number, a test name (pm_card_* or tok_*), or a stored
  *  PaymentMethod that recorded it when it was made. */
 export function afterSuccessOf(ctx: SemanticsContext, ref: unknown): Outcome | undefined {
+  // a card given as a token (card[token], payment_method_data[card][token]) is the card the token names
+  if (ref && typeof ref === 'object' && typeof (ref as Row).token === 'string') return afterSuccessOf(ctx, (ref as Row).token);
   if (ref && typeof ref === 'object') return BY_NUMBER[String((ref as Row).number ?? '').replace(/\D/g, '')];
   if (typeof ref !== 'string' || !ref) return undefined;
   const stored = ctx.row('payment_method', ref);

package/src/semantics/charges.ts

@@ -23,13 +23,22 @@ export function chargeBody(ctx: SemanticsContext, c: Row): Row {
 // (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
 // occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
 // created"): its charges settle when made.
+/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
+ *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
+ *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
+ *  CVC back on every read of the charge. */
+function withoutCard(params: Row): Row {
+  const { card: _card, ...rest } = params;
+  return rest;
+}
+
 /** A Charges-API charge a declining test card refuses: a 402 card_error naming the failed charge Stripe records for the
  *  attempt (docs.stripe.com/declines). */
 async function declinedCharge(ctx: SemanticsContext, decline: { code: string; decline_code?: string; message: string }): Promise<Response> {
   const params = ctx.params;
   const failedId = ctx.mint('charge');
   const amount = Number(params.amount) || 0;
-  await created(ctx, 'charge', { ...params, id: failedId }, {
+  await created(ctx, 'charge', { ...withoutCard(params), id: failedId }, {
     ...chargeDefaults(failedId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
     failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
     outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
@@ -63,7 +72,7 @@ const create: Semantics = async (ctx) => {
   const card = String(params.source ?? params.payment_method ?? (params.card as Row | undefined)?.number ?? '');
   const bt = captured ? await settleCharge(ctx, id, amount, String(params.currency ?? 'usd'), card) : null;
   const details = paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card);
-  await created(ctx, 'charge', { ...params, id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
+  await created(ctx, 'charge', { ...withoutCard(params), id }, { ...chargeDefaults(id, amount, captured, ctx.occurredAt), balance_transaction: bt, payment_method_details: details ?? null }, { operation: 'charge.succeeded' });
   await afterCharge(ctx, id, { amount, currency: String(params.currency ?? 'usd'), application_fee_amount: params.application_fee_amount, destination: (params.transfer_data as Row | undefined)?.destination }, params.payment_method ?? params.source ?? params.card);
   return ctx.reply(chargeBody(ctx, ctx.get('charge', id)!));
 };