@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/stripe-events.js

@@ -0,0 +1,388 @@
+import { nodeBuiltin } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+import vendorEvents from './generated/events.gen.json' with { type: 'json' };
+import { render } from "./stripe-version.js";
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+/** HMAC-SHA256(secret, `${timestamp}.${payload}`) as lowercase hex — Stripe's v1 signature. */
+export function computeStripeSignature(payload, secret, timestamp) {
+    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) {
+    const timestamp = opts.timestamp ?? Math.floor(Date.now() / 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) {
+    let timestamp = -1;
+    const signatures = [];
+    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) {
+        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, header, secret, opts = {}) {
+    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.now() / 1000);
+        if (now - timestamp > opts.tolerance) {
+            throw new StripeSignatureVerificationError('Timestamp outside the tolerance zone');
+        }
+    }
+    return JSON.parse(payload);
+}
+const registry = [];
+// 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();
+const subscriptions = new Map();
+export const STRIPE_WEBHOOK_FALLBACK_SECRET = 'whsec_twin_default';
+export function registerStripeWebhook(url, secret, enabledEvents) {
+    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) {
+    const i = registry.indexOf(url);
+    if (i !== -1)
+        registry.splice(i, 1);
+    secrets.delete(url);
+    subscriptions.delete(url);
+}
+export function clearStripeWebhooks() {
+    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, type) {
+    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() {
+    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.types);
+export function eventTypeFor(operation) {
+    // 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) {
+    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, resource, occurredAt, account) {
+    let h = 0x811c9dc5;
+    const seed = `${operation}|${String(resource.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 = async (url, event, endpointSecret) => {
+    // the event as its API version renders it (stripe-version.ts)
+    const payload = JSON.stringify(render(event, event.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);
+    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, event, payload, 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
+// 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: null };
+/** Install a default deliverer used by the write path when no per-call `deliver` is passed. */
+export function setStripeEventDelivery(deliver) {
+    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;
+// 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, event, secret) {
+    // the event as its API version renders it (stripe-version.ts)
+    const payload = JSON.stringify(render(event, event.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);
+    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, payload, header) {
+    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, event, secret) {
+    let res;
+    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 = { kind: 'timeout', message: 'Webhook endpoint did not respond within the real-time authorization window.' };
+const UNREACHED = { 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) {
+    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;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch {
+        return { kind: 'error', message: 'Webhook response body was not valid JSON.' };
+    }
+    const approved = parsed?.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.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, resource, opts = { occurredAt: '1970-01-01T00:00:00.000Z' }) {
+    const type = eventTypeFor(operation);
+    // the World's own endpoints (its tree is the record), then any URL a host registered directly
+    const targets = [...(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 = {
+        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 = [];
+    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;
+}

package/dist/src/stripe-js.d.ts

@@ -0,0 +1,4 @@
+/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
+export declare function stripeJsTrain(pathname: string): 3 | string | undefined;
+/** js.stripe.com's script for a GET of its path, or undefined for any other request. */
+export declare function stripeJs(request: Request): Response | undefined;

package/dist/src/stripe-js.js

@@ -0,0 +1,70 @@
+// STRIPE.JS — the client library an application's page loads from js.stripe.com (docs/contributing/architecture.md,
+// "Screens": a widget the vendor ships into the application's own page "is not a screen: it is a client library,
+// twinned from its published types as an SDK surface is"). Written from @stripe/stripe-js's published loader and types
+// (7.x: dist/index.mjs, dist/stripe-js/stripe.d.ts, dist/stripe-js/hosted-checkout.d.ts), nothing of Stripe's script
+// copied:
+//   - the loader injects https://js.stripe.com/<release train>/stripe.js (or /v3/), and accepts a script already on the
+//     page whose src matches `/^https:\/\/js\.stripe\.com\/(v3|[a-z]+)\/stripe\.js(\?.*)?$/` (so /v3/stripe.js too);
+//     it resolves `window.Stripe`, reads `Stripe.version` (3 is the v3 URL, otherwise the train's name) and calls the
+//     instance's `_registerWrapper` when it has one;
+//   - `stripe.redirectToCheckout({ sessionId })` sends the customer to that Checkout Session's page (hosted-checkout.d.ts,
+//     RedirectToCheckoutServerOptions), which this twin serves at checkout.stripe.com/c/pay/{id} (screens/checkout.tsx),
+//     and its promise settles only on failure (`Promise<never | {error}>`);
+//   - `stripe.collectFinancialConnectionsAccounts({ clientSecret })` loads the Financial Connections authentication
+//     flow for the session whose client_secret it is (stripe.d.ts; docs.stripe.com/js/financial_connections/
+//     collect_financial_connections_accounts: "it will load the Authentication Flow, an on-page modal UI"). Where the
+//     twin decides: it navigates to the flow's page, js.stripe.com/v3/financial-connections/{client_secret}
+//     (screens/financial-connections.tsx), instead of a modal, so its promise does not settle; the flow returns the
+//     holder to the session's return_url, where the application reads the session's accounts.
+// Demand: Dub's upgrade button (apps/web/ui/workspaces/upgrade-plan-button.tsx) creates a session on its server and
+// calls redirectToCheckout. Every other member of the library throws, naming itself, when called: an application
+// reaching one finds the gap instead of a silent no-op.
+/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
+export function stripeJsTrain(pathname) {
+    if (/^\/v3(\/|\/stripe\.js)?$/.test(pathname))
+        return 3;
+    return /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
+}
+function script(version) {
+    return `(function () {
+  var version = ${JSON.stringify(version)};
+  function gap(name) {
+    return function () { throw new Error("Stripe.js (Volter twin): stripe." + name + " is not modelled by this twin yet"); };
+  }
+  function Stripe(publishableKey) {
+    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
+    var known = {
+      _registerWrapper: function () {},
+      redirectToCheckout: function (options) {
+        if (!options || typeof options.sessionId !== "string" || !options.sessionId) return gap("redirectToCheckout without a sessionId")();
+        window.location.assign("https://checkout.stripe.com/c/pay/" + encodeURIComponent(options.sessionId));
+        return new Promise(function () {});
+      },
+      collectFinancialConnectionsAccounts: function (options) {
+        if (!options || typeof options.clientSecret !== "string" || !options.clientSecret) return gap("collectFinancialConnectionsAccounts without a clientSecret")();
+        window.location.assign("https://js.stripe.com/v3/financial-connections/" + encodeURIComponent(options.clientSecret));
+        return new Promise(function () {});
+      }
+    };
+    return new Proxy(known, {
+      get: function (target, name) {
+        if (name in target) return target[name];
+        if (typeof name === "symbol" || name === "then") return undefined;
+        return gap(String(name));
+      }
+    });
+  }
+  Stripe.version = version;
+  window.Stripe = Stripe;
+})();
+`;
+}
+/** js.stripe.com's script for a GET of its path, or undefined for any other request. */
+export function stripeJs(request) {
+    if (request.method !== 'GET')
+        return undefined;
+    const train = stripeJsTrain(new URL(request.url).pathname);
+    if (train === undefined)
+        return undefined;
+    return new Response(script(train), { headers: { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*' } });
+}

package/dist/src/stripe-mirror-ui.d.ts

@@ -0,0 +1,15 @@
+export * from './stripe-shared.js';
+/** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
+export declare function buildStripeMirrorClient(): Promise<string>;
+/** Serve the Stripe Dashboard (React app) with the twin's own fetch adapter mounted beside it. */
+export declare function createStripeMirrorServer(options: {
+    root?: string;
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure, for tests). The Dashboard itself is the React client. */
+export declare function stripeMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function stripeMirrorStyles(): Promise<string>;

package/dist/src/stripe-mirror-ui.js

@@ -0,0 +1,87 @@
+// The Stripe Dashboard (manifest screen `dashboard`, dashboard.stripe.com/test/{section}): a React app
+// (Bun-bundled) served beside the twin. A PURE FRONTEND (runtime contract R3): this module is the shell, its
+// assets and one listener that mounts the pack's OWN fetch adapter beside them. It imports no handler and no
+// 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 { serveHttp } from '@volter/world-core';
+import { createStripeTwinFetch } from "./stripe-server.js";
+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.
+//
+// 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/world-core`/`Bun`/twin-adapter usage.
+// ---------------------------------------------------------------------------
+export * from "./stripe-shared.js";
+import { flattenStripeValue, resolveCrossRefs } from "./stripe-shared.js";
+void flattenStripeValue;
+void resolveCrossRefs;
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>Dashboard – Stripe</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+let clientBundle = null;
+/** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
+export function buildStripeMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+/** Serve the Stripe Dashboard (React app) with the twin's own fetch adapter mounted beside it. */
+export async function createStripeMirrorServer(options) {
+    const twin = createStripeTwinFetch(options);
+    const server = await serveHttp({
+        // 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) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildStripeMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            // the Dashboard's own paths (/test/payments, /test/customers/cus_…) are the app; `/` opens Home
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '' || url.pathname === '/test' || url.pathname.startsWith('/test/'))) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // 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) };
+}
+/** The app-shell HTML (pure, for tests). The Dashboard itself is the React client. */
+export function stripeMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function stripeMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/stripe-params.d.ts

@@ -0,0 +1,3 @@
+import { type DerivedCall } from '@volter/world-core';
+/** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
+export declare function refuseParameters(call: DerivedCall): Promise<Response | undefined>;

package/dist/src/stripe-params.js

@@ -0,0 +1,43 @@
+// STRIPE'S PARAMETER CHECK — every API request's top-level parameters against the operation's own in the vendored
+// spec, before any handler reads them. Stripe refuses a parameter the operation does not take with
+// `400 parameter_unknown` ("Received unknown parameter: …", docs.stripe.com/error-codes#parameter-unknown) and a
+// required one left out with `400 parameter_missing` ("Missing required param: …",
+// docs.stripe.com/error-codes#parameter-missing). Without this check a handler read whatever it was sent, so a
+// parameter Stripe had removed (a promotion code's top-level `coupon`, replaced by `promotion[coupon]` in
+// 2025-09-30.clover) was accepted.
+//
+// Where the evidence stops: the check knows only the served version's parameters (the spec's, surface.version). A
+// request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec;
+// nested parameters are not checked.
+import { readParams, vendorError } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { SERVED_VERSION } from "./stripe-version.js";
+const OPS = new Map(surface.operations.map((o) => [o.id, o]));
+/** Parameters Stripe documents outside its published spec, each with the page that documents it. */
+const DOCUMENTED = {
+    // a top-up into the Issuing balance (docs.stripe.com/issuing/funding/balance: "destination_balance=issuing")
+    PostTopups: ['destination_balance'],
+};
+/** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
+export async function refuseParameters(call) {
+    const op = OPS.get(call.operation.id);
+    if (!op)
+        return undefined;
+    const pinned = call.request.headers.get('stripe-version');
+    if (pinned && pinned < SERVED_VERSION)
+        return undefined;
+    const method = call.request.method.toUpperCase();
+    const known = new Set([...(op.query ?? []), ...(op.body ?? [])].map((p) => p.name).concat(DOCUMENTED[op.id] ?? []));
+    const params = await readParams(manifest, call.request.clone(), call.operation);
+    for (const name of Object.keys(params)) {
+        if (!known.has(name))
+            return vendorError(manifest, { status: 400, code: 'parameter_unknown', param: name, message: `Received unknown parameter: ${name}` });
+    }
+    const required = method === 'GET' || method === 'DELETE' ? (op.query ?? []) : (op.body ?? []);
+    for (const p of required) {
+        if (p.required && params[p.name] === undefined)
+            return vendorError(manifest, { status: 400, code: 'parameter_missing', param: p.name, message: `Missing required param: ${p.name}.` });
+    }
+    return undefined;
+}

package/dist/src/stripe-perform-harness.d.ts

@@ -0,0 +1,9 @@
+import { type StripeExecute } from './stripe-connector.js';
+export declare function performPending(execute: StripeExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+}>;