@volter/twin-stripe 2.0.0 → 2.0.2

package/src/stripe-conformance.ts

@@ -15,6 +15,7 @@ import { twinResources } from '@volter/world-core';
 import { specConformance } from '@volter/world-tooling';
 import type { TwinResource } from '@volter/world-core';
 import { OBJECT_NAME } from './stripe-twin.ts';
+import { INCLUDABLE_FIELDS, render } from './stripe-version.ts';
 
 type JsonSchema = specConformance.JsonSchema;
 type KnownDeviation = specConformance.KnownDeviation;
@@ -43,6 +44,8 @@ export type StripeConformanceReport = {
   fieldsChecked: number;
   violations: StripeViolation[];
   knownIgnored: number;
+  /** fields checked per twin resource type: a type the check skipped (no schema) is absent */
+  fieldsByType: Record<string, number>;
 };
 
 const isTwinExtra = (k: string): boolean => k.startsWith('_');
@@ -51,11 +54,17 @@ const fixturePath = (name: string): string => new URL(`../test-fixtures/${name}`
 // The emitted REST body == the twin's view(): strip internal fields, add object + id.
 // Mirrors stripe-twin.ts view(): a vendor `type` field collides with the kernel
 // discriminator, so it is stored under `_stripe_type` and restored to `type` on emit.
+// ...and then rendered in the version a caller that pins none is served (stripe-version.ts render): since 24e757f60
+// the twin KEEPS objects in the 2024-06-20 shape its rules were written against and answers them in the served
+// version's (basil onward moved an invoice's subscription and charge, a charge's source, ...), so the stored row is
+// not what any client receives. The schemas are projected from a post-basil spec, so the answer is what is checked.
 function emitted(r: TwinResource): Record<string, unknown> {
   const { type, updatedAt, _stripe_type, ...rest } = r as TwinResource & { _stripe_type?: unknown };
   const out: Record<string, unknown> = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
   if (_stripe_type !== undefined) out.type = _stripe_type;
-  return out;
+  // expanded: an includable field (a session's line_items, a charge's refunds) is answered only when a request asks, and
+  // the check reads the answer that carries it so its shape is still checked
+  return render(out, undefined, INCLUDABLE_FIELDS) as Record<string, unknown>;
 }
 
 /** Load the vendored per-object Stripe JSON Schemas (type+required+enum from OpenAPI). */
@@ -79,6 +88,7 @@ export function checkStripeConformance(schemas: StripeSchemas, opts: { root?: st
   const violations: StripeViolation[] = [];
   let fieldsChecked = 0;
   let knownIgnored = 0;
+  const fieldsByType: Record<string, number> = {};
   for (const r of resources) {
     const objectName = TYPE_TO_OBJECT[r.type];
     if (!objectName) continue;
@@ -86,10 +96,11 @@ export function checkStripeConformance(schemas: StripeSchemas, opts: { root?: st
     if (!schema) continue;
     const rep = specConformance.checkSpecConformance(emitted(r), schema, { exemptKey: isTwinExtra, known: opts.known ?? [] });
     fieldsChecked += rep.fieldsChecked;
+    fieldsByType[r.type] = (fieldsByType[r.type] ?? 0) + rep.fieldsChecked;
     knownIgnored += rep.knownIgnored;
     for (const v of rep.violations) violations.push({ ...v, object: objectName, id: r.id });
   }
-  return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored };
+  return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored, fieldsByType };
 }
 
 export type StripeCoverageReport = specConformance.SpecCoverageReport & { object: string };

package/src/stripe-emit.ts

@@ -11,7 +11,7 @@
 // DELIVER does not transition state: it snapshots the subject AS IT IS in the twin and fires
 // the named event about it. Completing a checkout session / paying an invoice is the twin
 // API's job; this verb answers "my app's webhook handler needs to SEE the event, now."
-import { projectResources, type EmitEndpoint, type EmittableEvent, type SynthesizedDelivery, type TwinEmitter } from '@volter/world-core';
+import { projectResources, worldNow, type EmitEndpoint, type EmittableEvent, type SynthesizedDelivery, type TwinEmitter } from '@volter/world-core';
 import { OBJECT_NAME, PLATFORM_ACCOUNT_ID, TWIN_API_VERSION, view } from './stripe-twin.ts';
 import { STRIPE_WEBHOOK_FALLBACK_SECRET, generateTestHeaderString } from './stripe-events.ts';
 import { render } from './stripe-version.ts';
@@ -127,7 +127,7 @@ export const stripeEmitter: TwinEmitter = {
     const endpointRow = liveEndpointRows(root).find((w) => String(w.id) === endpoint.id || String(w.url) === endpoint.url);
     const secret = typeof endpointRow?.secret === 'string' && endpointRow.secret ? endpointRow.secret : STRIPE_WEBHOOK_FALLBACK_SECRET;
 
-    const created = occurredAt ? Math.floor(Date.parse(occurredAt) / 1000) : Math.floor(Date.now() / 1000);
+    const created = occurredAt ? Math.floor(Date.parse(occurredAt) / 1000) : Math.floor(Date.parse(worldNow()) / 1000);
     // a connected account's object is its event's, as the write path scopes it (stripe-twin.ts afterStripeWrite): the
     // account itself, or a row kept on its books (`_account`). "Each event for a connected account contains a top-level
     // `account` property that identifies the connected account" (docs.stripe.com/connect/webhooks).

package/src/stripe-events.ts

@@ -1,4 +1,5 @@
-import { nodeBuiltin } from '@volter/world-core';
+import { nodeBuiltin, worldNow, deliveryTraceHeaders } from '@volter/world-core';
+import { appDestination, appFetch } from '@volter/world-core/app-route';
 import { worldEgressRefusal } from '@volter/world-core/network-policy';
 import vendorEvents from './generated/events.gen.json' with { type: 'json' };
 import { render } from './stripe-version.ts';
@@ -51,7 +52,8 @@ export function computeStripeSignature(payload: string, secret: string, timestam
 
 /** Build a `Stripe-Signature` header value for `payload` (mirrors generateTestHeaderString). */
 export function generateTestHeaderString(opts: { payload: string; secret: string; timestamp?: number; scheme?: string }): string {
-  const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1000);
+  // signed at the World's time, as its application reads the time (a moved World clock; the app keeps it too)
+  const timestamp = opts.timestamp ?? Math.floor(Date.parse(worldNow()) / 1000);
   const scheme = opts.scheme ?? 'v1';
   const signature = computeStripeSignature(opts.payload, opts.secret, timestamp);
   return `t=${timestamp},${scheme}=${signature}`;
@@ -101,7 +103,7 @@ export function constructEvent(payload: string, header: string, secret: string,
     throw new StripeSignatureVerificationError('No signatures found matching the expected signature for payload.');
   }
   if (opts.tolerance !== undefined) {
-    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (now - timestamp > opts.tolerance) {
       throw new StripeSignatureVerificationError('Timestamp outside the tolerance zone');
     }
@@ -259,8 +261,9 @@ const httpDelivery: StripeEventDelivery = async (url, event, endpointSecret) =>
   // the event as its API version renders it (stripe-version.ts)
   const payload = JSON.stringify(render(event, (event as { api_version?: string }).api_version));
   const secret = endpointSecret ?? secrets.get(url) ?? STRIPE_WEBHOOK_FALLBACK_SECRET;
-  // the World's egress rule: an endpoint it refuses is not delivered to, and says so
-  const refusal = worldEgressRefusal(url);
+  // the World's egress rule: an endpoint it refuses is not delivered to, and says so; the application's own hostnames
+  // reach it inside the World
+  const refusal = appDestination(url) ? null : worldEgressRefusal(url);
   if (refusal !== null) console.error(`[twin:stripe] webhook delivery DROPPED — ${event.type} ${event.id} -> ${url}: ${refusal}`);
   return refusal !== null ? undefined : postEvent(url, event, payload, secret);
 };
@@ -271,7 +274,7 @@ async function postEvent(url: string, event: StripeEvent, payload: string, secre
   for (let attempt = 1; attempt <= DELIVERY_ATTEMPTS; attempt += 1) {
     try {
       const header = generateTestHeaderString({ payload, secret });
-      await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header }, body: payload });
+      await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() }, body: payload });
       return;
     } catch (error) {
       last = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
@@ -325,16 +328,17 @@ async function httpAuthRequestDelivery(url: string, event: StripeEvent, secret:
   // the event as its API version renders it (stripe-version.ts)
   const payload = JSON.stringify(render(event, (event as { api_version?: string }).api_version));
   const header = generateTestHeaderString({ payload, secret });
-  // the World's egress rule: a refused endpoint is an unreachable one (the caller's timeout fallback)
-  const refusal = worldEgressRefusal(url);
+  // the World's egress rule: a refused endpoint is an unreachable one (the caller's timeout fallback); the
+  // application's own hostnames reach it inside the World
+  const refusal = appDestination(url) ? null : worldEgressRefusal(url);
   return refusal !== null ? Promise.reject(new Error(refusal)) : postAuthRequest(url, payload, header);
 }
 
 /** The HTTP POST of a real-time authorization request, cut off at the window, and the endpoint's answer. */
 async function postAuthRequest(url: string, payload: string, header: string): Promise<StripeWebhookEndpointResponse> {
-  const res = await fetch(url, {
+  const res = await appFetch(url, {
     method: 'POST',
-    headers: { 'content-type': 'application/json', 'stripe-signature': header },
+    headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() },
     body: payload,
     signal: AbortSignal.timeout(STRIPE_REALTIME_AUTH_TIMEOUT_MS),
   });

package/src/stripe-mirror-ui.ts

@@ -4,12 +4,12 @@
 // twin internals; the client reads and writes only through Stripe's API (`/v1/...`, client/dashboard-api.ts),
 // so it renders a twin or a real account's test data unchanged, pointed at any origin by configuration.
 import { readFile } from 'node:fs/promises';
-import { bundleClient, fileResponse } from '@volter/world-core';
+import { bundleClient, fileResponse, filePathOf } from '@volter/world-core';
 import { serveHttp } from '@volter/world-core';
 import { createStripeTwinFetch } from './stripe-server.ts';
 
-const CLIENT_ENTRY = () => new URL('../client/stripe-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-const CLIENT_CSS = () => new URL('../client/stripe-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_ENTRY = () => filePathOf(new URL('../client/stripe-mirror.tsx', import.meta.url));  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => filePathOf(new URL('../client/stripe-mirror.css', import.meta.url));  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
 
 // ---------------------------------------------------------------------------
 // Pure, dependency-free render/format/resolution helpers.

package/src/stripe-server.ts

@@ -7,7 +7,7 @@
 // The surface is a plain `fetch` (`createStripeTwinFetch`) and the SERVER is one line of
 // `Bun.serve` around it — see that factory's docstring for why (a serverless entry has no
 // port to bind, so it mounts the fetch in-process).
-import { bindSemantics, coreFor, createDerivedFetch, crossCutting, readParams, semanticsContext, serveHttp, vendorError, type DerivedCall, type DerivedFetch } from '@volter/world-core';
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, derivedRequestScopes, readParams, runAsVendorMove, runWithRequestTrace, semanticsContext, serveHttp, vendorError, type DerivedCall, type DerivedFetch } from '@volter/world-core';
 import { stripeCheckoutFlow } from './screens/checkout.tsx';
 import { stripeJs } from './stripe-js.ts';
 import { stripeFinancialConnectionsFlow } from './screens/financial-connections.tsx';
@@ -15,6 +15,8 @@ import { stripeIdentityFlow } from './screens/identity.tsx';
 import { stripeOnboardingFlow } from './screens/onboarding.tsx';
 import { stripePortalFlow } from './screens/portal.tsx';
 import { stripePublicDetailsFlow } from './screens/public-details.tsx';
+import { connectionRevoked, oauthKeyAccount, redactKey, stripeConnectOAuthFlow } from './screens/connect-oauth.tsx';
+import { stripeConnectSettingsFlow } from './screens/connect-settings.tsx';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest } from './manifest.ts';
 import { appsSecrets } from './semantics/apps-secrets.ts';
@@ -112,6 +114,34 @@ async function publishableKeyRefused(call: DerivedCall, scope: { root?: string;
   return ctx.get(scoped.type, id)?.client_secret === secret ? undefined : wrongClientSecret(scoped, id);
 }
 
+// ── an account whose OAuth connection was revoked ──
+// "After revocation, the account can't be accessed by your platform in the Dashboard or through the API"
+// (docs.stripe.com/connect/oauth-reference, deauthorize; so too a connection revoked by a reused code). A call made as it
+// (the Stripe-Account header) or naming it (/v1/accounts/{account}…) is refused with the error Stripe documents for a
+// Stripe-Account the key cannot use: "account_invalid | The account ID provided as a value for the Stripe-Account header
+// is invalid" (docs.stripe.com/error-codes), as 403, "The API key doesn't have permissions to perform the request"
+// (docs.stripe.com/api/errors). Where the documentation stops and the twin decides: the message's wording; an account
+// the platform created itself, or never connected by OAuth, is not affected.
+async function revokedAccountRefused(call: DerivedCall, scope: { root?: string; clock?: () => string }): Promise<Response | undefined> {
+  const named = [call.request.headers.get('stripe-account') ?? undefined, call.operation.path.startsWith('/v1/accounts/{account}') ? call.params.account : undefined].filter((a): a is string => !!a);
+  if (!named.length) return undefined;
+  const ctx = await semanticsContext(manifest, new Request(call.request.url), call.operation, scope); // the rows only: no body read
+  const revoked = named.find((a) => connectionRevoked(ctx, a));
+  if (!revoked) return undefined;
+  const key = requestKey(call.request);
+  return vendorError(manifest, { status: 403, code: 'account_invalid', message: `The provided key '${redactKey(key)}' does not have access to account '${revoked}' (or that account does not exist). Application access may have been revoked.` });
+}
+
+/** The API key a request carries: Bearer, or Basic's user (`curl -u sk_…:`, docs.stripe.com/api/authentication). */
+function requestKey(request: Request): string {
+  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 { return atob(basic).split(':')[0] ?? ''; } catch { return ''; } }
+  return '';
+}
+
 /** A client-secret call whose secret is not the object's: answered as though the key could not see it (the twin's
  *  decision, above). */
 function wrongClientSecret(scoped: { type: string; param: string }, id: string): Response {
@@ -151,14 +181,16 @@ export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch
     core,
     // after the credential and the version, a publishable key is held to the client-side calls, then a request's
     // parameters are checked against the operation's (stripe-params.ts)
-    around: (call, next) => guard(call, async () => (await publishableKeyRefused(call, scope)) ?? (await refuseParameters(call)) ?? next()),
+    around: (call, next) => guard(call, async () => (await publishableKeyRefused(call, scope)) ?? (await revokedAccountRefused(call, scope)) ?? (await refuseParameters(call)) ?? next()),
     gap: (request) => vendorError(manifest, { status: 404, message: `Unrecognized request URL (${request.method}: ${new URL(request.url).pathname}).` }),
   });
   // the hosted flows sit beside the API: checkout.stripe.com's payment page, billing.stripe.com's customer portal,
-  // connect.stripe.com's onboarding, verify.stripe.com's identity check and the bank-linking flow Stripe.js opens, and
-  // the Dashboard's Public details page (dashboard.stripe.com/settings/public, the platform's customer-facing name);
+  // connect.stripe.com's onboarding and its OAuth endpoints (screens/connect-oauth.tsx), verify.stripe.com's identity
+  // check and the bank-linking flow Stripe.js opens, and the Dashboard's Public details page
+  // (dashboard.stripe.com/settings/public, the platform's customer-facing name) and Connect OAuth settings
+  // (dashboard.stripe.com/settings/connect/onboarding-options/oauth: the client_id, OAuth on, the redirect URIs);
   // a read-only twin takes no payments and moves nothing
-  const flows = [stripeCheckoutFlow(scope), stripePortalFlow(scope), stripeOnboardingFlow(scope), stripeIdentityFlow(scope), stripeFinancialConnectionsFlow(scope), stripePublicDetailsFlow(scope)];
+  const flows = [stripeCheckoutFlow(scope), stripePortalFlow(scope), stripeOnboardingFlow(scope), stripeIdentityFlow(scope), stripeFinancialConnectionsFlow(scope), stripePublicDetailsFlow(scope), stripeConnectOAuthFlow(scope), stripeConnectSettingsFlow(scope)];
   // the twin's own doors sit in front of the API: discovery, and what stands in for an act Stripe's API
   // does not have (stripe-twin.ts)
   // GET /twin: what this twin is (not Stripe's; a host reads it)
@@ -183,25 +215,28 @@ export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch
   // later: semantics/renewals.ts; each account's automatic payouts: semantics/balance.ts) are caught up to the World's clock before anything is answered, so every door
   // (the API, the hosted pages) reads the account as it stands now
   const billingClock = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'GetSubscriptions')!;
+  // time's moves are Stripe's own, not the caller's: they land under a read-only request too (runAsVendorMove)
   const catchUp = async (request: Request): Promise<void> => {
     if (readOnly) return;
-    const ctx = await semanticsContext(manifest, new Request(request.url), billingClock, scope);
-    // a test clock advanced by the last request has reached its time (semantics/test-clocks.ts)
-    await finishClockAdvances(ctx);
-    await advanceBilling(ctx);
-    // a submitted bank debit settles (in test mode at once) before anything is answered (semantics/payment-intents.ts)
-    await settleBankDebits(ctx);
-    // a coupon past its redeem_by is no longer valid (semantics/coupons.ts)
-    await lapseCoupons(ctx);
-    // a top-up's funds arrive five days after it is made (semantics/terminal.ts)
-    await settleTopups(ctx);
-    // a report run completes (semantics/platform.ts)
-    await finishReportRuns(ctx);
-    // a real-time authorization request no one answered is decided when its window ends (semantics/issuing.ts)
-    await lapseRealtimeRequests(ctx);
-    // a refund held for want of balance is made when funds cover it, before any payout takes them (semantics/refunds.ts)
-    await settleHeldRefunds(ctx);
-    await advancePayouts(ctx);
+    await runAsVendorMove(async () => {
+      const ctx = await semanticsContext(manifest, new Request(request.url), billingClock, scope);
+      // a test clock advanced by the last request has reached its time (semantics/test-clocks.ts)
+      await finishClockAdvances(ctx);
+      await advanceBilling(ctx);
+      // a submitted bank debit settles (in test mode at once) before anything is answered (semantics/payment-intents.ts)
+      await settleBankDebits(ctx);
+      // a coupon past its redeem_by is no longer valid (semantics/coupons.ts)
+      await lapseCoupons(ctx);
+      // a top-up's funds arrive five days after it is made (semantics/terminal.ts)
+      await settleTopups(ctx);
+      // a report run completes (semantics/platform.ts)
+      await finishReportRuns(ctx);
+      // a real-time authorization request no one answered is decided when its window ends (semantics/issuing.ts)
+      await lapseRealtimeRequests(ctx);
+      // a refund held for want of balance is made when funds cover it, before any payout takes them (semantics/refunds.ts)
+      await settleHeldRefunds(ctx);
+      await advancePayouts(ctx);
+    });
   };
   // Time's EVENTS, sent on the vendor's clock through a twin-only drain door, as the qstash and vercel twins send
   // theirs (a caller — a runner's drainer — drives each move). POST /_twin/drain catches time up as every request
@@ -238,8 +273,31 @@ export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch
     if (library) return library;
     await catchUp(request);
     if (!readOnly) for (const flow of flows) { const page = await flow(request); if (page) return page; }
+    const acting = await actingAsOAuthKey(request);
+    if (acting instanceof Response) return acting;
     // an update's metadata is merged into what the object holds before the handler or the core serves it (mergeMetadata)
-    return derived(readOnly ? request : await mergeMetadata(request, (op) => !(op.id in handlerMap) && core.owns(op), scope));
+    return derived(readOnly ? acting : await mergeMetadata(acting, (op) => !(op.id in handlerMap) && core.owns(op), scope));
+  };
+  // A connected account's OAuth keys (screens/connect-oauth.tsx): the token endpoint's access_token is "Use the
+  // Stripe-Account header with your platform's secret key (that can make requests on behalf of this Stripe account)" and
+  // its stripe_publishable_key the same with the publishable key (docs.stripe.com/connect/oauth-reference): a request made
+  // with one acts as that account, as a request with the Stripe-Account header does. A key no live connection holds (its
+  // connection revoked, or replaced by a refresh: "Any existing access token with the same scope and mode ... is
+  // revoked") is Stripe's unknown key, 401 "Invalid API Key provided" (docs.stripe.com/api/authentication, docs.stripe.com
+  // /error-codes); one sent with a Stripe-Account header naming another account cannot act as it (account_invalid).
+  // Where the documentation stops and the twin decides: the messages' wording; a read_only key is not held to reads
+  // (manifest todo stripe.connect.oauth_scope_enforcement).
+  const actingAsOAuthKey = async (request: Request): Promise<Request | Response> => {
+    const key = requestKey(request);
+    if (!/^(sk|pk)_test_oauth_/.test(key)) return request;
+    const held = oauthKeyAccount(await semanticsContext(manifest, new Request(request.url), billingClock, scope), key);
+    if (!held) return vendorError(manifest, { status: 401, message: `Invalid API Key provided: ${redactKey(key)}` });
+    const named = request.headers.get('stripe-account');
+    if (named && named !== held.account) return vendorError(manifest, { status: 403, code: 'account_invalid', message: `The provided key '${redactKey(key)}' does not have access to account '${named}' (or that account does not exist). Application access may have been revoked.` });
+    const headers = new Headers(request.headers);
+    headers.set('stripe-account', held.account);
+    const bodied = request.method !== 'GET' && request.method !== 'HEAD';
+    return new Request(request.url, { method: request.method, headers, ...(bodied ? { body: await request.arrayBuffer() } : {}) });
   };
   // every answer in the shape of the API version the caller is served (stripe-version.ts)
   const rendered = async (request: Request): Promise<Response> => {
@@ -254,7 +312,10 @@ export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch
     const answered = creates ? body : withoutEndpointSecret(body);
     return new Response(JSON.stringify(servesCurrent(pinned) ? render(answered, pinned, await expand) : answered), { status: res.status, statusText: res.statusText, headers: res.headers });
   };
-  return Object.assign(rendered, { owners: derived.owners });
+  // the request's W3C trace context scopes every door (the API, the hosted flows, the drain): their writes record it and
+  // the webhooks they cause continue it (world-core trace-context)
+  // a read-only request (x-volter-read-only) writes nothing, answered with Stripe's read-only error
+  return derivedRequestScopes(manifest, Object.assign((request: Request) => runWithRequestTrace(request, () => rendered(request)), { owners: derived.owners }));
 }
 
 export async function createStripeTwinServer(options: StripeTwinOptions): Promise<{ port: number; stop: () => void }> {

package/src/stripe-shared.ts

@@ -13,6 +13,9 @@ export type StripeRow = Record<string, any>;
  *  Dashboard to differentiate between accounts", the same object page), and with neither to "Twin Inc.", the name the
  *  Dashboard mirror has always given the World's own account. */
 export const PLATFORM_DEFAULT_NAME = 'Twin Inc.';
+/** The bookkeeping type of a connected account's Connect OAuth connection (screens/connect-oauth.tsx): one row per
+ *  account, `revoked: true` once deauthorized or its code reused. Read by the account list and the event path too. */
+export const OAUTH_CONNECTIONS = '_oauth_connection';
 export function publicBusinessName(account: StripeRow | undefined): string {
   const named = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v : undefined);
   return named(account?.business_profile?.name) ?? named(account?.settings?.dashboard?.display_name) ?? PLATFORM_DEFAULT_NAME;

package/src/stripe-twin.ts

@@ -15,6 +15,7 @@ import { emitStripeEvent, eventTypeFor, type StripeWebhookTarget } from './strip
 import { SERVED_VERSION } from './stripe-version.ts';
 import { planOf } from './semantics/plans.ts';
 import { platformAccountDefault } from './semantics/connect.ts';
+import { OAUTH_CONNECTIONS } from './stripe-shared.ts';
 
 const SERVICE = 'stripe';
 
@@ -483,6 +484,10 @@ export async function afterStripeWrite(type: string, op: string, out: Record<str
   const id = eventType ? nextStripeEventId(root) : undefined;
   // stored before it is delivered: a consumer that looks its webhook's event up finds it
   if (eventType) await persistStripeEvent(eventType, object, root, occurredAt, apiVersion, account, id);
+  // a connected account whose OAuth connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/
+  // oauth-reference): its events (a payout time makes, a renewal) are its own and no longer reach the platform's Connect
+  // endpoints, except the account.application.deauthorized that says so (screens/connect-oauth.tsx)
+  if (account && eventType !== 'account.application.deauthorized' && rows(OAUTH_CONNECTIONS, root).some((c) => (c as Record<string, unknown>).id === account && (c as Record<string, unknown>).revoked === true)) return;
   await emitStripeEvent(op, object, { occurredAt: occurredAt ?? '1970-01-01T00:00:00.000Z', endpoints: webhookTargets(root), ...(account ? { account } : {}), ...(id ? { id } : {}) });
 }
 
@@ -1250,7 +1255,7 @@ export async function handleStripeTwinRequest(req: StripeRequest): Promise<Strip
   // a GET carries its parameters in the query; a caller that handed them as a body keeps them
   let path = req.path.startsWith('/') ? req.path : `/${req.path}`;
   if ((method === 'GET' || method === 'HEAD') && req.body) path += (path.includes('?') ? '&' : '?') + req.body;
-  const response = await twin(new Request(`https://api.stripe.com${path}`, { method, headers, ...(method !== 'GET' && method !== 'HEAD' && req.body ? { body: req.body } : {}) }));
+  const response = await twin(new Request(`http://stripe.test${path}`, { method, headers, ...(method !== 'GET' && method !== 'HEAD' && req.body ? { body: req.body } : {}) }));
   const text = await response.text();
   return { status: response.status, body: text ? JSON.parse(text) : null };
 }

package/src/stripe-version.ts

@@ -228,6 +228,9 @@ const INCLUDABLE: Record<string, string[]> = {
   invoice: ['confirmation_secret'],
 };
 
+/** Every includable field name, as `expand` paths on a top-level object: what a check of an object's FULL answer expands. */
+export const INCLUDABLE_FIELDS: string[] = [...new Set(Object.values(INCLUDABLE).flat())];
+
 /** The `expand[]` paths a request names, in its query or its body (JSON or form). */
 export async function expandOf(request: Request): Promise<string[]> {
   const url = new URL(request.url);

package/test-fixtures/stripe-known-deviations.json

@@ -100,6 +100,11 @@
    "path": "price",
    "kind": "extra",
    "reason": "PEAK-3102 round 2: POST /v1/invoiceitems now stores the caller-supplied `price` id on the invoiceitem (needed to resolve amount = unit_amount * quantity for PeakHealth's catalog-product order path). Real Stripe replaced the top-level InvoiceItem.price field with a `pricing.price_details` object in a later API-version migration — stripe-schemas.json (LATEST published shape) reflects the post-migration object and has no price property, hence 'extra' under the harness's single-snapshot schema, same mechanism as current_period_start/_end and payment_intent above. This twin's default-served TWIN_API_VERSION ('2024-06-20') pre-dates that migration, where real Stripe DOES emit invoiceitem.price top-level, so emitting it here is faithful to what this twin actually serves by default."
+  },
+  {
+   "path": "net_amount",
+   "kind": "type",
+   "reason": "invoiceitem.net_amount is typed a non-nullable integer in the served spec, but its own description says \"This field is `null` for `discountable=true` items\" (served spec, invoiceitem.net_amount). The twin follows the description: a discountable item answers null. The spec's type and its description disagree; this declares the twin's side."
   }
- ]
+]
 }