@visa/cli 4.1.0-rc.25 → 4.1.0-rc.27

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

@@ -9,12 +9,70 @@ import { assertApprovalBaseUrl, resolveApprovalBaseUrl, runHostedApproval, } fro
 import { inlineTargetFromFlags } from './inline-target.js';
 import { createIntent, fetchCryptogram, postConfirmation } from './vgs-gateway/fetch-credential.mjs';
 import { cancelPreparedCheckout, prepareCheckout, submitApprovedCheckout, } from './executor.js';
-import { approvalPhrase, approvalQuestion, assertLegacyReferenceAllowed, assertSubmitAllowed, isRunSuccess, parseCheckoutMode, submitClickedWithoutConfirmation, } from './live-fill-approval.js';
+import { approvalPhrase, approvalQuestion, assertSubmitAllowed, isRunSuccess, parseCheckoutMode, submitClickedWithoutConfirmation, } from './live-fill-approval.js';
 import { assertOwnerOnlyFile, readOwnerOnlyJson } from './owner-only-file.js';
 import { buildReceipt, writeReceipt } from './receipt.js';
 import { loadRepoEnvDefaults } from './repo-env.js';
 import { reportVicOutcome } from './vic-confirmation.js';
-import { decimalToMinor, VgsAssuranceInstrument, VgsLiveInstrument, } from './vgs-live-instrument.js';
+import { decimalToMinor, VgsAssuranceInstrument, } from './vgs-live-instrument.js';
+import { execFile } from 'node:child_process';
+/** VISA_V4_HOME/identity/mailbox.json — mirrors @visa/wallet's v4Home default. */
+function v4Identity(file) {
+    const home = process.env.VISA_V4_HOME || join(homedir(), '.visa-v4');
+    return join(home, 'identity', 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.
+ */
+function loadAgentInboxEmail() {
+    try {
+        const raw = readFileSync(v4Identity('mailbox.json'), 'utf8');
+        const rec = JSON.parse(raw);
+        return typeof rec.email === 'string' && rec.email.includes('@') ? rec.email : null;
+    }
+    catch {
+        return null; // no mailbox provisioned, or unreadable — keep the contact-file email
+    }
+}
+/**
+ * Build the injected email-OTP resolver, or undefined when none is configured.
+ * @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
+ * 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.
+ */
+function buildOtpResolver() {
+    const cmd = process.env.VISA_V4_OTP_RESOLVER_CMD?.trim();
+    if (!cmd)
+        return undefined;
+    return (req) => new Promise((resolve) => {
+        execFile(cmd, [JSON.stringify(req)], { timeout: 150_000, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+            if (err) {
+                process.stdout.write(`email OTP resolver command failed: ${err.message}\n`);
+                return resolve(null); // fail CLEAN — the executor falls back to a human
+            }
+            try {
+                const parsed = JSON.parse(stdout.trim() || 'null');
+                if (parsed &&
+                    typeof parsed.code === 'string' &&
+                    typeof parsed.fromDomain === 'string') {
+                    process.stdout.write(`email OTP auto-resolved (from ${parsed.fromDomain})\n`);
+                    return resolve({ code: parsed.code, fromDomain: parsed.fromDomain });
+                }
+            }
+            catch {
+                /* fall through to null */
+            }
+            resolve(null);
+        });
+    });
+}
 function usage() {
     throw new Error('usage: pnpm fill:live --checkout-file <path> --contact-file <path> ' +
         '[--purchase-assurance-file <path>] [--approval-base-url <url>] ' +
@@ -27,9 +85,6 @@ function usage() {
         'the repo-root .env is loaded as env DEFAULTS (already-set variables win), e.g. for ' +
         'CHECKOUT_AGENT_MODE (--mode fallback); hosted approval on the deployed verify site ' +
         "is the built-in default (CHECKOUT_APPROVAL_BASE_URL='' forces the loopback ceremony)\n" +
-        'legacy: pnpm fill:live --reference-file <path> --contact-file <path> ' +
-        '(requires CHECKOUT_AGENT_ALLOW_LEGACY_REFERENCE=1 — bypasses purchase-assurance ' +
-        'validation, #5709)\n' +
         'Without --purchase-assurance-file the runner performs the device-binding ' +
         'ceremony itself after the typed approval. With --approval-base-url (or ' +
         'CHECKOUT_APPROVAL_BASE_URL) the passkey tap happens on the deployed verify ' +
@@ -67,7 +122,6 @@ function args() {
 // changes nothing.
 loadRepoEnvDefaults();
 const input = args();
-const referenceFile = input.get('--reference-file');
 const checkoutFile = input.get('--checkout-file');
 // Inline any-merchant mode: --merchant-url + --amount build the target
 // directly, so no checkout JSON has to exist. Throws its own scoped errors;
@@ -80,13 +134,8 @@ const agentCredentialFile = input.get('--agent-credential-file') ?? join(homedir
 // (#5709). Without the file, the runner performs the ceremony itself after
 // the typed approval (interactive ceremony mode).
 const purchaseAssuranceFile = input.get('--purchase-assurance-file');
-// Exactly ONE target source: legacy reference file, checkout file, or the
-// inline flags.
-const targetSources = [
-    typeof referenceFile === 'string',
-    typeof checkoutFile === 'string',
-    inlineTarget !== null,
-].filter(Boolean).length;
+// Exactly one target source: a checkout file or the inline flags.
+const targetSources = [typeof checkoutFile === 'string', inlineTarget !== null].filter(Boolean).length;
 if (targetSources !== 1 || typeof agentCredentialFile !== 'string') {
     usage();
 }
@@ -102,20 +151,25 @@ const challengeHoldMs = Number.isFinite(challengeHoldMinutes) && challengeHoldMi
 // Refuse an unarmed submit before anything else runs — no file is read, no
 // browser launches, no credential can possibly be minted.
 assertSubmitAllowed(mode);
-// The legacy path bypasses purchase-assurance validation (#5709) — default-off,
-// same fail-fast posture as the submit gate.
-assertLegacyReferenceAllowed(typeof referenceFile === 'string');
-const reference = typeof referenceFile === 'string'
-    ? await readOwnerOnlyJson(referenceFile, 'reference file')
-    : null;
-const target = reference
-    ? reference
-    : (inlineTarget ??
-        (await readOwnerOnlyJson(checkoutFile, 'checkout file')));
+const target = inlineTarget ??
+    (await readOwnerOnlyJson(checkoutFile, 'checkout file'));
 const contact = await readOwnerOnlyJson(contactFile, 'contact file');
-if (reference && (!reference.tokenId || !reference.intentId)) {
-    throw new Error('legacy reference requires tokenId and intentId');
+// Route merchant verification mail to the AGENT's provisioned inbox, not the
+// 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),
+// so the runner reads it directly. Only override when a mailbox exists;
+// otherwise keep the contact-file email.
+const agentInboxEmail = loadAgentInboxEmail();
+if (agentInboxEmail) {
+    contact.email = agentInboxEmail;
+    process.stdout.write(`Using agent inbox for merchant verification mail: ${agentInboxEmail}\n`);
 }
+// Optional out-of-process email-OTP resolver (see buildOtpResolver). Undefined
+// unless VISA_V4_OTP_RESOLVER_CMD is set — then merchant email codes are
+// auto-resolved single-use; otherwise email OTP falls to a human.
+const otpResolver = buildOtpResolver();
 if (typeof target.merchantName !== 'string' || !target.merchantName.trim()) {
     throw new Error('checkout target requires merchantName');
 }
@@ -125,8 +179,7 @@ if (typeof target.merchantCountryCode !== 'string' ||
 }
 // Normalize once so the instrument's strict uppercase re-check (which runs
 // after browser launch + operator confirmation) can't fail on a lowercase code
-// this loader already accepted. `target` aliases `reference` on the legacy
-// path, so both instruments see the normalized code.
+// this loader already accepted.
 target.merchantCountryCode = target.merchantCountryCode.toUpperCase();
 if (!contact.fullName && !(contact.firstName && contact.lastName)) {
     throw new Error('contact file needs fullName or firstName + lastName');
@@ -168,11 +221,9 @@ target.transactionCurrencyCode = currency;
 // instead of after the operator has completed the manual checkout review and
 // typed the FILL phrase (review nit). Contents stay unread until after
 // approval — the guard reads nothing.
-if (!reference) {
-    await assertOwnerOnlyFile(agentCredentialFile, 'CLI agent credential', 40 * 1024);
-    if (typeof purchaseAssuranceFile === 'string') {
-        await assertOwnerOnlyFile(purchaseAssuranceFile, 'purchase assurance', 40 * 1024);
-    }
+await assertOwnerOnlyFile(agentCredentialFile, 'CLI agent credential', 40 * 1024);
+if (typeof purchaseAssuranceFile === 'string') {
+    await assertOwnerOnlyFile(purchaseAssuranceFile, 'purchase assurance', 40 * 1024);
 }
 // Interactive ceremony mode (no --purchase-assurance-file): the runner performs
 // the device-binding ceremony itself after the typed approval. With an
@@ -180,7 +231,7 @@ if (!reference) {
 // loopback page, no local TLS/SDK/VGS-credential prerequisites); otherwise it
 // runs on the loopback page. Fail fast on the active mode's prerequisites
 // here, before any browser launches.
-const ceremonyMode = !reference && typeof purchaseAssuranceFile !== 'string';
+const ceremonyMode = typeof purchaseAssuranceFile !== 'string';
 // Hosted approval on the deployed verify site is the DEFAULT; set
 // CHECKOUT_APPROVAL_BASE_URL='' (empty) to force the loopback ceremony.
 const approvalBaseUrl = resolveApprovalBaseUrl(input.get('--approval-base-url'));
@@ -207,7 +258,9 @@ if (ceremonyMode) {
     // parent page (dev-harness certs) and the vendored SDK. The hosted page
     // brings its own origin and SDK — no local prerequisites.
     if (!hostedApproval) {
-        const harnessDir = fileURLToPath(new URL('../../../apps/v4-verify-web/dev-harness/', import.meta.url));
+        // GA graduation: the harness moved into this package (was
+        // apps/v4-verify-web/dev-harness); the vendored SDK ships with apps/web.
+        const harnessDir = fileURLToPath(new URL('../dev-harness/', import.meta.url));
         try {
             ceremonyTls = {
                 key: readFileSync(join(harnessDir, 'certs', 'key.pem')),
@@ -216,9 +269,9 @@ if (ceremonyMode) {
         }
         catch {
             throw new Error('interactive ceremony needs the dev-harness HTTPS certs — run ' +
-                'apps/v4-verify-web/dev-harness/generate-certs.sh once');
+                'packages/checkout-engine/dev-harness/generate-certs.sh once');
         }
-        const vendorSdkPath = fileURLToPath(new URL('../../../apps/v4-verify-web/public/vendor/vgs-agentic-auth.js', import.meta.url));
+        const vendorSdkPath = fileURLToPath(new URL('../../../apps/web/public/vendor/vgs-agentic-auth.js', import.meta.url));
         try {
             ceremonyVendorSdkJs = readFileSync(vendorSdkPath, 'utf8');
         }
@@ -317,83 +370,80 @@ try {
             let ceremonyFailure = null;
             let credential = null;
             let purchase = null;
-            if (!reference) {
-                credential = await readOwnerOnlyJson(agentCredentialFile, 'CLI agent credential', 40 * 1024);
-                if (typeof purchaseAssuranceFile === 'string') {
-                    // Fresh, purchase-scoped assurance — the instrument validates its
-                    // declared merchant/amount/currency scope + freshness against the
-                    // checkout target before any intent is minted (#5709).
-                    purchase = await readOwnerOnlyJson(purchaseAssuranceFile, 'purchase assurance', 40 * 1024);
-                }
-                else if (typeof credential.tokenId !== 'string' || !credential.tokenId.trim()) {
-                    ceremonyFailure = 'CLI agent credential requires tokenId';
-                }
-                else {
-                    process.stdout.write('approval received — complete the passkey on the Visa approval page…\n');
-                    try {
-                        purchase = hostedApproval
-                            ? await runHostedApproval({
-                                baseUrl: approvalBaseUrl,
+            credential = await readOwnerOnlyJson(agentCredentialFile, 'CLI agent credential', 40 * 1024);
+            if (typeof purchaseAssuranceFile === 'string') {
+                // Fresh, purchase-scoped assurance — the instrument validates its
+                // declared merchant/amount/currency scope + freshness against the
+                // checkout target before any intent is minted (#5709).
+                purchase = await readOwnerOnlyJson(purchaseAssuranceFile, 'purchase assurance', 40 * 1024);
+            }
+            else if (typeof credential.tokenId !== 'string' || !credential.tokenId.trim()) {
+                ceremonyFailure = 'CLI agent credential requires tokenId';
+            }
+            else {
+                process.stdout.write('approval received — complete the passkey on the Visa approval page…\n');
+                try {
+                    purchase = hostedApproval
+                        ? await runHostedApproval({
+                            baseUrl: approvalBaseUrl,
+                            tokenId: credential.tokenId,
+                            target,
+                            ...(ceremonyConsumerEmail ? { consumerEmail: ceremonyConsumerEmail } : {}),
+                            log: (line) => process.stdout.write(`${line}\n`),
+                        })
+                        : await runInteractiveCeremony({
+                            page: {
                                 tokenId: credential.tokenId,
-                                target,
-                                ...(ceremonyConsumerEmail ? { consumerEmail: ceremonyConsumerEmail } : {}),
-                                log: (line) => process.stdout.write(`${line}\n`),
-                            })
-                            : await runInteractiveCeremony({
-                                page: {
-                                    tokenId: credential.tokenId,
-                                    environment: process.env.VGS_ENVIRONMENT === 'sandbox' ? 'sandbox' : 'live',
-                                    consumerEmail: ceremonyConsumerEmail,
-                                    merchantName: target.merchantName,
-                                    amount: target.transactionAmount,
-                                    currency,
-                                    currencyNumericCode: currencyNumeric(currency),
-                                },
-                                target,
-                                vendorSdkJs: ceremonyVendorSdkJs,
-                                tls: ceremonyTls,
-                                mintAccessToken: mintCeremonyAccessToken,
-                                log: (line) => process.stdout.write(`${line}\n`),
-                            });
-                        process.stdout.write('passkey approved — minting the credential…\n');
-                    }
-                    catch (err) {
-                        ceremonyFailure = err.message;
-                    }
+                                environment: process.env.VGS_ENVIRONMENT === 'sandbox' ? 'sandbox' : 'live',
+                                consumerEmail: ceremonyConsumerEmail,
+                                merchantName: target.merchantName,
+                                amount: target.transactionAmount,
+                                currency,
+                                currencyNumericCode: currencyNumeric(currency),
+                            },
+                            target,
+                            vendorSdkJs: ceremonyVendorSdkJs,
+                            tls: ceremonyTls,
+                            mintAccessToken: mintCeremonyAccessToken,
+                            log: (line) => process.stdout.write(`${line}\n`),
+                        });
+                    process.stdout.write('passkey approved — minting the credential…\n');
+                }
+                catch (err) {
+                    ceremonyFailure = err.message;
                 }
             }
-            if (!reference && ceremonyFailure !== null) {
+            if (ceremonyFailure !== null) {
                 result = await cancelPreparedCheckout(review.id, `device-binding ceremony failed: ${ceremonyFailure}`);
             }
             else {
-                const instrument = reference
-                    ? new VgsLiveInstrument(reference, cardholderName, fetchCryptogram)
-                    : new VgsAssuranceInstrument(credential, purchase, target, cardholderName, 
-                    // The minter surfaces the fresh intentId (unlike getCredential,
-                    // which discards it) so the VIC confirmation below can target it.
-                    async (input) => {
-                        const { intentId, status } = await createIntent(input);
-                        try {
-                            const payment = await fetchCryptogram({
-                                tokenId: input.tokenId,
-                                intentId,
-                                transaction: input.transaction,
-                            });
-                            return { payment, intentId };
-                        }
-                        catch (err) {
-                            // HTTP 201 at intent creation ≠ an authorized intent — carry
-                            // the creation-time status so a not-completed cryptogram is
-                            // diagnosable in place (#5709).
-                            throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
-                        }
-                    });
+                const instrument = new VgsAssuranceInstrument(credential, purchase, target, cardholderName, 
+                // The minter surfaces the fresh intentId (unlike getCredential,
+                // which discards it) so the VIC confirmation below can target it.
+                async (input) => {
+                    const { intentId, status } = await createIntent(input);
+                    try {
+                        const payment = await fetchCryptogram({
+                            tokenId: input.tokenId,
+                            intentId,
+                            transaction: input.transaction,
+                        });
+                        return { payment, intentId };
+                    }
+                    catch (err) {
+                        // HTTP 201 at intent creation ≠ an authorized intent — carry
+                        // the creation-time status so a not-completed cryptogram is
+                        // diagnosable in place (#5709).
+                        throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
+                    }
+                });
                 result = await submitApprovedCheckout(review.id, {
                     approval: { approved: true, reviewId: review.id },
                     instrument,
                     contact,
                     mode,
                     challengeHoldMs,
+                    ...(otpResolver ? { resolveEmailOtp: otpResolver } : {}),
                     onChallengeHold: (signal) => process.stdout.write(signal === 'body:link-wallet'
                         ? `Stripe Link wallet login appeared despite network suppression — this means Link engaged through an endpoint isStripeLinkConsumerRequest does not yet match. Do NOT enter the code (it would pay with a Link-saved card, not the minted credential): close the modal to continue as guest, then pull the Link request URL from the evidence log (note "linkSuppressed"/network trace) and extend the route predicate to cover it. Holding up to ${challengeHoldMinutes} min…\n`
                         : `issuer challenge detected (${signal ?? 'challenge'}) — complete the bank verification in the browser window (enter the code your bank sent). Holding up to ${challengeHoldMinutes} min…\n`),

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

@@ -24,3 +24,16 @@ export type FillResult = {
     ok: boolean;
     filled: FilledField[];
 };
+export type OtpRequest = {
+    /** ISO watermark captured BEFORE the click that triggers the OTP email. */
+    after: string;
+    /** The merchant hostname; the sender's registrable domain must match it. */
+    merchantHost: string;
+};
+export type OtpResolution = {
+    /** The single-use code. The executor fills it exactly once; never retried. */
+    code: string;
+    /** The sender's registrable domain — a trust signal, safe to log (no PII). */
+    fromDomain: string;
+};
+export type OtpResolver = (req: OtpRequest) => Promise<OtpResolution | null>;

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

@@ -6,15 +6,48 @@ export type ServerMintDeps = {
     sleep?: (ms: number) => Promise<void>;
     env?: NodeJS.ProcessEnv;
 };
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export declare function merchantOrigin(url: string): 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,
+ * quantity 1, 30-day window). Present → the card-mandate (budget) layer sets a
+ * CEILING decline threshold and a multi-draw quantity so one passkey approves a
+ * spend ceiling and later draws pull cryptograms under it without a fresh tap.
+ * Whether the network honors a ceiling-scoped assurance across multiple
+ * sub-amount draws is UNPROVEN — see packages/checkout-engine/src/mandate/.
+ */
+export type ServerIntentMandateOverride = {
+    /** Wire decline-threshold amount (major-unit decimal string), e.g. "500.00". */
+    declineThresholdAmount?: string;
+    /** Number of draws the intent may fulfil (VGS mandate `quantity`). */
+    quantity?: number;
+    /** ISO 8601 mandate validity end. */
+    effectiveUntil?: string;
+    /** Human-readable consumer prompt describing the ceiling grant. */
+    consumerPrompt?: string;
+};
 /**
  * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
  * credential and calls the gateway; we send the same mandate shape the local
- * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999).
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
  */
 export declare function serverCreateIntent(base: string, mintToken: string, input: {
     tokenId: string;
     assuranceData: unknown;
     transaction: VgsCheckoutTarget;
+    mandate?: ServerIntentMandateOverride;
 }, deps?: ServerMintDeps): Promise<{
     intentId: string;
     status: string | null;

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

@@ -21,6 +21,24 @@ function stripTrailingSlashes(value) {
         out = out.slice(0, -1);
     return out;
 }
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export function merchantOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
 /** Read a stable, non-secret error message from a route's JSON body. */
 async function routeError(res) {
     const doc = (await res.json().catch(() => null));
@@ -32,29 +50,37 @@ function bearer(mintToken) {
 /**
  * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
  * credential and calls the gateway; we send the same mandate shape the local
- * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999).
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
  */
 export async function serverCreateIntent(base, mintToken, input, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
     const { tokenId, assuranceData, transaction: t } = input;
-    const cap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const override = input.mandate ?? {};
+    const defaultCap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const declineThresholdAmount = override.declineThresholdAmount ?? String(defaultCap);
+    const quantity = override.quantity ?? 1;
+    const effectiveUntil = override.effectiveUntil ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+    const consumerPrompt = override.consumerPrompt ??
+        `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`;
     const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
         method: 'POST',
         headers: bearer(mintToken),
         body: JSON.stringify({
             tokenId,
-            consumerPrompt: `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`,
+            consumerPrompt,
             assuranceData,
             mandates: [
                 {
                     description: `Purchase at ${t.merchantName}`,
-                    declineThresholdAmount: String(cap),
+                    declineThresholdAmount,
                     declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
-                    effectiveUntil: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+                    effectiveUntil,
                     merchantCategory: 'Retail',
                     merchantCategoryCode: '5999',
                     preferredMerchantName: t.merchantName,
-                    quantity: 1,
+                    quantity,
                 },
             ],
         }),
@@ -89,7 +115,9 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
         intentId,
         transaction: {
             merchantName: t.merchantName,
-            merchantUrl: t.merchantUrl,
+            // Send the merchant ORIGIN, not the full (possibly huge) checkout URL — an
+            // oversized merchantUrl makes the downstream cryptogram mint 502 (proven live).
+            merchantUrl: merchantOrigin(t.merchantUrl),
             merchantCountryCode: t.merchantCountryCode,
             transactionAmount: t.transactionAmount,
             transactionCurrencyCode: t.transactionCurrencyCode.toUpperCase(),

package/dist/checkout-engine/vgs-live-instrument.d.ts

@@ -83,6 +83,33 @@ export type VicConfirmationTarget = {
     intentId: string;
 };
 export declare function decimalToMinor(value: unknown): number | null;
+/**
+ * Currencies whose minor unit is 1/100 of the major unit (2 decimal places).
+ * minorToDecimal's /100 + pad-to-2 rendering is ONLY correct for these. The
+ * card mandate path accepts any 3-letter ISO code, so a 0- or 3-decimal
+ * currency (JPY, BHD, …) would otherwise be emitted with a wrong wire amount.
+ * We only support USD/USDC today; extend deliberately (and fix the exponent)
+ * before adding any non-2-decimal currency.
+ *
+ * NOTE (scanner FP pre-empt): this is a CLIENT-SIDE currency-exponent lookup for
+ * rendering a wire amount in @visa/checkout-engine — it is NOT the cross-store
+ * `PAYMENT_CURRENCIES` enum governed by apps/auth/src/shared-validators.ts, and
+ * this package cannot import from apps/auth (no dependency edge). It intentionally
+ * does not mirror that enum's membership; do not "reconcile" the two.
+ */
+export declare const TWO_DECIMAL_CURRENCIES: Set<string>;
+/**
+ * Inverse of decimalToMinor: render integer minor units as a major-unit decimal
+ * string ("D.DD") for the VGS wire (e.g. a ceiling of 50000 minor → "500.00").
+ * Integer-only; never floating-point money. Throws on a non-integer/negative so
+ * a bad accounting value cannot silently reach the network.
+ *
+ * The /100 + pad-to-2 rendering assumes a 2-decimal (exponent-2) currency. Pass
+ * `currencyCode` on any path that accepts arbitrary currencies (the mandate
+ * path) and it REFUSES a non-2-decimal currency rather than emit a wrong wire
+ * amount. Omit it only where the currency is already known to be USD/USDC.
+ */
+export declare function minorToDecimal(minor: number, currencyCode?: string): string;
 /**
  * Refuse to mint an intent unless the assurance is fresh and its declared
  * scope matches the checkout target exactly. `now` is injectable so the

package/dist/checkout-engine/vgs-live-instrument.js

@@ -19,6 +19,43 @@ export function decimalToMinor(value) {
     const minor = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));
     return Number.isSafeInteger(minor) ? minor : null;
 }
+/**
+ * Currencies whose minor unit is 1/100 of the major unit (2 decimal places).
+ * minorToDecimal's /100 + pad-to-2 rendering is ONLY correct for these. The
+ * card mandate path accepts any 3-letter ISO code, so a 0- or 3-decimal
+ * currency (JPY, BHD, …) would otherwise be emitted with a wrong wire amount.
+ * We only support USD/USDC today; extend deliberately (and fix the exponent)
+ * before adding any non-2-decimal currency.
+ *
+ * NOTE (scanner FP pre-empt): this is a CLIENT-SIDE currency-exponent lookup for
+ * rendering a wire amount in @visa/checkout-engine — it is NOT the cross-store
+ * `PAYMENT_CURRENCIES` enum governed by apps/auth/src/shared-validators.ts, and
+ * this package cannot import from apps/auth (no dependency edge). It intentionally
+ * does not mirror that enum's membership; do not "reconcile" the two.
+ */
+export const TWO_DECIMAL_CURRENCIES = new Set(['USD', 'USDC']);
+/**
+ * Inverse of decimalToMinor: render integer minor units as a major-unit decimal
+ * string ("D.DD") for the VGS wire (e.g. a ceiling of 50000 minor → "500.00").
+ * Integer-only; never floating-point money. Throws on a non-integer/negative so
+ * a bad accounting value cannot silently reach the network.
+ *
+ * The /100 + pad-to-2 rendering assumes a 2-decimal (exponent-2) currency. Pass
+ * `currencyCode` on any path that accepts arbitrary currencies (the mandate
+ * path) and it REFUSES a non-2-decimal currency rather than emit a wrong wire
+ * amount. Omit it only where the currency is already known to be USD/USDC.
+ */
+export function minorToDecimal(minor, currencyCode) {
+    if (!Number.isSafeInteger(minor) || minor < 0) {
+        throw new Error('minor units must be a non-negative safe integer');
+    }
+    if (currencyCode !== undefined && !TWO_DECIMAL_CURRENCIES.has(currencyCode.toUpperCase())) {
+        throw new Error(`minorToDecimal only supports 2-decimal currencies (${[...TWO_DECIMAL_CURRENCIES].join('/')}); refusing to emit a wire amount for ${currencyCode}`);
+    }
+    const whole = Math.floor(minor / 100);
+    const fraction = minor % 100;
+    return `${whole}.${String(fraction).padStart(2, '0')}`;
+}
 function validateTarget(reference, ctx) {
     if (typeof reference.merchantName !== 'string' ||
         typeof reference.merchantCountryCode !== 'string' ||