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

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

@@ -0,0 +1,45 @@
+/** 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,
+            code: 'outcome_not_definitive',
+            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,
+            code: 'no_credential_minted',
+            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,
+            code: 'post_failed',
+            reason: `confirmation POST failed: ${err.message} — the merchant-reported outcome ` +
+                'remains unverified; retry the confirmation for this intent out-of-band',
+        };
+    }
+}

package/dist/checkout-engine/web-bot-auth.d.ts

@@ -0,0 +1,92 @@
+/** Signature validity ceiling. A signature is a bearer-ish artifact for as long
+ *  as it is valid, so the window stays short even if a caller asks for more. */
+export declare const WEB_BOT_AUTH_MAX_TTL_SECONDS = 300;
+/** Default validity. Long enough to survive a redirect chain and a slow TLS
+ *  handshake, short enough that a captured signature is near-useless. */
+export declare const WEB_BOT_AUTH_DEFAULT_TTL_SECONDS = 60;
+/** Label for the single signature we emit. RFC 9421 allows several per request. */
+export declare const WEB_BOT_AUTH_SIGNATURE_LABEL = "sig1";
+/** Tag fixed by the Web Bot Auth draft; verifiers select on it. */
+export declare const WEB_BOT_AUTH_TAG = "web-bot-auth";
+/** Components covered by the signature, in the order they appear in the base. */
+export declare const WEB_BOT_AUTH_COVERED_COMPONENTS: readonly ["@authority", "signature-agent"];
+/** Ed25519 private key in JWK form, as stored in the agent's runtime key file. */
+export interface WebBotAuthPrivateJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+    d: string;
+}
+export interface WebBotAuthSigningKey {
+    /** RFC 7638 thumbprint. Must match a `kid` published in the directory. */
+    keyId: string;
+    privateJwk: WebBotAuthPrivateJwk;
+}
+export interface WebBotAuthConfig {
+    /** Absolute https URL of the operator-hosted signature directory. */
+    directoryUrl: string;
+    key: WebBotAuthSigningKey;
+    ttlSeconds?: number;
+}
+export interface WebBotAuthHeaders {
+    'Signature-Input': string;
+    Signature: string;
+    'Signature-Agent': string;
+    [header: string]: string;
+}
+export interface SignatureBaseParams {
+    authority: string;
+    directoryUrl: string;
+    keyId: string;
+    created: number;
+    expires: number;
+}
+/**
+ * Build the RFC 9421 signature base.
+ *
+ * The base is what actually gets signed, so its exact bytes are the contract
+ * with every verifier — one wrong space or a reordered parameter and the
+ * signature fails against a correct key. It is exported and pinned by a
+ * deterministic test vector for that reason.
+ */
+export declare function buildSignatureBase(params: SignatureBaseParams): string;
+/**
+ * The `@signature-params` value, which appears twice: as the final line of the
+ * signature base, and verbatim as the `Signature-Input` header value. Building
+ * it once is what keeps those two identical — a verifier rederives the base
+ * from the header it received, so any divergence fails every signature.
+ */
+export declare function buildSignatureParams(params: SignatureBaseParams): string;
+export interface BuildHeadersParams {
+    /** Host (and port, if non-default) of the request being signed. */
+    authority: string;
+    config: WebBotAuthConfig;
+    /** Unix seconds. Injected so tests are deterministic and never wall-clock. */
+    nowSeconds: number;
+}
+/**
+ * Produce the three Web Bot Auth headers for one request authority.
+ *
+ * Throws on unusable key material rather than emitting an unverifiable
+ * signature. Callers on the checkout path must treat a throw as "proceed
+ * unsigned" — see `webBotAuthHeadersOrNone`.
+ */
+export declare function buildWebBotAuthHeaders(params: BuildHeadersParams): WebBotAuthHeaders;
+/**
+ * Header-or-nothing wrapper for the checkout path.
+ *
+ * Signing is an optional trust upgrade, never a precondition for buying
+ * something. Unusable key material, a malformed URL, or any crypto failure
+ * degrades to an unsigned request — which is exactly what we sent before this
+ * module existed — rather than throwing into a live checkout.
+ */
+export declare function webBotAuthHeadersOrNone(config: WebBotAuthConfig | null, targetUrl: string, nowSeconds: number): WebBotAuthHeaders | null;
+/**
+ * Resolve signing config from the environment. Returns `null` — meaning "send
+ * unsigned" — unless a directory URL and a usable key are BOTH present.
+ *
+ * Default-off is deliberate. Until the operator directory is live and serving
+ * this key, a signature resolves to nothing and fails verification, which is
+ * worse than the honest unsigned request we sent before.
+ */
+export declare function resolveWebBotAuthConfig(env: NodeJS.ProcessEnv, loadKey: () => WebBotAuthSigningKey | null): WebBotAuthConfig | null;

package/dist/checkout-engine/web-bot-auth.js

@@ -0,0 +1,159 @@
+/**
+ * @purpose Web Bot Auth (RFC 9421) request signing for checkout navigations —
+ * the client half of Trusted Agent Protocol verification.
+ *
+ * Cloudflare's TAP verifies an agent by checking an RFC 9421 HTTP message
+ * signature on the request. Three headers carry it: `Signature-Input` names the
+ * covered components and parameters, `Signature` carries the Ed25519 signature
+ * over the derived base, and `Signature-Agent` gives the URL of the directory
+ * that resolves `keyid` to a public key. The checkout browser previously sent
+ * none of them, so a TAP-aware edge had nothing to verify and fell through to
+ * ordinary bot management.
+ *
+ * TWO HALVES, BOTH REQUIRED. This module presents a `keyid`; the auth server
+ * must publish that key at the `Signature-Agent` URL for anything to resolve.
+ * Signing while the directory is absent is strictly worse than not signing,
+ * because it advertises intent and then fails verification — which is why
+ * signing stays OFF unless explicitly configured with a directory URL.
+ *
+ * KEY MATERIAL NEVER LEAVES THIS MODULE. The signing key is accepted as a
+ * value, used once per request, and never logged, serialized, returned, or
+ * attached to evidence. Callers get headers, never the key. This module takes
+ * no logger for exactly that reason.
+ */
+import { createPrivateKey, sign as cryptoSign } from 'node:crypto';
+/** Signature validity ceiling. A signature is a bearer-ish artifact for as long
+ *  as it is valid, so the window stays short even if a caller asks for more. */
+export const WEB_BOT_AUTH_MAX_TTL_SECONDS = 300;
+/** Default validity. Long enough to survive a redirect chain and a slow TLS
+ *  handshake, short enough that a captured signature is near-useless. */
+export const WEB_BOT_AUTH_DEFAULT_TTL_SECONDS = 60;
+/** Label for the single signature we emit. RFC 9421 allows several per request. */
+export const WEB_BOT_AUTH_SIGNATURE_LABEL = 'sig1';
+/** Tag fixed by the Web Bot Auth draft; verifiers select on it. */
+export const WEB_BOT_AUTH_TAG = 'web-bot-auth';
+/** Components covered by the signature, in the order they appear in the base. */
+export const WEB_BOT_AUTH_COVERED_COMPONENTS = ['@authority', 'signature-agent'];
+/** Serialize an RFC 8941 structured-field string (always double-quoted). */
+function sfString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * Build the RFC 9421 signature base.
+ *
+ * The base is what actually gets signed, so its exact bytes are the contract
+ * with every verifier — one wrong space or a reordered parameter and the
+ * signature fails against a correct key. It is exported and pinned by a
+ * deterministic test vector for that reason.
+ */
+export function buildSignatureBase(params) {
+    return [
+        `"@authority": ${params.authority}`,
+        `"signature-agent": ${sfString(params.directoryUrl)}`,
+        `"@signature-params": ${buildSignatureParams(params)}`,
+    ].join('\n');
+}
+/**
+ * The `@signature-params` value, which appears twice: as the final line of the
+ * signature base, and verbatim as the `Signature-Input` header value. Building
+ * it once is what keeps those two identical — a verifier rederives the base
+ * from the header it received, so any divergence fails every signature.
+ */
+export function buildSignatureParams(params) {
+    return (`(${WEB_BOT_AUTH_COVERED_COMPONENTS.map(sfString).join(' ')})` +
+        `;created=${params.created}` +
+        `;expires=${params.expires}` +
+        `;keyid=${sfString(params.keyId)}` +
+        `;alg="ed25519"` +
+        `;tag=${sfString(WEB_BOT_AUTH_TAG)}`);
+}
+/**
+ * Produce the three Web Bot Auth headers for one request authority.
+ *
+ * Throws on unusable key material rather than emitting an unverifiable
+ * signature. Callers on the checkout path must treat a throw as "proceed
+ * unsigned" — see `webBotAuthHeadersOrNone`.
+ */
+export function buildWebBotAuthHeaders(params) {
+    const { authority, config, nowSeconds } = params;
+    const ttl = Math.min(Math.max(1, Math.floor(config.ttlSeconds ?? WEB_BOT_AUTH_DEFAULT_TTL_SECONDS)), WEB_BOT_AUTH_MAX_TTL_SECONDS);
+    const created = Math.floor(nowSeconds);
+    const expires = created + ttl;
+    const baseParams = {
+        authority,
+        directoryUrl: config.directoryUrl,
+        keyId: config.key.keyId,
+        created,
+        expires,
+    };
+    const base = buildSignatureBase(baseParams);
+    const signatureParams = buildSignatureParams(baseParams);
+    const privateKey = createPrivateKey({
+        key: config.key.privateJwk,
+        format: 'jwk',
+    });
+    // Ed25519 takes no separate digest algorithm; null is the required argument.
+    const signature = cryptoSign(null, Buffer.from(base, 'utf8'), privateKey);
+    return {
+        'Signature-Input': `${WEB_BOT_AUTH_SIGNATURE_LABEL}=${signatureParams}`,
+        Signature: `${WEB_BOT_AUTH_SIGNATURE_LABEL}=:${signature.toString('base64')}:`,
+        'Signature-Agent': sfString(config.directoryUrl),
+    };
+}
+/**
+ * Header-or-nothing wrapper for the checkout path.
+ *
+ * Signing is an optional trust upgrade, never a precondition for buying
+ * something. Unusable key material, a malformed URL, or any crypto failure
+ * degrades to an unsigned request — which is exactly what we sent before this
+ * module existed — rather than throwing into a live checkout.
+ */
+export function webBotAuthHeadersOrNone(config, targetUrl, nowSeconds) {
+    if (!config)
+        return null;
+    try {
+        const authority = new URL(targetUrl).host;
+        if (!authority)
+            return null;
+        return buildWebBotAuthHeaders({ authority, config, nowSeconds });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve signing config from the environment. Returns `null` — meaning "send
+ * unsigned" — unless a directory URL and a usable key are BOTH present.
+ *
+ * Default-off is deliberate. Until the operator directory is live and serving
+ * this key, a signature resolves to nothing and fails verification, which is
+ * worse than the honest unsigned request we sent before.
+ */
+export function resolveWebBotAuthConfig(env, loadKey) {
+    const directoryUrl = env.VISA_WEB_BOT_AUTH_DIRECTORY_URL?.trim();
+    if (!directoryUrl)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(directoryUrl);
+    }
+    catch {
+        return null;
+    }
+    // A directory fetched over plain http could be swapped in flight, which would
+    // let an observer substitute the key set our identity is judged against.
+    if (parsed.protocol !== 'https:')
+        return null;
+    let key = null;
+    try {
+        key = loadKey();
+    }
+    catch {
+        return null;
+    }
+    if (!key?.keyId || key.privateJwk?.crv !== 'Ed25519' || !key.privateJwk.d)
+        return null;
+    const rawTtl = Number(env.VISA_WEB_BOT_AUTH_TTL_SECONDS);
+    const ttlSeconds = Number.isFinite(rawTtl) && rawTtl > 0 ? rawTtl : undefined;
+    return { directoryUrl: parsed.toString(), key, ttlSeconds };
+}