wb-auth 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,19 +1,360 @@
 // src/signer.ts
-import { signatureHeaders } from "web-bot-auth";
+import { randomBytes } from "crypto";
+
+// src/identity.ts
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  sign as cryptoSign,
+  generateKeyPairSync
+} from "crypto";
+import { mkdir, open, readFile, rename, stat } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+var DEFAULT_KEY_PATH = resolve(
+  homedir(),
+  ".config",
+  "wbauth",
+  "key.pem"
+);
+var KEY_PASSWORD_ENV = "WBAUTH_KEY_PASSWORD";
+var KEYRING_ACTIVE = "active.pem";
+var KEYRING_RETIRING = "retiring.pem";
+var TEST_KEY_JWK = {
+  kty: "OKP",
+  crv: "Ed25519",
+  d: "n4Ni-HpISpVObnQMW0wOhCKROaIKqKtW_2ZYb2p9KcU",
+  x: "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs"
+};
+var warnedWindows = false;
+function validateSignatureAgentUrl(url) {
+  if (typeof url !== "string" || !url.startsWith("https://")) {
+    throw new Error(`signatureAgentUrl must be https://, got: ${String(url)}`);
+  }
+  for (const ch of url) {
+    const c = ch.charCodeAt(0);
+    if (c < 33 || c > 126 || ch === '"' || ch === "\\") {
+      throw new Error(
+        `signatureAgentUrl must be printable ASCII without spaces, quotes or backslashes, got: ${JSON.stringify(url)}`
+      );
+    }
+  }
+  let host = "";
+  try {
+    host = new URL(url).hostname;
+  } catch {
+  }
+  if (!host) throw new Error(`signatureAgentUrl has no host: ${url}`);
+  return url;
+}
+function validateUserAgent(ua) {
+  if (ua !== void 0 && [...ua].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127)) {
+    throw new Error(
+      `userAgent must not contain control characters: ${JSON.stringify(ua)}`
+    );
+  }
+  return ua;
+}
+var Identity = class _Identity {
+  #active;
+  #retiring;
+  #signatureAgentUrl;
+  #userAgent;
+  constructor(active, opts, retiring = null) {
+    this.#signatureAgentUrl = validateSignatureAgentUrl(opts.signatureAgentUrl);
+    this.#userAgent = validateUserAgent(opts.userAgent);
+    this.#active = active;
+    this.#retiring = retiring;
+  }
+  // ---------- Public read-only API ----------
+  get signatureAgentUrl() {
+    return this.#signatureAgentUrl;
+  }
+  get userAgent() {
+    return this.#userAgent;
+  }
+  /** The active key's kid (used as `keyid=` param in Signature-Input). */
+  get kid() {
+    return this.#active.kid;
+  }
+  /** The active key's public JWK (copy; never contains private material). */
+  get publicJwk() {
+    return { ...this.#active.publicJwk };
+  }
+  /** Module-internal: returns the active Signer for sign() to use. */
+  _signer() {
+    return this.#active.signer;
+  }
+  /** Public JWKS: active first, then the retiring key (if any). */
+  exportJwks() {
+    const keys = [{ ...this.#active.publicJwk }];
+    if (this.#retiring) keys.push({ ...this.#retiring.publicJwk });
+    return { keys };
+  }
+  /**
+   * IDENT-07: generate a new active key, demote current to retiring.
+   * In-memory only — use `rotateKeyring()` to persist. The default path is
+   * a fresh timestamped file next to DEFAULT_KEY_PATH (never collides).
+   */
+  async rotate(newPath, keyOpts = {}) {
+    const path = newPath ? expandUser(newPath) : join(
+      dirname(DEFAULT_KEY_PATH),
+      `key-${Math.floor(Date.now() / 1e3)}.pem`
+    );
+    const newPair = await generateKeypairTo(path, keyOpts);
+    return new _Identity(newPair, this.#opts(), this.#active);
+  }
+  /**
+   * Persisted rotation: `<dir>/active.pem` → `retiring.pem` (replacing the
+   * previous retiring key), then a fresh `active.pem` is generated.
+   */
+  async rotateKeyring(dir, keyOpts = {}) {
+    const d = expandUser(dir);
+    const active = join(d, KEYRING_ACTIVE);
+    const retiring = join(d, KEYRING_RETIRING);
+    await stat(active);
+    await rename(active, retiring);
+    let pair;
+    try {
+      pair = await generateKeypairTo(active, keyOpts);
+    } catch (e) {
+      await rename(retiring, active);
+      throw e;
+    }
+    return new _Identity(
+      pair,
+      this.#opts(),
+      await loadKeypair(retiring, keyOpts)
+    );
+  }
+  #opts() {
+    return {
+      signatureAgentUrl: this.#signatureAgentUrl,
+      userAgent: this.#userAgent
+    };
+  }
+  // ---------- Constructors ----------
+  /**
+   * Loads `path` if it exists, generates a fresh key there otherwise.
+   * Concurrent first starts are safe: the loser of the O_EXCL race loads the
+   * winner's key. `retiringPath` optionally loads the previous key.
+   */
+  static async loadOrGenerate(path = DEFAULT_KEY_PATH, opts) {
+    validateSignatureAgentUrl(opts.signatureAgentUrl);
+    const resolved = expandUser(path);
+    let pair = null;
+    if (!await exists(resolved)) {
+      try {
+        pair = await generateKeypairTo(resolved, opts);
+      } catch (e) {
+        if (e.code !== "EEXIST" && !await exists(resolved))
+          throw e;
+      }
+    }
+    pair ??= await loadKeypair(resolved, opts);
+    let retiring = null;
+    if (opts.retiringPath && await exists(expandUser(opts.retiringPath))) {
+      retiring = await loadKeypair(expandUser(opts.retiringPath), opts);
+    }
+    return new _Identity(pair, opts, retiring);
+  }
+  /** Load an existing key; never creates one. */
+  static async load(path, opts) {
+    return new _Identity(await loadKeypair(expandUser(path), opts), opts);
+  }
+  /** Generate a new key at `path`; never overwrites. */
+  static async generate(path, opts) {
+    validateSignatureAgentUrl(opts.signatureAgentUrl);
+    return new _Identity(await generateKeypairTo(expandUser(path), opts), opts);
+  }
+  /** `<dir>/active.pem` (+ `retiring.pem`), generating active on first use. */
+  static async loadKeyring(dir, opts) {
+    const d = expandUser(dir);
+    return _Identity.loadOrGenerate(join(d, KEYRING_ACTIVE), {
+      ...opts,
+      retiringPath: join(d, KEYRING_RETIRING)
+    });
+  }
+  /** Wrap an external signer (KMS, HSM, keychain). */
+  static async fromSigner(backend, opts) {
+    const jwk = backend.publicJwk;
+    if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x) {
+      throw new TypeError("fromSigner: publicJwk must be an Ed25519 OKP JWK");
+    }
+    const kid = thumbprint(jwk);
+    const enc = new TextEncoder();
+    return new _Identity(
+      {
+        kid,
+        publicJwk: { kty: "OKP", crv: "Ed25519", x: jwk.x, kid },
+        signer: {
+          alg: "ed25519",
+          keyid: kid,
+          sign: async (data) => backend.sign(enc.encode(data))
+        }
+      },
+      opts
+    );
+  }
+  /** RFC 9421 Appendix B.1.4 test key. NEVER use in production. */
+  static async fromTestKey(signatureAgentUrl, opts = {}) {
+    const key = createPrivateKey({ key: TEST_KEY_JWK, format: "jwk" });
+    return new _Identity(keyPairFromKeyObject(key), {
+      ...opts,
+      signatureAgentUrl
+    });
+  }
+  // ---------- Redaction guarantees (IDENT-08) ----------
+  toString() {
+    return `<Identity REDACTED kid='${this.kid}' sig_agent='${this.#signatureAgentUrl}'>`;
+  }
+  /** JSON.stringify(identity) → public data only. */
+  toJSON() {
+    return {
+      kid: this.kid,
+      signatureAgentUrl: this.#signatureAgentUrl,
+      ...this.#userAgent !== void 0 ? { userAgent: this.#userAgent } : {},
+      jwks: this.exportJwks()
+    };
+  }
+  /** util.inspect / console.log render the same REDACTED form (IDENT-08). */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+};
+function expandUser(path) {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/") || path.startsWith("~\\")) {
+    return resolve(homedir(), path.slice(2));
+  }
+  return resolve(path);
+}
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function b64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function thumbprint(jwk) {
+  const canonical = JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x });
+  return b64url(createHash("sha256").update(canonical).digest());
+}
+function keyPairFromKeyObject(privateKey) {
+  const pub = createPublicKey(privateKey).export({
+    format: "jwk"
+  });
+  if (pub.kty !== "OKP" || pub.crv !== "Ed25519") {
+    throw new TypeError(`Expected Ed25519, got kty=${pub.kty}, crv=${pub.crv}`);
+  }
+  const kid = thumbprint(pub);
+  return {
+    kid,
+    publicJwk: { kty: "OKP", crv: "Ed25519", x: pub.x, kid },
+    signer: {
+      alg: "ed25519",
+      keyid: kid,
+      // Sync node:crypto Ed25519 — no WebCrypto import / promise hop.
+      sign: async (data) => new Uint8Array(cryptoSign(null, Buffer.from(data, "utf8"), privateKey))
+    }
+  };
+}
+function passwordFor(opts) {
+  return opts.password ?? (process.env[KEY_PASSWORD_ENV] || void 0);
+}
+async function loadKeypair(path, opts = {}) {
+  if (process.platform !== "win32") {
+    const mode = (await stat(path)).mode & 511;
+    if ((mode & 63) !== 0) {
+      throw new Error(
+        `Key file ${path} has mode 0o${mode.toString(8)}; expected 0o600. Fix: chmod 600 ${path}`
+      );
+    }
+  } else if (!warnedWindows) {
+    warnedWindows = true;
+    process.emitWarning(
+      `Windows detected \u2014 file permissions on ${path} cannot be enforced via POSIX mode. Use NTFS ACLs or store the key in a per-user secrets vault.`
+    );
+  }
+  const pem = await readFile(path, "utf8");
+  const encrypted = pem.includes("ENCRYPTED");
+  const passphrase = passwordFor(opts);
+  if (encrypted && !passphrase) {
+    throw new TypeError(
+      `Key file ${path} is encrypted; pass { password } or set $${KEY_PASSWORD_ENV}`
+    );
+  }
+  const key = createPrivateKey(
+    encrypted ? { key: pem, format: "pem", passphrase } : pem
+  );
+  return keyPairFromKeyObject(key);
+}
+async function generateKeypairTo(path, opts = {}) {
+  await mkdir(dirname(path), { recursive: true });
+  if (await exists(path)) {
+    const err = new Error(
+      `Key already exists at ${path}; refuse overwrite`
+    );
+    err.code = "EEXIST";
+    throw err;
+  }
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const passphrase = passwordFor(opts);
+  const pem = privateKey.export(
+    passphrase ? { format: "pem", type: "pkcs8", cipher: "aes-256-cbc", passphrase } : { format: "pem", type: "pkcs8" }
+  );
+  const fh = await open(path, "wx", 384);
+  try {
+    await fh.writeFile(pem);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  return keyPairFromKeyObject(privateKey);
+}
+
+// src/signer.ts
+var WEB_BOT_AUTH_TAG = "web-bot-auth";
 var DEFAULT_LABEL = "sig1";
 var DEFAULT_EXPIRES_SECONDS = 60;
 var MAX_EXPIRES_SECONDS = 3600;
-function componentsFor(_method, hasBody) {
-  const base = ["@authority", "signature-agent"];
-  if (hasBody) {
-    base.push("content-digest");
+var NONCE_BYTES = 64;
+var SF_KEY_RE = /^[a-z*][a-z0-9_\-.*]*$/;
+var DEFAULT_PORTS = {
+  "https:": "443",
+  "http:": "80"
+};
+function sfString(value) {
+  for (const ch of value) {
+    const c = ch.charCodeAt(0);
+    if (c < 32 || c > 126) {
+      throw new Error(
+        `value is not a valid structured-field string: ${JSON.stringify(value)}`
+      );
+    }
   }
-  return base;
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function normalizeAuthority(url) {
+  const u = new URL(url);
+  if (!u.hostname) throw new Error(`URL has no host: ${url}`);
+  const host = u.hostname.toLowerCase();
+  const port = u.port && u.port !== DEFAULT_PORTS[u.protocol] ? `:${u.port}` : "";
+  return `${host}${port}`;
+}
+function componentsFor(hasBody) {
+  return hasBody ? ["@authority", "signature-agent", "content-digest"] : ["@authority", "signature-agent"];
 }
 var RESIGN_HEADERS = ["signature", "signature-input", "signature-agent"];
-function hasHeader(headers, name) {
+function getHeader(headers, name) {
   const n = name.toLowerCase();
-  return Object.keys(headers).some((k) => k.toLowerCase() === n);
+  const k = Object.keys(headers).find((key) => key.toLowerCase() === n);
+  return k === void 0 ? void 0 : headers[k];
 }
 function removeHeaders(headers, names) {
   for (const k of Object.keys(headers)) {
@@ -21,57 +362,54 @@ function removeHeaders(headers, names) {
   }
 }
 async function sign(request, identity, opts = {}) {
-  if (!identity.signatureAgentUrl.startsWith("https://")) {
-    throw new Error(
-      `signatureAgentUrl must be https://, got: ${identity.signatureAgentUrl}`
-    );
-  }
+  validateSignatureAgentUrl(identity.signatureAgentUrl);
   const expiresAfterSeconds = opts.expiresAfterSeconds ?? DEFAULT_EXPIRES_SECONDS;
   if (typeof expiresAfterSeconds !== "number" || !Number.isFinite(expiresAfterSeconds) || expiresAfterSeconds <= 0 || expiresAfterSeconds > MAX_EXPIRES_SECONDS) {
     throw new RangeError(
       `expiresAfterSeconds must be a number in (0, ${MAX_EXPIRES_SECONDS}], got: ${expiresAfterSeconds}`
     );
   }
-  removeHeaders(request.headers, RESIGN_HEADERS);
-  const signatureAgentHeader = `"${identity.signatureAgentUrl}"`;
-  request.headers["Signature-Agent"] = signatureAgentHeader;
-  const created = opts.created ?? /* @__PURE__ */ new Date();
-  const expires = new Date(created.getTime() + expiresAfterSeconds * 1e3);
   const label = opts.label ?? DEFAULT_LABEL;
-  const hasBody = request.body !== null && request.body !== void 0 && request.body.byteLength > 0;
-  const components = componentsFor(request.method, hasBody);
-  if (components.includes("content-digest") && !hasHeader(request.headers, "content-digest")) {
+  if (!SF_KEY_RE.test(label)) {
     throw new Error(
-      'Covered header field "content-digest" not found in the message. Call ensureContentDigest() or use createSignedFetch()/applyTo(), which add it automatically.'
+      `label must be an RFC 8941 key, got: ${JSON.stringify(label)}`
     );
   }
-  const headers = new Headers();
-  for (const [k, v] of Object.entries(request.headers)) headers.set(k, v);
-  const init = { method: request.method, headers };
-  const m = request.method.toUpperCase();
-  if (hasBody && m !== "GET" && m !== "HEAD") {
-    init.body = request.body;
-  }
-  const req = new Request(request.url, init);
-  const params = {
-    created,
-    expires,
-    key: label,
-    components,
-    ...opts.nonce !== void 0 ? { nonce: opts.nonce } : {}
-  };
-  const result = await signatureHeaders(req, identity._signer(), params);
-  request.headers.Signature = result.Signature;
-  request.headers["Signature-Input"] = result["Signature-Input"];
-  return {
-    signature: result.Signature,
-    signatureInput: result["Signature-Input"],
-    signatureAgent: signatureAgentHeader
+  removeHeaders(request.headers, RESIGN_HEADERS);
+  const signatureAgentHeader = sfString(identity.signatureAgentUrl);
+  request.headers["Signature-Agent"] = signatureAgentHeader;
+  const created = Math.floor((opts.created ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+  const expires = created + Math.floor(expiresAfterSeconds);
+  const nonce = opts.nonce ?? randomBytes(NONCE_BYTES).toString("base64");
+  const hasBody = request.body != null && request.body.byteLength > 0;
+  const components = componentsFor(hasBody);
+  const values = {
+    "@authority": normalizeAuthority(request.url),
+    "signature-agent": signatureAgentHeader
   };
+  if (hasBody) {
+    const cd = getHeader(request.headers, "content-digest");
+    if (cd === void 0) {
+      throw new Error(
+        'Covered header field "content-digest" not found in the message. Call ensureContentDigest() or use createSignedFetch()/applyTo(), which add it automatically.'
+      );
+    }
+    values["content-digest"] = cd.trim();
+  }
+  const signer = identity._signer();
+  const params = `(${components.map((c) => `"${c}"`).join(" ")});created=${created};keyid=${sfString(signer.keyid)};alg="ed25519";expires=${expires};nonce=${sfString(nonce)};tag=${sfString(WEB_BOT_AUTH_TAG)}`;
+  const base = `${components.map((c) => `"${c}": ${values[c]}`).join("\n")}
+"@signature-params": ${params}`;
+  const raw = await signer.sign(base);
+  const signatureInput = `${label}=${params}`;
+  const signature = `${label}=:${Buffer.from(raw).toString("base64")}:`;
+  request.headers["Signature-Input"] = signatureInput;
+  request.headers.Signature = signature;
+  return { signature, signatureInput, signatureAgent: signatureAgentHeader };
 }
 
 // src/adapters/_utils.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 var LIBRARY_DEFAULT_UA = /^(node|undici|node-fetch)(\/|$)/i;
 function findHeader(headers, name) {
   const n = name.toLowerCase();
@@ -80,10 +418,41 @@ function findHeader(headers, name) {
 function ensureContentDigest(method, headers, body) {
   if (!body || body.byteLength === 0) return;
   void method;
-  if (findHeader(headers, "content-digest")) return;
-  const b64 = createHash("sha256").update(body).digest("base64");
+  const b64 = createHash2("sha256").update(body).digest("base64");
+  const key = findHeader(headers, "content-digest");
+  if (key !== void 0) {
+    const m = /(?:^|,)\s*sha-256=:([A-Za-z0-9+/=]+):/.exec(headers[key] ?? "");
+    if (m === null || m[1] === b64) return;
+    delete headers[key];
+  }
   headers["Content-Digest"] = `sha-256=:${b64}:`;
 }
+var SIGNATURE_HEADERS = /* @__PURE__ */ new Set([
+  "signature",
+  "signature-input",
+  "signature-agent"
+]);
+function stripSignatureHeaders(headers) {
+  for (const k of Object.keys(headers)) {
+    if (SIGNATURE_HEADERS.has(k.toLowerCase())) delete headers[k];
+  }
+}
+function makeSignDecider(opts = {}) {
+  return (raw) => {
+    let u;
+    try {
+      u = new URL(raw);
+    } catch {
+      return false;
+    }
+    if (u.protocol !== "https:" && u.protocol !== "http:") return false;
+    if (!u.hostname) return false;
+    if (u.protocol === "http:" && !opts.allowInsecure) return false;
+    if (opts.shouldSign) return opts.shouldSign(u);
+    if (opts.hosts) return hostMatches(u.hostname, opts.hosts);
+    return true;
+  };
+}
 function applyUserAgent(headers, userAgent) {
   if (!userAgent) return;
   const key = findHeader(headers, "user-agent");
@@ -129,6 +498,7 @@ function dropHeaders(headers, names) {
   }
 }
 function createSignedFetch(identity, options = {}) {
+  const decide = makeSignDecider(options);
   return async function signedFetch(input, init = {}) {
     const req = new Request(input, init);
     let method = req.method;
@@ -148,8 +518,12 @@ function createSignedFetch(identity, options = {}) {
     const doFetch = options.fetch ?? globalThis.fetch;
     for (let hop = 0; ; hop++) {
       const headers = { ...baseHeaders };
-      ensureContentDigest(method, headers, body);
-      await sign({ method, url, headers, body }, identity);
+      if (decide(url)) {
+        ensureContentDigest(method, headers, body);
+        await sign({ method, url, headers, body }, identity);
+      } else {
+        stripSignatureHeaders(headers);
+      }
       applyUserAgent(headers, identity.userAgent);
       const outInit = {
         ...init,
@@ -196,19 +570,8 @@ function createSignedFetch(identity, options = {}) {
 // src/adapters/playwright.ts
 async function applyTo(page, identity, options = {}) {
   const pattern = options.pattern ?? "**/*";
-  const decide = (raw) => {
-    let u;
-    try {
-      u = new URL(raw);
-    } catch {
-      return false;
-    }
-    if (u.protocol !== "https:" && u.protocol !== "http:") return false;
-    if (options.shouldSign) return options.shouldSign(u);
-    if (options.hosts) return hostMatches(u.hostname, options.hosts);
-    return true;
-  };
-  await page.route(pattern, async (route, request) => {
+  const decide = makeSignDecider(options);
+  const handler = async (route, request) => {
     const url = request.url();
     if (!decide(url)) {
       const r = route;
@@ -222,175 +585,320 @@ async function applyTo(page, identity, options = {}) {
     await sign({ method: request.method(), url, headers, body }, identity);
     applyUserAgent(headers, identity.userAgent);
     await route.continue({ headers });
-  });
+  };
+  await page.route(pattern, handler);
+  return async () => {
+    await page.unroute(pattern, handler);
+  };
 }
 
-// src/identity.ts
-import { createPrivateKey, generateKeyPairSync } from "crypto";
+// src/verifier.ts
 import {
-  closeSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  statSync,
-  writeFileSync
-} from "fs";
-import { homedir } from "os";
-import { dirname, resolve } from "path";
-import { signerFromJWK } from "web-bot-auth/crypto";
-var DEFAULT_KEY_PATH = resolve(
-  homedir(),
-  ".config",
-  "wbauth",
-  "key.pem"
-);
-var TEST_KEY_JWK = {
-  kty: "OKP",
-  crv: "Ed25519",
-  d: "n4Ni-HpISpVObnQMW0wOhCKROaIKqKtW_2ZYb2p9KcU",
-  x: "JrQLj5P_89iXES9-vFgrIy29clF9CC_oPPsw3c5D0bs"
+  createHash as createHash3,
+  createPublicKey as createPublicKey2,
+  verify as cryptoVerify
+} from "crypto";
+var DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+var DIRECTORY_MAX_BYTES = 64 * 1024;
+var VerificationError = class extends Error {
+  name = "VerificationError";
 };
-var Identity = class _Identity {
-  _active;
-  _retiring;
-  signatureAgentUrl;
-  userAgent;
-  constructor(active, opts, retiring = null) {
-    if (!opts.signatureAgentUrl.startsWith("https://")) {
-      throw new Error(
-        `signatureAgentUrl must be https://, got: ${opts.signatureAgentUrl}`
-      );
-    }
-    this._active = active;
-    this._retiring = retiring;
-    this.signatureAgentUrl = opts.signatureAgentUrl;
-    this.userAgent = opts.userAgent;
+var NonceStore = class {
+  constructor(maxSize = 1e5) {
+    this.maxSize = maxSize;
   }
-  // ---------- Public read-only API ----------
-  /** The active key's kid (used as `keyid=` param in Signature-Input). */
-  get kid() {
-    return this._active.kid;
-  }
-  /** Module-internal: returns the resolved Signer for sign() to use. */
-  _signer() {
-    return this._active.signer;
+  maxSize;
+  #seen = /* @__PURE__ */ new Map();
+  seen(nonce, expiresAt) {
+    const now = Date.now() / 1e3;
+    if (this.#seen.size >= this.maxSize) {
+      for (const [n, e] of this.#seen) if (e <= now) this.#seen.delete(n);
+      for (const n of [...this.#seen.keys()].slice(
+        0,
+        Math.ceil(this.maxSize / 10)
+      )) {
+        if (this.#seen.size < this.maxSize) break;
+        this.#seen.delete(n);
+      }
+    }
+    const prev = this.#seen.get(nonce);
+    if (prev !== void 0 && prev > now) return true;
+    this.#seen.set(nonce, expiresAt);
+    return false;
   }
-  /**
-   * Export the public JWKS document.
-   *
-   * Returns `{keys: [active_jwk]}` if no retiring key is held, or
-   * `{keys: [active_jwk, retiring_jwk]}` after a rotation. Active is always
-   * first. Verifiers select by `kid`. Mirror of Python `export_jwks`.
-   */
-  exportJwks() {
-    const keys = [this._active.publicJwk];
-    if (this._retiring) keys.push(this._retiring.publicJwk);
-    return { keys };
+};
+var SF_STRING = String.raw`"(?:[^"\\]|\\.)*"`;
+var PARAM = String.raw`;\s*([a-z*][a-z0-9_.*-]*)(?:=(${SF_STRING}|-?\d+(?:\.\d+)?|\?[01]|[A-Za-z*][^;,\s]*))?`;
+var SIG_INPUT_RE = new RegExp(
+  String.raw`\s*([a-z*][a-z0-9_.*-]*)=(\((?:\s*${SF_STRING}(?:;[^\s)"]+)*)*\s*\))((?:${PARAM})*)`,
+  "y"
+);
+var unquote = (v) => v.startsWith('"') ? v.slice(1, -1).replace(/\\(.)/g, "$1") : v;
+function parseSignatureInput(value) {
+  const out = [];
+  let pos = 0;
+  while (pos < value.length) {
+    SIG_INPUT_RE.lastIndex = pos;
+    const m = SIG_INPUT_RE.exec(value);
+    if (!m) throw new VerificationError("malformed Signature-Input");
+    const [, label = "", inner = "", rest = ""] = m;
+    if (/"\s*;/.test(inner))
+      throw new VerificationError("component parameters are not supported");
+    const params = {};
+    for (const p of rest.matchAll(new RegExp(PARAM, "g"))) {
+      const k = p[1];
+      const v = p[2];
+      params[k] = v === void 0 ? true : v.startsWith('"') ? unquote(v) : /^-?\d+$/.test(v) ? Number(v) : v;
+    }
+    out.push({
+      label,
+      rawParams: inner + rest,
+      components: [...inner.matchAll(new RegExp(SF_STRING, "g"))].map(
+        (x) => unquote(x[0])
+      ),
+      params
+    });
+    pos = SIG_INPUT_RE.lastIndex;
+    while (pos < value.length && (value[pos] === " " || value[pos] === ","))
+      pos++;
   }
-  /**
-   * IDENT-07: generate a new active key, demote current to retiring.
-   *
-   * Returns a NEW Identity (immutable update — the old Identity is unchanged).
-   * Any previously-retiring key is dropped (only one overlap window).
-   */
-  async rotate(newPath = DEFAULT_KEY_PATH) {
-    const newPair = await generateKeypairTo(expandUser(newPath));
-    return new _Identity(
-      newPair,
-      { signatureAgentUrl: this.signatureAgentUrl, userAgent: this.userAgent },
-      this._active
-    );
+  return out;
+}
+function parseSignature(value) {
+  const out = /* @__PURE__ */ new Map();
+  for (const m of value.matchAll(
+    /\s*([a-z*][a-z0-9_.*-]*)=:([A-Za-z0-9+/=]*):/g
+  )) {
+    out.set(m[1], Buffer.from(m[2], "base64"));
   }
-  // ---------- Constructors ----------
-  /**
-   * Primary entry point. Loads `path` if it exists, generates a fresh key
-   * there otherwise. The on-disk file is PKCS8 NoEncryption PEM at 0o600,
-   * byte-equal to what Python's `Identity.load_or_generate` writes (D-60).
-   */
-  static async loadOrGenerate(path = DEFAULT_KEY_PATH, opts) {
-    const resolved = expandUser(path);
-    const pair = existsSync(resolved) ? await loadKeypair(resolved) : await generateKeypairTo(resolved);
-    return new _Identity(pair, opts);
+  return out;
+}
+function componentValue(name, req, headers, authority) {
+  const u = new URL(req.url);
+  switch (name) {
+    case "@authority":
+      return authority ?? normalizeAuthority(req.url);
+    case "@method":
+      return req.method.toUpperCase();
+    case "@scheme":
+      return u.protocol.slice(0, -1);
+    case "@target-uri":
+      return u.href;
+    case "@path":
+      return u.pathname || "/";
+    case "@query":
+      return u.search || "?";
   }
-  /**
-   * Construct from the RFC 9421 Appendix B.1.4 publicly-known test key.
-   * For tests + Cloudflare debug smoke checks. NEVER use in production.
-   * Does NOT write any file to disk.
-   */
-  static async fromTestKey(signatureAgentUrl, opts = {}) {
-    const pair = await keyPairFromJwk(TEST_KEY_JWK);
-    return new _Identity(pair, { ...opts, signatureAgentUrl });
+  if (name.startsWith("@"))
+    throw new VerificationError(`unsupported derived component ${name}`);
+  const v = headers.get(name);
+  if (v === null) throw new VerificationError(`covered header ${name} missing`);
+  return v.trim();
+}
+function directoryUrl(signatureAgent) {
+  const u = new URL(signatureAgent);
+  if (u.protocol !== "https:")
+    throw new VerificationError("Signature-Agent must be https://");
+  if (u.pathname === "/" || u.pathname === "") {
+    u.pathname = DIRECTORY_PATH;
+    u.search = "";
   }
-  // ---------- Redaction guarantees (IDENT-08) ----------
-  toString() {
-    return `<Identity REDACTED kid='${this.kid}' sig_agent='${this.signatureAgentUrl}'>`;
+  u.hash = "";
+  return u.href;
+}
+var Verifier = class {
+  #opts;
+  #nonces;
+  #jwks = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.#opts = opts;
+    this.#nonces = opts.nonceStore ?? new NonceStore();
   }
-  /** util.inspect / console.log render the same REDACTED form (IDENT-08). */
-  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
-    return this.toString();
+  async #directoryKeys(url) {
+    const hit = this.#jwks.get(url);
+    if (hit && hit.until > Date.now()) return hit.keys;
+    const f = this.#opts.fetch ?? globalThis.fetch;
+    let res;
+    try {
+      res = await f(url, {
+        headers: {
+          accept: "application/http-message-signatures-directory+json, application/json"
+        },
+        redirect: "error",
+        signal: AbortSignal.timeout(3e3)
+      });
+    } catch (e) {
+      throw new VerificationError(`directory unreachable: ${String(e)}`);
+    }
+    if (res.status !== 200)
+      throw new VerificationError(`directory ${url} answered ${res.status}`);
+    const buf = await res.arrayBuffer();
+    if (buf.byteLength > DIRECTORY_MAX_BYTES)
+      throw new VerificationError("directory too large");
+    let keys;
+    try {
+      keys = JSON.parse(new TextDecoder().decode(buf)).keys;
+    } catch {
+      throw new VerificationError("directory is not a JWKS");
+    }
+    if (!Array.isArray(keys))
+      throw new VerificationError("directory is not a JWKS");
+    this.#jwks.set(url, {
+      until: Date.now() + (this.#opts.jwksTtlSeconds ?? 300) * 1e3,
+      keys
+    });
+    return keys;
   }
-};
-function expandUser(path) {
-  return resolve(path.startsWith("~") ? path.replace(/^~/, homedir()) : path);
-}
-async function keyPairFromJwk(privateJwk) {
-  const signer = await signerFromJWK(privateJwk);
-  const kid = signer.keyid;
-  const publicJwk = {
-    kty: privateJwk.kty,
-    crv: privateJwk.crv,
-    x: privateJwk.x,
-    kid
-  };
-  return { privateJwk, publicJwk, kid, signer };
-}
-async function loadKeypair(path) {
-  if (process.platform !== "win32") {
-    const mode = statSync(path).mode & 511;
-    if ((mode & 63) !== 0) {
-      throw new Error(
-        `Key file ${path} has mode 0o${mode.toString(8)}; expected 0o600. Fix: chmod 600 ${path}`
+  async #resolve(kid, signatureAgent) {
+    if (this.#opts.keyResolver) {
+      const jwk = await this.#opts.keyResolver(kid, signatureAgent);
+      if (!jwk) throw new VerificationError(`unknown keyid ${kid}`);
+      return jwk;
+    }
+    if (!signatureAgent)
+      throw new VerificationError(
+        "no Signature-Agent and no keyResolver configured"
       );
+    for (const k of await this.#directoryKeys(directoryUrl(signatureAgent))) {
+      if (k && k.kty === "OKP" && k.crv === "Ed25519" && k.x && thumbprint(k) === kid)
+        return k;
     }
-  } else {
-    process.emitWarning(
-      `Windows detected \u2014 file permissions on ${path} cannot be enforced via POSIX mode. Use NTFS ACLs or store the key in a per-user secrets vault.`
+    throw new VerificationError(
+      `keyid ${kid} not published by ${signatureAgent}`
     );
   }
-  const pem = readFileSync(path, "utf8");
-  const jwk = createPrivateKey(pem).export({ format: "jwk" });
-  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519") {
-    throw new TypeError(`Expected Ed25519, got kty=${jwk.kty}, crv=${jwk.crv}`);
-  }
-  return keyPairFromJwk(jwk);
-}
-async function generateKeypairTo(path) {
-  const dir = dirname(path);
-  mkdirSync(dir, { recursive: true });
-  if (existsSync(path)) {
-    throw new Error(`Key already exists at ${path}; refuse overwrite`);
-  }
-  const { privateKey } = generateKeyPairSync("ed25519");
-  const pem = privateKey.export({ format: "pem", type: "pkcs8" });
-  const fd = openSync(path, "wx", 384);
-  try {
-    writeFileSync(fd, pem);
-  } finally {
-    closeSync(fd);
+  /**
+   * Verify a WHATWG Request (body is read from a clone). `authority`
+   * overrides the value derived from the URL (e.g. behind a proxy).
+   */
+  async verify(request, opts = {}) {
+    const h = request.headers;
+    const sigInput = h.get("signature-input");
+    const sigHeader = h.get("signature");
+    if (!sigInput || !sigHeader)
+      throw new VerificationError("request is not signed");
+    const sigs = parseSignature(sigHeader);
+    const cand = parseSignatureInput(sigInput).find(
+      (c) => c.params.tag === WEB_BOT_AUTH_TAG
+    );
+    if (!cand)
+      throw new VerificationError('no signature with tag="web-bot-auth"');
+    const { label, rawParams, components, params } = cand;
+    const raw = sigs.get(label);
+    if (!raw) throw new VerificationError(`Signature has no ${label} member`);
+    if ((params.alg ?? "ed25519") !== "ed25519")
+      throw new VerificationError("only alg=ed25519 is supported");
+    const { created, expires, keyid } = params;
+    if (typeof created !== "number" || typeof expires !== "number" || typeof keyid !== "string") {
+      throw new VerificationError("created, expires and keyid are required");
+    }
+    const skew = this.#opts.maxSkew ?? 5;
+    const now = opts.now ?? Date.now() / 1e3;
+    if (created > now + skew)
+      throw new VerificationError("signature created in the future");
+    if (expires < now - skew) throw new VerificationError("signature expired");
+    if (expires <= created || expires - created > MAX_EXPIRES_SECONDS) {
+      throw new VerificationError("invalid validity window");
+    }
+    if (!components.includes("@authority"))
+      throw new VerificationError("@authority must be covered");
+    let signatureAgent = null;
+    const sa = h.get("signature-agent");
+    if (sa !== null) {
+      if (!components.includes("signature-agent")) {
+        throw new VerificationError("Signature-Agent sent but not covered");
+      }
+      signatureAgent = unquote(sa.trim());
+    }
+    const body = request.body ? new Uint8Array(await request.clone().arrayBuffer()) : new Uint8Array();
+    if (body.byteLength > 0) {
+      if (!components.includes("content-digest")) {
+        throw new VerificationError(
+          "request has a body but content-digest is not covered"
+        );
+      }
+      const m = /(?:^|,)\s*sha-256=:([A-Za-z0-9+/=]+):/.exec(
+        h.get("content-digest") ?? ""
+      );
+      const actual = createHash3("sha256").update(body).digest("base64");
+      if (!m || m[1] !== actual)
+        throw new VerificationError("Content-Digest does not match the body");
+    }
+    const nonce = typeof params.nonce === "string" ? params.nonce : null;
+    if (this.#opts.requireNonce && !nonce)
+      throw new VerificationError("nonce required");
+    const base = [
+      ...components.map(
+        (c) => `"${c}": ${componentValue(c, request, h, opts.authority)}`
+      ),
+      `"@signature-params": ${rawParams}`
+    ].join("\n");
+    const jwk = await this.#resolve(keyid, signatureAgent);
+    let ok = false;
+    try {
+      const key = createPublicKey2({
+        key: { kty: "OKP", crv: "Ed25519", x: jwk.x },
+        format: "jwk"
+      });
+      ok = cryptoVerify(null, Buffer.from(base, "utf8"), key, raw);
+    } catch {
+      ok = false;
+    }
+    if (!ok) throw new VerificationError("signature does not verify");
+    if (nonce && this.#nonces.seen(nonce, expires + skew))
+      throw new VerificationError("nonce replayed");
+    return {
+      kid: keyid,
+      signatureAgentUrl: signatureAgent,
+      label,
+      created,
+      expires,
+      nonce,
+      covered: components,
+      jwk
+    };
   }
-  const jwk = privateKey.export({ format: "jwk" });
-  return keyPairFromJwk(jwk);
+};
+function createVerifierMiddleware(opts = {}) {
+  const verifier = new Verifier(opts);
+  return async (request) => {
+    const signed = request.headers.has("signature-input");
+    if (!signed && !opts.required) return null;
+    try {
+      if (!signed) throw new VerificationError("request is not signed");
+      return await verifier.verify(request);
+    } catch (e) {
+      if (!opts.required) return null;
+      return new Response(
+        JSON.stringify({
+          error: "web_bot_auth",
+          reason: String(e.message)
+        }),
+        {
+          status: 401,
+          headers: { "content-type": "application/json" }
+        }
+      );
+    }
+  };
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 export {
   DEFAULT_KEY_PATH,
   Identity,
+  KEY_PASSWORD_ENV,
+  NonceStore,
   VERSION,
+  VerificationError,
+  Verifier,
   applyTo,
   createSignedFetch,
-  sign
+  createVerifierMiddleware,
+  normalizeAuthority,
+  sign,
+  thumbprint,
+  validateSignatureAgentUrl
 };
 //# sourceMappingURL=index.js.map