@visa/cli 4.1.0-rc.298 → 4.1.0-rc.299

package/dist/checkout-engine/evidence.js

@@ -1,104 +0,0 @@
-// 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

@@ -1,262 +0,0 @@
-import type { Browser, BrowserContext, Page } from 'playwright-core';
-import { type FieldMap } from './detect.js';
-import { type Mandate, type MandateRefusalCode } 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';
-import { type NavigationRedirectEvidence } from './shopify-primary-domain.js';
-export { minorFromDecimal, pageCurrency } from './amount.js';
-export type CheckoutMode = 'dry-run' | 'submit';
-export type CheckoutRoute = 'guest-card';
-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;
-    /** Bounded reason behind a `blocked-by-mandate` outcome; absent otherwise. */
-    refusalCode?: MandateRefusalCode;
-    detail?: string;
-};
-export type PrepareCheckoutOptions = {
-    url: string;
-    checkoutRoute: CheckoutRoute;
-    mandate: Mandate;
-    browser: Browser;
-    contact?: Contact;
-    amountMinor?: number;
-    currency?: string;
-    debugShotsDir?: string;
-    webBotAuth?: WebBotAuthConfig | null;
-    /**
-     * Process-internal UCP provenance. Public callers may relay only handoffId;
-     * this origin set is recovered by the CLI from its single-use registry.
-     */
-    trustedMerchantIdentity?: Readonly<{
-        handoffId: string;
-        checkoutId: string;
-        allowedOrigins: readonly string[];
-        expiresAt: string;
-    }>;
-};
-export type RunCheckoutOptions = PrepareCheckoutOptions & {
-    instrument: Instrument;
-    contact: Contact;
-    mode: CheckoutMode;
-    outcomeDeadlineMs?: number;
-    resolveEmailOtp?: OtpResolver;
-};
-export type CheckoutReview = {
-    id: string;
-    url: string;
-    merchantHost: string;
-    /** Exact origin frozen for a trusted UCP checkout; omitted for generic flows. */
-    merchantOrigin?: string;
-    amountMinor: number;
-    currency: string;
-    mandateMaxAmountMinor: number;
-    mandateExpiresAt: string;
-    submitTarget: string | null;
-    submitTargetFingerprint: Readonly<CheckoutSubmitTargetFingerprint> | null;
-    detectedRoles: readonly string[];
-    checkoutRoute: CheckoutRoute;
-};
-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[];
-    readonly checkoutRoute: CheckoutRoute;
-};
-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 type TrustedOriginVerdict = Readonly<{
-    code: MandateRefusalCode;
-    reason: string;
-}>;
-export declare function trustedMerchantOriginVerdict(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): TrustedOriginVerdict | null;
-export declare function trustedMerchantOriginRefusal(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): string | null;
-/**
- * Bind the storefront a trusted UCP continuation actually lands on (#8669).
- *
- * The merchant published its UCP business profile at its own business origin
- * and declared the permanent `*.myshopify.com` service that issued the
- * continuation; the CLI verified both before minting the handoff. That is
- * independently verified merchant provenance, so the review may bind the final
- * page origin when, and only when: the navigation started on that declared
- * myshopify origin, the final origin is plain HTTPS, and its host is the
- * declared business host modulo a leading `www.` label. The redirect chain in
- * between (Shopify's primary-domain hop, its shop.app bounce, #8496) carries no
- * authority either way: a redirect cannot land on the merchant's own business
- * domain unless the merchant controls it, and any other final host stays an
- * undeclared origin. Shopify's `primary_domain_redirection` proof is recorded
- * as evidence when present but is not required.
- */
-export declare function trustedShopifyAliasOrigin(args: {
-    allowedOrigins: readonly string[];
-    initialUrl: string;
-    finalUrl: string;
-    redirects: readonly NavigationRedirectEvidence[];
-}): string | null;
-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>;