@adcp/sdk 6.6.0 → 6.8.0

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

@@ -0,0 +1,68 @@
+/**
+ * Typed errors surfaced by `resolveAgent`. Codes mirror the
+ * `request_signature_*` taxonomy from security.mdx §"Discovering an
+ * agent's signing keys via `brand_json_url`" so a verifier consuming the
+ * resolver's output can short-circuit to the same wire-rejection code
+ * without rewriting the mapping.
+ *
+ * Detail-field discipline:
+ *   - Counterparty-influenceable strings (`agent_url`, `brand_json_url`,
+ *     `matched_entries`, `parse_error`, etc.) MUST be HTML-escaped before
+ *     rendering in admin UIs. The `attackerInfluenced` symbol marks fields
+ *     that came from the wire so downstream renderers can detect them.
+ *   - Internal network topology (resolved IPs, DNS state) MUST NOT be
+ *     copied onto detail fields. If `ssrfSafeFetch` throws, the resolver
+ *     translates the `SsrfRefusedError` into a `request_signature_*_unreachable`
+ *     code with `dns_error` set to the error class name only — never the
+ *     `address` or `hostname` fields the underlying error carries.
+ */
+export declare const ATTACKER_INFLUENCED: unique symbol;
+export type AgentResolverErrorCode = 'request_signature_brand_json_url_missing' | 'request_signature_capabilities_unreachable' | 'request_signature_brand_json_unreachable' | 'request_signature_brand_json_malformed' | 'request_signature_brand_origin_mismatch' | 'request_signature_agent_not_in_brand_json' | 'request_signature_brand_json_ambiguous' | 'request_signature_key_origin_mismatch' | 'request_signature_key_origin_missing'
+/**
+ * SDK-side codes — not in the spec's `request_signature_*` rejection
+ * table but distinct conditions a verifier needs to surface separately.
+ * The spec hands JWKS-fetch failures off to the verifier checklist
+ * (`request_signature_key_unknown`), but that code only applies once a
+ * `kid` lookup has been attempted; the bootstrap chain needs a code
+ * before we have a kid in hand. Likewise, an alg-allowlist rejection at
+ * import time is a distinct trust failure, not a fetch failure.
+ */
+ | 'request_signature_jwks_unreachable' | 'request_signature_jwks_alg_disallowed';
+export interface AgentResolverErrorDetail {
+    agent_url?: string;
+    brand_json_url?: string;
+    jwks_uri?: string;
+    agent_etld1?: string;
+    brand_json_url_etld1?: string;
+    http_status?: number;
+    /**
+     * Coarse classification of a transport error class — `'fetch_failed'`,
+     * `'timeout'`, `'dns_error'`, `'ssrf_refused'`. NEVER includes a resolved
+     * IP, hostname-to-address mapping, or any other internal-topology hint.
+     */
+    dns_error?: string;
+    last_attempt_at?: number;
+    parse_error?: string;
+    matched_count?: number;
+    matched_entries?: ReadonlyArray<{
+        url: string;
+        jwks_uri?: string;
+    }>;
+    purpose?: string;
+    expected_origin?: string;
+    actual_origin?: string;
+    posture?: string;
+}
+export declare class AgentResolverError extends Error {
+    readonly code: AgentResolverErrorCode;
+    readonly detail: AgentResolverErrorDetail;
+    readonly [ATTACKER_INFLUENCED]: ReadonlyArray<keyof AgentResolverErrorDetail>;
+    constructor(code: AgentResolverErrorCode, message: string, detail?: AgentResolverErrorDetail, attackerInfluencedFields?: ReadonlyArray<keyof AgentResolverErrorDetail>);
+}
+/**
+ * Field names on `AgentResolverError.detail` that carry counterparty-controlled
+ * strings. Renderers (admin UIs, log aggregators) MUST HTML-escape these
+ * before display.
+ */
+export declare function attackerInfluencedFields(err: AgentResolverError): ReadonlyArray<keyof AgentResolverErrorDetail>;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,mBAAmB,eAAyC,CAAC;AAE1E,MAAM,MAAM,sBAAsB,GAC9B,0CAA0C,GAC1C,4CAA4C,GAC5C,0CAA0C,GAC1C,wCAAwC,GACxC,yCAAyC,GACzC,2CAA2C,GAC3C,wCAAwC,GACxC,uCAAuC,GACvC,sCAAsC;AACxC;;;;;;;;GAQG;GACD,oCAAoC,GACpC,uCAAuC,CAAC;AAE5C,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,aAAa,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,aAAa,CAAC,MAAM,wBAAwB,CAAC,CAAC;gBAG5E,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,wBAA6B,EACrC,wBAAwB,GAAE,aAAa,CAAC,MAAM,wBAAwB,CAAM;CAQ/E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,kBAAkB,GAAG,aAAa,CAAC,MAAM,wBAAwB,CAAC,CAE/G"}

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

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Typed errors surfaced by `resolveAgent`. Codes mirror the
+ * `request_signature_*` taxonomy from security.mdx §"Discovering an
+ * agent's signing keys via `brand_json_url`" so a verifier consuming the
+ * resolver's output can short-circuit to the same wire-rejection code
+ * without rewriting the mapping.
+ *
+ * Detail-field discipline:
+ *   - Counterparty-influenceable strings (`agent_url`, `brand_json_url`,
+ *     `matched_entries`, `parse_error`, etc.) MUST be HTML-escaped before
+ *     rendering in admin UIs. The `attackerInfluenced` symbol marks fields
+ *     that came from the wire so downstream renderers can detect them.
+ *   - Internal network topology (resolved IPs, DNS state) MUST NOT be
+ *     copied onto detail fields. If `ssrfSafeFetch` throws, the resolver
+ *     translates the `SsrfRefusedError` into a `request_signature_*_unreachable`
+ *     code with `dns_error` set to the error class name only — never the
+ *     `address` or `hostname` fields the underlying error carries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentResolverError = exports.ATTACKER_INFLUENCED = void 0;
+exports.attackerInfluencedFields = attackerInfluencedFields;
+exports.ATTACKER_INFLUENCED = Symbol.for('adcp.attacker-influenced');
+class AgentResolverError extends Error {
+    code;
+    detail;
+    [exports.ATTACKER_INFLUENCED];
+    constructor(code, message, detail = {}, attackerInfluencedFields = []) {
+        super(message);
+        this.name = 'AgentResolverError';
+        this.code = code;
+        this.detail = detail;
+        this[exports.ATTACKER_INFLUENCED] = attackerInfluencedFields;
+    }
+}
+exports.AgentResolverError = AgentResolverError;
+/**
+ * Field names on `AgentResolverError.detail` that carry counterparty-controlled
+ * strings. Renderers (admin UIs, log aggregators) MUST HTML-escape these
+ * before display.
+ */
+function attackerInfluencedFields(err) {
+    return err[exports.ATTACKER_INFLUENCED];
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAyEH,4DAEC;AAzEY,QAAA,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AA+C1E,MAAa,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAC7B,MAAM,CAA2B;IACjC,CAAC,2BAAmB,CAAC,CAAgD;IAE9E,YACE,IAA4B,EAC5B,OAAe,EACf,SAAmC,EAAE,EACrC,2BAA0E,EAAE;QAE5E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,2BAAmB,CAAC,GAAG,wBAAwB,CAAC;IACvD,CAAC;CACF;AAjBD,gDAiBC;AAED;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,GAAuB;IAC9D,OAAO,GAAG,CAAC,2BAAmB,CAAC,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,25 @@
+export declare const PSL_SNAPSHOT_VERSION = "tldts@7";
+export declare class EtldComputationError extends Error {
+    readonly meta: {
+        hostOrUrl?: string;
+    };
+    constructor(message: string, meta: {
+        hostOrUrl?: string;
+    });
+}
+/**
+ * Compute eTLD+1 for a hostname or URL. Caller should pass either a bare
+ * hostname (`buyer.example.com`) or a full URL (`https://buyer.example.com/mcp`).
+ *
+ * Returns the registrable domain in canonical form (ASCII-lowercased, IDNA-2008
+ * A-label). Throws when the input has no PSL match — typically because the host
+ * is an IP literal or a single-label name.
+ */
+export declare function eTldPlusOne(hostOrUrl: string): string;
+/**
+ * Convenience: do two hostnames share an eTLD+1? Returns false when either
+ * input has no PSL match (rather than throwing) — callers comparing two
+ * hostnames typically want a non-match boolean, not an exception.
+ */
+export declare function sameEtldPlusOne(a: string, b: string): boolean;
+//# sourceMappingURL=etld.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"etld.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/etld.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,IAAI,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;gBADrC,OAAO,EAAE,MAAM,EACN,IAAI,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;CAKxC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU7D"}

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

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EtldComputationError = exports.PSL_SNAPSHOT_VERSION = void 0;
+exports.eTldPlusOne = eTldPlusOne;
+exports.sameEtldPlusOne = sameEtldPlusOne;
+/**
+ * eTLD+1 computation against a pinned, dated PSL snapshot. Backed by
+ * `tldts`, which ships its PSL bundled into the published package — pinning
+ * the dependency in `package.json` pins the snapshot. Runtime PSL fetches are
+ * never performed: a runtime fetch creates both a denial-of-service oracle
+ * (PSL host outage stalls verification) and a non-deterministic eTLD+1
+ * across deployments running on different snapshot ages
+ * (security.mdx §"Quickstart: implement a `brand_json_url`-based verifier"
+ * step 3).
+ *
+ * Both ICANN and PRIVATE PSL sections are in scope: platforms like
+ * `vercel.app`, `pages.dev`, `github.io` MUST be treated as suffixes so an
+ * attacker on `attacker.vercel.app` cannot pretend to share an eTLD+1 with
+ * a legitimate publisher on `legit.vercel.app`.
+ */
+const tldts_1 = require("tldts");
+const canonicalize_1 = require("./canonicalize");
+exports.PSL_SNAPSHOT_VERSION = 'tldts@7';
+class EtldComputationError extends Error {
+    meta;
+    constructor(message, meta) {
+        super(message);
+        this.meta = meta;
+        this.name = 'EtldComputationError';
+    }
+}
+exports.EtldComputationError = EtldComputationError;
+/**
+ * Compute eTLD+1 for a hostname or URL. Caller should pass either a bare
+ * hostname (`buyer.example.com`) or a full URL (`https://buyer.example.com/mcp`).
+ *
+ * Returns the registrable domain in canonical form (ASCII-lowercased, IDNA-2008
+ * A-label). Throws when the input has no PSL match — typically because the host
+ * is an IP literal or a single-label name.
+ */
+function eTldPlusOne(hostOrUrl) {
+    const host = (0, canonicalize_1.canonicalizeHost)(extractHost(hostOrUrl));
+    const result = (0, tldts_1.parse)(host, { allowPrivateDomains: true });
+    if (result.isIp) {
+        throw new EtldComputationError(`Cannot compute eTLD+1 for IP literal`, { hostOrUrl });
+    }
+    if (!result.domain) {
+        throw new EtldComputationError(`No PSL match for hostname`, { hostOrUrl });
+    }
+    return (0, canonicalize_1.canonicalizeHost)(result.domain);
+}
+/**
+ * Convenience: do two hostnames share an eTLD+1? Returns false when either
+ * input has no PSL match (rather than throwing) — callers comparing two
+ * hostnames typically want a non-match boolean, not an exception.
+ */
+function sameEtldPlusOne(a, b) {
+    let aEtld;
+    let bEtld;
+    try {
+        aEtld = eTldPlusOne(a);
+        bEtld = eTldPlusOne(b);
+    }
+    catch {
+        return false;
+    }
+    return aEtld === bEtld;
+}
+function extractHost(hostOrUrl) {
+    if (hostOrUrl.includes('://')) {
+        return new URL(hostOrUrl).hostname;
+    }
+    return hostOrUrl;
+}
+//# sourceMappingURL=etld.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"etld.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/etld.ts"],"names":[],"mappings":";;;AAuCA,kCAUC;AAOD,0CAUC;AAlED;;;;;;;;;;;;;;GAcG;AACH,iCAA0C;AAE1C,iDAAkD;AAErC,QAAA,oBAAoB,GAAG,SAAS,CAAC;AAE9C,MAAa,oBAAqB,SAAQ,KAAK;IAGlC;IAFX,YACE,OAAe,EACN,IAA4B;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,SAAI,GAAJ,IAAI,CAAwB;QAGrC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AARD,oDAQC;AAED;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAC,SAAiB;IAC3C,MAAM,IAAI,GAAG,IAAA,+BAAgB,EAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,IAAA,aAAQ,EAAC,IAAI,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,oBAAoB,CAAC,sCAAsC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,oBAAoB,CAAC,2BAA2B,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,IAAA,+BAAgB,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAAC,CAAS,EAAE,CAAS;IAClD,IAAI,KAAa,CAAC;IAClB,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QACvB,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,KAAK,KAAK,CAAC;AACzB,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC;IACrC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/lib/signing/agent-resolver/fetch-helpers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SSRF-safe HTTPS fetches for the brand_json_url discovery chain. Wraps
+ * `ssrfSafeFetch` with the spec's body caps and the strict-JSON parser.
+ * No redirects, no caching here — that's the resolver's responsibility
+ * one layer up.
+ *
+ * Error translation lives here too: `SsrfRefusedError`'s `address` /
+ * `hostname` fields MUST NOT propagate onto `AgentResolverError.detail`
+ * (internal-topology leak). We surface the `code` only.
+ */
+export declare const MAX_CAPABILITIES_BYTES = 65536;
+export declare const MAX_BRAND_JSON_BYTES = 262144;
+export declare const MAX_JWKS_BYTES = 65536;
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+export declare const DEFAULT_TOTAL_TIMEOUT_MS = 10000;
+export type FetchKind = 'capabilities' | 'brand.json' | 'jwks';
+export declare class SafeFetchError extends Error {
+    readonly kind: FetchKind;
+    readonly httpStatus: number | undefined;
+    readonly transport: 'fetch_failed' | 'timeout' | 'dns_error' | 'ssrf_refused' | 'body_cap';
+    constructor(kind: FetchKind, transport: SafeFetchError['transport'], message: string, httpStatus?: number);
+}
+export interface SafeFetchJsonResult {
+    body: unknown;
+    status: number;
+    headers: Record<string, string>;
+    fetchedAt: number;
+}
+/**
+ * Fetch a JSON document under the spec's SSRF rules with a hard body cap and
+ * the strict-JSON parser. Network errors, body-cap overruns, and JSON parse
+ * errors are translated to a typed `SafeFetchError` so the resolver can map
+ * each onto a `request_signature_*` code without inspecting the underlying
+ * cause.
+ */
+export declare function safeFetchJson(url: string, kind: FetchKind, options: {
+    allowPrivateIp?: boolean;
+    timeoutMs?: number;
+    maxBodyBytes: number;
+}): Promise<SafeFetchJsonResult>;
+//# sourceMappingURL=fetch-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-helpers.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/fetch-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAC5C,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAChD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAE/D,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,CAAC;gBAC/E,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAO1G;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,EACf,OAAO,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC9E,OAAO,CAAC,mBAAmB,CAAC,CA4C9B"}

package/dist/lib/signing/agent-resolver/fetch-helpers.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * SSRF-safe HTTPS fetches for the brand_json_url discovery chain. Wraps
+ * `ssrfSafeFetch` with the spec's body caps and the strict-JSON parser.
+ * No redirects, no caching here — that's the resolver's responsibility
+ * one layer up.
+ *
+ * Error translation lives here too: `SsrfRefusedError`'s `address` /
+ * `hostname` fields MUST NOT propagate onto `AgentResolverError.detail`
+ * (internal-topology leak). We surface the `code` only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafeFetchError = exports.DEFAULT_TOTAL_TIMEOUT_MS = exports.DEFAULT_CONNECT_TIMEOUT_MS = exports.MAX_JWKS_BYTES = exports.MAX_BRAND_JSON_BYTES = exports.MAX_CAPABILITIES_BYTES = void 0;
+exports.safeFetchJson = safeFetchJson;
+const net_1 = require("../../net");
+const strict_json_1 = require("./strict-json");
+exports.MAX_CAPABILITIES_BYTES = 65_536;
+exports.MAX_BRAND_JSON_BYTES = 262_144;
+exports.MAX_JWKS_BYTES = 65_536;
+exports.DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
+exports.DEFAULT_TOTAL_TIMEOUT_MS = 10_000;
+class SafeFetchError extends Error {
+    kind;
+    httpStatus;
+    transport;
+    constructor(kind, transport, message, httpStatus) {
+        super(message);
+        this.name = 'SafeFetchError';
+        this.kind = kind;
+        this.transport = transport;
+        this.httpStatus = httpStatus;
+    }
+}
+exports.SafeFetchError = SafeFetchError;
+/**
+ * Fetch a JSON document under the spec's SSRF rules with a hard body cap and
+ * the strict-JSON parser. Network errors, body-cap overruns, and JSON parse
+ * errors are translated to a typed `SafeFetchError` so the resolver can map
+ * each onto a `request_signature_*` code without inspecting the underlying
+ * cause.
+ */
+async function safeFetchJson(url, kind, options) {
+    const fetchOpts = {
+        method: 'GET',
+        headers: { accept: 'application/json' },
+        allowPrivateIp: options.allowPrivateIp === true,
+        timeoutMs: options.timeoutMs ?? exports.DEFAULT_TOTAL_TIMEOUT_MS,
+        maxBodyBytes: options.maxBodyBytes,
+    };
+    let res;
+    try {
+        res = await (0, net_1.ssrfSafeFetch)(url, fetchOpts);
+    }
+    catch (err) {
+        if (err instanceof net_1.SsrfRefusedError) {
+            throw new SafeFetchError(kind, 'ssrf_refused', `${kind} fetch refused: ${err.code}`);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        if (/abort|timed?\s*out/i.test(message)) {
+            throw new SafeFetchError(kind, 'timeout', `${kind} fetch timed out`);
+        }
+        throw new SafeFetchError(kind, 'fetch_failed', `${kind} fetch failed`);
+    }
+    if (res.status < 200 || res.status >= 300) {
+        throw new SafeFetchError(kind, 'fetch_failed', `${kind} fetch returned HTTP ${res.status}`, res.status);
+    }
+    let parsed;
+    try {
+        const text = Buffer.from(res.body).toString('utf8');
+        parsed = (0, strict_json_1.parseStrictJson)(text);
+    }
+    catch (err) {
+        if (err instanceof strict_json_1.StrictJsonError) {
+            throw new SafeFetchError(kind, 'fetch_failed', `${kind} body failed strict-JSON parse: ${err.code}`);
+        }
+        throw new SafeFetchError(kind, 'fetch_failed', `${kind} body parse failed`);
+    }
+    return {
+        body: parsed,
+        status: res.status,
+        headers: res.headers,
+        fetchedAt: Math.floor(Date.now() / 1000),
+    };
+}
+//# sourceMappingURL=fetch-helpers.js.map

package/dist/lib/signing/agent-resolver/fetch-helpers.js.map

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

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

@@ -0,0 +1,26 @@
+/**
+ * Brand-JSON-URL agent resolver — bootstraps from an agent URL to its
+ * signing keys via the 8-step algorithm in `security.mdx` §"Discovering
+ * an agent's signing keys via `brand_json_url`".
+ *
+ * Public exports for `@adcp/client`:
+ *
+ *   - `resolveAgent(url, opts)`       — full chain + per-step trace
+ *   - `getAgentJwks(url, opts)`       — JWKS-only fast path (stage 4)
+ *   - `createAgentJwksSet(url, opts)` — JOSE-compatible JWTVerifyGetKey factory (stage 4)
+ *   - `AgentResolverError`            — typed error with `request_signature_*` codes
+ *   - `attackerInfluencedFields`      — names of `detail` fields admin UIs MUST escape
+ *
+ * Pure-function primitives (`eTldPlusOne`, `canonicalizeOrigin`,
+ * `selectAgentByUrl`, etc.) are exported under `agent-resolver/primitives`
+ * for callers building bespoke verification flows on top of this module.
+ */
+export { resolveAgent } from './resolve-agent';
+export type { AgentResolution, AgentProtocol, FetchCapabilitiesFn, ResolveAgentOptions, TraceStep, } from './resolve-agent';
+export { getAgentJwks, createAgentJwksSet } from './jwks-set';
+export type { AgentJwksResult, GetAgentJwksOptions, CreateAgentJwksSetOptions } from './jwks-set';
+export { AgentResolverError, ATTACKER_INFLUENCED, attackerInfluencedFields, type AgentResolverErrorCode, type AgentResolverErrorDetail, } from './errors';
+export type { AgentEntry } from './select-agent';
+export type { CapabilitiesWithBrandJsonUrl, IdentityKeyOriginPurpose, IdentityKeyOrigins, IdentityPosture, } from './capabilities-types';
+export { readBrandJsonUrl, readIdentityPosture } from './capabilities-types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EACV,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC9D,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAClG,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,4BAA4B,EAC5B,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}

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

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Brand-JSON-URL agent resolver — bootstraps from an agent URL to its
+ * signing keys via the 8-step algorithm in `security.mdx` §"Discovering
+ * an agent's signing keys via `brand_json_url`".
+ *
+ * Public exports for `@adcp/client`:
+ *
+ *   - `resolveAgent(url, opts)`       — full chain + per-step trace
+ *   - `getAgentJwks(url, opts)`       — JWKS-only fast path (stage 4)
+ *   - `createAgentJwksSet(url, opts)` — JOSE-compatible JWTVerifyGetKey factory (stage 4)
+ *   - `AgentResolverError`            — typed error with `request_signature_*` codes
+ *   - `attackerInfluencedFields`      — names of `detail` fields admin UIs MUST escape
+ *
+ * Pure-function primitives (`eTldPlusOne`, `canonicalizeOrigin`,
+ * `selectAgentByUrl`, etc.) are exported under `agent-resolver/primitives`
+ * for callers building bespoke verification flows on top of this module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readIdentityPosture = exports.readBrandJsonUrl = exports.attackerInfluencedFields = exports.ATTACKER_INFLUENCED = exports.AgentResolverError = exports.createAgentJwksSet = exports.getAgentJwks = exports.resolveAgent = void 0;
+var resolve_agent_1 = require("./resolve-agent");
+Object.defineProperty(exports, "resolveAgent", { enumerable: true, get: function () { return resolve_agent_1.resolveAgent; } });
+var jwks_set_1 = require("./jwks-set");
+Object.defineProperty(exports, "getAgentJwks", { enumerable: true, get: function () { return jwks_set_1.getAgentJwks; } });
+Object.defineProperty(exports, "createAgentJwksSet", { enumerable: true, get: function () { return jwks_set_1.createAgentJwksSet; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AgentResolverError", { enumerable: true, get: function () { return errors_1.AgentResolverError; } });
+Object.defineProperty(exports, "ATTACKER_INFLUENCED", { enumerable: true, get: function () { return errors_1.ATTACKER_INFLUENCED; } });
+Object.defineProperty(exports, "attackerInfluencedFields", { enumerable: true, get: function () { return errors_1.attackerInfluencedFields; } });
+var capabilities_types_1 = require("./capabilities-types");
+Object.defineProperty(exports, "readBrandJsonUrl", { enumerable: true, get: function () { return capabilities_types_1.readBrandJsonUrl; } });
+Object.defineProperty(exports, "readIdentityPosture", { enumerable: true, get: function () { return capabilities_types_1.readIdentityPosture; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAQrB,uCAA8D;AAArD,wGAAA,YAAY,OAAA;AAAE,8GAAA,kBAAkB,OAAA;AAEzC,mCAMkB;AALhB,4GAAA,kBAAkB,OAAA;AAClB,6GAAA,mBAAmB,OAAA;AACnB,kHAAA,wBAAwB,OAAA;AAW1B,2DAA6E;AAApE,sHAAA,gBAAgB,OAAA;AAAE,yHAAA,mBAAmB,OAAA"}

package/dist/lib/signing/agent-resolver/jwks-set.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Convenience surfaces over `resolveAgent`:
+ *
+ *   - `getAgentJwks(url, opts)` — JWKS-only fast path. Skips the trace
+ *     assembly the full resolver returns; callers who only need keys for
+ *     a verifier don't have to filter the larger record.
+ *
+ *   - `createAgentJwksSet(url, opts)` — returns a `JWTVerifyGetKey`-shaped
+ *     async function compatible with `jose.jwtVerify`'s `getKey` parameter.
+ *     Caches the resolved JWKS per `cacheMaxAgeSeconds`; refetches on a
+ *     `kid` miss subject to the spec's 30-second cooldown
+ *     (security.mdx §"Verifier checklist (requests)" step 7's refetch
+ *     guidance). Enforces the caller-supplied algorithm allowlist at JWKS
+ *     import time AND on the verify call — defense-in-depth against the
+ *     "alg: HS256" confusion vector. The allowlist is REQUIRED; there is
+ *     no library default.
+ */
+import { type JWTVerifyGetKey } from 'jose';
+import { type ResolveAgentOptions } from './resolve-agent';
+export type GetAgentJwksOptions = Pick<ResolveAgentOptions, 'protocol' | 'fetchCapabilities' | 'allowPrivateIp' | 'timeoutMs' | 'now'>;
+export interface AgentJwksResult {
+    agentUrl: string;
+    brandJsonUrl: string;
+    jwksUri: string;
+    jwks: {
+        keys: ReadonlyArray<Record<string, unknown>>;
+    };
+    cacheControl?: string;
+    fetchedAt: number;
+}
+/**
+ * Fast path: returns the JWKS plus the URIs that produced it. Skips the
+ * trace + freshness aggregate the full `resolveAgent` returns. Errors
+ * propagate as `AgentResolverError` with the same `request_signature_*`
+ * codes — the JWKS fast path is not a separate trust chain.
+ */
+export declare function getAgentJwks(agentUrl: string, options?: GetAgentJwksOptions): Promise<AgentJwksResult>;
+export interface CreateAgentJwksSetOptions extends Pick<ResolveAgentOptions, 'protocol' | 'fetchCapabilities' | 'allowPrivateIp' | 'timeoutMs' | 'now'> {
+    /**
+     * Algorithm allowlist enforced at JWKS-import time AND surfaced to
+     * `jose.jwtVerify`'s `algorithms` option. Required — there is no default.
+     * The classic confusion vector is `alg: HS256` against a public-key JWK,
+     * which jose's verifier would reject — but a library that pre-imports
+     * keys without an allowlist still leaves the door open to JWKs whose
+     * declared `alg` doesn't match the verifier's expectation. Requiring the
+     * caller to name the algorithms closes the door at every layer.
+     *
+     * Use a tight set: `["EdDSA"]` for Ed25519-only deployments;
+     * `["EdDSA", "ES256"]` for the AdCP request-signing default pair.
+     */
+    allowedAlgs: readonly string[];
+    /**
+     * Max age in seconds before a forced refetch of the JWKS. Default 300s
+     * (5 minutes). Bound this above by your operator's revocation polling
+     * interval — a longer cache mask key rotation; a shorter cache costs
+     * extra fetches without buying you anything.
+     */
+    cacheMaxAgeSeconds?: number;
+    /**
+     * Minimum interval between JWKS refetches when a `kid` miss triggers a
+     * refresh. Default 30s — matches the spec's cooldown rule for the
+     * verifier checklist's step-7 refetch.
+     */
+    kidMissCooldownSeconds?: number;
+}
+/**
+ * Build a `JWTVerifyGetKey` that runs the brand_json_url discovery chain on
+ * first use, caches the resolved JWKS, refetches on cache expiry, and
+ * refetches once on a `kid` miss subject to a 30s cooldown. Imports each
+ * JWK and rejects any whose `alg` (when declared) is outside `allowedAlgs`.
+ *
+ * The returned function is compatible with `jose.jwtVerify` — pass it as
+ * `getKey` and pair with `algorithms: opts.allowedAlgs` on the verify call.
+ */
+export declare function createAgentJwksSet(agentUrl: string, options: CreateAgentJwksSetOptions): JWTVerifyGetKey;
+//# sourceMappingURL=jwks-set.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-set.d.ts","sourceRoot":"","sources":["../../../../src/lib/signing/agent-resolver/jwks-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,MAAM,CAAC;AAGzE,OAAO,EAAsC,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE/F,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,mBAAmB,EACnB,UAAU,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,WAAW,GAAG,KAAK,CAC1E,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,eAAe,CAAC,CAUhH;AAED,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CACrD,mBAAmB,EACnB,UAAU,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,WAAW,GAAG,KAAK,CAC1E;IACC;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAYD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,eAAe,CAqDxG"}

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

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Convenience surfaces over `resolveAgent`:
+ *
+ *   - `getAgentJwks(url, opts)` — JWKS-only fast path. Skips the trace
+ *     assembly the full resolver returns; callers who only need keys for
+ *     a verifier don't have to filter the larger record.
+ *
+ *   - `createAgentJwksSet(url, opts)` — returns a `JWTVerifyGetKey`-shaped
+ *     async function compatible with `jose.jwtVerify`'s `getKey` parameter.
+ *     Caches the resolved JWKS per `cacheMaxAgeSeconds`; refetches on a
+ *     `kid` miss subject to the spec's 30-second cooldown
+ *     (security.mdx §"Verifier checklist (requests)" step 7's refetch
+ *     guidance). Enforces the caller-supplied algorithm allowlist at JWKS
+ *     import time AND on the verify call — defense-in-depth against the
+ *     "alg: HS256" confusion vector. The allowlist is REQUIRED; there is
+ *     no library default.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgentJwks = getAgentJwks;
+exports.createAgentJwksSet = createAgentJwksSet;
+const jose_1 = require("jose");
+const errors_1 = require("./errors");
+const resolve_agent_1 = require("./resolve-agent");
+/**
+ * Fast path: returns the JWKS plus the URIs that produced it. Skips the
+ * trace + freshness aggregate the full `resolveAgent` returns. Errors
+ * propagate as `AgentResolverError` with the same `request_signature_*`
+ * codes — the JWKS fast path is not a separate trust chain.
+ */
+async function getAgentJwks(agentUrl, options = {}) {
+    const resolution = await (0, resolve_agent_1.resolveAgent)(agentUrl, options);
+    return {
+        agentUrl: resolution.agentUrl,
+        brandJsonUrl: resolution.brandJsonUrl,
+        jwksUri: resolution.jwksUri,
+        jwks: resolution.jwks,
+        ...(resolution.jwksCacheControl !== undefined && { cacheControl: resolution.jwksCacheControl }),
+        fetchedAt: resolution.freshness.jwksFetchedAt,
+    };
+}
+const DEFAULT_CACHE_MAX_AGE_SECONDS = 300;
+const DEFAULT_KID_MISS_COOLDOWN_SECONDS = 30;
+/**
+ * Build a `JWTVerifyGetKey` that runs the brand_json_url discovery chain on
+ * first use, caches the resolved JWKS, refetches on cache expiry, and
+ * refetches once on a `kid` miss subject to a 30s cooldown. Imports each
+ * JWK and rejects any whose `alg` (when declared) is outside `allowedAlgs`.
+ *
+ * The returned function is compatible with `jose.jwtVerify` — pass it as
+ * `getKey` and pair with `algorithms: opts.allowedAlgs` on the verify call.
+ */
+function createAgentJwksSet(agentUrl, options) {
+    if (!options.allowedAlgs || options.allowedAlgs.length === 0) {
+        throw new TypeError(`createAgentJwksSet requires non-empty allowedAlgs — refusing to verify against an open algorithm set`);
+    }
+    const allowedAlgs = new Set(options.allowedAlgs);
+    const cacheMaxAge = options.cacheMaxAgeSeconds ?? DEFAULT_CACHE_MAX_AGE_SECONDS;
+    const kidCooldown = options.kidMissCooldownSeconds ?? DEFAULT_KID_MISS_COOLDOWN_SECONDS;
+    const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    let cache;
+    let lastRefetchAt = 0;
+    let inFlight;
+    const refresh = async () => {
+        if (inFlight)
+            return inFlight;
+        inFlight = (async () => {
+            const resolution = await (0, resolve_agent_1.resolveAgent)(agentUrl, options);
+            assertAllJwksAllowed(resolution.jwks, allowedAlgs, agentUrl);
+            const filtered = filterJwksToAllowedAlgs(resolution.jwks, allowedAlgs);
+            const getKey = (0, jose_1.createLocalJWKSet)({ keys: filtered });
+            cache = { resolution, fetchedAt: now(), getKey };
+            lastRefetchAt = cache.fetchedAt;
+            return cache;
+        })().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    const ensureFresh = async () => {
+        if (!cache || now() - cache.fetchedAt >= cacheMaxAge) {
+            return refresh();
+        }
+        return cache;
+    };
+    const getKey = async (protectedHeader, token) => {
+        const fresh = await ensureFresh();
+        try {
+            return await fresh.getKey(protectedHeader, token);
+        }
+        catch (err) {
+            // Likely cause: kid miss (key rotated). Subject to the cooldown,
+            // refetch once and retry — same logic the spec's verifier checklist
+            // applies between the agent-URL preamble and the kid resolution.
+            if (now() - lastRefetchAt < kidCooldown)
+                throw err;
+            const refreshed = await refresh();
+            return refreshed.getKey(protectedHeader, token);
+        }
+    };
+    return getKey;
+}
+/**
+ * Reject every JWK whose declared `alg` is outside the allowlist. This is
+ * the import-time half of the defense-in-depth pair against alg-confusion
+ * attacks; the verify-time half is the caller passing `algorithms` to
+ * `jose.jwtVerify`. Malformed-JWK detection is left to `createLocalJWKSet`
+ * + `jose.jwtVerify` at verify time — running an async smoke-import here
+ * would be fire-and-forget and swallow rejections.
+ */
+function assertAllJwksAllowed(jwks, allowedAlgs, agentUrl) {
+    for (const jwk of jwks.keys) {
+        const declared = jwk.alg;
+        if (typeof declared === 'string' && !allowedAlgs.has(declared)) {
+            throw new errors_1.AgentResolverError('request_signature_jwks_alg_disallowed', `Agent JWKS contains key with alg=${declared} not in allowedAlgs`, { agent_url: agentUrl }, ['agent_url']);
+        }
+    }
+}
+function filterJwksToAllowedAlgs(jwks, allowedAlgs) {
+    // Keep keys without a declared `alg` (jose still gates by the verifier's
+    // `algorithms` option) and keys whose declared `alg` is in the allowlist.
+    return jwks.keys.filter(jwk => typeof jwk.alg !== 'string' || allowedAlgs.has(jwk.alg));
+}
+//# sourceMappingURL=jwks-set.js.map