@visa/cli 4.1.0-rc.155 → 4.1.0-rc.156

package/dist/checkout-engine/adapters/generic.d.ts

@@ -26,6 +26,38 @@ export declare function fillContactFieldMap(page: Page, fields: FieldMap, contac
 export declare function fillFieldMap(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact, opts?: {
     fillTimeoutMs?: number;
 }): Promise<FilledField[]>;
+/**
+ * Re-detect and adopt fresh entries for every card field after the panel is
+ * unfolded. Injected for tests; the executor's own detector is used in
+ * production.
+ */
+export declare function refreshCardGroupFromPage(page: Page, fields: FieldMap, detect?: (page: Page) => Promise<DetectResult>): Promise<string[]>;
+/**
+ * Reveal card fields that a checkout keeps collapsed until a payment method is
+ * chosen.
+ *
+ * `fillFields` skips any entry with `visible === false`, so a card-number input
+ * sitting inside a folded panel is never even attempted — the generic adapter
+ * then reports `ok: false` ("fill incomplete") without having typed anything.
+ * That is the correct default: filling an invisible input is how a credential
+ * gets typed into the wrong place. But a payment-method `<select>` guarding the
+ * card panel is common enough to be worth handling, and the recovery is a
+ * single deterministic interaction rather than a guess.
+ *
+ * We only ever SELECT a card option — never a wallet, bank transfer, or
+ * anything else — and we only act when the card field is already detected but
+ * hidden. If nothing changes, the caller proceeds exactly as before and still
+ * fails closed.
+ *
+ * Mutates `fields.number.visible` on success so the subsequent fill attempts
+ * the field it just revealed.
+ */
+export declare function revealCollapsedCardSection(page: Page, fields: FieldMap, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    revealed: boolean;
+    via: string | null;
+}>;
 export declare class GenericAdapter implements CheckoutAdapter {
     name: string;
     matches(_detected: DetectResult): boolean;

package/dist/checkout-engine/adapters/generic.js

@@ -2,6 +2,7 @@
 // <select> dropdowns, handles split vs combined expiry, two- vs four-digit
 // years, and split first/last name. It is the fallback that should beat any
 // well-behaved guest checkout on its own.
+import { detectFields } from '../detect.js';
 import { maskCvc, maskExpiry, maskPan, redactContact } from '../evidence.js';
 function pad2(n) {
     return String(n).padStart(2, '0');
@@ -212,6 +213,145 @@ export async function fillContactFieldMap(page, fields, contact, opts = {}) {
 export async function fillFieldMap(page, fields, credential, contact, opts = {}) {
     return fillFields(page, fields, credential, contact, opts);
 }
+/** Option text that identifies a card-paying choice, most specific first. */
+const CARD_OPTION_PATTERNS = [
+    /^\s*visa\s*$/i,
+    /credit\s*card|card\s*payment/i,
+    /^\s*(mastercard|master\s*card)\s*$/i,
+    /\bcard\b/i,
+];
+/**
+ * Attribute selectors for a card-number input that survive a panel re-render,
+ * tried in order. The originally detected locator is tried first so a page that
+ * does NOT re-render keeps its higher-confidence match.
+ */
+const CARD_NUMBER_FALLBACK_SELECTORS = [
+    'input[autocomplete="cc-number"]',
+    'input[name*="creditcardnumber" i]',
+    'input[name*="cardnumber" i]',
+    'input[id*="cardnumber" i]',
+    'input[name*="cc-number" i]',
+];
+/** First selector that resolves to a visible input, or null if none do. */
+async function firstVisibleCardNumberLocator(page, detectedLocator, timeoutMs) {
+    for (const selector of [detectedLocator, ...CARD_NUMBER_FALLBACK_SELECTORS]) {
+        try {
+            await page
+                .locator(selector)
+                .first()
+                .waitFor({ state: 'visible', timeout: Math.max(500, Math.floor(timeoutMs / 3)) });
+            return selector;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** Card-credential roles that share the panel a payment select unfolds. */
+const CARD_GROUP_ROLES = ['number', 'cvc', 'expCombined', 'expMonth', 'expYear'];
+/**
+ * Re-detect and adopt fresh entries for every card field after the panel is
+ * unfolded. Injected for tests; the executor's own detector is used in
+ * production.
+ */
+export async function refreshCardGroupFromPage(page, fields, detect = detectFields) {
+    let fresh;
+    try {
+        fresh = (await detect(page)).fields;
+    }
+    catch {
+        return [];
+    }
+    const adopted = [];
+    for (const role of CARD_GROUP_ROLES) {
+        const next = fresh[role];
+        if (!next || next.visible === false)
+            continue;
+        const current = fields[role];
+        // Only ever replace an entry we could not have filled anyway. A field that
+        // is already visible was detected against the live DOM and keeps its
+        // higher-confidence match.
+        if (current && current.visible !== false)
+            continue;
+        fields[role] = next;
+        adopted.push(role);
+    }
+    return adopted;
+}
+/**
+ * Reveal card fields that a checkout keeps collapsed until a payment method is
+ * chosen.
+ *
+ * `fillFields` skips any entry with `visible === false`, so a card-number input
+ * sitting inside a folded panel is never even attempted — the generic adapter
+ * then reports `ok: false` ("fill incomplete") without having typed anything.
+ * That is the correct default: filling an invisible input is how a credential
+ * gets typed into the wrong place. But a payment-method `<select>` guarding the
+ * card panel is common enough to be worth handling, and the recovery is a
+ * single deterministic interaction rather than a guess.
+ *
+ * We only ever SELECT a card option — never a wallet, bank transfer, or
+ * anything else — and we only act when the card field is already detected but
+ * hidden. If nothing changes, the caller proceeds exactly as before and still
+ * fails closed.
+ *
+ * Mutates `fields.number.visible` on success so the subsequent fill attempts
+ * the field it just revealed.
+ */
+export async function revealCollapsedCardSection(page, fields, opts = {}) {
+    const number = fields.number;
+    if (!number || number.visible !== false)
+        return { revealed: false, via: null };
+    const timeoutMs = opts.timeoutMs ?? 5_000;
+    const selects = page.locator('select');
+    const count = await selects.count().catch(() => 0);
+    for (let i = 0; i < Math.min(count, 12); i++) {
+        const select = selects.nth(i);
+        // Read option labels through the locator API rather than page.evaluate.
+        // A bundled build rewrites the function passed to evaluate() and the
+        // injected helper is not defined in page scope, so it throws at runtime —
+        // silently, once a catch treats it as "this select didn't match". Staying
+        // on the locator API keeps this working in source and bundled alike.
+        let labels;
+        try {
+            labels = await select.locator('option').allTextContents();
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of CARD_OPTION_PATTERNS) {
+            const label = labels.map((l) => l.trim()).find((l) => l && pattern.test(l));
+            if (!label)
+                continue;
+            try {
+                await select.selectOption({ label }, { timeout: timeoutMs });
+            }
+            catch {
+                continue;
+            }
+            // Re-acquire the field instead of waiting on the detected locator.
+            // Unfolding the panel typically re-renders it, and the detector's
+            // synthetic `data-ca-id` attribute does not survive that — waiting on the
+            // old locator times out even though the field is now on screen and
+            // fillable. Stable attribute selectors survive the re-render.
+            const revealedLocator = await firstVisibleCardNumberLocator(page, number.locator, timeoutMs);
+            if (!revealedLocator)
+                continue;
+            number.locator = revealedLocator;
+            number.visible = true;
+            // The number is not alone in that panel: cvc and expiry were re-rendered
+            // with it and still carry stale, invisible entries. Filling only the
+            // number would trade "adapter fill incomplete" for "credential fill
+            // incomplete: missing cvc, expiry" — still a failed purchase, still after
+            // a credential was minted. Re-detect and adopt fresh entries for the
+            // whole card group.
+            await refreshCardGroupFromPage(page, fields);
+            return { revealed: true, via: label };
+        }
+    }
+    return { revealed: false, via: null };
+}
 export class GenericAdapter {
     name = 'generic';
     matches(_detected) {
@@ -219,10 +359,17 @@ export class GenericAdapter {
         return true;
     }
     async fill(page, fields, credential, contact) {
+        const reveal = await revealCollapsedCardSection(page, fields);
         const filled = await fillFieldMap(page, fields, credential, contact);
+        const ok = filled.some((f) => f.role === 'number' && f.ok);
         return {
-            ok: filled.some((f) => f.role === 'number' && f.ok),
+            ok,
             filled,
+            ...(ok || !reveal.revealed
+                ? {}
+                : {
+                    detail: `revealed the card section via "${reveal.via}" but the number field still did not fill`,
+                }),
         };
     }
 }

package/dist/checkout-engine/executor.d.ts

@@ -5,6 +5,7 @@ import type { Instrument } from './instrument.js';
 import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
+import { type WebBotAuthConfig } from './web-bot-auth.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
 export type CheckoutOutcome = 'reviewed-dry-run'
@@ -35,6 +36,7 @@ export type PrepareCheckoutOptions = {
     amountMinor?: number;
     currency?: string;
     debugShotsDir?: string;
+    webBotAuth?: WebBotAuthConfig | null;
 };
 export type RunCheckoutOptions = PrepareCheckoutOptions & {
     instrument: Instrument;

package/dist/checkout-engine/executor.js

@@ -24,6 +24,7 @@ import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
 import { traceHandleFields } from './trace-handles.js';
 import { readGenericPageAmount } from './amount.js';
+import { webBotAuthHeadersOrNone } from './web-bot-auth.js';
 import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, shopifyEnglishCheckoutUrl, } from './adapters/shopify.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
@@ -679,7 +680,16 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
     // Accept-Language (observed live 2026-08-16: a Shopify checkout redirected
     // to /es-us and rendered "Impuestos estimados", so the total never parsed
     // and the review refused fail-closed on a perfectly good checkout).
-    const context = await options.browser.newContext({ locale: 'en-US' });
+    // Present Web Bot Auth (RFC 9421) credentials when, and only when, an
+    // operator directory is configured to resolve them. Off by default: an
+    // unresolvable signature fails verification and is worse than none. The
+    // signature covers @authority, so it is bound to the checkout host — a
+    // cross-origin redirect simply arrives unverified, never wrongly verified.
+    const webBotAuthHeaders = webBotAuthHeadersOrNone(options.webBotAuth ?? null, options.url, Date.now() / 1000);
+    const context = await options.browser.newContext({
+        locale: 'en-US',
+        ...(webBotAuthHeaders ? { extraHTTPHeaders: webBotAuthHeaders } : {}),
+    });
     // Bound every action so a mis-detected or hidden element fails fast instead
     // of stalling on Playwright's long default timeout.
     context.setDefaultTimeout(6000);

package/dist/checkout-engine/web-bot-auth.d.ts

@@ -0,0 +1,92 @@
+/** Signature validity ceiling. A signature is a bearer-ish artifact for as long
+ *  as it is valid, so the window stays short even if a caller asks for more. */
+export declare const WEB_BOT_AUTH_MAX_TTL_SECONDS = 300;
+/** Default validity. Long enough to survive a redirect chain and a slow TLS
+ *  handshake, short enough that a captured signature is near-useless. */
+export declare const WEB_BOT_AUTH_DEFAULT_TTL_SECONDS = 60;
+/** Label for the single signature we emit. RFC 9421 allows several per request. */
+export declare const WEB_BOT_AUTH_SIGNATURE_LABEL = "sig1";
+/** Tag fixed by the Web Bot Auth draft; verifiers select on it. */
+export declare const WEB_BOT_AUTH_TAG = "web-bot-auth";
+/** Components covered by the signature, in the order they appear in the base. */
+export declare const WEB_BOT_AUTH_COVERED_COMPONENTS: readonly ["@authority", "signature-agent"];
+/** Ed25519 private key in JWK form, as stored in the agent's runtime key file. */
+export interface WebBotAuthPrivateJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+    d: string;
+}
+export interface WebBotAuthSigningKey {
+    /** RFC 7638 thumbprint. Must match a `kid` published in the directory. */
+    keyId: string;
+    privateJwk: WebBotAuthPrivateJwk;
+}
+export interface WebBotAuthConfig {
+    /** Absolute https URL of the operator-hosted signature directory. */
+    directoryUrl: string;
+    key: WebBotAuthSigningKey;
+    ttlSeconds?: number;
+}
+export interface WebBotAuthHeaders {
+    'Signature-Input': string;
+    Signature: string;
+    'Signature-Agent': string;
+    [header: string]: string;
+}
+export interface SignatureBaseParams {
+    authority: string;
+    directoryUrl: string;
+    keyId: string;
+    created: number;
+    expires: number;
+}
+/**
+ * Build the RFC 9421 signature base.
+ *
+ * The base is what actually gets signed, so its exact bytes are the contract
+ * with every verifier — one wrong space or a reordered parameter and the
+ * signature fails against a correct key. It is exported and pinned by a
+ * deterministic test vector for that reason.
+ */
+export declare function buildSignatureBase(params: SignatureBaseParams): string;
+/**
+ * The `@signature-params` value, which appears twice: as the final line of the
+ * signature base, and verbatim as the `Signature-Input` header value. Building
+ * it once is what keeps those two identical — a verifier rederives the base
+ * from the header it received, so any divergence fails every signature.
+ */
+export declare function buildSignatureParams(params: SignatureBaseParams): string;
+export interface BuildHeadersParams {
+    /** Host (and port, if non-default) of the request being signed. */
+    authority: string;
+    config: WebBotAuthConfig;
+    /** Unix seconds. Injected so tests are deterministic and never wall-clock. */
+    nowSeconds: number;
+}
+/**
+ * Produce the three Web Bot Auth headers for one request authority.
+ *
+ * Throws on unusable key material rather than emitting an unverifiable
+ * signature. Callers on the checkout path must treat a throw as "proceed
+ * unsigned" — see `webBotAuthHeadersOrNone`.
+ */
+export declare function buildWebBotAuthHeaders(params: BuildHeadersParams): WebBotAuthHeaders;
+/**
+ * Header-or-nothing wrapper for the checkout path.
+ *
+ * Signing is an optional trust upgrade, never a precondition for buying
+ * something. Unusable key material, a malformed URL, or any crypto failure
+ * degrades to an unsigned request — which is exactly what we sent before this
+ * module existed — rather than throwing into a live checkout.
+ */
+export declare function webBotAuthHeadersOrNone(config: WebBotAuthConfig | null, targetUrl: string, nowSeconds: number): WebBotAuthHeaders | null;
+/**
+ * Resolve signing config from the environment. Returns `null` — meaning "send
+ * unsigned" — unless a directory URL and a usable key are BOTH present.
+ *
+ * Default-off is deliberate. Until the operator directory is live and serving
+ * this key, a signature resolves to nothing and fails verification, which is
+ * worse than the honest unsigned request we sent before.
+ */
+export declare function resolveWebBotAuthConfig(env: NodeJS.ProcessEnv, loadKey: () => WebBotAuthSigningKey | null): WebBotAuthConfig | null;

package/dist/checkout-engine/web-bot-auth.js

@@ -0,0 +1,159 @@
+/**
+ * @purpose Web Bot Auth (RFC 9421) request signing for checkout navigations —
+ * the client half of Trusted Agent Protocol verification.
+ *
+ * Cloudflare's TAP verifies an agent by checking an RFC 9421 HTTP message
+ * signature on the request. Three headers carry it: `Signature-Input` names the
+ * covered components and parameters, `Signature` carries the Ed25519 signature
+ * over the derived base, and `Signature-Agent` gives the URL of the directory
+ * that resolves `keyid` to a public key. The checkout browser previously sent
+ * none of them, so a TAP-aware edge had nothing to verify and fell through to
+ * ordinary bot management.
+ *
+ * TWO HALVES, BOTH REQUIRED. This module presents a `keyid`; the auth server
+ * must publish that key at the `Signature-Agent` URL for anything to resolve.
+ * Signing while the directory is absent is strictly worse than not signing,
+ * because it advertises intent and then fails verification — which is why
+ * signing stays OFF unless explicitly configured with a directory URL.
+ *
+ * KEY MATERIAL NEVER LEAVES THIS MODULE. The signing key is accepted as a
+ * value, used once per request, and never logged, serialized, returned, or
+ * attached to evidence. Callers get headers, never the key. This module takes
+ * no logger for exactly that reason.
+ */
+import { createPrivateKey, sign as cryptoSign } from 'node:crypto';
+/** Signature validity ceiling. A signature is a bearer-ish artifact for as long
+ *  as it is valid, so the window stays short even if a caller asks for more. */
+export const WEB_BOT_AUTH_MAX_TTL_SECONDS = 300;
+/** Default validity. Long enough to survive a redirect chain and a slow TLS
+ *  handshake, short enough that a captured signature is near-useless. */
+export const WEB_BOT_AUTH_DEFAULT_TTL_SECONDS = 60;
+/** Label for the single signature we emit. RFC 9421 allows several per request. */
+export const WEB_BOT_AUTH_SIGNATURE_LABEL = 'sig1';
+/** Tag fixed by the Web Bot Auth draft; verifiers select on it. */
+export const WEB_BOT_AUTH_TAG = 'web-bot-auth';
+/** Components covered by the signature, in the order they appear in the base. */
+export const WEB_BOT_AUTH_COVERED_COMPONENTS = ['@authority', 'signature-agent'];
+/** Serialize an RFC 8941 structured-field string (always double-quoted). */
+function sfString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * Build the RFC 9421 signature base.
+ *
+ * The base is what actually gets signed, so its exact bytes are the contract
+ * with every verifier — one wrong space or a reordered parameter and the
+ * signature fails against a correct key. It is exported and pinned by a
+ * deterministic test vector for that reason.
+ */
+export function buildSignatureBase(params) {
+    return [
+        `"@authority": ${params.authority}`,
+        `"signature-agent": ${sfString(params.directoryUrl)}`,
+        `"@signature-params": ${buildSignatureParams(params)}`,
+    ].join('\n');
+}
+/**
+ * The `@signature-params` value, which appears twice: as the final line of the
+ * signature base, and verbatim as the `Signature-Input` header value. Building
+ * it once is what keeps those two identical — a verifier rederives the base
+ * from the header it received, so any divergence fails every signature.
+ */
+export function buildSignatureParams(params) {
+    return (`(${WEB_BOT_AUTH_COVERED_COMPONENTS.map(sfString).join(' ')})` +
+        `;created=${params.created}` +
+        `;expires=${params.expires}` +
+        `;keyid=${sfString(params.keyId)}` +
+        `;alg="ed25519"` +
+        `;tag=${sfString(WEB_BOT_AUTH_TAG)}`);
+}
+/**
+ * Produce the three Web Bot Auth headers for one request authority.
+ *
+ * Throws on unusable key material rather than emitting an unverifiable
+ * signature. Callers on the checkout path must treat a throw as "proceed
+ * unsigned" — see `webBotAuthHeadersOrNone`.
+ */
+export function buildWebBotAuthHeaders(params) {
+    const { authority, config, nowSeconds } = params;
+    const ttl = Math.min(Math.max(1, Math.floor(config.ttlSeconds ?? WEB_BOT_AUTH_DEFAULT_TTL_SECONDS)), WEB_BOT_AUTH_MAX_TTL_SECONDS);
+    const created = Math.floor(nowSeconds);
+    const expires = created + ttl;
+    const baseParams = {
+        authority,
+        directoryUrl: config.directoryUrl,
+        keyId: config.key.keyId,
+        created,
+        expires,
+    };
+    const base = buildSignatureBase(baseParams);
+    const signatureParams = buildSignatureParams(baseParams);
+    const privateKey = createPrivateKey({
+        key: config.key.privateJwk,
+        format: 'jwk',
+    });
+    // Ed25519 takes no separate digest algorithm; null is the required argument.
+    const signature = cryptoSign(null, Buffer.from(base, 'utf8'), privateKey);
+    return {
+        'Signature-Input': `${WEB_BOT_AUTH_SIGNATURE_LABEL}=${signatureParams}`,
+        Signature: `${WEB_BOT_AUTH_SIGNATURE_LABEL}=:${signature.toString('base64')}:`,
+        'Signature-Agent': sfString(config.directoryUrl),
+    };
+}
+/**
+ * Header-or-nothing wrapper for the checkout path.
+ *
+ * Signing is an optional trust upgrade, never a precondition for buying
+ * something. Unusable key material, a malformed URL, or any crypto failure
+ * degrades to an unsigned request — which is exactly what we sent before this
+ * module existed — rather than throwing into a live checkout.
+ */
+export function webBotAuthHeadersOrNone(config, targetUrl, nowSeconds) {
+    if (!config)
+        return null;
+    try {
+        const authority = new URL(targetUrl).host;
+        if (!authority)
+            return null;
+        return buildWebBotAuthHeaders({ authority, config, nowSeconds });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve signing config from the environment. Returns `null` — meaning "send
+ * unsigned" — unless a directory URL and a usable key are BOTH present.
+ *
+ * Default-off is deliberate. Until the operator directory is live and serving
+ * this key, a signature resolves to nothing and fails verification, which is
+ * worse than the honest unsigned request we sent before.
+ */
+export function resolveWebBotAuthConfig(env, loadKey) {
+    const directoryUrl = env.VISA_WEB_BOT_AUTH_DIRECTORY_URL?.trim();
+    if (!directoryUrl)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(directoryUrl);
+    }
+    catch {
+        return null;
+    }
+    // A directory fetched over plain http could be swapped in flight, which would
+    // let an observer substitute the key set our identity is judged against.
+    if (parsed.protocol !== 'https:')
+        return null;
+    let key = null;
+    try {
+        key = loadKey();
+    }
+    catch {
+        return null;
+    }
+    if (!key?.keyId || key.privateJwk?.crv !== 'Ed25519' || !key.privateJwk.d)
+        return null;
+    const rawTtl = Number(env.VISA_WEB_BOT_AUTH_TTL_SECONDS);
+    const ttlSeconds = Number.isFinite(rawTtl) && rawTtl > 0 ? rawTtl : undefined;
+    return { directoryUrl: parsed.toString(), key, ttlSeconds };
+}