@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/server/index.d.mts

@@ -83,8 +83,8 @@ export { createPinAndBindFetch, WEBHOOK_SSRF_POLICY, LOOPBACK_OK_WEBHOOK_SSRF_PO
 export type { PinAndBindFetchOptions, DnsLookupAll } from './pin-and-bind-fetch.mjs';
 export { checkGovernance, createAdcpGovernanceEnforcementMiddleware, governanceDeniedError, governanceUnavailableError, } from './governance.mjs';
 export type { AdcpGovernanceEnforcementMiddleware, CheckGovernanceOptions, GovernanceCallResult, GovernanceApproved, GovernanceDenied, GovernanceConditions, } from './governance.mjs';
-export { GovernanceAuthorizationError, GovernanceReplayStoreAdapter, InMemoryGovernanceReplayStore, buildGovernanceExecutionCommitment, buildGovernanceExecutionRequest, computeGovernedPayloadHash, createGovernanceEnforcementMiddleware, verifyGovernanceAuthorization, } from '../governance/index.mjs';
-export type { BuildGovernanceExecutionRequestInput, GovernanceAuthorizationClaims, GovernanceAuthorizationErrorCode, GovernanceAuthorizationResult, GovernanceAuthorizationSuccess, GovernanceCommitment, GovernanceEnforcementMiddleware, GovernanceEnforcementMiddlewareConfig, GovernanceEnforcementMiddlewareInput, GovernanceReplayStore, GovernanceReplayBinding, GovernanceRevocationResolver, GovernanceRevocationStatus, VerifyGovernanceAuthorizationOptions, } from '../governance/index.mjs';
+export { GovernanceAuthorizationError, GovernanceReplayStoreAdapter, InMemoryGovernanceReplayStore, buildGovernanceExecutionCommitment, buildGovernanceExecutionRequest, computeGovernedPayloadHash, createGovernanceEnforcementMiddleware, verifyGovernanceAuthorization, createGovernanceAgentJwksResolver, } from '../governance/index.mjs';
+export type { BuildGovernanceExecutionRequestInput, GovernanceAuthorizationClaims, GovernanceAuthorizationErrorCode, GovernanceAuthorizationResult, GovernanceAuthorizationSuccess, GovernanceCommitment, GovernanceEnforcementMiddleware, GovernanceEnforcementMiddlewareConfig, GovernanceEnforcementMiddlewareInput, GovernanceReplayStore, GovernanceReplayBinding, GovernanceRevocationResolver, GovernanceRevocationStatus, VerifyGovernanceAuthorizationOptions, GovernanceBuyerIdentity, } from '../governance/index.mjs';
 export { clearDefaultResolvedListCache, createResolvedListCache, DEFAULT_RESOLVE_LIST_PAGE_SIZE, defaultResolvedListCache, resolvePropertyList, resolveCollectionList, resolvedListCacheKey, matchesPropertyList, matchesCollectionList, } from './targeting-helpers.mjs';
 export type { ResolvedListCache, ResolvedListCacheEntry, ResolvedListCacheValue, ResolvedListKind, ResolvedPropertyList, ResolvedCollectionList, ResolvedCollection, ResolveListCallTool, ResolveListOptions, } from './targeting-helpers.mjs';
 export * from './decisioning/index.mjs';

package/dist/lib/server/index.d.ts

@@ -83,8 +83,8 @@ export { createPinAndBindFetch, WEBHOOK_SSRF_POLICY, LOOPBACK_OK_WEBHOOK_SSRF_PO
 export type { PinAndBindFetchOptions, DnsLookupAll } from './pin-and-bind-fetch';
 export { checkGovernance, createAdcpGovernanceEnforcementMiddleware, governanceDeniedError, governanceUnavailableError, } from './governance';
 export type { AdcpGovernanceEnforcementMiddleware, CheckGovernanceOptions, GovernanceCallResult, GovernanceApproved, GovernanceDenied, GovernanceConditions, } from './governance';
-export { GovernanceAuthorizationError, GovernanceReplayStoreAdapter, InMemoryGovernanceReplayStore, buildGovernanceExecutionCommitment, buildGovernanceExecutionRequest, computeGovernedPayloadHash, createGovernanceEnforcementMiddleware, verifyGovernanceAuthorization, } from '../governance';
-export type { BuildGovernanceExecutionRequestInput, GovernanceAuthorizationClaims, GovernanceAuthorizationErrorCode, GovernanceAuthorizationResult, GovernanceAuthorizationSuccess, GovernanceCommitment, GovernanceEnforcementMiddleware, GovernanceEnforcementMiddlewareConfig, GovernanceEnforcementMiddlewareInput, GovernanceReplayStore, GovernanceReplayBinding, GovernanceRevocationResolver, GovernanceRevocationStatus, VerifyGovernanceAuthorizationOptions, } from '../governance';
+export { GovernanceAuthorizationError, GovernanceReplayStoreAdapter, InMemoryGovernanceReplayStore, buildGovernanceExecutionCommitment, buildGovernanceExecutionRequest, computeGovernedPayloadHash, createGovernanceEnforcementMiddleware, verifyGovernanceAuthorization, createGovernanceAgentJwksResolver, } from '../governance';
+export type { BuildGovernanceExecutionRequestInput, GovernanceAuthorizationClaims, GovernanceAuthorizationErrorCode, GovernanceAuthorizationResult, GovernanceAuthorizationSuccess, GovernanceCommitment, GovernanceEnforcementMiddleware, GovernanceEnforcementMiddlewareConfig, GovernanceEnforcementMiddlewareInput, GovernanceReplayStore, GovernanceReplayBinding, GovernanceRevocationResolver, GovernanceRevocationStatus, VerifyGovernanceAuthorizationOptions, GovernanceBuyerIdentity, } from '../governance';
 export { clearDefaultResolvedListCache, createResolvedListCache, DEFAULT_RESOLVE_LIST_PAGE_SIZE, defaultResolvedListCache, resolvePropertyList, resolveCollectionList, resolvedListCacheKey, matchesPropertyList, matchesCollectionList, } from './targeting-helpers';
 export type { ResolvedListCache, ResolvedListCacheEntry, ResolvedListCacheValue, ResolvedListKind, ResolvedPropertyList, ResolvedCollectionList, ResolvedCollection, ResolveListCallTool, ResolveListOptions, } from './targeting-helpers';
 export * from './decisioning';

package/dist/lib/server/index.js

@@ -112,6 +112,7 @@ __export(server_exports, {
   createDerivedAccountStore: () => import_derived_account_store.createDerivedAccountStore,
   createDynamicRegistry: () => import_dynamic_registry.createDynamicRegistry,
   createExpressAdapter: () => import_express_adapter.createExpressAdapter,
+  createGovernanceAgentJwksResolver: () => import_governance2.createGovernanceAgentJwksResolver,
   createGovernanceEnforcementMiddleware: () => import_governance2.createGovernanceEnforcementMiddleware,
   createIdempotencyStore: () => import_idempotency.createIdempotencyStore,
   createLazyBackend: () => import_idempotency.createLazyBackend,
@@ -439,6 +440,7 @@ var import_media_buy_action_resolver = require('./media-buy-action-resolver.js')
   createDerivedAccountStore,
   createDynamicRegistry,
   createExpressAdapter,
+  createGovernanceAgentJwksResolver,
   createGovernanceEnforcementMiddleware,
   createIdempotencyStore,
   createLazyBackend,

package/dist/lib/server/index.mjs

@@ -234,7 +234,8 @@ import {
   buildGovernanceExecutionRequest,
   computeGovernedPayloadHash,
   createGovernanceEnforcementMiddleware,
-  verifyGovernanceAuthorization
+  verifyGovernanceAuthorization,
+  createGovernanceAgentJwksResolver
 } from "../governance/index.mjs";
 import {
   clearDefaultResolvedListCache,
@@ -387,6 +388,7 @@ export {
   createDerivedAccountStore,
   createDynamicRegistry,
   createExpressAdapter,
+  createGovernanceAgentJwksResolver,
   createGovernanceEnforcementMiddleware,
   createIdempotencyStore,
   createLazyBackend,

package/dist/lib/signing/agent-resolver/consistency.d.mts

@@ -5,9 +5,8 @@
  *
  *   `request_signature_key_origin_mismatch` — the resolved `jwks_uri` host
  *     does not match the operator's declared `identity.key_origins.{purpose}`
- *     value. Skipped only for the specific (agent, purpose, role) tuple
- *     whose JWKS source was a publisher `adagents.json signing_keys` pin —
- *     operator-side use of the same purpose is still checked.
+ *     value. Publisher pins never skip this check because they only narrow
+ *     keys in the operator's JWKS.
  *
  *   `request_signature_key_origin_missing` — the agent's capabilities
  *     declare a signing posture for a purpose (e.g. `request_signing.supported_for`
@@ -36,24 +35,18 @@ export interface KeyOriginMissing {
 export type ConsistencyResult = {
     ok: true;
 } | KeyOriginMismatch | KeyOriginMissing;
-/**
- * Inputs for the per-purpose origin check. The caller is responsible for
- * deciding whether `publisherPinned` is true — the carve-out applies only
- * to (agent, webhook-signing, sell-side) tuples whose JWKS came from an
- * `adagents.json signing_keys` pin. For request-signing, governance-signing,
- * TMP-signing, and buyer-side webhook receivers, `publisherPinned` MUST
- * always be false.
- */
+/** Inputs for the per-purpose origin check. Publisher pin markers are ignored. */
 export interface OriginCheckInput {
     purpose: IdentityKeyOriginPurpose;
     declaredOrigin: string | undefined;
     resolvedJwksUri: string;
-    publisherPinned: boolean;
+    /** @deprecated Pins narrow JWKS keys and never bypass origin checks. */
+    publisherPinned?: boolean;
 }
 /**
  * Check origin consistency for a single (purpose, jwksUri) pair against the
  * declared `identity.key_origins.{purpose}` value. Returns `{ ok: true }`
- * when the check passes or is skipped (publisher pin); a typed mismatch
+ * when the check passes; a typed mismatch
  * result on failure. `key_origin_missing` is NOT raised here — that is a
  * separate check (`checkRequiredOrigins`) because it depends on which
  * purposes the agent has declared signing for.

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

@@ -5,9 +5,8 @@
  *
  *   `request_signature_key_origin_mismatch` — the resolved `jwks_uri` host
  *     does not match the operator's declared `identity.key_origins.{purpose}`
- *     value. Skipped only for the specific (agent, purpose, role) tuple
- *     whose JWKS source was a publisher `adagents.json signing_keys` pin —
- *     operator-side use of the same purpose is still checked.
+ *     value. Publisher pins never skip this check because they only narrow
+ *     keys in the operator's JWKS.
  *
  *   `request_signature_key_origin_missing` — the agent's capabilities
  *     declare a signing posture for a purpose (e.g. `request_signing.supported_for`
@@ -36,24 +35,18 @@ export interface KeyOriginMissing {
 export type ConsistencyResult = {
     ok: true;
 } | KeyOriginMismatch | KeyOriginMissing;
-/**
- * Inputs for the per-purpose origin check. The caller is responsible for
- * deciding whether `publisherPinned` is true — the carve-out applies only
- * to (agent, webhook-signing, sell-side) tuples whose JWKS came from an
- * `adagents.json signing_keys` pin. For request-signing, governance-signing,
- * TMP-signing, and buyer-side webhook receivers, `publisherPinned` MUST
- * always be false.
- */
+/** Inputs for the per-purpose origin check. Publisher pin markers are ignored. */
 export interface OriginCheckInput {
     purpose: IdentityKeyOriginPurpose;
     declaredOrigin: string | undefined;
     resolvedJwksUri: string;
-    publisherPinned: boolean;
+    /** @deprecated Pins narrow JWKS keys and never bypass origin checks. */
+    publisherPinned?: boolean;
 }
 /**
  * Check origin consistency for a single (purpose, jwksUri) pair against the
  * declared `identity.key_origins.{purpose}` value. Returns `{ ok: true }`
- * when the check passes or is skipped (publisher pin); a typed mismatch
+ * when the check passes; a typed mismatch
  * result on failure. `key_origin_missing` is NOT raised here — that is a
  * separate check (`checkRequiredOrigins`) because it depends on which
  * purposes the agent has declared signing for.

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

@@ -25,7 +25,6 @@ __export(consistency_exports, {
 module.exports = __toCommonJS(consistency_exports);
 var import_canonicalize = require('./canonicalize.js');
 function checkOriginConsistency(input) {
-  if (input.publisherPinned) return { ok: true };
   if (!input.declaredOrigin) return { ok: true };
   let expected;
   let actual;

package/dist/lib/signing/agent-resolver/consistency.mjs

@@ -1,6 +1,5 @@
 import { canonicalizeOrigin } from "./canonicalize.mjs";
 function checkOriginConsistency(input) {
-  if (input.publisherPinned) return { ok: true };
   if (!input.declaredOrigin) return { ok: true };
   let expected;
   let actual;

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

@@ -17,7 +17,7 @@
  *     `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' | 'request_signature_jwks_unavailable' | 'request_signature_jwks_untrusted' | 'request_signature_key_purpose_invalid';
+export type AgentResolverErrorCode = 'request_signature_brand_json_url_missing' | 'request_signature_key_unknown' | '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' | 'request_signature_jwks_unavailable' | 'request_signature_jwks_untrusted' | 'request_signature_key_purpose_invalid';
 export interface AgentResolverErrorDetail {
     agent_url?: string;
     brand_json_url?: string;
@@ -46,6 +46,8 @@ export interface AgentResolverErrorDetail {
 export declare class AgentResolverError extends Error {
     readonly code: AgentResolverErrorCode;
     readonly detail: AgentResolverErrorDetail;
+    /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
     readonly [ATTACKER_INFLUENCED]: ReadonlyArray<keyof AgentResolverErrorDetail>;
     constructor(code: AgentResolverErrorCode, message: string, detail?: AgentResolverErrorDetail, attackerInfluencedFields?: ReadonlyArray<keyof AgentResolverErrorDetail>);
 }

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

@@ -17,7 +17,7 @@
  *     `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' | 'request_signature_jwks_unavailable' | 'request_signature_jwks_untrusted' | 'request_signature_key_purpose_invalid';
+export type AgentResolverErrorCode = 'request_signature_brand_json_url_missing' | 'request_signature_key_unknown' | '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' | 'request_signature_jwks_unavailable' | 'request_signature_jwks_untrusted' | 'request_signature_key_purpose_invalid';
 export interface AgentResolverErrorDetail {
     agent_url?: string;
     brand_json_url?: string;
@@ -46,6 +46,8 @@ export interface AgentResolverErrorDetail {
 export declare class AgentResolverError extends Error {
     readonly code: AgentResolverErrorCode;
     readonly detail: AgentResolverErrorDetail;
+    /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
     readonly [ATTACKER_INFLUENCED]: ReadonlyArray<keyof AgentResolverErrorDetail>;
     constructor(code: AgentResolverErrorCode, message: string, detail?: AgentResolverErrorDetail, attackerInfluencedFields?: ReadonlyArray<keyof AgentResolverErrorDetail>);
 }

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

@@ -23,16 +23,22 @@ __export(errors_exports, {
   attackerInfluencedFields: () => attackerInfluencedFields
 });
 module.exports = __toCommonJS(errors_exports);
+var import_fetch_helpers = require('./fetch-helpers.js');
+var import_enums = require('../../types/enums.generated.js');
 const ATTACKER_INFLUENCED = /* @__PURE__ */ Symbol.for("adcp.attacker-influenced");
 class AgentResolverError extends Error {
   code;
   detail;
+  /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+  recovery;
   [ATTACKER_INFLUENCED];
   constructor(code, message, detail = {}, attackerInfluencedFields2 = []) {
     super(message);
     this.name = "AgentResolverError";
     this.code = code;
     this.detail = detail;
+    const discovery = code === "request_signature_capabilities_unreachable" || code === "request_signature_brand_json_unreachable";
+    this.recovery = discovery && (0, import_fetch_helpers.isPermanentDiscoveryFailure)(detail) ? "terminal" : import_enums.RequestSigningErrorCodeMetadata[code].recovery;
     this[ATTACKER_INFLUENCED] = attackerInfluencedFields2;
   }
 }

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

@@ -1,13 +1,19 @@
+import { isPermanentDiscoveryFailure } from "./fetch-helpers.mjs";
+import { RequestSigningErrorCodeMetadata } from "../../types/enums.generated.mjs";
 const ATTACKER_INFLUENCED = /* @__PURE__ */ Symbol.for("adcp.attacker-influenced");
 class AgentResolverError extends Error {
   code;
   detail;
+  /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+  recovery;
   [ATTACKER_INFLUENCED];
   constructor(code, message, detail = {}, attackerInfluencedFields2 = []) {
     super(message);
     this.name = "AgentResolverError";
     this.code = code;
     this.detail = detail;
+    const discovery = code === "request_signature_capabilities_unreachable" || code === "request_signature_brand_json_unreachable";
+    this.recovery = discovery && isPermanentDiscoveryFailure(detail) ? "terminal" : RequestSigningErrorCodeMetadata[code].recovery;
     this[ATTACKER_INFLUENCED] = attackerInfluencedFields2;
   }
 }

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

@@ -8,6 +8,7 @@
  * `hostname` fields MUST NOT propagate onto `AgentResolverError.detail`
  * (internal-topology leak). We surface the `code` only.
  */
+import { type SsrfDnsLookup } from '../../net/index.mjs';
 export declare const MAX_CAPABILITIES_BYTES = 65536;
 export declare const MAX_BRAND_JSON_BYTES = 262144;
 export declare const MAX_JWKS_BYTES = 65536;
@@ -37,4 +38,14 @@ export declare function safeFetchJson(url: string, kind: FetchKind, options: {
     allowPrivateIp?: boolean;
     timeoutMs?: number;
     maxBodyBytes: number;
+    lookup?: SsrfDnsLookup;
 }): Promise<SafeFetchJsonResult>;
+/** Coarse causes only: never expose messages, resolved addresses, or topology. */
+export declare function classifyDiscoveryFailure(error: unknown): {
+    dns_error: SafeFetchError['transport'];
+    http_status?: number;
+};
+export declare function isPermanentDiscoveryFailure(detail: {
+    dns_error?: string;
+    http_status?: number;
+}): boolean;

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

@@ -8,6 +8,7 @@
  * `hostname` fields MUST NOT propagate onto `AgentResolverError.detail`
  * (internal-topology leak). We surface the `code` only.
  */
+import { type SsrfDnsLookup } from '../../net';
 export declare const MAX_CAPABILITIES_BYTES = 65536;
 export declare const MAX_BRAND_JSON_BYTES = 262144;
 export declare const MAX_JWKS_BYTES = 65536;
@@ -37,4 +38,14 @@ export declare function safeFetchJson(url: string, kind: FetchKind, options: {
     allowPrivateIp?: boolean;
     timeoutMs?: number;
     maxBodyBytes: number;
+    lookup?: SsrfDnsLookup;
 }): Promise<SafeFetchJsonResult>;
+/** Coarse causes only: never expose messages, resolved addresses, or topology. */
+export declare function classifyDiscoveryFailure(error: unknown): {
+    dns_error: SafeFetchError['transport'];
+    http_status?: number;
+};
+export declare function isPermanentDiscoveryFailure(detail: {
+    dns_error?: string;
+    http_status?: number;
+}): boolean;

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

@@ -24,10 +24,13 @@ __export(fetch_helpers_exports, {
   MAX_CAPABILITIES_BYTES: () => MAX_CAPABILITIES_BYTES,
   MAX_JWKS_BYTES: () => MAX_JWKS_BYTES,
   SafeFetchError: () => SafeFetchError,
+  classifyDiscoveryFailure: () => classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure: () => isPermanentDiscoveryFailure,
   safeFetchJson: () => safeFetchJson
 });
 module.exports = __toCommonJS(fetch_helpers_exports);
 var import_net = require('../../net/index.js');
+var import_agent_transport_fetch = require('../../net/agent-transport-fetch.js');
 var import_strict_json = require('./strict-json.js');
 const MAX_CAPABILITIES_BYTES = 65536;
 const MAX_BRAND_JSON_BYTES = 262144;
@@ -52,14 +55,19 @@ async function safeFetchJson(url, kind, options) {
     headers: { accept: "application/json" },
     allowPrivateIp: options.allowPrivateIp === true,
     timeoutMs: options.timeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS,
-    maxBodyBytes: options.maxBodyBytes
+    maxBodyBytes: options.maxBodyBytes,
+    lookup: options.lookup
   };
   let res;
   try {
     res = await (0, import_net.ssrfSafeFetch)(url, fetchOpts);
   } catch (err) {
     if (err instanceof import_net.SsrfRefusedError) {
-      throw new SafeFetchError(kind, "ssrf_refused", `${kind} fetch refused: ${err.code}`);
+      throw new SafeFetchError(
+        kind,
+        import_net.SSRF_TRANSIENT_CODES.has(err.code) ? err.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused",
+        `${kind} fetch refused: ${err.code}`
+      );
     }
     const message = err instanceof Error ? err.message : String(err);
     if (/abort|timed?\s*out/i.test(message)) {
@@ -87,6 +95,31 @@ async function safeFetchJson(url, kind, options) {
     fetchedAt: Math.floor(Date.now() / 1e3)
   };
 }
+function classifyDiscoveryFailure(error) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; error && typeof error === "object" && depth < 8 && !seen.has(error); depth++) {
+    seen.add(error);
+    if (error instanceof SafeFetchError)
+      return { dns_error: error.transport, ...error.httpStatus !== void 0 && { http_status: error.httpStatus } };
+    if (error instanceof import_agent_transport_fetch.AgentTransportPolicyError) return { dns_error: "ssrf_refused" };
+    if (error instanceof import_net.SsrfRefusedError)
+      return {
+        dns_error: import_net.SSRF_TRANSIENT_CODES.has(error.code) ? error.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused"
+      };
+    const obj = error;
+    const status = obj.httpStatus ?? obj.status ?? obj.statusCode;
+    if (typeof status === "number" && status >= 400 && status <= 599)
+      return { dns_error: "fetch_failed", http_status: status };
+    if (obj.code === "ENOTFOUND" || obj.code === "EAI_AGAIN") return { dns_error: "dns_error" };
+    if (obj.name === "AbortError" || obj.name === "TimeoutError" || obj.code === "ETIMEDOUT" || typeof obj.code === "string" && obj.code.startsWith("UND_ERR_") && obj.code.endsWith("_TIMEOUT"))
+      return { dns_error: "timeout" };
+    error = obj.cause;
+  }
+  return { dns_error: "fetch_failed" };
+}
+function isPermanentDiscoveryFailure(detail) {
+  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_CONNECT_TIMEOUT_MS,
@@ -95,5 +128,7 @@ async function safeFetchJson(url, kind, options) {
   MAX_CAPABILITIES_BYTES,
   MAX_JWKS_BYTES,
   SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure,
   safeFetchJson
 });

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

@@ -1,4 +1,9 @@
-import { ssrfSafeFetch, SsrfRefusedError } from "../../net/index.mjs";
+import {
+  ssrfSafeFetch,
+  SsrfRefusedError,
+  SSRF_TRANSIENT_CODES
+} from "../../net/index.mjs";
+import { AgentTransportPolicyError } from "../../net/agent-transport-fetch.mjs";
 import { parseStrictJson, StrictJsonError } from "./strict-json.mjs";
 const MAX_CAPABILITIES_BYTES = 65536;
 const MAX_BRAND_JSON_BYTES = 262144;
@@ -23,14 +28,19 @@ async function safeFetchJson(url, kind, options) {
     headers: { accept: "application/json" },
     allowPrivateIp: options.allowPrivateIp === true,
     timeoutMs: options.timeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS,
-    maxBodyBytes: options.maxBodyBytes
+    maxBodyBytes: options.maxBodyBytes,
+    lookup: options.lookup
   };
   let res;
   try {
     res = await ssrfSafeFetch(url, fetchOpts);
   } catch (err) {
     if (err instanceof SsrfRefusedError) {
-      throw new SafeFetchError(kind, "ssrf_refused", `${kind} fetch refused: ${err.code}`);
+      throw new SafeFetchError(
+        kind,
+        SSRF_TRANSIENT_CODES.has(err.code) ? err.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused",
+        `${kind} fetch refused: ${err.code}`
+      );
     }
     const message = err instanceof Error ? err.message : String(err);
     if (/abort|timed?\s*out/i.test(message)) {
@@ -58,6 +68,31 @@ async function safeFetchJson(url, kind, options) {
     fetchedAt: Math.floor(Date.now() / 1e3)
   };
 }
+function classifyDiscoveryFailure(error) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; error && typeof error === "object" && depth < 8 && !seen.has(error); depth++) {
+    seen.add(error);
+    if (error instanceof SafeFetchError)
+      return { dns_error: error.transport, ...error.httpStatus !== void 0 && { http_status: error.httpStatus } };
+    if (error instanceof AgentTransportPolicyError) return { dns_error: "ssrf_refused" };
+    if (error instanceof SsrfRefusedError)
+      return {
+        dns_error: SSRF_TRANSIENT_CODES.has(error.code) ? error.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused"
+      };
+    const obj = error;
+    const status = obj.httpStatus ?? obj.status ?? obj.statusCode;
+    if (typeof status === "number" && status >= 400 && status <= 599)
+      return { dns_error: "fetch_failed", http_status: status };
+    if (obj.code === "ENOTFOUND" || obj.code === "EAI_AGAIN") return { dns_error: "dns_error" };
+    if (obj.name === "AbortError" || obj.name === "TimeoutError" || obj.code === "ETIMEDOUT" || typeof obj.code === "string" && obj.code.startsWith("UND_ERR_") && obj.code.endsWith("_TIMEOUT"))
+      return { dns_error: "timeout" };
+    error = obj.cause;
+  }
+  return { dns_error: "fetch_failed" };
+}
+function isPermanentDiscoveryFailure(detail) {
+  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500;
+}
 export {
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_TOTAL_TIMEOUT_MS,
@@ -65,5 +100,7 @@ export {
   MAX_CAPABILITIES_BYTES,
   MAX_JWKS_BYTES,
   SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure,
   safeFetchJson
 };

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

@@ -58,10 +58,11 @@ function createAgentJwksSet(agentUrl, options) {
   }
   const now = options.now ?? (() => Date.now() / 1e3);
   let cache;
-  let lastRefetchAt = 0;
+  let lastRefetchAt = Number.NEGATIVE_INFINITY;
   let inFlight;
   const refresh = async () => {
     if (inFlight) return inFlight;
+    lastRefetchAt = now();
     inFlight = (async () => {
       const resolution = await (0, import_resolve_agent.resolveAgent)(agentUrl, options);
       const refreshedAt = now();
@@ -85,7 +86,21 @@ function createAgentJwksSet(agentUrl, options) {
     return inFlight;
   };
   const ensureFresh = async () => {
-    if (!cache || now() - cache.fetchedAt >= cacheMaxAge || cache.resolution.operatorAuthorizationValidUntil !== void 0 && now() >= cache.resolution.operatorAuthorizationValidUntil) {
+    if (!cache || now() - cache.fetchedAt >= Math.min(
+      cacheMaxAge,
+      1800,
+      Math.max(30, headerLifetime(cache.resolution.brandJsonCacheControl)),
+      Math.max(60, headerLifetime(cache.resolution.jwksCacheControl))
+    ) || cache.resolution.operatorAuthorizationValidUntil !== void 0 && now() >= cache.resolution.operatorAuthorizationValidUntil) {
+      if (!inFlight && now() - lastRefetchAt < 30) {
+        const expired = cache?.resolution.operatorAuthorizationValidUntil !== void 0 && now() >= cache.resolution.operatorAuthorizationValidUntil;
+        throw new import_errors.AgentResolverError(
+          expired ? "request_signature_brand_origin_mismatch" : "request_signature_brand_json_unreachable",
+          "Expired operator mapping cannot be used during the discovery cooldown",
+          { agent_url: agentUrl },
+          ["agent_url"]
+        );
+      }
       return refresh();
     }
     return cache;
@@ -95,7 +110,7 @@ function createAgentJwksSet(agentUrl, options) {
     try {
       return await fresh.getKey(protectedHeader, token);
     } catch (err) {
-      if (now() - lastRefetchAt < kidCooldown) throw err;
+      if (now() - lastRefetchAt < Math.max(30, kidCooldown)) throw err;
       const refreshed = await refresh();
       return refreshed.getKey(protectedHeader, token);
     }
@@ -118,6 +133,12 @@ function assertAllJwksAllowed(jwks, allowedAlgs, agentUrl) {
 function filterJwksToAllowedAlgs(jwks, allowedAlgs) {
   return jwks.keys.filter((jwk) => typeof jwk.alg !== "string" || allowedAlgs.has(jwk.alg));
 }
+function headerLifetime(value) {
+  if (!value) return Infinity;
+  if (/\bno-cache\b|\bno-store\b/i.test(value)) return 0;
+  const match = /(?:^|,)\s*max-age\s*=\s*"?(\d+)/i.exec(value);
+  return match ? Number(match[1]) : Infinity;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createAgentJwksSet,

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

@@ -34,10 +34,11 @@ function createAgentJwksSet(agentUrl, options) {
   }
   const now = options.now ?? (() => Date.now() / 1e3);
   let cache;
-  let lastRefetchAt = 0;
+  let lastRefetchAt = Number.NEGATIVE_INFINITY;
   let inFlight;
   const refresh = async () => {
     if (inFlight) return inFlight;
+    lastRefetchAt = now();
     inFlight = (async () => {
       const resolution = await resolveAgent(agentUrl, options);
       const refreshedAt = now();
@@ -61,7 +62,21 @@ function createAgentJwksSet(agentUrl, options) {
     return inFlight;
   };
   const ensureFresh = async () => {
-    if (!cache || now() - cache.fetchedAt >= cacheMaxAge || cache.resolution.operatorAuthorizationValidUntil !== void 0 && now() >= cache.resolution.operatorAuthorizationValidUntil) {
+    if (!cache || now() - cache.fetchedAt >= Math.min(
+      cacheMaxAge,
+      1800,
+      Math.max(30, headerLifetime(cache.resolution.brandJsonCacheControl)),
+      Math.max(60, headerLifetime(cache.resolution.jwksCacheControl))
+    ) || cache.resolution.operatorAuthorizationValidUntil !== void 0 && now() >= cache.resolution.operatorAuthorizationValidUntil) {
+      if (!inFlight && now() - lastRefetchAt < 30) {
+        const expired = cache?.resolution.operatorAuthorizationValidUntil !== void 0 && now() >= cache.resolution.operatorAuthorizationValidUntil;
+        throw new AgentResolverError(
+          expired ? "request_signature_brand_origin_mismatch" : "request_signature_brand_json_unreachable",
+          "Expired operator mapping cannot be used during the discovery cooldown",
+          { agent_url: agentUrl },
+          ["agent_url"]
+        );
+      }
       return refresh();
     }
     return cache;
@@ -71,7 +86,7 @@ function createAgentJwksSet(agentUrl, options) {
     try {
       return await fresh.getKey(protectedHeader, token);
     } catch (err) {
-      if (now() - lastRefetchAt < kidCooldown) throw err;
+      if (now() - lastRefetchAt < Math.max(30, kidCooldown)) throw err;
       const refreshed = await refresh();
       return refreshed.getKey(protectedHeader, token);
     }
@@ -94,6 +109,12 @@ function assertAllJwksAllowed(jwks, allowedAlgs, agentUrl) {
 function filterJwksToAllowedAlgs(jwks, allowedAlgs) {
   return jwks.keys.filter((jwk) => typeof jwk.alg !== "string" || allowedAlgs.has(jwk.alg));
 }
+function headerLifetime(value) {
+  if (!value) return Infinity;
+  if (/\bno-cache\b|\bno-store\b/i.test(value)) return 0;
+  const match = /(?:^|,)\s*max-age\s*=\s*"?(\d+)/i.exec(value);
+  return match ? Number(match[1]) : Infinity;
+}
 export {
   createAgentJwksSet,
   getAgentJwks

package/dist/lib/signing/agent-resolver/legacy-brand.d.mts

@@ -0,0 +1,15 @@
+import type { SsrfDnsLookup } from '../../net/index.mjs';
+/** 3.x webhook compatibility only; explicit capability URLs never use this path. */
+export declare function fetchLegacyBrandJson(agentUrl: string, options: {
+    allowPrivateIp?: boolean;
+    timeoutMs?: number;
+    maxBodyBytes: number;
+    lookup?: SsrfDnsLookup;
+}): Promise<{
+    body: unknown;
+    url: string;
+    fetchedAt: number;
+    headers: {
+        'cache-control': string | undefined;
+    };
+}>;

package/dist/lib/signing/agent-resolver/legacy-brand.d.ts

@@ -0,0 +1,15 @@
+import type { SsrfDnsLookup } from '../../net';
+/** 3.x webhook compatibility only; explicit capability URLs never use this path. */
+export declare function fetchLegacyBrandJson(agentUrl: string, options: {
+    allowPrivateIp?: boolean;
+    timeoutMs?: number;
+    maxBodyBytes: number;
+    lookup?: SsrfDnsLookup;
+}): Promise<{
+    body: unknown;
+    url: string;
+    fetchedAt: number;
+    headers: {
+        'cache-control': string | undefined;
+    };
+}>;