@visa/cli 4.1.0-rc.9 → 4.1.0-rc.91

package/dist/checkout-engine/vgs-gateway/fetch-credential.mjs

@@ -0,0 +1,248 @@
+// ⚠️ RETIRED CLIENT-SECRET PATH — used ONLY by the local `pnpm fill:live` spike
+// (run-live-fill.ts) and the older pay.ts dev entrypoints, NOT by the shipped
+// pay_merchant CLI. The productionized CLI (cli-engine.ts) mints SERVER-SIDE via
+// a scoped mint token (vgs-gateway/server-mint-client.ts) and never holds
+// VGS_USERNAME/VGS_PASSWORD. This module (and its spike callers) are slated for
+// deletion in the Phase-1 follow-up; do NOT add new callers. The
+// no-client-vgs-secret gate keeps the shipped path clear of everything below.
+//
+// Real credential fetch — NO mocks. Calls the live VGS agentic gateway to mint a
+// fresh, intent-scoped payment credential (DPAN + expiry + the 3-digit DAVV) and
+// returns it in memory. Same VGS agentic wire calls as enrollment; this just
+// returns the FULL values (for the form-filler) instead of masking.
+//
+// Nothing here persists or logs the credential — it is returned to the caller
+// (fillCheckout), and must never be written to disk or passed through an
+// LLM/agent context.
+//
+// Requires env: VGS_USERNAME, VGS_PASSWORD (the VGS service-account client id/secret),
+// and either VGS_ENVIRONMENT=live (+ optional VGS_GATEWAY_URL) or sandbox.
+
+const TOKEN_URL = 'https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token'
+
+function gatewayBase(env = process.env) {
+  if (env.VGS_GATEWAY_URL) return env.VGS_GATEWAY_URL.replace(/\/$/, '')
+  return env.VGS_ENVIRONMENT === 'live'
+    ? 'https://gw-01-live.vgsapi.com'
+    : 'https://gw-01-sandbox.vgsapi.com'
+}
+
+async function mintOauthToken(env = process.env) {
+  const clientId = env.VGS_USERNAME
+  const clientSecret = env.VGS_PASSWORD
+  if (!clientId || !clientSecret) {
+    throw new Error('Set VGS_USERNAME and VGS_PASSWORD (the VGS service-account client id/secret).')
+  }
+  const body = new URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    grant_type: 'client_credentials',
+  })
+  const r = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  })
+  if (!r.ok) throw new Error(`VGS token grant failed (${r.status}).`)
+  return (await r.json()).access_token
+}
+
+async function postJsonApi(url, type, attributes, env = process.env) {
+  const token = await mintOauthToken(env)
+  const r = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/vnd.api+json',
+    },
+    body: JSON.stringify({ data: { ...(type ? { type } : {}), attributes } }),
+  })
+  const text = await r.text()
+  let doc = {}
+  try {
+    doc = JSON.parse(text)
+  } catch {
+    /* non-json error body */
+  }
+  // Support trace handles VGS asked for on the #5713 decline thread: trace_id
+  // keys the request on VGS's side, network_correlation_id on the Visa network
+  // side. Routing metadata only — never credential material — and logged even
+  // on error responses so any run stays traceable after the fact.
+  const obs = doc?.meta?.observability
+  if (obs && typeof obs === 'object') {
+    console.info(
+      JSON.stringify({
+        op: 'vgs_observability',
+        type,
+        status: r.status,
+        trace_id: obs.trace_id,
+        vault_id: obs.vault_id,
+        network_correlation_id: obs.network_correlation_id,
+      })
+    )
+  }
+  if (!r.ok) {
+    // Never echo the full body (can carry ids); surface status + a short detail.
+    const detail = doc?.errors?.[0]?.detail || doc?.errors?.[0]?.title || ''
+    throw new Error(`VGS ${type} POST failed (${r.status})${detail ? `: ${detail}` : ''}.`)
+  }
+  return doc
+}
+
+const txnData = (t) => [
+  {
+    merchant_name: t.merchantName,
+    merchant_url: t.merchantUrl,
+    merchant_country_code: t.merchantCountryCode,
+    transaction_amount: {
+      transaction_amount: t.transactionAmount,
+      transaction_currency_code: t.transactionCurrencyCode,
+    },
+  },
+]
+
+/**
+ * Create a fresh intent scoped to `transaction`, bound to the passkey assurance.
+ * Needs `assuranceData` from a device-binding passkey ceremony run for THIS
+ * purchase (merchant + amount + currency aligned) — replaying enrollment-time
+ * assurance mints an intent that 201s but whose cryptogram never completes
+ * (#5709, confirmed live 2026-07-17).
+ * @returns {Promise<{intentId: string, status: string | null}>} the fresh
+ * intent id plus the creation-time status attribute (null when VGS omits it) —
+ * callers surface the status when a later cryptogram fails, since HTTP 201
+ * alone does not mean the intent is authorized.
+ */
+export async function createIntent({ tokenId, assuranceData, transaction }, env = process.env) {
+  const effectiveUntil = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString()
+  const cap = Math.max(Math.ceil(Number(transaction.transactionAmount) || 0) + 10, 25)
+  const doc = await postJsonApi(
+    `${gatewayBase(env)}/agentic-tokens/${encodeURIComponent(tokenId)}/intents`,
+    'intents',
+    {
+      consumer_prompt: `Buy an item from ${transaction.merchantName} for ${transaction.transactionCurrencyCode} ${transaction.transactionAmount}`,
+      assurance_data: assuranceData,
+      mandates: [
+        {
+          description: `Purchase at ${transaction.merchantName}`,
+          decline_threshold: { amount: cap, currency_code: transaction.transactionCurrencyCode },
+          effective_until: effectiveUntil,
+          merchant_category: 'Retail',
+          merchant_category_code: '5999',
+          preferred_merchant_name: transaction.merchantName,
+          quantity: 1,
+        },
+      ],
+    },
+    env
+  )
+  const intentId = doc.data?.id
+  if (!intentId) throw new Error('createIntent: response missing data.id')
+  const status = doc.data?.attributes?.status
+  return { intentId, status: typeof status === 'string' && status ? status : null }
+}
+
+/**
+ * Mint the FULL payment credential for an existing intent. Real VGS call — the
+ * DAVV is single-use and expires in hours, so call this immediately before fill.
+ * @returns {Promise<{networkToken,expMonth,expYear,cryptogramType,cryptogramValue}>}
+ */
+export async function fetchCryptogram({ tokenId, intentId, transaction }, env = process.env) {
+  // Intent approval can be asynchronous on live: creation returns PENDING and
+  // the first cryptogram answer can be PENDING too (observed 2026-07-17,
+  // donate.stripe.com run). Poll briefly on PENDING only — every other
+  // non-COMPLETED status still fails fast on the first answer. Both knobs are
+  // env-tunable (and injectable for tests, which must not sleep wall-clock).
+  const PENDING_ATTEMPTS = Math.max(1, Number(env.VGS_CRYPTOGRAM_PENDING_ATTEMPTS) || 4)
+  const PENDING_WAIT_MS = Number.isFinite(Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS))
+    ? Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS)
+    : 5000
+  let a = {}
+  for (let attempt = 1; ; attempt++) {
+    const doc = await postJsonApi(
+      `${gatewayBase(env)}/agentic-tokens/${encodeURIComponent(tokenId)}/intents/${encodeURIComponent(intentId)}/cryptograms`,
+      'cryptograms',
+      { transaction_data: txnData(transaction) },
+      env
+    )
+    a = doc.data?.attributes ?? {}
+    const s = typeof a.status === 'string' ? a.status.toUpperCase() : ''
+    if (s !== 'PENDING' || attempt >= PENDING_ATTEMPTS) break
+    console.info(
+      JSON.stringify({ op: 'cryptogram_pending_retry', attempt, waitMs: PENDING_WAIT_MS })
+    )
+    await new Promise((resolve) => setTimeout(resolve, PENDING_WAIT_MS))
+  }
+  // A network_token can come back while the cryptogram is still pending/failed —
+  // mirror lib/server/vgs.ts and reject anything not COMPLETED, so we never key a
+  // not-yet-valid credential (which would decline and read as a fill bug).
+  const status = a.status
+  if (typeof status === 'string' && status && status.toUpperCase() !== 'COMPLETED') {
+    throw new Error(`cryptogram not completed (status ${status})`)
+  }
+  const networkToken = a.network_token
+  const value = a.cryptogram?.value
+  if (typeof networkToken !== 'string' || !networkToken) {
+    throw new Error('cryptogram response missing network_token')
+  }
+  if (typeof value !== 'string' || !value) {
+    throw new Error('cryptogram response missing cryptogram value')
+  }
+  return {
+    networkToken,
+    expMonth: typeof a.exp_month === 'number' ? a.exp_month : Number(a.exp_month) || 0,
+    expYear: typeof a.exp_year === 'number' ? a.exp_year : Number(a.exp_year) || 0,
+    cryptogramType: a.cryptogram?.type ?? '',
+    cryptogramValue: value,
+    cryptogramExpiresAt:
+      typeof a.cryptogram?.expires_at === 'string' ? a.cryptogram.expires_at : undefined,
+  }
+}
+
+/**
+ * Full path: create the intent (needs fresh passkey assurance) then mint the
+ * credential. Use fetchCryptogram directly if you already have an intentId.
+ */
+export async function getCredential({ tokenId, assuranceData, transaction }, env = process.env) {
+  const { intentId, status } = await createIntent({ tokenId, assuranceData, transaction }, env)
+  try {
+    return await fetchCryptogram({ tokenId, intentId, transaction }, env)
+  } catch (err) {
+    // HTTP 201 on intent creation does not mean the intent was authorized —
+    // surface its creation-time status so a not-completed cryptogram is
+    // diagnosable (#5709) instead of an opaque failure.
+    throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`)
+  }
+}
+
+/**
+ * Report the observed merchant outcome back to VIC for a consumed intent.
+ * Mirrors lib/server/vgs.ts postConfirmation exactly: same endpoint, same
+ * JSON:API envelope, and the guide's quoted Unix-epoch-seconds timestamp
+ * (callers pass ISO 8601; converted here).
+ */
+export async function postConfirmation(
+  { tokenId, intentId, transactionStatus, transactionType, transactionTimestamp, transaction },
+  env = process.env
+) {
+  await postJsonApi(
+    `${gatewayBase(env)}/agentic-tokens/${encodeURIComponent(tokenId)}/intents/${encodeURIComponent(intentId)}/confirmations`,
+    'confirmations',
+    {
+      confirmation_data: [
+        {
+          payment_confirmation_data: {
+            transaction_status: transactionStatus,
+            transaction_type: transactionType,
+            transaction_timestamp: String(Math.floor(Date.parse(transactionTimestamp) / 1000)),
+            transaction_amount: {
+              transaction_amount: transaction.transactionAmount,
+              transaction_currency_code: transaction.transactionCurrencyCode,
+            },
+          },
+        },
+      ],
+    },
+    env
+  )
+  return { ok: true }
+}

package/dist/checkout-engine/vgs-gateway/server-mint-client.d.ts

@@ -0,0 +1,82 @@
+import type { VgsCheckoutTarget, VgsPaymentCredential } from '../vgs-live-instrument.js';
+export type ServerMintDeps = {
+    /** Injectable for tests — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export declare function merchantOrigin(url: string): string;
+/**
+ * Optional mandate override for serverCreateIntent. Absent → the historical
+ * 1:1 fresh-tap shape is preserved byte-for-byte (cap = ceil(amount)+10 min 25,
+ * quantity 1, 30-day window). Present → the card-mandate (budget) layer sets a
+ * CEILING decline threshold and a multi-draw quantity so one passkey approves a
+ * spend ceiling and later draws pull cryptograms under it without a fresh tap.
+ * Whether the network honors a ceiling-scoped assurance across multiple
+ * sub-amount draws is UNPROVEN — see packages/checkout-engine/src/mandate/.
+ */
+export type ServerIntentMandateOverride = {
+    /** Wire decline-threshold amount (major-unit decimal string), e.g. "500.00". */
+    declineThresholdAmount?: string;
+    /** Number of draws the intent may fulfil (VGS mandate `quantity`). */
+    quantity?: number;
+    /** ISO 8601 mandate validity end. */
+    effectiveUntil?: string;
+    /** Human-readable consumer prompt describing the ceiling grant. */
+    consumerPrompt?: string;
+};
+/**
+ * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
+ * credential and calls the gateway; we send the same mandate shape the local
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
+ */
+export declare function serverCreateIntent(base: string, mintToken: string, input: {
+    tokenId: string;
+    assuranceData: unknown;
+    transaction: VgsCheckoutTarget;
+    mandate?: ServerIntentMandateOverride;
+}, deps?: ServerMintDeps): Promise<{
+    intentId: string;
+    status: string | null;
+}>;
+/**
+ * Mint the FULL payment credential via POST {base}/api/vgs/payment-cryptogram.
+ * The server's route does a SINGLE gateway call and 502s on a not-COMPLETED
+ * (e.g. PENDING) cryptogram, but live intent approval is asynchronous and the
+ * first cryptogram answer can be PENDING (#5709). So we retry the route on any
+ * non-2xx up to PENDING_ATTEMPTS, matching fetch-credential.mjs's cadence
+ * exactly — a genuinely hard failure just surfaces after the same bounded wait.
+ * Re-POSTing for the same intentId is idempotent (mirrors the old client loop).
+ */
+export declare function serverFetchCryptogram(base: string, mintToken: string, input: {
+    tokenId: string;
+    intentId: string;
+    transaction: VgsCheckoutTarget;
+}, deps?: ServerMintDeps): Promise<VgsPaymentCredential>;
+/** Report the observed merchant outcome via POST {base}/api/vgs/confirmation. */
+export declare function serverPostConfirmation(base: string, mintToken: string, input: {
+    tokenId: string;
+    intentId: string;
+    transactionStatus: string;
+    transactionType: string;
+    transactionTimestamp: string;
+    transaction: {
+        transactionAmount: string;
+        transactionCurrencyCode: string;
+    };
+}, deps?: ServerMintDeps): Promise<{
+    ok: true;
+}>;

package/dist/checkout-engine/vgs-gateway/server-mint-client.js

@@ -0,0 +1,180 @@
+// Server-side mint client (Phase 1) — the checkout runner mints the payment
+// credential by calling the verify-web deployment's gateway routes with a
+// short-lived, purpose-scoped MINT TOKEN, instead of holding the shared VGS
+// service-account secret (the gateway client id/secret) on the machine.
+//
+// The mint token is issued at approval time (agent-approval/complete, which is
+// session + internal-tester + token-ownership gated) and released to this
+// runner by the claim leg. It is bound to the exact approved purchase, so these
+// calls can only mint the credential the human approved.
+//
+// Request derivation here mirrors ../fetch-credential.mjs EXACTLY (mandate cap,
+// consumer prompt, PENDING retry cadence) — the only change is the transport:
+// verify-web routes + Bearer mint token, never the VGS gateway + VGS secret.
+import { traceHandleFields } from '../trace-handles.js';
+const defaultSleep = (ms) => new Promise((r) => {
+    const t = setTimeout(r, ms);
+    t.unref?.();
+});
+function stripTrailingSlashes(value) {
+    let out = value;
+    while (out.endsWith('/'))
+        out = out.slice(0, -1);
+    return out;
+}
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export function merchantOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+/** Read a stable, non-secret error message from a route's JSON body. */
+async function routeError(res) {
+    const doc = (await res.json().catch(() => null));
+    return doc?.error || doc?.error_code || `HTTP ${res.status}`;
+}
+function bearer(mintToken) {
+    return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
+}
+/**
+ * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
+ * credential and calls the gateway; we send the same mandate shape the local
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
+ */
+export async function serverCreateIntent(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const { tokenId, assuranceData, transaction: t } = input;
+    const override = input.mandate ?? {};
+    const defaultCap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const declineThresholdAmount = override.declineThresholdAmount ?? String(defaultCap);
+    const quantity = override.quantity ?? 1;
+    const effectiveUntil = override.effectiveUntil ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+    const consumerPrompt = override.consumerPrompt ??
+        `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`;
+    const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
+        method: 'POST',
+        headers: bearer(mintToken),
+        body: JSON.stringify({
+            tokenId,
+            consumerPrompt,
+            assuranceData,
+            mandates: [
+                {
+                    description: `Purchase at ${t.merchantName}`,
+                    declineThresholdAmount,
+                    declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
+                    effectiveUntil,
+                    merchantCategory: 'Retail',
+                    merchantCategoryCode: '5999',
+                    preferredMerchantName: t.merchantName,
+                    quantity,
+                },
+            ],
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`server intent failed (${res.status}): ${await routeError(res)}`);
+    const doc = (await res.json().catch(() => null));
+    if (!doc?.intentId)
+        throw new Error('server intent response missing intentId');
+    return { intentId: doc.intentId, status: typeof doc.status === 'string' ? doc.status : null };
+}
+/**
+ * Mint the FULL payment credential via POST {base}/api/vgs/payment-cryptogram.
+ * The server's route does a SINGLE gateway call and 502s on a not-COMPLETED
+ * (e.g. PENDING) cryptogram, but live intent approval is asynchronous and the
+ * first cryptogram answer can be PENDING (#5709). So we retry the route on any
+ * non-2xx up to PENDING_ATTEMPTS, matching fetch-credential.mjs's cadence
+ * exactly — a genuinely hard failure just surfaces after the same bounded wait.
+ * Re-POSTing for the same intentId is idempotent (mirrors the old client loop).
+ */
+export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleep ?? defaultSleep;
+    const env = deps.env ?? process.env;
+    const attempts = Math.max(1, Number(env.VGS_CRYPTOGRAM_PENDING_ATTEMPTS) || 4);
+    const waitMs = Number.isFinite(Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS))
+        ? Number(env.VGS_CRYPTOGRAM_PENDING_WAIT_MS)
+        : 5000;
+    const { tokenId, intentId, transaction: t } = input;
+    const body = JSON.stringify({
+        tokenId,
+        intentId,
+        transaction: {
+            merchantName: t.merchantName,
+            // Send the merchant ORIGIN, not the full (possibly huge) checkout URL — an
+            // oversized merchantUrl makes the downstream cryptogram mint 502 (proven live).
+            merchantUrl: merchantOrigin(t.merchantUrl),
+            merchantCountryCode: t.merchantCountryCode,
+            transactionAmount: t.transactionAmount,
+            transactionCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
+        },
+    });
+    let lastError = 'unknown';
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/payment-cryptogram`, {
+            method: 'POST',
+            headers: bearer(mintToken),
+            body,
+        });
+        if (res.ok) {
+            const c = (await res.json().catch(() => null));
+            if (!c || typeof c.networkToken !== 'string' || typeof c.cryptogramValue !== 'string') {
+                throw new Error('server cryptogram response missing credential fields');
+            }
+            return {
+                networkToken: c.networkToken,
+                expMonth: Number(c.expMonth) || 0,
+                expYear: Number(c.expYear) || 0,
+                cryptogramType: c.cryptogramType ?? '',
+                cryptogramValue: c.cryptogramValue,
+                ...(typeof c.cryptogramExpiresAt === 'string'
+                    ? { cryptogramExpiresAt: c.cryptogramExpiresAt }
+                    : {}),
+                ...traceHandleFields(c),
+            };
+        }
+        // A 4xx (bad request / binding refusal / auth) is terminal — never retry it.
+        if (res.status >= 400 && res.status < 500) {
+            throw new Error(`server cryptogram refused (${res.status}): ${await routeError(res)}`);
+        }
+        lastError = `${res.status}: ${await routeError(res)}`;
+        if (attempt < attempts)
+            await sleep(waitMs);
+    }
+    throw new Error(`server cryptogram not completed after ${attempts} attempts (last: ${lastError})`);
+}
+/** Report the observed merchant outcome via POST {base}/api/vgs/confirmation. */
+export async function serverPostConfirmation(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/confirmation`, {
+        method: 'POST',
+        headers: bearer(mintToken),
+        body: JSON.stringify({
+            tokenId: input.tokenId,
+            intentId: input.intentId,
+            transactionStatus: input.transactionStatus,
+            transactionType: input.transactionType,
+            transactionTimestamp: input.transactionTimestamp,
+            transactionAmount: input.transaction.transactionAmount,
+            transactionCurrencyCode: input.transaction.transactionCurrencyCode.toUpperCase(),
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`server confirmation failed (${res.status}): ${await routeError(res)}`);
+    return { ok: true };
+}