@adcp/sdk 14.0.0 → 14.2.0

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

@@ -1,7 +1,11 @@
+import { classifyDiscoveryFailure, isPermanentDiscoveryFailure } from "./agent-resolver/fetch-helpers.mjs";
 import { ssrfSafeFetch } from "../net/index.mjs";
-import { HttpsJwksResolver } from "./jwks-https.mjs";
+import { ResolvedAgentJwksResolver } from "./agent-resolver/resolved-agent-jwks.mjs";
+import { parseStrictJson } from "./agent-resolver/strict-json.mjs";
+import { canonicalAgentUrl } from "./agent-resolver/select-agent.mjs";
 class BrandJsonResolverError extends Error {
   code;
+  recovery;
   cause;
   /** HTTP status for `fetch_failed` responses, when a response was received. */
   httpStatus;
@@ -11,6 +15,7 @@ class BrandJsonResolverError extends Error {
     this.code = code;
     this.httpStatus = details.httpStatus;
     this.cause = details.cause;
+    this.recovery = code !== "fetch_failed" || isPermanentDiscoveryFailure(classifyDiscoveryFailure(this)) ? "terminal" : "transient";
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -18,115 +23,115 @@ const DEFAULT_MAX_AGE_SECONDS = 3600;
 const DEFAULT_MAX_REDIRECTS = 3;
 const BARE_HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
 class BrandJsonJwksResolver {
-  url;
-  selector;
-  minCooldown;
-  maxAge;
-  maxRedirects;
-  allowPrivateIp;
-  lookup;
-  jwksOptions;
-  now;
-  snapshot;
-  inner;
-  inFlight;
   constructor(brandJsonUrl, options) {
-    this.url = brandJsonUrl;
-    this.selector = {
+    this.brandJsonUrl = brandJsonUrl;
+    this.options = options;
+    for (const lifetime of [options.maxAgeSeconds, options.jwksOptions?.maxAgeSeconds]) {
+      if (lifetime !== void 0 && (!Number.isFinite(lifetime) || lifetime <= 0))
+        throw new TypeError("maxAgeSeconds must be a finite positive number.");
+    }
+    for (const cooldown of [options.minCooldownSeconds, options.jwksOptions?.minCooldownSeconds]) {
+      if (cooldown !== void 0 && (!Number.isFinite(cooldown) || cooldown < 0))
+        throw new TypeError("minCooldownSeconds must be a finite non-negative number.");
+    }
+    if (options.agentUrl !== void 0) this.resolver = this.createResolver(options.agentUrl, brandJsonUrl);
+  }
+  brandJsonUrl;
+  options;
+  resolver;
+  onboarding;
+  lastOnboardingAttempt = Number.NEGATIVE_INFINITY;
+  lastOnboardingError;
+  createResolver(agentUrl, operatorUrl) {
+    const options = this.options;
+    return new ResolvedAgentJwksResolver(agentUrl, options.protocol ?? "mcp", {
       agentType: options.agentType,
-      ...options.agentId !== void 0 && { agentId: options.agentId },
-      ...options.brandId !== void 0 && { brandId: options.brandId }
-    };
-    this.minCooldown = options.minCooldownSeconds ?? DEFAULT_MIN_COOLDOWN_SECONDS;
-    this.maxAge = options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
-    this.maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
-    this.allowPrivateIp = options.allowPrivateIp ?? false;
-    this.lookup = options.lookup;
-    this.jwksOptions = options.jwksOptions ?? {};
-    this.now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+      agentId: options.agentId,
+      expectedBrandJsonUrl: operatorUrl,
+      fetchCapabilities: options.fetchCapabilities,
+      legacyWebhookFallback: options.legacyWebhookFallback ?? true,
+      allowPrivateIp: options.allowPrivateIp,
+      lookup: options.lookup,
+      now: options.now,
+      cacheTtlSeconds: Math.min(
+        options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS,
+        options.jwksOptions?.maxAgeSeconds ?? 1800
+      ),
+      unknownKidCooldownSeconds: options.minCooldownSeconds ?? options.jwksOptions?.minCooldownSeconds ?? DEFAULT_MIN_COOLDOWN_SECONDS
+    });
   }
-  /**
-   * Resolve a JWK by `kid`. On a cold cache, fetches brand.json first; on an
-   * expired brand.json snapshot, refreshes respecting the cooldown. Unknown
-   * kids cascade: first ask the inner HttpsJwksResolver (which will refetch
-   * its own URL if cooldown has elapsed); if still unknown, refresh
-   * brand.json in case `jwks_uri` rotated.
-   */
-  async resolve(keyid) {
-    if (!this.snapshot || !this.inner) {
-      await this.refresh();
-    } else if (this.now() > this.snapshot.expiresAt && this.now() - this.snapshot.fetchedAt >= this.minCooldown) {
-      await this.refresh().catch(() => {
-      });
-    }
-    if (!this.inner) return null;
-    const hit = await this.inner.resolve(keyid);
-    if (hit) return hit;
-    if (this.snapshot && this.now() - this.snapshot.fetchedAt >= this.minCooldown) {
-      await this.refresh().catch(() => {
+  async confirmedResolver() {
+    if (this.resolver) return this.resolver;
+    if (this.onboarding) return this.onboarding;
+    const now = this.options.now?.() ?? Date.now() / 1e3;
+    if (now - this.lastOnboardingAttempt < 30)
+      throw this.lastOnboardingError ?? new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
+    this.lastOnboardingAttempt = now;
+    this.onboarding = (async () => {
+      const record = await fetchBrandJson({
+        startUrl: this.brandJsonUrl,
+        maxRedirects: this.options.maxRedirects,
+        allowPrivateIp: this.options.allowPrivateIp,
+        lookup: this.options.lookup
       });
-      return this.inner ? this.inner.resolve(keyid) : null;
-    }
-    return null;
+      const agentUrl = inferOnboardingAgentUrl(record.data, this.options);
+      const resolver = this.createResolver(agentUrl, record.finalUrl);
+      await resolver.forceRefresh();
+      this.resolver = resolver;
+      this.lastOnboardingError = void 0;
+      return resolver;
+    })().catch((error) => {
+      this.lastOnboardingError = error;
+      throw error;
+    }).finally(() => {
+      this.onboarding = void 0;
+    });
+    return this.onboarding;
+  }
+  async resolve(keyid) {
+    return (await this.confirmedResolver()).resolve(keyid);
+  }
+  async resolveWithMetadata(keyid) {
+    return (await this.confirmedResolver()).resolveWithMetadata(keyid);
   }
-  /**
-   * The agent URL we resolved `jwks_uri` from. Populated after the first
-   * successful refresh; useful for verifier result attribution
-   * (`VerifyWebhookOptions.agentUrlForKeyid`).
-   */
   get agentUrl() {
-    return this.snapshot?.agentUrl;
+    return this.resolver?.resolvedAgentUrl;
   }
-  /** Force a refetch of both brand.json and the inner JWKS, bypassing the cooldown. */
   async forceRefresh() {
-    this.snapshot = void 0;
-    this.inner = void 0;
-    await this.refresh();
-  }
-  async refresh() {
-    if (this.inFlight) {
-      await this.inFlight;
-      return;
-    }
-    this.inFlight = this.doRefresh().finally(() => {
-      this.inFlight = void 0;
-    });
-    await this.inFlight;
+    if (this.resolver) await this.resolver.forceRefresh();
+    else await this.confirmedResolver();
   }
-  async doRefresh() {
-    const fetched = await fetchBrandJson({
-      startUrl: this.url,
-      currentEtag: this.snapshot?.etag,
-      maxRedirects: this.maxRedirects,
-      allowPrivateIp: this.allowPrivateIp,
-      lookup: this.lookup
-    });
-    if (fetched.status === "not_modified" && this.snapshot) {
-      this.snapshot = {
-        ...this.snapshot,
-        ...fetched.etag && { etag: fetched.etag },
-        fetchedAt: this.now(),
-        expiresAt: this.now() + computeLifetime(fetched.cacheControl, this.maxAge)
-      };
-      return;
+}
+function inferOnboardingAgentUrl(document, selector) {
+  const record = document;
+  const candidates = (agents) => !Array.isArray(agents) ? [] : agents.filter(
+    (entry) => entry?.type === selector.agentType && (selector.agentId === void 0 || entry.id === selector.agentId) && typeof entry.url === "string"
+  ).flatMap((entry) => {
+    try {
+      return [canonicalAgentUrl(entry.url)];
+    } catch {
+      return [];
     }
-    const agent = selectAgent(fetched.data, fetched.finalUrl, this.selector);
-    if (!this.inner || this.snapshot?.jwksUri !== agent.jwksUri) {
-      this.inner = new HttpsJwksResolver(agent.jwksUri, {
-        ...this.jwksOptions,
-        allowPrivateIp: this.allowPrivateIp,
-        lookup: this.lookup,
-        now: this.now
-      });
+  });
+  let urls;
+  if (isPortfolioHouse(record.house)) {
+    const house = record.house;
+    urls = [];
+    if (selector.brandId !== void 0 && Array.isArray(record.brands)) {
+      const brands = record.brands.filter((brand) => brand?.id === selector.brandId);
+      if (brands.length > 1)
+        throw new BrandJsonResolverError("agent_ambiguous", "Onboarding brand selector is ambiguous.");
+      urls = candidates(brands[0]?.agents);
     }
-    this.snapshot = {
-      jwksUri: agent.jwksUri,
-      agentUrl: agent.url,
-      ...fetched.etag && { etag: fetched.etag },
-      fetchedAt: this.now(),
-      expiresAt: this.now() + computeLifetime(fetched.cacheControl, this.maxAge)
-    };
-  }
+    if (urls.length === 0) urls = candidates(house.agents);
+  } else urls = candidates(record.agents);
+  const unique = [...new Set(urls)];
+  if (unique.length !== 1)
+    throw new BrandJsonResolverError(
+      unique.length === 0 ? "agent_not_found" : "agent_ambiguous",
+      "Onboarding must identify exactly one agent URL; supply agentUrl explicitly."
+    );
+  return unique[0];
 }
 const MAX_BRAND_JSON_TIMEOUT_MS = 1e4;
 const MAX_BRAND_JSON_BODY_BYTES = 262144;
@@ -147,6 +152,8 @@ async function fetchBrandJson(args) {
   const allowPrivateIp = args.allowPrivateIp === true;
   const seen = /* @__PURE__ */ new Set();
   let url = canonicalizeUrl(args.startUrl, allowPrivateIp);
+  const initial = new URL(url);
+  let httpRedirects = 0;
   for (let hop = 0; hop <= maxRedirects; hop++) {
     if (seen.has(url)) {
       throw new BrandJsonResolverError("redirect_loop", `brand.json redirect loop detected`);
@@ -169,6 +176,19 @@ async function fetchBrandJson(args) {
     } catch (cause) {
       throw new BrandJsonResolverError("fetch_failed", "Unable to fetch brand.json", { cause });
     }
+    if (args.domainDerived && hop === 0 && [301, 302, 303, 307, 308].includes(res.status)) {
+      const location = res.headers.location;
+      if (!location || httpRedirects++ >= 3)
+        throw new BrandJsonResolverError("fetch_failed", "Invalid domain-derived redirect");
+      const target = new URL(location, url);
+      const baseHost = initial.hostname.startsWith("www.") ? initial.hostname.slice(4) : initial.hostname;
+      if (target.hostname !== baseHost && target.hostname !== `www.${baseHost}` || target.port !== initial.port || target.protocol !== initial.protocol || target.username || target.password) {
+        throw new BrandJsonResolverError("invalid_url", "brand.json redirect leaves its original host/www boundary");
+      }
+      url = canonicalizeUrl(target.href, allowPrivateIp);
+      hop--;
+      continue;
+    }
     if (hop === 0 && res.status === 304) {
       return {
         status: "not_modified",
@@ -186,7 +206,7 @@ async function fetchBrandJson(args) {
     const text = Buffer.from(res.body).toString("utf8");
     let parsed;
     try {
-      parsed = JSON.parse(text);
+      parsed = parseStrictJson(text);
     } catch {
       throw new BrandJsonResolverError("invalid_body", `brand.json response is not valid JSON`);
     }
@@ -278,88 +298,6 @@ function assertBrandJsonShape(obj) {
     }
   }
 }
-function selectAgent(data, finalBrandUrl, selector) {
-  if (!data || typeof data !== "object") {
-    throw new BrandJsonResolverError(
-      "agent_not_found",
-      `brand.json has no agent matching ${describeSelector(selector)}`
-    );
-  }
-  const obj = data;
-  let picked;
-  if (isPortfolioHouse(obj.house)) {
-    const house = obj.house;
-    if (selector.brandId !== void 0) {
-      const brands = Array.isArray(obj.brands) ? obj.brands : [];
-      const brand = brands.find((b) => b && b.id === selector.brandId);
-      if (brand) picked = pickAgent(brand.agents, finalBrandUrl, selector);
-    }
-    picked ??= pickAgent(house.agents, finalBrandUrl, selector);
-  } else {
-    picked = pickAgent(obj.agents, finalBrandUrl, selector);
-  }
-  if (!picked) {
-    throw new BrandJsonResolverError(
-      "agent_not_found",
-      `brand.json has no agent matching ${describeSelector(selector)}`
-    );
-  }
-  return picked;
-}
-function pickAgent(agents, finalBrandUrl, selector) {
-  if (!Array.isArray(agents)) return void 0;
-  const matches = agents.filter((a) => {
-    if (!a || typeof a !== "object") return false;
-    const e = a;
-    if (e.type !== selector.agentType) return false;
-    if (selector.agentId !== void 0 && e.id !== selector.agentId) return false;
-    return typeof e.url === "string";
-  });
-  if (matches.length === 0) return void 0;
-  if (matches.length > 1 && selector.agentId === void 0) {
-    throw new BrandJsonResolverError(
-      "agent_ambiguous",
-      `brand.json declares ${matches.length} agents of type "${selector.agentType}"; pass \`agentId\` to disambiguate (choices: ${matches.map((m) => m.id ?? "<no-id>").join(", ")})`
-    );
-  }
-  const agent = matches[0];
-  const url = agent.url;
-  const jwksUri = agent.jwks_uri ?? defaultJwksUri(url, finalBrandUrl);
-  return { url, jwksUri };
-}
-function defaultJwksUri(agentUrl, finalBrandUrl) {
-  let agent;
-  try {
-    agent = new URL(agentUrl);
-  } catch {
-    throw new BrandJsonResolverError("invalid_url", `agent.url is not a valid URL`);
-  }
-  const brand = new URL(finalBrandUrl);
-  if (agent.origin !== brand.origin) {
-    throw new BrandJsonResolverError(
-      "jwks_origin_mismatch",
-      `agent.url origin (${agent.origin}) does not match brand.json origin (${brand.origin}); publisher must declare an explicit jwks_uri for cross-origin agents`
-    );
-  }
-  return `${agent.origin}/.well-known/jwks.json`;
-}
-function describeSelector(selector) {
-  const parts = [`type=${selector.agentType}`];
-  if (selector.agentId !== void 0) parts.push(`id=${selector.agentId}`);
-  if (selector.brandId !== void 0) parts.push(`brand=${selector.brandId}`);
-  return parts.join(" ");
-}
-function computeLifetime(cacheControl, maxAge) {
-  if (!cacheControl) return maxAge;
-  const lower = cacheControl.toLowerCase();
-  if (/\bno-store\b|\bno-cache\b/.test(lower)) return 0;
-  const match = /max-age\s*=\s*(\d+)/.exec(lower);
-  if (match) {
-    const serverMax = Number(match[1]);
-    if (Number.isFinite(serverMax)) return Math.min(serverMax, maxAge);
-  }
-  return maxAge;
-}
 export {
   BrandJsonJwksResolver,
   BrandJsonResolverError,

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

@@ -1,12 +1,14 @@
 import { ADCPError } from '../errors/index.mjs';
 import type { RequestSigningErrorCode } from '../types/core.generated.mjs';
-export { RequestSigningErrorCodeMetadata } from '../types/enums.generated.mjs';
+import { RequestSigningErrorCodeMetadata } from '../types/enums.generated.mjs';
+export { RequestSigningErrorCodeMetadata };
 /** Canonical rc.6 request-signing transport vocabulary. */
 export type RequestSignatureErrorCode = RequestSigningErrorCode;
 export declare class RequestSignatureError extends ADCPError {
     readonly code: RequestSignatureErrorCode;
     readonly failedStep: number;
-    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown);
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
+    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown, recovery?: 'transient' | 'correctable' | 'terminal');
 }
 /**
  * Error codes surfaced by the RFC 9421 webhook-signing verifier. Maps onto
@@ -24,7 +26,9 @@ export type WebhookSignatureErrorCode = 'webhook_signature_header_malformed' | '
 export declare class WebhookSignatureError extends ADCPError {
     readonly code: WebhookSignatureErrorCode;
     readonly failedStep: number;
-    constructor(code: WebhookSignatureErrorCode, failedStep: number, message: string, details?: unknown);
+    /** Local retry signal; the wire error code stays in the webhook vocabulary. */
+    readonly retryable: boolean;
+    constructor(code: WebhookSignatureErrorCode, failedStep: number, message: string, details?: unknown, retryable?: boolean);
 }
 export type ResponseSignatureErrorCode = 'response_signature_key_purpose_invalid';
 export declare class ResponseSignatureError extends ADCPError {

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

@@ -1,12 +1,14 @@
 import { ADCPError } from '../errors';
 import type { RequestSigningErrorCode } from '../types/core.generated';
-export { RequestSigningErrorCodeMetadata } from '../types/enums.generated';
+import { RequestSigningErrorCodeMetadata } from '../types/enums.generated';
+export { RequestSigningErrorCodeMetadata };
 /** Canonical rc.6 request-signing transport vocabulary. */
 export type RequestSignatureErrorCode = RequestSigningErrorCode;
 export declare class RequestSignatureError extends ADCPError {
     readonly code: RequestSignatureErrorCode;
     readonly failedStep: number;
-    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown);
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
+    constructor(code: RequestSignatureErrorCode, failedStep: number, message: string, details?: unknown, recovery?: 'transient' | 'correctable' | 'terminal');
 }
 /**
  * Error codes surfaced by the RFC 9421 webhook-signing verifier. Maps onto
@@ -24,7 +26,9 @@ export type WebhookSignatureErrorCode = 'webhook_signature_header_malformed' | '
 export declare class WebhookSignatureError extends ADCPError {
     readonly code: WebhookSignatureErrorCode;
     readonly failedStep: number;
-    constructor(code: WebhookSignatureErrorCode, failedStep: number, message: string, details?: unknown);
+    /** Local retry signal; the wire error code stays in the webhook vocabulary. */
+    readonly retryable: boolean;
+    constructor(code: WebhookSignatureErrorCode, failedStep: number, message: string, details?: unknown, retryable?: boolean);
 }
 export type ResponseSignatureErrorCode = 'response_signature_key_purpose_invalid';
 export declare class ResponseSignatureError extends ADCPError {

package/dist/lib/signing/errors.js

@@ -30,19 +30,24 @@ var import_enums = require('../types/enums.generated.js');
 class RequestSignatureError extends import_errors.ADCPError {
   code;
   failedStep;
-  constructor(code, failedStep, message, details) {
+  recovery;
+  constructor(code, failedStep, message, details, recovery) {
     super(message, details);
     this.code = code;
     this.failedStep = failedStep;
+    this.recovery = recovery ?? import_enums.RequestSigningErrorCodeMetadata[code].recovery;
   }
 }
 class WebhookSignatureError extends import_errors.ADCPError {
   code;
   failedStep;
-  constructor(code, failedStep, message, details) {
+  /** Local retry signal; the wire error code stays in the webhook vocabulary. */
+  retryable;
+  constructor(code, failedStep, message, details, retryable = false) {
     super(message, details);
     this.code = code;
     this.failedStep = failedStep;
+    this.retryable = retryable;
   }
 }
 class ResponseSignatureError extends import_errors.ADCPError {

package/dist/lib/signing/errors.mjs

@@ -3,19 +3,24 @@ import { RequestSigningErrorCodeMetadata } from "../types/enums.generated.mjs";
 class RequestSignatureError extends ADCPError {
   code;
   failedStep;
-  constructor(code, failedStep, message, details) {
+  recovery;
+  constructor(code, failedStep, message, details, recovery) {
     super(message, details);
     this.code = code;
     this.failedStep = failedStep;
+    this.recovery = recovery ?? RequestSigningErrorCodeMetadata[code].recovery;
   }
 }
 class WebhookSignatureError extends ADCPError {
   code;
   failedStep;
-  constructor(code, failedStep, message, details) {
+  /** Local retry signal; the wire error code stays in the webhook vocabulary. */
+  retryable;
+  constructor(code, failedStep, message, details, retryable = false) {
     super(message, details);
     this.code = code;
     this.failedStep = failedStep;
+    this.retryable = retryable;
   }
 }
 class ResponseSignatureError extends ADCPError {

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

@@ -15,6 +15,10 @@ export interface HttpsJwksResolverOptions {
      * longer. Default 3600s (1 hour).
      */
     maxAgeSeconds?: number;
+    /** Protocol cache floor. Defaults to 0; governance uses 60 seconds. */
+    minCacheAgeSeconds?: number;
+    /** Reject refresh failures instead of serving an expired snapshot. Default false. */
+    failClosed?: boolean;
     /** Allow `http://` / private-IP JWKS URLs (dev loops only). Default false. */
     allowPrivateIp?: boolean;
     /** DNS resolver forwarded to the SSRF-safe fetch path. Defaults to `dns/promises.lookup`. */
@@ -45,11 +49,14 @@ export declare class HttpsJwksResolver implements JwksResolver {
     private readonly url;
     private readonly minCooldown;
     private readonly maxAge;
+    private readonly minCacheAge;
+    private readonly failClosed;
     private readonly allowPrivateIp;
     private readonly lookup;
     private readonly now;
     private cache;
     private inFlight;
+    private lastAttemptAt;
     constructor(url: string, options?: HttpsJwksResolverOptions);
     resolve(keyid: string): Promise<AdcpJsonWebKey | null>;
     /**

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

@@ -15,6 +15,10 @@ export interface HttpsJwksResolverOptions {
      * longer. Default 3600s (1 hour).
      */
     maxAgeSeconds?: number;
+    /** Protocol cache floor. Defaults to 0; governance uses 60 seconds. */
+    minCacheAgeSeconds?: number;
+    /** Reject refresh failures instead of serving an expired snapshot. Default false. */
+    failClosed?: boolean;
     /** Allow `http://` / private-IP JWKS URLs (dev loops only). Default false. */
     allowPrivateIp?: boolean;
     /** DNS resolver forwarded to the SSRF-safe fetch path. Defaults to `dns/promises.lookup`. */
@@ -45,11 +49,14 @@ export declare class HttpsJwksResolver implements JwksResolver {
     private readonly url;
     private readonly minCooldown;
     private readonly maxAge;
+    private readonly minCacheAge;
+    private readonly failClosed;
     private readonly allowPrivateIp;
     private readonly lookup;
     private readonly now;
     private cache;
     private inFlight;
+    private lastAttemptAt;
     constructor(url: string, options?: HttpsJwksResolverOptions);
     resolve(keyid: string): Promise<AdcpJsonWebKey | null>;
     /**

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

@@ -22,40 +22,61 @@ __export(jwks_https_exports, {
 });
 module.exports = __toCommonJS(jwks_https_exports);
 var import_net = require('../net/index.js');
+var import_strict_json = require('./agent-resolver/strict-json.js');
 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;
   }
   /**
@@ -72,6 +93,7 @@ class HttpsJwksResolver {
       await this.inFlight;
       return;
     }
+    this.lastAttemptAt = this.now();
     this.inFlight = this.doRefresh().finally(() => {
       this.inFlight = void 0;
     });
@@ -103,7 +125,7 @@ class HttpsJwksResolver {
     const text = Buffer.from(res.body).toString("utf8");
     let parsed;
     try {
-      parsed = JSON.parse(text);
+      parsed = (0, import_strict_json.parseStrictJson)(text);
     } catch {
       throw new Error(`JWKS fetch ${this.url} returned non-JSON body`);
     }
@@ -118,6 +140,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);
       }
     }
@@ -130,11 +153,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;
   }