@visa/cli 4.1.0-rc.229 → 4.1.0-rc.230

package/dist/checkout-engine/executor.js

@@ -26,7 +26,7 @@ import { summarizeFillFailure } from './adapters/generic.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';
+import { assertShopifyGuestCheckout, ensureShopifyGuestCheckout, 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;
 const REVEAL_TEXT = /continue|next|proceed|review|go to payment/i;
@@ -499,7 +499,10 @@ function recordTransactionFacts(evidence, phase, facts) {
         currency: facts.currency,
     });
 }
-function reviewChangeReason(review, merchantHost, facts) {
+function reviewChangeReason(review, merchantHost, facts, merchantOrigin) {
+    if (review.merchantOrigin && merchantOrigin !== review.merchantOrigin) {
+        return `merchant origin changed after review: ${review.merchantOrigin} -> ${merchantOrigin ?? 'invalid'}`;
+    }
     if (merchantHost !== review.merchantHost) {
         return `merchant changed after review: ${review.merchantHost} -> ${merchantHost}`;
     }
@@ -511,6 +514,40 @@ function reviewChangeReason(review, merchantHost, facts) {
     }
     return null;
 }
+function exactOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return null;
+        return url.origin.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+export function trustedMerchantOriginRefusal(options, pageUrl, expectedOrigin) {
+    const identity = options.trustedMerchantIdentity;
+    if (!identity)
+        return null;
+    if (Date.parse(identity.expiresAt) <= Date.now())
+        return 'trusted UCP checkout handoff expired';
+    const origin = exactOrigin(pageUrl);
+    if (!origin)
+        return 'trusted UCP checkout reached a non-HTTPS or credentialed origin';
+    if (expectedOrigin) {
+        return origin === expectedOrigin
+            ? null
+            : `merchant origin changed after review: ${expectedOrigin} -> ${origin}`;
+    }
+    return identity.allowedOrigins.includes(origin)
+        ? null
+        : `trusted UCP checkout reached undeclared origin ${origin}`;
+}
+function mandateForPage(options, pageUrl) {
+    if (!options.trustedMerchantIdentity)
+        return options.mandate;
+    return { ...options.mandate, merchantHost: new URL(pageUrl).hostname };
+}
 function submitTargetChangeReason(review, current) {
     const reviewed = review.submitTargetFingerprint;
     if (!reviewed && !current)
@@ -727,6 +764,14 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
     const options = {
         ...opts,
         mandate: { ...opts.mandate },
+        ...(opts.trustedMerchantIdentity
+            ? {
+                trustedMerchantIdentity: Object.freeze({
+                    ...opts.trustedMerchantIdentity,
+                    allowedOrigins: Object.freeze([...opts.trustedMerchantIdentity.allowedOrigins]),
+                }),
+            }
+            : {}),
     };
     const evidence = new EvidenceLog();
     // Pin an English locale: amount reconciliation reads the order summary by
@@ -757,12 +802,30 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
     let fields = {};
     let keepOpen = false;
     try {
-        evidence.step('navigation', { url: options.url });
+        evidence.step('navigation', {
+            url: options.trustedMerchantIdentity ? exactOrigin(options.url) : options.url,
+        });
         await page.goto(options.url, { waitUntil: 'domcontentloaded' });
         await waitForStableDom(page);
-        evidence.step('dom-stable', { url: page.url() });
-        const merchantHost = new URL(page.url()).hostname;
-        const preFill = checkMandatePreFill(options.mandate, {
+        evidence.step('dom-stable', {
+            url: options.trustedMerchantIdentity ? exactOrigin(page.url()) : page.url(),
+        });
+        let merchantHost = new URL(page.url()).hostname;
+        const initialOriginRefusal = trustedMerchantOriginRefusal(options, page.url());
+        if (initialOriginRefusal) {
+            evidence.step('mandate-verdict', {
+                phase: 'trusted-origin',
+                ok: false,
+                reason: initialOriginRefusal,
+            });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return {
+                status: 'finished',
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, initialOriginRefusal),
+            };
+        }
+        let reviewedOrigin;
+        const preFill = checkMandatePreFill(mandateForPage(options, page.url()), {
             merchantHost,
             currency: options.currency ?? null,
         });
@@ -809,37 +872,76 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 await page.goto(englishUrl, { waitUntil: 'domcontentloaded' }).catch(() => { });
                 await waitForStableDom(page);
                 if (await isShopifyCheckoutPage(page)) {
-                    evidence.step('navigation', { url: page.url(), reason: 'shopify-locale-normalized' });
+                    evidence.step('navigation', {
+                        url: options.trustedMerchantIdentity ? exactOrigin(page.url()) : page.url(),
+                        reason: 'shopify-locale-normalized',
+                    });
                     detected = await detectFields(page);
                 }
             }
         }
         let adapter = selectAdapter(detected, { shopify: shopifyPage });
         if (options.contact && adapter.prepareContact) {
-            const preparedContact = await adapter.prepareContact(page, options.contact);
-            for (const field of preparedContact.filled) {
-                evidence.step('contact-prefill', {
-                    role: field.role,
-                    confidence: field.confidence,
-                    source: field.source,
-                    frame: field.frame,
-                    value: field.value,
-                    ok: field.ok,
-                    error: field.error,
-                });
-            }
-            const challenge = await detectShopifyChallenge(page);
-            if (challenge) {
-                evidence.step('outcome', {
-                    outcome: 'action-required',
-                    signal: challenge.signal,
+            const recordPrefill = async (contact) => {
+                const result = await adapter.prepareContact(page, contact);
+                for (const field of result.filled) {
+                    evidence.step('contact-prefill', {
+                        role: field.role,
+                        confidence: field.confidence,
+                        source: field.source,
+                        frame: field.frame,
+                        value: field.value,
+                        ok: field.ok,
+                        error: field.error,
+                    });
+                }
+                return result;
+            };
+            let preparedContact = await recordPrefill(options.contact);
+            if (shopifyPage && options.checkoutRoute === 'guest-card') {
+                const guest = await ensureShopifyGuestCheckout(page);
+                evidence.step('note', {
                     phase: 'contact-prefill',
+                    checkoutRoute: options.checkoutRoute,
+                    shopifyGuestStatus: guest.status,
+                    signal: guest.signal,
                 });
-                evidence.setSnapshotSummary(await snapshotSummary(page));
-                return {
-                    status: 'finished',
-                    result: makeResult('action-required', fields, evidence, requiresAdapter, `Shop Pay verification requires a human before review (${challenge.signal}); no payment credential was requested`),
-                };
+                if (guest.status === 'action-required') {
+                    evidence.step('outcome', {
+                        outcome: 'action-required',
+                        signal: guest.signal,
+                        phase: 'contact-prefill',
+                    });
+                    evidence.setSnapshotSummary(await snapshotSummary(page));
+                    return {
+                        status: 'finished',
+                        result: makeResult('action-required', fields, evidence, requiresAdapter, guest.detail, undefined, 'human-action-required'),
+                    };
+                }
+                if (guest.status === 'transitioned') {
+                    // Do not write the recognized email a second time: Shopify can open
+                    // the same modal on every email input event. Only retry contact fill
+                    // when the takeover interrupted it, and omit email on that retry.
+                    if (!preparedContact.ok) {
+                        await settle(page);
+                        detected = await detectFields(page);
+                        adapter = selectAdapter(detected, { shopify: true });
+                        preparedContact = await recordPrefill({ ...options.contact, email: undefined });
+                    }
+                    const verifiedGuest = await assertShopifyGuestCheckout(page);
+                    if (verifiedGuest.status === 'action-required') {
+                        evidence.step('outcome', {
+                            outcome: 'action-required',
+                            signal: verifiedGuest.signal,
+                            phase: 'contact-prefill-guest-verification',
+                        });
+                        evidence.setSnapshotSummary(await snapshotSummary(page));
+                        return {
+                            status: 'finished',
+                            result: makeResult('action-required', fields, evidence, requiresAdapter, verifiedGuest.detail, undefined, 'human-action-required'),
+                        };
+                    }
+                }
             }
             if (!preparedContact.ok) {
                 evidence.setSnapshotSummary(await snapshotSummary(page));
@@ -851,8 +953,10 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             }
             await settle(page);
             const prefillHost = new URL(page.url()).hostname;
-            if (prefillHost !== merchantHost) {
-                const reason = `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
+            const trustedPrefillRefusal = trustedMerchantOriginRefusal(options, page.url());
+            if (trustedPrefillRefusal || prefillHost !== merchantHost) {
+                const reason = trustedPrefillRefusal ??
+                    `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
                 evidence.step('mandate-verdict', {
                     phase: 'contact-prefill',
                     ok: false,
@@ -901,6 +1005,26 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 result: makeResult('failed', fields, evidence, requiresAdapter, reason, undefined, 'card-number-field-unavailable'),
             };
         }
+        // Contact/shipping and Shopify locale normalization may legitimately move
+        // between the exact service and business origins authorized by UCP. Freeze
+        // whichever declared origin is actually on-screen only after those
+        // credential-free steps, then require that exact origin for approval,
+        // credential fill, and submit.
+        const reviewOriginRefusal = trustedMerchantOriginRefusal(options, page.url());
+        if (reviewOriginRefusal) {
+            evidence.step('mandate-verdict', {
+                phase: 'review-origin',
+                ok: false,
+                reason: reviewOriginRefusal,
+            });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return {
+                status: 'finished',
+                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reviewOriginRefusal),
+            };
+        }
+        merchantHost = new URL(page.url()).hostname;
+        reviewedOrigin = options.trustedMerchantIdentity ? exactOrigin(page.url()) : undefined;
         const facts = await readTransactionFacts(page, options, 'review');
         recordTransactionFacts(evidence, 'review', facts);
         if (!facts.ok) {
@@ -911,7 +1035,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, facts.detail),
             };
         }
-        const verdict = checkMandate(options.mandate, {
+        const verdict = checkMandate(mandateForPage(options, page.url()), {
             merchantHost,
             amountMinor: facts.amountMinor,
             currency: facts.currency,
@@ -930,8 +1054,12 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         const submit = await findSubmit(page, { allowDeferred: true });
         const review = Object.freeze({
             id: randomUUID(),
-            url: page.url(),
+            // A UCP continuation may contain a bearer-like path/query. The live page
+            // stays in the process-bound store; serializable review facts expose only
+            // the exact reviewed origin.
+            url: reviewedOrigin ?? page.url(),
             merchantHost,
+            ...(reviewedOrigin ? { merchantOrigin: reviewedOrigin } : {}),
             amountMinor: facts.amountMinor,
             currency: facts.currency,
             mandateMaxAmountMinor: options.mandate.maxAmountMinor,
@@ -939,6 +1067,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             submitTarget: submit?.desc ?? null,
             submitTargetFingerprint: submit ? Object.freeze({ ...submit.fingerprint }) : null,
             detectedRoles: Object.freeze(Object.keys(fields)),
+            checkoutRoute: options.checkoutRoute,
         });
         evidence.step('review', {
             reviewId: review.id,
@@ -948,12 +1077,14 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             submitTarget: review.submitTarget,
             submitTargetFingerprint: review.submitTargetFingerprint,
             detectedRoles: review.detectedRoles,
+            checkoutRoute: review.checkoutRoute,
         });
         const checkout = Object.freeze({
             review,
             fields: Object.freeze({ ...fields }),
             evidence,
             requiresAdapter: Object.freeze([...requiresAdapter]),
+            checkoutRoute: options.checkoutRoute,
         });
         store.put(review.id, {
             checkout,
@@ -1005,7 +1136,17 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         // the credential boundary. A changed checkout requires a fresh review.
         await waitForStableDom(page);
         const merchantHost = new URL(page.url()).hostname;
-        const preFill = checkMandatePreFill(options.mandate, {
+        const approvalOriginRefusal = trustedMerchantOriginRefusal(options, page.url(), checkout.review.merchantOrigin);
+        if (approvalOriginRefusal) {
+            evidence.step('mandate-verdict', {
+                phase: 'approval-origin',
+                ok: false,
+                reason: approvalOriginRefusal,
+            });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalOriginRefusal);
+        }
+        const preFill = checkMandatePreFill(mandateForPage(options, page.url()), {
             merchantHost,
             currency: options.currency ?? null,
         });
@@ -1027,7 +1168,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvedFacts.detail);
         }
-        const approvalVerdict = checkMandate(options.mandate, {
+        const approvalVerdict = checkMandate(mandateForPage(options, page.url()), {
             merchantHost,
             amountMinor: approvedFacts.amountMinor,
             currency: approvedFacts.currency,
@@ -1038,7 +1179,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalVerdict.reason);
         }
-        const changedAtApproval = reviewChangeReason(checkout.review, merchantHost, approvedFacts);
+        const changedAtApproval = reviewChangeReason(checkout.review, merchantHost, approvedFacts, exactOrigin(page.url()) ?? undefined);
         if (changedAtApproval) {
             evidence.step('approval', {
                 approved: false,
@@ -1083,6 +1224,24 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 ? `validated the reviewed checkout; would click ${approvalSubmit.desc}`
                 : 'validated the reviewed checkout; no submit control detected');
         }
+        if (options.checkoutRoute === 'guest-card' && (await isShopifyCheckoutPage(page))) {
+            const guest = await assertShopifyGuestCheckout(page);
+            evidence.step('note', {
+                phase: 'pre-credential',
+                checkoutRoute: options.checkoutRoute,
+                shopifyGuestStatus: guest.status,
+                signal: guest.signal,
+            });
+            if (guest.status === 'action-required') {
+                evidence.step('outcome', {
+                    outcome: 'action-required',
+                    signal: guest.signal,
+                    phase: 'pre-credential',
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return makeResult('action-required', state.fields, evidence, requiresAdapter, guest.detail, undefined, 'human-action-required');
+            }
+        }
         const credential = await opts.instrument.getCredential({
             merchantHost,
             amountMinor: approvedFacts.amountMinor,
@@ -1104,8 +1263,11 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             // A reveal/continue action can navigate between attempts. Never expose
             // the credential to a host other than the one the human reviewed.
             const fillHost = new URL(page.url()).hostname;
-            if (fillHost !== checkout.review.merchantHost) {
-                const reason = `merchant changed after review: ${checkout.review.merchantHost} -> ${fillHost}`;
+            const fillOriginRefusal = trustedMerchantOriginRefusal(options, page.url(), checkout.review.merchantOrigin);
+            if (fillOriginRefusal ||
+                (!checkout.review.merchantOrigin && fillHost !== checkout.review.merchantHost)) {
+                const reason = fillOriginRefusal ??
+                    `merchant changed after review: ${checkout.review.merchantHost} -> ${fillHost}`;
                 evidence.step('mandate-verdict', {
                     phase: 'approved-submit',
                     ok: false,
@@ -1213,7 +1375,17 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitFacts.detail);
         }
         const submitMerchantHost = new URL(page.url()).hostname;
-        const verdict = checkMandate(options.mandate, {
+        const submitOriginRefusal = trustedMerchantOriginRefusal(options, page.url(), checkout.review.merchantOrigin);
+        if (submitOriginRefusal) {
+            evidence.step('mandate-verdict', {
+                phase: 'pre-submit-origin',
+                ok: false,
+                reason: submitOriginRefusal,
+            });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitOriginRefusal);
+        }
+        const verdict = checkMandate(mandateForPage(options, page.url()), {
             merchantHost: submitMerchantHost,
             amountMinor: submitFacts.amountMinor,
             currency: submitFacts.currency,
@@ -1223,7 +1395,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, verdict.reason);
         }
-        const changedBeforeSubmit = reviewChangeReason(checkout.review, submitMerchantHost, submitFacts);
+        const changedBeforeSubmit = reviewChangeReason(checkout.review, submitMerchantHost, submitFacts, exactOrigin(page.url()) ?? undefined);
         if (changedBeforeSubmit) {
             evidence.step('mandate-verdict', {
                 phase: 'pre-submit',

package/dist/checkout-engine/hosted-approval.js

@@ -61,8 +61,11 @@ function defaultOpenUrl(url) {
     // `CHECKOUT_SKIP_BROWSER_OPEN=1` or `VISA_SUPPRESS_BROWSER=true|1` disables it
     // (headless/agent hosts where launching a browser on the WRONG machine is pointless or noisy).
     if (process.env.CHECKOUT_SKIP_BROWSER_OPEN === '1' ||
+        process.env.CHECKOUT_SKIP_BROWSER_OPEN === 'true' ||
         process.env.VISA_SUPPRESS_BROWSER === '1' ||
-        process.env.VISA_SUPPRESS_BROWSER === 'true')
+        process.env.VISA_SUPPRESS_BROWSER === 'true' ||
+        process.env.VISA_CLI_NO_BROWSER === '1' ||
+        process.env.VISA_CLI_NO_BROWSER === 'true')
         return;
     // Platform-appropriate opener; unknown platforms just skip (the URL is logged).
     const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';

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

@@ -1,9 +1,10 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, CheckoutReviewRefusedError, } from './cli-engine.js';
+export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, type ReceiptWriteObservation, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, } from './executor.js';
+export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, CheckoutRoute, } from './executor.js';
 export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
 export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';
 export { RECEIPT_DIR } from './receipt-dir.js';
 export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
 export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, type CreateCardMandateInput, type CreateCardMandateDeps, type CardMandateFacts, type DrawFromMandateInput, type DrawFromMandateDeps, type DrawResult, type CardMandateMerchant, } from './mandate/card-mandate.js';
 export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, type CardMandateRecord, type CardMandateLedgerFile, type CardMandateDraw, type CardMandateReservation, } from './mandate/mandate-ledger.js';
+export { WEB_BOT_AUTH_MAX_TTL_SECONDS, WEB_BOT_AUTH_DEFAULT_TTL_SECONDS, WEB_BOT_AUTH_SIGNATURE_LABEL, WEB_BOT_AUTH_TAG, WEB_BOT_AUTH_COVERED_COMPONENTS, buildWebBotAuthHeaders, buildWebBotAuthHeadersAsync, webBotAuthHeadersOrNone, webBotAuthHeadersOrNoneAsync, resolveWebBotAuthConfig, type WebBotAuthPrivateJwk, type WebBotAuthSigningKey, type WebBotAuthConfig, type WebBotAuthHeaders, type BuildHeadersParams, } from './web-bot-auth.js';

package/dist/checkout-engine/index.js

@@ -9,3 +9,4 @@ export { RECEIPT_DIR } from './receipt-dir.js';
 export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
 export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, } from './mandate/card-mandate.js';
 export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, } from './mandate/mandate-ledger.js';
+export { WEB_BOT_AUTH_MAX_TTL_SECONDS, WEB_BOT_AUTH_DEFAULT_TTL_SECONDS, WEB_BOT_AUTH_SIGNATURE_LABEL, WEB_BOT_AUTH_TAG, WEB_BOT_AUTH_COVERED_COMPONENTS, buildWebBotAuthHeaders, buildWebBotAuthHeadersAsync, webBotAuthHeadersOrNone, webBotAuthHeadersOrNoneAsync, resolveWebBotAuthConfig, } from './web-bot-auth.js';

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

@@ -36,6 +36,10 @@ export type CheckoutReceiptV1 = {
 export type CheckoutReceiptV2 = {
     schema: 'checkout-agent-receipt/v2';
     recordedAt: string;
+    /** Correlates terminal pre-review observations that have no reviewId yet. */
+    observationId?: string;
+    /** Explicitly distinguishes pre-submit review observations from payment attempts. */
+    phase?: 'review';
     merchant: {
         name: string;
         host: string;
@@ -57,6 +61,15 @@ export type CheckoutReceiptV2 = {
     network: {
         confirmation: 'APPROVED' | 'DECLINED' | null;
     };
+    /**
+     * Capability evidence for unsuccessful checkout surfaces. Optional so
+     * previously published v2 receipt producers remain source-compatible.
+     */
+    capability?: {
+        failureCode: string | null;
+        detectedRoles: string[];
+        requiresAdapter: string[];
+    };
     /** Local reviewed-attempt identifier. Keeps filenames stable across schema versions. */
     receiptId: string | null;
     /** Merchant confirmation reference only; never substituted with an internal review id. */
@@ -80,6 +93,7 @@ export type ReceiptWriteReport = {
 export declare function buildReceipt(input: {
     mode: CheckoutMode;
     reviewId: string | null;
+    observationId?: string;
     merchant: {
         name: string;
         host: string;

package/dist/checkout-engine/receipt.js

@@ -6,7 +6,7 @@ import { submitClickedWithoutConfirmation } from './live-fill-approval.js';
  * What the operator still owes after this run. Empty for a clean dry-run fill
  * and for a definitive submit outcome whose VIC confirmation posted.
  */
-function reconciliationFor(result, vicConfirmation) {
+function reconciliationFor(result, vicConfirmation, mode) {
     const reasons = [];
     if (submitClickedWithoutConfirmation(result)) {
         reasons.push('the pay control was clicked but no definitive outcome was observed — ' +
@@ -22,7 +22,7 @@ function reconciliationFor(result, vicConfirmation) {
         reasons.push('confirmed without a merchant confirmation reference — ' +
             'record the order number from the merchant dashboard');
     }
-    if (result.outcome === 'action-required') {
+    if (mode === 'submit' && result.outcome === 'action-required') {
         reasons.push('an issuer verification challenge was shown and not completed — ' +
             'finish the purchase manually if still wanted, or confirm with the merchant that no order exists');
     }
@@ -30,7 +30,7 @@ function reconciliationFor(result, vicConfirmation) {
 }
 export function buildReceipt(input) {
     const { result } = input;
-    const reconciliation = reconciliationFor(result, input.vicConfirmation);
+    const reconciliation = reconciliationFor(result, input.vicConfirmation, input.mode);
     const fallbackAction = input.mode === 'dry-run'
         ? 'Dry run only — nothing was submitted; safe to run again.'
         : result.outcome === 'confirmed'
@@ -55,15 +55,25 @@ export function buildReceipt(input) {
     const cardLast4 = input.cardLast4 && /^\d{4}$/.test(input.cardLast4) ? input.cardLast4 : null;
     const checkoutUrl = input.merchant.url && KNOWN_MERCHANT_IDENTITIES[input.merchant.url] ? input.merchant.url : null;
     const networkConfirmation = input.vicConfirmation?.posted === true ? input.vicConfirmation.transactionStatus : null;
+    const capability = result.failureCode || result.requiresAdapter.length > 0
+        ? {
+            failureCode: result.failureCode ?? null,
+            detectedRoles: Object.keys(result.fields).sort(),
+            requiresAdapter: [...result.requiresAdapter].sort(),
+        }
+        : null;
     return {
         schema: 'checkout-agent-receipt/v2',
         recordedAt: (input.recordedAt ?? new Date()).toISOString(),
+        ...(input.observationId ? { observationId: input.observationId } : {}),
+        ...(input.observationId && input.reviewId === null ? { phase: 'review' } : {}),
         merchant: { name: input.merchant.name, host: input.merchant.host, checkoutUrl },
         transaction: input.transaction,
         outcome: result.outcome,
         agent: input.agentName ? { name: input.agentName } : null,
         rail: { type: 'card', cardLast4 },
         network: { confirmation: networkConfirmation },
+        ...(capability ? { capability } : {}),
         receiptId: input.reviewId,
         reference: result.confirmationRef ?? null,
         recovery: {

package/dist/checkout-engine/unresolved-charges.js

@@ -61,6 +61,15 @@ function parseUnresolved(json, receiptFile) {
         receipt.schema !== 'checkout-agent-receipt/v2') {
         return null;
     }
+    // Terminal review observations are useful capability evidence, but no pay
+    // control, credential, or submission exists yet. They must never poison the
+    // double-charge ledger even when the observed page showed a Shop Pay or 3DS
+    // action-required surface.
+    if (receipt.schema === 'checkout-agent-receipt/v2' &&
+        (receipt.phase === 'review' ||
+            (typeof receipt.observationId === 'string' && receipt.receiptId === null))) {
+        return null;
+    }
     if (typeof receipt.outcome !== 'string' || !MAY_HAVE_CHARGED_OUTCOMES.has(receipt.outcome)) {
         return null;
     }

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

@@ -20,7 +20,8 @@ export interface WebBotAuthPrivateJwk {
 export interface WebBotAuthSigningKey {
     /** RFC 7638 thumbprint. Must match a `kid` published in the directory. */
     keyId: string;
-    privateJwk: WebBotAuthPrivateJwk;
+    privateJwk?: WebBotAuthPrivateJwk;
+    signFn?: (signingInput: Uint8Array) => Promise<Uint8Array>;
 }
 export interface WebBotAuthConfig {
     /** Absolute https URL of the operator-hosted signature directory. */
@@ -81,6 +82,11 @@ export declare function buildWebBotAuthHeaders(params: BuildHeadersParams): WebB
  * module existed — rather than throwing into a live checkout.
  */
 export declare function webBotAuthHeadersOrNone(config: WebBotAuthConfig | null, targetUrl: string, nowSeconds: number): WebBotAuthHeaders | null;
+/**
+ * Async version of buildWebBotAuthHeaders, supporting Turnkey or vault signFn signers.
+ */
+export declare function buildWebBotAuthHeadersAsync(params: BuildHeadersParams): Promise<WebBotAuthHeaders>;
+export declare function webBotAuthHeadersOrNoneAsync(config: WebBotAuthConfig | null, targetUrl: string, nowSeconds: number): Promise<WebBotAuthHeaders | null>;
 /**
  * Resolve signing config from the environment. Returns `null` — meaning "send
  * unsigned" — unless a directory URL and a usable key are BOTH present.

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

@@ -88,6 +88,15 @@ export function buildWebBotAuthHeaders(params) {
     };
     const base = buildSignatureBase(baseParams);
     const signatureParams = buildSignatureParams(baseParams);
+    // privateJwk is optional on the key so a vault-held signer can supply signFn
+    // instead. Only the async builder can await such a signer, so refuse here with
+    // the same explicit message rather than handing undefined to createPrivateKey
+    // and surfacing an opaque node:crypto error.
+    if (!config.key.privateJwk) {
+        throw new Error(config.key.signFn
+            ? 'WebBotAuthSigningKey with signFn requires buildWebBotAuthHeadersAsync'
+            : 'WebBotAuthSigningKey requires either privateJwk or signFn');
+    }
     const privateKey = createPrivateKey({
         key: config.key.privateJwk,
         format: 'jwk',
@@ -121,6 +130,56 @@ export function webBotAuthHeadersOrNone(config, targetUrl, nowSeconds) {
         return null;
     }
 }
+/**
+ * Async version of buildWebBotAuthHeaders, supporting Turnkey or vault signFn signers.
+ */
+export async function buildWebBotAuthHeadersAsync(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);
+    let signature;
+    if (config.key.signFn) {
+        signature = await config.key.signFn(Buffer.from(base, 'utf8'));
+    }
+    else if (config.key.privateJwk) {
+        const privateKey = createPrivateKey({
+            key: config.key.privateJwk,
+            format: 'jwk',
+        });
+        signature = cryptoSign(null, Buffer.from(base, 'utf8'), privateKey);
+    }
+    else {
+        throw new Error('WebBotAuthSigningKey requires either privateJwk or signFn');
+    }
+    return {
+        'Signature-Input': `${WEB_BOT_AUTH_SIGNATURE_LABEL}=${signatureParams}`,
+        Signature: `${WEB_BOT_AUTH_SIGNATURE_LABEL}=:${Buffer.from(signature).toString('base64')}:`,
+        'Signature-Agent': sfString(config.directoryUrl),
+    };
+}
+export async function webBotAuthHeadersOrNoneAsync(config, targetUrl, nowSeconds) {
+    if (!config)
+        return null;
+    try {
+        const authority = new URL(targetUrl).host;
+        if (!authority)
+            return null;
+        return await buildWebBotAuthHeadersAsync({ 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.
@@ -151,7 +210,7 @@ export function resolveWebBotAuthConfig(env, loadKey) {
     catch {
         return null;
     }
-    if (!key?.keyId || key.privateJwk?.crv !== 'Ed25519' || !key.privateJwk.d)
+    if (!key?.keyId || (!key.signFn && (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;