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

package/dist/checkout-engine/vgs-live-instrument.js

@@ -0,0 +1,293 @@
+import { traceHandleFields } from './trace-handles.js';
+/**
+ * Our fail-closed freshness bound, matching the runner's 15-minute checkout
+ * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
+ * The only proven-working configuration mints the intent right after the
+ * ceremony; anything older is refused before an intent is created.
+ */
+export const PURCHASE_ASSURANCE_MAX_AGE_MS = 15 * 60 * 1000;
+/** Tolerated forward clock skew on `mintedAt` before it is treated as invalid. */
+const PURCHASE_ASSURANCE_MAX_SKEW_MS = 2 * 60 * 1000;
+export function decimalToMinor(value) {
+    // JSON files routinely carry a number where the contract says decimal string
+    // ("transactionAmount": 5): refuse non-strings HERE so every caller surfaces
+    // its scoped invalid/mismatch remedy instead of a raw TypeError crash.
+    if (typeof value !== 'string')
+        return null;
+    if (!/^\d+(\.\d{1,2})?$/.test(value))
+        return null;
+    const [whole, fraction = ''] = value.split('.');
+    const minor = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));
+    return Number.isSafeInteger(minor) ? minor : null;
+}
+/**
+ * Currencies whose minor unit is 1/100 of the major unit (2 decimal places).
+ * minorToDecimal's /100 + pad-to-2 rendering is ONLY correct for these. The
+ * card mandate path accepts any 3-letter ISO code, so a 0- or 3-decimal
+ * currency (JPY, BHD, …) would otherwise be emitted with a wrong wire amount.
+ * We only support USD/USDC today; extend deliberately (and fix the exponent)
+ * before adding any non-2-decimal currency.
+ *
+ * NOTE (scanner FP pre-empt): this is a CLIENT-SIDE currency-exponent lookup for
+ * rendering a wire amount in @visa/checkout-engine — it is NOT the cross-store
+ * `PAYMENT_CURRENCIES` enum governed by apps/auth/src/shared-validators.ts, and
+ * this package cannot import from apps/auth (no dependency edge). It intentionally
+ * does not mirror that enum's membership; do not "reconcile" the two.
+ */
+export const TWO_DECIMAL_CURRENCIES = new Set(['USD', 'USDC']);
+/**
+ * Inverse of decimalToMinor: render integer minor units as a major-unit decimal
+ * string ("D.DD") for the VGS wire (e.g. a ceiling of 50000 minor → "500.00").
+ * Integer-only; never floating-point money. Throws on a non-integer/negative so
+ * a bad accounting value cannot silently reach the network.
+ *
+ * The /100 + pad-to-2 rendering assumes a 2-decimal (exponent-2) currency. Pass
+ * `currencyCode` on any path that accepts arbitrary currencies (the mandate
+ * path) and it REFUSES a non-2-decimal currency rather than emit a wrong wire
+ * amount. Omit it only where the currency is already known to be USD/USDC.
+ */
+export function minorToDecimal(minor, currencyCode) {
+    if (!Number.isSafeInteger(minor) || minor < 0) {
+        throw new Error('minor units must be a non-negative safe integer');
+    }
+    if (currencyCode !== undefined && !TWO_DECIMAL_CURRENCIES.has(currencyCode.toUpperCase())) {
+        throw new Error(`minorToDecimal only supports 2-decimal currencies (${[...TWO_DECIMAL_CURRENCIES].join('/')}); refusing to emit a wire amount for ${currencyCode}`);
+    }
+    const whole = Math.floor(minor / 100);
+    const fraction = minor % 100;
+    return `${whole}.${String(fraction).padStart(2, '0')}`;
+}
+function validateTarget(reference, ctx) {
+    if (typeof reference.merchantName !== 'string' ||
+        typeof reference.merchantCountryCode !== 'string' ||
+        !reference.merchantName.trim() ||
+        !/^[A-Z]{2}$/.test(reference.merchantCountryCode)) {
+        throw new Error('VGS checkout reference merchant name/country is invalid');
+    }
+    let referenceHost;
+    try {
+        referenceHost = new URL(reference.merchantUrl).hostname;
+    }
+    catch {
+        throw new Error('VGS checkout reference merchant URL is invalid');
+    }
+    if (referenceHost !== ctx.merchantHost) {
+        throw new Error(`VGS credential merchant mismatch: ${referenceHost} vs ${ctx.merchantHost}`);
+    }
+    const amountMinor = decimalToMinor(reference.transactionAmount);
+    if (amountMinor === null)
+        throw new Error('VGS checkout reference amount is invalid');
+    if (amountMinor !== ctx.amountMinor) {
+        throw new Error(`VGS credential amount mismatch: ${amountMinor} vs ${ctx.amountMinor} minor units`);
+    }
+    // String() so a JSON-number currency (840) mismatches with a readable
+    // message instead of crashing on .toUpperCase().
+    const currency = String(reference.transactionCurrencyCode).toUpperCase();
+    if (currency !== ctx.currency) {
+        throw new Error(`VGS credential currency mismatch: ${currency} vs ${ctx.currency}`);
+    }
+}
+function validateCliCredential(value) {
+    if (typeof value.tokenId !== 'string' || !value.tokenId.trim()) {
+        throw new Error('CLI agent credential requires tokenId');
+    }
+    // Deliberately no assuranceData requirement: the artifact's enrollment-time
+    // assurance is identity/enrollment material and is never read here (#5709).
+}
+/**
+ * Refuse to mint an intent unless the assurance is fresh and its declared
+ * scope matches the checkout target exactly. `now` is injectable so the
+ * freshness rules are testable with a pinned clock (same pattern as
+ * validateCredential).
+ */
+export function validatePurchaseAssurance(value, target, now = new Date()) {
+    const remedy = 'run a fresh device-binding ceremony scoped to this exact merchant, amount, and ' +
+        'currency, and pass its output via --purchase-assurance-file (#5709)';
+    if (value == null || typeof value !== 'object') {
+        throw new Error(`purchase assurance is missing — ${remedy}`);
+    }
+    if (value.assuranceData == null) {
+        throw new Error(`purchase assurance requires assuranceData — ${remedy}`);
+    }
+    const mintedAtMs = typeof value.mintedAt === 'string' ? Date.parse(value.mintedAt) : NaN;
+    if (!Number.isFinite(mintedAtMs)) {
+        throw new Error(`purchase assurance requires an ISO 8601 mintedAt — ${remedy}`);
+    }
+    const age = now.getTime() - mintedAtMs;
+    if (age < -PURCHASE_ASSURANCE_MAX_SKEW_MS) {
+        throw new Error(`purchase assurance mintedAt is in the future — ${remedy}`);
+    }
+    if (age > PURCHASE_ASSURANCE_MAX_AGE_MS) {
+        throw new Error(`purchase assurance is stale (minted ${value.mintedAt}, limit ` +
+            `${PURCHASE_ASSURANCE_MAX_AGE_MS / 60000} minutes) — ${remedy}`);
+    }
+    let targetHost;
+    try {
+        targetHost = new URL(target.merchantUrl).hostname;
+    }
+    catch {
+        throw new Error('VGS checkout reference merchant URL is invalid');
+    }
+    if (value.merchantHost !== targetHost) {
+        throw new Error(`purchase assurance merchant mismatch: ${value.merchantHost} vs ${targetHost} — ${remedy}`);
+    }
+    const assuranceMinor = decimalToMinor(value.transactionAmount);
+    const targetMinor = decimalToMinor(target.transactionAmount);
+    if (assuranceMinor === null || assuranceMinor !== targetMinor) {
+        throw new Error(`purchase assurance amount mismatch: ${value.transactionAmount} vs ` +
+            `${target.transactionAmount} — ${remedy}`);
+    }
+    if (typeof value.transactionCurrencyCode !== 'string' ||
+        value.transactionCurrencyCode.toUpperCase() !==
+            String(target.transactionCurrencyCode).toUpperCase()) {
+        throw new Error(`purchase assurance currency mismatch: ${value.transactionCurrencyCode} vs ` +
+            `${target.transactionCurrencyCode} — ${remedy}`);
+    }
+}
+// `now` is injectable so expiry rules are testable with a pinned clock.
+export function validateCredential(value, now = new Date()) {
+    if (!/^\d{12,19}$/.test(value.networkToken)) {
+        throw new Error('VGS credential network token must contain 12-19 digits');
+    }
+    if (!/^\d{3,4}$/.test(value.cryptogramValue)) {
+        throw new Error('VGS credential short DAVV must contain 3-4 digits');
+    }
+    if (typeof value.cryptogramType !== 'string' || value.cryptogramType.toUpperCase() !== 'DAVV') {
+        throw new Error(`VGS credential type ${value.cryptogramType || '<missing>'} is not DAVV`);
+    }
+    if (!Number.isInteger(value.expMonth) || value.expMonth < 1 || value.expMonth > 12) {
+        throw new Error('VGS credential expiration month is invalid');
+    }
+    if (!Number.isInteger(value.expYear) ||
+        value.expYear < now.getFullYear() ||
+        (value.expYear === now.getFullYear() && value.expMonth < now.getMonth() + 1)) {
+        throw new Error('VGS credential is expired');
+    }
+    if (value.cryptogramExpiresAt === undefined) {
+        throw new Error('VGS credential expiry is missing');
+    }
+    const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
+    if (!Number.isFinite(expiresAtMs))
+        throw new Error('VGS credential expiry is invalid');
+    if (expiresAtMs - now.getTime() < 60_000) {
+        throw new Error('VGS credential has less than 60 seconds of validity remaining');
+    }
+}
+/**
+ * Mints the full DPAN + short DAVV only after the executor revalidates the
+ * reviewed merchant, amount, and currency. The payment credential remains in
+ * memory, is never returned to the caller, and can be requested only once.
+ */
+export class VgsLiveInstrument {
+    reference;
+    cardholderName;
+    fetchCredential;
+    kind = 'agentic-token';
+    used = false;
+    minted = null;
+    constructor(reference, cardholderName, fetchCredential) {
+        this.reference = reference;
+        this.cardholderName = cardholderName;
+        this.fetchCredential = fetchCredential;
+    }
+    /**
+     * Non-null once VGS has actually issued a credential (the intent is consumed
+     * from that moment, even if local validation later rejects the credential) —
+     * exactly the population a VIC confirmation can be owed for.
+     */
+    confirmationTarget() {
+        return this.minted;
+    }
+    async getCredential(ctx) {
+        if (this.used)
+            throw new Error('VGS live credential instrument is single-use');
+        this.used = true;
+        validateTarget(this.reference, ctx);
+        if (!this.reference.tokenId || !this.reference.intentId) {
+            throw new Error('VGS checkout reference requires tokenId and intentId');
+        }
+        if (!this.cardholderName.trim())
+            throw new Error('cardholder name is required');
+        const { tokenId, intentId, ...transaction } = this.reference;
+        const value = await this.fetchCredential({ tokenId, intentId, transaction });
+        this.minted = { tokenId, intentId };
+        try {
+            validateCredential(value);
+        }
+        catch (err) {
+            // VGS already issued a cryptogram for this intent even though we refuse
+            // to fill it; "correct inputs and retry" would silently reuse a consumed
+            // intent, so steer the operator to a fresh one.
+            throw new Error(`${err.message} — a credential was issued by VGS but rejected locally; obtain a fresh intent before retrying`);
+        }
+        return {
+            pan: value.networkToken,
+            expMonth: value.expMonth,
+            expYear: value.expYear,
+            cvc: value.cryptogramValue,
+            cardholderName: this.cardholderName.trim(),
+            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
+            ...traceHandleFields(value),
+        };
+    }
+}
+/**
+ * Consumes #5614's claimed CLI enrollment artifact (for the tokenId) plus a
+ * FRESH purchase-scoped assurance, and creates a fresh, transaction-scoped VIC
+ * intent + credential after checkout approval. This is the production-shaped
+ * bridge; unlike VgsLiveInstrument it never needs a pre-created intent ID.
+ *
+ * The enrollment artifact's stored assuranceData is deliberately never sent:
+ * replaying it makes intent creation succeed (HTTP 201) while the cryptogram
+ * deterministically never completes — the #5709 dead end. Purchase
+ * authorization is the fresh, merchant+amount+currency-scoped assurance,
+ * validated against the checkout target BEFORE any intent is minted so a
+ * doomed intent is never created.
+ */
+export class VgsAssuranceInstrument {
+    enrollment;
+    purchase;
+    target;
+    cardholderName;
+    mintCredential;
+    kind = 'agentic-token';
+    used = false;
+    minted = null;
+    constructor(enrollment, purchase, target, cardholderName, mintCredential) {
+        this.enrollment = enrollment;
+        this.purchase = purchase;
+        this.target = target;
+        this.cardholderName = cardholderName;
+        this.mintCredential = mintCredential;
+    }
+    /** See VgsLiveInstrument.confirmationTarget — same contract. */
+    confirmationTarget() {
+        return this.minted;
+    }
+    async getCredential(ctx) {
+        if (this.used)
+            throw new Error('VGS assurance instrument is single-use');
+        this.used = true;
+        validateCliCredential(this.enrollment);
+        validateTarget(this.target, ctx);
+        validatePurchaseAssurance(this.purchase, this.target);
+        if (!this.cardholderName.trim())
+            throw new Error('cardholder name is required');
+        const { payment: value, intentId } = await this.mintCredential({
+            tokenId: this.enrollment.tokenId,
+            assuranceData: this.purchase.assuranceData,
+            transaction: this.target,
+        });
+        this.minted = { tokenId: this.enrollment.tokenId, intentId };
+        validateCredential(value);
+        return {
+            pan: value.networkToken,
+            expMonth: value.expMonth,
+            expYear: value.expYear,
+            cvc: value.cryptogramValue,
+            cardholderName: this.cardholderName.trim(),
+            ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
+            ...traceHandleFields(value),
+        };
+    }
+}

package/dist/checkout-engine/vic-confirmation.d.ts

@@ -0,0 +1,34 @@
+import type { CheckoutOutcome } from './executor.js';
+import type { VicConfirmationTarget } from './vgs-live-instrument.js';
+export type VicTransactionStatus = 'APPROVED' | 'DECLINED';
+export type PostVicConfirmation = (input: {
+    tokenId: string;
+    intentId: string;
+    transactionStatus: VicTransactionStatus;
+    transactionType: 'PURCHASE';
+    transactionTimestamp: string;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+}) => Promise<unknown>;
+export type VicConfirmationReport = {
+    posted: true;
+    transactionStatus: VicTransactionStatus;
+} | {
+    posted: false;
+    reason: string;
+};
+/** Definitive merchant answers map to a status; everything else maps to none. */
+export declare function outcomeToTransactionStatus(outcome: CheckoutOutcome): VicTransactionStatus | null;
+export declare function reportVicOutcome(input: {
+    target: VicConfirmationTarget | null;
+    outcome: CheckoutOutcome;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+    post: PostVicConfirmation;
+    /** Injectable for tests; defaults to now. */
+    timestamp?: Date;
+}): Promise<VicConfirmationReport>;

package/dist/checkout-engine/vic-confirmation.js

@@ -0,0 +1,39 @@
+/** Definitive merchant answers map to a status; everything else maps to none. */
+export function outcomeToTransactionStatus(outcome) {
+    if (outcome === 'confirmed')
+        return 'APPROVED';
+    if (outcome === 'declined')
+        return 'DECLINED';
+    return null;
+}
+export async function reportVicOutcome(input) {
+    const transactionStatus = outcomeToTransactionStatus(input.outcome);
+    if (!transactionStatus) {
+        return {
+            posted: false,
+            reason: `outcome '${input.outcome}' is not a definitive merchant answer — ` +
+                'resolve it with the merchant, then post the confirmation manually',
+        };
+    }
+    if (!input.target) {
+        return { posted: false, reason: 'no VIC credential was minted in this run' };
+    }
+    try {
+        await input.post({
+            tokenId: input.target.tokenId,
+            intentId: input.target.intentId,
+            transactionStatus,
+            transactionType: 'PURCHASE',
+            transactionTimestamp: (input.timestamp ?? new Date()).toISOString(),
+            transaction: input.transaction,
+        });
+        return { posted: true, transactionStatus };
+    }
+    catch (err) {
+        return {
+            posted: false,
+            reason: `confirmation POST failed: ${err.message} — the merchant-reported outcome ` +
+                'remains unverified; retry the confirmation for this intent out-of-band',
+        };
+    }
+}