@volter/twin-stripe 0.1.0 → 0.1.2

package/src/stripe-emit.ts

@@ -0,0 +1,150 @@
+// The Stripe DELIVER verb — `world-stripe emit` (feature-sweep friction: hand-constructing
+// checkout.session.completed / invoice.paid envelopes + HMAC signing to poke an app's webhook
+// handler). This is the pack side of the kernel's emit seam (@volter/twin emit.ts): the
+// catalog of emittable event types, endpoint registrations read FROM TWIN STATE AT REST
+// (webhook_endpoint rows minted by POST /v1/webhook_endpoints — the CLI runs in its own
+// process, so the in-memory delivery registry in stripe-events.ts does not apply), and
+// synthesis of the exact envelope real Stripe delivers, signed with the DESTINATION
+// endpoint's own whsec_twin_* so `stripe.webhooks.constructEvent(rawBody, header, secret)`
+// in the app's unmodified SDK verifies the delivery unchanged.
+//
+// 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/twin';
+import { OBJECT_NAME, TWIN_API_VERSION, view } from './stripe-twin.ts';
+import { STRIPE_WEBHOOK_FALLBACK_SECRET, generateTestHeaderString } from './stripe-events.ts';
+
+const SERVICE = 'stripe';
+
+// event type → the twin resource type whose current state becomes `data.object`.
+// The catalog is every event type the twin's own write path can produce (eventTypeFor's
+// range) — the emit verb can re-fire anything the twin emits organically.
+const EMITTABLE: Record<string, string> = {
+  // payment intents
+  'payment_intent.created': 'payment_intent',
+  'payment_intent.succeeded': 'payment_intent',
+  'payment_intent.processing': 'payment_intent',
+  'payment_intent.requires_action': 'payment_intent',
+  'payment_intent.amount_capturable_updated': 'payment_intent',
+  'payment_intent.payment_failed': 'payment_intent',
+  'payment_intent.canceled': 'payment_intent',
+  // charges + disputes
+  'charge.succeeded': 'charge',
+  'charge.captured': 'charge',
+  'charge.refunded': 'charge',
+  'charge.dispute.created': 'dispute',
+  // customers
+  'customer.created': 'customer',
+  'customer.updated': 'customer',
+  'customer.deleted': 'customer',
+  // checkout — the sweep's exact pain
+  'checkout.session.completed': 'checkout_session',
+  // invoices — the sweep's exact pain
+  'invoice.created': 'invoice',
+  'invoice.finalized': 'invoice',
+  'invoice.paid': 'invoice',
+  'invoice.payment_failed': 'invoice',
+  'invoice.voided': 'invoice',
+  'invoice.marked_uncollectible': 'invoice',
+  'invoice.sent': 'invoice',
+  // subscriptions
+  'customer.subscription.created': 'subscription',
+  'customer.subscription.updated': 'subscription',
+  'customer.subscription.deleted': 'subscription',
+  'customer.subscription.paused': 'subscription',
+  'customer.subscription.resumed': 'subscription',
+  // payment methods
+  'payment_method.attached': 'payment_method',
+  'payment_method.detached': 'payment_method',
+  // setup intents
+  'setup_intent.created': 'setup_intent',
+  'setup_intent.succeeded': 'setup_intent',
+  // payouts, catalog
+  'payout.created': 'payout',
+  'payout.paid': 'payout',
+  'payout.canceled': 'payout',
+  'price.created': 'price',
+  'product.created': 'product',
+  // issuing — the settlement consumer's diet (issuing_transaction.created) plus the
+  // authorization/card/cardholder lifecycle. issuing_authorization.request is emittable
+  // too: DELIVER re-fires the request event about an authorization AS IT IS in twin state
+  // (the organic synchronous leg lives in the present-authorization flow; this verb lets
+  // an app's handler see the event again without re-presenting).
+  'issuing_authorization.created': 'issuing_authorization',
+  'issuing_authorization.request': 'issuing_authorization',
+  'issuing_authorization.updated': 'issuing_authorization',
+  'issuing_card.created': 'issuing_card',
+  'issuing_card.updated': 'issuing_card',
+  'issuing_cardholder.created': 'issuing_cardholder',
+  'issuing_cardholder.updated': 'issuing_cardholder',
+  'issuing_transaction.created': 'issuing_transaction',
+};
+
+function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+
+function liveEndpointRows(root?: string): Array<Record<string, unknown>> {
+  return rows('webhook_endpoint', root).filter((w) => w._deleted !== true);
+}
+
+let emitSeq = 0;
+
+export const stripeEmitter: TwinEmitter = {
+  vendor: 'stripe',
+
+  events(): EmittableEvent[] {
+    return Object.entries(EMITTABLE).map(([type, subjectType]) => ({ type, subjectType }));
+  },
+
+  endpoints(root?: string): EmitEndpoint[] {
+    return liveEndpointRows(root).map((w) => ({
+      id: String(w.id),
+      url: String(w.url ?? ''),
+      ...(Array.isArray(w.enabled_events) ? { enabledEvents: w.enabled_events.map(String) } : {}),
+    }));
+  },
+
+  subjects(subjectType: string, root?: string): string[] {
+    return rows(subjectType, root).filter((r) => r._deleted !== true).map((r) => String(r.id));
+  },
+
+  synthesize({ type, subjectId, endpoint, root, occurredAt }): SynthesizedDelivery {
+    const subjectType = EMITTABLE[type];
+    if (!subjectType) throw new Error(`emit: the stripe pack cannot synthesize "${type}".`);
+    const row = rows(subjectType, root).find((r) => String(r.id) === subjectId && r._deleted !== true);
+    if (!row) {
+      const have = stripeEmitter.subjects(subjectType, root);
+      throw new Error(
+        `emit: no ${subjectType} "${subjectId}" in stripe twin state — cannot synthesize ${type}. ` +
+          (have.length ? `${subjectType} ids in state: ${have.join(', ')}.` : `No ${subjectType} exists in this twin yet (object name: ${OBJECT_NAME[subjectType] ?? subjectType}) — create one through the vendor API first.`),
+      );
+    }
+    // The endpoint's own signing secret, from its state row (real Stripe signs per-endpoint).
+    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);
+    // Same envelope persistStripeEvent stores for GET /v1/events; `evt_twin_emit_*` marks it
+    // operator-fired (never colliding with the write path's organic `evt_twin_<n>` ids).
+    const event: Record<string, unknown> = {
+      id: `evt_twin_emit_${created}_${++emitSeq}`,
+      object: 'event',
+      api_version: TWIN_API_VERSION,
+      created,
+      data: { object: view(subjectType, row) },
+      livemode: false,
+      pending_webhooks: 1,
+      request: { id: null, idempotency_key: null },
+      type,
+    };
+    const payload = JSON.stringify(event);
+    const header = generateTestHeaderString({ payload, secret, ...(occurredAt ? { timestamp: created } : {}) });
+    return {
+      payload,
+      headers: { 'content-type': 'application/json', 'stripe-signature': header },
+      event,
+    };
+  },
+};

package/src/stripe-events.ts

@@ -12,7 +12,12 @@ export type StripeEvent = {
   livemode: false;
   data: { object: Record<string, unknown> };
 };
-export type StripeEventDelivery = (url: string, event: StripeEvent) => Promise<void> | void;
+// A deliverer MAY return the endpoint's raw HTTP response. Ordinary (asynchronous) event
+// emission ignores the return value; the SYNCHRONOUS real-time-authorization leg
+// (issuing_authorization.request) reads it to honor the endpoint's approve/decline. A
+// fire-and-forget deliverer returning void stays valid for the asynchronous path.
+export type StripeWebhookEndpointResponse = { status: number; body: string };
+export type StripeEventDelivery = (url: string, event: StripeEvent) => Promise<void | StripeWebhookEndpointResponse> | void | StripeWebhookEndpointResponse;
 
 // ── Webhook signature verification (Stripe's scheme) ────────────────────────────
 // Real Stripe signs each webhook delivery with an HMAC-SHA256 over `${timestamp}.${payload}`
@@ -97,15 +102,43 @@ export function constructEvent(payload: string, header: string, secret: string,
 }
 
 const registry: string[] = [];
-export function registerStripeWebhook(url: string): void {
+// Endpoint signing secrets by URL. POST /v1/webhook_endpoints mints a `whsec_twin_*`
+// secret on the WebhookEndpoint object and registers it here so live HTTP delivery
+// signs each POST with THAT endpoint's secret (real Stripe signs per-endpoint). A
+// URL registered without a secret (test seam) is signed with the fallback below so
+// the header is still a real, verifiable signature — never a placeholder.
+const secrets = new Map<string, string>();
+// Subscriptions by URL: the endpoint's enabled_events, carried through registration so the
+// organic fan-out filters like the vendor. A URL registered WITHOUT a list (test seam)
+// receives every event — equivalent to ['*'].
+const subscriptions = new Map<string, string[]>();
+export const STRIPE_WEBHOOK_FALLBACK_SECRET = 'whsec_twin_default';
+export function registerStripeWebhook(url: string, secret?: string, enabledEvents?: string[]): void {
   if (!registry.includes(url)) registry.push(url);
+  if (secret) secrets.set(url, secret);
+  if (enabledEvents) subscriptions.set(url, enabledEvents.map(String));
 }
 export function unregisterStripeWebhook(url: string): void {
   const i = registry.indexOf(url);
   if (i !== -1) registry.splice(i, 1);
+  secrets.delete(url);
+  subscriptions.delete(url);
 }
 export function clearStripeWebhooks(): void {
   registry.length = 0;
+  secrets.clear();
+  subscriptions.clear();
+}
+
+// Does an enabled_events list subscribe an endpoint to `type`? Stripe semantics: '*'
+// matches everything, 'issuing_authorization.*' matches the family, else exact. Shared by
+// the organic fan-out below and the synchronous issuing leg's enrollment check.
+export function stripeEventMatches(enabledEvents: unknown, type: string): boolean {
+  if (!Array.isArray(enabledEvents)) return false;
+  return enabledEvents.some((p) => {
+    const s = String(p);
+    return s === '*' || (s.endsWith('.*') && type.startsWith(s.slice(0, -1))) || s === type;
+  });
 }
 export function listStripeWebhooks(): string[] {
   return [...registry];
@@ -128,6 +161,16 @@ export function eventTypeFor(operation: string): string | null {
     'customer.subscription.updated', 'customer.subscription.paused', 'customer.subscription.resumed',
     'payout.created', 'payout.paid', 'payout.canceled', 'price.created', 'product.created',
     'setup_intent.succeeded', 'setup_intent.created',
+    // The twin's checkout completion transition records the op AS the real event type:
+    // real Stripe fires checkout.session.completed (data.object = the completed Session)
+    // the moment a session reaches status=complete — the event most billing integrations
+    // fulfill from, so it must pass through, not be swallowed.
+    'checkout.session.completed',
+    // Issuing writes record the op AS the real event type (issuing_authorization.updated on
+    // approve/decline/update, issuing_card.updated on card updates, …) — all real vendor
+    // event types (stripe@22.3.0 WebhookEndpoint.EnabledEvent enum).
+    'issuing_authorization.updated', 'issuing_card.updated', 'issuing_cardholder.updated',
+    'issuing_transaction.updated',
   ]);
   if (PASSTHROUGH.has(operation)) return operation;
   switch (operation) {
@@ -148,17 +191,56 @@ export function eventTypeFor(operation: string): string | null {
     case 'payout.create': return 'payout.created';
     case 'product.create': return 'product.created';
     case 'price.create': return 'price.created';
+    // Issuing: real Stripe fires issuing_authorization.created/.updated,
+    // issuing_card.created/.updated, issuing_cardholder.created/.updated and
+    // issuing_transaction.created (all present in the vendor SDK's
+    // WebhookEndpoint.EnabledEvent enum, stripe@22.3.0 WebhookEndpoints.d.ts).
+    // issuing_authorization.request is deliberately NOT here: it is not a
+    // state-change event — the twin delivers it SYNCHRONOUSLY from the
+    // present-authorization flow (requestAuthorizationDecision below).
+    case 'issuing_authorization.create': return 'issuing_authorization.created';
+    case 'issuing_card.create': return 'issuing_card.created';
+    case 'issuing_cardholder.create': return 'issuing_cardholder.created';
+    case 'issuing_transaction.create': return 'issuing_transaction.created';
     default: return null;
   }
 }
 
 let counter = 0;
+// Live HTTP delivery signs exactly like real Stripe: HMAC-SHA256 over
+// `${timestamp}.${payload}` keyed by the ENDPOINT'S OWN signing secret (the
+// `whsec_twin_*` minted by POST /v1/webhook_endpoints and registered alongside the
+// URL), sent as `Stripe-Signature: t=...,v1=...`. The signed bytes are the exact
+// request body, so `stripe.webhooks.constructEvent(rawBody, header, secret)` in the
+// consumer's real SDK verifies twin deliveries unchanged (a hardcoded placeholder
+// header made every verifying consumer 400 — the delivery was unverifiable).
+// Delivery is AT-LEAST-ONCE, like the vendor: real Stripe re-attempts a webhook whose
+// delivery fails at the transport layer rather than dropping it, so a consumer that missed
+// one event because a socket blipped is a consumer real Stripe would have reached. A single
+// swallowed `fetch` rejection here is indistinguishable, downstream, from the consumer
+// having a bug — it cost a week of "the settlement webhook is racy" before anyone could see
+// that the event had simply never left the twin. Two cheap re-attempts cover a transient
+// local failure (ECONNRESET / socket exhaustion under a boot storm); a genuinely unreachable
+// endpoint refuses instantly, so the retries cost microseconds. A NON-2xx response is the
+// consumer answering, not a transport failure — it is not retried here.
+// A delivery that still fails after the re-attempts is DROPPED, and says so: silent loss is
+// the one outcome a twin must never have, because it makes every consumer look flaky.
+const DELIVERY_ATTEMPTS = 3;
 const httpDelivery: StripeEventDelivery = async (url, event) => {
-  try {
-    await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': 'twin' }, body: JSON.stringify(event) });
-  } catch {
-    /* fire-and-forget */
+  const payload = JSON.stringify(event);
+  const secret = secrets.get(url) ?? STRIPE_WEBHOOK_FALLBACK_SECRET;
+  let last = '';
+  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 });
+      return;
+    } catch (error) {
+      last = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+      if (attempt < DELIVERY_ATTEMPTS) await new Promise((resolve) => setTimeout(resolve, 25 * attempt));
+    }
   }
+  console.error(`[twin:stripe] webhook delivery DROPPED after ${DELIVERY_ATTEMPTS} attempts — ${event.type} ${event.id} -> ${url}: ${last}`);
 };
 
 // Default deliverer override (a TEST SEAM). The twin's write path emits events without
@@ -171,11 +253,97 @@ export function setStripeEventDelivery(deliver: StripeEventDelivery | null): voi
   defaultDelivery = deliver;
 }
 
+// ── Real-time authorization (issuing_authorization.request) — the SYNCHRONOUS leg ────────
+// Real Stripe delivers issuing_authorization.request to the ONE enrolled endpoint while the
+// card network holds the authorization open, and the endpoint must answer within Stripe's
+// documented 2-second window ("This request should be made within the timeout window of the
+// real-time authorization flow" — stripe@22.3.0 Issuing/Authorizations.d.ts; the current
+// method is to "respond directly to the webhook request to approve an authorization"). The
+// endpoint's HTTP response body carries the decision: a JSON object with a boolean
+// `approved` (and, for an amount-controllable request, an optional integer `amount` to hold
+// a different amount). Outcomes map onto the vendor's request_history.reason values
+// (stripe@22.3.0 RequestHistory.Reason):
+//   webhook_approved / webhook_declined — the endpoint answered in time;
+//   webhook_timeout — no response arrived inside the window (incl. unreachable endpoint);
+//   webhook_error   — "the direct webhook response is invalid (for example, parsing errors
+//                      or missing parameters)" (verbatim from the SDK's reason_message doc),
+//                      i.e. non-2xx status, non-JSON body, or a missing `approved`.
+// On timeout/error real Stripe DECLINES the authorization (fail-closed; the card's own
+// spending_controls remain the backstop) — the account-level "approve on timeout" opt-in is
+// not API-configurable and is not modeled.
+export const STRIPE_REALTIME_AUTH_TIMEOUT_MS = 2_000;
+
+export type StripeAuthRequestOutcome =
+  | { kind: 'approved'; amount?: number }
+  | { kind: 'declined' }
+  | { kind: 'timeout'; message: string }
+  | { kind: 'error'; message: string };
+
+// The live synchronous deliverer: POST the signed event and WAIT for the response within
+// the 2s window. Signs with the enrolled endpoint's own whsec (passed by the caller, read
+// from the endpoint's state row) — never a placeholder.
+async function httpAuthRequestDelivery(url: string, event: StripeEvent, secret: string): Promise<StripeWebhookEndpointResponse> {
+  const payload = JSON.stringify(event);
+  const header = generateTestHeaderString({ payload, secret });
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'stripe-signature': header },
+    body: payload,
+    signal: AbortSignal.timeout(STRIPE_REALTIME_AUTH_TIMEOUT_MS),
+  });
+  return { status: res.status, body: await res.text() };
+}
+
+/**
+ * Deliver an issuing_authorization.request event to the enrolled endpoint and interpret
+ * its synchronous response as the authorization decision. Honors the installed test
+ * deliverer (setStripeEventDelivery) so verifies run fully offline: a fake returning a
+ * {status, body} response drives the decision; a fake that throws a TimeoutError (the
+ * exact error AbortSignal.timeout produces) exercises the timeout fallback.
+ */
+export async function requestAuthorizationDecision(url: string, event: StripeEvent, secret: string): Promise<StripeAuthRequestOutcome> {
+  let res: void | StripeWebhookEndpointResponse;
+  try {
+    res = defaultDelivery ? await defaultDelivery(url, event) : await httpAuthRequestDelivery(url, event, secret);
+  } catch (e) {
+    const name = e instanceof Error ? e.name : '';
+    if (name === 'TimeoutError' || name === 'AbortError') {
+      return { kind: 'timeout', message: 'Webhook endpoint did not respond within the real-time authorization window.' };
+    }
+    // No response ever reached us (connection refused, DNS, socket reset) — like an
+    // endpoint that never answered inside the window: a timeout, not an invalid response.
+    return { kind: 'timeout', message: 'Webhook endpoint was unreachable within the real-time authorization window.' };
+  }
+  if (!res || typeof res !== 'object') {
+    return { kind: 'error', message: 'Webhook endpoint returned no response body.' };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    return { kind: 'error', message: `Webhook endpoint responded with HTTP status ${res.status}.` };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    return { kind: 'error', message: 'Webhook response body was not valid JSON.' };
+  }
+  const approved = (parsed as { approved?: unknown } | null)?.approved;
+  if (typeof approved !== 'boolean') {
+    return { kind: 'error', message: 'Webhook response is missing the required `approved` parameter.' };
+  }
+  if (!approved) return { kind: 'declined' };
+  const amount = (parsed as { amount?: unknown }).amount;
+  return { kind: 'approved', ...(typeof amount === 'number' && Number.isInteger(amount) && amount > 0 ? { amount } : {}) };
+}
+
 /**
  * Emit a Stripe event for a twin write to registered endpoints. `resource` is the
  * Stripe object the event is about. `occurredAt` is caller-supplied (deterministic).
  * Returns the delivered events (for assertions); no-op when nothing is registered
  * or the operation has no mapped event type.
+ *
+ * Fan-out filters by each endpoint's registered enabled_events (stripeEventMatches — '*',
+ * 'family.*', exact), like the vendor: a consumer enrolled for one event type receives
+ * only that type. A URL registered without a list (test seam) receives everything.
  */
 export async function emitStripeEvent(
   operation: string,
@@ -195,6 +363,8 @@ export async function emitStripeEvent(
   };
   const out: StripeEvent[] = [];
   for (const url of registry) {
+    const enabled = subscriptions.get(url);
+    if (enabled && !stripeEventMatches(enabled, type)) continue;
     await deliver(url, event);
     out.push(event);
   }

package/src/stripe-mirror-ui.ts

@@ -2,10 +2,12 @@
 // React/TSX app (bundled by Bun, the repo convention; cf. tracker-visualizer).
 // It renders by consuming the twin's OWN REST API on the same origin
 // (/v1/<collection>) — the same endpoints the app uses. Per-vendor + concrete.
-import { handleStripeTwinRequest } from './stripe-twin.ts';
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// own fetch adapter as its API backend and reads every byte of state back over the wire.
+import { createStripeTwinFetch } from './stripe-server.ts';
 
-const CLIENT_ENTRY = new URL('../client/stripe-mirror.tsx', import.meta.url).pathname;
-const CLIENT_CSS = new URL('../client/stripe-mirror.css', import.meta.url).pathname;
+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)
 
 // ---------------------------------------------------------------------------
 // Pure, dependency-free render/format/resolution helpers.
@@ -13,7 +15,7 @@ const CLIENT_CSS = new URL('../client/stripe-mirror.css', import.meta.url).pathn
 // These are intentionally framework-agnostic (plain data in → plain data out) so
 // they can be unit-tested in isolation AND imported by the React/TSX client
 // (Bun tree-shakes the server-only exports below out of the browser bundle).
-// Keep them free of any `@volter/twin`/`Bun`/`handleStripeTwinRequest` usage.
+// Keep them free of any `@volter/twin`/`Bun`/twin-adapter usage.
 // ---------------------------------------------------------------------------
 
 export type StripeRow = Record<string, any>;
@@ -303,7 +305,7 @@ let clientBundle: Promise<string> | null = null;
 /** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
 export function buildStripeMirrorClient(): Promise<string> {
   if (!clientBundle) {
-    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY], target: 'browser', minify: true })
+    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY()], target: 'browser', minify: true })
       .then(async (result) => {
         if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || 'stripe mirror client build failed');
         return result.outputs[0]!.text();
@@ -315,7 +317,16 @@ export function buildStripeMirrorClient(): Promise<string> {
 
 /** Serve the Stripe dashboard mirror UI (React app) + its backing REST API. */
 export function createStripeMirrorServer(options: { root?: string; port?: number }): { port: number; stop: () => void } {
+  const twin = createStripeTwinFetch(options);
   const server = Bun.serve({
+    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+    // on loopback, so the verify's fetches deterministically reach THIS server.
+    hostname: '127.0.0.1',
     port: options.port ?? 0,
     idleTimeout: 60,
     async fetch(request) {
@@ -325,15 +336,19 @@ export function createStripeMirrorServer(options: { root?: string; port?: number
         catch (error) { return new Response(String(error), { status: 500 }); }
       }
       if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
-        return new Response(Bun.file(CLIENT_CSS), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+        return new Response(Bun.file(CLIENT_CSS()), { headers: { 'content-type': 'text/css; charset=utf-8' } });
       }
       if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
         return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
       }
-      // everything else → the twin's REST API (the React client fetches /v1/<collection>)
-      const body = request.method === 'GET' ? '' : await request.text();
-      const { status, body: out } = await handleStripeTwinRequest({ method: request.method, path: url.pathname + (url.search || ''), body, ...(options.root !== undefined ? { root: options.root } : {}) });
-      return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json' } });
+      // everything else → the twin's OWN FETCH ADAPTER (composition, R2): the React client fetches
+      // the vendor's real paths (/v1/<collection>) and this is the same closure
+      // `createStripeTwinServer` mounts, so there is exactly ONE serving code path — the `/twin`
+      // manifest door, the form-encoded body passed through byte-for-byte, the Idempotency-Key /
+      // Stripe-Version / Stripe-Account threading, the `request-id` response header, the world
+      // clock and an honorable `readOnly` all come from it, and the mirror port cannot drift from
+      // the API port.
+      return twin(request);
     },
   });
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };

package/src/stripe-server.ts

@@ -3,44 +3,79 @@
 // backend sandbox's api.stripe.com interception at it. Form-encoded bodies (what
 // the SDK sends) pass through to the handler. Writable by default (the local stack
 // uses the twin as its authoritative Stripe); pass readOnly to reject writes (R4).
+//
+// 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 { handleStripeTwinRequest } from './stripe-twin.ts';
+import { worldNow, statefulTwinManifest} from '@volter/twin';
 
-export function createStripeTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): { port: number; stop: () => void } {
+/** Options shared by the fetch handler and the Bun.serve wrapper around it. `port` is a
+ *  BIND concern the fetch ignores; it stays in one shape so a caller configures the twin
+ *  once whichever way it is mounted. */
+export type StripeTwinOptions = { root?: string; port?: number; readOnly?: boolean };
+
+/**
+ * The whole Stripe serve path as a plain `(Request) => Response` — the `/twin` manifest
+ * door, the header threading (idempotency key, pinned API version, Connect account) and
+ * the dispatch into `handleStripeTwinRequest`. NOTHING about it is port-bound.
+ *
+ * Why this is the factory and `createStripeTwinServer` is a wrapper (runtime contract R12,
+ * the Cloudflare ruling): a Durable Object / Worker entry has no loopback ports — it mounts
+ * pack fetches IN-PROCESS behind one router. Handing that entry `Bun.serve` is not an
+ * option, so the vendor HTTP adaptation has to be a value it can call. Keeping the server a
+ * thin `Bun.serve(fetch)` also means the local and hosted lanes execute the SAME bytes of
+ * serving code — the parity claim (R9) is about one code path, not two that resemble each
+ * other.
+ *
+ * SCOPING THE STORES AROUND IT: this fetch is ASYNC, so install the world store with
+ * `setActiveWorldStore(store)` in a try/finally — **not** `withWorldStore(store, fn)`, whose
+ * `finally` fires when `fn` RETURNS, i.e. at the first `await`, restoring the previous store
+ * under the rest of the request.
+ */
+export function createStripeTwinFetch(options: StripeTwinOptions): (request: Request) => Promise<Response> {
   const readOnly = options.readOnly ?? false;
+  return async function stripeTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(statefulTwinManifest({ vendor: 'stripe', twinOf: 'the Stripe REST API', stores: 'customers, payment objects, checkout sessions, products/prices and webhook endpoints (signed events)' }));
+    }
+    const body = request.method === 'GET' ? '' : await request.text();
+    // Stripe sends the idempotency key as the `Idempotency-Key` request header; the
+    // real SDK sets it from { idempotencyKey } on a write call. Thread it through so
+    // a replay returns the stored response without re-applying the write.
+    const idempotencyKey = request.headers.get('idempotency-key') ?? undefined;
+    // Stripe pins API behavior via the `Stripe-Version` request header; the real SDK
+    // sets it from { apiVersion }. Thread it through so the twin can reflect it (and
+    // reject a malformed value with a 400) exactly like real Stripe.
+    const apiVersion = request.headers.get('stripe-version') ?? undefined;
+    // Connect: the SDK sets `Stripe-Account` from { stripeAccount } to act on behalf of a
+    // connected account. Thread it through so account-scoped writes (e.g. a payout created
+    // on the connected account's balance) are attributed to that account, like real Stripe.
+    const stripeAccount = request.headers.get('stripe-account') ?? undefined;
+    const { status, body: out } = await handleStripeTwinRequest({
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      readOnly,
+      ...(apiVersion ? { apiVersion } : {}),
+      ...(stripeAccount ? { stripeAccount } : {}),
+      // The WORLD instant (R9): served `created` epochs come from the world clock, never
+      // wall time. Embedded/test callers pass their own occurredAt.
+      occurredAt: worldNow(),
+      ...(idempotencyKey ? { idempotencyKey } : {}),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    });
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'request-id': 'req_twin' } });
+  };
+}
+
+export function createStripeTwinServer(options: StripeTwinOptions): { port: number; stop: () => void } {
   const server = Bun.serve({
     port: options.port ?? 0,
     idleTimeout: 60,
-    async fetch(request) {
-      const url = new URL(request.url);
-      const body = request.method === 'GET' ? '' : await request.text();
-      // Stripe sends the idempotency key as the `Idempotency-Key` request header; the
-      // real SDK sets it from { idempotencyKey } on a write call. Thread it through so
-      // a replay returns the stored response without re-applying the write.
-      const idempotencyKey = request.headers.get('idempotency-key') ?? undefined;
-      // Stripe pins API behavior via the `Stripe-Version` request header; the real SDK
-      // sets it from { apiVersion }. Thread it through so the twin can reflect it (and
-      // reject a malformed value with a 400) exactly like real Stripe.
-      const apiVersion = request.headers.get('stripe-version') ?? undefined;
-      // Connect: the SDK sets `Stripe-Account` from { stripeAccount } to act on behalf of a
-      // connected account. Thread it through so account-scoped writes (e.g. a payout created
-      // on the connected account's balance) are attributed to that account, like real Stripe.
-      const stripeAccount = request.headers.get('stripe-account') ?? undefined;
-      const { status, body: out } = await handleStripeTwinRequest({
-        method: request.method,
-        path: url.pathname + (url.search || ''),
-        body,
-        readOnly,
-        ...(apiVersion ? { apiVersion } : {}),
-        ...(stripeAccount ? { stripeAccount } : {}),
-        // Stamp real wall-clock time so served objects get a real `created` epoch (not 1970).
-        // Embedded/test callers pass their own occurredAt for determinism; the live HTTP path
-        // — what the real SDK hits — should reflect actual time, like the real vendor.
-        occurredAt: new Date().toISOString(),
-        ...(idempotencyKey ? { idempotencyKey } : {}),
-        ...(options.root !== undefined ? { root: options.root } : {}),
-      });
-      return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'request-id': 'req_twin' } });
-    },
+    fetch: createStripeTwinFetch(options),
   });
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }