@visa/cli 4.1.0-rc.26 → 4.1.0-rc.261

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

@@ -34,17 +34,24 @@ export type HostedApprovalOptions = {
     /** Prefills the approval page's enrollment-email field (optional). */
     consumerEmail?: string;
     /**
-     * BUDGET/mandate approval: `target.transactionAmount` is the approved spend
-     * CEILING (not one charge), so the server mints a BUDGET mint token that later
-     * accepts many sub-ceiling draws tap-free. Omit for a single-purchase approval.
+     * BUDGET/mandate approval — the only kind since #7348 retired the
+     * single-purchase plane: `target.transactionAmount` is the approved spend
+     * CEILING (not one charge), so the server mints a BUDGET mint token that
+     * later accepts many sub-ceiling draws tap-free.
      */
-    budget?: boolean;
-    /** Advisory max draws the ceiling intent may fulfil — carried onto the token. */
-    maxDraws?: number;
+    budget: true;
     /**
-     * Per-purchase cap (decimal string, <= the ceiling) on a BUDGET approval —
-     * shown on the approval page as a worst-case term and carried onto the mint
-     * token so the displayed cap is the enforced cap. Budget mode only.
+     * Exact current request-key thumbprint receiving the budget; the
+     * authenticated page resolves it to the owner's stable agent before
+     * displaying or signing.
+     */
+    agentJkt: string;
+    /** Max draws the ceiling intent may fulfil — carried onto the token. */
+    maxDraws: number;
+    /**
+     * Per-purchase cap (decimal string, <= the ceiling) — shown on the approval
+     * page as a worst-case term and carried onto the mint token so the displayed
+     * cap is the enforced cap.
      */
     perTransaction?: string;
     /**
@@ -132,4 +139,57 @@ export declare function assertApprovalBaseUrl(value: string): string;
  */
 export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance & {
     mintToken?: string;
+    validUntil?: number;
 }>;
+/**
+ * A panel-initiated mandate handoff, released by its single-use pickup code.
+ * The context here is SERVER truth (an owner-authenticated panel session parked
+ * it, and the code is the credential that releases it) — the runner had no part
+ * in registering it, so unlike {@link runHostedApproval} the fields are
+ * returned for the caller to act on rather than compared against a local run.
+ * What IS verified here is the binding: the entry must be a budget approval
+ * minted for exactly THIS runtime's request key and THIS device's card token.
+ */
+export type MandatePickupClaim = {
+    /** Null only when {@link assuranceExempt} — a code-verified card runs no ceremony. */
+    assuranceData: unknown;
+    assuranceExempt: boolean;
+    mintToken: string;
+    /** Unix seconds — the mandate lapse the owner approved in the panel. */
+    validUntil: number;
+    /** Decimal ceiling string exactly as approved (the context's `amount`). */
+    ceiling: string;
+    currency: string;
+    maxDraws: number;
+    perTransaction?: string;
+    merchant: {
+        name: string;
+        url: string;
+        countryCode: string;
+    };
+};
+export type ClaimMandatePickupOptions = {
+    /** The enrollment web deployment origin (apps/web). */
+    baseUrl: string;
+    /** Single-use pickup code (the approval verifier) the owner handed over. */
+    pickupCode: string;
+    /** This runtime's exact current request-key JKT — the only key the code may fund. */
+    agentJkt: string;
+    /**
+     * The agent handoff this runtime just redeemed, when the code came from one.
+     * A budget minted in the Add-agent dialog exists before the agent does, so it
+     * pins the handoff rather than a key; this is the value that pin is compared
+     * against. Absent for the panel flow, whose budgets pin a key instead.
+     */
+    expectedHandoffId?: string;
+    /** The card token id this runtime's card authority points at. */
+    tokenId: string;
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Bounded retries for transient 429/5xx; the claim itself is single-use. */
+    attempts?: number;
+    retryDelayMs?: number;
+};
+export declare function claimMandatePickup(opts: ClaimMandatePickupOptions): Promise<MandatePickupClaim>;

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

@@ -58,9 +58,14 @@ const defaultSleep = (ms) => new Promise((r) => {
 function defaultOpenUrl(url) {
     // 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` 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')
+    // `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';
@@ -128,7 +133,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, 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 +142,10 @@ 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 (!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
@@ -148,7 +157,12 @@ export async function runHostedApproval(opts) {
     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
@@ -182,9 +196,10 @@ export async function runHostedApproval(opts) {
                 amount: target.transactionAmount,
                 currency,
                 ...(consumerEmail ? { consumerEmail } : {}),
-                ...(budget ? { budget: true } : {}),
-                ...(budget && maxDraws !== undefined ? { maxDraws } : {}),
-                ...(budget && perTransaction !== undefined ? { perTransaction } : {}),
+                budget: true,
+                agentJkt,
+                maxDraws,
+                ...(perTransaction !== undefined ? { perTransaction } : {}),
                 ...(intentSanitized !== undefined ? { intent: intentSanitized } : {}),
             },
         }),
@@ -201,6 +216,7 @@ export async function runHostedApproval(opts) {
     // 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);
     let lastHeartbeat = now();
     // Keep the event loop alive for the whole poll wait. `defaultSleep` unref()'s
@@ -225,7 +241,13 @@ export async function runHostedApproval(opts) {
                 if (doc?.status === 'declined')
                     throw new HostedApprovalDeclinedError();
                 if (doc?.status === 'completed') {
-                    if (doc.assuranceData === undefined || doc.assuranceData === null) {
+                    // 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
@@ -248,26 +270,29 @@ export async function runHostedApproval(opts) {
                         }
                     }
                     // A budget approval must complete AS a budget approval — a relay that
-                    // dropped the flag would mint a single-purchase token that then rejects
-                    // the first sub-ceiling draw. Compare the boolean explicitly (it is not a
-                    // string, so it lives outside the string-map loop above).
-                    if (Boolean(doc.context?.budget) !== Boolean(budget)) {
+                    // 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');
                     }
-                    // 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
-                    // path registers maxDraws, so only enforce it there; compare exactly,
+                    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 (budget && doc.context?.maxDraws !== maxDraws) {
+                    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 (budget && doc.context?.perTransaction !== perTransaction) {
+                    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');
                     }
@@ -277,12 +302,20 @@ 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');
                     }
-                    log('passkey approval received from the hosted page.');
+                    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),
+                        ...assuranceFromCeremony(target, doc.assuranceData ?? null),
+                        ...(assuranceExempt ? { assuranceExempt: true } : {}),
                         ...(typeof doc.mintToken === 'string' && doc.mintToken
                             ? { mintToken: doc.mintToken }
                             : {}),
+                        validUntil: doc.validUntil,
                     };
                 }
                 // status 'pending' — the operator is still signing in / tapping.
@@ -309,3 +342,160 @@ export async function runHostedApproval(opts) {
         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 (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');
+        }
+    }
+    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,6 +1,10 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, } 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,8 +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;

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',
+    },
+};

package/dist/checkout-engine/live-fill-approval.d.ts

@@ -1,21 +1,10 @@
 import type { CheckoutMode, CheckoutOutcome, CheckoutResult } from './executor.js';
-export declare const SUBMIT_ENV_FLAG = "CHECKOUT_AGENT_ALLOW_SUBMIT";
 export declare const MODE_ENV_FLAG = "CHECKOUT_AGENT_MODE";
 /**
  * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
  * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
  */
 export declare function parseCheckoutMode(value: string | undefined, env?: Record<string, string | undefined>): CheckoutMode;
-/**
- * Fail fast (before any file read or browser launch) when submit lacks an
- * enablement. The env arm exists to stop AUTOMATION from reaching a live
- * charge by accident — so it is required only when stdin is not a real TTY
- * (scripts, agents, pipes). An interactive human needs no standing config:
- * their per-run consent is the typed PAY phrase plus the passkey tap, both of
- * which a non-interactive caller cannot fake (the phrase names the exact
- * review id; the passkey is a FIDO ceremony on the verify site).
- */
-export declare function assertSubmitAllowed(mode: CheckoutMode, env?: Record<string, string | undefined>, isInteractive?: boolean): void;
 /** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
 export declare function approvalPhrase(mode: CheckoutMode, reviewId: string): string;
 /** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
@@ -39,5 +28,10 @@ export declare function isRunSuccess(mode: CheckoutMode, outcome: CheckoutOutcom
  * so no charge can exist until it is completed — the double-charge warning
  * would misdirect the operator, and the runner prints the challenge-specific
  * notice instead.
+ *
+ * The executor now NAMES this state in the outcome itself ('unverified'), so
+ * the two agree by construction. This predicate stays the broader guard: it
+ * also catches a post-click throw or any future outcome that leaves the same
+ * question open, and it is what the receipt's reconciliation list reads.
  */
 export declare function submitClickedWithoutConfirmation(result: CheckoutResult): boolean;

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

@@ -1,18 +1,19 @@
 // Deliberate-enablement seam for run-live-fill's submit mode. A real submit
 // moves real money, so it requires:
-//   1. an interactive human at a real TTY — or, for scripted/agent runs,
-//      the explicit CHECKOUT_AGENT_ALLOW_SUBMIT=1 environment arm,
-//   2. the invocation opts in (--mode submit, or the CHECKOUT_AGENT_MODE
+//   1. the invocation opts in (--mode submit, or the CHECKOUT_AGENT_MODE
 //      environment default for operators who always run one mode),
-//   3. the operator types the PAY phrase against the exact review id (and a
+//   2. the operator types the PAY phrase against the exact review id (and a
 //      hosted run additionally requires the passkey tap on the verify site).
-// The env arm is an anti-automation gate, not a human ritual: a TTY human's
-// consent is act 3 — the PAY phrase differs from dry-run's FILL phrase, so a
-// muscle-memory rerun of the dry-run procedure still cannot drift into
-// charging a card — while a non-interactive caller (script, agent, pipe) can
-// fake neither the phrase's review id nor the FIDO ceremony and must also be
-// explicitly armed. Fresh checkouts therefore need ZERO persisted config.
-export const SUBMIT_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_SUBMIT';
+// The PAY phrase differs from dry-run's FILL phrase and names the exact review
+// id, so a muscle-memory rerun of the dry-run procedure cannot drift into
+// charging a card. Fresh checkouts need ZERO persisted config.
+//
+// There was a third requirement — a CHECKOUT_AGENT_ALLOW_SUBMIT=1 environment
+// arm, exempted for interactive TTYs — meant to stop AUTOMATION reaching a live
+// charge. It never ran: nothing in the product ever called `assertSubmitAllowed`.
+// The same flag DID gate `pay_merchant`, where being default-off with no
+// in-product way to set it meant a real install could not complete a purchase at
+// all. Both are gone; the phrase and the mandate caps are the gates.
 export const MODE_ENV_FLAG = 'CHECKOUT_AGENT_MODE';
 /**
  * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
@@ -26,29 +27,9 @@ export function parseCheckoutMode(value, env = process.env) {
         return 'submit';
     throw new Error(`--mode (or ${MODE_ENV_FLAG}) must be dry-run or submit (got ${JSON.stringify(effective)})`);
 }
-/**
- * Fail fast (before any file read or browser launch) when submit lacks an
- * enablement. The env arm exists to stop AUTOMATION from reaching a live
- * charge by accident — so it is required only when stdin is not a real TTY
- * (scripts, agents, pipes). An interactive human needs no standing config:
- * their per-run consent is the typed PAY phrase plus the passkey tap, both of
- * which a non-interactive caller cannot fake (the phrase names the exact
- * review id; the passkey is a FIDO ceremony on the verify site).
- */
-export function assertSubmitAllowed(mode, env = process.env, isInteractive = process.stdin.isTTY === true) {
-    if (mode !== 'submit')
-        return;
-    if (env[SUBMIT_ENV_FLAG] === '1')
-        return;
-    if (isInteractive)
-        return;
-    throw new Error(`--mode submit refused: this is not an interactive terminal, and scripted submits ` +
-        `require ${SUBMIT_ENV_FLAG}=1. The gate is default-off so automation cannot ` +
-        'reach a live charge by accident.');
-}
 /** 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 +43,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
@@ -79,6 +60,11 @@ export function isRunSuccess(mode, outcome) {
  * so no charge can exist until it is completed — the double-charge warning
  * would misdirect the operator, and the runner prints the challenge-specific
  * notice instead.
+ *
+ * The executor now NAMES this state in the outcome itself ('unverified'), so
+ * the two agree by construction. This predicate stays the broader guard: it
+ * also catches a post-click throw or any future outcome that leaves the same
+ * question open, and it is what the receipt's reconciliation list reads.
  */
 export function submitClickedWithoutConfirmation(result) {
     if (result.outcome === 'confirmed' ||