@visa/cli 4.1.0-rc.144 → 4.1.0-rc.146

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

@@ -16,7 +16,7 @@ import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
-import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
+import { VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
 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';
@@ -33,6 +33,21 @@ export function isTransientDrawFailure(err) {
     const msgs = [];
     let e = err;
     for (let i = 0; i < 5 && e; i++) {
+        // A refusal that declared itself TERMINAL wins outright, before any message
+        // matching. Message text is not a safe carrier for this decision: the mint
+        // client interpolates provider-supplied `upstream_codes` into its message
+        // for diagnosability, and an identifier like `request_timeout` would match
+        // the unanchored `tim(e|ed)-out` alternative below and silently reclassify
+        // a permanent 422 as transient — skipping markUnhonored and stranding the
+        // mandate in the retry-forever loop this classifier exists to prevent.
+        // Duck-typed rather than instanceof so it survives bundling and any
+        // re-wrapping across package boundaries. Optional chaining rather than an
+        // explicit null guard: the loop condition already proved `e` truthy, so a
+        // `e !== null` test is dead code, and `?.` stays safe on a primitive or a
+        // nullish link if that guard ever changes.
+        if (e?.terminal === true) {
+            return false;
+        }
         if (e instanceof Error && typeof e.message === 'string')
             msgs.push(e.message);
         e = e.cause;
@@ -765,73 +780,31 @@ export function createCliCheckoutEngine(deps = {}) {
                     instrument = new VgsLiveInstrument(reference, session.contact.fullName ?? '', fetchCredential);
                 }
                 else {
-                    // A v4 card grant is aggregate authority, not a credential-only escape
-                    // hatch. Its spend must be represented by a claimed mandate so auth can
-                    // atomically reserve both the card scope and aggregate budget before a
-                    // payable cryptogram is minted. Falling through to the legacy 1:1 tap
-                    // here would create a real card credential with zero canonical draw.
-                    if (isV4CardGrant) {
-                        return {
-                            outcome: 'failed',
-                            confirmationRef: null,
-                            receiptPath: null,
-                            detail: 'this v4 card grant has no active mandate covering the purchase; run ' +
+                    // #7348 fresh-tap retirement: card spend is mandate-only for EVERY
+                    // runtime. The legacy 1:1 fresh-tap flow that lived here minted a
+                    // payable credential outside the grant/mandate ledger — invisible to
+                    // spending controls. The server now refuses non-budget approvals at
+                    // registration and non-budget mint tokens at verification; this
+                    // client refusal exists to give the honest remedy up front instead
+                    // of a mid-flow server error.
+                    return {
+                        outcome: 'failed',
+                        confirmationRef: null,
+                        receiptPath: null,
+                        detail: isV4CardGrant
+                            ? 'this v4 card grant has no active mandate covering the purchase; run ' +
                                 '`visa mandate start --ceiling <usd> --per-transaction <usd>` for the selected ' +
                                 'agent, approve and claim the mandate, then retry this checkout. No payment ' +
-                                'credential was requested and no charge was made.',
-                            vicConfirmation: null,
-                            source: null,
-                            remainingMinor: null,
-                        };
-                    }
-                    // --- Legacy 1:1 fresh-tap flow --------------------------------------
-                    // Kept only for a pre-v4 credential-file runtime. A selected v4 grant
-                    // can never reach this parallel, non-canonical accounting path.
-                    source = 'fresh-tap';
-                    // Legacy credential file only. A v4 grant was refused above unless a
-                    // covering mandate selected the canonical draw path.
-                    const credential = await resolveCardInstrument(input);
-                    const assurance = await runHostedApproval({
-                        baseUrl: input.approvalBaseUrl,
-                        tokenId: credential.tokenId,
-                        target: session.target,
-                        consumerEmail: session.contact.email,
-                        onApprovalUrl: input.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;
-                    confirmationAuthority = mintToken;
-                    instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
-                        const { intentId, status } = await serverCreateIntent(confirmBase, mintToken, mintInput);
-                        try {
-                            const payment = await serverFetchCryptogram(confirmBase, mintToken, {
-                                tokenId: mintInput.tokenId,
-                                intentId,
-                                transaction: mintInput.transaction,
-                            });
-                            return { payment, intentId };
-                        }
-                        catch (err) {
-                            throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
-                        }
-                    });
+                                'credential was requested and no charge was made.'
+                            : 'one-off card approvals are retired (#7348): card spending always runs through ' +
+                                'an owner-approved mandate now. Attach card authority to this agent ' +
+                                '(`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait`), ' +
+                                'then start and claim a mandate (`visa mandate start <usd> --per-transaction <usd>`), ' +
+                                'and retry the checkout. No payment credential was requested and no charge was made.',
+                        vicConfirmation: null,
+                        source: null,
+                        remainingMinor: null,
+                    };
                 }
                 const mode = input.submit ? 'submit' : 'dry-run';
                 const result = await submitApprovedCheckout(input.reviewId, {

package/dist/checkout-engine/vgs-gateway/server-mint-client.d.ts

@@ -17,6 +17,25 @@ export type ServerMintDeps = {
  * — the mint must never throw here.
  */
 export declare function merchantOrigin(url: string): string;
+/**
+ * A definitive refusal from the cryptogram mint route — the request will not
+ * succeed if retried unchanged.
+ *
+ * `terminal` is the load-bearing field. Draw terminality used to be decided by
+ * regex over the error MESSAGE, which made it hostage to text nobody controls:
+ * this client now interpolates the provider's own `upstream_codes` into the
+ * message for diagnosability, and a provider identifier such as
+ * `request_timeout` would match the transient matcher's unanchored
+ * `tim(e|ed)-out` alternative — flipping a permanent 422 back to "transient",
+ * skipping markUnhonored, and stranding the mandate in the exact retry-forever
+ * loop this whole change exists to kill. Terminality is therefore carried
+ * structurally, and consumers must consult it BEFORE any message matching.
+ */
+export declare class ServerCryptogramRefusedError extends Error {
+    readonly status: number;
+    readonly terminal: true;
+    constructor(status: number, detail: string);
+}
 /**
  * Optional mandate override for serverCreateIntent. Absent → the historical
  * 1:1 fresh-tap shape is preserved byte-for-byte (cap = ceil(amount)+10 min 25,

package/dist/checkout-engine/vgs-gateway/server-mint-client.js

@@ -40,10 +40,44 @@ export function merchantOrigin(url) {
         return url;
     }
 }
+/**
+ * A definitive refusal from the cryptogram mint route — the request will not
+ * succeed if retried unchanged.
+ *
+ * `terminal` is the load-bearing field. Draw terminality used to be decided by
+ * regex over the error MESSAGE, which made it hostage to text nobody controls:
+ * this client now interpolates the provider's own `upstream_codes` into the
+ * message for diagnosability, and a provider identifier such as
+ * `request_timeout` would match the transient matcher's unanchored
+ * `tim(e|ed)-out` alternative — flipping a permanent 422 back to "transient",
+ * skipping markUnhonored, and stranding the mandate in the exact retry-forever
+ * loop this whole change exists to kill. Terminality is therefore carried
+ * structurally, and consumers must consult it BEFORE any message matching.
+ */
+export class ServerCryptogramRefusedError extends Error {
+    status;
+    terminal = true;
+    constructor(status, detail) {
+        super(`server cryptogram refused (${status}): ${detail}`);
+        this.name = 'ServerCryptogramRefusedError';
+        this.status = status;
+    }
+}
 /** Read a stable, non-secret error message from a route's JSON body. */
 async function routeError(res) {
     const doc = (await res.json().catch(() => null));
-    return doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    const base = doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    // Carry the provider's own status and rejected-attribute identifiers into the
+    // message when the route reflected them. Without this the operator sees only
+    // our status and has to go log-diving to learn WHICH field the gateway
+    // objected to — the gap that left a live create_intent 422 undiagnosable.
+    const parts = [];
+    if (typeof doc?.upstream_status === 'number')
+        parts.push(`upstream_status=${doc.upstream_status}`);
+    if (Array.isArray(doc?.upstream_codes) && doc.upstream_codes.length > 0) {
+        parts.push(`upstream_codes=${doc.upstream_codes.join(',')}`);
+    }
+    return parts.length > 0 ? `${base} [${parts.join(' ')}]` : base;
 }
 function bearer(mintToken) {
     return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
@@ -149,8 +183,12 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
             };
         }
         // A 4xx (bad request / binding refusal / auth) is terminal — never retry it.
-        if (res.status >= 400 && res.status < 500) {
-            throw new Error(`server cryptogram refused (${res.status}): ${await routeError(res)}`);
+        // 429 is the sole exception: it is an explicitly retryable 4xx, and treating
+        // it as terminal would let a transient rate limit permanently disable a
+        // healthy mandate. The route maps upstream rate limits to 503 today, so this
+        // is a guard against a future emitter, not a live path.
+        if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+            throw new ServerCryptogramRefusedError(res.status, await routeError(res));
         }
         lastError = `${res.status}: ${await routeError(res)}`;
         if (attempt < attempts)