@visa/cli 4.1.0-rc.6 → 4.1.0-rc.61

package/dist/checkout-engine/outcome.js

@@ -0,0 +1,225 @@
+// Definitive merchant/processor "no". Kept high-precision: every phrase here
+// means the charge did NOT succeed — never "maybe".
+const DECLINED_BODY = [
+    { name: 'body:card-declined', re: /\bdeclined\b/ },
+    { name: 'body:payment-failed', re: /payment (?:has )?failed/ },
+    { name: 'body:do-not-honor', re: /do not honou?r/ },
+    { name: 'body:insufficient-funds', re: /insufficient funds/ },
+    // Shopify's stock copy for a rejected card.
+    { name: 'body:not-verified', re: /payment details couldn.t be verified/ },
+    { name: 'body:not-authorized', re: /transaction (?:was )?not authori[sz]ed/ },
+];
+// Where checkouts land after success. Matched against the parsed PATHNAME
+// only — never the hostname or query string — and anchored to terminal
+// segments, so `?next=/thank-you`, a host like thankyou-boutique.example,
+// `/no-thank-you`, or a pre-payment review step at `/checkout/confirm` can
+// never fabricate a confirmed verdict (Sentinel finding on #5704). A missed
+// real confirmation degrades to 'unknown' + operator verification — the safe
+// direction; a false 'confirmed' would report a charge that never happened.
+// `thank-you` covers Shopify's legacy (/checkouts/<token>/thank_you) and
+// extensibility (/checkouts/cn/<token>/thank-you) endings.
+const CONFIRMED_URL = [
+    { name: 'url:thank-you', re: /\/thank[-_]?you\/?$/ },
+    { name: 'url:order-confirmation', re: /\/order-confirmation\b/ },
+    { name: 'url:orders-page', re: /\/orders\/[a-z0-9]/ },
+    { name: 'url:success', re: /\/success\/?$/ },
+    { name: 'url:confirmation', re: /\/confirmation\/?$/ },
+];
+const CONFIRMED_BODY = [
+    { name: 'body:order-confirmed', re: /order (?:is )?(?:confirmed|placed)/ },
+    { name: 'body:thank-you-order', re: /thank(?:s| you) for your (?:order|purchase|donation)/ },
+    // Stripe payment-link success copy: "A payment to X will appear on your
+    // statement." Live run c2eda9f6 confirmed on-screen but classified unknown.
+    { name: 'body:on-your-statement', re: /payment to .{1,80} will appear on your statement/ },
+    { name: 'body:payment-ok', re: /payment (?:successful|approved)/ },
+    { name: 'body:order-received', re: /(?:order received|we.ve received your order)/ },
+    { name: 'body:order-ref', re: /order #/ },
+];
+// Issuer / 3-D Secure verification surfaces. 3DS runs BEFORE authorization,
+// so a detected challenge is its own definitive verdict: "a human must verify
+// — no charge exists until the challenge completes", and the page will never
+// resolve to confirmed or declined on its own. Signals are precision-first
+// heuristics: the two vendor hosts are documented 3DS infrastructure
+// (Cardinal Commerce is Visa's 3DS provider; Stripe serves its challenge
+// frames from hooks.stripe.com/3d_secure), and the generic pattern requires a
+// 3DS path segment FOLLOWED by a challenge-flow segment, so an unrelated
+// `/acs/…` route or a marketing `/3d/` page can never match. A missed
+// challenge degrades to 'unknown' + operator verification — the safe
+// direction, and exactly the pre-detection behavior.
+const ACTION_REQUIRED_FRAME = [
+    { name: 'frame:cardinal-3ds', re: /(?:^|\.)cardinalcommerce\.com\// },
+    { name: 'frame:stripe-3ds', re: /hooks\.stripe\.com\/3d_secure/ },
+    {
+        name: 'frame:3ds-challenge',
+        re: /\/(?:3ds2?|3d[-_]?secure|threeds2?|acs)\/(?:challenge|browser|method|auth)\b/,
+    },
+];
+// Full-page ACS redirect flows (no iframe): matched on the pathname only.
+const ACTION_REQUIRED_URL = [
+    { name: 'url:3ds-redirect', re: /\/(?:3ds2?|3d[-_]?secure|threeds2?)\b/ },
+];
+// Challenge copy on the merchant's own page. Kept tight: each phrase is an
+// instruction to authenticate, not a generic mention of security.
+// 'body:link-wallet' must stay FIRST: the Stripe Link login modal is NOT an
+// issuer challenge (completing it pays with an old saved card, not the minted
+// 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>".
+// 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/ },
+    { name: 'body:code-sent', re: /(?:code|passcode) (?:has been |was )?sent to/ },
+];
+// Interstitial states that mean "no verdict yet — keep watching".
+const PROCESSING = [
+    { name: 'body:processing', re: /processing (?:your )?(?:payment|order)/ },
+    { name: 'body:please-wait', re: /please wait|do not (?:refresh|close)/ },
+    { name: 'url:processing', re: /\/processing\b/ },
+];
+function match(patterns, text) {
+    for (const p of patterns)
+        if (p.re.test(text))
+            return p.name;
+    return null;
+}
+// URL signals only ever see the pathname: hostname and query/hash must not be
+// able to satisfy a confirmation pattern. Falls back to a manual query/hash
+// strip for non-absolute inputs (page.url() is always absolute in practice).
+function pathnameOf(url) {
+    try {
+        return new URL(url).pathname.toLowerCase();
+    }
+    catch {
+        return url.split(/[?#]/)[0].toLowerCase();
+    }
+}
+// Frame signals see host + pathname only — the same #5704 lesson as
+// confirmation URLs: a query string like `?next=https://x.cardinalcommerce.com/`
+// must never satisfy an infrastructure-host pattern.
+function hostAndPathOf(url) {
+    try {
+        const u = new URL(url);
+        return `${u.hostname}${u.pathname}`.toLowerCase();
+    }
+    catch {
+        return url.split(/[?#]/)[0].toLowerCase();
+    }
+}
+/** Pure classification of one page state (case-insensitive on all inputs). */
+export function classifyOutcomePage(url, bodyText, frameUrls = []) {
+    const u = pathnameOf(url);
+    const b = bodyText.toLowerCase();
+    const declined = match(DECLINED_BODY, b);
+    if (declined)
+        return { status: 'declined', signal: declined };
+    for (const frameUrl of frameUrls) {
+        const frame = match(ACTION_REQUIRED_FRAME, hostAndPathOf(frameUrl));
+        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 };
+    const challengeBody = match(ACTION_REQUIRED_BODY, b);
+    if (challengeBody)
+        return { status: 'action-required', signal: challengeBody };
+    const confirmedUrl = match(CONFIRMED_URL, u);
+    if (confirmedUrl)
+        return { status: 'confirmed', signal: confirmedUrl };
+    const confirmedBody = match(CONFIRMED_BODY, b);
+    if (confirmedBody)
+        return { status: 'confirmed', signal: confirmedBody };
+    const processing = match(PROCESSING, b) ?? match(PROCESSING, u);
+    if (processing)
+        return { status: 'processing', signal: processing };
+    return { status: 'unknown', signal: null };
+}
+/**
+ * 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 async function observeOutcome(page, opts = {}) {
+    const deadlineMs = opts.deadlineMs ?? 20_000;
+    const pollMs = opts.pollMs ?? 500;
+    const startedAt = Date.now();
+    let attempts = 0;
+    for (;;) {
+        attempts++;
+        // Visible text only (innerText, never textContent): Stripe payment links
+        // embed their entire client-side error catalog — including "your card was
+        // declined" — in non-rendered DOM, so a hidden-inclusive read classifies a
+        // fresh page as declined before any authorization has run.
+        const body = (await page.evaluate(() => document.body?.innerText ?? '').catch(() => '')) || '';
+        const frameUrls = page.frames().map((f) => f.url());
+        const seen = classifyOutcomePage(page.url(), body, frameUrls);
+        // An active challenge is normally final for the automated observer (it
+        // will not resolve itself). holdThroughChallenge inverts that for the
+        // human-in-the-loop hold: the challenge stays "pending" and observation
+        // 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,
+                signal: seen.signal,
+                lastSeen: seen.status,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+            };
+        }
+        if (Date.now() - startedAt >= deadlineMs) {
+            return {
+                status: 'unknown',
+                signal: seen.signal,
+                lastSeen: seen.status,
+                attempts,
+                elapsedMs: Date.now() - startedAt,
+            };
+        }
+        await page.waitForTimeout(pollMs);
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * lstat-only guard for operator-supplied secret-bearing files: must be a
+ * regular file (never a symlink), owner-only (chmod 600), and size-bounded.
+ * Reads NOTHING — safe to run as a preflight before the point where the
+ * file's contents are allowed to be consumed (the assurance-mode agent
+ * credential is only read after the operator approves the checkout review).
+ */
+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

@@ -0,0 +1,41 @@
+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.
+ * Reads NOTHING — safe to run as a preflight before the point where the
+ * file's contents are allowed to be consumed (the assurance-mode agent
+ * credential is only read after the operator approves the checkout review).
+ */
+export async function assertOwnerOnlyFile(path, label, maxBytes = 16 * 1024) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error(`${label} must be a regular file`);
+    if ((info.mode & 0o077) !== 0)
+        throw new Error(`${label} must be owner-only (chmod 600)`);
+    if (info.size > maxBytes)
+        throw new Error(`${label} is unexpectedly large`);
+}
+/** The same guard, then parse — contents are read only after the guard passes. */
+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/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

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

@@ -0,0 +1,81 @@
+import type { EvidenceStep } from './evidence.js';
+import type { CheckoutMode, CheckoutOutcome, CheckoutResult, CredentialLifecycle, CredentialTiming } from './executor.js';
+import type { VicConfirmationReport } from './vic-confirmation.js';
+export type CheckoutReceipt = {
+    schema: 'checkout-agent-receipt/v1';
+    recordedAt: string;
+    mode: CheckoutMode;
+    reviewId: string | null;
+    merchant: {
+        name: string;
+        host: string;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    outcome: CheckoutOutcome;
+    detail: string | null;
+    confirmationRef: string | null;
+    vicConfirmation: VicConfirmationReport | null;
+    credentialLifecycle: CredentialLifecycle;
+    credentialTiming: CredentialTiming;
+    detectedRoles: string[];
+    requiresAdapter: string[];
+    reconciliation: {
+        required: boolean;
+        reasons: string[];
+    };
+    evidence: {
+        steps: EvidenceStep[];
+        snapshotSummary: string | null;
+    };
+};
+export type ReceiptWriteReport = {
+    written: true;
+    path: string;
+    panRedactions: number;
+} | {
+    written: false;
+    reason: string;
+};
+export declare function buildReceipt(input: {
+    mode: CheckoutMode;
+    reviewId: string | null;
+    merchant: {
+        name: string;
+        host: string;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    result: CheckoutResult;
+    vicConfirmation: VicConfirmationReport | null;
+    /** Injectable for tests; defaults to now. */
+    recordedAt?: Date;
+}): CheckoutReceipt;
+/**
+ * Defense-in-depth scrub before anything touches disk: any standalone
+ * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by
+ * single spaces/hyphens between digit groups, the way merchant card-preview
+ * widgets render a typed number ("4242 4242 4242 4242") into page text that
+ * can reach the snapshot summary. Upstream masking means a hit should be
+ * impossible; the count surfaces so the runner can flag a leak.
+ */
+export declare function redactPanLikeDigits(text: string): {
+    text: string;
+    redactions: number;
+};
+export declare function serializeReceipt(receipt: CheckoutReceipt): {
+    json: string;
+    panRedactions: number;
+};
+export declare function receiptFileName(receipt: CheckoutReceipt): string;
+/**
+ * Persist one receipt as an owner-only file (0600) in an owner-only directory
+ * (0700). Refuses to overwrite an existing file (`wx`). Never throws.
+ */
+export declare function writeReceipt(dir: string, receipt: CheckoutReceipt): Promise<ReceiptWriteReport>;

package/dist/checkout-engine/receipt.js

@@ -0,0 +1,109 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { submitClickedWithoutConfirmation } from './live-fill-approval.js';
+/**
+ * What the operator still owes after this run. Empty for a clean dry-run fill
+ * and for a definitive submit outcome whose VIC confirmation posted.
+ */
+function reconciliationFor(result, vicConfirmation) {
+    const reasons = [];
+    if (submitClickedWithoutConfirmation(result)) {
+        reasons.push('the pay control was clicked but no definitive outcome was observed — ' +
+            'verify the charge with the merchant dashboard before any retry');
+    }
+    if ((result.outcome === 'confirmed' || result.outcome === 'declined') &&
+        vicConfirmation &&
+        !vicConfirmation.posted) {
+        reasons.push(`the VIC confirmation was not posted (${vicConfirmation.reason}) — ` +
+            'retry it for this intent out-of-band');
+    }
+    if (result.outcome === 'confirmed' && !result.confirmationRef) {
+        reasons.push('confirmed without a merchant confirmation reference — ' +
+            'record the order number from the merchant dashboard');
+    }
+    if (result.outcome === 'action-required') {
+        reasons.push('an issuer verification challenge was shown and not completed — ' +
+            'finish the purchase manually if still wanted, or confirm with the merchant that no order exists');
+    }
+    return { required: reasons.length > 0, reasons };
+}
+export function buildReceipt(input) {
+    const { result } = input;
+    return {
+        schema: 'checkout-agent-receipt/v1',
+        recordedAt: (input.recordedAt ?? new Date()).toISOString(),
+        mode: input.mode,
+        reviewId: input.reviewId,
+        merchant: { name: input.merchant.name, host: input.merchant.host },
+        transaction: input.transaction,
+        outcome: result.outcome,
+        detail: result.detail ?? null,
+        confirmationRef: result.confirmationRef ?? null,
+        vicConfirmation: input.vicConfirmation,
+        credentialLifecycle: result.credentialLifecycle,
+        credentialTiming: result.credentialTiming,
+        detectedRoles: Object.keys(result.fields),
+        requiresAdapter: [...result.requiresAdapter],
+        reconciliation: reconciliationFor(result, input.vicConfirmation),
+        evidence: result.evidence.toObject(),
+    };
+}
+function luhnValid(digits) {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (double) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+/**
+ * Defense-in-depth scrub before anything touches disk: any standalone
+ * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by
+ * single spaces/hyphens between digit groups, the way merchant card-preview
+ * widgets render a typed number ("4242 4242 4242 4242") into page text that
+ * can reach the snapshot summary. Upstream masking means a hit should be
+ * impossible; the count surfaces so the runner can flag a leak.
+ */
+export function redactPanLikeDigits(text) {
+    let redactions = 0;
+    const scrubbed = text.replace(/(?<!\d)(?<!\d[\s-])\d(?:[\s-]?\d){11,18}(?![\s-]?\d)/g, (run) => {
+        const digits = run.replace(/[\s-]/g, '');
+        if (digits.length < 12 || digits.length > 19 || !luhnValid(digits))
+            return run;
+        redactions++;
+        return '<redacted:pan-like>';
+    });
+    return { text: scrubbed, redactions };
+}
+export function serializeReceipt(receipt) {
+    const { text, redactions } = redactPanLikeDigits(`${JSON.stringify(receipt, null, 2)}\n`);
+    return { json: text, panRedactions: redactions };
+}
+export function receiptFileName(receipt) {
+    const ts = receipt.recordedAt.replace(/[:.]/g, '-');
+    const review = (receipt.reviewId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
+    return `receipt-${ts}-${review || 'no-review'}.json`;
+}
+/**
+ * Persist one receipt as an owner-only file (0600) in an owner-only directory
+ * (0700). Refuses to overwrite an existing file (`wx`). Never throws.
+ */
+export async function writeReceipt(dir, receipt) {
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const path = join(dir, receiptFileName(receipt));
+        const { json, panRedactions } = serializeReceipt(receipt);
+        await writeFile(path, json, { mode: 0o600, flag: 'wx' });
+        return { written: true, path, panRedactions };
+    }
+    catch (err) {
+        return { written: false, reason: err.message };
+    }
+}

package/dist/checkout-engine/repo-env.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Load the monorepo root `.env` as DEFAULTS for the runner, so stable
+ * per-machine config (VGS credentials, CHECKOUT_APPROVAL_BASE_URL,
+ * CHECKOUT_AGENT_ALLOW_SUBMIT, CHECKOUT_AGENT_MODE) is set once instead of
+ * retyped on every invocation. `process.loadEnvFile` never overrides
+ * variables already present in the environment (verified: shell always wins),
+ * so an explicit `FOO=x pnpm pay …` still beats the file. A missing file is
+ * fine — the runner then relies on the ambient environment exactly as before.
+ */
+export declare function defaultRepoEnvPath(): string;
+export declare function loadRepoEnvDefaults(path?: string, log?: (line: string) => void): boolean;

package/dist/checkout-engine/repo-env.js

@@ -0,0 +1,23 @@
+import { fileURLToPath } from 'node:url';
+/**
+ * Load the monorepo root `.env` as DEFAULTS for the runner, so stable
+ * per-machine config (VGS credentials, CHECKOUT_APPROVAL_BASE_URL,
+ * CHECKOUT_AGENT_ALLOW_SUBMIT, CHECKOUT_AGENT_MODE) is set once instead of
+ * retyped on every invocation. `process.loadEnvFile` never overrides
+ * variables already present in the environment (verified: shell always wins),
+ * so an explicit `FOO=x pnpm pay …` still beats the file. A missing file is
+ * fine — the runner then relies on the ambient environment exactly as before.
+ */
+export function defaultRepoEnvPath() {
+    return fileURLToPath(new URL('../../../.env', import.meta.url));
+}
+export function loadRepoEnvDefaults(path = defaultRepoEnvPath(), log = (line) => process.stdout.write(`${line}\n`)) {
+    try {
+        process.loadEnvFile(path);
+    }
+    catch {
+        return false;
+    }
+    log(`loaded env defaults from ${path} (already-set variables win)`);
+    return true;
+}

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

@@ -0,0 +1,44 @@
+export type PostalAddress = {
+    firstName?: string;
+    lastName?: string;
+    fullName?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+};
+export type Contact = PostalAddress & {
+    email?: string;
+    phone?: string;
+    billingAddress?: PostalAddress;
+};
+export type FilledField = {
+    role: string;
+    locator: string;
+    confidence: number;
+    source: string;
+    frame?: string;
+    value: string;
+    ok: boolean;
+    error?: string;
+};
+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/types.js

@@ -0,0 +1,2 @@
+// Shared value types used across the engine.
+export {};

package/dist/checkout-engine/vgs-gateway/fetch-credential.d.mts

@@ -0,0 +1,74 @@
+export type VgsTransaction = {
+  merchantName: string
+  merchantUrl: string
+  merchantCountryCode: string
+  transactionAmount: string
+  transactionCurrencyCode: string
+}
+
+export function createIntent(
+  input: {
+    tokenId: string
+    assuranceData: unknown
+    transaction: VgsTransaction
+  },
+  env?: Record<string, string | undefined>
+): Promise<{
+  intentId: string
+  /**
+   * Creation-time status attribute (null when VGS omits it). HTTP 201 alone
+   * does not mean the intent is authorized — surface this when a later
+   * cryptogram fails (#5709).
+   */
+  status: string | null
+}>
+
+export function fetchCryptogram(
+  input: {
+    tokenId: string
+    intentId: string
+    transaction: VgsTransaction
+  },
+  env?: Record<string, string | undefined>
+): Promise<{
+  networkToken: string
+  expMonth: number
+  expYear: number
+  cryptogramType: string
+  cryptogramValue: string
+  cryptogramExpiresAt?: string
+}>
+
+export function getCredential(
+  input: {
+    tokenId: string
+    assuranceData: unknown
+    transaction: VgsTransaction
+  },
+  env?: Record<string, string | undefined>
+): Promise<{
+  networkToken: string
+  expMonth: number
+  expYear: number
+  cryptogramType: string
+  cryptogramValue: string
+  cryptogramExpiresAt?: string
+}>
+
+export function postConfirmation(input: {
+  tokenId: string
+  intentId: string
+  transactionStatus: 'APPROVED' | 'DECLINED' | 'PENDING' | 'ERROR' | 'CANCELLED'
+  transactionType:
+    | 'PURCHASE'
+    | 'AUTHORIZATION'
+    | 'CAPTURE'
+    | 'REFUND'
+    | 'REVERSAL'
+    | 'VERIFICATION'
+    | 'CHARGEBACK'
+    | 'FRAUD'
+  /** ISO 8601; converted to the guide's quoted epoch-seconds on the wire. */
+  transactionTimestamp: string
+  transaction: Pick<VgsTransaction, 'transactionAmount' | 'transactionCurrencyCode'>
+}, env?: Record<string, string | undefined>): Promise<{ ok: true }>