@visa/cli 4.1.0-rc.14 → 4.1.0-rc.16

package/dist/checkout-engine/cli-engine.js

@@ -1,8 +1,8 @@
 // createCliCheckoutEngine — the review()/pay() adapter consumed by @visa/cli's
-// pay_merchant tool. It COMPOSES the same primitives the `pnpm fill:live` runner
-// uses (prepareCheckout, runHostedApproval, the createIntent/fetchCryptogram
-// mint, submitApprovedCheckout, reportVicOutcome, receipts) into a two-call API,
-// WITHOUT touching run-live-fill.ts — so the proven CLI flow keeps working.
+// pay_merchant tool. It COMPOSES prepareCheckout, runHostedApproval, the
+// server-side mint (serverCreateIntent/serverFetchCryptogram — the credential is
+// minted by the verify-web deployment, not this machine), submitApprovedCheckout,
+// reportVicOutcome, and receipts into a two-call API.
 //
 // A live browser + prepared-checkout session is held in-process between review
 // and pay, keyed by reviewId, so the submitted checkout is the exact one the
@@ -17,7 +17,7 @@ import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { VgsAssuranceInstrument, decimalToMinor, } from './vgs-live-instrument.js';
-import { createIntent, fetchCryptogram, postConfirmation } from './vgs-gateway/fetch-credential.mjs';
+import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
 import { buildReceipt, writeReceipt as realWriteReceipt } from './receipt.js';
 import { reportVicOutcome as realReportVicOutcome, } from './vic-confirmation.js';
 const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');
@@ -152,10 +152,27 @@ export function createCliCheckoutEngine(deps = {}) {
                     target: session.target,
                     consumerEmail: session.contact.email,
                 });
+                // Server-side mint (Phase 1): the approval claim releases a scoped mint
+                // token; the credential is minted by the verify-web deployment (which
+                // holds the VGS secret), never on this machine. No token means the
+                // deployment ran the dev-auth stub — refuse loudly rather than reach for
+                // a client-held secret (there is none anymore).
+                const approvalBase = input.approvalBaseUrl;
+                const mintToken = assurance.mintToken;
+                if (!mintToken) {
+                    return {
+                        outcome: 'failed',
+                        confirmationRef: null,
+                        receiptPath: null,
+                        detail: 'the approval server issued no mint token — server-side minting requires the ' +
+                            'verify-web deployment to run real/turnkey auth (not the dev stub). Retry once it does.',
+                        vicConfirmation: null,
+                    };
+                }
                 const instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
-                    const { intentId, status } = await createIntent(mintInput);
+                    const { intentId, status } = await serverCreateIntent(approvalBase, mintToken, mintInput);
                     try {
-                        const payment = await fetchCryptogram({
+                        const payment = await serverFetchCryptogram(approvalBase, mintToken, {
                             tokenId: mintInput.tokenId,
                             intentId,
                             transaction: mintInput.transaction,
@@ -185,7 +202,7 @@ export function createCliCheckoutEngine(deps = {}) {
                             transactionAmount: session.target.transactionAmount,
                             transactionCurrencyCode: session.currency,
                         },
-                        post: postConfirmation,
+                        post: (confInput) => serverPostConfirmation(approvalBase, mintToken, confInput),
                     });
                 }
                 let receiptPath = null;

package/dist/checkout-engine/hosted-approval.d.ts

@@ -66,4 +66,13 @@ export declare function resolveApprovalBaseUrl(flagValue: string | undefined, en
  * assurance), so a cleartext remote origin is never acceptable.
  */
 export declare function assertApprovalBaseUrl(value: string): string;
-export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance>;
+/**
+ * The claim also releases the scoped MINT TOKEN (server-side mint, Phase 1) —
+ * bound to this exact approved purchase — so the runner can call the gateway
+ * mint routes without the VGS secret. Absent when the deployment ran the
+ * dev-auth stub (it mints no token); the caller then surfaces a clear error
+ * rather than falling back to a client-held secret.
+ */
+export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance & {
+    mintToken?: string;
+}>;

package/dist/checkout-engine/hosted-approval.js

@@ -56,6 +56,13 @@ function stripTrailingSlashes(value) {
         out = out.slice(0, -1);
     return out;
 }
+/**
+ * The claim also releases the scoped MINT TOKEN (server-side mint, Phase 1) —
+ * bound to this exact approved purchase — so the runner can call the gateway
+ * mint routes without the VGS secret. Absent when the deployment ran the
+ * dev-auth stub (it mints no token); the caller then surfaces a clear error
+ * rather than falling back to a client-held secret.
+ */
 export async function runHostedApproval(opts) {
     const { baseUrl, tokenId, target, consumerEmail, log = () => { }, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, timeoutMs = HOSTED_APPROVAL_TIMEOUT_MS, } = opts;
     const base = stripTrailingSlashes(assertApprovalBaseUrl(baseUrl));
@@ -143,7 +150,12 @@ export async function runHostedApproval(opts) {
                     }
                 }
                 log('passkey approval received from the hosted page.');
-                return assuranceFromCeremony(target, doc.assuranceData);
+                return {
+                    ...assuranceFromCeremony(target, doc.assuranceData),
+                    ...(typeof doc.mintToken === 'string' && doc.mintToken
+                        ? { mintToken: doc.mintToken }
+                        : {}),
+                };
             }
             // status 'pending' — the operator is still signing in / tapping.
         }

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

@@ -1,3 +1,11 @@
+// ⚠️ 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 wire calls the enrollment harness (../server-e2e.mjs)

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

@@ -0,0 +1,49 @@
+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;
+};
+/**
+ * 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).
+ */
+export declare function serverCreateIntent(base: string, mintToken: string, input: {
+    tokenId: string;
+    assuranceData: unknown;
+    transaction: VgsCheckoutTarget;
+}, 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,150 @@
+// 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.
+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;
+}
+/** 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).
+ */
+export async function serverCreateIntent(base, mintToken, input, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const { tokenId, assuranceData, transaction: t } = input;
+    const cap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
+        method: 'POST',
+        headers: bearer(mintToken),
+        body: JSON.stringify({
+            tokenId,
+            consumerPrompt: `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`,
+            assuranceData,
+            mandates: [
+                {
+                    description: `Purchase at ${t.merchantName}`,
+                    declineThresholdAmount: String(cap),
+                    declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
+                    effectiveUntil: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+                    merchantCategory: 'Retail',
+                    merchantCategoryCode: '5999',
+                    preferredMerchantName: t.merchantName,
+                    quantity: 1,
+                },
+            ],
+        }),
+    });
+    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,
+            merchantUrl: 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 }
+                    : {}),
+            };
+        }
+        // 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 };
+}