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

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

@@ -11,6 +11,7 @@
 // Every browser/network primitive is injectable (CliEngineDeps) so the session/
 // timer/store lifecycle is unit-testable without launching Chromium.
 import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { RECEIPT_DIR } from './receipt-dir.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
@@ -19,7 +20,7 @@ import { VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-i
 import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
 import { createCardMandate, DEFAULT_MANDATE_MAX_DRAWS, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
 import { MandateLedger } from './mandate/mandate-ledger.js';
-import { buildReceipt, writeReceipt as realWriteReceipt } from './receipt.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.
@@ -60,6 +61,31 @@ export function isTransientDrawFailure(err) {
     // 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(' '));
 }
+/**
+ * Refusals that are about the OUTER card GRANT's remaining capacity, not about
+ * this mandate and not about the card network (#7491).
+ *
+ * The atomic reserve (#7233) charges the grant's shared `agent_grant_usage`
+ * epoch, so an exhausted or replaced grant refuses BEFORE any credential is
+ * minted: no cryptogram is issued, no processor intent is created, no money
+ * moves. Treating that as a mandate decline burned the budget the human had
+ * just approved and told the caller to create another mandate — which, over the
+ * same exhausted grant, is guaranteed to fail identically. The honest remedy is
+ * a new/replacement card grant, and the mandate must stay honored so it can
+ * draw once the owner supplies one.
+ */
+// Deliberately NARROW. `grant_aggregate_no_mandate` is NOT here: that refusal
+// means the mandate row itself vanished between the read and the reserve, which
+// is a statement about the mandate, not about the grant's capacity.
+const GRANT_CAPACITY_REASONS = new Set([
+    'over_grant_aggregate',
+    'no_active_grant',
+    'no_active_grant_or_card_scope',
+    'card_grant_exhausted',
+]);
+function isGrantCapacityReason(reason) {
+    return GRANT_CAPACITY_REASONS.has(reason);
+}
 /**
  * A verdict refusal may be wrapped by drawFromMandate after its local
  * reservation is released. Walk the cause chain so the original auth status +
@@ -80,10 +106,17 @@ export function classifyCardDrawVerdictFailure(err) {
             ? candidate.reasons.filter((reason) => typeof reason === 'string')
             : [];
         if (status !== 0 || reasons.length > 0) {
+            const transient = status === 503 ||
+                reasons.length === 0 ||
+                reasons.every((reason) => transientReasons.has(reason));
             return {
-                transient: status === 503 ||
-                    reasons.length === 0 ||
-                    reasons.every((reason) => transientReasons.has(reason)),
+                transient,
+                // A capacity refusal is NEITHER transient nor a decline. Retrying now
+                // fails identically (so it is not transient), but nothing about the
+                // MANDATE was refused (so it is not a decline). Only a refusal that is
+                // exclusively about the outer grant qualifies: a mixed reason list
+                // still carries a real mandate/network refusal and stays a decline.
+                grantCapacity: !transient && reasons.length > 0 && reasons.every(isGrantCapacityReason),
                 reasons,
             };
         }
@@ -130,8 +163,9 @@ export class CheckoutReviewRefusedError extends Error {
     failureCode;
     requiresAdapter;
     detectedRoles;
+    receiptWrite;
     detail;
-    constructor(result) {
+    constructor(result, receiptWrite) {
         super(result.detail
             ? `review refused: ${result.outcome} — ${result.detail}`
             : `review refused: ${result.outcome}`);
@@ -140,12 +174,14 @@ export class CheckoutReviewRefusedError extends Error {
         this.failureCode = result.failureCode;
         this.requiresAdapter = [...result.requiresAdapter];
         this.detectedRoles = Object.keys(result.fields);
+        this.receiptWrite = receiptWrite;
         this.detail = result.detail;
     }
 }
 function payAttemptFingerprint(input) {
     return JSON.stringify([
         input.url,
+        input.checkoutRoute,
         input.amount,
         input.currency,
         input.credentialPath,
@@ -171,6 +207,9 @@ function failedPay(detail) {
         credentialDisclosed: false,
     };
 }
+function boundedReceiptWriteErrorCode(reason) {
+    return reason.match(/\b(?:EACCES|EEXIST|ENOSPC|ENOTDIR|EPERM|EROFS)\b/)?.[0] ?? 'UNKNOWN';
+}
 // 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;
@@ -194,6 +233,39 @@ export function createCliCheckoutEngine(deps = {}) {
     const now = deps.now ?? (() => new Date());
     const fetchMandateCryptogram = deps.serverFetchCryptogram ?? serverFetchCryptogram;
     const postServerConfirmation = deps.serverPostConfirmation ?? serverPostConfirmation;
+    const createObservationId = deps.createObservationId ?? randomUUID;
+    async function writeObservedReceipt(mode, receipt) {
+        let report;
+        try {
+            report = await writeReceipt(RECEIPT_DIR, receipt);
+        }
+        catch (err) {
+            // The real writer is fail-open already. Keep that invariant even for an
+            // injected writer so a filesystem or test-double failure cannot replace
+            // the checkout result after a charge may have completed.
+            report = { written: false, reason: err instanceof Error ? err.message : String(err) };
+        }
+        const event = {
+            event: 'checkout_receipt_write',
+            status: report.written ? 'written' : 'failed',
+            mode,
+            checkoutOutcome: receipt.outcome,
+            merchantHost: receipt.merchant.host,
+            observationId: receipt.observationId ?? receipt.receiptId ?? createObservationId(),
+            failureCode: receipt.capability?.failureCode ?? null,
+            errorCode: report.written ? null : boundedReceiptWriteErrorCode(report.reason),
+            panRedactions: report.written ? report.panRedactions : null,
+        };
+        try {
+            const observerResult = deps.onReceiptWrite?.(event);
+            if (observerResult)
+                void Promise.resolve(observerResult).catch(() => undefined);
+        }
+        catch {
+            // Observability is non-authoritative and must not affect payment state.
+        }
+        return { report, event };
+    }
     const cardDrawVerdict = deps.cardDrawVerdict ?? null;
     const cardMandateRegister = deps.cardMandateRegister ?? null;
     async function closeSession(reviewId) {
@@ -504,6 +576,7 @@ export function createCliCheckoutEngine(deps = {}) {
             try {
                 const prep = await prepareCheckout({
                     url: input.url,
+                    checkoutRoute: input.checkoutRoute,
                     mandate: {
                         maxAmountMinor: amountMinor,
                         currency: input.currency,
@@ -514,18 +587,56 @@ export function createCliCheckoutEngine(deps = {}) {
                     currency: input.currency,
                     browser,
                     contact: input.contact,
+                    ...(input.trustedMerchantIdentity
+                        ? { trustedMerchantIdentity: input.trustedMerchantIdentity }
+                        : {}),
                 }, store);
                 if (prep.status !== 'ready') {
-                    throw new CheckoutReviewRefusedError(prep.result);
+                    // A terminal review is still a capability observation. Persist the
+                    // same compact, owner-only artifact as a pay attempt so the local
+                    // ledger records unsupported merchant surfaces and the safe card
+                    // display identity instead of retaining successes only.
+                    const observationId = createObservationId();
+                    const receiptWrite = await writeObservedReceipt('dry-run', buildReceipt({
+                        mode: 'dry-run',
+                        reviewId: null,
+                        observationId,
+                        merchant: {
+                            name: input.merchantName ?? host,
+                            host,
+                            url: input.url,
+                        },
+                        transaction: {
+                            amount: input.amount,
+                            amountMinor,
+                            currency: input.currency,
+                        },
+                        result: prep.result,
+                        vicConfirmation: null,
+                        agentName: input.agentName,
+                        cardLast4: input.cardLast4,
+                        recordedAt: now(),
+                    }));
+                    throw new CheckoutReviewRefusedError(prep.result, receiptWrite.event);
                 }
                 const r = prep.checkout.review;
                 // Expire the companion session on the SAME schedule as the store entry
                 // (unref'd so a pending timer never keeps the process alive).
                 const cleanupTimer = setTimeout(() => void closeSession(r.id), ttlMs);
                 cleanupTimer.unref?.();
+                const target = buildTarget(input);
+                if (r.merchantOrigin) {
+                    // The credential and mandate bind to the exact origin the browser
+                    // actually reviewed, not the Shopify service continuation that led
+                    // there. Keep the latter separately for review/pay replay binding.
+                    target.merchantUrl = r.merchantOrigin;
+                    target.merchantName = input.merchantName ?? r.merchantHost;
+                }
                 sessions.set(r.id, {
                     browser,
-                    target: buildTarget(input),
+                    requestUrl: new URL(input.url).toString(),
+                    checkoutRoute: input.checkoutRoute,
+                    target,
                     amountMinor,
                     currency: input.currency,
                     contact: input.contact,
@@ -604,7 +715,7 @@ export function createCliCheckoutEngine(deps = {}) {
             let reviewedUrl;
             try {
                 payUrl = new URL(input.url).toString();
-                reviewedUrl = new URL(session.target.merchantUrl).toString();
+                reviewedUrl = session.requestUrl;
             }
             catch {
                 await closeSession(input.reviewId);
@@ -658,6 +769,19 @@ export function createCliCheckoutEngine(deps = {}) {
                     ...noCredentialFacts,
                 };
             }
+            if (input.checkoutRoute !== session.checkoutRoute) {
+                await closeSession(input.reviewId);
+                return {
+                    outcome: 'failed',
+                    confirmationRef: null,
+                    receiptPath: null,
+                    detail: 'pay checkout route does not match the reviewed guest-card route — start a fresh review',
+                    vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
+                    ...noCredentialFacts,
+                };
+            }
             // Amount-bind the confirmation: the pay-call amount must match the
             // reviewed amount. The reviewId already locks the immutable mandate, but
             // re-checking here makes the confirmation explicitly amount-bound so a
@@ -856,9 +980,18 @@ export function createCliCheckoutEngine(deps = {}) {
                             if (err instanceof MandateDrawDeclinedError) {
                                 const verdictFailure = classifyCardDrawVerdictFailure(err);
                                 if (verdictFailure) {
-                                    if (!verdictFailure.transient) {
+                                    // #7491: a GRANT-capacity refusal is pre-credential and says
+                                    // nothing about this mandate, so it must NOT disable it. The
+                                    // mandate is healthy and becomes drawable again the moment the
+                                    // owner supplies a grant with room; disabling it here threw
+                                    // away a just-approved budget and pointed the caller at a new
+                                    // mandate that would die on the same wall.
+                                    if (!verdictFailure.transient && !verdictFailure.grantCapacity) {
                                         await ledger.markUnhonored(mandateId, now()).catch(() => { });
                                     }
+                                    if (verdictFailure.grantCapacity) {
+                                        throw new Error(`this agent's card grant has no remaining capacity (${verdictFailure.reasons.join(', ') || 'grant exhausted'}) — nothing was charged and the mandate is still valid; ask the owner for a new or replenished card grant (visa agent grant-card) before retrying this checkout`, { cause: err });
+                                    }
                                     throw new Error(verdictFailure.transient
                                         ? `the card-mandate draw could not be authorized right now (${verdictFailure.reasons.join(', ') || 'temporary error'}) — retry shortly`
                                         : `this card mandate can no longer be drawn (${verdictFailure.reasons.join(', ') || 'refused'}); it has been disabled — create and claim a new mandate before retrying this checkout`, { cause: err });
@@ -938,7 +1071,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     });
                 }
                 let receiptPath = null;
-                const report = await writeReceipt(RECEIPT_DIR, buildReceipt({
+                const receiptWrite = await writeObservedReceipt(mode, buildReceipt({
                     mode,
                     reviewId: input.reviewId,
                     // Derive BOTH name and host from the reviewed session target (not
@@ -959,8 +1092,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     agentName: input.agentName,
                     cardLast4: input.cardLast4,
                 }));
-                if (report.written)
-                    receiptPath = report.path;
+                if (receiptWrite.report.written)
+                    receiptPath = receiptWrite.report.path;
                 return finishAttempt({
                     outcome: result.outcome,
                     confirmationRef: result.confirmationRef ?? null,
@@ -973,6 +1106,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     credentialIssued: result.credentialLifecycle !== 'not-requested',
                     credentialDisclosed: result.credentialLifecycle === 'partially-exposed' ||
                         result.credentialLifecycle === 'fully-filled',
+                    receiptWrite: receiptWrite.event,
                 });
             }
             catch (error) {

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

@@ -8,6 +8,7 @@ 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 CheckoutRoute = 'guest-card';
 export type CheckoutOutcome = 'reviewed-dry-run'
 /** Historical receipt value from the credential-disclosing dry-run. */
  | 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate'
@@ -56,6 +57,7 @@ export type CheckoutResult = {
 };
 export type PrepareCheckoutOptions = {
     url: string;
+    checkoutRoute: CheckoutRoute;
     mandate: Mandate;
     browser: Browser;
     contact?: Contact;
@@ -63,6 +65,16 @@ export type PrepareCheckoutOptions = {
     currency?: string;
     debugShotsDir?: string;
     webBotAuth?: WebBotAuthConfig | null;
+    /**
+     * Process-internal UCP provenance. Public callers may relay only handoffId;
+     * this origin set is recovered by the CLI from its single-use registry.
+     */
+    trustedMerchantIdentity?: Readonly<{
+        handoffId: string;
+        checkoutId: string;
+        allowedOrigins: readonly string[];
+        expiresAt: string;
+    }>;
 };
 export type RunCheckoutOptions = PrepareCheckoutOptions & {
     instrument: Instrument;
@@ -75,6 +87,8 @@ export type CheckoutReview = {
     id: string;
     url: string;
     merchantHost: string;
+    /** Exact origin frozen for a trusted UCP checkout; omitted for generic flows. */
+    merchantOrigin?: string;
     amountMinor: number;
     currency: string;
     mandateMaxAmountMinor: number;
@@ -82,6 +96,7 @@ export type CheckoutReview = {
     submitTarget: string | null;
     submitTargetFingerprint: Readonly<CheckoutSubmitTargetFingerprint> | null;
     detectedRoles: readonly string[];
+    checkoutRoute: CheckoutRoute;
 };
 export type CheckoutSubmitTargetFingerprint = {
     kind: 'submit-control' | 'text-button';
@@ -99,6 +114,7 @@ export type PreparedCheckout = {
     readonly fields: Readonly<FieldMap>;
     readonly evidence: EvidenceLog;
     readonly requiresAdapter: readonly string[];
+    readonly checkoutRoute: CheckoutRoute;
 };
 export type PrepareCheckoutResult = {
     status: 'ready';
@@ -174,6 +190,7 @@ export declare class InMemoryPreparedCheckoutStore implements PreparedCheckoutSe
     private scheduleReaper;
     private closeState;
 }
+export declare function trustedMerchantOriginRefusal(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): string | null;
 export declare function reconcileHeldOutcome(original: ObservedOutcome, held: ObservedOutcome): ObservedOutcome;
 export declare function debugShotMaskPlan(fields: FieldMap): {
     skipReason: string | null;