@visa/cli 4.1.0-rc.13 → 4.1.0-rc.130

package/dist/checkout-engine/mandate/mandate-ledger.js

@@ -0,0 +1,373 @@
+// Owner-only persisted ledger for card mandates (budgets). One passkey approval
+// creates one VGS intent with a CEILING decline threshold; this ledger tracks
+// the cumulative budget the agent may draw against that intent without a fresh
+// tap. It deliberately MIRRORS csmoove530's standing-mandate ledger (#5600 /
+// #5724) so the two reconcile later rather than competing:
+//
+//   - owner-only (chmod 600) JSON artifact under ~/.visa-mcp/, atomic write;
+//   - integer minor-unit accounting only — no floating-point money;
+//   - atomic reserve -> commit | release around every draw, so approved plus
+//     in-flight spend can never exceed the authenticated ceiling.
+//
+// VGS's decline_threshold is a per-transaction NETWORK control; this ledger is
+// the SEPARATE cumulative budget control. The file holds identifiers and
+// accounting state plus the scoped mint token (owner-only) — never PAN, DPAN,
+// CVC, or cryptogram values. Cross-process concurrency is NOT solved by a file
+// (same caveat csmoove notes); the in-process mutex below serializes draws
+// within one CLI process, which is the live-spike target.
+//
+// SELF-HEALING: a reservation is persisted the instant it is taken and is only
+// removed by commit() or release(). A crash BETWEEN reserve and commit/release
+// would otherwise strand the reservation forever, permanently shrinking
+// `remaining`. The headroom-deciding paths (reserve() and findCovering()) run a
+// stale-reservation sweep on load: any reservation older than
+// STALE_RESERVATION_MS (a draw cannot legitimately stay in-flight that long) is
+// dropped, returning its headroom, so a stranded reservation can never block a
+// legitimate draw. reserve()'s save() persists the prune; findCovering() heals
+// its in-memory view. The sweep uses the caller's clock (michaelyang1 L1).
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readOwnerOnlyJson, writeOwnerOnlyJson } from '../owner-only-file.js';
+export const CARD_MANDATE_LEDGER_VERSION = 1;
+// A ledger with a long draw history is larger than a single credential; cap
+// generously but still bounded (owner-only-file's default 16 KB is too small).
+const LEDGER_MAX_BYTES = 512 * 1024;
+// A tap-free draw's reserve -> commit/release cycle completes in one network
+// round-trip; a reservation older than this window can only be the debris of a
+// crash between reserve and commit/release, so load() sweeps it (L1 self-heal).
+// Must match the server-authoritative TTL (CARD_MANDATE_RESERVATION_TTL_SECONDS
+// in apps/auth/src/server.ts, default 15 min) to avoid a window where the local
+// ledger over-reports available headroom.
+const STALE_RESERVATION_MS = 15 * 60 * 1000;
+// Mandates expired longer ago than this are pruned on the next create(). Generous
+// (a week) so a recently-expired mandate is still visible in `mandate list`, but
+// bounded so a long-lived heavy user cannot grow the owner-only ledger file into
+// its size cap — which would otherwise brick EVERY ledger op (create/reserve/
+// findCovering/commit/release all load the file first).
+const EXPIRED_PRUNE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+function reservedTotal(record) {
+    return record.reservations.reduce((sum, r) => sum + r.amountMinor, 0);
+}
+/**
+ * Drop reservations older than STALE_RESERVATION_MS across every mandate — the
+ * debris of a crash between reserve and commit/release. Mutates in place and
+ * returns true if anything was swept (so the caller can decide to persist).
+ * A reservation with an unparseable `reservedAt` is treated as stale.
+ */
+function sweepStaleReservations(file, nowMs) {
+    let swept = false;
+    for (const m of file.mandates) {
+        const kept = m.reservations.filter((r) => {
+            const reservedMs = Date.parse(r.reservedAt);
+            const stale = !Number.isFinite(reservedMs) || nowMs - reservedMs > STALE_RESERVATION_MS;
+            if (stale)
+                swept = true;
+            return !stale;
+        });
+        if (kept.length !== m.reservations.length)
+            m.reservations = kept;
+    }
+    return swept;
+}
+/** Available headroom = ceiling - committed - reserved. Integer minor units. */
+export function remainingMinor(record) {
+    return record.ceilingMinor - record.spentMinor - reservedTotal(record);
+}
+function isExpired(record, now) {
+    const end = Date.parse(record.expiresAt);
+    return !Number.isFinite(end) || end <= now.getTime();
+}
+function committedDrawCount(record) {
+    return record.draws.filter((draw) => draw.status === 'committed').length;
+}
+function hasDrawCountHeadroom(record) {
+    return (record.maxDraws === undefined ||
+        committedDrawCount(record) + record.reservations.length < record.maxDraws);
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer (minor units)`);
+    }
+}
+/**
+ * The persisted card-mandate ledger. All mutating operations are serialized on
+ * an in-process promise chain so two concurrent draws cannot both observe the
+ * same remaining balance (the read-modify-write is atomic within the process).
+ */
+export class MandateLedger {
+    path;
+    chain = Promise.resolve();
+    constructor(path = defaultLedgerPath()) {
+        this.path = path;
+    }
+    /** Serialize a read-modify-write so concurrent draws can't race the file. */
+    run(fn) {
+        const next = this.chain.then(fn, fn);
+        // Keep the chain alive even if this op rejects; swallow only the chain copy.
+        this.chain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    // `nowMs` is the caller's clock for the stale-reservation sweep. The sweep
+    // deliberately runs only on the headroom-DECIDING loads — reserve() and
+    // findCovering() — which are the paths that must not be blocked by
+    // crash-stranded reservation debris. commit(), release(), and markUnhonored()
+    // pass NO clock on purpose: sweeping while finalizing a reservation could drop
+    // the very reservation being committed/released. Pure snapshot reads (get) and
+    // create() are likewise clock-independent.
+    async load(nowMs) {
+        try {
+            const doc = await readOwnerOnlyJson(this.path, 'card mandate ledger', LEDGER_MAX_BYTES);
+            if (!doc || !Array.isArray(doc.mandates)) {
+                return { version: CARD_MANDATE_LEDGER_VERSION, mandates: [] };
+            }
+            // Self-heal: prune reservations stranded by a crash before commit/release
+            // so `remaining` reflects reality. In-memory here; a mutating caller then
+            // persists the pruned state via save().
+            if (nowMs !== undefined)
+                sweepStaleReservations(doc, nowMs);
+            return doc;
+        }
+        catch (err) {
+            // A missing ledger is the normal first-run state.
+            if (err.code === 'ENOENT') {
+                return { version: CARD_MANDATE_LEDGER_VERSION, mandates: [] };
+            }
+            throw err;
+        }
+    }
+    async save(file) {
+        await writeOwnerOnlyJson(this.path, file);
+    }
+    /**
+     * Append a freshly-created mandate record. `now` drives the expired-mandate
+     * prune below; it defaults to the wall clock but is injectable so callers (and
+     * tests) can pin it — every other mutating method takes the same clock, and a
+     * real `new Date()` here would otherwise make the prune non-deterministic
+     * against fixtures dated relative to a fixed reference time.
+     */
+    create(record, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            if (file.mandates.some((m) => m.mandateId === record.mandateId)) {
+                throw new Error(`mandate ${record.mandateId} already exists in the ledger`);
+            }
+            // Bound ledger growth: drop mandates expired beyond the grace window. They
+            // are already invisible to `mandate list` and unselectable by findCovering,
+            // so nothing references them. A mandate with an unparseable expiry is kept
+            // (fail-safe — never prune what we cannot date).
+            const pruneBefore = now.getTime() - EXPIRED_PRUNE_GRACE_MS;
+            file.mandates = file.mandates.filter((m) => {
+                const exp = Date.parse(m.expiresAt);
+                return !Number.isFinite(exp) || exp >= pruneBefore;
+            });
+            file.mandates.push(record);
+            await this.save(file);
+            return record;
+        });
+    }
+    /** Read a single mandate (no lock — a snapshot copy). */
+    async get(mandateId) {
+        const file = await this.load();
+        return file.mandates.find((m) => m.mandateId === mandateId) ?? null;
+    }
+    /**
+     * First ACTIVE mandate (not expired) whose merchant + currency match and whose
+     * remaining headroom covers amountMinor. Used by pay_merchant to decide the
+     * tap-free draw path vs a fresh per-purchase tap.
+     */
+    async findCovering(query) {
+        const now = query.now ?? new Date();
+        const file = await this.load(now.getTime());
+        // Multiple mandates can now cover one merchant: a merchant-scoped mandate for
+        // this host AND any crossMerchant (budget) mandate both qualify (#6003). A
+        // mandate the network refused is skipped via `!m.unhonoredAt` so it can never
+        // be re-selected. A register-failed mandate is skipped the same way
+        // (`!m.registerFailedAt`): it has no server row, so a delegated draw would 404
+        // `no_mandate` — better to fall through to a fresh per-purchase tap.
+        // Selection order among covering candidates:
+        //   1. Prefer a merchant-SCOPED mandate over a crossMerchant budget one —
+        //      spend the dedicated grant for this merchant first and keep the broader
+        //      broader retail budget for merchants that have no scoped mandate. Draining
+        //      the budget for a purchase a scoped mandate already covers both wastes
+        //      the general headroom and can later force a fresh tap at another merchant.
+        //   2. Then the MOST headroom, then the latest expiry — never let a near-empty
+        //      or near-expiry mandate get selected over a fuller, longer-lived sibling
+        //      and then fail a draw the sibling would have covered.
+        const candidates = file.mandates.filter((m) => 
+        // A crossMerchant retail budget is locally cross-host; a merchant-scoped
+        // one only matches its own host. Network Retail/5999 eligibility is
+        // enforced downstream and is not inferred from a website hostname.
+        (m.crossMerchant || m.merchantHost === query.merchantHost) &&
+            m.agentJkt === query.agentJkt &&
+            m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
+            !m.unhonoredAt &&
+            !m.registerFailedAt &&
+            !isExpired(m, now) &&
+            hasDrawCountHeadroom(m) &&
+            remainingMinor(m) >= query.amountMinor);
+        candidates.sort((a, b) => 
+        // A scoped mandate (crossMerchant falsy → 0) sorts before a budget one (1).
+        (a.crossMerchant ? 1 : 0) - (b.crossMerchant ? 1 : 0) ||
+            remainingMinor(b) - remainingMinor(a) ||
+            Date.parse(b.expiresAt) - Date.parse(a.expiresAt));
+        return candidates[0] ?? null;
+    }
+    /**
+     * Mark a mandate as unhonored — the network declined a ceiling-scoped draw
+     * against it, so it must never be selected again. Atomic, owner-only write on
+     * the same serialized chain as every other mutation. Idempotent: a second
+     * call keeps the first timestamp. Throws only if the mandate is unknown.
+     */
+    markUnhonored(mandateId, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.unhonoredAt) {
+                record.unhonoredAt = now.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
+    /**
+     * Mark a mandate as register-failed — the delegated-draw register handshake
+     * did not create the server row at mandate-start, so it must never be selected
+     * for a (delegated) draw. Atomic, owner-only write on the same serialized chain
+     * as every other mutation. Idempotent: a second call keeps the first timestamp.
+     * Throws only if the mandate is unknown.
+     */
+    markRegisterFailed(mandateId, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.registerFailedAt) {
+                record.registerFailedAt = now.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
+    /**
+     * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId, approvedCeilingMinor) {
+        return this.run(async () => {
+            assertPositiveInteger(approvedCeilingMinor, 'approved mandate ceiling');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (approvedCeilingMinor >= record.ceilingMinor)
+                return record;
+            record.ceilingMinor = approvedCeilingMinor;
+            await this.save(file);
+            return record;
+        });
+    }
+    /**
+     * Atomically reserve headroom for a draw. Fail-closed: refuses when the
+     * mandate is unknown, expired, or the amount exceeds remaining headroom. The
+     * reservation counts against availability immediately, closing the window in
+     * which two concurrent draws both see the same remaining balance.
+     */
+    reserve(mandateId, amountMinor, now = new Date()) {
+        return this.run(async () => {
+            assertPositiveInteger(amountMinor, 'draw amount');
+            // Sweep with the draw's clock so a crash-stranded reservation cannot block
+            // a legitimate draw; the save() below persists the pruned state.
+            const file = await this.load(now.getTime());
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (isExpired(record, now)) {
+                throw new Error(`mandate ${mandateId} expired at ${record.expiresAt}`);
+            }
+            if (amountMinor > remainingMinor(record)) {
+                throw new Error(`draw ${amountMinor} exceeds remaining budget ${remainingMinor(record)} (minor units)`);
+            }
+            if (!hasDrawCountHeadroom(record)) {
+                throw new Error(`mandate ${mandateId} reached its approved purchase-count limit`);
+            }
+            const reservationId = `rsv_${randomBytes(9).toString('base64url')}`;
+            record.reservations.push({ reservationId, amountMinor, reservedAt: now.toISOString() });
+            await this.save(file);
+            return reservationId;
+        });
+    }
+    /** Commit a reservation to permanent spend and record the payable draw. */
+    commit(mandateId, reservationId, meta, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            const idx = record.reservations.findIndex((r) => r.reservationId === reservationId);
+            if (idx === -1) {
+                throw new Error(`reservation ${reservationId} is not open (already committed or released)`);
+            }
+            const [reservation] = record.reservations.splice(idx, 1);
+            record.spentMinor += reservation.amountMinor;
+            record.draws.push({
+                drawId: `drw_${randomBytes(9).toString('base64url')}`,
+                reservationId,
+                amountMinor: reservation.amountMinor,
+                intentId: meta.intentId,
+                status: 'committed',
+                at: now.toISOString(),
+            });
+            await this.save(file);
+            return record;
+        });
+    }
+    /** Release a reservation back to availability (draw failed / not payable). */
+    release(mandateId, reservationId, now = new Date()) {
+        return this.run(async () => {
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            const idx = record.reservations.findIndex((r) => r.reservationId === reservationId);
+            if (idx === -1) {
+                // Idempotent by refusal: a committed/released reservation cannot be
+                // released again, but a redundant release must not corrupt state.
+                return record;
+            }
+            const [reservation] = record.reservations.splice(idx, 1);
+            record.draws.push({
+                drawId: `drw_${randomBytes(9).toString('base64url')}`,
+                reservationId,
+                amountMinor: reservation.amountMinor,
+                intentId: record.mandateId,
+                status: 'released',
+                at: now.toISOString(),
+            });
+            await this.save(file);
+            return record;
+        });
+    }
+}
+export function defaultLedgerPath() {
+    return (process.env.VISA_CARD_MANDATE_LEDGER_FILE ?? join(homedir(), '.visa-mcp', 'card-mandates.json'));
+}

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

@@ -1,5 +1,5 @@
 import type { Page } from 'playwright-core';
-export type OutcomeStatus = 'confirmed' | 'declined' | 'action-required' | 'processing' | 'unknown';
+export type OutcomeStatus = 'confirmed' | 'declined' | 'action-required' | 'verification-required' | 'processing' | 'unknown';
 export type OutcomeClassification = {
     status: OutcomeStatus;
     /** The named pattern that decided the status, e.g. "body:card-declined". */
@@ -8,7 +8,7 @@ export type OutcomeClassification = {
 /** Pure classification of one page state (case-insensitive on all inputs). */
 export declare function classifyOutcomePage(url: string, bodyText: string, frameUrls?: readonly string[]): OutcomeClassification;
 export type ObservedOutcome = {
-    status: 'confirmed' | 'declined' | 'action-required' | 'unknown';
+    status: 'confirmed' | 'declined' | 'action-required' | 'verification-required' | 'unknown';
     signal: string | null;
     /** Last non-final classification when the deadline expired ('processing' | 'unknown'). */
     lastSeen: OutcomeStatus;

package/dist/checkout-engine/outcome.js

@@ -65,11 +65,34 @@ const ACTION_REQUIRED_URL = [
 // credential) but its copy also says "Enter the code sent to …", which would
 // otherwise match body:code-sent and misreport it as 3DS. Its own copy is
 // distinctive: "to use your saved information" / "Logging in as <email>".
-const ACTION_REQUIRED_BODY = [
+// The Stripe Link login modal. Checked BEFORE every other body pattern
+// (including the email-OTP split below): completing it pays with an old saved
+// card, not the minted credential, so it must stay action-required (human) and
+// must never be mistaken for an agent-resolvable email code. See #5879.
+const LINK_WALLET_BODY = [
     {
         name: 'body:link-wallet',
         re: /use your saved information|logging in as .{1,60}?\. your device will be remembered/,
     },
+];
+// Agent-RESOLVABLE email OTP: a code the MERCHANT emailed to the agent's own
+// inbox, which wallet_mail_await_otp can retrieve. Kept deliberately narrow —
+// it requires an EMAIL indicator (email / inbox / @) so an SMS "code sent to
+// your phone" or an issuer 3DS challenge (both un-retrievable by the agent)
+// stay action-required and fall to a human. This is the ONLY status the OTP
+// subroutine will try to auto-complete.
+const VERIFICATION_REQUIRED_BODY = [
+    // "a code was sent / e-mailed to your email / inbox" (code-first order).
+    {
+        name: 'body:email-code-sent',
+        re: /(?:code|passcode).{0,40}(?:sent|e-?mailed).{0,40}(?:e-?mail|inbox|@)/,
+    },
+    // "we e-mailed you a … code" (email-verb-first order).
+    { name: 'body:email-code-sent', re: /e-?mailed\b.{0,40}(?:code|passcode)/ },
+    // "check your email / inbox for a … code".
+    { name: 'body:check-email-code', re: /check your (?:e-?mail|inbox).{0,40}(?:code|verif)/ },
+];
+const ACTION_REQUIRED_BODY = [
     { name: 'body:3d-secure', re: /3-?d secure/ },
     { name: 'body:verify-identity', re: /verify your identity/ },
     { name: 'body:one-time-code', re: /enter (?:the )?(?:one[- ]?time|verification|security) code/ },
@@ -122,6 +145,15 @@ export function classifyOutcomePage(url, bodyText, frameUrls = []) {
         if (frame)
             return { status: 'action-required', signal: frame };
     }
+    // Stripe Link modal first — it must never fall through to the email-OTP split.
+    const linkWallet = match(LINK_WALLET_BODY, b);
+    if (linkWallet)
+        return { status: 'action-required', signal: linkWallet };
+    // Agent-resolvable email OTP: its own verdict, so the executor can retrieve
+    // the code rather than stopping for a human.
+    const emailVerify = match(VERIFICATION_REQUIRED_BODY, b);
+    if (emailVerify)
+        return { status: 'verification-required', signal: emailVerify };
     const challengeUrl = match(ACTION_REQUIRED_URL, u);
     if (challengeUrl)
         return { status: 'action-required', signal: challengeUrl };
@@ -167,6 +199,9 @@ export async function observeOutcome(page, opts = {}) {
         // continues until the post-challenge confirmed/declined signal appears.
         if (seen.status === 'confirmed' ||
             seen.status === 'declined' ||
+            // Email OTP won't self-resolve either — return it so the executor's
+            // single-use OTP subroutine can retrieve the code (or a human is asked).
+            seen.status === 'verification-required' ||
             (seen.status === 'action-required' && !opts.holdThroughChallenge)) {
             return {
                 status: seen.status,

package/dist/checkout-engine/owner-only-file.d.ts

@@ -8,3 +8,12 @@
 export declare function assertOwnerOnlyFile(path: string, label: string, maxBytes?: number): Promise<void>;
 /** The same guard, then parse — contents are read only after the guard passes. */
 export declare function readOwnerOnlyJson<T>(path: string, label: string, maxBytes?: number): Promise<T>;
+/**
+ * Atomically write an owner-only (chmod 600) JSON artifact: serialize to a
+ * sibling temp file created 0600, then rename over the target so a reader never
+ * observes a half-written ledger (and a crash mid-write leaves the prior file
+ * intact). The parent directory is created if absent (matching ~/.visa-mcp).
+ * Used by the card-mandate ledger — the same owner-only posture as
+ * agent-credential.json / contact.json.
+ */
+export declare function writeOwnerOnlyJson(path: string, value: unknown): Promise<void>;

package/dist/checkout-engine/owner-only-file.js

@@ -1,4 +1,6 @@
-import { lstat, readFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
 /**
  * lstat-only guard for operator-supplied secret-bearing files: must be a
  * regular file (never a symlink), owner-only (chmod 600), and size-bounded.
@@ -20,3 +22,20 @@ export async function readOwnerOnlyJson(path, label, maxBytes = 16 * 1024) {
     await assertOwnerOnlyFile(path, label, maxBytes);
     return JSON.parse(await readFile(path, 'utf8'));
 }
+/**
+ * Atomically write an owner-only (chmod 600) JSON artifact: serialize to a
+ * sibling temp file created 0600, then rename over the target so a reader never
+ * observes a half-written ledger (and a crash mid-write leaves the prior file
+ * intact). The parent directory is created if absent (matching ~/.visa-mcp).
+ * Used by the card-mandate ledger — the same owner-only posture as
+ * agent-credential.json / contact.json.
+ */
+export async function writeOwnerOnlyJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${randomBytes(6).toString('hex')}`;
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    // writeFile's mode only applies on create; chmod defensively in case the temp
+    // name somehow pre-existed with looser bits.
+    await chmod(tmp, 0o600);
+    await rename(tmp, path);
+}

package/dist/checkout-engine/trace-handles.d.ts

@@ -0,0 +1,8 @@
+export declare function safeTraceHandle(value: unknown): string | undefined;
+export declare function traceHandleFields(value: {
+    vgsTraceId?: unknown;
+    networkCorrelationId?: unknown;
+}): {
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
+};

package/dist/checkout-engine/trace-handles.js

@@ -0,0 +1,12 @@
+const SAFE_TRACE_HANDLE_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+export function safeTraceHandle(value) {
+    return typeof value === 'string' && SAFE_TRACE_HANDLE_RE.test(value) ? value : undefined;
+}
+export function traceHandleFields(value) {
+    const vgsTraceId = safeTraceHandle(value.vgsTraceId);
+    const networkCorrelationId = safeTraceHandle(value.networkCorrelationId);
+    return {
+        ...(vgsTraceId ? { vgsTraceId } : {}),
+        ...(networkCorrelationId ? { networkCorrelationId } : {}),
+    };
+}

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

@@ -1,5 +1,4 @@
-export type Contact = {
-    email?: string;
+export type PostalAddress = {
     firstName?: string;
     lastName?: string;
     fullName?: string;
@@ -10,6 +9,11 @@ export type Contact = {
     postalCode?: string;
     country?: string;
 };
+export type Contact = PostalAddress & {
+    email?: string;
+    phone?: string;
+    billingAddress?: PostalAddress;
+};
 export type FilledField = {
     role: string;
     locator: string;
@@ -23,4 +27,18 @@ export type FilledField = {
 export type FillResult = {
     ok: boolean;
     filled: FilledField[];
+    detail?: string;
+};
+export type OtpRequest = {
+    /** ISO watermark captured BEFORE the click that triggers the OTP email. */
+    after: string;
+    /** The merchant hostname; the sender's registrable domain must match it. */
+    merchantHost: string;
+};
+export type OtpResolution = {
+    /** The single-use code. The executor fills it exactly once; never retried. */
+    code: string;
+    /** The sender's registrable domain — a trust signal, safe to log (no PII). */
+    fromDomain: string;
 };
+export type OtpResolver = (req: OtpRequest) => Promise<OtpResolution | null>;

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

@@ -0,0 +1,82 @@
+import type { VgsCheckoutTarget, VgsPaymentCredential } from '../vgs-live-instrument.js';
+export type ServerMintDeps = {
+    /** Injectable for tests — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export declare function merchantOrigin(url: string): string;
+/**
+ * Optional mandate override for serverCreateIntent. Absent → the historical
+ * 1:1 fresh-tap shape is preserved byte-for-byte (cap = ceil(amount)+10 min 25,
+ * quantity 1, 30-day window). Present → the card-mandate (budget) layer sets a
+ * CEILING decline threshold and a multi-draw quantity so one passkey approves a
+ * spend ceiling and later draws pull cryptograms under it without a fresh tap.
+ * Whether the network honors a ceiling-scoped assurance across multiple
+ * sub-amount draws is UNPROVEN — see packages/checkout-engine/src/mandate/.
+ */
+export type ServerIntentMandateOverride = {
+    /** Wire decline-threshold amount (major-unit decimal string), e.g. "500.00". */
+    declineThresholdAmount?: string;
+    /** Number of draws the intent may fulfil (VGS mandate `quantity`). */
+    quantity?: number;
+    /** ISO 8601 mandate validity end. */
+    effectiveUntil?: string;
+    /** Human-readable consumer prompt describing the ceiling grant. */
+    consumerPrompt?: string;
+};
+/**
+ * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
+ * credential and calls the gateway; we send the same mandate shape the local
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
+ */
+export declare function serverCreateIntent(base: string, mintToken: string, input: {
+    tokenId: string;
+    assuranceData: unknown;
+    transaction: VgsCheckoutTarget;
+    mandate?: ServerIntentMandateOverride;
+}, deps?: ServerMintDeps): Promise<{
+    intentId: string;
+    status: string | null;
+}>;
+/**
+ * Mint the FULL payment credential via POST {base}/api/vgs/payment-cryptogram.
+ * The server's route does a SINGLE gateway call and 502s on a not-COMPLETED
+ * (e.g. PENDING) cryptogram, but live intent approval is asynchronous and the
+ * first cryptogram answer can be PENDING (#5709). So we retry the route on any
+ * non-2xx up to PENDING_ATTEMPTS, matching fetch-credential.mjs's cadence
+ * exactly — a genuinely hard failure just surfaces after the same bounded wait.
+ * Re-POSTing for the same intentId is idempotent (mirrors the old client loop).
+ */
+export declare function serverFetchCryptogram(base: string, mintToken: string, input: {
+    tokenId: string;
+    intentId: string;
+    transaction: VgsCheckoutTarget;
+}, deps?: ServerMintDeps): Promise<VgsPaymentCredential>;
+/** Report the observed merchant outcome via POST {base}/api/vgs/confirmation. */
+export declare function serverPostConfirmation(base: string, mintToken: string, input: {
+    tokenId: string;
+    intentId: string;
+    transactionStatus: string;
+    transactionType: string;
+    transactionTimestamp: string;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+}, deps?: ServerMintDeps): Promise<{
+    ok: true;
+}>;