@visa/cli 4.1.0-rc.24 → 4.1.0-rc.240

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

@@ -1,25 +1,94 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { exec } from 'node:child_process';
 import { assuranceFromCeremony } from './ceremony.js';
+/** One short sentence — must match the relay's cap (agent-approval.ts). */
+export const APPROVAL_INTENT_MAX_CHARS = 200;
+/**
+ * Sanitize an agent-supplied intent to what the relay will accept and the page
+ * will display: control chars (and JS line separators) stripped, trimmed,
+ * TRUNCATED to the cap (the runner is the agent's own side, so truncating here
+ * beats a failed registration; the server still rejects an over-cap value).
+ * Returns undefined when nothing displayable remains.
+ */
+export function sanitizeApprovalIntent(value) {
+    if (value === undefined)
+        return undefined;
+    const cleaned = value
+        .replace(/[\p{Cc}\u2028\u2029]/gu, '')
+        .trim()
+        .slice(0, APPROVAL_INTENT_MAX_CHARS)
+        .trim();
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * The operator saw the request and said NO. Terminal and non-retryable: the
+ * relay entry is consumed, re-running would only re-ask a human who already
+ * refused. Callers must not classify this as transient.
+ */
+export class HostedApprovalDeclinedError extends Error {
+    constructor() {
+        super('The approver declined this request — the checkout was cancelled and nothing was charged');
+        this.name = 'HostedApprovalDeclinedError';
+    }
+}
 export const HOSTED_APPROVAL_TIMEOUT_MS = 4 * 60 * 1000;
 export const HOSTED_APPROVAL_POLL_MS = 3_000;
+/** Emit a "still waiting" heartbeat roughly every this-many ms during the poll. */
+export const HOSTED_APPROVAL_HEARTBEAT_MS = 30_000;
+/**
+ * Resolve the approval timeout: `CHECKOUT_APPROVAL_TIMEOUT_MS` (seconds*1000, an
+ * integer ms) overrides the default when it parses to a positive integer.
+ * Lets an operator widen the window for separate-device / headless approval
+ * without threading a flag through every caller. Invalid values fall back.
+ */
+export function resolveApprovalTimeoutMs() {
+    const raw = process.env.CHECKOUT_APPROVAL_TIMEOUT_MS;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isSafeInteger(n) && n > 0)
+            return n;
+    }
+    return HOSTED_APPROVAL_TIMEOUT_MS;
+}
 /** Unref'd so a raced-and-abandoned deadline timer can never hold the process open. */
 const defaultSleep = (ms) => new Promise((r) => {
     const t = setTimeout(r, ms);
     t.unref?.();
 });
 function defaultOpenUrl(url) {
-    // Quoting: the URL is server-origin + our own base64url challenge — no
-    // shell-hostile characters — but single-quote anyway.
-    exec(`open '${url.replaceAll("'", "'\\''")}'`);
+    // Best-effort convenience only — the URL is always surfaced via `log`/
+    // `onApprovalUrl`, so this must never throw or hang if there is no browser.
+    // `CHECKOUT_SKIP_BROWSER_OPEN=1` or `VISA_SUPPRESS_BROWSER=true|1` disables it
+    // (headless/agent hosts where launching a browser on the WRONG machine is pointless or noisy).
+    if (process.env.CHECKOUT_SKIP_BROWSER_OPEN === '1' ||
+        process.env.CHECKOUT_SKIP_BROWSER_OPEN === 'true' ||
+        process.env.VISA_SUPPRESS_BROWSER === '1' ||
+        process.env.VISA_SUPPRESS_BROWSER === 'true' ||
+        process.env.VISA_CLI_NO_BROWSER === '1' ||
+        process.env.VISA_CLI_NO_BROWSER === 'true')
+        return;
+    // Platform-appropriate opener; unknown platforms just skip (the URL is logged).
+    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';
+    if (process.platform !== 'darwin' && process.platform !== 'win32' && process.platform !== 'linux')
+        return;
+    const quoted = `'${url.replaceAll("'", "'\\''")}'`;
+    try {
+        // exec is async and fire-and-forget; swallow the callback error so a missing
+        // opener binary (common on headless Linux) can never surface as a failure.
+        exec(`${opener} ${quoted}`, () => { });
+    }
+    catch {
+        // Spawn failure (no shell, sandboxed) — ignore; the printed URL is the path.
+    }
 }
 /**
- * The one deployed verify site — hosted approval is the NORMAL path (no local
- * certs, no vendored SDK, no localhost anywhere), so its origin is a built-in
- * default rather than per-machine config. Not a secret: it's the public page
- * the operator's browser opens anyway.
+ * The staging apps/web deploy (which now hosts the /agent/enroll/approve page
+ * after the v4-verify-web GA graduation) — hosted approval is the NORMAL path
+ * (no local certs, no vendored SDK, no localhost anywhere), so its origin is a
+ * built-in default rather than per-machine config. Not a secret: it's the
+ * public page the operator's browser opens anyway.
  */
-export const DEFAULT_APPROVAL_BASE_URL = 'https://v4-verify-web-visa-code-preview.up.railway.app';
+export const DEFAULT_APPROVAL_BASE_URL = 'https://web-visa-code-preview.up.railway.app';
 /**
  * Flag > environment > built-in default. An explicitly EMPTY value
  * (CHECKOUT_APPROVAL_BASE_URL='') opts out of hosted approval entirely —
@@ -64,16 +133,36 @@ function stripTrailingSlashes(value) {
  * rather than falling back to a client-held secret.
  */
 export async function runHostedApproval(opts) {
-    const { baseUrl, tokenId, target, consumerEmail, log = () => { }, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, timeoutMs = HOSTED_APPROVAL_TIMEOUT_MS, } = opts;
+    const { baseUrl, tokenId, target, consumerEmail, 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.
+    log = (line) => void process.stderr.write(`${line}\n`), onApprovalUrl, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, 
+    // A human approving on a SEPARATE device (open the link, sign in, tap the
+    // 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 (!canonicalJkt) {
+        throw new Error('a budget approval requires the exact current agent request-key JKT');
+    }
     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
     // code registers (and verifies) the same value the relay stores.
     const currency = target.transactionCurrencyCode.toUpperCase();
+    // Sanitize once, register + verify the SAME value: the relay stores the
+    // sanitized form, so equality below must compare against it, not the raw input.
+    const intentSanitized = sanitizeApprovalIntent(intent);
     const verifier = randomBytes(32).toString('base64url');
     const challenge = createHash('sha256').update(verifier, 'utf8').digest('base64url');
     const deadline = now() + timeoutMs;
-    const timeoutError = () => new Error(`no passkey approval within ${Math.round(timeoutMs / 1000)}s — ` +
+    // Verification-neutral: what the page asks the human for is a per-card
+    // property (passkey ceremony, issuer one-time code, or nothing beyond the
+    // signed-in approval) that this runner never learns. Naming a passkey here
+    // told operators on code-verified cards to wait for a device prompt that was
+    // never coming, and then blamed the timeout on the step they never saw.
+    const timeoutError = () => new Error(`no approval within ${Math.round(timeoutMs / 1000)}s — ` +
         'the checkout was cancelled; run again to retry');
     // Bound EVERY request by the remaining deadline: race the fetch against the
     // (injectable) sleep and abort the request when the deadline wins, so a
@@ -107,6 +196,11 @@ export async function runHostedApproval(opts) {
                 amount: target.transactionAmount,
                 currency,
                 ...(consumerEmail ? { consumerEmail } : {}),
+                budget: true,
+                agentJkt,
+                maxDraws,
+                ...(perTransaction !== undefined ? { perTransaction } : {}),
+                ...(intentSanitized !== undefined ? { intent: intentSanitized } : {}),
             },
         }),
     });
@@ -115,57 +209,293 @@ export async function runHostedApproval(opts) {
         throw new Error(`could not register the hosted approval (${registerRes.status})` +
             (body.error ? `: ${body.error}` : ''));
     }
-    const approveUrl = `${base}/approve?req=${challenge}`;
+    // GA graduation: the approval page moved into apps/web under /agent/enroll
+    // (the /api/vgs/** routes above kept their paths verbatim).
+    const approveUrl = `${base}/agent/enroll/approve?req=${challenge}`;
+    // Surface the URL as DATA first (headless relay), then as a log line + best-
+    // effort browser open for the interactive case.
+    onApprovalUrl?.(approveUrl);
     log(`approve the purchase in your browser: ${approveUrl}`);
+    log(`budget recipient request key: ${agentJkt.slice(0, 8)}…${agentJkt.slice(-6)}`);
     openUrl(approveUrl);
-    for (;;) {
-        const res = await fetchWithDeadline(`${base}/api/vgs/agent-approval/claim`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ verifier }),
-        });
-        if (res.ok) {
-            const doc = (await res.json().catch(() => null));
-            if (doc?.status === 'completed') {
-                if (doc.assuranceData === undefined || doc.assuranceData === null) {
-                    throw new Error('hosted approval completed but carried no assuranceData');
-                }
-                // The context the approval was COMPLETED against must be exactly this
-                // run's checkout target — a divergent field means the relay entry was
-                // not ours (corruption, or a mutated registration) and the assurance
-                // is scoped to something else. Fail naming the field; no secrets here
-                // (merchant facts only).
-                const expected = {
-                    tokenId,
-                    merchantName: target.merchantName,
-                    merchantUrl: target.merchantUrl,
-                    merchantCountryCode: target.merchantCountryCode,
-                    amount: target.transactionAmount,
-                    currency,
-                };
-                for (const [field, want] of Object.entries(expected)) {
-                    if (doc.context?.[field] !== want) {
-                        throw new Error(`hosted approval context mismatch on ${field} — the approval was not for this ` +
+    let lastHeartbeat = now();
+    // Keep the event loop alive for the whole poll wait. `defaultSleep` unref()'s
+    // its timer (so the deadline race can't hang the process past the timeout), but
+    // that means the ONLY pending work between polls is an unref'd timer — in a bare
+    // CLI invocation (no stdin/other handles) node would exit 0 mid-poll, after the
+    // first `pending` claim and before the operator finishes the passkey, so the
+    // minted token is parked but never claimed. A ref'd keepalive, cleared on every
+    // exit, holds the process open until the poll loop returns/throws.
+    const keepAlive = setInterval(() => { }, 60_000);
+    try {
+        for (;;) {
+            const res = await fetchWithDeadline(`${base}/api/vgs/agent-approval/claim`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ verifier }),
+            });
+            if (res.ok) {
+                const doc = (await res.json().catch(() => null));
+                // The operator refused — terminal and immediate. Exit the wait now
+                // rather than polling out the timeout; retrying cannot help.
+                if (doc?.status === 'declined')
+                    throw new HostedApprovalDeclinedError();
+                if (doc?.status === 'completed') {
+                    // A passkey-exempt token ('otp' cardholder ID&V / 'none') runs no
+                    // ceremony and produces no assurance — the approval server marks the
+                    // claim explicitly (derived from the owner's verified card record at
+                    // complete-time). Only that marker excuses a null assuranceData; a
+                    // silently dropped payload still fails exactly as before.
+                    const assuranceExempt = doc.cardholderVerification === 'otp' || doc.cardholderVerification === 'none';
+                    if ((doc.assuranceData === undefined || doc.assuranceData === null) && !assuranceExempt) {
+                        throw new Error('hosted approval completed but carried no assuranceData');
+                    }
+                    // The context the approval was COMPLETED against must be exactly this
+                    // run's checkout target — a divergent field means the relay entry was
+                    // not ours (corruption, or a mutated registration) and the assurance
+                    // is scoped to something else. Fail naming the field; no secrets here
+                    // (merchant facts only).
+                    const expected = {
+                        tokenId,
+                        merchantName: target.merchantName,
+                        merchantUrl: target.merchantUrl,
+                        merchantCountryCode: target.merchantCountryCode,
+                        amount: target.transactionAmount,
+                        currency,
+                    };
+                    for (const [field, want] of Object.entries(expected)) {
+                        if (doc.context?.[field] !== want) {
+                            throw new Error(`hosted approval context mismatch on ${field} — the approval was not for this ` +
+                                'exact purchase; run the checkout again for a fresh link');
+                        }
+                    }
+                    // A budget approval must complete AS a budget approval — a relay that
+                    // dropped the flag did not complete OUR registration. Compare the
+                    // boolean explicitly (it is not a string, so it lives outside the
+                    // string-map loop above).
+                    if (doc.context?.budget !== true) {
+                        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 (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');
+                    }
+                    // The 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. Compare exactly,
+                    // the omitted/undefined case included, so a silently dropped value is
+                    // caught the same as a mutated one.
+                    if (doc.context?.maxDraws !== maxDraws) {
+                        throw new Error('hosted approval context mismatch on maxDraws — the approval was not for this ' +
+                            'exact purchase; run the checkout again for a fresh link');
+                    }
+                    // Same drop-or-mutate rule for the per-purchase cap: the term the
+                    // operator read must be the term the token enforces.
+                    if (doc.context?.perTransaction !== perTransaction) {
+                        throw new Error('hosted approval context mismatch on perTransaction — the approval was not for ' +
+                            'this exact purchase; run the checkout again for a fresh link');
+                    }
+                    // The intent is display-only, but a relay that altered it showed the
+                    // operator different words than the agent sent — refuse, either way.
+                    if (doc.context?.intent !== intentSanitized) {
+                        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 (!Number.isSafeInteger(doc.validUntil) ||
+                        doc.validUntil <= Math.floor(now() / 1000)) {
+                        throw new Error('hosted budget approval completed without a valid future expiry');
+                    }
+                    log(assuranceExempt
+                        ? 'approval received from the hosted page (code-verified card, no passkey).'
+                        : 'approval received from the hosted page (passkey-verified card).');
+                    return {
+                        ...assuranceFromCeremony(target, doc.assuranceData ?? null),
+                        ...(assuranceExempt ? { assuranceExempt: true } : {}),
+                        ...(typeof doc.mintToken === 'string' && doc.mintToken
+                            ? { mintToken: doc.mintToken }
+                            : {}),
+                        validUntil: doc.validUntil,
+                    };
                 }
-                log('passkey approval received from the hosted page.');
-                return {
-                    ...assuranceFromCeremony(target, doc.assuranceData),
-                    ...(typeof doc.mintToken === 'string' && doc.mintToken
-                        ? { mintToken: doc.mintToken }
-                        : {}),
-                };
+                // status 'pending' — the operator is still signing in / tapping.
+            }
+            else if (res.status === 404) {
+                // Registered moments ago, so absent now means expired or already claimed.
+                throw new Error('the hosted approval expired or was already used — run the checkout again for a fresh link');
             }
-            // status 'pending' — the operator is still signing in / tapping.
+            // Any other status (429 rate bucket, transient 5xx) polls through.
+            if (now() >= deadline)
+                throw timeoutError();
+            // Heartbeat so a human staring at a terminal (or an agent tailing logs)
+            // knows the wait is live and where to approve — the loop is otherwise silent
+            // for up to the full timeout between the open and the completed claim.
+            if (now() - lastHeartbeat >= HOSTED_APPROVAL_HEARTBEAT_MS) {
+                lastHeartbeat = now();
+                const leftS = Math.max(0, Math.round((deadline - now()) / 1000));
+                log(`still waiting for approval (~${leftS}s left) — approve at ${approveUrl}`);
+            }
+            await sleep(pollIntervalMs);
+        }
+    }
+    finally {
+        clearInterval(keepAlive);
+    }
+}
+const PICKUP_CODE_SHAPE = /^[A-Za-z0-9_-]{43}$/;
+const DECIMAL_AMOUNT_SHAPE = /^[0-9]+(\.[0-9]{1,2})?$/;
+function pickupMismatch(field, detail) {
+    return new Error(`mandate pickup code mismatch on ${field} — ${detail}. Ask the owner to start a fresh ` +
+        'mandate in the panel for this agent');
+}
+export async function claimMandatePickup(opts) {
+    const { baseUrl, pickupCode, agentJkt, expectedHandoffId, tokenId, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, attempts = 3, retryDelayMs = 1_000, } = opts;
+    // Both producers (runHostedApproval and the panel initiate route) mint the
+    // verifier as randomBytes(32).base64url = 43 chars; refuse anything else
+    // before it travels.
+    if (!PICKUP_CODE_SHAPE.test(pickupCode)) {
+        throw new Error('that does not look like a mandate pickup code (43 URL-safe characters) — ' +
+            'paste the code exactly as the panel displayed it');
+    }
+    if (!/^[A-Za-z0-9_-]{43}$/.test(agentJkt)) {
+        throw new Error('claiming a mandate pickup requires the exact current agent request-key JKT');
+    }
+    if (!tokenId.trim()) {
+        throw new Error('claiming a mandate pickup requires the provisioned card token id');
+    }
+    const base = stripTrailingSlashes(assertApprovalBaseUrl(baseUrl));
+    let res = null;
+    for (let attempt = 1;; attempt++) {
+        res = await fetchImpl(`${base}/api/vgs/agent-approval/claim`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ verifier: pickupCode }),
+        });
+        // 4xx other than 404/429 is a terminal shape/validation answer; 404 is the
+        // single-use/TTL answer. Only rate-limit and 5xx are worth a bounded retry —
+        // the entry is durable until claimed or expired.
+        if (res.ok || res.status === 404 || (res.status < 500 && res.status !== 429))
+            break;
+        if (attempt >= attempts)
+            break;
+        await sleep(retryDelayMs);
+    }
+    if (res.status === 404) {
+        throw new Error('this pickup code has expired or was already used — codes are single-use and live ' +
+            'about 10 minutes. Ask the owner to start a fresh mandate in the panel');
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`could not redeem the pickup code (${res.status})` + (body.error ? `: ${body.error}` : ''));
+    }
+    const doc = (await res.json().catch(() => null));
+    if (doc?.status === 'declined')
+        throw new HostedApprovalDeclinedError();
+    if (doc?.status !== 'completed') {
+        // A panel-issued pickup code is parked already-completed (the owner approved
+        // in the panel before the code existed). `pending` means this verifier came
+        // from an in-flight runner ceremony, not a mandate handoff — redeeming it
+        // here would race the runner that owns it.
+        throw new Error('this code is not a completed mandate handoff — it looks like an in-progress approval. ' +
+            'Use the pickup code the panel displayed after the owner approved the mandate');
+    }
+    const ctx = doc.context ?? {};
+    if (ctx.budget !== true) {
+        throw pickupMismatch('budget', 'the approval is a one-purchase approval, not a spend budget');
+    }
+    // A budget names exactly ONE agent, by one of two pins.
+    //
+    //  - `agentJkt` — the panel flow: the owner picked an agent that already
+    //    existed, so the approval names its key and this runtime compares keys.
+    //  - `handoffId` — the Add-agent dialog: the budget was minted before any
+    //    agent existed, so it names the handoff the agent would go on to redeem.
+    //    This runtime redeemed one moments ago and knows which, so the comparison
+    //    is just as concrete — it is simply a different identifier.
+    //
+    // EXACTLY one, enforced before either is compared. Neither pin is an unbound
+    // budget, and "no pin" must never be the quiet way past a binding check.
+    // BOTH pins is worse: it names two agents, and checking whichever one happens
+    // to match would let the weaker claim decide. The signer refuses to mint such
+    // a context and the approval store refuses to hold one, so this is the third
+    // and last place to say it — the one that runs on material already in hand.
+    const hasHandoffPin = typeof ctx.handoffId === 'string';
+    const hasAgentPin = typeof ctx.agentJkt === 'string';
+    if (hasHandoffPin === hasAgentPin) {
+        throw pickupMismatch('agentJkt', hasHandoffPin
+            ? 'this budget names two different agents at once — it binds to a handoff or to a key, never both'
+            : 'this budget names no agent at all, so nothing can prove it belongs to this runtime');
+    }
+    if (hasHandoffPin) {
+        if (!expectedHandoffId || ctx.handoffId !== expectedHandoffId) {
+            throw pickupMismatch('handoffId', 'this budget belongs to a different agent handoff than the one this runtime just claimed');
         }
-        else if (res.status === 404) {
-            // Registered moments ago, so absent now means expired or already claimed.
-            throw new Error('the hosted approval expired or was already used — run the checkout again for a fresh link');
+    }
+    else if (ctx.agentJkt !== agentJkt) {
+        throw pickupMismatch('agentJkt', 'the owner approved this mandate for a different agent key than this runtime holds');
+    }
+    if (ctx.tokenId !== tokenId) {
+        throw pickupMismatch('tokenId', "the mandate was approved against a different enrolled card than this runtime's card " +
+            'authority points at (the owner may have re-enrolled a card — re-run grant-card first)');
+    }
+    const ceiling = ctx.amount;
+    if (typeof ceiling !== 'string' || !DECIMAL_AMOUNT_SHAPE.test(ceiling) || Number(ceiling) <= 0) {
+        throw pickupMismatch('amount', 'the approved ceiling is missing or malformed');
+    }
+    const currency = ctx.currency;
+    if (typeof currency !== 'string' || !/^[A-Z]{3}$/.test(currency)) {
+        throw pickupMismatch('currency', 'the approved currency is missing or malformed');
+    }
+    const maxDraws = ctx.maxDraws;
+    if (!Number.isSafeInteger(maxDraws) || maxDraws < 1) {
+        throw pickupMismatch('maxDraws', 'the approved purchase count is missing or malformed');
+    }
+    const perTransaction = ctx.perTransaction;
+    if (perTransaction !== undefined) {
+        if (typeof perTransaction !== 'string' ||
+            !DECIMAL_AMOUNT_SHAPE.test(perTransaction) ||
+            Number(perTransaction) <= 0 ||
+            Number(perTransaction) > Number(ceiling)) {
+            throw pickupMismatch('perTransaction', 'the approved per-purchase cap is malformed');
         }
-        // Any other status (429 rate bucket, transient 5xx) polls through.
-        if (now() >= deadline)
-            throw timeoutError();
-        await sleep(pollIntervalMs);
     }
+    const merchantName = ctx.merchantName;
+    const merchantUrl = ctx.merchantUrl;
+    const merchantCountryCode = ctx.merchantCountryCode;
+    if (typeof merchantName !== 'string' ||
+        !merchantName.trim() ||
+        typeof merchantUrl !== 'string' ||
+        !merchantUrl.trim() ||
+        typeof merchantCountryCode !== 'string' ||
+        !merchantCountryCode.trim()) {
+        throw pickupMismatch('merchant', 'the approved budget target is missing or malformed');
+    }
+    if (typeof doc.mintToken !== 'string' || !doc.mintToken) {
+        throw new Error('the mandate handoff carried no mint token — the deployment that parked it ran the ' +
+            'dev-auth stub, which cannot mint draw authority. Re-initiate against a real deployment');
+    }
+    if (!Number.isSafeInteger(doc.validUntil) ||
+        doc.validUntil <= Math.floor(now() / 1000)) {
+        throw new Error('the mandate handoff carried no valid future expiry — ask the owner to re-initiate');
+    }
+    // Same exemption contract as runHostedApproval: only the server's explicit
+    // code-verified-card marker excuses a missing assurance payload.
+    const assuranceExempt = doc.cardholderVerification === 'otp' || doc.cardholderVerification === 'none';
+    if ((doc.assuranceData === undefined || doc.assuranceData === null) && !assuranceExempt) {
+        throw new Error('the mandate handoff completed but carried no assuranceData');
+    }
+    return {
+        assuranceData: doc.assuranceData ?? null,
+        assuranceExempt,
+        mintToken: doc.mintToken,
+        validUntil: doc.validUntil,
+        ceiling,
+        currency,
+        maxDraws: maxDraws,
+        ...(perTransaction !== undefined ? { perTransaction: perTransaction } : {}),
+        merchant: {
+            name: merchantName,
+            url: merchantUrl,
+            countryCode: merchantCountryCode,
+        },
+    };
 }

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

@@ -1,3 +1,10 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, } from './cli-engine.js';
+export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, type ReceiptWriteObservation, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';
+export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, CheckoutRoute, } from './executor.js';
+export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
+export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
+export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, type CreateCardMandateInput, type CreateCardMandateDeps, type CardMandateFacts, type DrawFromMandateInput, type DrawFromMandateDeps, type DrawResult, type CardMandateMerchant, } from './mandate/card-mandate.js';
+export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, type CardMandateRecord, type CardMandateLedgerFile, type CardMandateDraw, type CardMandateReservation, } from './mandate/mandate-ledger.js';
+export { WEB_BOT_AUTH_MAX_TTL_SECONDS, WEB_BOT_AUTH_DEFAULT_TTL_SECONDS, WEB_BOT_AUTH_SIGNATURE_LABEL, WEB_BOT_AUTH_TAG, WEB_BOT_AUTH_COVERED_COMPONENTS, buildWebBotAuthHeaders, buildWebBotAuthHeadersAsync, webBotAuthHeadersOrNone, webBotAuthHeadersOrNoneAsync, resolveWebBotAuthConfig, type WebBotAuthPrivateJwk, type WebBotAuthSigningKey, type WebBotAuthConfig, type WebBotAuthHeaders, type BuildHeadersParams, } from './web-bot-auth.js';

package/dist/checkout-engine/index.js

@@ -1,5 +1,12 @@
 // Public API of @visa/checkout-engine. The pay_merchant tool in @visa/cli
 // consumes createCliCheckoutEngine() through a structural seam; the core engine
 // primitives are re-exported for direct/embedded use.
-export { createCliCheckoutEngine, } from './cli-engine.js';
+export { createCliCheckoutEngine, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { readConfirmedMerchants, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
+export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
+export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, } from './mandate/card-mandate.js';
+export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, } from './mandate/mandate-ledger.js';
+export { WEB_BOT_AUTH_MAX_TTL_SECONDS, WEB_BOT_AUTH_DEFAULT_TTL_SECONDS, WEB_BOT_AUTH_SIGNATURE_LABEL, WEB_BOT_AUTH_TAG, WEB_BOT_AUTH_COVERED_COMPONENTS, buildWebBotAuthHeaders, buildWebBotAuthHeadersAsync, webBotAuthHeadersOrNone, webBotAuthHeadersOrNoneAsync, resolveWebBotAuthConfig, } from './web-bot-auth.js';

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

@@ -6,6 +6,12 @@ export type CardCredential = {
     cardholderName: string;
     /** Dynamic payment credential expiry, distinct from the card expiration. */
     credentialExpiresAt?: string;
+    /**
+     * Non-sensitive, bounded request-correlation handles returned by the mint
+     * route. These are evidence pointers, not card credential material.
+     */
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type InstrumentContext = {
     merchantHost: string;
@@ -24,6 +30,7 @@ export declare const OFFICIAL_TEST_PANS: {
     readonly visaSlowConfirm: "4000000000000069";
     readonly visaUnknownOutcome: "4000000000000044";
     readonly visaChallenge: "4000000000000010";
+    readonly visaEmailOtp: "4000000000000077";
 };
 export type TestCardOptions = {
     pan?: string;

package/dist/checkout-engine/instrument.js

@@ -22,6 +22,10 @@ export const OFFICIAL_TEST_PANS = {
     // page embedding an ACS challenge iframe that never completes — exercises
     // the observer's action-required (issuer challenge) path.
     visaChallenge: '4000000000000010',
+    // Ending 0077: the fixture acquirer emails a one-time code to the agent
+    // inbox and shows a 'check your email for a code' page with a one-time-code
+    // field — exercises the executor's agent-resolvable email-OTP subroutine.
+    visaEmailOtp: '4000000000000077',
 };
 function futureExpiry() {
     const now = new Date();

package/dist/checkout-engine/known-merchants.d.ts

@@ -0,0 +1,10 @@
+export type MerchantIdentity = {
+    /** Human-recognizable merchant name. */
+    name: string;
+    /** What the merchant is, e.g. "charity (animal rescue)". */
+    category: string;
+    /** The merchant's own site, when known — not the checkout URL. */
+    website?: string;
+};
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export declare const KNOWN_MERCHANT_IDENTITIES: Readonly<Record<string, MerchantIdentity>>;

package/dist/checkout-engine/known-merchants.js

@@ -0,0 +1,38 @@
+// Curated identities for checkout URLs the registry cannot name on its own.
+//
+// Hosted payment links are anonymous by construction: the page host is the
+// PSP's (donate.stripe.com, buy.stripe.com), the path is an opaque token, and
+// the receipt records nothing else. So a registry row for a completed payment
+// link answers "where can I use my card?" with a string no human recognizes.
+// This map carries the once-per-link human identification, keyed by the exact
+// checkout URL the receipts group on.
+//
+// Curation rule: an entry is added only after a checkout at that URL completed
+// for real (engine outcome 'confirmed' + VIC APPROVED — the same admission rule
+// confirmed-merchants.ts enforces) and the merchant behind the link was
+// identified by a person. The map never creates registry rows; it only names
+// rows the device's own receipts already earned. A URL missing here still
+// lists — it just shows as its host.
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export const KNOWN_MERCHANT_IDENTITIES = {
+    'https://donate.stripe.com/3cscPcaqY20H8ta4gh': {
+        name: 'NC Seaside Animal Rescue',
+        category: 'charity (animal rescue, NC nonprofit)',
+        website: 'https://www.ncseasideanimalrescue.org/make-a-donation',
+    },
+    'https://donate.stripe.com/14k3ei9TYgwFclq145': {
+        name: 'FreeCAD',
+        category: 'open-source project donation (CAD software)',
+        website: 'https://www.freecad.org',
+    },
+    'https://buy.stripe.com/dR6eWGaK41MX2YgaEF': {
+        name: 'scribepod',
+        category: 'indie creator tip jar (AI podcast project)',
+        website: 'https://github.com/yacineMTB/scribepod',
+    },
+    'https://donate.stripe.com/7sIcNj9Gs4WO6d29AA': {
+        name: 'n0bleKing GRAFFITI',
+        category: 'indie creator tip jar (pixel art and fonts)',
+        website: 'https://nobleking-graffiti.itch.io',
+    },
+};