@agent-cards/checkout 0.2.0 → 0.2.1

package/README.md

@@ -126,6 +126,7 @@ Merchants inherit their processor, so one entry covers every store on it.
 | Stripe | supported, verified end to end |
 | Braintree / PayPal | supported, verified end to end |
 | Checkout.com | supported |
+| VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
 | Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it |
 | Tranzila | supported (mode `hosted_form`): the cardholder finishes on Tranzila's own page; the paused form navigation resolves to a synthetic page, and you poll the merchant's order state |
 
@@ -146,7 +147,20 @@ three; the difference matters if you drive `authorize()` yourself.
 
 - **`token`** (every processor but Adyen). The cardholder's device calls the
   processor and reports its answer; `authorize()` resolves with `status`,
-  `headers` and `body` to fulfill the paused request with.
+  `headers` and `body` to fulfill the paused request with. The browser checks
+  a fulfilled answer exactly as it checks a real one, so when the page called
+  the processor cross-origin (Stripe always does: Checkout on
+  `checkout.stripe.com` and Elements in the `js.stripe.com` frame both fetch
+  `api.stripe.com`) the answer must carry `access-control-allow-origin` for
+  the request's own `Origin`, or the page's fetch rejects and the checkout
+  reports a connection error even though the cardholder approved. The
+  adapters add those headers (`corsHeadersFor` + `withCorsHeaders`, exported
+  for a runtime that fulfills by hand, and `corsDecision` when you also want
+  the reason) and report the decision on the `authorized` event as `cors`:
+  `echoed`, `same_origin`, or `none` (no usable Origin on the request, so
+  the page could not read the answer). Only what a browser serializes is
+  echoed: one canonical http(s) origin, or the opaque `null`. Shopify's
+  card iframe posts to its own origin, so it never needed them.
 - **`cse`** (Adyen). Adyen's own page SDK encrypts the card before the request
   leaves the browser, so the paused body carries ciphertext. The cardholder's
   device produces the same ciphertext under the merchant's Adyen public key

package/dist/cdp.d.ts

@@ -1,4 +1,67 @@
 import { type VaultClient } from './client.js';
+/**
+ * The CORS headers a fulfilled CROSS-ORIGIN request needs, or null when the
+ * request is same-origin (or carries no Origin, so no CORS check applies).
+ *
+ * The browser checks a fulfilled response exactly as it checks a real one. A
+ * page that fetches a processor on another origin therefore needs
+ * `access-control-allow-origin` on the synthetic answer, or its fetch rejects
+ * with "Failed to fetch" and the page never sees the processor's reply, even
+ * though the cardholder approved and the processor answered the vault.
+ * Shopify never hit this on its current host: the checkout.pci.shopifyinc.com
+ * card iframe posts to its own origin (its older deposit.<region>.shopifycs.com
+ * host is called from the checkout.shopifycs.com frame, cross-origin, and gets
+ * the answer like everyone else). Stripe hits it on every surface (Checkout on
+ * checkout.stripe.com or a merchant domain, and Elements in the js.stripe.com
+ * frame, all call api.stripe.com), and so does every other processor whose
+ * card frame calls a separate API host. Observed live on
+ * 2026-09-03: the vault replayed a Stripe PaymentMethod into a raw-CDP
+ * runtime, the browser refused the answer for want of this header, and
+ * Stripe Checkout showed "We are experiencing connection issues".
+ *
+ * The exact Origin is echoed rather than `*`: a credentialed request refuses
+ * `*`, the echo satisfies both. The processor's own value can never reach
+ * this adapter (a browser does not expose that header to the page that
+ * replayed the call), so whatever the replay carries under these names is
+ * replaced by the one value that is right for THIS request. Playwright adds
+ * the same headers inside route.fulfill when a cross-origin fulfill carries
+ * none (microsoft/playwright#12929), which is why attachToPlaywright never
+ * needed this; it writes them itself anyway, replacing a stale value, so both
+ * adapters answer the vault's replays identically.
+ *
+ * This widens nothing. A tokenization endpoint is built for anonymous
+ * browsers and answers every origin (`access-control-allow-origin: *` on
+ * Stripe's and Shopify's own replies), so the page that made the request
+ * could always read the processor's answer to it; the replay is made exactly
+ * as visible, to exactly that page. Whether a card goes anywhere at all is
+ * decided by the cardholder on the approval screen, never by this header.
+ *
+ * Only what a browser serializes is ever echoed: one canonical http(s)
+ * origin (`new URL(origin).origin === origin`), or the opaque `null` a
+ * sandboxed or data: document sends, which Chrome matches against
+ * `access-control-allow-origin: null` and which Playwright echoes too. That
+ * refuses userinfo, a path, an explicit default port, several origins in one
+ * value, or a control character that would break the fulfill after the
+ * cardholder already approved. Anything refused simply gets no CORS answer,
+ * which is what every fulfill got before this existed.
+ */
+export declare function corsHeadersFor(url: string, requestHeaders: Record<string, string> | undefined): Record<string, string> | null;
+/** How a fulfill was answered, reported on the `authorized` event so a silent CORS failure is diagnosable from events alone. */
+export type CorsOutcome = 'echoed' | 'same_origin' | 'none';
+/** The CORS answer and its reason: `none` when no usable Origin was sent (or the url is not http(s)), `same_origin` when no check applies. */
+export declare function corsDecision(url: string, requestHeaders: Record<string, string> | undefined): {
+    headers: Record<string, string> | null;
+    outcome: CorsOutcome;
+};
+/**
+ * `headers` with the CORS answer for this request written in; the object
+ * itself when none is needed. Any header the answer names is replaced
+ * whatever its case, so a name is never sent twice. The answer varies by
+ * Origin, and a `vary` the replay already carries is extended rather than
+ * replaced (or left alone when it already covers Origin or is `*`); a `vary`
+ * the answer itself names is taken as given.
+ */
+export declare function withCorsHeaders(headers: Record<string, string>, cors: Record<string, string> | null): Record<string, string>;
 /**
  * Minimal shape of a CDP connection. Works with a raw websocket client, a
  * Puppeteer CDPSession, or Playwright's CDPSession.

package/dist/cdp.js

@@ -141,6 +141,128 @@ function pausedBody(request) {
     return Buffer.concat(entries.map((e) => Buffer.from(e.bytes, 'base64'))).toString('utf8');
 }
 const BODY_UNREADABLE_REASON = 'the paused request\'s body could not be read (no postData and no postDataEntries)';
+/**
+ * The CORS headers a fulfilled CROSS-ORIGIN request needs, or null when the
+ * request is same-origin (or carries no Origin, so no CORS check applies).
+ *
+ * The browser checks a fulfilled response exactly as it checks a real one. A
+ * page that fetches a processor on another origin therefore needs
+ * `access-control-allow-origin` on the synthetic answer, or its fetch rejects
+ * with "Failed to fetch" and the page never sees the processor's reply, even
+ * though the cardholder approved and the processor answered the vault.
+ * Shopify never hit this on its current host: the checkout.pci.shopifyinc.com
+ * card iframe posts to its own origin (its older deposit.<region>.shopifycs.com
+ * host is called from the checkout.shopifycs.com frame, cross-origin, and gets
+ * the answer like everyone else). Stripe hits it on every surface (Checkout on
+ * checkout.stripe.com or a merchant domain, and Elements in the js.stripe.com
+ * frame, all call api.stripe.com), and so does every other processor whose
+ * card frame calls a separate API host. Observed live on
+ * 2026-09-03: the vault replayed a Stripe PaymentMethod into a raw-CDP
+ * runtime, the browser refused the answer for want of this header, and
+ * Stripe Checkout showed "We are experiencing connection issues".
+ *
+ * The exact Origin is echoed rather than `*`: a credentialed request refuses
+ * `*`, the echo satisfies both. The processor's own value can never reach
+ * this adapter (a browser does not expose that header to the page that
+ * replayed the call), so whatever the replay carries under these names is
+ * replaced by the one value that is right for THIS request. Playwright adds
+ * the same headers inside route.fulfill when a cross-origin fulfill carries
+ * none (microsoft/playwright#12929), which is why attachToPlaywright never
+ * needed this; it writes them itself anyway, replacing a stale value, so both
+ * adapters answer the vault's replays identically.
+ *
+ * This widens nothing. A tokenization endpoint is built for anonymous
+ * browsers and answers every origin (`access-control-allow-origin: *` on
+ * Stripe's and Shopify's own replies), so the page that made the request
+ * could always read the processor's answer to it; the replay is made exactly
+ * as visible, to exactly that page. Whether a card goes anywhere at all is
+ * decided by the cardholder on the approval screen, never by this header.
+ *
+ * Only what a browser serializes is ever echoed: one canonical http(s)
+ * origin (`new URL(origin).origin === origin`), or the opaque `null` a
+ * sandboxed or data: document sends, which Chrome matches against
+ * `access-control-allow-origin: null` and which Playwright echoes too. That
+ * refuses userinfo, a path, an explicit default port, several origins in one
+ * value, or a control character that would break the fulfill after the
+ * cardholder already approved. Anything refused simply gets no CORS answer,
+ * which is what every fulfill got before this existed.
+ */
+export function corsHeadersFor(url, requestHeaders) {
+    return corsDecision(url, requestHeaders).headers;
+}
+/** The CORS answer and its reason: `none` when no usable Origin was sent (or the url is not http(s)), `same_origin` when no check applies. */
+export function corsDecision(url, requestHeaders) {
+    const none = { headers: null, outcome: 'none' };
+    const originEntry = Object.entries(requestHeaders ?? {}).find(([name]) => name.toLowerCase() === 'origin');
+    const origin = typeof originEntry?.[1] === 'string' ? originEntry[1].trim() : '';
+    if (!origin)
+        return none;
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return none;
+    }
+    if (target.protocol !== 'https:' && target.protocol !== 'http:')
+        return none;
+    if (origin !== 'null') {
+        let originUrl;
+        try {
+            originUrl = new URL(origin);
+        }
+        catch {
+            return none;
+        }
+        if (originUrl.protocol !== 'https:' && originUrl.protocol !== 'http:')
+            return none;
+        if (originUrl.origin !== origin)
+            return none;
+        if (target.origin === origin)
+            return { headers: null, outcome: 'same_origin' };
+    }
+    return { headers: { 'access-control-allow-origin': origin, 'access-control-allow-credentials': 'true' }, outcome: 'echoed' };
+}
+/**
+ * `headers` with the CORS answer for this request written in; the object
+ * itself when none is needed. Any header the answer names is replaced
+ * whatever its case, so a name is never sent twice. The answer varies by
+ * Origin, and a `vary` the replay already carries is extended rather than
+ * replaced (or left alone when it already covers Origin or is `*`); a `vary`
+ * the answer itself names is taken as given.
+ */
+export function withCorsHeaders(headers, cors) {
+    if (!cors)
+        return headers;
+    const replaced = new Set(Object.keys(cors).map((name) => name.toLowerCase()));
+    const out = {};
+    let varyName = null;
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (replaced.has(lower))
+            continue;
+        if (lower === 'vary')
+            varyName = name;
+        out[name] = value;
+    }
+    Object.assign(out, cors);
+    if (replaced.has('vary'))
+        return out;
+    if (varyName === null) {
+        out.vary = 'Origin';
+    }
+    else {
+        const existing = String(out[varyName]);
+        const members = existing.split(',').map((m) => m.trim().toLowerCase());
+        if (!members.includes('origin') && !members.includes('*'))
+            out[varyName] = `${existing}, Origin`;
+    }
+    return out;
+}
+/** CDP's header shape: `{ name, value }` entries. */
+function headerEntries(headers) {
+    return Object.entries(headers).map(([name, value]) => ({ name, value: String(value) }));
+}
 /**
  * Last-resort patterns: the built-in recognizers' hosts, derived the same way
  * as everything else. Used only when the vault hands back nothing at all (a
@@ -255,10 +377,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // why not a fake result page), and the same form is refused if the
                 // page posts it again.
                 const page = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                // A navigation response is never CORS-checked, so the CORS wrap is
+                // inert here; it is applied so every fulfill goes through one path.
                 await cdp.send('Fetch.fulfillRequest', {
                     requestId,
                     responseCode: page.status,
-                    responseHeaders: Object.entries(page.headers).map(([name, value]) => ({ name, value })),
+                    responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(request.url, request.headers))),
                     body: Buffer.from(page.body).toString('base64'),
                 }, sessionId);
                 lastSubmitted = { url: request.url, body, at: Date.now() };
@@ -279,13 +403,20 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
+                // The processor's answer, handed to the page as if the processor had
+                // sent it. Cross-origin, the browser then runs its CORS check on it:
+                // see corsHeadersFor for why the answer has to carry the headers. The
+                // decision rides on the event, so a fulfill the page could not read
+                // (no usable Origin on a cross-origin request) is visible in telemetry
+                // rather than only as the page's own "connection error".
+                const cors = corsDecision(request.url, request.headers);
                 await cdp.send('Fetch.fulfillRequest', {
                     requestId,
                     responseCode: replay.status,
-                    responseHeaders: Object.entries(replay.headers).map(([name, value]) => ({ name, value: String(value) })),
+                    responseHeaders: headerEntries(withCorsHeaders(replay.headers, cors.headers)),
                     body: Buffer.from(replay.body).toString('base64'),
                 }, sessionId);
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null } });
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
         }
         catch (err) {
@@ -375,7 +506,8 @@ export async function attachToPlaywright(page, opts) {
                 // Same as the CDP path: the paused navigation resolves to the
                 // synthetic page, and a re-post of this form is refused.
                 const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
-                await route.fulfill({ status: synthetic.status, headers: synthetic.headers, body: synthetic.body });
+                // Inert on a navigation (never CORS-checked); one path for every fulfill.
+                await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
                 lastSubmitted = { url: request.url(), body, at: Date.now() };
                 opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
             }
@@ -387,8 +519,12 @@ export async function attachToPlaywright(page, opts) {
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
-                await route.fulfill({ status: replay.status, headers: replay.headers, body: replay.body });
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null } });
+                // Playwright adds these itself when a cross-origin fulfill carries
+                // none; written here anyway (replacing a stale value) so a
+                // cross-origin answer is the same whichever adapter ran.
+                const cors = corsDecision(request.url(), request.headers());
+                await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
         }
         catch (err) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, } from './client.js';
 export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, } from './client.js';
-export { attachToCdp, attachToPlaywright } from './cdp.js';
-export type { CdpLike, AttachOptions } from './cdp.js';
+export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export type { Substitutions } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, } from './client.js';
-export { attachToCdp, attachToPlaywright } from './cdp.js';
+export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",