@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/signing/jwks-https.mjs

@@ -1,38 +1,59 @@
 import { ssrfSafeFetch } from "../net/index.mjs";
+import { parseStrictJson } from "./agent-resolver/strict-json.mjs";
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
 const DEFAULT_MAX_AGE_SECONDS = 3600;
 class HttpsJwksResolver {
   url;
   minCooldown;
   maxAge;
+  minCacheAge;
+  failClosed;
   allowPrivateIp;
   lookup;
   now;
   cache;
   inFlight;
+  lastAttemptAt = Number.NEGATIVE_INFINITY;
   constructor(url, options = {}) {
     this.url = url;
     this.minCooldown = options.minCooldownSeconds ?? DEFAULT_MIN_COOLDOWN_SECONDS;
     this.maxAge = options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+    this.minCacheAge = Math.min(options.minCacheAgeSeconds ?? 0, this.maxAge);
+    if (!Number.isFinite(this.maxAge) || this.maxAge < 0) {
+      throw new TypeError("maxAgeSeconds must be a finite non-negative number");
+    }
+    if (!Number.isFinite(this.minCooldown) || this.minCooldown < 0) {
+      throw new TypeError("minCooldownSeconds must be a finite non-negative number");
+    }
+    if (!Number.isFinite(options.minCacheAgeSeconds ?? 0) || (options.minCacheAgeSeconds ?? 0) < 0) {
+      throw new TypeError("minCacheAgeSeconds must be a finite non-negative number");
+    }
+    this.failClosed = options.failClosed === true;
     this.allowPrivateIp = options.allowPrivateIp ?? false;
     this.lookup = options.lookup;
     this.now = options.now ?? (() => Math.floor(Date.now() / 1e3));
   }
   async resolve(keyid) {
     if (!this.cache) {
+      if (!this.inFlight && this.now() - this.lastAttemptAt < this.minCooldown) {
+        throw new Error("JWKS lookup is in its retry cooldown");
+      }
       await this.refresh();
     } else if (this.cache.keys.has(keyid)) {
-      if (this.now() <= this.cache.expiresAt) {
+      if (this.now() < this.cache.expiresAt) {
         return this.cache.keys.get(keyid) ?? null;
       }
-      if (this.now() - this.cache.fetchedAt >= this.minCooldown) {
-        await this.refresh().catch(() => {
+      if (this.now() - this.lastAttemptAt >= this.minCooldown) {
+        await this.refresh().catch((error) => {
+          if (this.failClosed) throw error;
         });
       }
-    } else if (this.now() - this.cache.fetchedAt >= this.minCooldown) {
-      await this.refresh().catch(() => {
+    } else if (this.now() - this.lastAttemptAt >= this.minCooldown) {
+      await this.refresh().catch((error) => {
+        if (this.failClosed) throw error;
       });
     }
+    if (this.failClosed && this.cache && this.now() >= this.cache.expiresAt) throw new Error("JWKS snapshot expired");
     return this.cache?.keys.get(keyid) ?? null;
   }
   /**
@@ -49,6 +70,7 @@ class HttpsJwksResolver {
       await this.inFlight;
       return;
     }
+    this.lastAttemptAt = this.now();
     this.inFlight = this.doRefresh().finally(() => {
       this.inFlight = void 0;
     });
@@ -80,7 +102,7 @@ class HttpsJwksResolver {
     const text = Buffer.from(res.body).toString("utf8");
     let parsed;
     try {
-      parsed = JSON.parse(text);
+      parsed = parseStrictJson(text);
     } catch {
       throw new Error(`JWKS fetch ${this.url} returned non-JSON body`);
     }
@@ -95,6 +117,7 @@ class HttpsJwksResolver {
     for (const entry of keysField) {
       if (entry && typeof entry === "object" && typeof entry.kid === "string") {
         const jwk = entry;
+        if (byKid.has(jwk.kid)) throw new Error("JWKS has duplicate key identifiers");
         byKid.set(jwk.kid, jwk);
       }
     }
@@ -107,11 +130,11 @@ class HttpsJwksResolver {
   }
   computeExpiry(headers) {
     const cacheCtl = headers["cache-control"]?.toLowerCase() ?? "";
-    if (/\bno-store\b|\bno-cache\b/.test(cacheCtl)) return this.now();
+    if (/\bno-store\b|\bno-cache\b/.test(cacheCtl)) return this.now() + this.minCacheAge;
     const match = /max-age\s*=\s*(\d+)/.exec(cacheCtl);
     if (match) {
       const serverMax = Number(match[1]);
-      if (Number.isFinite(serverMax)) return this.now() + Math.min(serverMax, this.maxAge);
+      if (Number.isFinite(serverMax)) return this.now() + Math.max(this.minCacheAge, Math.min(serverMax, this.maxAge));
     }
     return this.now() + this.maxAge;
   }

package/dist/lib/signing/jwks.d.mts

@@ -1,6 +1,14 @@
 import type { AdcpJsonWebKey } from './types.mjs';
 export interface JwksResolution {
     jwk: AdcpJsonWebKey | null;
+    /** Canonical agent identity established by capability-bound discovery. */
+    agentUrl?: string;
+    /** Exact capability-selected operator document for signed-buyer governance. */
+    operatorRecord?: {
+        url: string;
+        document: unknown;
+    };
+    legacyWebhookFallback?: boolean;
     /** Epoch seconds for a delegated-operator authorization boundary, when applicable. */
     operatorAuthorizationValidUntil?: number;
 }

package/dist/lib/signing/jwks.d.ts

@@ -1,6 +1,14 @@
 import type { AdcpJsonWebKey } from './types';
 export interface JwksResolution {
     jwk: AdcpJsonWebKey | null;
+    /** Canonical agent identity established by capability-bound discovery. */
+    agentUrl?: string;
+    /** Exact capability-selected operator document for signed-buyer governance. */
+    operatorRecord?: {
+        url: string;
+        document: unknown;
+    };
+    legacyWebhookFallback?: boolean;
     /** Epoch seconds for a delegated-operator authorization boundary, when applicable. */
     operatorAuthorizationValidUntil?: number;
 }

package/dist/lib/signing/middleware.js

@@ -49,7 +49,8 @@ function createExpressVerifier(options) {
         req.verifiedSigner = {
           keyid: result.keyid,
           agent_url: result.agent_url,
-          verified_at: result.verified_at
+          verified_at: result.verified_at,
+          ...result.operatorRecord !== void 0 && { operatorRecord: result.operatorRecord }
         };
       }
       next();

package/dist/lib/signing/middleware.mjs

@@ -26,7 +26,8 @@ function createExpressVerifier(options) {
         req.verifiedSigner = {
           keyid: result.keyid,
           agent_url: result.agent_url,
-          verified_at: result.verified_at
+          verified_at: result.verified_at,
+          ...result.operatorRecord !== void 0 && { operatorRecord: result.operatorRecord }
         };
       }
       next();

package/dist/lib/signing/publisher-pins.d.mts

@@ -0,0 +1,11 @@
+import type { AdcpJsonWebKey } from './types.mjs';
+export interface PublisherSigningKeyPin {
+    /** Publisher identity from the buyer's own record, for local diagnostics. */
+    publisher: string;
+    /** undefined means no pin; an empty pin accepts no keys. */
+    signingKeys?: readonly Record<string, unknown>[];
+    /** Fetch adagents.json without its usual cache. Reuse a callback bound to this agent/publisher/tenant across deliveries; refreshes share a 30-second cooldown. Return null only for confirmed pin removal; throw on failure. */
+    refresh: () => Promise<readonly Record<string, unknown>[] | null>;
+}
+/** Intersect an already discovered JWKS key with every applicable publisher pin. */
+export declare function assertPublisherPins(jwk: AdcpJsonWebKey, publishers: readonly PublisherSigningKeyPin[], now: () => number): Promise<void>;

package/dist/lib/signing/publisher-pins.d.ts

@@ -0,0 +1,11 @@
+import type { AdcpJsonWebKey } from './types';
+export interface PublisherSigningKeyPin {
+    /** Publisher identity from the buyer's own record, for local diagnostics. */
+    publisher: string;
+    /** undefined means no pin; an empty pin accepts no keys. */
+    signingKeys?: readonly Record<string, unknown>[];
+    /** Fetch adagents.json without its usual cache. Reuse a callback bound to this agent/publisher/tenant across deliveries; refreshes share a 30-second cooldown. Return null only for confirmed pin removal; throw on failure. */
+    refresh: () => Promise<readonly Record<string, unknown>[] | null>;
+}
+/** Intersect an already discovered JWKS key with every applicable publisher pin. */
+export declare function assertPublisherPins(jwk: AdcpJsonWebKey, publishers: readonly PublisherSigningKeyPin[], now: () => number): Promise<void>;

package/dist/lib/signing/publisher-pins.js

@@ -0,0 +1,125 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var publisher_pins_exports = {};
+__export(publisher_pins_exports, {
+  assertPublisherPins: () => assertPublisherPins
+});
+module.exports = __toCommonJS(publisher_pins_exports);
+var import_jose = require("jose");
+var import_errors = require('./agent-resolver/errors.js');
+const refreshes = /* @__PURE__ */ new WeakMap();
+async function refreshPin(publisher, now) {
+  let states = refreshes.get(publisher.refresh);
+  if (!states) refreshes.set(publisher.refresh, states = /* @__PURE__ */ new Map());
+  const checkedAt = now();
+  const existing = states.get(publisher.publisher);
+  if (existing && (existing.inFlight || checkedAt - existing.attemptedAt < 30) && existing.inputPins !== JSON.stringify(publisher.signingKeys)) {
+    throw new Error("Publisher pin changed during the refresh cooldown");
+  }
+  if (existing?.inFlight) return existing.inFlight;
+  if (existing && checkedAt - existing.attemptedAt < 30) {
+    if (existing.error !== void 0) throw existing.error;
+    return existing.snapshot;
+  }
+  const state = { attemptedAt: checkedAt, inputPins: JSON.stringify(publisher.signingKeys) };
+  if (states.size >= 512) {
+    const evictable = [...states].find(([, candidate]) => !candidate.inFlight);
+    if (!evictable) throw new Error("Publisher refresh capacity exceeded");
+    states.delete(evictable[0]);
+  }
+  states.set(publisher.publisher, state);
+  state.inFlight = Promise.resolve().then(async () => {
+    try {
+      const snapshot = await publisher.refresh();
+      if (snapshot === void 0) throw new TypeError("Publisher refresh must return a confirmed pin or null");
+      state.snapshot = snapshot === null ? null : Object.freeze(snapshot.map((key) => Object.freeze({ ...key })));
+      return state.snapshot;
+    } catch (error) {
+      state.error = error ?? new Error("Publisher refresh failed");
+      throw state.error;
+    } finally {
+      state.inFlight = void 0;
+    }
+  });
+  return state.inFlight;
+}
+async function thumbprint(key) {
+  const members = key.kty === "OKP" ? ["crv", "x"] : key.kty === "EC" ? ["crv", "x", "y"] : key.kty === "RSA" ? ["n", "e"] : void 0;
+  if (!members || members.some((name) => typeof key[name] !== "string" || key[name] === "")) return void 0;
+  try {
+    return await (0, import_jose.calculateJwkThumbprint)(key, "sha256");
+  } catch {
+    return void 0;
+  }
+}
+async function matchingValidity(keyThumbprint, pins) {
+  if (pins === void 0) return [Infinity];
+  const validity = [];
+  for (const pin of pins) {
+    if (!pin || typeof pin !== "object" || await thumbprint(pin) !== keyThumbprint) continue;
+    if (pin.revoked_at === void 0) validity.push(Infinity);
+    else if (typeof pin.revoked_at === "string") {
+      const revoked = Date.parse(pin.revoked_at) / 1e3;
+      validity.push(Number.isFinite(revoked) ? revoked : -Infinity);
+    } else validity.push(-Infinity);
+  }
+  return validity.length ? [Math.min(...validity)] : [];
+}
+async function matches(keyThumbprint, pins, now) {
+  const validity = await matchingValidity(keyThumbprint, pins);
+  return validity.some((until) => now() < until);
+}
+async function assertPublisherPins(jwk, publishers, now) {
+  const fingerprint = await thumbprint(jwk);
+  if (!fingerprint) throw new import_errors.AgentResolverError("request_signature_key_unknown", "Invalid public key", {});
+  const applicable = [];
+  const supplied = [];
+  for (const publisher of publishers) {
+    const inputPins = JSON.stringify(publisher.signingKeys);
+    supplied.push(inputPins);
+    const recent = refreshes.get(publisher.refresh)?.get(publisher.publisher);
+    let selected = recent?.snapshot !== void 0 && recent.inputPins === inputPins && now() - recent.attemptedAt < 30 ? recent.snapshot ?? void 0 : publisher.signingKeys;
+    if (!await matches(fingerprint, selected, now)) {
+      const refreshed = await refreshPin(publisher, now);
+      selected = refreshed ?? void 0;
+      if (!await matches(fingerprint, selected, now))
+        throw new import_errors.AgentResolverError(
+          "request_signature_key_unknown",
+          "Key is outside the applicable publisher pin",
+          {}
+        );
+    }
+    applicable.push(selected);
+  }
+  const validity = await Promise.all(applicable.map((selected) => matchingValidity(fingerprint, selected)));
+  const checkedInputs = publishers.map((publisher) => JSON.stringify(publisher.signingKeys));
+  for (let i = 0; i < publishers.length; i++) {
+    if (supplied[i] !== checkedInputs[i]) {
+      validity.push(await matchingValidity(fingerprint, publishers[i].signingKeys));
+    }
+  }
+  const checkedAt = now();
+  if (publishers.some((publisher, i) => JSON.stringify(publisher.signingKeys) !== checkedInputs[i]) || validity.some((bounds) => !bounds.some((until) => checkedAt < until))) {
+    throw new import_errors.AgentResolverError("request_signature_key_unknown", "Key is outside the applicable publisher pin", {});
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertPublisherPins
+});

package/dist/lib/signing/publisher-pins.mjs

@@ -0,0 +1,101 @@
+import { calculateJwkThumbprint } from "jose";
+import { AgentResolverError } from "./agent-resolver/errors.mjs";
+const refreshes = /* @__PURE__ */ new WeakMap();
+async function refreshPin(publisher, now) {
+  let states = refreshes.get(publisher.refresh);
+  if (!states) refreshes.set(publisher.refresh, states = /* @__PURE__ */ new Map());
+  const checkedAt = now();
+  const existing = states.get(publisher.publisher);
+  if (existing && (existing.inFlight || checkedAt - existing.attemptedAt < 30) && existing.inputPins !== JSON.stringify(publisher.signingKeys)) {
+    throw new Error("Publisher pin changed during the refresh cooldown");
+  }
+  if (existing?.inFlight) return existing.inFlight;
+  if (existing && checkedAt - existing.attemptedAt < 30) {
+    if (existing.error !== void 0) throw existing.error;
+    return existing.snapshot;
+  }
+  const state = { attemptedAt: checkedAt, inputPins: JSON.stringify(publisher.signingKeys) };
+  if (states.size >= 512) {
+    const evictable = [...states].find(([, candidate]) => !candidate.inFlight);
+    if (!evictable) throw new Error("Publisher refresh capacity exceeded");
+    states.delete(evictable[0]);
+  }
+  states.set(publisher.publisher, state);
+  state.inFlight = Promise.resolve().then(async () => {
+    try {
+      const snapshot = await publisher.refresh();
+      if (snapshot === void 0) throw new TypeError("Publisher refresh must return a confirmed pin or null");
+      state.snapshot = snapshot === null ? null : Object.freeze(snapshot.map((key) => Object.freeze({ ...key })));
+      return state.snapshot;
+    } catch (error) {
+      state.error = error ?? new Error("Publisher refresh failed");
+      throw state.error;
+    } finally {
+      state.inFlight = void 0;
+    }
+  });
+  return state.inFlight;
+}
+async function thumbprint(key) {
+  const members = key.kty === "OKP" ? ["crv", "x"] : key.kty === "EC" ? ["crv", "x", "y"] : key.kty === "RSA" ? ["n", "e"] : void 0;
+  if (!members || members.some((name) => typeof key[name] !== "string" || key[name] === "")) return void 0;
+  try {
+    return await calculateJwkThumbprint(key, "sha256");
+  } catch {
+    return void 0;
+  }
+}
+async function matchingValidity(keyThumbprint, pins) {
+  if (pins === void 0) return [Infinity];
+  const validity = [];
+  for (const pin of pins) {
+    if (!pin || typeof pin !== "object" || await thumbprint(pin) !== keyThumbprint) continue;
+    if (pin.revoked_at === void 0) validity.push(Infinity);
+    else if (typeof pin.revoked_at === "string") {
+      const revoked = Date.parse(pin.revoked_at) / 1e3;
+      validity.push(Number.isFinite(revoked) ? revoked : -Infinity);
+    } else validity.push(-Infinity);
+  }
+  return validity.length ? [Math.min(...validity)] : [];
+}
+async function matches(keyThumbprint, pins, now) {
+  const validity = await matchingValidity(keyThumbprint, pins);
+  return validity.some((until) => now() < until);
+}
+async function assertPublisherPins(jwk, publishers, now) {
+  const fingerprint = await thumbprint(jwk);
+  if (!fingerprint) throw new AgentResolverError("request_signature_key_unknown", "Invalid public key", {});
+  const applicable = [];
+  const supplied = [];
+  for (const publisher of publishers) {
+    const inputPins = JSON.stringify(publisher.signingKeys);
+    supplied.push(inputPins);
+    const recent = refreshes.get(publisher.refresh)?.get(publisher.publisher);
+    let selected = recent?.snapshot !== void 0 && recent.inputPins === inputPins && now() - recent.attemptedAt < 30 ? recent.snapshot ?? void 0 : publisher.signingKeys;
+    if (!await matches(fingerprint, selected, now)) {
+      const refreshed = await refreshPin(publisher, now);
+      selected = refreshed ?? void 0;
+      if (!await matches(fingerprint, selected, now))
+        throw new AgentResolverError(
+          "request_signature_key_unknown",
+          "Key is outside the applicable publisher pin",
+          {}
+        );
+    }
+    applicable.push(selected);
+  }
+  const validity = await Promise.all(applicable.map((selected) => matchingValidity(fingerprint, selected)));
+  const checkedInputs = publishers.map((publisher) => JSON.stringify(publisher.signingKeys));
+  for (let i = 0; i < publishers.length; i++) {
+    if (supplied[i] !== checkedInputs[i]) {
+      validity.push(await matchingValidity(fingerprint, publishers[i].signingKeys));
+    }
+  }
+  const checkedAt = now();
+  if (publishers.some((publisher, i) => JSON.stringify(publisher.signingKeys) !== checkedInputs[i]) || validity.some((bounds) => !bounds.some((until) => checkedAt < until))) {
+    throw new AgentResolverError("request_signature_key_unknown", "Key is outside the applicable publisher pin", {});
+  }
+}
+export {
+  assertPublisherPins
+};

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

@@ -30,3 +30,4 @@ export { createExpressVerifier, type ExpressLike, type ExpressMiddlewareOptions
 export { finalizeResponseSignature, prepareResponseSignature, signResponse, type PreparedResponseSignature, type SignedResponse, type SignResponseOptions, } from './signer.mjs';
 export { signResponseAsync } from './signer-async.mjs';
 export { resolveAgent, ResolvedAgentJwksResolver, getAgentJwks, createAgentJwksSet, AgentResolverError, attackerInfluencedFields, ATTACKER_INFLUENCED, readBrandJsonUrl, readIdentityPosture, type AgentResolution, type AgentProtocol, type AuthorizedOperatorScope, type DelegatedOperatorAuthorizationContext, type AgentResolverErrorCode, type AgentResolverErrorDetail, type AgentEntry, type AgentJwksResult, type CapabilitiesWithBrandJsonUrl, type CreateAgentJwksSetOptions, type FetchCapabilitiesFn, type GetAgentJwksOptions, type IdentityKeyOriginPurpose, type IdentityKeyOrigins, type IdentityPosture, type ResolveAgentOptions, type ResolvedAgentJwksResolverOptions, type TraceStep, } from './agent-resolver/index.mjs';
+export type { PublisherSigningKeyPin } from './publisher-pins.mjs';

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

@@ -30,3 +30,4 @@ export { createExpressVerifier, type ExpressLike, type ExpressMiddlewareOptions
 export { finalizeResponseSignature, prepareResponseSignature, signResponse, type PreparedResponseSignature, type SignedResponse, type SignResponseOptions, } from './signer';
 export { signResponseAsync } from './signer-async';
 export { resolveAgent, ResolvedAgentJwksResolver, getAgentJwks, createAgentJwksSet, AgentResolverError, attackerInfluencedFields, ATTACKER_INFLUENCED, readBrandJsonUrl, readIdentityPosture, type AgentResolution, type AgentProtocol, type AuthorizedOperatorScope, type DelegatedOperatorAuthorizationContext, type AgentResolverErrorCode, type AgentResolverErrorDetail, type AgentEntry, type AgentJwksResult, type CapabilitiesWithBrandJsonUrl, type CreateAgentJwksSetOptions, type FetchCapabilitiesFn, type GetAgentJwksOptions, type IdentityKeyOriginPurpose, type IdentityKeyOrigins, type IdentityPosture, type ResolveAgentOptions, type ResolvedAgentJwksResolverOptions, type TraceStep, } from './agent-resolver';
+export type { PublisherSigningKeyPin } from './publisher-pins';

package/dist/lib/signing/types.d.mts

@@ -60,6 +60,11 @@ export interface RevocationSnapshot {
 export interface VerifiedSigner {
     keyid: string;
     agent_url?: string;
+    /** Exact operator record selected during verified agent discovery. */
+    operatorRecord?: {
+        url: string;
+        document: unknown;
+    };
     verified_at: number;
 }
 /**

package/dist/lib/signing/types.d.ts

@@ -60,6 +60,11 @@ export interface RevocationSnapshot {
 export interface VerifiedSigner {
     keyid: string;
     agent_url?: string;
+    /** Exact operator record selected during verified agent discovery. */
+    operatorRecord?: {
+        url: string;
+        document: unknown;
+    };
     verified_at: number;
 }
 /**

package/dist/lib/signing/verifier.js

@@ -32,7 +32,8 @@ var import_crypto = require('./crypto.js');
 var import_webhook_auth_detection = require('./webhook-auth-detection.js');
 var import_types = require('./types.js');
 async function verifyRequestSignature(request, options) {
-  const now = options.now ? options.now() : Math.floor(Date.now() / 1e3);
+  const currentTime = options.now ?? (() => Math.floor(Date.now() / 1e3));
+  const now = currentTime();
   const pinnedBinaryEncoding = options.adcpVersion !== void 0 ? (0, import_content_digest.requestSigningEncodingForVersion)(options.adcpVersion) : void 0;
   const sigInputHeader = (0, import_canonicalize.getHeaderValue)(request.headers, "Signature-Input");
   const sigHeader = (0, import_canonicalize.getHeaderValue)(request.headers, "Signature");
@@ -119,14 +120,38 @@ async function verifyRequestSignature(request, options) {
   const effectiveCapability = pinnedBinaryEncoding === "rfc8941-base64" ? { ...options.capability, covers_content_digest: "required" } : options.capability;
   validateCoveredComponents(parsedInput.components, effectiveCapability, request);
   let jwk;
+  let resolvedAgentUrl;
+  let authorizationValidUntil;
+  let operatorRecord;
   try {
-    jwk = await options.jwks.resolve(parsedInput.params.keyid);
+    if (options.jwks.resolveWithMetadata) {
+      const resolution = await options.jwks.resolveWithMetadata(parsedInput.params.keyid);
+      if (resolution.legacyWebhookFallback)
+        throw new import_errors2.AgentResolverError(
+          "request_signature_brand_json_url_missing",
+          "Legacy discovery is limited to webhook verification",
+          {}
+        );
+      jwk = resolution.jwk;
+      resolvedAgentUrl = resolution.agentUrl;
+      operatorRecord = resolution.operatorRecord;
+      authorizationValidUntil = resolution.operatorAuthorizationValidUntil;
+    } else {
+      jwk = await options.jwks.resolve(parsedInput.params.keyid);
+    }
   } catch (err) {
     if (err instanceof import_errors2.AgentResolverError) {
-      throw new import_errors.RequestSignatureError(err.code, 7, err.message, err.detail);
+      throw new import_errors.RequestSignatureError(err.code, 7, err.message, err.detail, err.recovery);
     }
     throw err;
   }
+  if (authorizationValidUntil !== void 0 && currentTime() >= authorizationValidUntil) {
+    throw new import_errors.RequestSignatureError(
+      "request_signature_brand_origin_mismatch",
+      7,
+      "Delegated operator authorization expired before verification"
+    );
+  }
   if (!jwk) {
     throw new import_errors.RequestSignatureError(
       "request_signature_key_unknown",
@@ -222,6 +247,13 @@ async function verifyRequestSignature(request, options) {
       throw err;
     }
   }
+  if (authorizationValidUntil !== void 0 && currentTime() >= authorizationValidUntil) {
+    throw new import_errors.RequestSignatureError(
+      "request_signature_brand_origin_mismatch",
+      7,
+      "Delegated operator authorization expired during verification"
+    );
+  }
   const remaining = parsedInput.params.expires - now + import_types.CLOCK_SKEW_TOLERANCE_SECONDS;
   const ttl = Math.max(remaining, import_types.MAX_SIGNATURE_WINDOW_SECONDS + import_types.CLOCK_SKEW_TOLERANCE_SECONDS);
   const insertResult = await options.replayStore.insert(jwk.kid, replayScope, parsedInput.params.nonce, ttl, now);
@@ -239,8 +271,21 @@ async function verifyRequestSignature(request, options) {
       `Per-keyid replay cache cap exceeded for keyid=${jwk.kid}`
     );
   }
-  const agent_url = options.agentUrlForKeyid?.(jwk.kid);
-  return { status: "verified", keyid: jwk.kid, agent_url, verified_at: now };
+  if (authorizationValidUntil !== void 0 && currentTime() >= authorizationValidUntil) {
+    throw new import_errors.RequestSignatureError(
+      "request_signature_brand_origin_mismatch",
+      7,
+      "Delegated operator authorization expired before acceptance"
+    );
+  }
+  const agent_url = resolvedAgentUrl ?? options.agentUrlForKeyid?.(jwk.kid);
+  return {
+    status: "verified",
+    keyid: jwk.kid,
+    agent_url,
+    verified_at: now,
+    ...operatorRecord !== void 0 && { operatorRecord }
+  };
 }
 function signatureEncodingCandidates(pinned, digestPolicy) {
   if (!pinned) return ["legacy-base64url", "rfc8941-base64"];

package/dist/lib/signing/verifier.mjs

@@ -25,7 +25,8 @@ import {
   REQUEST_SIGNING_TAG
 } from "./types.mjs";
 async function verifyRequestSignature(request, options) {
-  const now = options.now ? options.now() : Math.floor(Date.now() / 1e3);
+  const currentTime = options.now ?? (() => Math.floor(Date.now() / 1e3));
+  const now = currentTime();
   const pinnedBinaryEncoding = options.adcpVersion !== void 0 ? requestSigningEncodingForVersion(options.adcpVersion) : void 0;
   const sigInputHeader = getHeaderValue(request.headers, "Signature-Input");
   const sigHeader = getHeaderValue(request.headers, "Signature");
@@ -112,14 +113,38 @@ async function verifyRequestSignature(request, options) {
   const effectiveCapability = pinnedBinaryEncoding === "rfc8941-base64" ? { ...options.capability, covers_content_digest: "required" } : options.capability;
   validateCoveredComponents(parsedInput.components, effectiveCapability, request);
   let jwk;
+  let resolvedAgentUrl;
+  let authorizationValidUntil;
+  let operatorRecord;
   try {
-    jwk = await options.jwks.resolve(parsedInput.params.keyid);
+    if (options.jwks.resolveWithMetadata) {
+      const resolution = await options.jwks.resolveWithMetadata(parsedInput.params.keyid);
+      if (resolution.legacyWebhookFallback)
+        throw new AgentResolverError(
+          "request_signature_brand_json_url_missing",
+          "Legacy discovery is limited to webhook verification",
+          {}
+        );
+      jwk = resolution.jwk;
+      resolvedAgentUrl = resolution.agentUrl;
+      operatorRecord = resolution.operatorRecord;
+      authorizationValidUntil = resolution.operatorAuthorizationValidUntil;
+    } else {
+      jwk = await options.jwks.resolve(parsedInput.params.keyid);
+    }
   } catch (err) {
     if (err instanceof AgentResolverError) {
-      throw new RequestSignatureError(err.code, 7, err.message, err.detail);
+      throw new RequestSignatureError(err.code, 7, err.message, err.detail, err.recovery);
     }
     throw err;
   }
+  if (authorizationValidUntil !== void 0 && currentTime() >= authorizationValidUntil) {
+    throw new RequestSignatureError(
+      "request_signature_brand_origin_mismatch",
+      7,
+      "Delegated operator authorization expired before verification"
+    );
+  }
   if (!jwk) {
     throw new RequestSignatureError(
       "request_signature_key_unknown",
@@ -215,6 +240,13 @@ async function verifyRequestSignature(request, options) {
       throw err;
     }
   }
+  if (authorizationValidUntil !== void 0 && currentTime() >= authorizationValidUntil) {
+    throw new RequestSignatureError(
+      "request_signature_brand_origin_mismatch",
+      7,
+      "Delegated operator authorization expired during verification"
+    );
+  }
   const remaining = parsedInput.params.expires - now + CLOCK_SKEW_TOLERANCE_SECONDS;
   const ttl = Math.max(remaining, MAX_SIGNATURE_WINDOW_SECONDS + CLOCK_SKEW_TOLERANCE_SECONDS);
   const insertResult = await options.replayStore.insert(jwk.kid, replayScope, parsedInput.params.nonce, ttl, now);
@@ -232,8 +264,21 @@ async function verifyRequestSignature(request, options) {
       `Per-keyid replay cache cap exceeded for keyid=${jwk.kid}`
     );
   }
-  const agent_url = options.agentUrlForKeyid?.(jwk.kid);
-  return { status: "verified", keyid: jwk.kid, agent_url, verified_at: now };
+  if (authorizationValidUntil !== void 0 && currentTime() >= authorizationValidUntil) {
+    throw new RequestSignatureError(
+      "request_signature_brand_origin_mismatch",
+      7,
+      "Delegated operator authorization expired before acceptance"
+    );
+  }
+  const agent_url = resolvedAgentUrl ?? options.agentUrlForKeyid?.(jwk.kid);
+  return {
+    status: "verified",
+    keyid: jwk.kid,
+    agent_url,
+    verified_at: now,
+    ...operatorRecord !== void 0 && { operatorRecord }
+  };
 }
 function signatureEncodingCandidates(pinned, digestPolicy) {
   if (!pinned) return ["legacy-base64url", "rfc8941-base64"];

package/dist/lib/signing/webhook-verifier.d.mts

@@ -14,8 +14,8 @@
  *     `content-type`, and `content-digest` — `content-digest` is unconditional
  *     for webhooks (vs policy-driven on requests) because every webhook
  *     carries a JSON body.
- *   - JWKS resolved via the publisher's `brand.json` `agents[]` `jwks_uri`,
- *     not the request-path capability document.
+ *   - JWKS resolved via the capabilities-selected operator brand.json;
+ *     publisher pins narrow its keys for applicable inventory.
  *
  * Checklist steps below mirror the 14-step shape in
  * `docs/building/implementation/security.mdx#verifier-checklist-for-webhooks`
@@ -23,6 +23,7 @@
  * match the security doc.
  */
 import type { JwksResolver } from './jwks.mjs';
+import { type PublisherSigningKeyPin } from './publisher-pins.mjs';
 import { type ReplayStore } from './replay.mjs';
 import { type RevocationStore } from './revocation.mjs';
 export declare const WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
@@ -42,6 +43,10 @@ export interface WebhookRequestLike {
 export declare const WEBHOOK_MANDATORY_COMPONENTS: ReadonlyArray<string>;
 export interface VerifyWebhookOptions {
     jwks: JwksResolver;
+    /** Applicable publishers from the verifier's own media-buy record. */
+    publisherPins?: readonly PublisherSigningKeyPin[];
+    /** Log the underlying request_signature_* discovery cause locally. */
+    onKeyResolutionError?: (error: unknown) => void;
     replayStore: ReplayStore;
     revocationStore: RevocationStore;
     /** Now in seconds since epoch. Defaults to `Date.now() / 1000`. */