@agent-cards/checkout 0.4.1 → 0.6.0

package/dist/preparation.js

@@ -1,4 +1,5 @@
 import { CheckoutPreparationError } from './client.js';
+import { matchesPreparedRequest, validPreparationEnvironment, preparationEndpoint } from './prepared-processor.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
     opts;
@@ -33,9 +34,9 @@ export class PreparationGate {
         const onAbort = () => this.invalidate('cancelled');
         signal.addEventListener('abort', onAbort, { once: true });
         try {
-            if (!options || options.psp !== 'square' || !['production', 'sandbox'].includes(options.environment))
+            if (!options || !validPreparationEnvironment(options.psp, options.environment))
                 throw new CheckoutPreparationError(null, 'unsupported_processor');
-            const tokenizer = options.environment === 'production' ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
+            const tokenizer = preparationEndpoint(options.psp, options.environment);
             if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
                 throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
             if (!Number.isSafeInteger(this.opts.amountCents) || (this.opts.amountCents ?? 0) <= 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
@@ -62,6 +63,8 @@ export class PreparationGate {
                 },
             });
             this.prepared = prepared;
+            if (prepared.psp !== options.psp || prepared.environment !== options.environment)
+                throw new CheckoutPreparationError(prepared.id, 'checkout_changed');
             if (signal.aborted || this.state !== 'preparing') {
                 void this.opts.vault.cancelPreparation(prepared.id).catch(() => { });
                 throw new CheckoutPreparationError(prepared.id, 'cancelled');
@@ -86,7 +89,7 @@ export class PreparationGate {
         // Keep the signal listener after ready: caller cancellation retires the handle too.
     }
     /** Called for every recognized card mutation, before any await or local retry guard. */
-    claim(requestUrl) {
+    claim(requestUrl, requestBody) {
         this.observedRequest = true;
         if (this.state === 'unused')
             return undefined;
@@ -95,9 +98,7 @@ export class PreparationGate {
             throw new CheckoutPreparationError(this.prepared?.id ?? null, 'already_used_or_unavailable');
         }
         const prepared = this.prepared;
-        const request = new URL(requestUrl);
-        const origin = prepared.environment === 'production' ? 'https://pci-connect.squareup.com' : 'https://pci-connect.squareupsandbox.com';
-        if (Date.parse(prepared.expiresAt) <= Date.now() || request.origin !== origin || request.pathname !== '/v2/card-nonce' || request.username || request.password) {
+        if (Date.parse(prepared.expiresAt) <= Date.now() || !matchesPreparedRequest(prepared.psp, prepared.environment, requestUrl, 'POST', requestBody)) {
             const reason = Date.parse(prepared.expiresAt) <= Date.now() ? 'expired' : 'checkout_changed';
             this.invalidate(reason);
             throw new CheckoutPreparationError(prepared.id, reason);

package/dist/prepared-processor.d.ts

@@ -0,0 +1,7 @@
+export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago';
+export type PreparationEnvironment = 'production' | 'sandbox' | 'shared';
+/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
+export declare function validPreparationEnvironment(psp: string, environment: string): boolean;
+export declare function preparationEndpoint(psp: PreparationProcessor, environment: PreparationEnvironment): string;
+/** Processor identity and environment are part of the device's prior consent. */
+export declare function matchesPreparedRequest(psp: PreparationProcessor, environment: PreparationEnvironment, requestUrl: string, method: string, body?: string | null): boolean;

package/dist/prepared-processor.js

@@ -0,0 +1,93 @@
+import { braintreeEnvironment, isPreparedBraintreeRequest, readTokenizationJson } from './braintree.js';
+/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
+export function validPreparationEnvironment(psp, environment) {
+    if (psp === 'bambora' || psp === 'mercado_pago')
+        return environment === 'shared';
+    return ['square', 'braintree', 'worldpay'].includes(psp) && ['production', 'sandbox'].includes(environment);
+}
+export function preparationEndpoint(psp, environment) {
+    if (!validPreparationEnvironment(psp, environment))
+        throw new Error('unsupported_preparation_processor');
+    if (psp === 'bambora')
+        return 'https://api.bam.shift4api.net/scripts/tokenization/tokens';
+    if (psp === 'mercado_pago')
+        return 'https://api.mercadopago.com/v1/card_tokens';
+    if (psp === 'worldpay')
+        return environment === 'production'
+            ? 'https://access.worldpay.com/sessions/card' : 'https://try.access.worldpay.com/sessions/card';
+    if (psp === 'braintree')
+        return environment === 'production'
+            ? 'https://payments.braintree-api.com/graphql' : 'https://payments.sandbox.braintree-api.com/graphql';
+    return environment === 'production'
+        ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const keys = (value, allowed) => Object.keys(value).every(key => allowed.includes(key));
+const string = (value, max = 1024) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+const digits = (value, min, max) => typeof value === 'string' && value.length >= min && value.length <= max && !/[^0-9]/.test(value);
+const month = (value) => (typeof value === 'number' && Number.isInteger(value) || digits(value, 1, 2)) && Number(value) >= 1 && Number(value) <= 12;
+const year = (value) => (typeof value === 'number' && Number.isInteger(value) || digits(value, 2, 4)) && (Number(value) >= 0 && Number(value) <= 99 || Number(value) >= 2000 && Number(value) <= 9999);
+/** Native fresh-card shapes only. Saved-card, charge and recurring siblings never consume consent. */
+function freshCardBody(psp, body) {
+    const value = readTokenizationJson(body);
+    if (!value)
+        return false;
+    if (psp === 'worldpay')
+        return keys(value, ['identity', 'cardNumber', 'cardExpiryDate', 'cvc'])
+            && string(value.identity) && digits(value.cardNumber, 12, 19)
+            && record(value.cardExpiryDate) && keys(value.cardExpiryDate, ['month', 'year'])
+            && month(value.cardExpiryDate.month) && year(value.cardExpiryDate.year)
+            && (value.cvc === undefined || digits(value.cvc, 3, 4));
+    if (psp === 'bambora')
+        return keys(value, ['number', 'expiry_month', 'expiry_year', 'cvd'])
+            && digits(value.number, 12, 19) && month(value.expiry_month) && year(value.expiry_year)
+            && (value.cvd === undefined || digits(value.cvd, 3, 4));
+    if (psp !== 'mercado_pago' || !keys(value, ['card_number', 'expiration_month', 'expiration_year', 'security_code', 'cardholder', 'device'])
+        || !digits(value.card_number, 12, 19) || !month(value.expiration_month) || !year(value.expiration_year)
+        || (value.security_code !== undefined && value.security_code !== '' && !digits(value.security_code, 3, 4)) || !record(value.cardholder)
+        || !keys(value.cardholder, ['name', 'identification']))
+        return false;
+    const holder = value.cardholder;
+    if (holder.name !== undefined && holder.name !== '' && !string(holder.name))
+        return false;
+    if (holder.identification !== undefined && (!record(holder.identification) || !keys(holder.identification, ['type', 'number'])
+        || Object.values(holder.identification).some(v => v !== '' && !string(v))))
+        return false;
+    if (value.device !== undefined && (!record(value.device) || !keys(value.device, ['meli'])
+        || !record(value.device.meli) || !keys(value.device.meli, ['session_id']) || !string(value.device.meli.session_id, 4096)))
+        return false;
+    return true;
+}
+/** Processor identity and environment are part of the device's prior consent. */
+export function matchesPreparedRequest(psp, environment, requestUrl, method, body) {
+    if (method.toUpperCase() !== 'POST' || !validPreparationEnvironment(psp, environment))
+        return false;
+    if (psp === 'braintree')
+        return braintreeEnvironment(requestUrl) === environment && isPreparedBraintreeRequest(body ?? null);
+    try {
+        const request = new URL(requestUrl), endpoint = new URL(preparationEndpoint(psp, environment));
+        if (request.username || request.password || request.hash)
+            return false;
+        if (psp === 'bambora') {
+            if (![endpoint.href, 'https://api.na.bambora.com/scripts/tokenization/tokens'].includes(requestUrl))
+                return false;
+        }
+        else if (psp === 'worldpay') {
+            if (requestUrl !== endpoint.href)
+                return false;
+        }
+        else if (request.origin !== endpoint.origin || request.pathname !== endpoint.pathname)
+            return false;
+        if (psp === 'mercado_pago') {
+            const names = [...request.searchParams.keys()];
+            if (new Set(names).size !== names.length || names.some(name => !['public_key', 'locale', 'js_version', 'referer'].includes(name)))
+                return false;
+        }
+        return psp === 'square' || freshCardBody(psp, body ?? null);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/registry.js

@@ -48,8 +48,12 @@ export const BUILTIN_REGISTRY = [
     },
     {
         psp: 'checkout_com',
-        match: /api(\.sandbox)?\.checkout\.com\/tokens/i,
-        hosts: ["^api\\.checkout\\.com$", "^api\\.sandbox\\.checkout\\.com$"],
+        // Flow's native card controller can use either tokenization host.
+        match: /(api|card-acquisition-gateway)(\.sandbox)?\.checkout\.com\/tokens/i,
+        hosts: [
+            "^api\\.checkout\\.com$", "^api\\.sandbox\\.checkout\\.com$",
+            "^card-acquisition-gateway\\.checkout\\.com$", "^card-acquisition-gateway\\.sandbox\\.checkout\\.com$",
+        ],
         encoding: 'json',
         passthroughHeaders: [/^authorization$/i],
     },
@@ -156,10 +160,10 @@ export const BUILTIN_REGISTRY = [
     },
     {
         psp: 'paysafe',
-        match: /api(\.test)?\.paysafe\.com\/(?:paymenthub\/v1\/singleusepaymenthandles|js\/api\/v1\/tokenize)(?![\w\/-])/i,
-        hosts: ["^api\\.paysafe\\.com$", "^api\\.test\\.paysafe\\.com$"],
+        match: /(?:api(\.test)?\.paysafe\.com\/(?:paymenthub\/v1\/singleusepaymenthandles|js\/api\/v1\/tokenize)|hosted(\.test)?\.paysafe\.com\/checkout\/api\/v1\/tokenize)(?![\w\/-])/i,
+        hosts: ["^api\\.paysafe\\.com$", "^api\\.test\\.paysafe\\.com$", "^hosted\\.paysafe\\.com$", "^hosted\\.test\\.paysafe\\.com$"],
         encoding: 'json',
-        passthroughHeaders: [/^authorization$/i, /^x-paysafe-credentials$/i],
+        passthroughHeaders: [/^authorization$/i, /^x-paysafe-credentials$/i, /^correlationid$/i],
     },
     {
         psp: 'recurly',
@@ -211,7 +215,7 @@ export function findRecognizer(url, registry = BUILTIN_REGISTRY) {
     catch {
         return null;
     }
-    if (parsed.protocol !== 'https:')
+    if (parsed.protocol !== 'https:' || parsed.port || parsed.username || parsed.password)
         return null;
     const hostPath = `${parsed.hostname.toLowerCase()}${parsed.pathname}`;
     return (registry.find((r) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "_comment_build": "TypeScript is fetched rather than declared as a devDependency ON PURPOSE. This package ships zero dependencies, which is why pnpm writes no importer for it in the workspace lockfile; adding any dep here creates one, and an importer the lockfile has not been regenerated for fails every Vercel build with ERR_PNPM_OUTDATED_LOCKFILE. Pinned so the published output is reproducible.",
     "build": "npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs",
     "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs"
   },
   "keywords": [