@visa/cli 4.1.0-rc.7 → 4.1.0-rc.71

package/dist/checkout-engine/mandate/mandate-ledger.d.ts

@@ -0,0 +1,142 @@
+export declare const CARD_MANDATE_LEDGER_VERSION: 1;
+export type CardMandateReservation = {
+    reservationId: string;
+    amountMinor: number;
+    reservedAt: string;
+};
+export type CardMandateDraw = {
+    drawId: string;
+    reservationId: string;
+    amountMinor: number;
+    intentId: string;
+    status: 'committed' | 'released';
+    at: string;
+};
+export type CardMandateRecord = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    /** == the VGS intentId the ceiling approval created. */
+    mandateId: string;
+    /** Exact runtime request key this budget was issued to. Absent on legacy rows. */
+    agentJkt?: string;
+    tokenId: string;
+    ceilingMinor: number;
+    /** Permanently committed (drawn) spend, integer minor units. */
+    spentMinor: number;
+    /** In-flight reservations (reserved but not yet committed/released). */
+    reservations: CardMandateReservation[];
+    currencyCode: string;
+    merchantName: string;
+    merchantUrl: string;
+    merchantHost: string;
+    merchantCountryCode: string;
+    /** verify-web origin the ceiling intent was minted against. */
+    approvalBaseUrl: string;
+    /**
+     * Scoped token released by the ceiling approval. It bootstraps the one intent
+     * + register ceremony only. Each cryptogram AND its outcome confirmation use
+     * the exact per-draw verdict instead. Owner-only (0600).
+     */
+    mintToken?: string;
+    expiresAt: string;
+    /** Network purchase-count cap disclosed at approval. Absent on legacy rows. */
+    maxDraws?: number;
+    createdAt: string;
+    draws: CardMandateDraw[];
+    /**
+     * Set when the network DECLINED a tap-free draw against this mandate (a
+     * ceiling-scoped assurance the acquirer would not honor for a sub-amount
+     * draw). Distinct from a reservation `status`: it disables the whole mandate.
+     * Once set, findCovering() SKIPS this mandate so the caller's next
+     * pay_merchant falls through to a fresh per-purchase tap instead of
+     * re-selecting the same failing mandate forever. ISO 8601.
+     */
+    unhonoredAt?: string;
+    /**
+     * Set when the delegated-draw register handshake FAILED at mandate-start (the
+     * server-side `card_mandate_spend` row was never created), so a later
+     * delegated (verdict-signed) draw would 404 `no_mandate`. Like `unhonoredAt`,
+     * findCovering() SKIPS a register-failed mandate so the next checkout falls
+     * through to a fresh per-purchase tap instead of surfacing a confusing
+     * `no_mandate`. Mandate-start requires delegated card authority, so every
+     * created record attempted registration. ISO 8601.
+     */
+    registerFailedAt?: string;
+    /**
+     * A cross-host retail budget, not scoped to one `merchantHost`. The local
+     * selector may attempt it at any host, while the provider/network still
+     * applies the approved Retail/5999 category plus amount/count/time controls.
+     * `crossMerchant` is retained as the version-1 persisted field name.
+     */
+    crossMerchant?: boolean;
+};
+export type CardMandateLedgerFile = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    mandates: CardMandateRecord[];
+};
+export type CoverQuery = {
+    merchantHost: string;
+    currencyCode: string;
+    amountMinor: number;
+    now?: Date;
+};
+/** Available headroom = ceiling - committed - reserved. Integer minor units. */
+export declare function remainingMinor(record: CardMandateRecord): number;
+/**
+ * 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 declare class MandateLedger {
+    private readonly path;
+    private chain;
+    constructor(path?: string);
+    /** Serialize a read-modify-write so concurrent draws can't race the file. */
+    private run;
+    private load;
+    private save;
+    /**
+     * 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: CardMandateRecord, now?: Date): Promise<CardMandateRecord>;
+    /** Read a single mandate (no lock — a snapshot copy). */
+    get(mandateId: string): Promise<CardMandateRecord | 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.
+     */
+    findCovering(query: CoverQuery): Promise<CardMandateRecord | 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: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * 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: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * 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: string, amountMinor: number, now?: Date): Promise<string>;
+    /** Commit a reservation to permanent spend and record the payable draw. */
+    commit(mandateId: string, reservationId: string, meta: {
+        intentId: string;
+    }, now?: Date): Promise<CardMandateRecord>;
+    /** Release a reservation back to availability (draw failed / not payable). */
+    release(mandateId: string, reservationId: string, now?: Date): Promise<CardMandateRecord>;
+}
+export declare function defaultLedgerPath(): string;

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

@@ -0,0 +1,338 @@
+// 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.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;
+        });
+    }
+    /**
+     * 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/mandate.d.ts

@@ -0,0 +1,25 @@
+export type Mandate = {
+    maxAmountMinor: number;
+    currency: string;
+    merchantHost?: string;
+    expiresAt: string;
+};
+export type MandateContext = {
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+    now?: Date;
+};
+export type MandatePreFillContext = {
+    merchantHost: string;
+    currency?: string | null;
+    now?: Date;
+};
+export type MandateVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkMandatePreFill(mandate: Mandate | null | undefined, ctx: MandatePreFillContext): MandateVerdict;
+export declare function checkMandate(mandate: Mandate | null | undefined, ctx: MandateContext): MandateVerdict;

package/dist/checkout-engine/mandate.js

@@ -0,0 +1,100 @@
+// Mandate gate. The mandate is the user's pre-authorization for a purchase:
+// how much, in what currency, at which merchant, until when. The gate is
+// fail-closed: anything missing, expired, over cap, or mismatched refuses.
+//
+// The gate runs in two phases:
+//   pre-fill  (checkMandatePreFill) — every fact knowable BEFORE a credential
+//             is minted: structure, expiry, merchant host, and the caller's
+//             asserted currency if any. No credential leaves the instrument
+//             and no field is filled without this passing. This is the
+//             boundary that matters once instruments mint live credentials:
+//             merchant JS sees field values on input, so filling first and
+//             gating at submit would already have exposed the credential.
+//   pre-submit (checkMandate) — the full check including the transaction
+//             amount and resolved currency, which are only known after the
+//             page total is read. No submit ever happens without this passing.
+//
+// All amounts are integer minor units (e.g. cents for USD). There is no
+// floating-point money here on purpose; the executor reads a minor-unit total
+// and compares integers.
+function isInteger(n) {
+    return typeof n === 'number' && Number.isInteger(n);
+}
+// Pre-fill gate: everything knowable before a credential is minted.
+export function checkMandatePreFill(mandate, ctx) {
+    if (!mandate) {
+        return { ok: false, reason: 'no mandate provided' };
+    }
+    // Structural validation: a malformed mandate must never authorize a spend.
+    if (!isInteger(mandate.maxAmountMinor) || mandate.maxAmountMinor <= 0) {
+        return { ok: false, reason: 'mandate maxAmountMinor must be a positive integer (minor units)' };
+    }
+    if (!mandate.currency) {
+        return { ok: false, reason: 'mandate is missing a currency' };
+    }
+    if (!mandate.expiresAt) {
+        return { ok: false, reason: 'mandate is missing an expiry' };
+    }
+    const expiry = new Date(mandate.expiresAt);
+    if (Number.isNaN(expiry.getTime())) {
+        return { ok: false, reason: `mandate expiry is not a valid date: ${mandate.expiresAt}` };
+    }
+    const now = ctx.now ?? new Date();
+    if (expiry.getTime() <= now.getTime()) {
+        return { ok: false, reason: `mandate expired at ${mandate.expiresAt}` };
+    }
+    if (ctx.currency && mandate.currency.toUpperCase() !== ctx.currency.toUpperCase()) {
+        return {
+            ok: false,
+            reason: `currency mismatch: mandate ${mandate.currency} vs transaction ${ctx.currency}`,
+        };
+    }
+    if (mandate.merchantHost &&
+        normalizeHost(mandate.merchantHost) !== normalizeHost(ctx.merchantHost)) {
+        return {
+            ok: false,
+            reason: `merchant host mismatch: mandate ${mandate.merchantHost} vs checkout ${ctx.merchantHost}`,
+        };
+    }
+    return { ok: true };
+}
+// Full (pre-submit) gate: the pre-fill checks plus amount and the resolved
+// transaction currency.
+export function checkMandate(mandate, ctx) {
+    const pre = checkMandatePreFill(mandate, ctx);
+    if (!pre.ok)
+        return pre;
+    if (!mandate)
+        return { ok: false, reason: 'no mandate provided' };
+    // The pre-fill phase skips the currency check when none is asserted yet;
+    // here the resolved currency is mandatory.
+    if (!ctx.currency) {
+        return { ok: false, reason: 'transaction currency could not be determined' };
+    }
+    // Transaction amount must be a clean integer minor-unit value.
+    if (!isInteger(ctx.amountMinor) || ctx.amountMinor < 0) {
+        return { ok: false, reason: 'transaction amount is not a non-negative integer (minor units)' };
+    }
+    if (ctx.amountMinor > mandate.maxAmountMinor) {
+        return {
+            ok: false,
+            reason: `amount ${ctx.amountMinor} exceeds mandate cap ${mandate.maxAmountMinor} (minor units)`,
+        };
+    }
+    return { ok: true };
+}
+function normalizeHost(host) {
+    // Reduce a scheme/path/port-bearing host to its bare hostname for the
+    // mandate-vs-checkout equality gate. Uses a linear `split('/')` to drop the
+    // path segment instead of a greedy `/\/.*$/` replace: on a merchant-supplied
+    // host with many leading slashes the greedy variant is a polynomial-ReDoS
+    // vector (CodeQL js/polynomial-redos), and `split` is exact-equivalent here —
+    // "everything before the first '/'". The remaining regexes are start/end
+    // anchored, so they backtrack linearly.
+    const noScheme = host
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, '');
+    const noPath = noScheme.split('/', 1)[0];
+    return noPath.replace(/:\d+$/, '');
+}

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

@@ -0,0 +1,30 @@
+import type { Page } from 'playwright-core';
+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". */
+    signal: string | null;
+};
+/** 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' | 'verification-required' | 'unknown';
+    signal: string | null;
+    /** Last non-final classification when the deadline expired ('processing' | 'unknown'). */
+    lastSeen: OutcomeStatus;
+    attempts: number;
+    elapsedMs: number;
+};
+/**
+ * Watch the page until a definitive outcome or the deadline. Polling (rather
+ * than waiting for one navigation) is deliberate: declines often render in
+ * place with NO navigation, while confirmations may arrive after several
+ * redirects — both resolve here the moment their signal appears. A detected
+ * issuer challenge is equally final for this observer: it will not resolve
+ * itself, so waiting out the deadline would only misreport it as unknown.
+ */
+export declare function observeOutcome(page: Page, opts?: {
+    deadlineMs?: number;
+    pollMs?: number;
+    holdThroughChallenge?: boolean;
+}): Promise<ObservedOutcome>;