@visa/cli 4.1.0-rc.90 → 4.1.0-rc.91

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

@@ -1,6 +1,6 @@
 import { type Browser } from 'playwright-core';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type PreparedCheckoutSessionStore } from './executor.js';
-import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
+import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
 import { serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
 import { type CardMandateFacts } from './mandate/card-mandate.js';
@@ -84,6 +84,16 @@ export type CliStartMandateInput = {
      */
     intent?: string;
 };
+export type CliClaimMandateInput = {
+    /** Optional local card-capability selector (legacy name or exact request-key JKT). */
+    agentRef?: string;
+    /** Single-use pickup code the owner handed over from the panel. */
+    pickupCode: string;
+    credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    approvalBaseUrl: string;
+};
 export type CliMandateFacts = CardMandateFacts & {
     merchantHost: string;
     /**
@@ -164,6 +174,8 @@ export type CliEngineDeps = {
     prepareCheckout?: typeof realPrepareCheckout;
     submitApprovedCheckout?: typeof realSubmitApprovedCheckout;
     runHostedApproval?: typeof realRunHostedApproval;
+    /** Injectable pickup-code redeem for claimCardMandate — tests pass a fake. */
+    claimMandatePickup?: typeof realClaimMandatePickup;
     /**
      * Relay the hosted-approval URL to the caller as DATA the moment it is known,
      * before the (up-to-timeout) poll wait. A headless agent surface wires this to
@@ -208,6 +220,7 @@ export type CliEngineDeps = {
 };
 export declare function createCliCheckoutEngine(deps?: CliEngineDeps): {
     startCardMandate(input: CliStartMandateInput): Promise<CliMandateFacts>;
+    claimCardMandate(input: CliClaimMandateInput): Promise<CliMandateFacts>;
     review(input: CliReviewInput): Promise<CliReviewFacts>;
     pay(input: CliPayInput): Promise<CliReceiptFacts>;
 };

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

@@ -15,7 +15,7 @@ import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
+import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
 import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, } from './vgs-live-instrument.js';
 import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
 import { createCardMandate, DEFAULT_MANDATE_MAX_DRAWS, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
@@ -114,6 +114,7 @@ export function createCliCheckoutEngine(deps = {}) {
     const prepareCheckout = deps.prepareCheckout ?? realPrepareCheckout;
     const submitApprovedCheckout = deps.submitApprovedCheckout ?? realSubmitApprovedCheckout;
     const runHostedApproval = deps.runHostedApproval ?? realRunHostedApproval;
+    const claimMandatePickup = deps.claimMandatePickup ?? realClaimMandatePickup;
     const reportVicOutcome = deps.reportVicOutcome ?? realReportVicOutcome;
     const writeReceipt = deps.writeReceipt ?? realWriteReceipt;
     const ledger = deps.ledger ?? defaultLedger;
@@ -139,6 +140,55 @@ export function createCliCheckoutEngine(deps = {}) {
             transactionCurrencyCode: input.currency,
         };
     }
+    // Seed the one server-authoritative cumulative store keyed by the VGS intent
+    // ID (#5942). On failure the local record is marked register-failed so
+    // findCovering() SKIPS it — the mandate exists but is never drawn tap-free —
+    // and the caller reports the failure honestly. Shared by mandate-start and
+    // pickup-claim; both refuse before their ceremony/claim when no capability
+    // can register, so registerCap is always present here.
+    async function registerMandateOrDisable(args) {
+        if (!cardMandateRegister)
+            return { registerFailed: true, registerFailureReason: 'no_seam' };
+        const reg = await cardMandateRegister
+            .register({
+            authBaseUrl: args.registerCap.authBaseUrl,
+            agentKey: args.registerCap.agentKey,
+            mandateId: args.mandateId,
+            mintToken: args.mintToken,
+            ceiling: args.ceiling,
+            currency: args.currency,
+        })
+            .catch((err) => ({
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        }));
+        if (reg.ok)
+            return { registerFailed: false };
+        // Register failed: the server `card_mandate_spend` row was never created, so
+        // a delegated draw against this mandate would 404 `no_mandate`. Mark it
+        // register-failed so findCovering() SKIPS it and the owner's next checkout
+        // falls through to a fresh per-purchase tap, rather than silently selecting
+        // a mandate that can't be drawn. Marking is best-effort too — a failure here
+        // must not abort the flow.
+        const marked = await ledger
+            .markRegisterFailed(args.mandateId, now())
+            .then(() => true)
+            .catch(() => false);
+        process.stderr.write(marked
+            ? `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) — this mandate ` +
+                `will NOT be used for tap-free draws; your next checkout will use a fresh ` +
+                `per-purchase passkey tap. Re-run 'mandate start' to try again.\n`
+            : // Escalate: the mark write ALSO failed, so the mandate is persisted but
+                // NOT disabled — findCovering could still select an undrawable mandate.
+                // Tell the owner loudly not to rely on it and how to recover.
+                `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) AND the mandate ` +
+                    `could NOT be disabled locally — do not rely on it. Run 'mandate list' and re-run ` +
+                    `'mandate start'. mandateId=${args.mandateId}\n`);
+        return {
+            registerFailed: true,
+            ...(reg.reason !== undefined ? { registerFailureReason: reg.reason } : {}),
+        };
+    }
     return {
         // BUDGET step: one passkey approves a CEILING; a VGS intent is minted with
         // that ceiling as its decline threshold and the owner-only ledger records
@@ -234,52 +284,80 @@ export function createCliCheckoutEngine(deps = {}) {
             // Seed the one server-authoritative cumulative store keyed by the VGS
             // intent ID. A later draw requires its PoP verdict; the budget token never
             // falls back as payable authority.
-            let registerFailed = false;
-            let registerFailureReason;
-            if (registerCap && cardMandateRegister) {
-                const reg = await cardMandateRegister
-                    .register({
-                    authBaseUrl: registerCap.authBaseUrl,
-                    agentKey: registerCap.agentKey,
-                    mandateId: facts.mandateId,
-                    mintToken,
-                    ceiling: input.ceiling,
-                    currency: input.currency,
-                })
-                    .catch((err) => ({
-                    ok: false,
-                    reason: err instanceof Error ? err.message : String(err),
-                }));
-                if (!reg.ok) {
-                    registerFailed = true;
-                    registerFailureReason = reg.reason;
-                    // Register failed: the server `card_mandate_spend` row was never
-                    // created, so a delegated draw against this mandate would 404
-                    // `no_mandate`. Mark it register-failed so findCovering() SKIPS it and
-                    // the owner's next checkout falls through to a fresh per-purchase tap,
-                    // rather than silently selecting a mandate that can't be drawn. Marking
-                    // is best-effort too — a failure here must not abort mandate-start.
-                    const marked = await ledger
-                        .markRegisterFailed(facts.mandateId, now())
-                        .then(() => true)
-                        .catch(() => false);
-                    process.stderr.write(marked
-                        ? `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) — this mandate ` +
-                            `will NOT be used for tap-free draws; your next checkout will use a fresh ` +
-                            `per-purchase passkey tap. Re-run 'mandate start' to try again.\n`
-                        : // Escalate: the mark write ALSO failed, so the mandate is persisted but
-                            // NOT disabled — findCovering could still select an undrawable mandate.
-                            // Tell the owner loudly not to rely on it and how to recover.
-                            `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) AND the mandate ` +
-                                `could NOT be disabled locally — do not rely on it. Run 'mandate list' and re-run ` +
-                                `'mandate start'. mandateId=${facts.mandateId}\n`);
-                }
-            }
+            const registered = await registerMandateOrDisable({
+                registerCap,
+                mandateId: facts.mandateId,
+                mintToken,
+                ceiling: input.ceiling,
+                currency: input.currency,
+            });
             return {
                 ...facts,
                 merchantHost: new URL(merchant.url).hostname,
-                registerFailed,
-                ...(registerFailureReason !== undefined ? { registerFailureReason } : {}),
+                registerFailed: registered.registerFailed,
+                ...(registered.registerFailureReason !== undefined
+                    ? { registerFailureReason: registered.registerFailureReason }
+                    : {}),
+            };
+        },
+        // PICKUP leg: the owner already approved the ceiling in the account panel
+        // and handed this runtime a single-use pickup code. Claim it, verify it was
+        // minted for exactly this runtime's request key + card token, then run the
+        // same intent → register → ledger sequence as startCardMandate. No approval
+        // page, no passkey, no contact profile — the human side already happened.
+        async claimCardMandate(input) {
+            const registerCap = cardMandateRegister?.loadCapability(input.agentRef) ?? null;
+            if (!cardMandateRegister || !registerCap) {
+                throw new Error('claimCardMandate requires separately provisioned card authority in this runtime; ' +
+                    'identity pairing alone does not grant a card mandate');
+            }
+            const credential = await resolveCardInstrument(input);
+            const claim = await claimMandatePickup({
+                baseUrl: input.approvalBaseUrl,
+                pickupCode: input.pickupCode,
+                agentJkt: registerCap.agentJkt,
+                tokenId: credential.tokenId,
+            });
+            const ceilingMinor = decimalToMinor(claim.ceiling);
+            if (ceilingMinor === null || ceilingMinor <= 0) {
+                throw new Error(`the handoff carried an invalid ceiling ${JSON.stringify(claim.ceiling)}`);
+            }
+            // Same single-product bound as mandate-start (the panel initiate route
+            // enforces it too; a divergent store entry must not widen it here).
+            if (claim.currency.toUpperCase() !== 'USD') {
+                throw new Error('card spend budgets currently support USD only');
+            }
+            const expiresAt = new Date(claim.validUntil * 1000).toISOString();
+            const facts = await createCardMandate({
+                agentJkt: registerCap.agentJkt,
+                tokenId: credential.tokenId,
+                assuranceData: claim.assuranceData,
+                ceilingMinor,
+                merchant: claim.merchant,
+                currencyCode: claim.currency,
+                expiresAt,
+                maxDraws: claim.maxDraws,
+                crossMerchant: true,
+            }, {
+                createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, claim.mintToken, i),
+                ledger,
+                approvalBaseUrl: input.approvalBaseUrl,
+                now,
+            });
+            const registered = await registerMandateOrDisable({
+                registerCap,
+                mandateId: facts.mandateId,
+                mintToken: claim.mintToken,
+                ceiling: claim.ceiling,
+                currency: claim.currency,
+            });
+            return {
+                ...facts,
+                merchantHost: new URL(claim.merchant.url).hostname,
+                registerFailed: registered.registerFailed,
+                ...(registered.registerFailureReason !== undefined
+                    ? { registerFailureReason: registered.registerFailureReason }
+                    : {}),
             };
         },
         async review(input) {

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

@@ -140,3 +140,48 @@ export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<
     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 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

@@ -346,3 +346,133 @@ 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, 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');
+    }
+    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,
+        },
+    };
+}