@adcp/sdk 16.1.0 → 16.2.0

package/dist/lib/identity-3.3/jws-artifacts.d.ts

@@ -0,0 +1,147 @@
+import { type SsrfFetchOptions } from '../net';
+import type { AdcpJsonWebKey } from '../signing/types';
+import { type SignatureDirectoryResolver } from '../signing/web-bot-auth';
+import type { OriginRevocationResolver, OriginRevocationStatus } from './revocation';
+import type { TrustEvaluator } from './trust';
+import type { RevocationDetail } from './types';
+/** Which profile verifies a JWS artifact from origin `O`. */
+export type JwsArtifactProfile = {
+    profile: 'web-bot-auth';
+    /** `O`, the canonical origin of the signing agent's URL. */
+    origin: string;
+    /** The registrable domain whose trust record lists `O`. */
+    operator: string;
+} | {
+    profile: '3.2';
+    origin: string;
+    /**
+     * `no_trust_record`: `O` has no registrable domain (IP literal, public
+     * suffix, no PSL match), or its operator has not published a trust
+     * record (404/410 with no remembered 200). `unlisted`: the record does
+     * not list `O`.
+     */
+    reason: 'no_trust_record' | 'unlisted';
+};
+export type JwsArtifactErrorCode = 
+/** A trust record, key directory or archive could not be read. Retryable. */
+'jws_key_unavailable'
+/** No key at `O` (directory, or archive for history) carries the `kid`. */
+ | 'jws_key_unknown'
+/** Wrong `typ`, `alg` not `EdDSA`, `kid` not the key's thumbprint, or a signature that does not verify. */
+ | 'jws_invalid'
+/** `O`'s revocation list revokes the `kid`. */
+ | 'jws_key_revoked'
+/** `O`'s revocation status is unknown, or (by default) `O` serves no list. Retryable. */
+ | 'jws_revocation_unavailable';
+export declare class JwsArtifactError extends Error {
+    readonly code: JwsArtifactErrorCode;
+    constructor(code: JwsArtifactErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+    /** True for outages: retry later, never treat as absence or as a verdict on the artifact. */
+    get transient(): boolean;
+}
+/** Components the WBA path reuses. */
+export interface JwsArtifactWebBotAuthOptions {
+    /**
+     * Derives the trust record from `O` (R3a step 1) to select the profile.
+     * Configure durable `authorityHistory` on it for public, multi-replica or
+     * serverless verifiers: without it, the rule that a 404/410 after a 200 is an
+     * outage (never a return to 3.2) holds only within one process.
+     */
+    trust: TrustEvaluator;
+    /** `O`'s Web Bot Auth key directory. */
+    directory: SignatureDirectoryResolver;
+    /** `O`'s revocation list (R3). Required: the WBA path never skips revocation. */
+    revocation: OriginRevocationResolver;
+}
+/**
+ * Select the profile for a JWS artifact whose signing agent URL is
+ * `signingAgentUrl` (R4). Throws {@link JwsArtifactError}
+ * `jws_key_unavailable` when the trust record cannot be read: a fetch failure
+ * is never absence and never selects the 3.2 profile. An unparseable
+ * `signingAgentUrl` is a caller error (`TypeError` from canonicalization).
+ */
+export declare function selectJwsArtifactProfile(signingAgentUrl: string, trust: TrustEvaluator): Promise<JwsArtifactProfile>;
+export interface VerifyWebBotAuthJwsArtifactOptions {
+    /** The protected-header `typ` this surface accepts, e.g. `adcp-gov+jws`. Any other is refused. */
+    typ: string;
+    directory: SignatureDirectoryResolver;
+    /**
+     * `O`'s revocation list (R3). Pass `false` only when the caller checks the
+     * returned `kid` against `O`'s list itself.
+     */
+    revocation: OriginRevocationResolver | false;
+    /**
+     * `O`'s revocation status `absent` (the origin serves no list). `reject`
+     * (default) fails closed, as a WBA identity without a list cannot be bound
+     * for spend. `accept` treats it as nothing revoked.
+     */
+    revocationAbsent?: 'reject' | 'accept';
+    /**
+     * A key `O`'s list revokes. `reject` (default) refuses the artifact, as
+     * online verification must (R9: a revoked key is rejected whatever its
+     * detail). `report` verifies it and returns the revocation and its detail,
+     * for audit of retained artifacts.
+     */
+    revokedKey?: 'reject' | 'report';
+    /**
+     * Historical verification: also look the `kid` up in the governance key
+     * archive at `O` when the directory does not carry it or cannot be read.
+     * Governance contexts only; only governance agents publish an archive.
+     */
+    archive?: GovernanceKeyArchiveResolver;
+    /** Critical header parameters the surface understands (jose `crit`). */
+    crit?: Record<string, boolean>;
+}
+export interface VerifiedWebBotAuthJwsArtifact {
+    origin: string;
+    kid: string;
+    key: AdcpJsonWebKey;
+    /** Where the key came from: `O`'s key directory, or (history) its archive. */
+    keySource: 'directory' | 'archive';
+    protectedHeader: Record<string, unknown>;
+    payload: Uint8Array;
+    /** `O`'s revocation status for `kid`, when a resolver was supplied. Never `unknown`. */
+    revocation?: Exclude<OriginRevocationStatus, 'unknown'>;
+    /** The most severe revocation detail recorded for `kid` (R9), when it is revoked. */
+    revocationDetail?: RevocationDetail;
+}
+/**
+ * Verify a compact JWS with a key from `origin`'s WBA key directory (R4):
+ * `typ` as the surface requires, `alg` `EdDSA`, `kid` the key's JWK
+ * thumbprint, no `use`/`key_ops`/`adcp_use` checks, and revocation from
+ * `origin`'s list. Signature and key only: every other check of the surface
+ * (claims, audience, freshness, replay) stays with the surface. Throws
+ * {@link JwsArtifactError}.
+ */
+export declare function verifyWebBotAuthJwsArtifact(token: string, origin: string, options: VerifyWebBotAuthJwsArtifactOptions): Promise<VerifiedWebBotAuthJwsArtifact>;
+export declare const GOVERNANCE_KEY_ARCHIVE_PATH = "/.well-known/jwks-archive.json";
+export interface GovernanceKeyArchiveResolverOptions {
+    now?: () => number;
+    fetchOptions?: Pick<SsrfFetchOptions, 'lookup' | 'trustedFetchFn'>;
+    /** Seconds an archive read stays cached. Default 300. */
+    maxAgeSeconds?: number;
+    /** Origins cached at once. Default 256. */
+    maxOrigins?: number;
+    /** Published fixture keys are read only outside production, as for the key directory. */
+    allowTestKeys?: boolean;
+}
+/**
+ * The governance key archive at an origin (`security.mdx` §Revocation):
+ * `{origin}/.well-known/jwks-archive.json`, a JWKS of retired governance keys
+ * kept discoverable for audit. On the WBA path only Ed25519 keys whose `kid`
+ * (when present) is their JWK thumbprint are read; other keys are ignored. A
+ * 404/410 is an origin with no archive. Any other failure is
+ * `jws_key_unavailable`, never absence, and is retried after a cooldown.
+ */
+export declare class GovernanceKeyArchiveResolver {
+    private readonly options;
+    private readonly cache;
+    private readonly failures;
+    private readonly pending;
+    private readonly maxOrigins;
+    constructor(options?: GovernanceKeyArchiveResolverOptions);
+    resolve(origin: string, kid: string): Promise<AdcpJsonWebKey | null>;
+    private fetch;
+}

package/dist/lib/identity-3.3/jws-artifacts.js

@@ -0,0 +1,258 @@
+"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 jws_artifacts_exports = {};
+__export(jws_artifacts_exports, {
+  GOVERNANCE_KEY_ARCHIVE_PATH: () => GOVERNANCE_KEY_ARCHIVE_PATH,
+  GovernanceKeyArchiveResolver: () => GovernanceKeyArchiveResolver,
+  JwsArtifactError: () => JwsArtifactError,
+  selectJwsArtifactProfile: () => selectJwsArtifactProfile,
+  verifyWebBotAuthJwsArtifact: () => verifyWebBotAuthJwsArtifact
+});
+module.exports = __toCommonJS(jws_artifacts_exports);
+var import_jose = require("jose");
+var import_net = require('../net/index.js');
+var import_canonicalize = require('../signing/agent-resolver/canonicalize.js');
+var import_etld = require('../signing/agent-resolver/etld.js');
+var import_strict_json = require('../signing/agent-resolver/strict-json.js');
+var import_web_bot_auth = require('../signing/web-bot-auth.js');
+class JwsArtifactError extends Error {
+  constructor(code, message, options) {
+    super(message);
+    this.code = code;
+    this.name = "JwsArtifactError";
+    if (options?.cause !== void 0) Object.defineProperty(this, "cause", { value: options.cause });
+  }
+  code;
+  /** True for outages: retry later, never treat as absence or as a verdict on the artifact. */
+  get transient() {
+    return this.code === "jws_key_unavailable" || this.code === "jws_revocation_unavailable";
+  }
+}
+async function selectJwsArtifactProfile(signingAgentUrl, trust) {
+  const origin = (0, import_canonicalize.canonicalAgentOrigin)(signingAgentUrl);
+  try {
+    (0, import_etld.eTldPlusOne)(origin);
+  } catch {
+    return { profile: "3.2", origin, reason: "no_trust_record" };
+  }
+  let record;
+  try {
+    record = await trust.get(origin);
+  } catch (cause) {
+    throw new JwsArtifactError("jws_key_unavailable", "Issuer trust record is unavailable", { cause });
+  }
+  if (record.status !== "present") return { profile: "3.2", origin, reason: "no_trust_record" };
+  const listed = (record.record.agents ?? []).some((agent) => {
+    try {
+      return (0, import_canonicalize.canonicalAgentOrigin)(agent.url) === origin;
+    } catch {
+      return false;
+    }
+  });
+  return listed ? { profile: "web-bot-auth", origin, operator: record.operator } : { profile: "3.2", origin, reason: "unlisted" };
+}
+async function verifyWebBotAuthJwsArtifact(token, origin, options) {
+  if (typeof options.typ !== "string" || !options.typ)
+    throw new TypeError("verifyWebBotAuthJwsArtifact requires the typ the surface accepts");
+  if (options.revocation === void 0)
+    throw new TypeError("verifyWebBotAuthJwsArtifact requires a revocation resolver, or revocation: false");
+  let header;
+  try {
+    header = (0, import_jose.decodeProtectedHeader)(token);
+  } catch {
+    throw new JwsArtifactError("jws_invalid", "Malformed JWS protected header");
+  }
+  if (header.typ !== options.typ)
+    throw new JwsArtifactError("jws_invalid", "JWS typ is not the one this surface accepts");
+  if (header.alg !== "EdDSA") throw new JwsArtifactError("jws_invalid", "A Web Bot Auth JWS artifact uses alg EdDSA");
+  const kid = header.kid;
+  if (typeof kid !== "string" || kid.length === 0 || kid.length > 256)
+    throw new JwsArtifactError("jws_key_unknown", "JWS kid is missing");
+  try {
+    origin = (0, import_web_bot_auth.receivedAgentOrigin)((0, import_canonicalize.canonicalAgentOrigin)(origin));
+  } catch {
+    throw new JwsArtifactError("jws_key_unknown", "Signing origin is not an https origin");
+  }
+  let key = null;
+  let keySource = "directory";
+  let directoryFailure;
+  try {
+    key = await options.directory.resolve(kid, origin);
+  } catch (cause) {
+    directoryFailure = cause;
+  }
+  if (!key && options.archive) {
+    const archived = await options.archive.resolve(origin, kid);
+    if (archived) {
+      key = archived;
+      keySource = "archive";
+    }
+  }
+  if (!key) {
+    if (directoryFailure !== void 0)
+      throw new JwsArtifactError("jws_key_unavailable", "Issuer key directory is unavailable", {
+        cause: directoryFailure
+      });
+    throw new JwsArtifactError("jws_key_unknown", "No key at the issuer origin carries this kid");
+  }
+  if (key.kty !== "OKP" || key.crv !== "Ed25519" || typeof key.x !== "string")
+    throw new JwsArtifactError("jws_invalid", "A Web Bot Auth JWS artifact is signed with an Ed25519 key");
+  let thumbprint;
+  try {
+    thumbprint = (0, import_web_bot_auth.jwkThumbprint)(key);
+  } catch {
+    throw new JwsArtifactError("jws_invalid", "Key thumbprint cannot be computed");
+  }
+  if (kid !== thumbprint) throw new JwsArtifactError("jws_invalid", "JWS kid is not the key JWK thumbprint");
+  let verified;
+  try {
+    const publicKey = { kty: "OKP", crv: "Ed25519", x: key.x };
+    verified = await (0, import_jose.compactVerify)(token, await (0, import_jose.importJWK)(publicKey, "EdDSA"), {
+      algorithms: ["EdDSA"],
+      ...options.crit ? { crit: options.crit } : {}
+    });
+  } catch {
+    throw new JwsArtifactError("jws_invalid", "JWS signature verification failed");
+  }
+  const result = {
+    origin,
+    kid,
+    key,
+    keySource,
+    protectedHeader: verified.protectedHeader,
+    payload: verified.payload
+  };
+  if (options.revocation) {
+    let status;
+    try {
+      status = await options.revocation.status(origin, kid);
+    } catch (cause) {
+      throw new JwsArtifactError("jws_revocation_unavailable", "Issuer revocation status could not be established", {
+        cause
+      });
+    }
+    if (status === "unknown" || status === "absent" && (options.revocationAbsent ?? "reject") === "reject")
+      throw new JwsArtifactError("jws_revocation_unavailable", "Issuer revocation status could not be established");
+    if (status === "revoked") {
+      if ((options.revokedKey ?? "reject") === "reject")
+        throw new JwsArtifactError("jws_key_revoked", "Signing key is revoked by its origin");
+      try {
+        const detail = await options.revocation.detail(origin, kid);
+        if (detail) result.revocationDetail = detail;
+      } catch (cause) {
+        throw new JwsArtifactError("jws_revocation_unavailable", "Issuer revocation detail could not be read", {
+          cause
+        });
+      }
+    }
+    result.revocation = status;
+  }
+  return result;
+}
+const GOVERNANCE_KEY_ARCHIVE_PATH = "/.well-known/jwks-archive.json";
+const ARCHIVE_FAILURE_COOLDOWN_SECONDS = 60;
+class GovernanceKeyArchiveResolver {
+  constructor(options = {}) {
+    this.options = options;
+    const maxAge = options.maxAgeSeconds ?? 300;
+    if (!Number.isFinite(maxAge) || maxAge < 0)
+      throw new TypeError("maxAgeSeconds must be a finite, non-negative number");
+    this.maxOrigins = options.maxOrigins ?? 256;
+    if (!Number.isSafeInteger(this.maxOrigins) || this.maxOrigins < 1)
+      throw new TypeError("maxOrigins must be a positive safe integer");
+  }
+  options;
+  cache = /* @__PURE__ */ new Map();
+  failures = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  maxOrigins;
+  async resolve(origin, kid) {
+    origin = (0, import_web_bot_auth.receivedAgentOrigin)((0, import_canonicalize.canonicalAgentOrigin)(origin));
+    const now = (this.options.now ?? (() => Date.now() / 1e3))();
+    const cached = this.cache.get(origin);
+    let keys;
+    if (cached && cached.freshUntil > now) keys = cached.keys;
+    else {
+      const failure = this.failures.get(origin);
+      if (failure && failure.until > now)
+        throw new JwsArtifactError("jws_key_unavailable", "Governance key archive is unavailable", {
+          cause: failure.cause
+        });
+      let pending = this.pending.get(origin);
+      if (!pending) {
+        pending = this.fetch(origin, now);
+        this.pending.set(origin, pending);
+      }
+      try {
+        keys = await pending;
+      } finally {
+        if (this.pending.get(origin) === pending) this.pending.delete(origin);
+      }
+    }
+    return keys.find((key) => key.kid === kid) ?? null;
+  }
+  async fetch(origin, now) {
+    let keys;
+    try {
+      const response = await (0, import_net.ssrfSafeFetch)(origin + GOVERNANCE_KEY_ARCHIVE_PATH, {
+        ...this.options.fetchOptions,
+        headers: { accept: "application/json" },
+        timeoutMs: 1e4,
+        maxBodyBytes: 1024 * 1024
+      });
+      if (response.status === 404 || response.status === 410) keys = [];
+      else {
+        if (response.status !== 200) throw new Error(`Archive answered ${response.status}`);
+        const document = (0, import_strict_json.parseStrictJson)(new TextDecoder("utf-8", { fatal: true }).decode(response.body), 32);
+        if (!Array.isArray(document.keys) || document.keys.length > 4096) throw new Error("Invalid key archive");
+        keys = [];
+        for (const raw of document.keys) {
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+          const jwk = raw;
+          if (Object.keys(jwk).some((name) => PRIVATE_JWK_MEMBERS.has(name.toLowerCase()) || name.startsWith("_private")))
+            throw new Error("Key archive publishes private key material");
+          if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string") continue;
+          const thumbprint = (0, import_web_bot_auth.jwkThumbprint)(jwk);
+          if (jwk.kid !== void 0 && jwk.kid !== thumbprint) continue;
+          if ((0, import_web_bot_auth.isRefusedWebBotAuthTestKey)(thumbprint, this.options.allowTestKeys)) continue;
+          keys.push({ kty: "OKP", crv: "Ed25519", x: jwk.x, kid: thumbprint });
+        }
+      }
+    } catch (cause) {
+      if (this.failures.size >= this.maxOrigins && !this.failures.has(origin))
+        this.failures.delete(this.failures.keys().next().value);
+      this.failures.set(origin, { until: now + ARCHIVE_FAILURE_COOLDOWN_SECONDS, cause });
+      throw new JwsArtifactError("jws_key_unavailable", "Governance key archive is unavailable", { cause });
+    }
+    this.failures.delete(origin);
+    if (this.cache.size >= this.maxOrigins && !this.cache.has(origin))
+      this.cache.delete(this.cache.keys().next().value);
+    this.cache.set(origin, { keys, freshUntil: now + (this.options.maxAgeSeconds ?? 300) });
+    return keys;
+  }
+}
+const PRIVATE_JWK_MEMBERS = /* @__PURE__ */ new Set(["d", "p", "q", "dp", "dq", "qi", "oth", "k"]);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GOVERNANCE_KEY_ARCHIVE_PATH,
+  GovernanceKeyArchiveResolver,
+  JwsArtifactError,
+  selectJwsArtifactProfile,
+  verifyWebBotAuthJwsArtifact
+});

package/dist/lib/identity-3.3/jws-artifacts.mjs

@@ -0,0 +1,234 @@
+import { compactVerify, decodeProtectedHeader, importJWK } from "jose";
+import { ssrfSafeFetch } from "../net/index.mjs";
+import { canonicalAgentOrigin } from "../signing/agent-resolver/canonicalize.mjs";
+import { eTldPlusOne } from "../signing/agent-resolver/etld.mjs";
+import { parseStrictJson } from "../signing/agent-resolver/strict-json.mjs";
+import {
+  isRefusedWebBotAuthTestKey,
+  jwkThumbprint,
+  receivedAgentOrigin
+} from "../signing/web-bot-auth.mjs";
+class JwsArtifactError extends Error {
+  constructor(code, message, options) {
+    super(message);
+    this.code = code;
+    this.name = "JwsArtifactError";
+    if (options?.cause !== void 0) Object.defineProperty(this, "cause", { value: options.cause });
+  }
+  code;
+  /** True for outages: retry later, never treat as absence or as a verdict on the artifact. */
+  get transient() {
+    return this.code === "jws_key_unavailable" || this.code === "jws_revocation_unavailable";
+  }
+}
+async function selectJwsArtifactProfile(signingAgentUrl, trust) {
+  const origin = canonicalAgentOrigin(signingAgentUrl);
+  try {
+    eTldPlusOne(origin);
+  } catch {
+    return { profile: "3.2", origin, reason: "no_trust_record" };
+  }
+  let record;
+  try {
+    record = await trust.get(origin);
+  } catch (cause) {
+    throw new JwsArtifactError("jws_key_unavailable", "Issuer trust record is unavailable", { cause });
+  }
+  if (record.status !== "present") return { profile: "3.2", origin, reason: "no_trust_record" };
+  const listed = (record.record.agents ?? []).some((agent) => {
+    try {
+      return canonicalAgentOrigin(agent.url) === origin;
+    } catch {
+      return false;
+    }
+  });
+  return listed ? { profile: "web-bot-auth", origin, operator: record.operator } : { profile: "3.2", origin, reason: "unlisted" };
+}
+async function verifyWebBotAuthJwsArtifact(token, origin, options) {
+  if (typeof options.typ !== "string" || !options.typ)
+    throw new TypeError("verifyWebBotAuthJwsArtifact requires the typ the surface accepts");
+  if (options.revocation === void 0)
+    throw new TypeError("verifyWebBotAuthJwsArtifact requires a revocation resolver, or revocation: false");
+  let header;
+  try {
+    header = decodeProtectedHeader(token);
+  } catch {
+    throw new JwsArtifactError("jws_invalid", "Malformed JWS protected header");
+  }
+  if (header.typ !== options.typ)
+    throw new JwsArtifactError("jws_invalid", "JWS typ is not the one this surface accepts");
+  if (header.alg !== "EdDSA") throw new JwsArtifactError("jws_invalid", "A Web Bot Auth JWS artifact uses alg EdDSA");
+  const kid = header.kid;
+  if (typeof kid !== "string" || kid.length === 0 || kid.length > 256)
+    throw new JwsArtifactError("jws_key_unknown", "JWS kid is missing");
+  try {
+    origin = receivedAgentOrigin(canonicalAgentOrigin(origin));
+  } catch {
+    throw new JwsArtifactError("jws_key_unknown", "Signing origin is not an https origin");
+  }
+  let key = null;
+  let keySource = "directory";
+  let directoryFailure;
+  try {
+    key = await options.directory.resolve(kid, origin);
+  } catch (cause) {
+    directoryFailure = cause;
+  }
+  if (!key && options.archive) {
+    const archived = await options.archive.resolve(origin, kid);
+    if (archived) {
+      key = archived;
+      keySource = "archive";
+    }
+  }
+  if (!key) {
+    if (directoryFailure !== void 0)
+      throw new JwsArtifactError("jws_key_unavailable", "Issuer key directory is unavailable", {
+        cause: directoryFailure
+      });
+    throw new JwsArtifactError("jws_key_unknown", "No key at the issuer origin carries this kid");
+  }
+  if (key.kty !== "OKP" || key.crv !== "Ed25519" || typeof key.x !== "string")
+    throw new JwsArtifactError("jws_invalid", "A Web Bot Auth JWS artifact is signed with an Ed25519 key");
+  let thumbprint;
+  try {
+    thumbprint = jwkThumbprint(key);
+  } catch {
+    throw new JwsArtifactError("jws_invalid", "Key thumbprint cannot be computed");
+  }
+  if (kid !== thumbprint) throw new JwsArtifactError("jws_invalid", "JWS kid is not the key JWK thumbprint");
+  let verified;
+  try {
+    const publicKey = { kty: "OKP", crv: "Ed25519", x: key.x };
+    verified = await compactVerify(token, await importJWK(publicKey, "EdDSA"), {
+      algorithms: ["EdDSA"],
+      ...options.crit ? { crit: options.crit } : {}
+    });
+  } catch {
+    throw new JwsArtifactError("jws_invalid", "JWS signature verification failed");
+  }
+  const result = {
+    origin,
+    kid,
+    key,
+    keySource,
+    protectedHeader: verified.protectedHeader,
+    payload: verified.payload
+  };
+  if (options.revocation) {
+    let status;
+    try {
+      status = await options.revocation.status(origin, kid);
+    } catch (cause) {
+      throw new JwsArtifactError("jws_revocation_unavailable", "Issuer revocation status could not be established", {
+        cause
+      });
+    }
+    if (status === "unknown" || status === "absent" && (options.revocationAbsent ?? "reject") === "reject")
+      throw new JwsArtifactError("jws_revocation_unavailable", "Issuer revocation status could not be established");
+    if (status === "revoked") {
+      if ((options.revokedKey ?? "reject") === "reject")
+        throw new JwsArtifactError("jws_key_revoked", "Signing key is revoked by its origin");
+      try {
+        const detail = await options.revocation.detail(origin, kid);
+        if (detail) result.revocationDetail = detail;
+      } catch (cause) {
+        throw new JwsArtifactError("jws_revocation_unavailable", "Issuer revocation detail could not be read", {
+          cause
+        });
+      }
+    }
+    result.revocation = status;
+  }
+  return result;
+}
+const GOVERNANCE_KEY_ARCHIVE_PATH = "/.well-known/jwks-archive.json";
+const ARCHIVE_FAILURE_COOLDOWN_SECONDS = 60;
+class GovernanceKeyArchiveResolver {
+  constructor(options = {}) {
+    this.options = options;
+    const maxAge = options.maxAgeSeconds ?? 300;
+    if (!Number.isFinite(maxAge) || maxAge < 0)
+      throw new TypeError("maxAgeSeconds must be a finite, non-negative number");
+    this.maxOrigins = options.maxOrigins ?? 256;
+    if (!Number.isSafeInteger(this.maxOrigins) || this.maxOrigins < 1)
+      throw new TypeError("maxOrigins must be a positive safe integer");
+  }
+  options;
+  cache = /* @__PURE__ */ new Map();
+  failures = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  maxOrigins;
+  async resolve(origin, kid) {
+    origin = receivedAgentOrigin(canonicalAgentOrigin(origin));
+    const now = (this.options.now ?? (() => Date.now() / 1e3))();
+    const cached = this.cache.get(origin);
+    let keys;
+    if (cached && cached.freshUntil > now) keys = cached.keys;
+    else {
+      const failure = this.failures.get(origin);
+      if (failure && failure.until > now)
+        throw new JwsArtifactError("jws_key_unavailable", "Governance key archive is unavailable", {
+          cause: failure.cause
+        });
+      let pending = this.pending.get(origin);
+      if (!pending) {
+        pending = this.fetch(origin, now);
+        this.pending.set(origin, pending);
+      }
+      try {
+        keys = await pending;
+      } finally {
+        if (this.pending.get(origin) === pending) this.pending.delete(origin);
+      }
+    }
+    return keys.find((key) => key.kid === kid) ?? null;
+  }
+  async fetch(origin, now) {
+    let keys;
+    try {
+      const response = await ssrfSafeFetch(origin + GOVERNANCE_KEY_ARCHIVE_PATH, {
+        ...this.options.fetchOptions,
+        headers: { accept: "application/json" },
+        timeoutMs: 1e4,
+        maxBodyBytes: 1024 * 1024
+      });
+      if (response.status === 404 || response.status === 410) keys = [];
+      else {
+        if (response.status !== 200) throw new Error(`Archive answered ${response.status}`);
+        const document = parseStrictJson(new TextDecoder("utf-8", { fatal: true }).decode(response.body), 32);
+        if (!Array.isArray(document.keys) || document.keys.length > 4096) throw new Error("Invalid key archive");
+        keys = [];
+        for (const raw of document.keys) {
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+          const jwk = raw;
+          if (Object.keys(jwk).some((name) => PRIVATE_JWK_MEMBERS.has(name.toLowerCase()) || name.startsWith("_private")))
+            throw new Error("Key archive publishes private key material");
+          if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string") continue;
+          const thumbprint = jwkThumbprint(jwk);
+          if (jwk.kid !== void 0 && jwk.kid !== thumbprint) continue;
+          if (isRefusedWebBotAuthTestKey(thumbprint, this.options.allowTestKeys)) continue;
+          keys.push({ kty: "OKP", crv: "Ed25519", x: jwk.x, kid: thumbprint });
+        }
+      }
+    } catch (cause) {
+      if (this.failures.size >= this.maxOrigins && !this.failures.has(origin))
+        this.failures.delete(this.failures.keys().next().value);
+      this.failures.set(origin, { until: now + ARCHIVE_FAILURE_COOLDOWN_SECONDS, cause });
+      throw new JwsArtifactError("jws_key_unavailable", "Governance key archive is unavailable", { cause });
+    }
+    this.failures.delete(origin);
+    if (this.cache.size >= this.maxOrigins && !this.cache.has(origin))
+      this.cache.delete(this.cache.keys().next().value);
+    this.cache.set(origin, { keys, freshUntil: now + (this.options.maxAgeSeconds ?? 300) });
+    return keys;
+  }
+}
+const PRIVATE_JWK_MEMBERS = /* @__PURE__ */ new Set(["d", "p", "q", "dp", "dq", "qi", "oth", "k"]);
+export {
+  GOVERNANCE_KEY_ARCHIVE_PATH,
+  GovernanceKeyArchiveResolver,
+  JwsArtifactError,
+  selectJwsArtifactProfile,
+  verifyWebBotAuthJwsArtifact
+};

package/dist/lib/identity-3.3/revocation.d.mts

@@ -78,6 +78,13 @@ export declare class OriginRevocationResolver {
      */
     status(originUrl: string, keyid: string): Promise<OriginRevocationStatus>;
     private currentStatus;
+    /**
+     * The most severe detail stored for a revoked key (R9: `keyCompromise` and
+     * the earliest `invalidity_date` win), or undefined when the key is not
+     * revoked. Reads the history store only; call {@link status} first to refresh.
+     * Throws {@link WebBotAuthUnavailableError} when the store fails.
+     */
+    detail(originUrl: string, keyid: string): Promise<RevocationDetail | undefined>;
     private readStored;
     private refresh;
     private now;

package/dist/lib/identity-3.3/revocation.d.ts

@@ -78,6 +78,13 @@ export declare class OriginRevocationResolver {
      */
     status(originUrl: string, keyid: string): Promise<OriginRevocationStatus>;
     private currentStatus;
+    /**
+     * The most severe detail stored for a revoked key (R9: `keyCompromise` and
+     * the earliest `invalidity_date` win), or undefined when the key is not
+     * revoked. Reads the history store only; call {@link status} first to refresh.
+     * Throws {@link WebBotAuthUnavailableError} when the store fails.
+     */
+    detail(originUrl: string, keyid: string): Promise<RevocationDetail | undefined>;
     private readStored;
     private refresh;
     private now;