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

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

@@ -18,7 +18,7 @@ import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realS
 import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, } from './vgs-live-instrument.js';
 import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
-import { createCardMandate, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.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 { reportVicOutcome as realReportVicOutcome, } from './vic-confirmation.js';
@@ -46,6 +46,32 @@ 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(' '));
 }
+/**
+ * A verdict refusal may be wrapped by drawFromMandate after its local
+ * reservation is released. Walk the cause chain so the original auth status +
+ * reasons still decide whether the mandate is permanently disabled.
+ */
+function classifyCardDrawVerdictFailure(err) {
+    const transientReasons = new Set(['challenge_failed', 'challenge_malformed', 'verdict_refused']);
+    let current = err;
+    for (let i = 0; i < 5 && current; i++) {
+        const candidate = current;
+        const status = typeof candidate.status === 'number' ? candidate.status : 0;
+        const reasons = Array.isArray(candidate.reasons)
+            ? candidate.reasons.filter((reason) => typeof reason === 'string')
+            : [];
+        if (status !== 0 || reasons.length > 0) {
+            return {
+                transient: status === 503 ||
+                    reasons.length === 0 ||
+                    reasons.every((reason) => transientReasons.has(reason)),
+                reasons,
+            };
+        }
+        current = candidate.cause;
+    }
+    return null;
+}
 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.
@@ -66,6 +92,7 @@ export function createCliCheckoutEngine(deps = {}) {
     const ledger = deps.ledger ?? defaultLedger;
     const now = deps.now ?? (() => new Date());
     const fetchMandateCryptogram = deps.serverFetchCryptogram ?? serverFetchCryptogram;
+    const postServerConfirmation = deps.serverPostConfirmation ?? serverPostConfirmation;
     const cardDrawVerdict = deps.cardDrawVerdict ?? null;
     const cardMandateRegister = deps.cardMandateRegister ?? null;
     async function closeSession(reviewId) {
@@ -95,6 +122,9 @@ export function createCliCheckoutEngine(deps = {}) {
             if (ceilingMinor === null || ceilingMinor <= 0) {
                 throw new Error(`invalid mandate ceiling ${JSON.stringify(input.ceiling)}`);
             }
+            if (input.currency.toUpperCase() !== 'USD') {
+                throw new Error('card spend budgets currently support USD only');
+            }
             if (input.perTransaction !== undefined) {
                 const perTxMinor = decimalToMinor(input.perTransaction);
                 if (perTxMinor === null || perTxMinor <= 0 || perTxMinor > ceilingMinor) {
@@ -102,24 +132,24 @@ export function createCliCheckoutEngine(deps = {}) {
                         'must be a positive amount at or under the ceiling');
                 }
             }
-            // BUDGET mandate: not tied to a merchant. The approval screen shows the
-            // any-merchant label so the owner sees the broader scope they're granting;
-            // the URL is a stable sentinel (advisory on the intent, ignored on draw).
-            const anyMerchant = input.anyMerchant === true;
-            if (!anyMerchant && !input.url) {
-                throw new Error('a merchant url is required unless anyMerchant (budget mandate) is set');
+            // A budget token can bootstrap one VGS intent and its register handshake,
+            // but it is never payable draw authority. Refuse before the passkey
+            // ceremony unless this runtime can both prove the separately provisioned
+            // card capability and register the resulting intent server-side.
+            const registerCap = cardMandateRegister?.loadCapability(input.agentRef) ?? null;
+            if (!cardMandateRegister || !registerCap) {
+                throw new Error('startCardMandate requires separately provisioned card authority in this runtime; ' +
+                    'identity pairing alone does not grant a card mandate');
             }
-            const merchant = anyMerchant
-                ? {
-                    name: 'spend budget mandate',
-                    url: 'https://any-merchant.visa/budget',
-                    countryCode: input.merchantCountryCode ?? 'US',
-                }
-                : {
-                    name: input.merchantName ?? new URL(input.url).hostname,
-                    url: input.url,
-                    countryCode: input.merchantCountryCode ?? 'US',
-                };
+            // There is one budget product: eligible retail merchants under the
+            // provider's required Retail/5999 network category, with total,
+            // per-purchase, count, and time bounds stated on the approval page. The
+            // sentinel is provider metadata, never a user-entered merchant route.
+            const merchant = {
+                name: 'retail spend budget',
+                url: 'https://retail-budget.visa/budget',
+                countryCode: 'US',
+            };
             const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
             // The passkey ceremony is scoped to the CEILING + merchant (not one
             // charge) — that scope is the unproven part of the spike.
@@ -140,8 +170,9 @@ export function createCliCheckoutEngine(deps = {}) {
                 target: ceilingTarget,
                 consumerEmail: input.contact.email,
                 budget: true,
+                agentJkt: registerCap.agentJkt,
                 onApprovalUrl: deps.onApprovalUrl,
-                ...(input.maxDraws !== undefined ? { maxDraws: input.maxDraws } : {}),
+                maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
                 ...(input.perTransaction !== undefined ? { perTransaction: input.perTransaction } : {}),
                 ...(input.intent !== undefined ? { intent: input.intent } : {}),
             });
@@ -150,29 +181,30 @@ export function createCliCheckoutEngine(deps = {}) {
                 throw new Error('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.');
             }
-            const expiresAt = input.expiresAt ?? new Date(now().getTime() + 24 * 60 * 60 * 1000).toISOString();
+            if (!Number.isSafeInteger(assurance.validUntil) ||
+                assurance.validUntil <= Math.floor(now().getTime() / 1000)) {
+                throw new Error('the approval server issued no valid budget expiry');
+            }
+            const expiresAt = new Date(assurance.validUntil * 1000).toISOString();
             const facts = await createCardMandate({
+                agentJkt: registerCap.agentJkt,
                 tokenId: credential.tokenId,
                 assuranceData: assurance.assuranceData,
                 ceilingMinor,
                 merchant,
                 currencyCode: input.currency,
                 expiresAt,
-                ...(input.maxDraws !== undefined ? { maxDraws: input.maxDraws } : {}),
-                ...(anyMerchant ? { crossMerchant: true } : {}),
+                maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
+                crossMerchant: true,
             }, {
                 createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, mintToken, i),
                 ledger,
                 approvalBaseUrl: input.approvalBaseUrl,
-                mintToken,
                 now,
             });
-            // #5942 CONVERGE: seed the auth-side cumulative store keyed by the VGS INTENT
-            // id (`facts.mandateId`) so a later delegated draw resolves the mandate. This
-            // is BEST-EFFORT: a failure is logged, never fatal — the bearer mint-token
-            // path still works, only the delegated draw needs the register row. Skipped
-            // entirely when no mode='card' delegated binding is present.
-            const registerCap = cardMandateRegister?.loadCapability() ?? null;
+            // Seed the one server-authoritative cumulative store keyed by the VGS
+            // intent ID. A later draw requires its PoP verdict; the budget token never
+            // falls back as payable authority.
             let registerFailed = false;
             if (registerCap && cardMandateRegister) {
                 const reg = await cardMandateRegister
@@ -277,6 +309,53 @@ export function createCliCheckoutEngine(deps = {}) {
                     remainingMinor: null,
                 };
             }
+            // The reviewId selects the prepared browser session, but the pay call also
+            // repeats the target facts. Refuse if any repeated fact disagrees so the
+            // caller cannot submit one reviewed checkout while labeling the result or
+            // telemetry as another. Never echo the full URLs: payment links can carry
+            // claimable secrets in their path/query.
+            let payUrl;
+            let reviewedUrl;
+            try {
+                payUrl = new URL(input.url).toString();
+                reviewedUrl = new URL(session.target.merchantUrl).toString();
+            }
+            catch {
+                await closeSession(input.reviewId);
+                return {
+                    outcome: 'failed',
+                    confirmationRef: null,
+                    receiptPath: null,
+                    detail: 'pay merchant URL is invalid or does not match the reviewed checkout — start a fresh review',
+                    vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
+                };
+            }
+            if (payUrl !== reviewedUrl) {
+                await closeSession(input.reviewId);
+                return {
+                    outcome: 'failed',
+                    confirmationRef: null,
+                    receiptPath: null,
+                    detail: 'pay merchant URL does not match the reviewed checkout — start a fresh review',
+                    vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
+                };
+            }
+            if (input.currency.toUpperCase() !== session.currency.toUpperCase()) {
+                await closeSession(input.reviewId);
+                return {
+                    outcome: 'failed',
+                    confirmationRef: null,
+                    receiptPath: null,
+                    detail: `pay currency ${JSON.stringify(input.currency)} does not match the reviewed currency (${session.currency}) — start a fresh review`,
+                    vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
+                };
+            }
             // 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
@@ -315,8 +394,8 @@ export function createCliCheckoutEngine(deps = {}) {
                 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
-                // 1:1 fresh-tap flow. `mintToken` requirement means a mandate with no
-                // persisted token can never silently short-circuit the tap.
+                // 1:1 fresh-tap flow. Mandates no longer persist the bootstrap token:
+                // it is consumed by intent creation + register and has no draw power.
                 const covering = await ledger.findCovering({
                     merchantHost: host,
                     currencyCode: session.currency,
@@ -325,94 +404,50 @@ export function createCliCheckoutEngine(deps = {}) {
                 });
                 let source;
                 let confirmBase;
-                let confirmToken;
+                // Fresh purchases confirm with their one-purchase mint token. Mandate
+                // draws set this only after the local reserve succeeds and auth returns
+                // the exact per-draw verdict used to mint the credential.
+                let confirmationAuthority = null;
                 let drawnRemaining = null;
                 let instrument;
-                if (covering && covering.mintToken) {
+                if (covering) {
                     // --- Tap-free mandate draw ------------------------------------------
                     source = 'mandate';
                     confirmBase = covering.approvalBaseUrl;
-                    // The bearer mint token stays the auth for the VIC confirmation POST
-                    // (the confirmation route accepts only the mint token). The CRYPTOGRAM
-                    // mint, however, may use a delegated verdict token — see below.
-                    confirmToken = covering.mintToken;
                     const mandateId = covering.mandateId;
-                    // #5923 delegated card-draw: when the agent holds a local mode='card'
-                    // binding, mint the cryptogram with a PoP-signed VERDICT token (the
-                    // verify-web tryVerdictAuth path) INSTEAD of the bearer mint token. No
-                    // binding (or seam not injected) → `drawToken` stays the bearer token:
-                    // today's #5917 draw, byte-for-byte unchanged (converge-not-break).
+                    // A mandate cryptogram is authorized only by a PoP-signed verdict.
+                    // The budget mint token is bootstrap-only and cannot bypass the
+                    // server reserve/commit ledger when local draw authority is absent.
                     //
                     // #5928 CRITICAL-2: the CLI does NOT settle the reservation. verify-web
                     // (which knows whether the cryptogram was payable) commits it on a
                     // payable mint and releases it on a decline, server-authoritatively, so
                     // the drawer can never release after a payable mint to dodge the ceiling.
-                    let drawToken = confirmToken;
-                    const capability = cardDrawVerdict?.loadCapability() ?? null;
-                    if (capability && cardDrawVerdict) {
-                        try {
-                            const { verdict } = await cardDrawVerdict.fetchVerdict({
-                                authBaseUrl: capability.authBaseUrl,
-                                agentKey: capability.agentKey,
-                                mandateId,
-                                // One draw per review; the reviewId is the server-side idempotency key.
-                                drawId: input.reviewId,
-                                draw: {
-                                    tokenId: covering.tokenId,
-                                    amount: session.target.transactionAmount,
-                                    currency: session.currency,
-                                    merchantName: session.target.merchantName,
-                                    merchantUrl: session.target.merchantUrl,
-                                    merchantCountryCode: session.target.merchantCountryCode,
-                                },
-                            });
-                            drawToken = verdict;
-                        }
-                        catch (err) {
-                            // The verdict gate refused (or a transient error) BEFORE the cryptogram
-                            // mint. This point is OUTSIDE the submitApprovedCheckout catch that
-                            // gracefully handles later draw errors, so an un-caught throw here
-                            // escapes pay() raw — making an agent WITH a card binding strictly more
-                            // fragile than one without (breaks converge-not-break). Convert it into
-                            // a graceful FAILED result instead. We do NOT silently fall back to the
-                            // bearer mint token: on an over_ceiling/reserve_refused refusal that
-                            // would DODGE the server-side ceiling the verdict path exists to enforce.
-                            //
-                            // Definitive gate refusal (no_mandate, over_ceiling, reserve_refused,
-                            // checkout_access_revoked, token_mismatch, …): the mandate cannot be
-                            // drawn, so disable it — findCovering then skips it and the NEXT
-                            // pay_merchant falls through to a fresh per-purchase tap. Transient
-                            // (503 card_draw_disabled, challenge hiccup, network): leave the mandate
-                            // healthy and surface a retryable message. Duck-typed: the engine cannot
-                            // import CardDrawRefusedError (it lives in @visa/cli, above this seam).
-                            const reasons = Array.isArray(err.reasons)
-                                ? err.reasons
-                                : [];
-                            const status = typeof err.status === 'number'
-                                ? err.status
-                                : 0;
-                            const TRANSIENT = new Set([
-                                'challenge_failed',
-                                'challenge_malformed',
-                                'verdict_refused',
-                            ]);
-                            const transient = status === 503 || reasons.length === 0 || reasons.every((r) => TRANSIENT.has(r));
-                            if (!transient) {
-                                // Best-effort: a mark failure must not turn a clean refusal into a throw.
-                                await ledger.markUnhonored(mandateId, now()).catch(() => { });
-                            }
-                            return {
-                                outcome: 'failed',
-                                confirmationRef: null,
-                                receiptPath: null,
-                                detail: transient
-                                    ? `the card-mandate draw could not be authorized right now (${reasons.join(', ') || 'temporary error'}) — retry shortly`
-                                    : `this card mandate can no longer be drawn (${reasons.join(', ') || 'refused'}); it has been disabled — retry the checkout to use a fresh per-purchase passkey tap`,
-                                vicConfirmation: null,
-                                source,
-                                remainingMinor: null,
-                            };
-                        }
+                    const verdictSeam = cardDrawVerdict;
+                    const capability = verdictSeam?.loadCapability(covering.agentJkt) ?? null;
+                    if (!capability || !verdictSeam) {
+                        return {
+                            outcome: 'failed',
+                            confirmationRef: null,
+                            receiptPath: null,
+                            detail: 'this mandate cannot draw because its delegated card authority is unavailable; ' +
+                                'restore the runtime binding or use a fresh per-purchase passkey approval',
+                            vicConfirmation: null,
+                            source,
+                            remainingMinor: null,
+                        };
+                    }
+                    if (covering.agentJkt && capability.agentJkt !== covering.agentJkt) {
+                        return {
+                            outcome: 'failed',
+                            confirmationRef: null,
+                            receiptPath: null,
+                            detail: 'this budget belongs to a different request key than the selected card capability; ' +
+                                'restore that exact runtime key or use a fresh per-purchase approval',
+                            vicConfirmation: null,
+                            source,
+                            remainingMinor: null,
+                        };
                     }
                     // VgsLiveInstrument mints against an EXISTING intent (the mandate) with
                     // no fresh assurance — exactly the draw semantics. The fetchCredential
@@ -435,7 +470,30 @@ export function createCliCheckoutEngine(deps = {}) {
                                 amountMinor: session.amountMinor,
                                 transaction: { ...transaction, transactionCurrencyCode: session.currency },
                             }, {
-                                fetchCryptogram: (i) => fetchMandateCryptogram(confirmBase, drawToken, i),
+                                // Ordering matters: reserve the local ledger FIRST, then ask
+                                // auth to reserve the server-authoritative budget immediately
+                                // before the payable mint. A local reserve race/expiry/file
+                                // failure therefore makes zero auth/verdict calls and cannot
+                                // strand a server reservation until its sweep.
+                                fetchCryptogram: async (i) => {
+                                    const { verdict } = await verdictSeam.fetchVerdict({
+                                        authBaseUrl: capability.authBaseUrl,
+                                        agentKey: capability.agentKey,
+                                        mandateId,
+                                        // One draw per review; the reviewId is auth's idempotency key.
+                                        drawId: input.reviewId,
+                                        draw: {
+                                            tokenId: covering.tokenId,
+                                            amount: session.target.transactionAmount,
+                                            currency: session.currency,
+                                            merchantName: session.target.merchantName,
+                                            merchantUrl: session.target.merchantUrl,
+                                            merchantCountryCode: session.target.merchantCountryCode,
+                                        },
+                                    });
+                                    confirmationAuthority = verdict;
+                                    return fetchMandateCryptogram(confirmBase, verdict, i);
+                                },
                                 ledger,
                                 now,
                             });
@@ -463,9 +521,19 @@ export function createCliCheckoutEngine(deps = {}) {
                             // Classify on the underlying gateway CAUSE, not the MandateDrawDeclinedError
                             // wrapper — the wrapper's own advisory text mentions "try again"/"network",
                             // which would otherwise self-classify every decline as transient.
-                            if (err instanceof MandateDrawDeclinedError &&
-                                !isTransientDrawFailure(err.cause ?? err)) {
-                                await ledger.markUnhonored(mandateId, now());
+                            if (err instanceof MandateDrawDeclinedError) {
+                                const verdictFailure = classifyCardDrawVerdictFailure(err);
+                                if (verdictFailure) {
+                                    if (!verdictFailure.transient) {
+                                        await ledger.markUnhonored(mandateId, now()).catch(() => { });
+                                    }
+                                    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 — retry the checkout to use a fresh per-purchase passkey tap`, { cause: err });
+                                }
+                                if (!isTransientDrawFailure(err.cause ?? err)) {
+                                    await ledger.markUnhonored(mandateId, now());
+                                }
                             }
                             // #5928 CRITICAL-2: the server-side reservation is released by
                             // verify-web (it saw the mint fail), not here — the CLI never settles.
@@ -507,11 +575,11 @@ export function createCliCheckoutEngine(deps = {}) {
                         };
                     }
                     confirmBase = input.approvalBaseUrl;
-                    confirmToken = mintToken;
+                    confirmationAuthority = mintToken;
                     instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
-                        const { intentId, status } = await serverCreateIntent(confirmBase, confirmToken, mintInput);
+                        const { intentId, status } = await serverCreateIntent(confirmBase, mintToken, mintInput);
                         try {
-                            const payment = await serverFetchCryptogram(confirmBase, confirmToken, {
+                            const payment = await serverFetchCryptogram(confirmBase, mintToken, {
                                 tokenId: mintInput.tokenId,
                                 intentId,
                                 transaction: mintInput.transaction,
@@ -542,7 +610,12 @@ export function createCliCheckoutEngine(deps = {}) {
                             transactionAmount: session.target.transactionAmount,
                             transactionCurrencyCode: session.currency,
                         },
-                        post: (confInput) => serverPostConfirmation(confirmBase, confirmToken, confInput),
+                        post: (confInput) => {
+                            if (!confirmationAuthority) {
+                                throw new Error('confirmation authority missing for the consumed VIC intent');
+                            }
+                            return postServerConfirmation(confirmBase, confirmationAuthority, confInput);
+                        },
                     });
                 }
                 let receiptPath = null;

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

@@ -1,4 +1,4 @@
-export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'credential-minted' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
+export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'credential-minted' | 'credential-skipped' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
 export type EvidenceStep = {
     ts: string;
     type: EvidenceStepType;

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

@@ -6,7 +6,9 @@ import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
 export type CheckoutMode = 'dry-run' | 'submit';
-export type CheckoutOutcome = 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate' | 'failed';
+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' | 'failed';
 export type CredentialLifecycle = 'not-requested' | 'minted-not-exposed' | 'partially-exposed' | 'fully-filled';
 export type CredentialTiming = {
     approvedAt?: string;

package/dist/checkout-engine/executor.js

@@ -2,7 +2,8 @@
 //   prepareCheckout(): navigate -> stabilize -> mandate gate -> resolve the
 //   review facts. No credential is requested or filled in this phase.
 //   submitApprovedCheckout(): verify the approval is bound to that review ->
-//   revalidate -> mint credential -> fill -> revalidate -> submit.
+//   revalidate -> in dry-run stop without requesting a credential; in submit
+//   mode mint -> fill -> revalidate -> submit.
 //
 // runCheckout() remains the one-shot, auto-approved compatibility wrapper.
 //
@@ -11,8 +12,8 @@
 //     runs before instrument.getCredential(). No credential is minted and no
 //     field is filled on a page the mandate does not cover.
 //   - The PRE-SUBMIT gate re-runs the full check with the resolved amount and
-//     currency. No submit ever happens without it passing. Dry-run never
-//     clicks submit.
+//     currency. No submit ever happens without it passing. Dry-run requests no
+//     credential and neither fills fields nor clicks submit.
 import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -967,6 +968,16 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, reason);
         }
         evidence.step('approval', { approved: true, reviewId: checkout.review.id });
+        if (opts.mode === 'dry-run') {
+            evidence.step('credential-skipped', {
+                reason: 'dry-run stops before credential mint or merchant-page disclosure',
+            });
+            evidence.step('submit', { would: true, target: approvalSubmit?.desc ?? 'none found' });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('reviewed-dry-run', state.fields, evidence, requiresAdapter, approvalSubmit
+                ? `validated the reviewed checkout; would click ${approvalSubmit.desc}`
+                : 'validated the reviewed checkout; no submit control detected');
+        }
         const credential = await opts.instrument.getCredential({
             merchantHost,
             amountMinor: approvedFacts.amountMinor,
@@ -1099,17 +1110,6 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedBeforeClick);
         }
-        if (opts.mode === 'dry-run') {
-            evidence.step('submit', { would: true, target: submit?.desc ?? 'none found' });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            if (missingCredentialRoles.length > 0) {
-                const adapterRequired = requiresAdapter.size > 0;
-                return makeResult(adapterRequired ? 'adapter-required' : 'partial-fill', state.fields, evidence, requiresAdapter, adapterRequired
-                    ? `credential fields require adapter: ${[...requiresAdapter].join(', ')}; missing ${missingCredentialRoles.join(', ')}`
-                    : `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
-            }
-            return makeResult('filled-dry-run', state.fields, evidence, requiresAdapter, submit ? `would click ${submit.desc}` : 'no submit control detected');
-        }
         if (missingCredentialRoles.length > 0) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('failed', state.fields, evidence, requiresAdapter, `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);

package/dist/checkout-engine/hosted-approval.d.ts

@@ -39,6 +39,12 @@ export type HostedApprovalOptions = {
      * accepts many sub-ceiling draws tap-free. Omit for a single-purchase approval.
      */
     budget?: boolean;
+    /**
+     * Exact current request-key thumbprint receiving a budget. Required for a
+     * budget and forbidden for a one-purchase approval; the authenticated page
+     * resolves it to the owner's stable agent before displaying or signing.
+     */
+    agentJkt?: string;
     /** Advisory max draws the ceiling intent may fulfil — carried onto the token. */
     maxDraws?: number;
     /**
@@ -132,4 +138,5 @@ export declare function assertApprovalBaseUrl(value: string): string;
  */
 export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance & {
     mintToken?: string;
+    validUntil?: number;
 }>;

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