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

package/dist/checkout-engine/confirmed-merchants.d.ts

@@ -0,0 +1,31 @@
+/** One confirmed charge, in the receipt's own terms. */
+export type ConfirmedCharge = {
+    recordedAt: string;
+    amount: string;
+    currency: string;
+    /** Receipt file basename, so an operator can open the evidence log. */
+    receiptFile: string;
+};
+export type ConfirmedMerchant = {
+    /** The checkout page the card went through. */
+    url: string;
+    host: string;
+    /**
+     * Curated human identity (known-merchants.ts), present only when someone has
+     * identified who is behind this checkout URL. Hosted payment links carry an
+     * opaque path on the PSP's host, so without this a row names nobody.
+     */
+    name?: string;
+    category?: string;
+    website?: string;
+    confirmedCount: number;
+    lastConfirmedAt: string;
+    charges: ConfirmedCharge[];
+};
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export declare function readConfirmedMerchants(receiptDir?: string): Promise<ConfirmedMerchant[]>;

package/dist/checkout-engine/confirmed-merchants.js

@@ -0,0 +1,165 @@
+// "Where can I use my card?", the merchant registry derived from this
+// device's checkout receipts.
+//
+// Receipts (receipt.ts) are the only local record that a real merchant
+// checkout completed on this box. This module reads them back and answers one
+// question: which checkout pages has this card actually gone through?
+//
+// A merchant only counts when BOTH halves agree. The engine's own outcome must
+// be 'confirmed' (the merchant showed a definitive success) AND the VIC
+// confirmation must have posted APPROVED (the network side of the same
+// purchase). Either half alone is a claim, not a completion: a 'confirmed' with
+// no posted confirmation is exactly the reconciliation case receipt.ts flags,
+// and a posted DECLINED is a completed report of a failure.
+//
+// Reading is best-effort by construction. The receipts directory is an operator
+// artifact that anything on the box can touch, so an unreadable or malformed
+// file is skipped rather than failing the whole read. One bad file must not
+// hide every merchant behind it.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * The URL a receipt's charge happened at.
+ *
+ * A compact v2 receipt carries an exact checkout URL only when it is already in
+ * the curated identity map; otherwise it carries the host. Legacy v1 receipts
+ * keep the URL in the evidence log (the executor's first 'navigation' step is
+ * the page the run opened), so recover it there and fall back to the host when
+ * that evidence is absent or shaped differently.
+ */
+function checkoutUrlOf(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const checkoutUrl = receipt.merchant.checkoutUrl;
+        return checkoutUrl && KNOWN_MERCHANT_IDENTITIES[checkoutUrl]
+            ? checkoutUrl
+            : `https://${receipt.merchant.host}/`;
+    }
+    const navigation = receipt.evidence.steps.find((step) => step?.type === 'navigation');
+    const data = navigation?.data;
+    const url = typeof data === 'object' && data !== null ? data.url : undefined;
+    return typeof url === 'string' && url.length > 0 ? url : `https://${receipt.merchant.host}/`;
+}
+function isConfirmedCompletion(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        return receipt.outcome === 'confirmed' && receipt.network.confirmation === 'APPROVED';
+    }
+    return (receipt.outcome === 'confirmed' &&
+        receipt.vicConfirmation?.posted === true &&
+        receipt.vicConfirmation.transactionStatus === 'APPROVED');
+}
+/**
+ * Parse one supported receipt file, or null when its fields cannot safely feed
+ * the registry. Deliberately permissive about everything the grouping does not
+ * touch: older and newer engines only have to carry the fields read below.
+ */
+function parseReceipt(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const receipt = parsed;
+    if (receipt.schema === 'checkout-agent-receipt/v1') {
+        const v1 = receipt;
+        if (typeof v1.recordedAt !== 'string')
+            return null;
+        if (typeof v1.merchant?.host !== 'string')
+            return null;
+        if (typeof v1.transaction?.amount !== 'string')
+            return null;
+        if (typeof v1.transaction?.currency !== 'string')
+            return null;
+        if (!Array.isArray(v1.evidence?.steps))
+            return null;
+        return v1;
+    }
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const v2 = receipt;
+        if (typeof v2.recordedAt !== 'string')
+            return null;
+        if (typeof v2.merchant?.host !== 'string')
+            return null;
+        if (v2.merchant.checkoutUrl !== null && typeof v2.merchant.checkoutUrl !== 'string')
+            return null;
+        if (typeof v2.transaction?.amount !== 'string')
+            return null;
+        if (typeof v2.transaction?.currency !== 'string')
+            return null;
+        if (v2.network?.confirmation !== null &&
+            v2.network?.confirmation !== 'APPROVED' &&
+            v2.network?.confirmation !== 'DECLINED') {
+            return null;
+        }
+        return v2;
+    }
+    return null;
+}
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export async function readConfirmedMerchants(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const byUrl = new Map();
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const receipt = parseReceipt(raw);
+        if (!receipt || !isConfirmedCompletion(receipt))
+            continue;
+        const url = checkoutUrlOf(receipt);
+        const charge = {
+            recordedAt: receipt.recordedAt,
+            amount: receipt.transaction.amount,
+            currency: receipt.transaction.currency,
+            receiptFile: name,
+        };
+        const existing = byUrl.get(url);
+        if (existing) {
+            existing.confirmedCount += 1;
+            existing.charges.push(charge);
+            if (charge.recordedAt > existing.lastConfirmedAt) {
+                existing.lastConfirmedAt = charge.recordedAt;
+            }
+            continue;
+        }
+        const identity = KNOWN_MERCHANT_IDENTITIES[url];
+        byUrl.set(url, {
+            url,
+            host: receipt.merchant.host,
+            // Conditional spread on purpose: an unidentified merchant carries no
+            // identity keys at all, rather than keys holding undefined.
+            ...(identity ?? {}),
+            confirmedCount: 1,
+            lastConfirmedAt: charge.recordedAt,
+            charges: [charge],
+        });
+    }
+    const merchants = [...byUrl.values()];
+    for (const merchant of merchants) {
+        merchant.charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    }
+    merchants.sort((left, right) => (left.lastConfirmedAt < right.lastConfirmedAt ? 1 : -1));
+    return merchants;
+}

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

@@ -0,0 +1,61 @@
+import type { Page } from 'playwright-core';
+export type FieldSource = 'autocomplete' | 'attr-heuristic' | 'label-text' | 'iframe-psp' | 'type-inference';
+export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'phone' | 'oneTimeCode' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
+export declare const ALL_ROLES: FieldRole[];
+export type SelectOption = {
+    value: string;
+    text: string;
+};
+export type CandidateMeta = {
+    idx: number;
+    tag: 'input' | 'select' | 'textarea';
+    type: string;
+    name: string;
+    id: string;
+    placeholder: string;
+    ariaLabel: string;
+    autocomplete: string;
+    maxlength: string;
+    inputmode: string;
+    pattern: string;
+    labelText: string;
+    options: SelectOption[];
+    visible: boolean;
+};
+export type RoleMatch = {
+    role: FieldRole;
+    confidence: number;
+    source: FieldSource;
+};
+export type FieldEntry = {
+    locator: string;
+    confidence: number;
+    source: FieldSource;
+    frame?: string;
+    tag: 'input' | 'select' | 'textarea';
+    inputType: string;
+    visible: boolean;
+    options?: SelectOption[];
+    maxlength?: number;
+};
+export type FieldMap = Partial<Record<FieldRole, FieldEntry>>;
+export type FieldCandidate = {
+    role: FieldRole | null;
+    confidence: number;
+    source: FieldSource | null;
+    matches: RoleMatch[];
+    frame?: string;
+    meta: CandidateMeta;
+};
+export type PspHit = {
+    psp: string;
+    requiresAdapter: string | null;
+    frameSelector: string;
+};
+export type DetectResult = {
+    fields: FieldMap;
+    candidates: FieldCandidate[];
+    psps: PspHit[];
+};
+export declare function classifyCandidate(m: CandidateMeta): RoleMatch[];
+export declare function detectFields(page: Page): Promise<DetectResult>;

package/dist/checkout-engine/detect.js

@@ -0,0 +1,398 @@
+// Layered field detection. This is the success-rate core of the spike: given a
+// live page, work out which element is the card number, which is the expiry,
+// the cvc, the cardholder name, and the contact/shipping fields, with a
+// confidence and a provenance for each. Higher layers (explicit autocomplete
+// attributes) beat lower ones (raw type inference). Every candidate is kept so
+// the evidence log can show WHY a field was chosen.
+//
+// Layers, highest confidence first:
+//   1.0 autocomplete attributes (cc-number, cc-exp, cc-csc, ...)
+//   0.7 attribute regex bank over name/id/placeholder/aria-label + <select> shape
+//   0.6 associated <label> text
+//   0.5 PSP iframe fingerprints (Stripe/Braintree/Adyen) -> detect + report
+//   0.4 type inference (numeric inputmode/pattern + maxlength)
+export const ALL_ROLES = [
+    'number',
+    'expMonth',
+    'expYear',
+    'expCombined',
+    'cvc',
+    'name',
+    'nameFirst',
+    'nameLast',
+    'email',
+    'phone',
+    'oneTimeCode',
+    'addressLine1',
+    'addressLine2',
+    'city',
+    'state',
+    'postalCode',
+    'country',
+];
+// ---------------------------------------------------------------------------
+// Regex bank (layer 2 / 3)
+// ---------------------------------------------------------------------------
+const numberRe = /(card.?number|cardnumber|cardnum|card_num|ccnum|cc.?number|(^|[^a-z])pan([^a-z]|$)|kartennummer|numero.?(de.?)?(carte|tarjeta))/;
+const cvcRe = /(cvv|cvc|csc|cvn|security.?code|card.?code|card.?verif|pruef|prüf)/;
+const expMonthRe = /(exp.?month|expmonth|exp_mm|(^|[^a-z])mm([^a-z]|$)|(^|[^a-z])month([^a-z]|$)|monat|mois|(^|[^a-z])mes([^a-z]|$))/;
+const expYearRe = /(exp.?year|expyear|exp_yy|(^|[^a-z])yy(yy)?([^a-z]|$)|(^|[^a-z])year([^a-z]|$)|jahr|annee|(^|[^a-z])ano([^a-z]|$))/;
+const expCombinedRe = /(exp(iry|iration)?(.?date)?|mm.?\/.?yy|mm.?jj|valid.?thru|ablauf|caducidad)/;
+const emailRe = /(e-?mail|correo|courriel)/;
+const phoneRe = /(phone|telephone|mobile|(^|[^a-z])tel([^a-z]|$)|telefono|téléphone)/;
+// One-time verification code (merchant email/SMS OTP). Ordered AFTER cvcRe in
+// attrClassify so a card CVC ("security code"/"card code") still wins — this
+// regex deliberately omits those card phrasings. It also OMITS a bare "code":
+// `postal_code`/`zip_code`/`country_code`/`promo_code` all contain "code" and
+// would otherwise misclassify as an OTP field and starve the address fill. A
+// bare "code" is matched LAST (bareCodeRe), after every address role.
+const oneTimeCodeRe = /(one[-_ ]?time|(^|[^a-z])otp([^a-z]|$)|passcode|(^|[^a-z])pin([^a-z]|$)|verif(y|ication)?.?code|auth.?code)/;
+// Standalone verification "code" — a last-resort OTP match tried only after the
+// specific address roles (postal/country/state/city/line) have had their say,
+// so a compound `*_code` address/product field is never stolen by the OTP role.
+const bareCodeRe = /(^|[^a-z])code([^a-z]|$)/;
+const postalRe = /(zip|postal|postcode|(^|[^a-z])plz([^a-z]|$)|(^|[^a-z])cep([^a-z]|$)|codigo.?postal)/;
+const countryRe = /(country|(^|[^a-z])land([^a-z]|$)|(^|[^a-z])pais)/;
+const stateRe = /((^|[^a-z])state([^a-z]|$)|province|region|bundesland|provincia)/;
+const cityRe = /((^|[^a-z])city([^a-z]|$)|(^|[^a-z])town([^a-z]|$)|(^|[^a-z])ort([^a-z]|$)|ciudad|ville)/;
+const addr2Re = /(address.?2|addr.?2|line.?2|(^|[^a-z])apt|apartment|suite|(^|[^a-z])unit|zusatz)/;
+const addr1Re = /(address|street|(^|[^a-z])addr|strasse|stra.?e|adresse|direccion|(^|[^a-z])rue)/;
+const nameFirstRe = /(first.?name|(^|[^a-z])fname|given.?name|vorname|nombre|pr.?nom)/;
+const nameLastRe = /(last.?name|(^|[^a-z])lname|surname|family.?name|nachname|apellido)/;
+const nameRe = /(card.?holder|name.?on.?card|cardname|ccname|karteninhaber|titular|holder|(^|[^a-z])name([^a-z]|$)|(^|[^a-z])nom([^a-z]|$))/;
+const AUTOCOMPLETE_MAP = {
+    'cc-number': 'number',
+    'cc-exp': 'expCombined',
+    'cc-exp-month': 'expMonth',
+    'cc-exp-year': 'expYear',
+    'cc-csc': 'cvc',
+    'cc-name': 'name',
+    name: 'name',
+    email: 'email',
+    tel: 'phone',
+    'tel-national': 'phone',
+    'one-time-code': 'oneTimeCode',
+    'given-name': 'nameFirst',
+    'family-name': 'nameLast',
+    'address-line1': 'addressLine1',
+    'address-line2': 'addressLine2',
+    'address-level2': 'city',
+    'address-level1': 'state',
+    'postal-code': 'postalCode',
+    country: 'country',
+    'country-name': 'country',
+};
+// Real PSP iframe fingerprints. A match on any of these hosts is a real,
+// cross-origin PSP surface: for M0 we DETECT and report it (requiresAdapter)
+// but do not attempt to fill it. Same-origin test iframes never match these.
+const PSP_FINGERPRINTS = [
+    { name: 'stripe', re: /js\.stripe\.com|m\.stripe\.network/ },
+    { name: 'braintree', re: /braintree(gateway|-api)?\.com|assets\.braintreegateway\.com/ },
+    { name: 'adyen', re: /checkoutshopper|adyen\.com/ },
+];
+function fingerprintPsp(src) {
+    for (const f of PSP_FINGERPRINTS)
+        if (f.re.test(src))
+            return f.name;
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Classifier (pure — unit-testable without a browser)
+// ---------------------------------------------------------------------------
+function isMonthOptions(options) {
+    const vals = options.map((o) => o.value).filter((v) => v !== '');
+    const texts = options.map((o) => o.text.toLowerCase()).join(' ');
+    if (/jan|feb|mar|month/.test(texts) && vals.length >= 11)
+        return true;
+    if (vals.length >= 12 && vals.length <= 13) {
+        const nums = vals.filter((v) => /^\d{1,2}$/.test(v)).map((v) => Number(v));
+        if (nums.length >= 12 && nums.every((n) => n >= 1 && n <= 12))
+            return true;
+    }
+    return false;
+}
+function isYearOptions(options) {
+    const vals = options.map((o) => o.value).filter((v) => v !== '');
+    if (vals.length < 4 || vals.length > 30)
+        return false;
+    const four = vals.filter((v) => /^\d{4}$/.test(v)).map(Number);
+    if (four.length >= 4 && four.some((y) => y >= 2020 && y <= 2100))
+        return true;
+    const two = vals.filter((v) => /^\d{2}$/.test(v)).map(Number);
+    if (two.length === vals.length && two.some((n) => n > 12))
+        return true;
+    return false;
+}
+function looksLikeCountry(options) {
+    const texts = options.map((o) => o.text.toLowerCase()).join(' ');
+    if (/united states|canada|united kingdom|australia|germany/.test(texts))
+        return true;
+    const codes = options.map((o) => o.value).filter((v) => /^[A-Za-z]{2}$/.test(v));
+    return codes.length >= 5;
+}
+function attrClassify(text, m) {
+    if (m.tag === 'select') {
+        if (expMonthRe.test(text))
+            return 'expMonth';
+        if (expYearRe.test(text))
+            return 'expYear';
+        if (countryRe.test(text))
+            return 'country';
+        if (stateRe.test(text))
+            return 'state';
+        if (isMonthOptions(m.options))
+            return 'expMonth';
+        if (isYearOptions(m.options))
+            return 'expYear';
+        if (looksLikeCountry(m.options))
+            return 'country';
+        return null;
+    }
+    if (numberRe.test(text))
+        return 'number';
+    if (cvcRe.test(text))
+        return 'cvc';
+    // Expiry: a combined MM/YY field must not be mistaken for a month-only one.
+    // Explicit combined markers, or the presence of BOTH month and year tokens,
+    // win over a single-part match.
+    const explicitCombined = /(mm\s*[/\-]?\s*yy|mm.?jj|valid.?thru|ablauf|caducidad)/.test(text);
+    const hasMonth = expMonthRe.test(text);
+    const hasYear = expYearRe.test(text);
+    if (explicitCombined || (hasMonth && hasYear))
+        return 'expCombined';
+    if (hasMonth && !hasYear)
+        return 'expMonth';
+    if (hasYear && !hasMonth)
+        return 'expYear';
+    if (expCombinedRe.test(text))
+        return 'expCombined';
+    if (emailRe.test(text))
+        return 'email';
+    // OTP comes after cvc (checked above) so card CVC still classifies as 'cvc'.
+    if (oneTimeCodeRe.test(text))
+        return 'oneTimeCode';
+    if (phoneRe.test(text))
+        return 'phone';
+    if (postalRe.test(text))
+        return 'postalCode';
+    if (countryRe.test(text))
+        return 'country';
+    if (stateRe.test(text))
+        return 'state';
+    if (cityRe.test(text))
+        return 'city';
+    if (addr2Re.test(text))
+        return 'addressLine2';
+    if (addr1Re.test(text))
+        return 'addressLine1';
+    // Last-resort bare "code" → OTP, only once every address role has been ruled
+    // out, so `postal_code`/`country_code`/etc. keep their own role above.
+    if (bareCodeRe.test(text))
+        return 'oneTimeCode';
+    if (nameFirstRe.test(text))
+        return 'nameFirst';
+    if (nameLastRe.test(text))
+        return 'nameLast';
+    if (nameRe.test(text))
+        return 'name';
+    return null;
+}
+function fromAutocomplete(ac) {
+    if (!ac)
+        return null;
+    for (const tok of ac.split(/\s+/)) {
+        const role = AUTOCOMPLETE_MAP[tok];
+        if (role)
+            return { role, confidence: 1.0, source: 'autocomplete' };
+    }
+    return null;
+}
+function typeInfer(m) {
+    if (m.tag !== 'input')
+        return null;
+    const ml = Number.parseInt(m.maxlength || '0', 10);
+    const numeric = m.inputmode === 'numeric' ||
+        /\\d|\[0-9\]/.test(m.pattern) ||
+        m.type === 'tel' ||
+        m.type === 'number';
+    if (!numeric)
+        return null;
+    if (ml >= 15 && ml <= 19)
+        return 'number';
+    if (ml >= 3 && ml <= 4)
+        return 'cvc';
+    return null;
+}
+// Returns every layer match for an element. Exported for unit tests.
+export function classifyCandidate(m) {
+    const ac = fromAutocomplete(m.autocomplete);
+    if (ac)
+        return [ac];
+    const out = [];
+    const text = [m.name, m.id, m.placeholder, m.ariaLabel].join(' ').toLowerCase();
+    const attrRole = attrClassify(text, m);
+    if (attrRole)
+        out.push({ role: attrRole, confidence: 0.7, source: 'attr-heuristic' });
+    const labelRole = attrClassify(m.labelText, m);
+    if (labelRole)
+        out.push({ role: labelRole, confidence: 0.6, source: 'label-text' });
+    const inf = typeInfer(m);
+    if (inf)
+        out.push({ role: inf, confidence: 0.4, source: 'type-inference' });
+    return out;
+}
+function bestMatch(matches) {
+    let best = null;
+    for (const mm of matches)
+        if (!best || mm.confidence > best.confidence)
+            best = mm;
+    return best;
+}
+// ---------------------------------------------------------------------------
+// DOM extraction (one evaluate pass per frame; stamps a stable data-ca-id)
+// ---------------------------------------------------------------------------
+async function extractCandidateMeta(root) {
+    return root.evaluate(() => {
+        const SKIP = new Set([
+            'hidden',
+            'submit',
+            'button',
+            'reset',
+            'checkbox',
+            'radio',
+            'image',
+            'file',
+        ]);
+        const els = Array.from(document.querySelectorAll('input, select, textarea'));
+        const out = [];
+        let i = 0;
+        for (const el of els) {
+            const tag = el.tagName.toLowerCase();
+            const type = (el.getAttribute('type') || '').toLowerCase();
+            if (tag === 'input' && SKIP.has(type))
+                continue;
+            const idx = i++;
+            el.setAttribute('data-ca-id', String(idx));
+            let labelText = '';
+            const anyEl = el;
+            if (anyEl.labels)
+                labelText += Array.from(anyEl.labels)
+                    .map((l) => l.textContent || '')
+                    .join(' ');
+            const alb = el.getAttribute('aria-labelledby');
+            if (alb) {
+                labelText +=
+                    ' ' +
+                        alb
+                            .split(/\s+/)
+                            .map((id) => {
+                            const n = document.getElementById(id);
+                            return n ? n.textContent || '' : '';
+                        })
+                            .join(' ');
+            }
+            const wrap = el.closest('label');
+            if (wrap)
+                labelText += ' ' + (wrap.textContent || '');
+            const style = getComputedStyle(el);
+            const visible = el.offsetParent !== null &&
+                style.visibility !== 'hidden' &&
+                style.display !== 'none';
+            const options = tag === 'select'
+                ? Array.from(el.options).map((o) => ({
+                    value: o.value,
+                    text: (o.textContent || '').trim(),
+                }))
+                : [];
+            out.push({
+                idx,
+                tag,
+                type,
+                name: el.getAttribute('name') || '',
+                id: el.id || '',
+                placeholder: el.getAttribute('placeholder') || '',
+                ariaLabel: el.getAttribute('aria-label') || '',
+                autocomplete: (el.getAttribute('autocomplete') || '').toLowerCase(),
+                maxlength: el.getAttribute('maxlength') || '',
+                inputmode: (el.getAttribute('inputmode') || '').toLowerCase(),
+                pattern: el.getAttribute('pattern') || '',
+                labelText: labelText.trim().toLowerCase(),
+                options,
+                visible,
+            });
+        }
+        return out;
+    });
+}
+function toCandidate(m, frame) {
+    const matches = classifyCandidate(m);
+    const best = bestMatch(matches);
+    return {
+        role: best?.role ?? null,
+        confidence: best?.confidence ?? 0,
+        source: best?.source ?? null,
+        matches,
+        frame,
+        meta: m,
+    };
+}
+function buildFieldMap(candidates) {
+    const map = {};
+    for (const c of candidates) {
+        if (!c.role || !c.source)
+            continue;
+        const existing = map[c.role];
+        const better = !existing ||
+            c.confidence > existing.confidence ||
+            (c.confidence === existing.confidence && c.meta.visible && !existing.visible);
+        if (!better)
+            continue;
+        map[c.role] = {
+            locator: `[data-ca-id="${c.meta.idx}"]`,
+            confidence: c.confidence,
+            // The true provenance is kept even for in-frame candidates — the frame
+            // is carried separately in `frame`. 'iframe-psp' means a PSP
+            // fingerprint match, never "this field happened to be in a frame".
+            source: c.source,
+            frame: c.frame,
+            tag: c.meta.tag,
+            inputType: c.meta.type,
+            visible: c.meta.visible,
+            options: c.meta.options.length ? c.meta.options : undefined,
+            maxlength: c.meta.maxlength ? Number.parseInt(c.meta.maxlength, 10) : undefined,
+        };
+    }
+    return map;
+}
+export async function detectFields(page) {
+    const candidates = [];
+    const psps = [];
+    const mainMeta = await extractCandidateMeta(page);
+    for (const m of mainMeta)
+        candidates.push(toCandidate(m, undefined));
+    const frameEls = await page.$$('iframe');
+    for (let k = 0; k < frameEls.length; k++) {
+        const el = frameEls[k];
+        const src = (await el.getAttribute('src')) || '';
+        const frameSelector = `iframe[data-ca-frame="${k}"]`;
+        await el.evaluate((node, idx) => node.setAttribute('data-ca-frame', String(idx)), k);
+        const psp = fingerprintPsp(src);
+        if (psp) {
+            // Real, cross-origin PSP surface: detect + report, do not fill in M0.
+            psps.push({ psp, requiresAdapter: psp, frameSelector });
+            continue;
+        }
+        const frame = await el.contentFrame();
+        if (!frame)
+            continue;
+        try {
+            const meta = await extractCandidateMeta(frame);
+            for (const m of meta)
+                candidates.push(toCandidate(m, frameSelector));
+        }
+        catch {
+            // Frame not accessible; skip.
+        }
+    }
+    return { fields: buildFieldMap(candidates), candidates, psps };
+}

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

@@ -0,0 +1,25 @@
+export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'contact-prefill' | 'credential-minted' | 'credential-skipped' | 'credential-expiry-check' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
+export type EvidenceStep = {
+    ts: string;
+    type: EvidenceStepType;
+    data: Record<string, unknown>;
+};
+export declare function maskPan(pan: string): string;
+export declare function maskCvc(_cvc: string): string;
+export declare function maskExpiry(): string;
+export declare function maskOtp(): string;
+export declare function hostOf(hostOrEmail: string): string;
+export declare function verificationLinkAllowed(link: string, messageFrom: string): boolean;
+export declare function redactContact(role: string, value: string): string;
+export declare class EvidenceLog {
+    private steps;
+    private snapshotSummary;
+    step(type: EvidenceStepType, data?: Record<string, unknown>): void;
+    setSnapshotSummary(summary: string): void;
+    getSteps(): readonly EvidenceStep[];
+    toJSONL(): string;
+    toObject(): {
+        steps: EvidenceStep[];
+        snapshotSummary: string | null;
+    };
+}