@volter/twin-stripe 2.0.38 → 3.0.0

package/src/stripe-emit.ts

@@ -1,157 +0,0 @@
-// 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/world-core 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, 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';
-
-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.failed': '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.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).
-    const account = typeof row._account === 'string' ? row._account : subjectType === 'account' && String(row.id) !== PLATFORM_ACCOUNT_ID ? String(row.id) : undefined;
-    // 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,
-      ...(account ? { account } : {}),
-    };
-    const payload = JSON.stringify(render(event, TWIN_API_VERSION));
-    const header = generateTestHeaderString({ payload, secret, ...(occurredAt ? { timestamp: created } : {}) });
-    return {
-      payload,
-      headers: { 'content-type': 'application/json', 'stripe-signature': header },
-      event,
-    };
-  },
-};

package/src/stripe-events.ts

@@ -1,434 +0,0 @@
-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';
-// Stripe event/webhook emission (scorecard R17). Real Stripe fires `event`
-// objects (and webhooks) on state changes — payment_intent.succeeded,
-// customer.subscription.created, invoice.paid, … — so an app's webhook handler
-// runs. A faithful twin must too. On a twin write we build the Stripe `event`
-// envelope and deliver it to registered endpoints (injected delivery: fake in
-// tests, HTTP POST live, failures swallowed like the real vendor).
-export type StripeEvent = {
-  id: string;
-  object: 'event';
-  type: string;
-  created: number;
-  livemode: false;
-  /** the connected account a Connect event is from */
-  account?: string;
-  data: { object: Record<string, unknown> };
-};
-// 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, secret?: string) => Promise<void | StripeWebhookEndpointResponse> | void | StripeWebhookEndpointResponse;
-/** A webhook endpoint a World holds in its tree: where to POST, what to sign with, what it subscribed to. */
-export type StripeWebhookTarget = { url: string; secret?: string; enabledEvents?: string[]; /** a Connect endpoint (`connect: true`): events from connected accounts */ connect?: boolean };
-
-// ── Webhook signature verification (Stripe's scheme) ────────────────────────────
-// Real Stripe signs each webhook delivery with an HMAC-SHA256 over `${timestamp}.${payload}`
-// keyed by the endpoint's signing secret, and sends it in the `Stripe-Signature` header as
-// `t=<unix>,v1=<hex-sig>`. The SDK's `stripe.webhooks.constructEvent(payload, header, secret)`
-// recomputes the signature and 400s on a mismatch / stale timestamp; tests build the header
-// with `stripe.webhooks.generateTestHeaderString(...)`. We reproduce BOTH, byte-for-byte, so a
-// real `stripe` SDK consumer verifies twin-delivered webhooks unchanged. Pure Node crypto —
-// no network, fully deterministic. `node:crypto` is required lazily (inside the functions that
-// use it) rather than as a top-level static import, so this module can be pulled into the
-// browser bundle of the UI mirror without Bun's browser target choking on `node:crypto` — the
-// signature helpers are server-only and never reached in the browser path.
-type NodeCrypto = typeof import('node:crypto');
-function nodeCrypto(): NodeCrypto {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  return nodeBuiltin('node:crypto') as NodeCrypto;
-}
-
-/** HMAC-SHA256(secret, `${timestamp}.${payload}`) as lowercase hex — Stripe's v1 signature. */
-export function computeStripeSignature(payload: string, secret: string, timestamp: number): string {
-  return nodeCrypto().createHmac('sha256', secret).update(`${timestamp}.${payload}`, 'utf8').digest('hex');
-}
-
-/** Build a `Stripe-Signature` header value for `payload` (mirrors generateTestHeaderString). */
-export function generateTestHeaderString(opts: { payload: string; secret: string; timestamp?: number; scheme?: string }): string {
-  // 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}`;
-}
-
-/** Parse a `Stripe-Signature` header into its timestamp + the list of v1 signatures. */
-function parseSignatureHeader(header: string): { timestamp: number; signatures: string[] } {
-  let timestamp = -1;
-  const signatures: string[] = [];
-  for (const part of header.split(',')) {
-    const eq = part.indexOf('=');
-    if (eq === -1) continue;
-    const key = part.slice(0, eq).trim();
-    const value = part.slice(eq + 1).trim();
-    if (key === 't') timestamp = Number(value);
-    else if (key === 'v1') signatures.push(value);
-  }
-  return { timestamp, signatures };
-}
-
-export class StripeSignatureVerificationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'StripeSignatureVerificationError';
-  }
-}
-
-/**
- * Verify a webhook payload + signature header against the signing secret and return the
- * parsed event (mirrors `stripe.webhooks.constructEvent`). Throws a
- * StripeSignatureVerificationError on a malformed/missing header, a signature that does
- * not match, or (when `tolerance` is given) a timestamp outside the allowed window.
- */
-export function constructEvent(payload: string, header: string, secret: string, opts: { tolerance?: number; now?: number } = {}): StripeEvent {
-  if (!header) throw new StripeSignatureVerificationError('No signatures found matching the expected signature for payload.');
-  const { timestamp, signatures } = parseSignatureHeader(header);
-  if (timestamp < 0 || signatures.length === 0) {
-    throw new StripeSignatureVerificationError('Unable to extract timestamp and signatures from header');
-  }
-  const expected = computeStripeSignature(payload, secret, timestamp);
-  const expectedBuf = Buffer.from(expected, 'utf8');
-  const matched = signatures.some((s) => {
-    const sBuf = Buffer.from(s, 'utf8');
-    return sBuf.length === expectedBuf.length && nodeCrypto().timingSafeEqual(sBuf, expectedBuf);
-  });
-  if (!matched) {
-    throw new StripeSignatureVerificationError('No signatures found matching the expected signature for payload.');
-  }
-  if (opts.tolerance !== undefined) {
-    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
-    if (now - timestamp > opts.tolerance) {
-      throw new StripeSignatureVerificationError('Timestamp outside the tolerance zone');
-    }
-  }
-  return JSON.parse(payload) as StripeEvent;
-}
-
-const registry: string[] = [];
-// URLs a HOST registered directly (registerStripeWebhook), with the secret to sign with and the
-// enabled_events to filter on. A World's own endpoints are not here: POST /v1/webhook_endpoints
-// writes the WebhookEndpoint to the tree, and every emit reads the tree (the caller passes them as
-// `endpoints`), so delivery survives a restart and belongs to one World. A URL registered here
-// without a secret is signed with the fallback below, so the header is still a real, verifiable
-// signature; one registered without a list receives every event, equivalent to ['*'].
-const secrets = new Map<string, string>();
-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];
-}
-
-// twin write operation → Stripe event type (the ones an app's webhooks care about).
-// Returns null when an operation has no event (e.g. a plain create/retrieve we
-// don't model an event for).
-const VENDOR_EVENT_TYPES = new Set((vendorEvents as { types: string[] }).types);
-
-export function eventTypeFor(operation: string): string | null {
-  // Several twin write operations ARE already the Stripe event type (we record the
-  // op as `<resource>.<event>` so it maps 1:1): payment_intent.amount_capturable_updated,
-  // payment_intent.canceled, payment_intent.succeeded. Those pass through directly.
-  const PASSTHROUGH = new Set([
-    'payment_intent.amount_capturable_updated', 'payment_intent.canceled', 'payment_intent.succeeded',
-    'payment_intent.payment_failed', 'payment_intent.created', 'payment_intent.processing',
-    'payment_intent.requires_action',
-    'charge.succeeded', 'charge.captured', 'charge.refunded', 'charge.dispute.created',
-    // A refund fires TWO real Stripe events: `refund.created` carrying the Refund, and
-    // `charge.refunded` carrying the CHARGE with its new totals. The twin records the charge's
-    // own write as `charge.refunded`, so the event a consumer receives is the charge — which is
-    // the whole point of that event and the reason a reconciler subscribes to it.
-    'refund.created', 'refund.updated',
-    'customer.updated', 'customer.deleted', 'invoice.created', 'invoice.finalized',
-    'invoice.paid', 'invoice.payment_failed', 'invoice.voided', 'invoice.marked_uncollectible', 'invoice.sent',
-    '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) {
-    case 'customer.create': return 'customer.created';
-    case 'payment_intent.create': return 'payment_intent.created';
-    case 'payment_intent.confirm': return 'payment_intent.succeeded';
-    case 'payment_method.attach': return 'payment_method.attached';
-    case 'payment_method.detach': return 'payment_method.detached';
-    case 'setup_intent.confirm': return 'setup_intent.succeeded';
-    case 'subscription.create': return 'customer.subscription.created';
-    case 'subscription.update': return 'customer.subscription.updated';
-    case 'subscription.cancel': return 'customer.subscription.deleted';
-    case 'invoice.finalize': return 'invoice.finalized';
-    case 'invoice.pay': return 'invoice.paid';
-    case 'invoice.void': return 'invoice.voided';
-    case 'refund.create': return 'refund.created';
-    case 'dispute.create': return 'charge.dispute.created';
-    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 vendorEventType(operation);
-  }
-}
-
-/** Any other write records the event Stripe sends for it, when Stripe sends one: the operation itself, or its
- *  resource's create/update/delete as `<resource>.created|updated|deleted` (the types Stripe's spec enumerates). */
-function vendorEventType(operation: string): string | null {
-  if (VENDOR_EVENT_TYPES.has(operation)) return operation;
-  const verb = /^(.+)\.(create|update|delete)$/.exec(operation);
-  return verb && VENDOR_EVENT_TYPES.has(`${verb[1]}.${verb[2]}d`) ? `${verb[1]}.${verb[2]}d` : null;
-}
-
-/** An event's id, DERIVED from the event itself — the operation, the resource it carries and the instant —
- *  never a process counter (protocol 2: two identical worlds deliver identically, and a replay of the same
- *  write raises the same event id rather than one that drifts with process uptime). */
-function eventId(operation: string, resource: Record<string, unknown>, occurredAt: string, account?: string): string {
-  let h = 0x811c9dc5;
-  const seed = `${operation}|${String((resource as { id?: unknown }).id ?? '')}|${occurredAt}|${account ?? ''}`;
-  for (let i = 0; i < seed.length; i += 1) { h ^= seed.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
-  return `evt_twin_${h.toString(16).padStart(8, '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, 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; 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);
-};
-
-/** The HTTP POST of a signed event to an endpoint the World lets it reach, re-attempted on a transport failure. */
-async function postEvent(url: string, event: StripeEvent, payload: string, secret: string): Promise<void> {
-  let last = '';
-  for (let attempt = 1; attempt <= DELIVERY_ATTEMPTS; attempt += 1) {
-    try {
-      const header = generateTestHeaderString({ payload, secret });
-      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);
-      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
-// threading a per-call deliverer, so to drive event delivery fully OFFLINE/deterministically
-// — no real sockets — a test installs a fake sink here. When unset, real HTTP POST is used
-// (prod behavior). This keeps D5 honest: verify() exercises the twin's own emission, in-process.
-// a slot, not module truth (protocol 2): WHERE a delivery goes, set once by the host that mounts the twin
-const defaultDelivery: { current: StripeEventDelivery | null } = { current: null };
-/** Install a default deliverer used by the write path when no per-call `deliver` is passed. */
-export function setStripeEventDelivery(deliver: StripeEventDelivery | null): void {
-  defaultDelivery.current = 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> {
-  // 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); 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 appFetch(url, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() },
-    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.current ? await defaultDelivery.current(url, event) : await httpAuthRequestDelivery(url, event, secret);
-  } catch (e) {
-    // no answer inside the window: cut off (TimeoutError, AbortError), or never reached (refused, DNS, reset), alike
-    return (e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError')) ? TIMED_OUT : UNREACHED;
-  }
-  return readDecision(res);
-}
-
-const TIMED_OUT: StripeAuthRequestOutcome = { kind: 'timeout', message: 'Webhook endpoint did not respond within the real-time authorization window.' };
-const UNREACHED: StripeAuthRequestOutcome = { kind: 'timeout', message: 'Webhook endpoint was unreachable within the real-time authorization window.' };
-
-/** The endpoint's synchronous answer read as the decision: `approved` (and an optional `amount`), or an error for an
- *  answer Stripe cannot read. */
-function readDecision(res: void | StripeWebhookEndpointResponse): StripeAuthRequestOutcome {
-  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,
-  resource: Record<string, unknown>,
-  opts: { occurredAt: string; deliver?: StripeEventDelivery; endpoints?: StripeWebhookTarget[]; account?: string; /** the id the stored event takes (afterStripeWrite) */ id?: string } = { occurredAt: '1970-01-01T00:00:00.000Z' },
-): Promise<StripeEvent[]> {
-  const type = eventTypeFor(operation);
-  // the World's own endpoints (its tree is the record), then any URL a host registered directly
-  const targets: StripeWebhookTarget[] = [...(opts.endpoints ?? [])];
-  for (const url of registry) if (!targets.some((t) => t.url === url)) targets.push({ url, ...(secrets.has(url) ? { secret: secrets.get(url)! } : {}), ...(subscriptions.has(url) ? { enabledEvents: subscriptions.get(url)! } : {}) });
-  if (!type || targets.length === 0) return [];
-  const deliver = opts.deliver ?? defaultDelivery.current ?? httpDelivery;
-  const event: StripeEvent = {
-    id: opts.id ?? eventId(operation, resource, opts.occurredAt, opts.account),
-    object: 'event',
-    type,
-    created: Math.floor(Date.parse(opts.occurredAt) / 1000) || 0,
-    livemode: false,
-    data: { object: resource },
-    // "Each event for a connected account contains a top-level `account` property that identifies the connected account"
-    ...(opts.account ? { account: opts.account } : {}),
-  };
-  const out: StripeEvent[] = [];
-  for (const target of targets) {
-    if (target.enabledEvents && !stripeEventMatches(target.enabledEvents, type)) continue;
-    // an endpoint's scope (docs.stripe.com/connect/webhooks): `connect: true` receives the Connected accounts scope,
-    // `connect: false` Your account; a URL registered without a scope (a host's seam) receives both
-    if (target.connect !== undefined && target.connect !== Boolean(opts.account)) continue;
-    await deliver(target.url, event, target.secret);
-    out.push(event);
-  }
-  return out;
-}