@visa/cli 4.1.0-rc.25 → 4.1.0-rc.27

package/dist/checkout-engine/cli-engine.js

@@ -16,16 +16,43 @@ import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
-import { VgsAssuranceInstrument, decimalToMinor, } from './vgs-live-instrument.js';
+import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, } from './vgs-live-instrument.js';
 import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
+import { createCardMandate, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
+import { MandateLedger } from './mandate/mandate-ledger.js';
 import { buildReceipt, writeReceipt as realWriteReceipt } from './receipt.js';
 import { reportVicOutcome as realReportVicOutcome, } from './vic-confirmation.js';
+/**
+ * A card-mandate draw failed transiently (retryable) rather than definitively.
+ * Gateway 5xx, "server cryptogram not completed / try again", and network
+ * reset/timeout errors are transient: the mandate stays healthy and must NOT be
+ * disabled. Walks the error's cause chain so a wrapped MandateDrawDeclinedError
+ * is classified by its underlying gateway error. Exported for tests.
+ */
+export function isTransientDrawFailure(err) {
+    const msgs = [];
+    let e = err;
+    for (let i = 0; i < 5 && e; i++) {
+        if (e instanceof Error && typeof e.message === 'string')
+            msgs.push(e.message);
+        e = e.cause;
+    }
+    // Transient = a gateway 5xx / 429 in the mint client's "(last: <status>: …)"
+    // framing, or an unambiguous network reset/timeout error name. The status is
+    // ANCHORED to `(last:` so a bare 3-digit token elsewhere (an amount, a ref id,
+    // an attempt count) can never be mistaken for a status code, and so the
+    // advisory DRAW_REMEDY wrapper text ("gateway 5xx / try again") cannot
+    // self-classify a hard decline as transient. A hard decline (4xx / a
+    // card-decline reason) matches nothing here → the mandate is correctly disabled.
+    return /\(last:\s*(?:5\d\d|429)\b|\bETIMEDOUT\b|\bECONNRESET\b|\bECONNREFUSED\b|\bEAI_AGAIN\b|socket hang up|tim(?:e|ed)[ -]?out/i.test(msgs.join(' '));
+}
 const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');
 // Must match the prepared-checkout store TTL so a session and its store entry
 // expire together — an abandoned review can't leak the browser + state.
 const PREPARED_TTL_MS = 5 * 60 * 1000;
 const defaultStore = new InMemoryPreparedCheckoutStore({ ttlMs: PREPARED_TTL_MS });
 const defaultSessions = new Map();
+const defaultLedger = new MandateLedger();
 export function createCliCheckoutEngine(deps = {}) {
     const store = deps.store ?? defaultStore;
     const sessions = deps.sessions ?? defaultSessions;
@@ -36,6 +63,11 @@ export function createCliCheckoutEngine(deps = {}) {
     const runHostedApproval = deps.runHostedApproval ?? realRunHostedApproval;
     const reportVicOutcome = deps.reportVicOutcome ?? realReportVicOutcome;
     const writeReceipt = deps.writeReceipt ?? realWriteReceipt;
+    const ledger = deps.ledger ?? defaultLedger;
+    const now = deps.now ?? (() => new Date());
+    const fetchMandateCryptogram = deps.serverFetchCryptogram ?? serverFetchCryptogram;
+    const cardDrawVerdict = deps.cardDrawVerdict ?? null;
+    const cardMandateRegister = deps.cardMandateRegister ?? null;
     async function closeSession(reviewId) {
         const session = sessions.get(reviewId);
         if (!session)
@@ -54,6 +86,134 @@ export function createCliCheckoutEngine(deps = {}) {
         };
     }
     return {
+        // BUDGET step: one passkey approves a CEILING; a VGS intent is minted with
+        // that ceiling as its decline threshold and the owner-only ledger records
+        // the cumulative budget. No browser checkout is prepared — this is purely
+        // the passkey ceremony + intent, so later pay() draws need no fresh tap.
+        async startCardMandate(input) {
+            const ceilingMinor = decimalToMinor(input.ceiling);
+            if (ceilingMinor === null || ceilingMinor <= 0) {
+                throw new Error(`invalid mandate ceiling ${JSON.stringify(input.ceiling)}`);
+            }
+            if (input.perTransaction !== undefined) {
+                const perTxMinor = decimalToMinor(input.perTransaction);
+                if (perTxMinor === null || perTxMinor <= 0 || perTxMinor > ceilingMinor) {
+                    throw new Error(`invalid mandate perTransaction ${JSON.stringify(input.perTransaction)} — ` +
+                        'must be a positive amount at or under the ceiling');
+                }
+            }
+            // BUDGET mandate: not tied to a merchant. The approval screen shows the
+            // any-merchant label so the owner sees the broader scope they're granting;
+            // the URL is a stable sentinel (advisory on the intent, ignored on draw).
+            const anyMerchant = input.anyMerchant === true;
+            if (!anyMerchant && !input.url) {
+                throw new Error('a merchant url is required unless anyMerchant (budget mandate) is set');
+            }
+            const merchant = anyMerchant
+                ? {
+                    name: 'spend budget mandate',
+                    url: 'https://any-merchant.visa/budget',
+                    countryCode: input.merchantCountryCode ?? 'US',
+                }
+                : {
+                    name: input.merchantName ?? new URL(input.url).hostname,
+                    url: input.url,
+                    countryCode: input.merchantCountryCode ?? 'US',
+                };
+            const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
+            // The passkey ceremony is scoped to the CEILING + merchant (not one
+            // charge) — that scope is the unproven part of the spike.
+            const ceilingTarget = {
+                merchantName: merchant.name,
+                merchantUrl: merchant.url,
+                merchantCountryCode: merchant.countryCode,
+                transactionAmount: input.ceiling,
+                transactionCurrencyCode: input.currency,
+            };
+            // BUDGET mode: the ceiling target's amount IS the approved ceiling, so the
+            // server mints a budget mint token bound to that ceiling — later draws pull
+            // sub-ceiling amounts against it tap-free (the single-purchase fresh-tap
+            // path below stays non-budget).
+            const assurance = await runHostedApproval({
+                baseUrl: input.approvalBaseUrl,
+                tokenId: credential.tokenId,
+                target: ceilingTarget,
+                consumerEmail: input.contact.email,
+                budget: true,
+                onApprovalUrl: deps.onApprovalUrl,
+                ...(input.maxDraws !== undefined ? { maxDraws: input.maxDraws } : {}),
+                ...(input.perTransaction !== undefined ? { perTransaction: input.perTransaction } : {}),
+                ...(input.intent !== undefined ? { intent: input.intent } : {}),
+            });
+            const mintToken = assurance.mintToken;
+            if (!mintToken) {
+                throw new Error('the approval server issued no mint token — server-side minting requires the ' +
+                    'verify-web deployment to run real/turnkey auth (not the dev stub). Retry once it does.');
+            }
+            const expiresAt = input.expiresAt ?? new Date(now().getTime() + 24 * 60 * 60 * 1000).toISOString();
+            const facts = await createCardMandate({
+                tokenId: credential.tokenId,
+                assuranceData: assurance.assuranceData,
+                ceilingMinor,
+                merchant,
+                currencyCode: input.currency,
+                expiresAt,
+                ...(input.maxDraws !== undefined ? { maxDraws: input.maxDraws } : {}),
+                ...(anyMerchant ? { crossMerchant: true } : {}),
+            }, {
+                createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, mintToken, i),
+                ledger,
+                approvalBaseUrl: input.approvalBaseUrl,
+                mintToken,
+                now,
+            });
+            // #5942 CONVERGE: seed the auth-side cumulative store keyed by the VGS INTENT
+            // id (`facts.mandateId`) so a later delegated draw resolves the mandate. This
+            // is BEST-EFFORT: a failure is logged, never fatal — the bearer mint-token
+            // path still works, only the delegated draw needs the register row. Skipped
+            // entirely when no mode='card' delegated binding is present.
+            const registerCap = cardMandateRegister?.loadCapability() ?? null;
+            let registerFailed = false;
+            if (registerCap && cardMandateRegister) {
+                const reg = await cardMandateRegister
+                    .register({
+                    authBaseUrl: registerCap.authBaseUrl,
+                    agentKey: registerCap.agentKey,
+                    mandateId: facts.mandateId,
+                    mintToken,
+                    ceiling: input.ceiling,
+                    currency: input.currency,
+                })
+                    .catch((err) => ({
+                    ok: false,
+                    reason: err instanceof Error ? err.message : String(err),
+                }));
+                if (!reg.ok) {
+                    registerFailed = true;
+                    // Register failed: the server `card_mandate_spend` row was never
+                    // created, so a delegated draw against this mandate would 404
+                    // `no_mandate`. Mark it register-failed so findCovering() SKIPS it and
+                    // the owner's next checkout falls through to a fresh per-purchase tap,
+                    // rather than silently selecting a mandate that can't be drawn. Marking
+                    // is best-effort too — a failure here must not abort mandate-start.
+                    const marked = await ledger
+                        .markRegisterFailed(facts.mandateId, now())
+                        .then(() => true)
+                        .catch(() => false);
+                    process.stderr.write(marked
+                        ? `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) — this mandate ` +
+                            `will NOT be used for tap-free draws; your next checkout will use a fresh ` +
+                            `per-purchase passkey tap. Re-run 'mandate start' to try again.\n`
+                        : // Escalate: the mark write ALSO failed, so the mandate is persisted but
+                            // NOT disabled — findCovering could still select an undrawable mandate.
+                            // Tell the owner loudly not to rely on it and how to recover.
+                            `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) AND the mandate ` +
+                                `could NOT be disabled locally — do not rely on it. Run 'mandate list' and re-run ` +
+                                `'mandate start'. mandateId=${facts.mandateId}\n`);
+                }
+            }
+            return { ...facts, merchantHost: new URL(merchant.url).hostname, registerFailed };
+        },
         async review(input) {
             const amountMinor = decimalToMinor(input.amount);
             if (amountMinor === null)
@@ -113,6 +273,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath: null,
                     detail: `no prepared review ${input.reviewId} — call review first (a review does not survive a restart)`,
                     vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
                 };
             }
             // Amount-bind the confirmation: the pay-call amount must match the
@@ -128,6 +290,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath: null,
                     detail: `pay amount ${JSON.stringify(input.amount)} does not match the reviewed amount (${session.amountMinor} minor units) — start a fresh review`,
                     vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
                 };
             }
             // Reject an expired prepared checkout BEFORE running the hosted passkey
@@ -141,48 +305,224 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath: null,
                     detail: `prepared review ${input.reviewId} expired — start a fresh review`,
                     vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
                 };
             }
             clearTimeout(session.cleanupTimer);
             try {
                 const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
-                const assurance = await runHostedApproval({
-                    baseUrl: input.approvalBaseUrl,
-                    tokenId: credential.tokenId,
-                    target: session.target,
-                    consumerEmail: session.contact.email,
+                const host = new URL(session.target.merchantUrl).hostname;
+                // Does an ACTIVE card mandate already cover this exact purchase? If so,
+                // draw against it TAP-FREE (no hosted passkey). Else fall back to today's
+                // 1:1 fresh-tap flow. `mintToken` requirement means a mandate with no
+                // persisted token can never silently short-circuit the tap.
+                const covering = await ledger.findCovering({
+                    merchantHost: host,
+                    currencyCode: session.currency,
+                    amountMinor: session.amountMinor,
+                    now: now(),
                 });
-                // Server-side mint (Phase 1): the approval claim releases a scoped mint
-                // token; the credential is minted by the verify-web deployment (which
-                // holds the VGS secret), never on this machine. No token means the
-                // deployment ran the dev-auth stub — refuse loudly rather than reach for
-                // a client-held secret (there is none anymore).
-                const approvalBase = input.approvalBaseUrl;
-                const mintToken = assurance.mintToken;
-                if (!mintToken) {
-                    return {
-                        outcome: 'failed',
-                        confirmationRef: null,
-                        receiptPath: null,
-                        detail: 'the approval server issued no mint token — server-side minting requires the ' +
-                            'verify-web deployment to run real/turnkey auth (not the dev stub). Retry once it does.',
-                        vicConfirmation: null,
+                let source;
+                let confirmBase;
+                let confirmToken;
+                let drawnRemaining = null;
+                let instrument;
+                if (covering && covering.mintToken) {
+                    // --- Tap-free mandate draw ------------------------------------------
+                    source = 'mandate';
+                    confirmBase = covering.approvalBaseUrl;
+                    // The bearer mint token stays the auth for the VIC confirmation POST
+                    // (the confirmation route accepts only the mint token). The CRYPTOGRAM
+                    // mint, however, may use a delegated verdict token — see below.
+                    confirmToken = covering.mintToken;
+                    const mandateId = covering.mandateId;
+                    // #5923 delegated card-draw: when the agent holds a local mode='card'
+                    // binding, mint the cryptogram with a PoP-signed VERDICT token (the
+                    // verify-web tryVerdictAuth path) INSTEAD of the bearer mint token. No
+                    // binding (or seam not injected) → `drawToken` stays the bearer token:
+                    // today's #5917 draw, byte-for-byte unchanged (converge-not-break).
+                    //
+                    // #5928 CRITICAL-2: the CLI does NOT settle the reservation. verify-web
+                    // (which knows whether the cryptogram was payable) commits it on a
+                    // payable mint and releases it on a decline, server-authoritatively, so
+                    // the drawer can never release after a payable mint to dodge the ceiling.
+                    let drawToken = confirmToken;
+                    const capability = cardDrawVerdict?.loadCapability() ?? null;
+                    if (capability && cardDrawVerdict) {
+                        try {
+                            const { verdict } = await cardDrawVerdict.fetchVerdict({
+                                authBaseUrl: capability.authBaseUrl,
+                                agentKey: capability.agentKey,
+                                mandateId,
+                                // One draw per review; the reviewId is the server-side idempotency key.
+                                drawId: input.reviewId,
+                                draw: {
+                                    tokenId: covering.tokenId,
+                                    amount: session.target.transactionAmount,
+                                    currency: session.currency,
+                                    merchantName: session.target.merchantName,
+                                    merchantUrl: session.target.merchantUrl,
+                                    merchantCountryCode: session.target.merchantCountryCode,
+                                },
+                            });
+                            drawToken = verdict;
+                        }
+                        catch (err) {
+                            // The verdict gate refused (or a transient error) BEFORE the cryptogram
+                            // mint. This point is OUTSIDE the submitApprovedCheckout catch that
+                            // gracefully handles later draw errors, so an un-caught throw here
+                            // escapes pay() raw — making an agent WITH a card binding strictly more
+                            // fragile than one without (breaks converge-not-break). Convert it into
+                            // a graceful FAILED result instead. We do NOT silently fall back to the
+                            // bearer mint token: on an over_ceiling/reserve_refused refusal that
+                            // would DODGE the server-side ceiling the verdict path exists to enforce.
+                            //
+                            // Definitive gate refusal (no_mandate, over_ceiling, reserve_refused,
+                            // checkout_access_revoked, token_mismatch, …): the mandate cannot be
+                            // drawn, so disable it — findCovering then skips it and the NEXT
+                            // pay_merchant falls through to a fresh per-purchase tap. Transient
+                            // (503 card_draw_disabled, challenge hiccup, network): leave the mandate
+                            // healthy and surface a retryable message. Duck-typed: the engine cannot
+                            // import CardDrawRefusedError (it lives in @visa/cli, above this seam).
+                            const reasons = Array.isArray(err.reasons)
+                                ? err.reasons
+                                : [];
+                            const status = typeof err.status === 'number'
+                                ? err.status
+                                : 0;
+                            const TRANSIENT = new Set([
+                                'challenge_failed',
+                                'challenge_malformed',
+                                'verdict_refused',
+                            ]);
+                            const transient = status === 503 || reasons.length === 0 || reasons.every((r) => TRANSIENT.has(r));
+                            if (!transient) {
+                                // Best-effort: a mark failure must not turn a clean refusal into a throw.
+                                await ledger.markUnhonored(mandateId, now()).catch(() => { });
+                            }
+                            return {
+                                outcome: 'failed',
+                                confirmationRef: null,
+                                receiptPath: null,
+                                detail: transient
+                                    ? `the card-mandate draw could not be authorized right now (${reasons.join(', ') || 'temporary error'}) — retry shortly`
+                                    : `this card mandate can no longer be drawn (${reasons.join(', ') || 'refused'}); it has been disabled — retry the checkout to use a fresh per-purchase passkey tap`,
+                                vicConfirmation: null,
+                                source,
+                                remainingMinor: null,
+                            };
+                        }
+                    }
+                    // VgsLiveInstrument mints against an EXISTING intent (the mandate) with
+                    // no fresh assurance — exactly the draw semantics. The fetchCredential
+                    // seam routes through drawFromMandate so the ledger accounting (reserve
+                    // -> commit on payable, release on reject) wraps the cryptogram pull.
+                    const reference = {
+                        tokenId: covering.tokenId,
+                        intentId: mandateId,
+                        merchantName: session.target.merchantName,
+                        merchantUrl: session.target.merchantUrl,
+                        merchantCountryCode: session.target.merchantCountryCode,
+                        transactionAmount: session.target.transactionAmount,
+                        transactionCurrencyCode: session.currency,
+                    };
+                    const fetchCredential = async ({ transaction }) => {
+                        let draw;
+                        try {
+                            draw = await drawFromMandate({
+                                mandateId,
+                                amountMinor: session.amountMinor,
+                                transaction: { ...transaction, transactionCurrencyCode: session.currency },
+                            }, {
+                                fetchCryptogram: (i) => fetchMandateCryptogram(confirmBase, drawToken, i),
+                                ledger,
+                                now,
+                            });
+                        }
+                        catch (err) {
+                            // Disable the mandate ONLY for a post-reservation NETWORK decline
+                            // (MandateDrawDeclinedError). That case leaves the mandate
+                            // active+covering, so a naive retry would re-select it and fail
+                            // identically — trapping the caller; marking it unhonored makes the
+                            // next pay_merchant skip it and take a fresh per-purchase tap. We do
+                            // NOT attempt an unsafe same-call browser fallback mid-submit.
+                            //
+                            // A PRE-network failure — reserve() failing closed on a concurrent
+                            // over-budget race or expiry, or commit() throwing on file I/O —
+                            // is NOT a network decline: the mandate is HEALTHY, so we must
+                            // rethrow WITHOUT disabling it (michaelyang1 M1). drawFromMandate
+                            // has already released any reservation, so the budget is intact.
+                            // Only a DEFINITIVE (hard) decline disables the mandate. A TRANSIENT
+                            // failure — a gateway 5xx / "not completed, try again" / network
+                            // reset/timeout — must NOT permanently kill the budget: the mandate
+                            // may be perfectly healthy (it can have committed a draw seconds
+                            // earlier) and the rails may recover on retry. Over-disabling on a
+                            // transient 502 threw away good budgets and forced a fresh passkey
+                            // every time.
+                            // Classify on the underlying gateway CAUSE, not the MandateDrawDeclinedError
+                            // wrapper — the wrapper's own advisory text mentions "try again"/"network",
+                            // which would otherwise self-classify every decline as transient.
+                            if (err instanceof MandateDrawDeclinedError &&
+                                !isTransientDrawFailure(err.cause ?? err)) {
+                                await ledger.markUnhonored(mandateId, now());
+                            }
+                            // #5928 CRITICAL-2: the server-side reservation is released by
+                            // verify-web (it saw the mint fail), not here — the CLI never settles.
+                            throw err;
+                        }
+                        drawnRemaining = draw.remainingMinor;
+                        // #5928 CRITICAL-2: the reservation is committed by verify-web on the
+                        // payable mint (server-authoritative); the CLI does not settle.
+                        return draw.payment;
                     };
+                    instrument = new VgsLiveInstrument(reference, session.contact.fullName ?? '', fetchCredential);
                 }
-                const instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
-                    const { intentId, status } = await serverCreateIntent(approvalBase, mintToken, mintInput);
-                    try {
-                        const payment = await serverFetchCryptogram(approvalBase, mintToken, {
-                            tokenId: mintInput.tokenId,
-                            intentId,
-                            transaction: mintInput.transaction,
-                        });
-                        return { payment, intentId };
-                    }
-                    catch (err) {
-                        throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
+                else {
+                    // --- 1:1 fresh-tap flow (unchanged) ---------------------------------
+                    source = 'fresh-tap';
+                    const assurance = await runHostedApproval({
+                        baseUrl: input.approvalBaseUrl,
+                        tokenId: credential.tokenId,
+                        target: session.target,
+                        consumerEmail: session.contact.email,
+                        onApprovalUrl: deps.onApprovalUrl,
+                    });
+                    // Server-side mint (Phase 1): the approval claim releases a scoped mint
+                    // token; the credential is minted by the verify-web deployment (which
+                    // holds the VGS secret), never on this machine. No token means the
+                    // deployment ran the dev-auth stub — refuse loudly rather than reach for
+                    // a client-held secret (there is none anymore).
+                    const mintToken = assurance.mintToken;
+                    if (!mintToken) {
+                        return {
+                            outcome: 'failed',
+                            confirmationRef: null,
+                            receiptPath: null,
+                            detail: 'the approval server issued no mint token — server-side minting requires the ' +
+                                'verify-web deployment to run real/turnkey auth (not the dev stub). Retry once it does.',
+                            vicConfirmation: null,
+                            source: 'fresh-tap',
+                            remainingMinor: null,
+                        };
                     }
-                });
+                    confirmBase = input.approvalBaseUrl;
+                    confirmToken = mintToken;
+                    instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
+                        const { intentId, status } = await serverCreateIntent(confirmBase, confirmToken, mintInput);
+                        try {
+                            const payment = await serverFetchCryptogram(confirmBase, confirmToken, {
+                                tokenId: mintInput.tokenId,
+                                intentId,
+                                transaction: mintInput.transaction,
+                            });
+                            return { payment, intentId };
+                        }
+                        catch (err) {
+                            throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
+                        }
+                    });
+                }
                 const mode = input.submit ? 'submit' : 'dry-run';
                 const result = await submitApprovedCheckout(input.reviewId, {
                     approval: { approved: true, reviewId: input.reviewId },
@@ -202,7 +542,7 @@ export function createCliCheckoutEngine(deps = {}) {
                             transactionAmount: session.target.transactionAmount,
                             transactionCurrencyCode: session.currency,
                         },
-                        post: (confInput) => serverPostConfirmation(approvalBase, mintToken, confInput),
+                        post: (confInput) => serverPostConfirmation(confirmBase, confirmToken, confInput),
                     });
                 }
                 let receiptPath = null;
@@ -232,6 +572,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath,
                     detail: result.detail ?? null,
                     vicConfirmation,
+                    source,
+                    remainingMinor: drawnRemaining,
                 };
             }
             finally {

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

@@ -1,6 +1,6 @@
 import type { Page } from 'playwright-core';
 export type FieldSource = 'autocomplete' | 'attr-heuristic' | 'label-text' | 'iframe-psp' | 'type-inference';
-export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
+export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'oneTimeCode' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
 export declare const ALL_ROLES: FieldRole[];
 export type SelectOption = {
     value: string;

package/dist/checkout-engine/detect.js

@@ -21,6 +21,7 @@ export const ALL_ROLES = [
     'nameFirst',
     'nameLast',
     'email',
+    'oneTimeCode',
     'addressLine1',
     'addressLine2',
     'city',
@@ -37,6 +38,17 @@ const expMonthRe = /(exp.?month|expmonth|exp_mm|(^|[^a-z])mm([^a-z]|$)|(^|[^a-z]
 const expYearRe = /(exp.?year|expyear|exp_yy|(^|[^a-z])yy(yy)?([^a-z]|$)|(^|[^a-z])year([^a-z]|$)|jahr|annee|(^|[^a-z])ano([^a-z]|$))/;
 const expCombinedRe = /(exp(iry|iration)?(.?date)?|mm.?\/.?yy|mm.?jj|valid.?thru|ablauf|caducidad)/;
 const emailRe = /(e-?mail|correo|courriel)/;
+// One-time verification code (merchant email/SMS OTP). Ordered AFTER cvcRe in
+// attrClassify so a card CVC ("security code"/"card code") still wins — this
+// regex deliberately omits those card phrasings. It also OMITS a bare "code":
+// `postal_code`/`zip_code`/`country_code`/`promo_code` all contain "code" and
+// would otherwise misclassify as an OTP field and starve the address fill. A
+// bare "code" is matched LAST (bareCodeRe), after every address role.
+const oneTimeCodeRe = /(one[-_ ]?time|(^|[^a-z])otp([^a-z]|$)|passcode|(^|[^a-z])pin([^a-z]|$)|verif(y|ication)?.?code|auth.?code)/;
+// Standalone verification "code" — a last-resort OTP match tried only after the
+// specific address roles (postal/country/state/city/line) have had their say,
+// so a compound `*_code` address/product field is never stolen by the OTP role.
+const bareCodeRe = /(^|[^a-z])code([^a-z]|$)/;
 const postalRe = /(zip|postal|postcode|(^|[^a-z])plz([^a-z]|$)|(^|[^a-z])cep([^a-z]|$)|codigo.?postal)/;
 const countryRe = /(country|(^|[^a-z])land([^a-z]|$)|(^|[^a-z])pais)/;
 const stateRe = /((^|[^a-z])state([^a-z]|$)|province|region|bundesland|provincia)/;
@@ -55,6 +67,7 @@ const AUTOCOMPLETE_MAP = {
     'cc-name': 'name',
     name: 'name',
     email: 'email',
+    'one-time-code': 'oneTimeCode',
     'given-name': 'nameFirst',
     'family-name': 'nameLast',
     'address-line1': 'addressLine1',
@@ -151,6 +164,9 @@ function attrClassify(text, m) {
         return 'expCombined';
     if (emailRe.test(text))
         return 'email';
+    // OTP comes after cvc (checked above) so card CVC still classifies as 'cvc'.
+    if (oneTimeCodeRe.test(text))
+        return 'oneTimeCode';
     if (postalRe.test(text))
         return 'postalCode';
     if (countryRe.test(text))
@@ -163,6 +179,10 @@ function attrClassify(text, m) {
         return 'addressLine2';
     if (addr1Re.test(text))
         return 'addressLine1';
+    // Last-resort bare "code" → OTP, only once every address role has been ruled
+    // out, so `postal_code`/`country_code`/etc. keep their own role above.
+    if (bareCodeRe.test(text))
+        return 'oneTimeCode';
     if (nameFirstRe.test(text))
         return 'nameFirst';
     if (nameLastRe.test(text))

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

@@ -7,6 +7,9 @@ export type EvidenceStep = {
 export declare function maskPan(pan: string): string;
 export declare function maskCvc(_cvc: string): string;
 export declare function maskExpiry(): string;
+export declare function maskOtp(): string;
+export declare function hostOf(hostOrEmail: string): string;
+export declare function verificationLinkAllowed(link: string, messageFrom: string): boolean;
 export declare function redactContact(role: string, value: string): string;
 export declare class EvidenceLog {
     private steps;

package/dist/checkout-engine/evidence.js

@@ -3,12 +3,15 @@
 // the mandate verdict, the submit, and the final outcome, plus a compact
 // accessibility snapshot of the end state.
 //
-// Money-adjacent hygiene rule: the full PAN, the cvc, and the card expiry
-// NEVER enter the log. PANs are masked to last-4; cvc and expiry are redacted
-// entirely. maskPan/maskCvc/maskExpiry are the only sanctioned way to put a
-// card value anywhere near a log line. Contact PII (cardholder name, email,
-// address, ...) is redacted via redactContact: the log records THAT a field
-// was filled, never the personal value.
+// Money-adjacent hygiene rule: the full PAN, the cvc, the card expiry, and any
+// one-time verification code NEVER enter the log. PANs are masked to last-4;
+// cvc, expiry, and OTP codes are redacted entirely. maskPan/maskCvc/maskExpiry/
+// maskOtp are the only sanctioned way to put such a value anywhere near a log
+// line. (receipt.ts redactPanLikeDigits only catches 12-19-digit PANs, so a
+// 4-8-digit OTP would slip straight through — maskOtp at the fill site is the
+// load-bearing guarantee it never reaches the evidence log.) Contact PII
+// (cardholder name, email, address, ...) is redacted via redactContact: the
+// log records THAT a field was filled, never the personal value.
 // Mask a PAN to its last four digits. Non-digits are stripped for the count.
 export function maskPan(pan) {
     const digits = (pan || '').replace(/\D/g, '');
@@ -25,6 +28,48 @@ export function maskCvc(_cvc) {
 export function maskExpiry() {
     return 'redacted';
 }
+// A merchant one-time verification code is single-use secret material — it
+// never enters the log, in any format. Used at the oneTimeCode fill site so
+// the code is masked exactly as cvc/PAN are (see the header note above).
+export function maskOtp() {
+    return 'redacted';
+}
+// The registrable domain (approx eTLD+1) of an email address or hostname, for
+// the caller-side from-domain guard on verification links: before navigating a
+// link parsed from an untrusted OTP email, require the link host to match the
+// message sender's domain. extract.ts guarantees mechanical extraction, NOT
+// navigation safety — this guard is the anti-injection backstop.
+export function hostOf(hostOrEmail) {
+    return (hostOrEmail.split('@').pop() ?? '').trim().toLowerCase().replace(/\.$/, '');
+}
+// Strict bidirectional host-suffix match (exact / child / parent). Deliberately
+// NOT approximate eTLD+1 — that collapses shared-tenant hosts (`x.myshopify.com`,
+// `x.co.uk`) to a common suffix and lets a sibling tenant match; siblings never
+// match here. Fails SAFE: an unrelated-but-legitimate sender is skipped, not
+// trusted.
+function hostsRelated(a, b) {
+    const x = hostOf(a);
+    const y = hostOf(b);
+    if (!x || !y)
+        return false;
+    return x === y || x.endsWith('.' + y) || y.endsWith('.' + x);
+}
+// Whether a verification LINK is safe to navigate: the sender must NOT be the
+// unauthenticated inbound variant (AgentMail marks spoofable inbound with an
+// `.unauthenticated` sub-label), and the link host must belong to the sender's
+// domain. Returns false to SKIP a link that fails either check.
+export function verificationLinkAllowed(link, messageFrom) {
+    if (/\.unauthenticated\b/i.test(messageFrom))
+        return false;
+    let linkHost;
+    try {
+        linkHost = new URL(link).hostname;
+    }
+    catch {
+        return false;
+    }
+    return hostsRelated(linkHost, messageFrom);
+}
 // Contact values (cardholder name, email, address, ...) are PII and never
 // enter the log raw either. Email keeps its domain for debuggability;
 // everything else becomes a bare presence marker.