@volter/twin-stripe 2.0.38 → 3.0.0

package/src/screens/connect-oauth.tsx

@@ -9,7 +9,7 @@
 // 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
+// - authorize: `client_id` is the platform's (its Connect OAuth settings, ./dashboard.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,
@@ -26,13 +26,13 @@
 //   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).
+//   your platform ... through the API" (../engine/front.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
+// - the twin is a test-mode Stripe: its client_id is a test one (./dashboard.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).
@@ -50,50 +50,34 @@
 //   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
+// - tokens are drawn from secrets the World holds (ctx.secret), so none is computable from the account's id:
+//   access_token `sk_test_oauth_{account}_{secret of its generation}`, refresh_token `rt_{secret of the code}`,
+//   stripe_publishable_key `pk_test_oauth_{account}` (publishable, so public); a refresh answers the same refresh_token. The access_token and publishable key are deprecated by Stripe (use the
+//   Stripe-Account header) and act as the account (../engine/front.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 type { HandlerContext } 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';
+import type { Row } from '../engine/common.ts';
+import { PLATFORM_CLIENT_ID, SETTINGS_URL } from '../engine/connect-settings.ts';
+import { OAUTH_CONNECTIONS, publicBusinessName } from '../engine/display.ts';
+import { redactKey } from '../engine/oauth.ts';
+import { accountSettings, nowUnix, PLATFORM_ACCOUNT_ID } from '../engine/stripe.ts';
+import { formOf, notFound, seeOther, STRIPE_CONSENT_SKIN } from './shared.tsx';
+import { connectOAuthSettings, created, decide } from '../semantics/shared.ts';
 
-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 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 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). */
@@ -102,7 +86,7 @@ const param = (q: URLSearchParams, k: string): string | undefined => { const 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 {
+function checked(ctx: HandlerContext, 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');
@@ -137,7 +121,7 @@ function withParams(uri: string, params: Array<[string, string | undefined]>): s
 /** 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> {
+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; };
@@ -160,7 +144,7 @@ const COUNTRY_CURRENCY: Record<string, string> = { US: 'usd', CA: 'cad', GB: 'gb
 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> {
+async function createAccount(ctx: HandlerContext, 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: [] };
@@ -180,20 +164,17 @@ async function createAccount(ctx: SemanticsContext, p: Record<string, string>):
 }
 
 /** The platform's application as the account.application.* events carry it. */
-function application(ctx: SemanticsContext): Row {
+function application(ctx: HandlerContext): 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);
+/** Send one of the account.application.* events as the connected account's: the notice it is sent for (the kernel
+ *  sends it, ../semantics/events.ts renders it). */
+async function applicationEvent(ctx: HandlerContext, type: 'account.application.authorized' | 'account.application.deauthorized', account: string): Promise<void> {
+  await ctx.write('_application_notice', `${account}:${type}:${ctx.occurredAt}`, { account, application: application(ctx) }, type);
 }
 
-/** 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 {
+function page(ctx: HandlerContext, 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({
@@ -221,22 +202,20 @@ function page(ctx: SemanticsContext, action: string, a: Authorize, p: Record<str
 }
 
 /** 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> {
+async function connect(ctx: HandlerContext, 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' } };
-  });
+  // the code's row id is minted and its value drawn from the World's secret; the row keeps the value's SHA-256 alone
+  const id = ctx.mint(CODES);
+  const code = `ac_${(await ctx.secret(`stripe-oauth-code:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 24)}`;
+  await ctx.record(CODES, { client_id: PLATFORM_CLIENT_ID, account, scope: a.scope, redirect_uri: a.redirect, expires_at: nowUnix(ctx.occurredAt) + CODE_TTL_SECONDS, used: false, livemode: false, sha256: ctx.crypto.sha256(code) }, id);
   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> {
+async function authorize(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
   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);
@@ -267,13 +246,6 @@ function secretKey(request: Request, params: Record<string, string>): string | u
   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);
@@ -286,26 +258,29 @@ function keyRefused(key: string | undefined): Response | 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}`;
+/** A connection's access token of one generation: its account, then a digest of the connection's secret and the
+ *  generation (the secret read before the atomic move that numbers the generation). */
+// p3: keyed by the connection's secret, drawn from ctx.secret
+const accessToken = (ctx: Pick<HandlerContext, 'crypto'>, secret: string, account: string, n: number): string => `sk_test_oauth_${account}_${ctx.crypto.digest('sha256', `${secret}:${n}`, 'base64url').replace(/[-_]/g, '').slice(0, 24)}`;
 
 /** 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) => {
+async function revoke(ctx: HandlerContext, account: string): Promise<boolean> {
+  const revoked = await decide(ctx, (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' } };
+    return { value: true, write: { resource: CONNECTIONS, id: account, fields: { revoked: true, access_token: null, revoked_at: nowUnix(ctx.occurredAt) }, operation: 'oauth_connection.revoke' } };
   });
   if (revoked) await applicationEvent(ctx, 'account.application.deauthorized', account);
   return revoked;
 }
 
-async function token(request: Request, scope: Scoped): Promise<Response> {
+async function token(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
   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.`);
@@ -315,13 +290,13 @@ async function token(request: Request, scope: Scoped): Promise<Response> {
     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);
+    const found = await decide<Redeemed>(ctx, (rows) => {
+      const row = rows(CODES).find((r) => r.sha256 === ctx.crypto.sha256(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 (row.used === true) return { value: { outcome: 'used', row }, write: { resource: CODES, id: String(row.id), fields: { reused: true }, operation: 'oauth_code.reuse' } };
+      if (nowUnix(ctx.occurredAt) >= Number(row.expires_at)) return { value: { outcome: 'expired', row } };
+      return { value: { outcome: 'ok', row }, write: { resource: CODES, id: String(row.id), fields: { used: true, used_at: nowUnix(ctx.occurredAt) }, operation: 'oauth_code.redeem' } };
     });
     if (found.outcome === 'missing') return oauthError('invalid_grant', `Authorization code does not exist: ${code}`);
     const account = String(found.row.account);
@@ -332,11 +307,12 @@ async function token(request: Request, scope: Scoped): Promise<Response> {
     }
     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 };
+    const refresh = `rt_${(await ctx.secret(`stripe-oauth-refresh:${String(found.row.id)}`)).replace(/[-_]/g, '').slice(0, 32)}`;
+    const secret = await ctx.secret(`stripe-oauth-access:${account}`);
+    const connection = { client_id: PLATFORM_CLIENT_ID, account, scope: granted, code: found.row.id, refresh_token: refresh, access_token: accessToken(ctx, secret, 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)) {
+    if (ctx.rowsRaw(CODES).some((r) => r.id === found.row.id && 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.');
     }
@@ -354,11 +330,12 @@ async function token(request: Request, scope: Scoped): Promise<Response> {
   // "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 secret = await ctx.secret(`stripe-oauth-access:${account}`);
+  const renewed = await decide(ctx, (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 };
+    const fields = { access_token: accessToken(ctx, secret, 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}`);
@@ -370,12 +347,12 @@ 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> {
+async function deauthorize(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
   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');
@@ -388,13 +365,12 @@ async function deauthorize(request: Request, scope: Scoped): Promise<Response> {
   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;
-  };
+/** connect.stripe.com's OAuth endpoints; Stripe's 404 for anything else there. */
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const path = new URL(request.url).pathname.replace(/\/+$/, '');
+  if (path === '/oauth/authorize' && (request.method === 'GET' || request.method === 'POST')) return authorize(ctx);
+  if (path === '/oauth/token' && request.method === 'POST') return token(ctx);
+  if (path === '/oauth/deauthorize' && request.method === 'POST') return deauthorize(ctx);
+  return notFound();
 }

package/src/screens/{onboarding.tsx → connect-onboarding.tsx}

@@ -23,25 +23,25 @@
 // merchant category codes as its list gives them (./industries.ts), and an industry the page does not offer leaves
 // business_profile.mcc due; the states are the fifty and the District of Columbia; a request with no forwarded address
 // records 127.0.0.1. An update link (account_update) shows the same page.
-import { semanticsContext, type SemanticsContext } from '@volter/world-core';
+import type { HandlerContext } from '@volter/world-core';
 import { CONSENT_CSS, flowPage, Payment, PAYMENT_CSS, type PaymentField } from '@volter/world-ui';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { created, syncExternals, type Row } from '../semantics/shared.ts';
-import { formOf, seeOther, STRIPE_CONSENT_SKIN } from './consent-skin.ts';
-import { INDUSTRIES as MCCS } from './industries.ts';
+import type { Row } from '../engine/common.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import { formOf, notFound, seeOther, STRIPE_CONSENT_SKIN } from './shared.tsx';
+import { INDUSTRIES as MCCS } from '../engine/industries.ts';
+import { currentlyDue, type Form, type Kind, kindOf, OFFERED } from '../engine/onboarding.ts';
+import { created, syncExternals } from '../semantics/shared.ts';
 
 const LINK = 'account_link';
-const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'PostAccountsAccount')!;
+const OPERATION = { id: 'PostAccountsAccount' };
 
 const gone = (): Response => flowPage({ title: 'Stripe', status: 404, css: [CONSENT_CSS, STRIPE_CONSENT_SKIN], body: <main className="consent"><h1 className="consent-heading">This link is invalid.</h1></main> });
 
 /** A link that can still be used: not used and not past its expiry. */
-const usable = (ctx: SemanticsContext, link: Row): boolean => link.used !== true && Number(link.expires_at) > Number(ctx.now());
+const usable = (ctx: HandlerContext, link: Row): boolean => link.used !== true && Number(link.expires_at) > nowUnix(ctx.occurredAt);
 
 // the field asks, with no industry chosen until the person chooses one (an unanswered field leaves the MCC due)
 const INDUSTRIES = [{ value: '', label: 'Select your industry' }, ...MCCS.map(([value, label]) => ({ value, label }))];
-const OFFERED = new Set(MCCS.map(([mcc]) => mcc));
 // the fifty states and the District of Columbia, by their USPS codes (the address's `state`, ISO 3166-2 without its
 // country, docs.stripe.com/api/accounts/object)
 const STATES = ([
@@ -55,49 +55,6 @@ const STATES = ([
   ['WA', 'Washington'], ['WV', 'West Virginia'], ['WI', 'Wisconsin'], ['WY', 'Wyoming'],
 ] as const).map(([value, label]) => ({ value, label }));
 
-type Form = Record<string, string>;
-type Kind = 'company' | 'individual';
-const has = (v: Form, k: string): boolean => (v[k] ?? '').trim() !== '';
-const dobPart = (v: Form, i: number): boolean => /^\d{4}-\d{2}-\d{2}$/.test(v.dob ?? '') && Number((v.dob ?? '').split('-')[i]) > 0;
-
-/** Each requirement Stripe names, the form's answer that meets it, and which of the two sets it belongs to. */
-const REQUIREMENTS: Array<[string, (v: Form) => boolean, Kind[]]> = [
-  ['business_profile.mcc', (v) => OFFERED.has((v.mcc ?? '').trim()), ['company', 'individual']],
-  ['business_profile.url', (v) => has(v, 'url'), ['company', 'individual']],
-  ['settings.payments.statement_descriptor', (v) => has(v, 'statement_descriptor'), ['company', 'individual']],
-  ['company.name', (v) => has(v, 'company_name'), ['company']],
-  ['company.tax_id', (v) => has(v, 'company_tax_id'), ['company']],
-  ['company.phone', (v) => has(v, 'company_phone'), ['company']],
-  ['company.address.line1', (v) => has(v, 'company_line1'), ['company']],
-  ['company.address.city', (v) => has(v, 'company_city'), ['company']],
-  ['company.address.state', (v) => has(v, 'company_state'), ['company']],
-  ['company.address.postal_code', (v) => has(v, 'company_postal_code'), ['company']],
-  ['company.owners_provided', (v) => v.owners_provided === 'provided', ['company']],
-  ['owners.first_name', (v) => has(v, 'owner_first_name'), ['company']],
-  ['owners.last_name', (v) => has(v, 'owner_last_name'), ['company']],
-  ['owners.email', (v) => has(v, 'owner_email'), ['company']],
-  ...(['first_name', 'last_name', 'email', 'phone'] as const).flatMap((f): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.${f}`, (v) => has(v, f), ['company']], [`individual.${f}`, (v) => has(v, f), ['individual']]]),
-  ...(['day', 'month', 'year'] as const).flatMap((f, i): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.dob.${f}`, (v) => dobPart(v, 2 - i), ['company']], [`individual.dob.${f}`, (v) => dobPart(v, 2 - i), ['individual']]]),
-  ...(['line1', 'city', 'state', 'postal_code'] as const).flatMap((f): Array<[string, (v: Form) => boolean, Kind[]]> => [[`representative.address.${f}`, (v) => has(v, f), ['company']], [`individual.address.${f}`, (v) => has(v, f), ['individual']]]),
-  ['representative.relationship.title', (v) => has(v, 'title'), ['company']],
-  ['representative.ssn_last_4', (v) => /^\d{4}$/.test(v.ssn_last_4 ?? ''), ['company']],
-  ['individual.ssn_last_4', (v) => /^\d{4}$/.test(v.ssn_last_4 ?? ''), ['individual']],
-  ['tos_acceptance.date', (v) => v.tos === 'accepted', ['company', 'individual']],
-  ['tos_acceptance.ip', (v) => v.tos === 'accepted', ['company', 'individual']],
-  ['external_account', (v) => has(v, 'routing_number') && has(v, 'account_number'), ['company', 'individual']],
-];
-
-/** The set an account onboards against: the two US sets the twin models, or none. */
-export function kindOf(account: Row): Kind | undefined {
-  const type = account.business_type ?? 'individual';
-  return (account.country ?? 'US') === 'US' && (type === 'company' || type === 'individual') ? type : undefined;
-}
-
-/** What an account of this kind still owes, given the form's answers (none: all of it). */
-export function currentlyDue(kind: Kind, v: Form = {}): string[] {
-  return REQUIREMENTS.filter(([, met, kinds]) => kinds.includes(kind) && !met(v)).map(([req]) => req);
-}
-
 const field = (id: string, label: string, v: Form, extra: Partial<PaymentField> = {}): PaymentField => ({ id, label, value: v[id] ?? '', ...extra });
 const addressFields = (prefix: string, v: Form): PaymentField[] => [
   field(`${prefix}line1`, 'Address', v, { autoComplete: 'address-line1' }), field(`${prefix}city`, 'City', v),
@@ -107,7 +64,7 @@ const addressFields = (prefix: string, v: Form): PaymentField[] => [
 /** The industry the field shows: what the form sent, else what the account already holds, when the page offers it. */
 const industryOf = (mcc: unknown): string => (typeof mcc === 'string' && OFFERED.has(mcc.trim()) ? mcc.trim() : '');
 
-function page(ctx: SemanticsContext, sessionUrl: string, link: Row, kind: Kind, values: Form = {}, error?: string): Response {
+function page(ctx: HandlerContext, sessionUrl: string, link: Row, kind: Kind, values: Form = {}, error?: string): Response {
   const v = values;
   const business: PaymentField[] = [
     field('mcc', 'Industry', v, { options: INDUSTRIES, value: industryOf(v.mcc ?? (ctx.get('account', String(link.account))?.business_profile as Row | undefined)?.mcc) }),
@@ -157,13 +114,13 @@ function unmodelled(account: Row): Response {
 }
 
 /** A submit that leaves something out is refused on the page with what is missing, the owner's answers kept. */
-function incomplete(ctx: SemanticsContext, sessionUrl: string, link: Row, kind: Kind, v: Form, missing: string[]): Response {
+function incomplete(ctx: HandlerContext, sessionUrl: string, link: Row, kind: Kind, v: Form, missing: string[]): Response {
   return page(ctx, sessionUrl, link, kind, v, `Still required: ${missing.join(', ')}.`);
 }
 
 /** The owner submits everything: it is stored on the account, nothing is due, and charges, payouts and the requested
  *  capabilities are enabled. */
-async function submit(ctx: SemanticsContext, link: Row, kind: Kind, v: Form, ip: string): Promise<void> {
+async function submit(ctx: HandlerContext, link: Row, kind: Kind, v: Form, ip: string): Promise<void> {
   const id = String(link.account);
   const account = ctx.get('account', id);
   if (!account) return;
@@ -186,7 +143,7 @@ async function submit(ctx: SemanticsContext, link: Row, kind: Kind, v: Form, ip:
     ...(company
       ? { company: { name: v.company_name, phone: v.company_phone, address: addressOf('company_'), tax_id_provided: true, owners_provided: true, directors_provided: false, executives_provided: false } }
       : { individual: { ...person, id: `person_${id}` } }),
-    tos_acceptance: { date: Number(ctx.now()), ip, user_agent: null },
+    tos_acceptance: { date: nowUnix(ctx.occurredAt), ip, user_agent: null },
   }, 'account.updated');
   if (company) {
     await created(ctx, 'person', { account: id }, { ...person, relationship: { representative: true, executive: true, director: false, owner: false, percent_ownership: null, title: v.title }, metadata: {} });
@@ -205,7 +162,7 @@ const SESSIONS = 'https://connect.stripe.com/setup/s/';
 
 /** Visiting an Account Link consumes it and sends the owner to their onboarding session; a used or expired one sends
  *  them to refresh_url for a fresh link. */
-async function visit(ctx: SemanticsContext, id: string): Promise<Response> {
+async function visit(ctx: HandlerContext, id: string): Promise<Response> {
   const link = ctx.get(LINK, id);
   if (!link) return gone();
   if (!usable(ctx, link)) return seeOther(String(link.refresh_url));
@@ -215,29 +172,28 @@ async function visit(ctx: SemanticsContext, id: string): Promise<Response> {
 }
 
 /** connect.stripe.com's onboarding pages, or undefined for any other request. */
-export function stripeOnboardingFlow(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
-  return async (request) => {
-    const path = new URL(request.url).pathname;
-    const entry = /^\/setup\/(acctlink_[A-Za-z0-9_]+)\/?$/.exec(path);
-    const at = /^\/setup\/s\/(onbs_[A-Za-z0-9_]+)\/?$/.exec(path);
-    if (entry && request.method === 'GET') return visit(await semanticsContext(manifest, request, OPERATION, scope), entry[1]!);
-    if (!at || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
-    const sid = at[1]!;
-    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
-    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
-    // the session the visited link opened, until it is submitted
-    const stored = ctx.rowsRaw(LINK).find((l) => l._session === sid && l._submitted !== true);
-    const link = stored ? ctx.get(LINK, String(stored.id)) : undefined;
-    if (!stored || !link) return gone();
-    const sessionUrl = `${SESSIONS}${sid}`;
-    const account = ctx.get('account', String(link.account)) ?? {};
-    const kind = kindOf(account);
-    if (!kind) return unmodelled(account);
-    if (request.method === 'GET') return page(ctx, sessionUrl, link, kind);
-    const missing = currentlyDue(kind, form);
-    if (missing.length) return incomplete(ctx, sessionUrl, link, kind, form, missing);
-    await ctx.write(LINK, String(stored.id), { _submitted: true }, 'account_link.submitted');
-    await submit(ctx, link, kind, form, request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || '127.0.0.1');
-    return seeOther(String(link.return_url));
-  };
+export async function screen(ctx: HandlerContext): Promise<Response> {
+  const request = ctx.call.request;
+  const path = new URL(request.url).pathname;
+  const entry = /^\/setup\/(acctlink_[A-Za-z0-9_]+)\/?$/.exec(path);
+  const at = /^\/setup\/s\/(onbs_[A-Za-z0-9_]+)\/?$/.exec(path);
+  if (entry && request.method === 'GET') return visit(ctx, entry[1]!);
+  if (!at || (request.method !== 'GET' && request.method !== 'POST')) return notFound();
+  const sid = at[1]!;
+  const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+  // the session the visited link opened, until it is submitted
+  const stored = ctx.rowsRaw(LINK).find((l) => l._session === sid && l._submitted !== true);
+  const link = stored ? ctx.get(LINK, String(stored.id)) : undefined;
+  if (!stored || !link) return gone();
+  const sessionUrl = `${SESSIONS}${sid}`;
+  const account = ctx.get('account', String(link.account)) ?? {};
+  const kind = kindOf(account);
+  if (!kind) return unmodelled(account);
+  if (request.method === 'GET') return page(ctx, sessionUrl, link, kind);
+  const missing = currentlyDue(kind, form);
+  if (missing.length) return incomplete(ctx, sessionUrl, link, kind, form, missing);
+  await ctx.write(LINK, String(stored.id), { _submitted: true }, 'account_link.submitted');
+  await submit(ctx, link, kind, form, request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || '127.0.0.1');
+  return seeOther(String(link.return_url));
 }
+