@visa/cli 4.1.0-rc.66 → 4.1.0-rc.67

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

@@ -21,6 +21,8 @@ export type CliReviewInput = {
     amount: string;
     currency: string;
     credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
     contact: Contact;
     approvalBaseUrl: string;
     merchantName?: string;
@@ -66,6 +68,8 @@ export type CliStartMandateInput = {
     ceiling: string;
     currency: string;
     credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
     contact: Contact;
     approvalBaseUrl: string;
     /**
@@ -90,6 +94,16 @@ export type CliMandateFacts = CardMandateFacts & {
      * mandate-start now refuses before approval when no capability can register.
      */
     registerFailed?: boolean;
+    /**
+     * The server's refusal reason when {@link registerFailed} is true, verbatim.
+     * Carried out so the CLI can distinguish causes that need DIFFERENT operator
+     * actions — notably `token_mismatch`, which means the on-device grant record's
+     * cached token no longer matches the owner's live agentic token (they
+     * re-enrolled a card after the grant) and is fixed by re-running `grant-card`,
+     * not by retrying `mandate start`. Without the reason every failure reads as
+     * "the auth server was unreachable", which sends the operator in a loop.
+     */
+    registerFailureReason?: string;
 };
 type Session = {
     browser: Browser;

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

@@ -72,6 +72,33 @@ function classifyCardDrawVerdictFailure(err) {
     }
     return null;
 }
+/**
+ * Resolve the card instrument for one flow. Fail-closed: an unusable legacy file
+ * with no grant token rethrows (never silently proceeds), and the ONLY thing the
+ * fallback contributes is a token id — a non-secret handle the server
+ * re-authorizes against the owner (`requireTokenOwnership`) and against the live
+ * grant on every draw. Nothing here authorizes anything.
+ */
+async function resolveCardInstrument(input) {
+    let credential = null;
+    let readError = null;
+    try {
+        credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
+    }
+    catch (err) {
+        readError = err;
+    }
+    if (credential && typeof credential.tokenId === 'string' && credential.tokenId.trim()) {
+        return credential;
+    }
+    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
+        return { tokenId: input.cardTokenId, source: 'card-grant' };
+    }
+    throw new Error('no card instrument is available to this runtime: there is no usable credential at ' +
+        `${input.credentialPath} and no activated card:vic grant token was supplied. Run ` +
+        '`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait` to ' +
+        'attach one, or use a pre-provisioned VIC runtime.', readError instanceof Error ? { cause: readError } : undefined);
+}
 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.
@@ -150,7 +177,9 @@ export function createCliCheckoutEngine(deps = {}) {
                 url: 'https://retail-budget.visa/budget',
                 countryCode: 'US',
             };
-            const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
+            // Legacy credential file OR the activated card:vic grant's token — see
+            // resolveCardInstrument. A v2-paired runtime only ever has the latter.
+            const credential = await resolveCardInstrument(input);
             // The passkey ceremony is scoped to the CEILING + merchant (not one
             // charge) — that scope is the unproven part of the spike.
             const ceilingTarget = {
@@ -206,6 +235,7 @@ export function createCliCheckoutEngine(deps = {}) {
             // intent ID. A later draw requires its PoP verdict; the budget token never
             // falls back as payable authority.
             let registerFailed = false;
+            let registerFailureReason;
             if (registerCap && cardMandateRegister) {
                 const reg = await cardMandateRegister
                     .register({
@@ -222,6 +252,7 @@ export function createCliCheckoutEngine(deps = {}) {
                 }));
                 if (!reg.ok) {
                     registerFailed = true;
+                    registerFailureReason = reg.reason;
                     // 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
@@ -244,7 +275,12 @@ export function createCliCheckoutEngine(deps = {}) {
                                 `'mandate start'. mandateId=${facts.mandateId}\n`);
                 }
             }
-            return { ...facts, merchantHost: new URL(merchant.url).hostname, registerFailed };
+            return {
+                ...facts,
+                merchantHost: new URL(merchant.url).hostname,
+                registerFailed,
+                ...(registerFailureReason !== undefined ? { registerFailureReason } : {}),
+            };
         },
         async review(input) {
             const amountMinor = decimalToMinor(input.amount);
@@ -391,7 +427,11 @@ export function createCliCheckoutEngine(deps = {}) {
             }
             clearTimeout(session.cleanupTimer);
             try {
-                const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
+                // NO instrument read here. A tap-free mandate draw spends `covering
+                // .tokenId` (frozen into the mandate at start) and needs neither the
+                // legacy credential file nor a grant token; only the fresh-tap branch
+                // below needs one, and it resolves lazily so a grant-only device with an
+                // as-yet-unrefreshed token can still draw on a mandate it already holds.
                 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
@@ -550,6 +590,8 @@ export function createCliCheckoutEngine(deps = {}) {
                 else {
                     // --- 1:1 fresh-tap flow (unchanged) ---------------------------------
                     source = 'fresh-tap';
+                    // Legacy credential file OR the activated card:vic grant's token.
+                    const credential = await resolveCardInstrument(input);
                     const assurance = await runHostedApproval({
                         baseUrl: input.approvalBaseUrl,
                         tokenId: credential.tokenId,