@visa/cli 4.1.0-rc.154 → 4.1.0-rc.156

package/dist/checkout-engine/executor.js

@@ -24,7 +24,8 @@ import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
 import { traceHandleFields } from './trace-handles.js';
 import { readGenericPageAmount } from './amount.js';
-import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, } from './adapters/shopify.js';
+import { webBotAuthHeadersOrNone } from './web-bot-auth.js';
+import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, shopifyEnglishCheckoutUrl, } from './adapters/shopify.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
 const REVEAL_TEXT = /continue|next|proceed|review|go to payment/i;
@@ -674,7 +675,21 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         mandate: { ...opts.mandate },
     };
     const evidence = new EvidenceLog();
-    const context = await options.browser.newContext();
+    // Pin an English locale: amount reconciliation reads the order summary by
+    // its visible labels (Subtotal/Taxes/Total), and merchants localize by
+    // Accept-Language (observed live 2026-08-16: a Shopify checkout redirected
+    // to /es-us and rendered "Impuestos estimados", so the total never parsed
+    // and the review refused fail-closed on a perfectly good checkout).
+    // Present Web Bot Auth (RFC 9421) credentials when, and only when, an
+    // operator directory is configured to resolve them. Off by default: an
+    // unresolvable signature fails verification and is worse than none. The
+    // signature covers @authority, so it is bound to the checkout host — a
+    // cross-origin redirect simply arrives unverified, never wrongly verified.
+    const webBotAuthHeaders = webBotAuthHeadersOrNone(options.webBotAuth ?? null, options.url, Date.now() / 1000);
+    const context = await options.browser.newContext({
+        locale: 'en-US',
+        ...(webBotAuthHeaders ? { extraHTTPHeaders: webBotAuthHeaders } : {}),
+    });
     // Bound every action so a mis-detected or hidden element fails fast instead
     // of stalling on Playwright's long default timeout.
     context.setDefaultTimeout(6000);
@@ -732,6 +747,19 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         // Instrument.getCredential() call can occur before an explicit approval.
         let detected = await detectFields(page);
         const shopifyPage = await isShopifyCheckoutPage(page);
+        if (shopifyPage) {
+            // Same checkout session, English presentation — the amount reader needs
+            // the English summary labels (see shopifyEnglishCheckoutUrl).
+            const englishUrl = shopifyEnglishCheckoutUrl(page.url());
+            if (englishUrl) {
+                await page.goto(englishUrl, { waitUntil: 'domcontentloaded' }).catch(() => { });
+                await waitForStableDom(page);
+                if (await isShopifyCheckoutPage(page)) {
+                    evidence.step('navigation', { url: page.url(), reason: 'shopify-locale-normalized' });
+                    detected = await detectFields(page);
+                }
+            }
+        }
         let adapter = selectAdapter(detected, { shopify: shopifyPage });
         if (options.contact && adapter.prepareContact) {
             const preparedContact = await adapter.prepareContact(page, options.contact);
@@ -799,6 +827,26 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
             }
         }
+        // A checkout the runner cannot put a card INTO is not reviewable. Without a
+        // detected card-number field a later pay would fill nothing and dispatch
+        // whatever control the review happened to bind (observed live 2026-08-16:
+        // a Payhip storefront SEARCH form, a FastSpring "PayPal Checkout" label,
+        // and a Shopify discount-form "Submit" all reviewed clean this way — the
+        // real card fields sat in unreachable PSP iframes or an unrendered payment
+        // section). Every adapter fills from this same detection, so a missing
+        // number field here means no pay can ever succeed: refuse while it is
+        // still free.
+        if (!fields.number) {
+            const found = Object.keys(fields);
+            const reason = `no card number field detected (roles found: ${found.length ? found.join(', ') : 'none'}) — ` +
+                'the card form is likely inside a PSP iframe or behind a later step, so a credential cannot be entered on this page';
+            evidence.step('detect', { phase: 'review', missingCardNumber: true, reason });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return {
+                status: 'finished',
+                result: makeResult('failed', fields, evidence, requiresAdapter, reason),
+            };
+        }
         const facts = await readTransactionFacts(page, options, 'review');
         recordTransactionFacts(evidence, 'review', facts);
         if (!facts.ok) {

package/dist/checkout-engine/mandate/mandate-ledger.d.ts

@@ -61,6 +61,13 @@ export type CardMandateRecord = {
      * created record attempted registration. ISO 8601.
      */
     registerFailedAt?: string;
+    /**
+     * Set after an authenticated owner-scoped server read proves this mandate was
+     * revoked. The local file is only an execution cache; server revocation is
+     * canonical and permanently retires the cached mandate from selection while
+     * retaining its receipt history for the owner.
+     */
+    serverRevokedAt?: string;
     /**
      * A cross-host retail budget, not scoped to one `merchantHost`. The local
      * selector may attempt it at any host, while the provider/network still
@@ -127,6 +134,12 @@ export declare class MandateLedger {
      * Throws only if the mandate is unknown.
      */
     markRegisterFailed(mandateId: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId: string, revokedAt: string): Promise<CardMandateRecord>;
     /**
      * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
      *

package/dist/checkout-engine/mandate/mandate-ledger.js

@@ -203,6 +203,7 @@ export class MandateLedger {
             m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
             !m.unhonoredAt &&
             !m.registerFailedAt &&
+            !m.serverRevokedAt &&
             !isExpired(m, now) &&
             hasDrawCountHeadroom(m) &&
             remainingMinor(m) >= query.amountMinor);
@@ -252,6 +253,27 @@ export class MandateLedger {
             return record;
         });
     }
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId, revokedAt) {
+        return this.run(async () => {
+            const parsed = new Date(revokedAt);
+            if (Number.isNaN(parsed.getTime()))
+                throw new Error('server revocation timestamp is invalid');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.serverRevokedAt) {
+                record.serverRevokedAt = parsed.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
     /**
      * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
      *

package/dist/checkout-engine/receipt.d.ts

@@ -1,7 +1,8 @@
 import type { EvidenceStep } from './evidence.js';
 import type { CheckoutMode, CheckoutOutcome, CheckoutResult, CredentialLifecycle, CredentialTiming } from './executor.js';
 import type { VicConfirmationReport } from './vic-confirmation.js';
-export type CheckoutReceipt = {
+/** Published v1 artifact shape. Retained so patch releases remain readable/typable. */
+export type CheckoutReceiptV1 = {
     schema: 'checkout-agent-receipt/v1';
     recordedAt: string;
     mode: CheckoutMode;
@@ -32,6 +33,42 @@ export type CheckoutReceipt = {
         snapshotSummary: string | null;
     };
 };
+export type CheckoutReceiptV2 = {
+    schema: 'checkout-agent-receipt/v2';
+    recordedAt: string;
+    merchant: {
+        name: string;
+        host: string;
+        checkoutUrl: string | null;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    outcome: CheckoutOutcome;
+    agent: {
+        name: string;
+    } | null;
+    rail: {
+        type: 'card';
+        cardLast4: string | null;
+    };
+    network: {
+        confirmation: 'APPROVED' | 'DECLINED' | null;
+    };
+    /** Local reviewed-attempt identifier. Keeps filenames stable across schema versions. */
+    receiptId: string | null;
+    /** Merchant confirmation reference only; never substituted with an internal review id. */
+    reference: string | null;
+    recovery: {
+        required: boolean;
+        retrySafe: boolean;
+        action: string;
+        actions: string[];
+    };
+};
+export type CheckoutReceipt = CheckoutReceiptV1 | CheckoutReceiptV2;
 export type ReceiptWriteReport = {
     written: true;
     path: string;
@@ -46,6 +83,7 @@ export declare function buildReceipt(input: {
     merchant: {
         name: string;
         host: string;
+        url?: string;
     };
     transaction: {
         amount: string;
@@ -54,9 +92,11 @@ export declare function buildReceipt(input: {
     };
     result: CheckoutResult;
     vicConfirmation: VicConfirmationReport | null;
+    agentName?: string;
+    cardLast4?: string;
     /** Injectable for tests; defaults to now. */
     recordedAt?: Date;
-}): CheckoutReceipt;
+}): CheckoutReceiptV2;
 /**
  * Defense-in-depth scrub before anything touches disk: any standalone
  * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by

package/dist/checkout-engine/receipt.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
 import { submitClickedWithoutConfirmation } from './live-fill-approval.js';
 /**
  * What the operator still owes after this run. Empty for a clean dry-run fill
@@ -29,23 +30,37 @@ function reconciliationFor(result, vicConfirmation) {
 }
 export function buildReceipt(input) {
     const { result } = input;
+    const reconciliation = reconciliationFor(result, input.vicConfirmation);
+    const fallbackAction = input.mode === 'dry-run'
+        ? 'Dry run only — nothing was submitted; safe to run again.'
+        : result.outcome === 'confirmed'
+            ? 'No action needed.'
+            : result.outcome === 'declined'
+                ? 'Review the decline before trying again.'
+                : 'Review this outcome before retrying.';
+    const recoveryActions = reconciliation.reasons.length > 0 ? reconciliation.reasons : [fallbackAction];
+    const cardLast4 = input.cardLast4 && /^\d{4}$/.test(input.cardLast4) ? input.cardLast4 : null;
+    const checkoutUrl = input.merchant.url && KNOWN_MERCHANT_IDENTITIES[input.merchant.url] ? input.merchant.url : null;
+    const networkConfirmation = input.vicConfirmation?.posted === true ? input.vicConfirmation.transactionStatus : null;
     return {
-        schema: 'checkout-agent-receipt/v1',
+        schema: 'checkout-agent-receipt/v2',
         recordedAt: (input.recordedAt ?? new Date()).toISOString(),
-        mode: input.mode,
-        reviewId: input.reviewId,
-        merchant: { name: input.merchant.name, host: input.merchant.host },
+        merchant: { name: input.merchant.name, host: input.merchant.host, checkoutUrl },
         transaction: input.transaction,
         outcome: result.outcome,
-        detail: result.detail ?? null,
-        confirmationRef: result.confirmationRef ?? null,
-        vicConfirmation: input.vicConfirmation,
-        credentialLifecycle: result.credentialLifecycle,
-        credentialTiming: result.credentialTiming,
-        detectedRoles: Object.keys(result.fields),
-        requiresAdapter: [...result.requiresAdapter],
-        reconciliation: reconciliationFor(result, input.vicConfirmation),
-        evidence: result.evidence.toObject(),
+        agent: input.agentName ? { name: input.agentName } : null,
+        rail: { type: 'card', cardLast4 },
+        network: { confirmation: networkConfirmation },
+        receiptId: input.reviewId,
+        reference: result.confirmationRef ?? null,
+        recovery: {
+            required: reconciliation.required,
+            // A clean dry-run did not submit anything, so repeating inspection is
+            // safe. Every submit outcome requires either no retry or owner review.
+            retrySafe: input.mode === 'dry-run' && !reconciliation.required,
+            action: recoveryActions[0],
+            actions: recoveryActions,
+        },
     };
 }
 function luhnValid(digits) {
@@ -88,7 +103,8 @@ export function serializeReceipt(receipt) {
 }
 export function receiptFileName(receipt) {
     const ts = receipt.recordedAt.replace(/[:.]/g, '-');
-    const review = (receipt.reviewId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
+    const receiptId = receipt.schema === 'checkout-agent-receipt/v1' ? receipt.reviewId : receipt.receiptId;
+    const review = (receiptId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
     return `receipt-${ts}-${review || 'no-review'}.json`;
 }
 /**

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 };
+}