@visa/cli 4.1.0-rc.38 → 4.1.0-rc.39

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

@@ -128,7 +128,7 @@ function stripTrailingSlashes(value) {
  * rather than falling back to a client-held secret.
  */
 export async function runHostedApproval(opts) {
-    const { baseUrl, tokenId, target, consumerEmail, budget, maxDraws, perTransaction, intent, 
+    const { baseUrl, tokenId, target, consumerEmail, budget, agentJkt, maxDraws, perTransaction, intent, 
     // Default to stderr, NOT a no-op: the approval URL is the one thing a remote /
     // SSH / headless-terminal human needs to proceed, and swallowing it (the old
     // `() => {}` default) left it emitted nowhere readable. Tests inject their own.
@@ -137,6 +137,13 @@ export async function runHostedApproval(opts) {
     // passkey) needs more than the interactive 4-minute window; allow an env
     // override without threading a flag through every caller.
     timeoutMs = resolveApprovalTimeoutMs(), } = opts;
+    const canonicalJkt = typeof agentJkt === 'string' && /^[A-Za-z0-9_-]{43}$/.test(agentJkt);
+    if (budget && !canonicalJkt) {
+        throw new Error('a budget approval requires the exact current agent request-key JKT');
+    }
+    if (!budget && agentJkt !== undefined) {
+        throw new Error('agentJkt is accepted only for a budget approval');
+    }
     const base = stripTrailingSlashes(assertApprovalBaseUrl(baseUrl));
     // The server's currency map is uppercase ISO 4217; the loader normalizes the
     // target once, but normalize here too so a direct caller with a lowercase
@@ -183,6 +190,7 @@ export async function runHostedApproval(opts) {
                 currency,
                 ...(consumerEmail ? { consumerEmail } : {}),
                 ...(budget ? { budget: true } : {}),
+                ...(budget ? { agentJkt } : {}),
                 ...(budget && maxDraws !== undefined ? { maxDraws } : {}),
                 ...(budget && perTransaction !== undefined ? { perTransaction } : {}),
                 ...(intentSanitized !== undefined ? { intent: intentSanitized } : {}),
@@ -201,6 +209,9 @@ export async function runHostedApproval(opts) {
     // effort browser open for the interactive case.
     onApprovalUrl?.(approveUrl);
     log(`approve the purchase in your browser: ${approveUrl}`);
+    if (budget && agentJkt) {
+        log(`budget recipient request key: ${agentJkt.slice(0, 8)}…${agentJkt.slice(-6)}`);
+    }
     openUrl(approveUrl);
     let lastHeartbeat = now();
     // Keep the event loop alive for the whole poll wait. `defaultSleep` unref()'s
@@ -255,6 +266,13 @@ export async function runHostedApproval(opts) {
                         throw new Error('hosted approval context mismatch on budget — the approval was not for this ' +
                             'exact purchase; run the checkout again for a fresh link');
                     }
+                    if (budget && doc.context?.agentJkt !== agentJkt) {
+                        throw new Error('hosted approval context mismatch on agentJkt — the approval was not for this ' +
+                            'exact request key; run the checkout again for a fresh link');
+                    }
+                    if (!budget && doc.context?.agentJkt !== undefined) {
+                        throw new Error('hosted approval unexpectedly carried an agentJkt for a one-purchase request');
+                    }
                     // The advisory draw ceiling must survive the relay intact too — a relay
                     // that dropped or altered maxDraws would mint a budget token whose draw
                     // count no longer matches what the operator approved. Only the budget
@@ -277,12 +295,22 @@ export async function runHostedApproval(opts) {
                         throw new Error('hosted approval context mismatch on intent — the approval was not for this ' +
                             'exact purchase; run the checkout again for a fresh link');
                     }
+                    if (budget) {
+                        if (!Number.isSafeInteger(doc.validUntil) ||
+                            doc.validUntil <= Math.floor(now() / 1000)) {
+                            throw new Error('hosted budget approval completed without a valid future expiry');
+                        }
+                    }
+                    else if (doc.validUntil !== undefined) {
+                        throw new Error('hosted one-purchase approval unexpectedly carried a budget expiry');
+                    }
                     log('passkey approval received from the hosted page.');
                     return {
                         ...assuranceFromCeremony(target, doc.assuranceData),
                         ...(typeof doc.mintToken === 'string' && doc.mintToken
                             ? { mintToken: doc.mintToken }
                             : {}),
+                        ...(budget ? { validUntil: doc.validUntil } : {}),
                     };
                 }
                 // status 'pending' — the operator is still signing in / tapping.

package/dist/checkout-engine/live-fill-approval.js

@@ -48,7 +48,7 @@ export function assertSubmitAllowed(mode, env = process.env, isInteractive = pro
 }
 /** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
 export function approvalPhrase(mode, reviewId) {
-    return `${mode === 'submit' ? 'PAY' : 'FILL'} ${reviewId}`;
+    return `${mode === 'submit' ? 'PAY' : 'CHECK'} ${reviewId}`;
 }
 /** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
 export function formatAmountMinor(amountMinor, currency) {
@@ -62,11 +62,11 @@ export function approvalQuestion(mode, review, phrase) {
             `Type ${JSON.stringify(phrase)} to disclose the credential AND submit the order: `);
     }
     return (`Inspect the visible checkout. Type ${JSON.stringify(phrase)} ` +
-        `to disclose the credential to this page without submitting: `);
+        `to validate the reviewed page without minting, filling, or submitting a credential: `);
 }
 /** The one outcome each mode may exit 0 with. */
 export function isRunSuccess(mode, outcome) {
-    return outcome === (mode === 'submit' ? 'confirmed' : 'filled-dry-run');
+    return outcome === (mode === 'submit' ? 'confirmed' : 'reviewed-dry-run');
 }
 /**
  * True when the pay control was actually clicked but the run ended with an

package/dist/checkout-engine/mandate/card-mandate.d.ts

@@ -18,6 +18,8 @@ export type CardMandateMerchant = {
     countryCode: string;
 };
 export type CreateCardMandateInput = {
+    /** Exact current runtime request key selected before human approval. */
+    agentJkt: string;
     tokenId: string;
     assuranceData: unknown;
     ceilingMinor: number;
@@ -26,7 +28,7 @@ export type CreateCardMandateInput = {
     expiresAt: string;
     /** Max draws the ceiling intent may fulfil; defaults to DEFAULT_MANDATE_MAX_DRAWS. */
     maxDraws?: number;
-    /** BUDGET mandate — spendable at any merchant (see CardMandateRecord.crossMerchant). */
+    /** Cross-host retail budget; network category eligibility still applies. */
     crossMerchant?: boolean;
 };
 export type CreateIntentFn = (input: {
@@ -60,6 +62,8 @@ export type CardMandateFacts = {
     currencyCode: string;
     merchant: CardMandateMerchant;
     expiresAt: string;
+    /** Network-enforced maximum purchase count disclosed at approval. */
+    maxDraws: number;
 };
 /**
  * Create a card mandate: approve a spend CEILING once (the passkey assurance

package/dist/checkout-engine/mandate/card-mandate.js

@@ -61,6 +61,9 @@ export async function createCardMandate(input, deps) {
     }
     if (!input.tokenId?.trim())
         throw new Error('mandate requires a tokenId');
+    if (!/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(input.agentJkt)) {
+        throw new Error('mandate requires a canonical agent request-key JKT');
+    }
     const now = (deps.now ?? (() => new Date()))();
     const expiryMs = Date.parse(input.expiresAt);
     if (!Number.isFinite(expiryMs))
@@ -109,6 +112,7 @@ export async function createCardMandate(input, deps) {
     const record = {
         version: CARD_MANDATE_LEDGER_VERSION,
         mandateId: intentId,
+        agentJkt: input.agentJkt,
         tokenId: input.tokenId,
         ceilingMinor: input.ceilingMinor,
         spentMinor: 0,
@@ -121,6 +125,7 @@ export async function createCardMandate(input, deps) {
         approvalBaseUrl: deps.approvalBaseUrl,
         ...(deps.mintToken ? { mintToken: deps.mintToken } : {}),
         expiresAt: new Date(expiryMs).toISOString(),
+        maxDraws,
         createdAt: now.toISOString(),
         draws: [],
         ...(input.crossMerchant ? { crossMerchant: true } : {}),
@@ -133,6 +138,7 @@ export async function createCardMandate(input, deps) {
         currencyCode,
         merchant: input.merchant,
         expiresAt: record.expiresAt,
+        maxDraws,
     };
 }
 const DRAW_REMEDY = 'the card-mandate draw did not complete — a ceiling-scoped assurance may not be honored ' +
@@ -180,7 +186,7 @@ export async function drawFromMandate(input, deps) {
             `${JSON.stringify(input.transaction.transactionAmount)} (minor units)`);
     }
     // Currency must always match; merchant must match UNLESS this is a budget
-    // (crossMerchant) mandate the owner approved for any merchant. The network
+    // (crossMerchant) mandate the owner approved for eligible retail merchants. The network
     // honors a ceiling-scoped cryptogram cross-merchant, so a budget mandate is
     // deliberately not host-restricted — the ceiling + per-transaction limit still
     // bound it.

package/dist/checkout-engine/mandate/mandate-ledger.d.ts

@@ -16,6 +16,8 @@ export type CardMandateRecord = {
     version: typeof CARD_MANDATE_LEDGER_VERSION;
     /** == the VGS intentId the ceiling approval created. */
     mandateId: string;
+    /** Exact runtime request key this budget was issued to. Absent on legacy rows. */
+    agentJkt?: string;
     tokenId: string;
     ceilingMinor: number;
     /** Permanently committed (drawn) spend, integer minor units. */
@@ -30,12 +32,14 @@ export type CardMandateRecord = {
     /** verify-web origin the ceiling intent was minted against. */
     approvalBaseUrl: string;
     /**
-     * Scoped mint token released by the ceiling approval, reused to draw
-     * cryptograms tap-free. Owner-only (0600) like the rest of the file; whether
-     * it stays valid across multiple draws is part of the unproven spike.
+     * Scoped token released by the ceiling approval. It bootstraps the one intent
+     * + register ceremony only. Each cryptogram AND its outcome confirmation use
+     * the exact per-draw verdict instead. Owner-only (0600).
      */
     mintToken?: string;
     expiresAt: string;
+    /** Network purchase-count cap disclosed at approval. Absent on legacy rows. */
+    maxDraws?: number;
     createdAt: string;
     draws: CardMandateDraw[];
     /**
@@ -53,18 +57,15 @@ export type CardMandateRecord = {
      * delegated (verdict-signed) draw would 404 `no_mandate`. Like `unhonoredAt`,
      * findCovering() SKIPS a register-failed mandate so the next checkout falls
      * through to a fresh per-purchase tap instead of surfacing a confusing
-     * `no_mandate`. Only set when a delegated binding was present and register was
-     * attempted; a bare bearer mandate (no binding) never carries it. ISO 8601.
+     * `no_mandate`. Mandate-start requires delegated card authority, so every
+     * created record attempted registration. ISO 8601.
      */
     registerFailedAt?: string;
     /**
-     * A BUDGET mandate: spendable at ANY merchant, not scoped to `merchantHost`.
-     * The card network honors a ceiling-scoped cryptogram cross-merchant (the
-     * mandate's merchant is only an advisory hint on the intent), so this is a
-     * deliberate product mode — the owner approved a spend budget usable anywhere,
-     * bounded by the same ceiling + per-transaction limit. When set, findCovering
-     * matches this mandate for any merchant and drawFromMandate skips the
-     * merchant-match guard. Absent/false = the default merchant-scoped mandate.
+     * A cross-host retail budget, not scoped to one `merchantHost`. The local
+     * selector may attempt it at any host, while the provider/network still
+     * applies the approved Retail/5999 category plus amount/count/time controls.
+     * `crossMerchant` is retained as the version-1 persisted field name.
      */
     crossMerchant?: boolean;
 };

package/dist/checkout-engine/mandate/mandate-ledger.js

@@ -75,6 +75,13 @@ function isExpired(record, now) {
     const end = Date.parse(record.expiresAt);
     return !Number.isFinite(end) || end <= now.getTime();
 }
+function committedDrawCount(record) {
+    return record.draws.filter((draw) => draw.status === 'committed').length;
+}
+function hasDrawCountHeadroom(record) {
+    return (record.maxDraws === undefined ||
+        committedDrawCount(record) + record.reservations.length < record.maxDraws);
+}
 function assertPositiveInteger(value, label) {
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new Error(`${label} must be a positive integer (minor units)`);
@@ -172,21 +179,22 @@ export class MandateLedger {
         // Selection order among covering candidates:
         //   1. Prefer a merchant-SCOPED mandate over a crossMerchant budget one —
         //      spend the dedicated grant for this merchant first and keep the broader
-        //      any-merchant budget for merchants that have no scoped mandate. Draining
+        //      broader retail budget for merchants that have no scoped mandate. Draining
         //      the budget for a purchase a scoped mandate already covers both wastes
         //      the general headroom and can later force a fresh tap at another merchant.
         //   2. Then the MOST headroom, then the latest expiry — never let a near-empty
         //      or near-expiry mandate get selected over a fuller, longer-lived sibling
         //      and then fail a draw the sibling would have covered.
         const candidates = file.mandates.filter((m) => 
-        // A crossMerchant (budget) mandate covers ANY merchant; a merchant-scoped
-        // one only its own host. A budget mandate the owner approved for "any
-        // merchant" is deliberately not host-restricted.
+        // A crossMerchant retail budget is locally cross-host; a merchant-scoped
+        // one only matches its own host. Network Retail/5999 eligibility is
+        // enforced downstream and is not inferred from a website hostname.
         (m.crossMerchant || m.merchantHost === query.merchantHost) &&
             m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
             !m.unhonoredAt &&
             !m.registerFailedAt &&
             !isExpired(m, now) &&
+            hasDrawCountHeadroom(m) &&
             remainingMinor(m) >= query.amountMinor);
         candidates.sort((a, b) => 
         // A scoped mandate (crossMerchant falsy → 0) sorts before a budget one (1).
@@ -255,6 +263,9 @@ export class MandateLedger {
             if (amountMinor > remainingMinor(record)) {
                 throw new Error(`draw ${amountMinor} exceeds remaining budget ${remainingMinor(record)} (minor units)`);
             }
+            if (!hasDrawCountHeadroom(record)) {
+                throw new Error(`mandate ${mandateId} reached its approved purchase-count limit`);
+            }
             const reservationId = `rsv_${randomBytes(9).toString('base64url')}`;
             record.reservations.push({ reservationId, amountMinor, reservedAt: now.toISOString() });
             await this.save(file);

package/dist/checkout-engine/run-live-fill.js

@@ -23,9 +23,10 @@ function v4Identity(file) {
 }
 /**
  * The agent's provisioned inbox address from mailbox.json, or null when no
- * inbox exists. Non-sensitive: address + opaque inbox id only. The sealed
- * scoped key is NEVER read here — OTP reads go through the out-of-process
- * resolver command (below), keeping the keychain gate outside this package.
+ * inbox exists. Non-sensitive: address + opaque inbox id only. The exportable
+ * scoped bearer credential is NEVER read here — OTP reads go through the
+ * out-of-process resolver command (below), keeping the owner-only file gate
+ * outside this package.
  */
 function loadAgentInboxEmail() {
     try {
@@ -42,7 +43,7 @@ function loadAgentInboxEmail() {
  * @visa/checkout-engine depends on playwright-core ONLY, so it must not import
  * @visa/wallet-tools/@visa/agent-mail to read OTPs. Instead the operator wires
  * an OUT-OF-PROCESS command (VISA_V4_OTP_RESOLVER_CMD) that shells to the
- * keychain-gated `wallet_mail_await_otp` tool: the scoped-key read and the
+ * owner-only-credential-gated `wallet_mail_await_otp` tool: the scoped-key read and the
  * from-domain guard live entirely behind that command. The command receives a
  * JSON request on argv and must print JSON `{code,fromDomain}` (or `null`) to
  * stdout. Absent ⇒ no resolver ⇒ the executor hands email OTP to a human.
@@ -158,7 +159,7 @@ const contact = await readOwnerOnlyJson(contactFile, 'contact file');
 // human's address: the merchant emails OTP/verification codes to whatever
 // contact.email it is given, and wallet_mail_await_otp can only read the
 // agent inbox. mailbox.json is non-sensitive provisioning state (address +
-// opaque inbox id — the SCOPED KEY is sealed separately and never read here),
+// opaque inbox id — the scoped bearer credential is stored separately and never read here),
 // so the runner reads it directly. Only override when a mailbox exists;
 // otherwise keep the contact-file email.
 const agentInboxEmail = loadAgentInboxEmail();

package/dist/checkout-engine/vic-confirmation.js

@@ -32,8 +32,8 @@ export async function reportVicOutcome(input) {
     catch (err) {
         return {
             posted: false,
-            reason: `confirmation POST failed: ${err.message} — the merchant outcome stands; ` +
-                'retry the confirmation for this intent out-of-band',
+            reason: `confirmation POST failed: ${err.message} — the merchant-reported outcome ` +
+                'remains unverified; retry the confirmation for this intent out-of-band',
         };
     }
 }