@adcp/sdk 6.6.0 → 6.8.0

package/dist/lib/signing/agent-resolver/jwks-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-set.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/jwks-set.ts"],"names":[],"mappings":"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"}

package/dist/lib/signing/agent-resolver/resolve-agent.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `resolveAgent` — implementation of the 8-step brand_json_url discovery
+ * algorithm defined in `security.mdx` §"Discovering an agent's signing
+ * keys via `brand_json_url`". Given an agent URL `A` and (optionally)
+ * the protocol it speaks, returns the resolved brand.json document, the
+ * matched `agents[]` entry, the JWKS URI, the JWKS itself, and a per-step
+ * trace.
+ *
+ * Composition with existing pieces:
+ *   - Step 1 (capabilities fetch) goes through `ProtocolClient` via the
+ *     `createMCPClient` / `createA2AClient` factories — never a raw HTTP
+ *     GET on the agent URL. The spec is explicit: the agent URL is the
+ *     protocol endpoint, not a JSON capabilities document.
+ *   - Steps 4 / 8 (brand.json / JWKS fetches) go through `ssrfSafeFetch`
+ *     with `maxRedirects: 0` (the spec forbids redirects on the
+ *     bootstrap fetch — the `authoritative_location` carve-out is scoped
+ *     to webhook receivers and MUST NOT be inherited here) and the
+ *     strict-JSON parser (duplicate-key + prototype-property rejection).
+ *
+ * Error mapping:
+ *   - All wire-shape rejections surface as `AgentResolverError` with a
+ *     `request_signature_*` code matching the spec's rejection-code table.
+ *   - Counterparty-controlled detail fields (`brand_json_url`,
+ *     `matched_entries`, `parse_error`) are marked
+ *     `attackerInfluencedFields` so admin-UI renderers know to escape.
+ *   - SSRF refusals translate to a coarse `dns_error` classification —
+ *     never the resolved IP or hostname-to-address mapping the underlying
+ *     `SsrfRefusedError` carries.
+ */
+import type { IdentityKeyOriginPurpose, IdentityPosture } from './capabilities-types';
+import { type ConsistencyResult } from './consistency';
+import { type AgentResolverErrorDetail } from './errors';
+import { type AgentEntry } from './select-agent';
+export type AgentProtocol = 'mcp' | 'a2a';
+export interface FetchCapabilitiesFn {
+    (agentUrl: string): Promise<unknown>;
+}
+export interface ResolveAgentOptions {
+    /** Default `'mcp'`. Ignored when `fetchCapabilities` is supplied. */
+    protocol?: AgentProtocol;
+    /**
+     * Override the capabilities-fetch step entirely. Tests pass a fake; production
+     * callers who already hold a configured protocol client can wire it through
+     * here rather than letting the resolver build a fresh transport.
+     */
+    fetchCapabilities?: FetchCapabilitiesFn;
+    /**
+     * Allow `http://` and private/loopback targets. Default false.
+     *
+     * Refused outside `{NODE_ENV=test, NODE_ENV=development}` unless the
+     * adopter sets `ADCP_RESOLVER_ALLOW_PRIVATE_IP=1` as an explicit ops
+     * acknowledgment — a security-critical entry point should fail closed
+     * when the carve-out gets wired from a misconfigured env var. Matches
+     * the project pattern around `createAdcpServer`'s in-memory-state and
+     * `tenant-registry`'s NODE_ENV allowlist.
+     */
+    allowPrivateIp?: boolean;
+    /**
+     * Body caps for the brand.json + JWKS fetches. Default: brand.json 256 KiB,
+     * JWKS 64 KiB — the budgets recommended by `security.mdx` §"Quickstart".
+     * The capabilities-fetch cap is enforced upstream by `ProtocolClient`'s
+     * own response-size limit; it is not configurable here.
+     */
+    bodyCaps?: {
+        brandJsonBytes?: number;
+        jwksBytes?: number;
+    };
+    /** Total per-fetch timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+    /**
+     * Purposes the caller knows the agent is signing for but that aren't
+     * inferable from a generic capabilities walk (governance-signing,
+     * TMP-signing). Joined with the auto-detected set before the
+     * `key_origins` missing check.
+     */
+    declaredPurposes?: readonly IdentityKeyOriginPurpose[];
+    /**
+     * Sell-side webhook publisher pin marker — when `webhook_signing` is
+     * `true`, the step-7 origin-consistency check is skipped for the
+     * webhook-signing purpose only (operator-side webhook-signing remains
+     * checked). Buyer-side / receive-side verifiers MUST leave this unset.
+     */
+    publisherPinned?: {
+        webhook_signing?: boolean;
+    };
+    /** Override the current time (epoch seconds) — for deterministic tests. */
+    now?: () => number;
+}
+export interface TraceStep {
+    step: number;
+    name: string;
+    ok: boolean;
+    fetchedAt?: number;
+    ageSeconds?: number;
+    url?: string;
+    detail?: Record<string, unknown> | AgentResolverErrorDetail;
+}
+export interface AgentResolution {
+    agentUrl: string;
+    brandJsonUrl: string;
+    agentEntry: AgentEntry;
+    jwksUri: string;
+    jwks: {
+        keys: ReadonlyArray<Record<string, unknown>>;
+    };
+    identityPosture: IdentityPosture | undefined;
+    consistency: {
+        ok: true;
+    } | {
+        ok: false;
+        results: ReadonlyArray<ConsistencyResult>;
+    };
+    freshness: {
+        capabilitiesFetchedAt: number;
+        brandJsonFetchedAt: number;
+        jwksFetchedAt: number;
+    };
+    /** `Cache-Control` header from the JWKS fetch, when the response carried one. */
+    jwksCacheControl?: string;
+    trace: ReadonlyArray<TraceStep>;
+}
+export declare function resolveAgent(agentUrl: string, options?: ResolveAgentOptions): Promise<AgentResolution>;
+//# sourceMappingURL=resolve-agent.d.ts.map

package/dist/lib/signing/agent-resolver/resolve-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-agent.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/resolve-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGtF,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAsB,KAAK,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAI7E,OAAO,EAAE,KAAK,UAAU,EAAwC,MAAM,gBAAgB,CAAC;AAEvF,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,CAAC;AAE1C,MAAM,WAAW,mBAAmB;IAClC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD;;;;;OAKG;IACH,eAAe,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChD,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,wBAAwB,CAAC;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACvD,eAAe,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,WAAW,EACP;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GACZ;QACE,EAAE,EAAE,KAAK,CAAC;QACV,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;KAC3C,CAAC;IACN,SAAS,EAAE;QACT,qBAAqB,EAAE,MAAM,CAAC;QAC9B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACjC;AAID,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwShH"}

package/dist/lib/signing/agent-resolver/resolve-agent.js

@@ -0,0 +1,398 @@
+"use strict";
+/**
+ * `resolveAgent` — implementation of the 8-step brand_json_url discovery
+ * algorithm defined in `security.mdx` §"Discovering an agent's signing
+ * keys via `brand_json_url`". Given an agent URL `A` and (optionally)
+ * the protocol it speaks, returns the resolved brand.json document, the
+ * matched `agents[]` entry, the JWKS URI, the JWKS itself, and a per-step
+ * trace.
+ *
+ * Composition with existing pieces:
+ *   - Step 1 (capabilities fetch) goes through `ProtocolClient` via the
+ *     `createMCPClient` / `createA2AClient` factories — never a raw HTTP
+ *     GET on the agent URL. The spec is explicit: the agent URL is the
+ *     protocol endpoint, not a JSON capabilities document.
+ *   - Steps 4 / 8 (brand.json / JWKS fetches) go through `ssrfSafeFetch`
+ *     with `maxRedirects: 0` (the spec forbids redirects on the
+ *     bootstrap fetch — the `authoritative_location` carve-out is scoped
+ *     to webhook receivers and MUST NOT be inherited here) and the
+ *     strict-JSON parser (duplicate-key + prototype-property rejection).
+ *
+ * Error mapping:
+ *   - All wire-shape rejections surface as `AgentResolverError` with a
+ *     `request_signature_*` code matching the spec's rejection-code table.
+ *   - Counterparty-controlled detail fields (`brand_json_url`,
+ *     `matched_entries`, `parse_error`) are marked
+ *     `attackerInfluencedFields` so admin-UI renderers know to escape.
+ *   - SSRF refusals translate to a coarse `dns_error` classification —
+ *     never the resolved IP or hostname-to-address mapping the underlying
+ *     `SsrfRefusedError` carries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgent = resolveAgent;
+const protocols_1 = require("../../protocols");
+const capabilities_types_1 = require("./capabilities-types");
+const canonicalize_1 = require("./canonicalize");
+const consistency_1 = require("./consistency");
+const errors_1 = require("./errors");
+const etld_1 = require("./etld");
+const fetch_helpers_1 = require("./fetch-helpers");
+const protocol_response_1 = require("../protocol-response");
+const select_agent_1 = require("./select-agent");
+const DEFAULT_TIMEOUT_MS = 10_000;
+async function resolveAgent(agentUrl, options = {}) {
+    const trace = [];
+    const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    const allowPrivateIp = checkAllowPrivateIp(options.allowPrivateIp === true);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const caps = options.bodyCaps ?? {};
+    const brandJsonCap = caps.brandJsonBytes ?? fetch_helpers_1.MAX_BRAND_JSON_BYTES;
+    const jwksCap = caps.jwksBytes ?? fetch_helpers_1.MAX_JWKS_BYTES;
+    // ─── Step 1: fetch capabilities at the protocol layer ─────────────────
+    const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? 'mcp');
+    let capabilitiesPayload;
+    let capabilitiesFetchedAt;
+    try {
+        const raw = await fetchCapabilities(agentUrl);
+        capabilitiesPayload = (0, protocol_response_1.unwrapProtocolResponse)(raw);
+        capabilitiesFetchedAt = now();
+        pushTrace(trace, {
+            step: 1,
+            name: 'fetch_capabilities',
+            ok: true,
+            fetchedAt: capabilitiesFetchedAt,
+            url: agentUrl,
+        });
+    }
+    catch (err) {
+        const detail = {
+            agent_url: agentUrl,
+            dns_error: err instanceof fetch_helpers_1.SafeFetchError ? err.transport : 'fetch_failed',
+            last_attempt_at: now(),
+        };
+        pushTrace(trace, { step: 1, name: 'fetch_capabilities', ok: false, url: agentUrl, detail });
+        throw new errors_1.AgentResolverError('request_signature_capabilities_unreachable', `Capabilities fetch failed for ${agentUrl}`, detail, ['agent_url']);
+    }
+    // ─── Step 2: read identity.brand_json_url ─────────────────────────────
+    const brandJsonUrl = (0, capabilities_types_1.readBrandJsonUrl)(capabilitiesPayload);
+    const identityPosture = (0, capabilities_types_1.readIdentityPosture)(capabilitiesPayload);
+    // Spec mandates `https://`; dev/test deployments setting `allowPrivateIp`
+    // are also allowed `http://` (matches the parallel carve-out in
+    // `ssrfSafeFetch` and `BrandJsonJwksResolver` for loopback testing).
+    const acceptsScheme = (url) => {
+        if (!url)
+            return false;
+        if (url.startsWith('https://'))
+            return true;
+        if (allowPrivateIp && url.startsWith('http://'))
+            return true;
+        return false;
+    };
+    if (!acceptsScheme(brandJsonUrl)) {
+        const detail = { agent_url: agentUrl };
+        pushTrace(trace, { step: 2, name: 'read_brand_json_url', ok: false, detail });
+        throw new errors_1.AgentResolverError('request_signature_brand_json_url_missing', `identity.brand_json_url is absent or not https on ${agentUrl}`, detail, ['agent_url']);
+    }
+    pushTrace(trace, { step: 2, name: 'read_brand_json_url', ok: true, detail: { brand_json_url: brandJsonUrl } });
+    // ─── Step 3: eTLD+1 origin binding ────────────────────────────────────
+    // IP-literal hosts have no PSL match; under `allowPrivateIp` (dev/test)
+    // we fall back to bare hostname equality so loopback fixtures work without
+    // standing up a public-name server. Production callers who don't set
+    // `allowPrivateIp` will hit `request_signature_brand_origin_mismatch` on
+    // an IP literal — which is the right answer: an agent advertising an IP
+    // brand_json_url has no business being trusted at the wire.
+    let agentEtld1;
+    let brandEtld1;
+    let sameOrigin;
+    try {
+        agentEtld1 = (0, etld_1.eTldPlusOne)(agentUrl);
+        brandEtld1 = (0, etld_1.eTldPlusOne)(brandJsonUrl);
+        sameOrigin = (0, etld_1.sameEtldPlusOne)(agentUrl, brandJsonUrl);
+    }
+    catch {
+        if (allowPrivateIp) {
+            const agentHost = new URL(agentUrl).hostname;
+            const brandHost = new URL(brandJsonUrl).hostname;
+            agentEtld1 = agentHost;
+            brandEtld1 = brandHost;
+            sameOrigin = agentHost === brandHost;
+        }
+        else {
+            const detail = { agent_url: agentUrl, brand_json_url: brandJsonUrl };
+            pushTrace(trace, { step: 3, name: 'etld1_binding', ok: false, detail });
+            throw new errors_1.AgentResolverError('request_signature_brand_origin_mismatch', `Cannot compute eTLD+1 for agent or brand.json host`, detail, ['agent_url', 'brand_json_url']);
+        }
+    }
+    // ─── Step 4: fetch brand.json (no redirects, strict JSON) ─────────────
+    let brandJson;
+    let brandJsonFetchedAt;
+    try {
+        const fetched = await (0, fetch_helpers_1.safeFetchJson)(brandJsonUrl, 'brand.json', {
+            allowPrivateIp,
+            timeoutMs,
+            maxBodyBytes: brandJsonCap,
+        });
+        brandJson = fetched.body;
+        brandJsonFetchedAt = fetched.fetchedAt;
+        pushTrace(trace, {
+            step: 4,
+            name: 'fetch_brand_json',
+            ok: true,
+            fetchedAt: brandJsonFetchedAt,
+            url: brandJsonUrl,
+        });
+    }
+    catch (err) {
+        if (err instanceof fetch_helpers_1.SafeFetchError && /strict-JSON parse/.test(err.message)) {
+            const detail = {
+                brand_json_url: brandJsonUrl,
+                parse_error: err.message,
+                last_attempt_at: now(),
+            };
+            pushTrace(trace, { step: 4, name: 'fetch_brand_json', ok: false, url: brandJsonUrl, detail });
+            throw new errors_1.AgentResolverError('request_signature_brand_json_malformed', `brand.json failed strict-JSON parse`, detail, ['brand_json_url', 'parse_error']);
+        }
+        const transport = err instanceof fetch_helpers_1.SafeFetchError ? err.transport : 'fetch_failed';
+        const detail = {
+            brand_json_url: brandJsonUrl,
+            dns_error: transport,
+            last_attempt_at: now(),
+            ...(err instanceof fetch_helpers_1.SafeFetchError && err.httpStatus !== undefined && { http_status: err.httpStatus }),
+        };
+        pushTrace(trace, { step: 4, name: 'fetch_brand_json', ok: false, url: brandJsonUrl, detail });
+        throw new errors_1.AgentResolverError('request_signature_brand_json_unreachable', `brand.json fetch failed`, detail, [
+            'brand_json_url',
+        ]);
+    }
+    // Now run step 3's authorized_operators delegation check against the body.
+    if (!sameOrigin) {
+        const delegated = isAuthorizedOperator(brandJson, agentEtld1);
+        if (!delegated) {
+            const detail = {
+                agent_url: agentUrl,
+                agent_etld1: agentEtld1,
+                brand_json_url_etld1: brandEtld1,
+            };
+            pushTrace(trace, { step: 3, name: 'etld1_binding', ok: false, detail });
+            throw new errors_1.AgentResolverError('request_signature_brand_origin_mismatch', `Agent eTLD+1 ${agentEtld1} not delegated by brand.json authorized_operators[]`, detail, ['agent_url']);
+        }
+        pushTrace(trace, {
+            step: 3,
+            name: 'etld1_binding',
+            ok: true,
+            detail: { agent_etld1: agentEtld1, brand_json_url_etld1: brandEtld1, delegated_via_authorized_operators: true },
+        });
+    }
+    else {
+        pushTrace(trace, {
+            step: 3,
+            name: 'etld1_binding',
+            ok: true,
+            detail: { agent_etld1: agentEtld1, brand_json_url_etld1: brandEtld1 },
+        });
+    }
+    // ─── Step 5: byte-equal agents[] selection ────────────────────────────
+    let agentEntry;
+    try {
+        agentEntry = (0, select_agent_1.selectAgentByUrl)(brandJson, agentUrl);
+        pushTrace(trace, { step: 5, name: 'select_agent', ok: true, detail: { url: agentEntry.url } });
+    }
+    catch (err) {
+        if (err instanceof select_agent_1.AgentSelectorError) {
+            const detail = { agent_url: agentUrl, brand_json_url: brandJsonUrl };
+            const attacker = ['agent_url', 'brand_json_url'];
+            let code;
+            if (err.code === 'agent_not_in_brand_json') {
+                code = 'request_signature_agent_not_in_brand_json';
+            }
+            else {
+                code = 'request_signature_brand_json_ambiguous';
+                if (err.detail.matched_count !== undefined)
+                    detail.matched_count = err.detail.matched_count;
+                if (err.detail.matched_entries !== undefined) {
+                    detail.matched_entries = err.detail.matched_entries.map(e => ({
+                        url: e.url,
+                        ...(e.jwks_uri !== undefined && { jwks_uri: e.jwks_uri }),
+                    }));
+                    attacker.push('matched_entries');
+                }
+            }
+            pushTrace(trace, { step: 5, name: 'select_agent', ok: false, detail });
+            throw new errors_1.AgentResolverError(code, err.message, detail, attacker);
+        }
+        throw err;
+    }
+    // ─── Step 6: resolve jwks_uri ─────────────────────────────────────────
+    const declaredJwksUri = agentEntry.jwks_uri;
+    const jwksUriFromEntry = typeof declaredJwksUri === 'string' && acceptsScheme(declaredJwksUri) ? declaredJwksUri : undefined;
+    const jwksUri = jwksUriFromEntry ?? `${originOf(agentUrl)}/.well-known/jwks.json`;
+    pushTrace(trace, { step: 6, name: 'resolve_jwks_uri', ok: true, detail: { jwks_uri: jwksUri } });
+    // ─── Step 7: identity.key_origins consistency ─────────────────────────
+    const consistencyResults = runConsistencyChecks({
+        capabilitiesPayload,
+        identityPosture,
+        jwksUri,
+        publisherPinnedWebhookSigning: options.publisherPinned?.webhook_signing === true,
+        extraDeclaredPurposes: options.declaredPurposes ?? [],
+    });
+    const failedConsistency = consistencyResults.filter(r => r.ok === false);
+    if (failedConsistency.length > 0) {
+        const first = failedConsistency[0];
+        const detail = { purpose: first.purpose };
+        if (first.code === 'key_origin_mismatch') {
+            detail.expected_origin = first.expected_origin;
+            detail.actual_origin = first.actual_origin;
+            pushTrace(trace, { step: 7, name: 'key_origins_consistency', ok: false, detail });
+            throw new errors_1.AgentResolverError('request_signature_key_origin_mismatch', `identity.key_origins.${first.purpose} mismatch`, detail);
+        }
+        detail.posture = first.posture;
+        pushTrace(trace, { step: 7, name: 'key_origins_consistency', ok: false, detail });
+        throw new errors_1.AgentResolverError('request_signature_key_origin_missing', `identity.key_origins.${first.purpose} declaration missing`, detail);
+    }
+    pushTrace(trace, { step: 7, name: 'key_origins_consistency', ok: true });
+    // ─── Step 8 (preamble): fetch JWKS ────────────────────────────────────
+    let jwks;
+    let jwksFetchedAt;
+    let jwksCacheControl;
+    try {
+        const fetched = await (0, fetch_helpers_1.safeFetchJson)(jwksUri, 'jwks', {
+            allowPrivateIp,
+            timeoutMs,
+            maxBodyBytes: jwksCap,
+        });
+        if (!fetched.body ||
+            typeof fetched.body !== 'object' ||
+            !Array.isArray(fetched.body.keys)) {
+            throw new fetch_helpers_1.SafeFetchError('jwks', 'fetch_failed', 'JWKS document has no keys[] array');
+        }
+        jwks = fetched.body;
+        jwksFetchedAt = fetched.fetchedAt;
+        if (typeof fetched.headers['cache-control'] === 'string') {
+            jwksCacheControl = fetched.headers['cache-control'];
+        }
+        pushTrace(trace, { step: 8, name: 'fetch_jwks', ok: true, fetchedAt: jwksFetchedAt, url: jwksUri });
+    }
+    catch (err) {
+        const transport = err instanceof fetch_helpers_1.SafeFetchError ? err.transport : 'fetch_failed';
+        const detail = {
+            jwks_uri: jwksUri,
+            dns_error: transport,
+            last_attempt_at: now(),
+            ...(err instanceof fetch_helpers_1.SafeFetchError && err.httpStatus !== undefined && { http_status: err.httpStatus }),
+        };
+        pushTrace(trace, { step: 8, name: 'fetch_jwks', ok: false, url: jwksUri, detail });
+        // The spec hands step 8 off to the verifier checklist, where the
+        // canonical "JWKS unreachable" code (`request_signature_key_unknown`)
+        // only applies once a kid lookup has been attempted. The bootstrap
+        // chain needs a code before we have a kid, so we emit the SDK-side
+        // `request_signature_jwks_unreachable`. Operators triaging the
+        // rejection see `detail.jwks_uri`, not `detail.brand_json_url`.
+        throw new errors_1.AgentResolverError('request_signature_jwks_unreachable', `JWKS fetch failed`, detail, ['jwks_uri']);
+    }
+    return {
+        agentUrl,
+        brandJsonUrl,
+        agentEntry,
+        jwksUri,
+        jwks,
+        identityPosture,
+        consistency: { ok: true },
+        freshness: { capabilitiesFetchedAt, brandJsonFetchedAt, jwksFetchedAt },
+        ...(jwksCacheControl !== undefined && { jwksCacheControl }),
+        trace: trace.map(annotateAge(now())),
+    };
+}
+/**
+ * Refuse `allowPrivateIp: true` outside `{NODE_ENV=test, NODE_ENV=development}`
+ * unless the adopter set `ADCP_RESOLVER_ALLOW_PRIVATE_IP=1`. The flag lifts
+ * the spec's HTTPS-only / public-IP-only constraint to enable loopback test
+ * fixtures; in production it would silently widen the SSRF surface, so we
+ * close the door at the public API rather than relying on caller discipline.
+ */
+function checkAllowPrivateIp(requested) {
+    if (!requested)
+        return false;
+    const env = process.env.NODE_ENV;
+    if (env === 'test' || env === 'development')
+        return true;
+    if (process.env.ADCP_RESOLVER_ALLOW_PRIVATE_IP === '1')
+        return true;
+    throw new Error('resolveAgent: allowPrivateIp=true refused outside {NODE_ENV=test, NODE_ENV=development}. ' +
+        'Set NODE_ENV appropriately for dev/test, or set ADCP_RESOLVER_ALLOW_PRIVATE_IP=1 as an ' +
+        'explicit ops acknowledgment if you genuinely need private-IP discovery in this process.');
+}
+function defaultFetchCapabilities(agentUrl, protocol) {
+    return async () => {
+        const client = protocol === 'a2a' ? (0, protocols_1.createA2AClient)(agentUrl) : (0, protocols_1.createMCPClient)(agentUrl);
+        return client.callTool('get_adcp_capabilities', {});
+    };
+}
+function isAuthorizedOperator(brandJson, agentEtld1) {
+    if (!brandJson || typeof brandJson !== 'object')
+        return false;
+    const operators = brandJson.authorized_operators;
+    if (!Array.isArray(operators))
+        return false;
+    for (const op of operators) {
+        if (op && typeof op === 'object') {
+            const domain = op.domain;
+            if (typeof domain === 'string') {
+                try {
+                    if ((0, etld_1.eTldPlusOne)(domain) === agentEtld1)
+                        return true;
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        // Some brand.json shapes carry a bare-string entry rather than `{ domain }`.
+        if (typeof op === 'string') {
+            try {
+                if ((0, etld_1.eTldPlusOne)(op) === agentEtld1)
+                    return true;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return false;
+}
+function originOf(url) {
+    return (0, canonicalize_1.canonicalizeOrigin)(url);
+}
+function pushTrace(trace, step) {
+    trace.push(step);
+}
+function annotateAge(now) {
+    return step => (step.fetchedAt !== undefined ? { ...step, ageSeconds: Math.max(0, now - step.fetchedAt) } : step);
+}
+function runConsistencyChecks(args) {
+    const results = [];
+    const declared = (0, consistency_1.declaredSigningPurposes)(args.capabilitiesPayload, args.extraDeclaredPurposes);
+    // Missing-origin check first — independent of jwksUri origin matching.
+    for (const missing of (0, consistency_1.checkRequiredOrigins)(declared, args.identityPosture?.key_origins)) {
+        results.push(missing);
+    }
+    // Origin-match check: walk every declared origin and compare against jwksUri
+    // host. Skip publisher-pinned webhook-signing only.
+    const keyOrigins = args.identityPosture?.key_origins;
+    if (keyOrigins) {
+        for (const purpose of Object.keys(keyOrigins)) {
+            const declaredOrigin = keyOrigins[purpose];
+            if (!declaredOrigin)
+                continue;
+            const result = (0, consistency_1.checkOriginConsistency)({
+                purpose,
+                declaredOrigin,
+                resolvedJwksUri: args.jwksUri,
+                publisherPinned: purpose === 'webhook_signing' && args.publisherPinnedWebhookSigning,
+            });
+            if (result.ok === false)
+                results.push(result);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=resolve-agent.js.map

package/dist/lib/signing/agent-resolver/resolve-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-agent.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/resolve-agent.ts"],"names":[],"mappings":"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"}

package/dist/lib/signing/agent-resolver/select-agent.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Step 5 of the brand_json_url discovery algorithm: locate the brand.json
+ * `agents[]` entry whose `url` byte-equals the agent URL the verifier is
+ * resolving. The byte-equal rule is deliberate (security.mdx §"Discovering
+ * an agent's signing keys via `brand_json_url`" step 5) — no canonicalization,
+ * because the most common operator misconfiguration is a trailing-slash or
+ * scheme mismatch (`https://x.com/mcp` vs `https://x.com/mcp/`), and silently
+ * canonicalizing past that hides the bug. The match must be exact.
+ *
+ * Both flat (`agents[]` at top level) and house-portfolio
+ * (`house.agents[]` + `brands[].agents[]`) brand.json shapes are supported,
+ * because either may carry the entry that matches the agent URL.
+ */
+export type AgentSelectorErrorCode = 'agent_not_in_brand_json' | 'brand_json_ambiguous';
+export interface AgentEntry {
+    url: string;
+    jwks_uri?: string;
+    /** Other fields preserved verbatim — the resolver passes the entry to the caller. */
+    [key: string]: unknown;
+}
+export declare class AgentSelectorError extends Error {
+    readonly code: AgentSelectorErrorCode;
+    readonly detail: {
+        agent_url: string;
+        matched_count?: number;
+        matched_entries?: AgentEntry[];
+    };
+    constructor(code: AgentSelectorErrorCode, message: string, detail: {
+        agent_url: string;
+        matched_count?: number;
+        matched_entries?: AgentEntry[];
+    });
+}
+/**
+ * Walk every `agents[]` array reachable from the brand.json document and
+ * collect entries with a string `url`. Entries without a string `url` are
+ * silently skipped — they cannot match an agent URL, and rejecting the
+ * whole document here would let a single malformed entry deny verification
+ * for every agent the document declares.
+ */
+export declare function collectAgentEntries(brandJson: unknown): AgentEntry[];
+/**
+ * Find the unique `agents[]` entry whose `url` byte-equals `agentUrl`.
+ *
+ * - Returns the matched entry on a unique hit.
+ * - Throws `AgentSelectorError('agent_not_in_brand_json')` on zero matches.
+ * - Throws `AgentSelectorError('brand_json_ambiguous')` on multiple matches.
+ *   `matched_count` and `matched_entries` are populated on the error so the
+ *   caller can map them onto `request_signature_brand_json_ambiguous` detail
+ *   fields. `matched_entries` reflects counterparty-controlled state and is
+ *   marked attacker-influenceable in the resolver's error mapping.
+ */
+export declare function selectAgentByUrl(brandJson: unknown, agentUrl: string): AgentEntry;
+//# sourceMappingURL=select-agent.d.ts.map

package/dist/lib/signing/agent-resolver/select-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-agent.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/select-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,sBAAsB,GAAG,yBAAyB,GAAG,sBAAsB,CAAC;AAExF,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;gBAE7F,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,UAAU,EAAE,CAAA;KAAE;CAOxF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,OAAO,GAAG,UAAU,EAAE,CAiBpE;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAkBjF"}