@volter/twin-stripe 3.0.0 → 3.0.1

package/src/screens/connect-oauth.tsx

@@ -1,376 +0,0 @@
-// 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, ./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,
-//   "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" (../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 (./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).
-// - 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 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 type { HandlerContext } from '@volter/world-core';
-import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
-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';
-
-/** A code "expires in 5 minutes". */
-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. */
-const CONNECTIONS = OAUTH_CONNECTIONS;
-const SCOPES = ['read_write', 'read_only'] as const;
-type Scope = (typeof SCOPES)[number];
-
-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);
-
-// ── 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: 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');
-  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). */
-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: 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: [] };
-  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: 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: 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);
-}
-
-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({
-    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: HandlerContext, a: Authorize, p: Record<string, string>): Promise<Response> {
-  const account = await createAccount(ctx, p);
-  // 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(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 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;
-}
-
-/** 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. */
-/** 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: 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: nowUnix(ctx.occurredAt) }, operation: 'oauth_connection.revoke' } };
-  });
-  if (revoked) await applicationEvent(ctx, 'account.application.deauthorized', account);
-  return revoked;
-}
-
-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 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 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: 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);
-    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_${(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 === 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.');
-    }
-    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 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(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}`);
-  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(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 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; 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/semantics/disputes.ts

@@ -1,12 +0,0 @@
-// Stripe's disputes operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
-// handler contract's context, computing with the engine (../engine/).
-import type { HandlerContext } from '@volter/world-core';
-import type { Row } from '../engine/common.ts';
-import { asBool } from '../engine/stripe.ts';
-import { at, disputesDisputeMissing, keepEvidence, settleDisputeWon } from './shared.ts';
-
-export async function GetDisputesDispute(ctx: HandlerContext): Promise<Response> {
-  const d = ctx.get('dispute', at(ctx, 'dispute'));
-  return d ? ctx.reply(d) : disputesDisputeMissing(ctx, at(ctx, 'dispute'));
-}
-

package/src/semantics/invoiceitems.ts

@@ -1,59 +0,0 @@
-// Stripe's invoiceitems operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
-// handler contract's context, computing with the engine (../engine/).
-import type { HandlerContext } from '@volter/world-core';
-import type { Row } from '../engine/common.ts';
-import { INV, linesOf } from '../engine/invoices.ts';
-import { nowUnix } from '../engine/stripe.ts';
-import { at, created, fail, invoiceMissing, itemMissing, pricedItem, resyncDraftLines, writeLines } from './shared.ts';
-
-// an item is deleted only while its invoice is still editable
-export async function DeleteInvoiceitemsInvoiceitem(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'invoiceitem');
-  const it = ctx.get('invoiceitem', id);
-  if (!it) return itemMissing(ctx, id);
-  const onInvoice = typeof it.invoice === 'string' ? ctx.get(INV, it.invoice) : undefined;
-  if (onInvoice && onInvoice.status !== 'draft') return fail(ctx, 'You cannot delete an invoice item that is attached to an invoice that is no longer editable.', 400, 'invoice_not_editable');
-  await ctx.write('invoiceitem', id, { deleted: true }, 'invoiceitem.delete');
-  if (typeof it.invoice === 'string') await resyncDraftLines(ctx, it.invoice);
-  return ctx.reply({ id, object: 'invoiceitem', deleted: true });
-}
-
-export async function PostInvoiceitems(ctx: HandlerContext): Promise<Response> {
-  const params = ctx.params;
-  const now = Number(nowUnix(ctx.occurredAt));
-  const qty = Number(params.quantity) || 1;
-  // the served version names the price in `pricing[price]` ("The pricing information for the invoice item", the served
-  // spec); an older version sends `price`. It is kept as the item's price, which the answer renders as `pricing`
-  // (../engine/version.ts)
-  const { pricing: pricingParam, ...stored } = params;
-  const given = (pricingParam as Row | undefined)?.price;
-  const priceRef = typeof given === 'string' && given ? given : typeof params.price === 'string' ? params.price : '';
-  const priced = priceRef ? pricedItem(ctx, priceRef, qty) : undefined;
-  if (priced instanceof Response) return priced;
-  const resolvedAmount = priced?.amount;
-  let resolvedCurrency = priced?.currency;
-  // only a draft invoice takes new items
-  const invoiceRef = typeof params.invoice === 'string' ? params.invoice : '';
-  let target: Row | undefined;
-  if (invoiceRef) {
-    target = ctx.get(INV, invoiceRef);
-    if (!target) return invoiceMissing(ctx, invoiceRef);
-    if (target.status !== 'draft') return fail(ctx, `This invoice cannot have invoice items added because it has status ${String(target.status)}.`, 400, 'invoice_not_editable');
-    if (resolvedCurrency === undefined && typeof target.currency === 'string') resolvedCurrency = target.currency;
-  }
-  // an invoice item is dated by `date`, not `created`; its currency is the price's, else the invoice's
-  const item = await created(ctx, 'invoiceitem', { ...stored, ...(priceRef ? { price: priceRef } : {}) }, {
-    livemode: false, discountable: true, proration: false, quantity: qty, quantity_decimal: String(qty),
-    period: { start: now, end: now }, currency: resolvedCurrency ?? 'usd',
-    ...(resolvedAmount !== undefined ? { amount: resolvedAmount } : {}),
-  }, { timeField: 'date' });
-  if (target) {
-    await writeLines(ctx, invoiceRef, [...linesOf(target), {
-      id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(item.amount) || 0, currency: String(target.currency ?? item.currency ?? 'usd'),
-      quantity: qty, proration: false, invoice_item: item.id, price: item.price ?? null,
-      period: item.period ?? { start: now, end: now }, description: (item.description as string) ?? null,
-    }]);
-  }
-  return ctx.reply(item);
-}
-

package/src/semantics/setup_intents.ts

@@ -1,45 +0,0 @@
-// Stripe's setup_intents operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
-// handler contract's context, computing with the engine (../engine/).
-import type { HandlerContext } from '@volter/world-core';
-import { SI } from '../engine/setup-intents.ts';
-import { asBool, microdepositsNextAction, mintClientSecret, requiresMicrodeposits, verifyMicrodeposits } from '../engine/stripe.ts';
-import { at, attachable, attachPaymentMethod, confirmOnly, created, fail, load, mergeUpdate, methodFromData, microdepositsAsked, mintMandate, send } from './shared.ts';
-
-export async function PostSetupIntents(ctx: HandlerContext): Promise<Response> {
-  // mandate_data and return_url each "can only be used with `confirm=true`" (the served spec; shared.ts confirmOnly)
-  const unconfirmed = confirmOnly(ctx, ['mandate_data', 'return_url'], asBool(ctx.params.confirm));
-  if (unconfirmed) return unconfirmed;
-  // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
-  const id = typeof ctx.params.id === 'string' && ctx.params.id ? ctx.params.id : ctx.mint(SI);
-  // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
-  const hasMethod = typeof ctx.params.payment_method === 'string' && ctx.params.payment_method !== '';
-  if (hasMethod) ctx.legal(SI, 'status', 'PostSetupIntents', 'requires_payment_method', 'requires_confirmation', id);
-  return ctx.reply(
-    // allowed_payment_method_types in the served version names the methods (docs.stripe.com/api/setup_intents/create)
-    await created(ctx, SI, { ...ctx.params, ...(Array.isArray(ctx.params.allowed_payment_method_types) ? { payment_method_types: ctx.params.allowed_payment_method_types.map(String) } : {}), id }, {
-      status: hasMethod ? 'requires_confirmation' : 'requires_payment_method', usage: 'off_session', client_secret: mintClientSecret(id, await ctx.secret(`client-secret:${id}`)), payment_method_types: ['card'],
-      next_action: null, latest_attempt: null, last_setup_error: null, livemode: false,
-    }),
-  );
-}
-
-// a bank account that needs micro-deposit verification waits in requires_action; anything else succeeds. The confirm's
-// payment_method_data and mandate_data are instructions, not fields of the SetupIntent.
-export async function PostSetupIntentsIntentConfirm(ctx: HandlerContext): Promise<Response> {
-  const loaded = load(ctx, 'PostSetupIntentsIntentConfirm');
-  if ('answer' in loaded) return loaded.answer;
-  const si = loaded.si;
-  const id = String(si.id);
-  const given = ctx.params;
-  const { payment_method_data: data, mandate_data: _mandate, ...fields } = given;
-  const made = await methodFromData(ctx, data);
-  const pm = made ?? (typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : typeof si.payment_method === 'string' ? si.payment_method : undefined);
-  if (si.status !== 'requires_action' && (requiresMicrodeposits(ctx.params, si) || microdepositsAsked(ctx, ctx.params, si, pm))) {
-    return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(pm ? { payment_method: pm } : {}), status: 'requires_action', next_action: microdepositsNextAction() }), 'setup_intent.requires_action'));
-  }
-  // a setup for a customer saves the method to them (docs.stripe.com/payments/save-and-reuse): its payment method is attached
-  const customer = typeof si.customer === 'string' ? si.customer : undefined;
-  const saved = pm && customer && attachable(ctx, pm) && ctx.get('payment_method', pm)?.customer !== customer ? String((await attachPaymentMethod(ctx, pm, customer)).id) : pm;
-  return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(saved ? { payment_method: saved } : {}), status: 'succeeded' }), 'setup_intent.confirm'));
-}
-

package/src/semantics/subscription_items.ts

@@ -1,54 +0,0 @@
-// Stripe's subscription_items operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
-// handler contract's context, computing with the engine (../engine/).
-import type { HandlerContext } from '@volter/world-core';
-import type { Row } from '../engine/common.ts';
-import { subscriptionItemPrice } from '../engine/stripe.ts';
-import { ITEM_ATTRIBUTES, SUB } from '../engine/subscriptions.ts';
-import { at, created, fail, finder, list, newest, subMissing, subscriptionsItemMissing, syncItems, withPeriod } from './shared.ts';
-
-export async function DeleteSubscriptionItemsItem(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'item');
-  const si = ctx.get('subscription_item', id);
-  if (!si) return subscriptionsItemMissing(ctx, id);
-  await ctx.write('subscription_item', id, { deleted: true }, 'subscription_item.delete');
-  await syncItems(ctx, String(si.subscription));
-  return ctx.reply({ id, object: 'subscription_item', deleted: true });
-}
-
-export async function GetSubscriptionItemsItem(ctx: HandlerContext): Promise<Response> {
-  const si = ctx.get('subscription_item', at(ctx, 'item'));
-  return si ? ctx.reply(withPeriod(ctx, si)) : subscriptionsItemMissing(ctx, at(ctx, 'item'));
-}
-
-export async function PostSubscriptionItems(ctx: HandlerContext): Promise<Response> {
-  const params = ctx.params;
-  const subId = typeof params.subscription === 'string' ? params.subscription : '';
-  if (!subId) return fail(ctx, 'Missing required param: subscription.', 400, 'parameter_missing');
-  if (!ctx.get(SUB, subId)) return subMissing(ctx, subId);
-  const priceRef = typeof params.price === 'string' ? params.price : '';
-  if (!priceRef && !(params.price_data && typeof params.price_data === 'object')) return fail(ctx, 'Missing required param: price.', 400, 'parameter_missing');
-  if (priceRef && !ctx.get('price', priceRef)) return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
-  const quantity = params.quantity !== undefined ? Math.max(0, Math.trunc(Number(params.quantity) || 0)) : 1;
-  // "metadata: Set of key-value pairs that you can attach to an object" (docs.stripe.com/api/subscription_items/create)
-  const metadata = params.metadata && typeof params.metadata === 'object' ? { metadata: params.metadata } : {};
-  const body = await created(ctx, 'subscription_item', { subscription: subId, ...(priceRef ? subscriptionItemPrice(priceRef, finder(ctx)) : { price: null, plan: null }), quantity, ...metadata }, { livemode: false, metadata: {} });
-  await syncItems(ctx, subId);
-  return ctx.reply(withPeriod(ctx, body));
-}
-
-export async function PostSubscriptionItemsItem(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'item');
-  const si = ctx.get('subscription_item', id);
-  if (!si) return subscriptionsItemMissing(ctx, id);
-  // only the item's own attributes are kept; the update's instructions (off_session, payment_behavior, price_data,
-  // proration_behavior, proration_date) are not attributes of the Subscription Item object
-  // (docs.stripe.com/api/subscription_items/object lists none of them)
-  const fields: Row = Object.fromEntries(Object.entries(ctx.params).filter(([k]) => ITEM_ATTRIBUTES.has(k)));
-  if (ctx.params.quantity !== undefined) fields.quantity = Math.max(0, Math.trunc(Number(ctx.params.quantity) || 0));
-  if (typeof ctx.params.price === 'string' && ctx.params.price && !ctx.get('price', ctx.params.price)) return fail(ctx, `No such price: '${ctx.params.price}'`, 400, 'resource_missing');
-  // the item carries its Price and plan, as the subscription's own items do (subscriptionItemPrice)
-  if (typeof ctx.params.price === 'string' && ctx.params.price) Object.assign(fields, subscriptionItemPrice(ctx.params.price, finder(ctx)));
-  const out = await ctx.write('subscription_item', id, fields, 'subscription_item.update');
-  await syncItems(ctx, String(si.subscription));
-  return ctx.reply(withPeriod(ctx, out));
-}

package/src/semantics/subscription_schedules.ts

@@ -1,66 +0,0 @@
-// Stripe's subscription_schedules operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
-// handler contract's context, computing with the engine (../engine/).
-import type { HandlerContext } from '@volter/world-core';
-import type { Row } from '../engine/common.ts';
-import { buildSubscriptionItemsList, nowUnix } from '../engine/stripe.ts';
-import { SS } from '../engine/subscription-schedules.ts';
-import { at, created, end, fail, finder, phasesOf, scheduleMissing, storeItems } from './shared.ts';
-
-export async function GetSubscriptionSchedulesSchedule(ctx: HandlerContext): Promise<Response> {
-  const s = ctx.get(SS, at(ctx, 'schedule'));
-  return s ? ctx.reply(s) : scheduleMissing(ctx, at(ctx, 'schedule'));
-}
-
-// a schedule starts from a customer or from an existing subscription
-export async function PostSubscriptionSchedules(ctx: HandlerContext): Promise<Response> {
-  const params = ctx.params;
-  const customer = typeof params.customer === 'string' ? params.customer : '';
-  const fromSub = typeof params.from_subscription === 'string' ? params.from_subscription : '';
-  if (!customer && !fromSub) return fail(ctx, 'Missing required param: customer (or from_subscription).', 400, 'parameter_missing');
-  if (customer && !ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-  if (fromSub && !ctx.get('subscription', fromSub)) return fail(ctx, `No such subscription: '${fromSub}'`, 404, 'resource_missing');
-  // start_date is an instruction ("now" or when), not a field of the schedule
-  const start = params.start_date !== undefined && params.start_date !== 'now' ? Number(params.start_date) : Number(nowUnix(ctx.occurredAt));
-  const phases = phasesOf(ctx, Array.isArray(params.phases) ? (params.phases as Row[]) : [], start);
-  const { phases: _p, start_date: _s, default_settings: givenDefaults, ...rest } = params;
-  const defaults = givenDefaults && typeof givenDefaults === 'object' ? (givenDefaults as Row) : {};
-  const schedId = ctx.mint(SS);
-  // a schedule for a customer whose first phase starts now starts its subscription at once, on that phase's items
-  // (docs.stripe.com/billing/subscriptions/subscription-schedules#managing)
-  let subscription = fromSub || null;
-  if (!fromSub && phases.length) {
-    const now = Number(nowUnix(ctx.occurredAt));
-    const subId = ctx.mint('subscription');
-    const items = buildSubscriptionItemsList(phases[0]!.items as Row[], subId, now, finder(ctx));
-    await created(ctx, 'subscription', { customer, id: subId }, {
-      status: 'active', livemode: false, currency: 'usd', collection_method: String((params.default_settings as Row | undefined)?.collection_method ?? 'charge_automatically'),
-      cancel_at_period_end: false, start_date: now, billing_cycle_anchor: now, metadata: {}, discounts: [], billing_schedules: [],
-      trial_start: null, trial_end: null, current_period_start: now, current_period_end: phases[0]!.end_date, items, schedule: schedId,
-      automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' }, invoice_settings: { issuer: { type: 'self' } },
-    });
-    await storeItems(ctx, subId, (items.data as Row[]) ?? []);
-    subscription = subId;
-  }
-  return ctx.reply(
-    await created(ctx, SS, { ...rest, id: schedId }, {
-      status: 'active', livemode: false, phases, current_phase: phases.length ? { start_date: phases[0]!.start_date, end_date: phases[0]!.end_date } : null,
-      subscription, released_subscription: null, released_at: null,
-      canceled_at: null, completed_at: null, end_behavior: (params.end_behavior as string) ?? 'release',
-      renewal_interval: null, metadata: {}, billing_mode: { type: 'classic' },
-      // "billing_cycle_anchor: Possible values are phase_start or automatic" and invoice_settings are required (the
-      // served spec's default settings); the rest answer what the request set, else null
-      default_settings: {
-        application_fee_percent: defaults.application_fee_percent ?? null, automatic_tax: { enabled: false, liability: null, disabled_reason: null },
-        billing_cycle_anchor: typeof defaults.billing_cycle_anchor === 'string' ? defaults.billing_cycle_anchor : 'automatic', billing_thresholds: null,
-        collection_method: typeof defaults.collection_method === 'string' ? defaults.collection_method : 'charge_automatically', default_payment_method: defaults.default_payment_method ?? null,
-        description: defaults.description ?? null, invoice_settings: { account_tax_ids: null, days_until_due: null, issuer: { type: 'self' } }, on_behalf_of: null, transfer_data: null,
-      },
-      // a schedule made from a subscription is its customer's
-      customer: customer || String(ctx.get('subscription', fromSub)?.customer ?? ''),
-    }),
-  );
-}
-
-export async function PostSubscriptionSchedulesScheduleRelease(ctx: HandlerContext): Promise<Response> {
-  return (end('release'))(ctx);
-}