@visa/cli 4.1.0-rc.2 → 4.1.0-rc.200

package/dist/checkout-engine/evidence.js

@@ -0,0 +1,104 @@
+// Evidence log. A timestamped JSONL trail of everything the executor did:
+// navigation, adapter choice, each field fill (with confidence + source),
+// the mandate verdict, the submit, and the final outcome, plus a compact
+// accessibility snapshot of the end state.
+//
+// Money-adjacent hygiene rule: the full PAN, the cvc, the card expiry, and any
+// one-time verification code NEVER enter the log. PANs are masked to last-4;
+// cvc, expiry, and OTP codes are redacted entirely. maskPan/maskCvc/maskExpiry/
+// maskOtp are the only sanctioned way to put such a value anywhere near a log
+// line. (receipt.ts redactPanLikeDigits only catches 12-19-digit PANs, so a
+// 4-8-digit OTP would slip straight through — maskOtp at the fill site is the
+// load-bearing guarantee it never reaches the evidence log.) Contact PII
+// (cardholder name, email, address, ...) is redacted via redactContact: the
+// log records THAT a field was filled, never the personal value.
+// Mask a PAN to its last four digits. Non-digits are stripped for the count.
+export function maskPan(pan) {
+    const digits = (pan || '').replace(/\D/g, '');
+    if (digits.length <= 4)
+        return '****';
+    return `**** **** **** ${digits.slice(-4)}`;
+}
+// The cvc is never displayed, even masked by length.
+export function maskCvc(_cvc) {
+    return 'redacted';
+}
+// The expiry is credential material too (one of the three keyable components
+// alongside the DPAN and the DAVV) — it never enters the log, in any format.
+export function maskExpiry() {
+    return 'redacted';
+}
+// A merchant one-time verification code is single-use secret material — it
+// never enters the log, in any format. Used at the oneTimeCode fill site so
+// the code is masked exactly as cvc/PAN are (see the header note above).
+export function maskOtp() {
+    return 'redacted';
+}
+// The registrable domain (approx eTLD+1) of an email address or hostname, for
+// the caller-side from-domain guard on verification links: before navigating a
+// link parsed from an untrusted OTP email, require the link host to match the
+// message sender's domain. extract.ts guarantees mechanical extraction, NOT
+// navigation safety — this guard is the anti-injection backstop.
+export function hostOf(hostOrEmail) {
+    return (hostOrEmail.split('@').pop() ?? '').trim().toLowerCase().replace(/\.$/, '');
+}
+// Strict bidirectional host-suffix match (exact / child / parent). Deliberately
+// NOT approximate eTLD+1 — that collapses shared-tenant hosts (`x.myshopify.com`,
+// `x.co.uk`) to a common suffix and lets a sibling tenant match; siblings never
+// match here. Fails SAFE: an unrelated-but-legitimate sender is skipped, not
+// trusted.
+function hostsRelated(a, b) {
+    const x = hostOf(a);
+    const y = hostOf(b);
+    if (!x || !y)
+        return false;
+    return x === y || x.endsWith('.' + y) || y.endsWith('.' + x);
+}
+// Whether a verification LINK is safe to navigate: the sender must NOT be the
+// unauthenticated inbound variant (AgentMail marks spoofable inbound with an
+// `.unauthenticated` sub-label), and the link host must belong to the sender's
+// domain. Returns false to SKIP a link that fails either check.
+export function verificationLinkAllowed(link, messageFrom) {
+    if (/\.unauthenticated\b/i.test(messageFrom))
+        return false;
+    let linkHost;
+    try {
+        linkHost = new URL(link).hostname;
+    }
+    catch {
+        return false;
+    }
+    return hostsRelated(linkHost, messageFrom);
+}
+// Contact values (cardholder name, email, address, ...) are PII and never
+// enter the log raw either. Email keeps its domain for debuggability;
+// everything else becomes a bare presence marker.
+export function redactContact(role, value) {
+    if (!value)
+        return '';
+    if (role === 'email') {
+        const at = value.lastIndexOf('@');
+        return at > 0 ? `<redacted>@${value.slice(at + 1)}` : '<redacted>';
+    }
+    return '<redacted>';
+}
+export class EvidenceLog {
+    steps = [];
+    snapshotSummary = null;
+    step(type, data = {}) {
+        this.steps.push({ ts: new Date().toISOString(), type, data });
+    }
+    setSnapshotSummary(summary) {
+        this.snapshotSummary = summary;
+    }
+    getSteps() {
+        return this.steps;
+    }
+    // Newline-delimited JSON. One object per line.
+    toJSONL() {
+        return this.steps.map((s) => JSON.stringify(s)).join('\n');
+    }
+    toObject() {
+        return { steps: this.steps, snapshotSummary: this.snapshotSummary };
+    }
+}

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

@@ -0,0 +1,215 @@
+import type { Browser, BrowserContext, Page } from 'playwright-core';
+import { type FieldMap } from './detect.js';
+import { type Mandate } from './mandate.js';
+import type { Instrument } from './instrument.js';
+import type { Contact, OtpResolver } from './types.js';
+import { EvidenceLog } from './evidence.js';
+import { type ObservedOutcome } from './outcome.js';
+import { type WebBotAuthConfig } from './web-bot-auth.js';
+export { minorFromDecimal, pageCurrency } from './amount.js';
+export type CheckoutMode = 'dry-run' | 'submit';
+export type CheckoutOutcome = 'reviewed-dry-run'
+/** Historical receipt value from the credential-disclosing dry-run. */
+ | 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate'
+/**
+ * KNOWN-NOT-CHARGED. Every `failed` path ends before the pay control was
+ * clicked (or before a credential existed at all), so a caller may retry it
+ * without risking a second charge.
+ */
+ | 'failed'
+/**
+ * SUBMITTED, OUTCOME UNKNOWN — the pay control WAS clicked and neither a
+ * confirmation nor a decline was observed before the deadline. The charge may
+ * have captured. NEVER retry this automatically.
+ *
+ * This case used to be reported as `failed`, and the difference is not
+ * academic: on 2026-08-17 a whop.com checkout returned `failed` here, the
+ * caller read that as "nothing happened" and re-ran the purchase, and the
+ * second run drew a second $5 against the owner's mandate. `outcome.ts`
+ * already treats an unrecognized post-submit page as the SAFE direction
+ * ('unknown' → operator verification); collapsing it into `failed` at the
+ * boundary is what threw that safety away. The distinction has to survive all
+ * the way to the value consumers branch on.
+ */
+ | 'unverified';
+/** Stable machine-readable cause for an expected terminal checkout result. */
+export type CheckoutFailureCode = 'card-number-field-unavailable' | 'human-action-required' | 'mandate-blocked'
+/** A detected, visible field we held a value for refused every fill attempt. */
+ | 'required-field-unfillable';
+export type CredentialLifecycle = 'not-requested' | 'minted-not-exposed' | 'partially-exposed' | 'fully-filled';
+export type CredentialTiming = {
+    approvedAt?: string;
+    credentialMintedAt?: string;
+    credentialExpiresAt?: string;
+    fillCompletedAt?: string;
+};
+export type CheckoutResult = {
+    outcome: CheckoutOutcome;
+    fields: FieldMap;
+    evidence: EvidenceLog;
+    confirmationRef?: string;
+    requiresAdapter: string[];
+    credentialLifecycle: CredentialLifecycle;
+    credentialTiming: CredentialTiming;
+    failureCode?: CheckoutFailureCode;
+    detail?: string;
+};
+export type PrepareCheckoutOptions = {
+    url: string;
+    mandate: Mandate;
+    browser: Browser;
+    contact?: Contact;
+    amountMinor?: number;
+    currency?: string;
+    debugShotsDir?: string;
+    webBotAuth?: WebBotAuthConfig | null;
+};
+export type RunCheckoutOptions = PrepareCheckoutOptions & {
+    instrument: Instrument;
+    contact: Contact;
+    mode: CheckoutMode;
+    outcomeDeadlineMs?: number;
+    resolveEmailOtp?: OtpResolver;
+};
+export type CheckoutReview = {
+    id: string;
+    url: string;
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+    mandateMaxAmountMinor: number;
+    mandateExpiresAt: string;
+    submitTarget: string | null;
+    submitTargetFingerprint: Readonly<CheckoutSubmitTargetFingerprint> | null;
+    detectedRoles: readonly string[];
+};
+export type CheckoutSubmitTargetFingerprint = {
+    kind: 'submit-control' | 'text-button';
+    label: string;
+    elementTag: string;
+    elementId: string | null;
+    elementName: string | null;
+    elementType: string | null;
+    formAction: string | null;
+    formMethod: string | null;
+    formTarget: string | null;
+};
+export type PreparedCheckout = {
+    readonly review: Readonly<CheckoutReview>;
+    readonly fields: Readonly<FieldMap>;
+    readonly evidence: EvidenceLog;
+    readonly requiresAdapter: readonly string[];
+};
+export type PrepareCheckoutResult = {
+    status: 'ready';
+    checkout: PreparedCheckout;
+} | {
+    status: 'finished';
+    result: CheckoutResult;
+};
+export type CheckoutApproval = {
+    approved: true;
+    reviewId: string;
+};
+export type SubmitApprovedCheckoutOptions = {
+    approval: CheckoutApproval;
+    instrument: Instrument;
+    contact: Contact;
+    mode: CheckoutMode;
+    outcomeDeadlineMs?: number;
+    challengeHoldMs?: number;
+    onChallengeHold?: (signal: string | null) => void;
+    resolveEmailOtp?: OtpResolver;
+};
+export type SubmitCandidateMeta = {
+    label: string;
+    ariaHidden: boolean;
+    tabIndex: number | null;
+    visible: boolean;
+    area: number;
+};
+export declare function preferredSubmitIndex(cands: readonly SubmitCandidateMeta[], opts?: {
+    allowDeferred?: boolean;
+}): number;
+export declare function snapshotOrigin(rawUrl: string): string;
+export type PreparedCheckoutSession = {
+    checkout: PreparedCheckout;
+    context: BrowserContext;
+    page: Page;
+    options: PrepareCheckoutOptions;
+    evidence: EvidenceLog;
+    fields: FieldMap;
+    requiresAdapter: Set<string>;
+};
+export type PreparedCheckoutSessionStore = {
+    put: (reviewId: string, state: PreparedCheckoutSession) => void;
+    take: (reviewId: string) => PreparedCheckoutSession | undefined;
+    peek: (reviewId: string) => PreparedCheckoutSession | undefined;
+    pendingCleanupReviewIds: () => readonly string[];
+    reapExpired: (nowMs?: number) => Promise<number>;
+    dispose: () => Promise<void>;
+};
+export type InMemoryPreparedCheckoutStoreOptions = {
+    ttlMs?: number;
+    cleanupRetryMs?: number;
+    now?: () => number;
+};
+export declare const DEFAULT_PREPARED_CHECKOUT_TTL_MS: number;
+export declare const DEFAULT_PREPARED_CHECKOUT_CLEANUP_RETRY_MS = 5000;
+export declare class InMemoryPreparedCheckoutStore implements PreparedCheckoutSessionStore {
+    private readonly entries;
+    private readonly cleanupPending;
+    private readonly ttlMs;
+    private readonly cleanupRetryMs;
+    private readonly now;
+    private reaper;
+    constructor(options?: InMemoryPreparedCheckoutStoreOptions);
+    put(reviewId: string, state: PreparedCheckoutSession): void;
+    take(reviewId: string): PreparedCheckoutSession | undefined;
+    peek(reviewId: string): PreparedCheckoutSession | undefined;
+    pendingCleanupReviewIds(): readonly string[];
+    reapExpired(nowMs?: number): Promise<number>;
+    dispose(): Promise<void>;
+    private queueCleanup;
+    private scheduleReaper;
+    private closeState;
+}
+export declare function reconcileHeldOutcome(original: ObservedOutcome, held: ObservedOutcome): ObservedOutcome;
+export declare function debugShotMaskPlan(fields: FieldMap): {
+    skipReason: string | null;
+    maskLocators: string[];
+    maskFrames: {
+        frame: string;
+        locator: string;
+    }[];
+};
+export declare function isStripeLinkConsumerRequest(url: string): boolean;
+export declare function suppressStripeLink(page: Page, evidence: EvidenceLog): Promise<void>;
+export type LinkQuietResult = {
+    fired: boolean;
+    waitedMs: number;
+};
+/**
+ * Wait for the suppressed Stripe Link lookup to fire and settle BEFORE the
+ * submit click. Stripe debounces its consumer-session lookup ~300ms after the
+ * email input changes; our fill→click gap is single-digit ms, so the (aborted)
+ * lookup used to land INSIDE Stripe's in-flight submit chain and kill it
+ * silently — the click looked accepted but tokenization never ran and the page
+ * sat on the form until the outcome deadline (#5879: three identical live
+ * stalls at donate.stripe.com). Verified live A/B on that page: instant click →
+ * dead submit, no /v1/payment_methods; lookup settled first → tokenization and
+ * the confirm step both reached.
+ *
+ * If the lookup already fired, only the short settle applies (lets Stripe's
+ * abort handling unwind). If it never fires — non-Link page variants, no email
+ * field — the bound expires and the click proceeds as before.
+ */
+export declare function waitForLinkLookupQuiet(page: Page, opts?: {
+    boundMs?: number;
+    settleMs?: number;
+    delay?: (ms: number) => Promise<void>;
+}): Promise<LinkQuietResult>;
+export declare function prepareCheckout(opts: PrepareCheckoutOptions, store?: PreparedCheckoutSessionStore): Promise<PrepareCheckoutResult>;
+export declare function submitApprovedCheckout(reviewId: string, opts: SubmitApprovedCheckoutOptions, store?: PreparedCheckoutSessionStore): Promise<CheckoutResult>;
+export declare function cancelPreparedCheckout(reviewId: string, detail?: string, store?: PreparedCheckoutSessionStore): Promise<CheckoutResult>;
+export declare function runCheckout(opts: RunCheckoutOptions, store?: PreparedCheckoutSessionStore): Promise<CheckoutResult>;