@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/stripe-events.js

@@ -1,392 +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.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) {
-    // 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) {
-    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.parse(worldNow()) / 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; 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, event, payload, secret) {
-    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: 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); 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, payload, header) {
-    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, 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

@@ -1,4 +0,0 @@
-/** 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

@@ -1,70 +0,0 @@
-// 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

@@ -1,15 +0,0 @@
-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

@@ -1,87 +0,0 @@
-// 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, filePathOf } from '@volter/world-core';
-import { serveHttp } from '@volter/world-core';
-import { createStripeTwinFetch } from "./stripe-server.js";
-const CLIENT_ENTRY = () => filePathOf(new URL('../client/stripe-mirror.tsx', import.meta.url)); // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-const CLIENT_CSS = () => filePathOf(new URL('../client/stripe-mirror.css', import.meta.url)); // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-// ---------------------------------------------------------------------------
-// Pure, dependency-free render/format/resolution helpers.
-//
-// 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-perform-harness.d.ts

@@ -1,9 +0,0 @@
-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>;
-}>;

package/dist/src/stripe-perform-harness.js

@@ -1,26 +0,0 @@
-// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). The kernel's loop
-// (`performEntries`) needs a bound root and a sealed credential a unit test does not have; this is the same
-// shape without one — the same `deployableEntries`, the pack's own push, the same `confirmAction`. Not on
-// the serve path, not exported from the pack.
-import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
-import { INTERNAL_SUBJECT_TYPES, isPushable, pushStripeAction } from "./stripe-connector.js";
-export async function performPending(execute, opts) {
-    const confirmed = [];
-    const externalIds = {};
-    for (const entry of deployableEntries('stripe', opts.root)) {
-        const op = entry.operation ?? `${entry.subject.type}.update`;
-        // the twin's own records — the recorded event envelopes and the idempotency bookkeeping — are local
-        // state and are never sent
-        if (INTERNAL_SUBJECT_TYPES.has(entry.subject.type) || !isPushable(op))
-            continue;
-        const { externalId } = await pushStripeAction(execute, { operation: op, subject: entry.subject, fields: entry.fields ?? {} });
-        confirmAction({
-            service: 'stripe', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
-            occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
-            ...(opts.root !== undefined ? { root: opts.root } : {}),
-        });
-        confirmed.push(entry.id);
-        externalIds[entry.id] = externalId;
-    }
-    return { pushed: confirmed.length, confirmed, externalIds };
-}

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

@@ -1,33 +0,0 @@
-import { type DerivedFetch } from '@volter/world-core';
-/** 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 World instant, when a caller pins it */
-    clock?: () => string;
-};
-/**
- * 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 derived dispatch over the hand-written routes. 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 declare function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch;
-export declare function createStripeTwinServer(options: StripeTwinOptions): Promise<{
-    port: number;
-    stop: () => void;
-}>;