@visa/cli 4.1.0-rc.25 → 4.1.0-rc.250

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

@@ -11,6 +11,7 @@
 // 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?.();
@@ -21,10 +22,62 @@ function stripTrailingSlashes(value) {
         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;
+    }
+}
+/**
+ * A definitive refusal from the cryptogram mint route — the request will not
+ * succeed if retried unchanged.
+ *
+ * `terminal` is the load-bearing field. Draw terminality used to be decided by
+ * regex over the error MESSAGE, which made it hostage to text nobody controls:
+ * this client now interpolates the provider's own `upstream_codes` into the
+ * message for diagnosability, and a provider identifier such as
+ * `request_timeout` would match the transient matcher's unanchored
+ * `tim(e|ed)-out` alternative — flipping a permanent 422 back to "transient",
+ * skipping markUnhonored, and stranding the mandate in the exact retry-forever
+ * loop this whole change exists to kill. Terminality is therefore carried
+ * structurally, and consumers must consult it BEFORE any message matching.
+ */
+export class ServerCryptogramRefusedError extends Error {
+    status;
+    terminal = true;
+    constructor(status, detail) {
+        super(`server cryptogram refused (${status}): ${detail}`);
+        this.name = 'ServerCryptogramRefusedError';
+        this.status = status;
+    }
+}
 /** 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}`;
+    const base = doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    // Carry the provider's own status and rejected-attribute identifiers into the
+    // message when the route reflected them. Without this the operator sees only
+    // our status and has to go log-diving to learn WHICH field the gateway
+    // objected to — the gap that left a live create_intent 422 undiagnosable.
+    const parts = [];
+    if (typeof doc?.upstream_status === 'number')
+        parts.push(`upstream_status=${doc.upstream_status}`);
+    if (Array.isArray(doc?.upstream_codes) && doc.upstream_codes.length > 0) {
+        parts.push(`upstream_codes=${doc.upstream_codes.join(',')}`);
+    }
+    return parts.length > 0 ? `${base} [${parts.join(' ')}]` : base;
 }
 function bearer(mintToken) {
     return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
@@ -32,29 +85,37 @@ function 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).
+ * 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 cap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    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: `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`,
+            consumerPrompt,
             assuranceData,
             mandates: [
                 {
                     description: `Purchase at ${t.merchantName}`,
-                    declineThresholdAmount: String(cap),
+                    declineThresholdAmount,
                     declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
-                    effectiveUntil: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+                    effectiveUntil,
                     merchantCategory: 'Retail',
                     merchantCategoryCode: '5999',
                     preferredMerchantName: t.merchantName,
-                    quantity: 1,
+                    quantity,
                 },
             ],
         }),
@@ -89,7 +150,9 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
         intentId,
         transaction: {
             merchantName: t.merchantName,
-            merchantUrl: t.merchantUrl,
+            // 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(),
@@ -116,11 +179,16 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
                 ...(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)}`);
+        // 429 is the sole exception: it is an explicitly retryable 4xx, and treating
+        // it as terminal would let a transient rate limit permanently disable a
+        // healthy mandate. The route maps upstream rate limits to 503 today, so this
+        // is a guard against a future emitter, not a live path.
+        if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+            throw new ServerCryptogramRefusedError(res.status, await routeError(res));
         }
         lastError = `${res.status}: ${await routeError(res)}`;
         if (attempt < attempts)

package/dist/checkout-engine/vgs-live-instrument.d.ts

@@ -42,6 +42,15 @@ export type PurchaseAssurance = {
     transactionAmount: string;
     /** ISO 4217 currency the ceremony was scoped to. */
     transactionCurrencyCode: string;
+    /**
+     * True iff the approval server marked this token passkey-exempt ('otp'
+     * cardholder ID&V / 'none' — verified against the owner's account card
+     * record at complete-time): no ceremony ran, `assuranceData` is null by
+     * design, and the intent is minted without it (the signed mint token
+     * carries the same exemption for the server's own check). Absent/false →
+     * assuranceData is REQUIRED, exactly the historical contract.
+     */
+    assuranceExempt?: boolean;
 };
 /**
  * Our fail-closed freshness bound, matching the runner's 15-minute checkout
@@ -57,6 +66,8 @@ export type VgsPaymentCredential = {
     cryptogramType: string;
     cryptogramValue: string;
     cryptogramExpiresAt?: string;
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type FetchVgsPaymentCredential = (input: {
     tokenId: string;
@@ -69,20 +80,39 @@ export type FetchVgsPaymentCredential = (input: {
         transactionCurrencyCode: string;
     };
 }) => Promise<VgsPaymentCredential>;
-export type MintFreshVgsPaymentCredential = (input: {
-    tokenId: string;
-    assuranceData: unknown;
-    transaction: VgsCheckoutTarget;
-}) => Promise<{
-    payment: VgsPaymentCredential;
-    intentId: string;
-}>;
 /** The (token, intent) pair a VIC confirmation is posted against. */
 export type VicConfirmationTarget = {
     tokenId: string;
     intentId: string;
 };
 export declare function decimalToMinor(value: unknown): number | 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 declare const TWO_DECIMAL_CURRENCIES: Set<string>;
+/**
+ * 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 declare function minorToDecimal(minor: number, currencyCode?: string): string;
 /**
  * Refuse to mint an intent unless the assurance is fresh and its declared
  * scope matches the checkout target exactly. `now` is injectable so the
@@ -112,30 +142,3 @@ export declare class VgsLiveInstrument implements Instrument {
     confirmationTarget(): VicConfirmationTarget | null;
     getCredential(ctx: InstrumentContext): Promise<CardCredential>;
 }
-/**
- * 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 declare class VgsAssuranceInstrument implements Instrument {
-    private readonly enrollment;
-    private readonly purchase;
-    private readonly target;
-    private readonly cardholderName;
-    private readonly mintCredential;
-    readonly kind: "agentic-token";
-    private used;
-    private minted;
-    constructor(enrollment: CliAgentCredential, purchase: PurchaseAssurance, target: VgsCheckoutTarget, cardholderName: string, mintCredential: MintFreshVgsPaymentCredential);
-    /** See VgsLiveInstrument.confirmationTarget — same contract. */
-    confirmationTarget(): VicConfirmationTarget | null;
-    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
-}

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

@@ -1,3 +1,4 @@
+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).
@@ -19,6 +20,43 @@ export function decimalToMinor(value) {
     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' ||
@@ -49,13 +87,6 @@ function validateTarget(reference, ctx) {
         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
@@ -68,7 +99,10 @@ export function validatePurchaseAssurance(value, target, now = new Date()) {
     if (value == null || typeof value !== 'object') {
         throw new Error(`purchase assurance is missing — ${remedy}`);
     }
-    if (value.assuranceData == null) {
+    // A passkey-exempt approval (marked by the approval SERVER, never assumed
+    // locally) carries no assurance by design — every scope/freshness check
+    // below still applies to it unchanged.
+    if (value.assuranceData == null && value.assuranceExempt !== true) {
         throw new Error(`purchase assurance requires assuranceData — ${remedy}`);
     }
     const mintedAtMs = typeof value.mintedAt === 'string' ? Date.parse(value.mintedAt) : NaN;
@@ -125,13 +159,14 @@ export function validateCredential(value, now = new Date()) {
         (value.expYear === now.getFullYear() && value.expMonth < now.getMonth() + 1)) {
         throw new Error('VGS credential is expired');
     }
-    if (value.cryptogramExpiresAt !== undefined) {
-        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');
-        }
+    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');
     }
 }
 /**
@@ -188,65 +223,7 @@ export class VgsLiveInstrument {
             cvc: value.cryptogramValue,
             cardholderName: this.cardholderName.trim(),
             ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
-        };
-    }
-}
-/**
- * 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

@@ -12,11 +12,29 @@ export type PostVicConfirmation = (input: {
         transactionCurrencyCode: string;
     };
 }) => Promise<unknown>;
+/**
+ * Why a confirmation was not posted, as a BOUNDED value rather than prose.
+ *
+ * `reason` below is a human sentence built for the local receipt; it embeds
+ * upstream error text and is useless as an aggregate. These three codes are the
+ * whole space, and they mean very different things:
+ *
+ *  - `outcome_not_definitive` — the merchant never gave a definitive answer, so
+ *    there is nothing truthful to report. Expected, not a fault.
+ *  - `no_credential_minted` — no VIC credential existed for this run, so there
+ *    is no intent to confirm against. Expected, not a fault.
+ *  - `post_failed` — we HAD a definitive outcome and an intent to report it
+ *    against, and the POST did not land. This one is a fault: the processor
+ *    lifecycle row is never written, so the purchase can never rank above the
+ *    platform's own record no matter how well it actually went.
+ */
+export type VicConfirmationSkipCode = 'outcome_not_definitive' | 'no_credential_minted' | 'post_failed';
 export type VicConfirmationReport = {
     posted: true;
     transactionStatus: VicTransactionStatus;
 } | {
     posted: false;
+    code: VicConfirmationSkipCode;
     reason: string;
 };
 /** Definitive merchant answers map to a status; everything else maps to none. */

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

@@ -11,12 +11,17 @@ export async function reportVicOutcome(input) {
     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, reason: 'no VIC credential was minted in this run' };
+        return {
+            posted: false,
+            code: 'no_credential_minted',
+            reason: 'no VIC credential was minted in this run',
+        };
     }
     try {
         await input.post({
@@ -32,8 +37,9 @@ export async function reportVicOutcome(input) {
     catch (err) {
         return {
             posted: false,
-            reason: `confirmation POST failed: ${err.message} — the merchant outcome stands; ` +
-                'retry the confirmation for this intent out-of-band',
+            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,98 @@
+/** 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;
+    signFn?: (signingInput: Uint8Array) => Promise<Uint8Array>;
+}
+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;
+/**
+ * Async version of buildWebBotAuthHeaders, supporting Turnkey or vault signFn signers.
+ */
+export declare function buildWebBotAuthHeadersAsync(params: BuildHeadersParams): Promise<WebBotAuthHeaders>;
+export declare function webBotAuthHeadersOrNoneAsync(config: WebBotAuthConfig | null, targetUrl: string, nowSeconds: number): Promise<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;