@agentsbloom/sdk 0.4.0 → 0.5.0

package/lib/http-signatures.js

@@ -0,0 +1,874 @@
+/**
+ * RFC 9421 HTTP Message Signature verification for incoming agent requests.
+ *
+ * This module replaces the inline, regex-driven verifier that lived in
+ * `index.js`. Extracting it is not cosmetic — the old code interleaved
+ * parsing, key resolution, canonicalization and crypto in one `try` block
+ * inside a 1,300-line request handler, which is why several of the defects
+ * below survived three hardening passes.
+ *
+ * What changed, and why each one mattered
+ * ---------------------------------------
+ *
+ * 1. **Real structured-field parsing.** `keyid` used to be pulled with
+ *    `/keyid="([^"]+)"/` — the first match ANYWHERE in the header, including
+ *    inside a quoted covered-component name. The key used to verify could
+ *    therefore differ from the key named in the signed parameters. Component
+ *    parameters (`;sf`, `;bs`, `;req`, `;key`) were dropped silently, so a
+ *    signature over `"content-digest";sf` verified against the canonical
+ *    value of plain `"content-digest"`.
+ *
+ * 2. **ECDSA actually works.** `crypto.verify(hash, base, key, sig)` defaults
+ *    to DER-encoded ECDSA signatures. RFC 9421 (and WebCrypho, and JOSE)
+ *    use raw `r||s`. Every genuine ES256/ES384/ES512 signature therefore
+ *    failed verification, while `/ap2/capabilities` advertised support for
+ *    all three. Now pinned with `dsaEncoding: 'ieee-p1363'`.
+ *
+ * 3. **Algorithm is pinned to the key, precisely.** The old check was a
+ *    family prefix test (`rsa` ↔ `rs*`, `ec` ↔ `es*`), so `ES256` against a
+ *    P-521 key passed the policy gate. Curves and RSA modulus size are now
+ *    checked explicitly, and symmetric (`oct`) JWKs are refused outright — a
+ *    published HMAC key is a forgeable key.
+ *
+ * 4. **Authority binding is required by default, and the authority is
+ *    validated.** Without `@authority` in the covered components, a signature
+ *    captured at store A is structurally valid at store B for the same path —
+ *    a real cross-merchant replay whenever two stores trust the same JWKS.
+ *
+ *    Covering `@authority` is necessary but NOT sufficient on its own: the
+ *    canonical value comes from the request's own `Host` header, so an
+ *    attacker replaying store A's signature at store B need only send
+ *    `Host: store-a.com` for the base to reconstruct identically. Binding is
+ *    therefore only real when the verifier also knows which authorities are
+ *    legitimately its own — hence `expectedAuthorities`.
+ *
+ * 5. **Missing covered headers fail.** `req.headers[comp] || ''` meant a
+ *    header the client signed but an intermediary stripped verified against
+ *    the empty string.
+ *
+ * 6. **The digest covers the received bytes.** See `resolveBodyBytes`.
+ *
+ * 7. **Nonce records outlive the acceptance window.** The replay TTL used to
+ *    be the signature's own `expires`, which the freshness rules allow to be
+ *    up to `clockSkewMs` in the PAST — so a near-expired signature recorded
+ *    its nonce for as little as one second and then replayed freely inside
+ *    the remaining skew window.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9421
+ */
+
+import crypto from 'crypto';
+import dns from 'dns';
+
+import { parseDictionary, ByteSequence, StructuredFieldError } from './structured-fields.js';
+import {
+  buildSignatureBase,
+  verifyContentDigest,
+  resolveBodyBytes,
+  normalizeAuthority,
+  PROFILE_STRICT,
+  PROFILE_LEGACY,
+  SignatureBaseError,
+} from './signature-base.js';
+
+/** Components every AgentsBloom signature must cover in strict mode. */
+export const STRICT_REQUIRED_COMPONENTS = ['@method', '@authority', '@path'];
+/** Components required by the legacy profile (no authority binding). */
+export const LEGACY_REQUIRED_COMPONENTS = ['@method', '@path'];
+
+const JWKS_CACHE_MAX_ENTRIES = 500;
+const JWKS_POSITIVE_TTL_MS = 60 * 60 * 1000;
+const JWKS_NEGATIVE_TTL_MS = 60 * 1000;
+const JWKS_FETCH_TIMEOUT_MS = 5000;
+const JWKS_MAX_BYTES = 256 * 1024;
+const JWKS_MAX_KEYS = 100;
+
+const MIN_RSA_MODULUS_BITS = 2048;
+const NONCE_PATTERN = /^[\x21-\x7e]{16,256}$/;
+/** Bounds the keyid before it is used in a cache key or a log line. */
+const KEYID_PATTERN = /^[\x21-\x7e]{1,256}$/;
+
+/**
+ * Signature algorithm registry.
+ *
+ * Keys are the lowercased `alg` parameter. Both the RFC 9421 HTTP Signature
+ * Algorithms registry names and the JOSE names are accepted, because the
+ * agent SDK and JWKS `alg` fields use JOSE spellings while the RFC registry
+ * is what a conformant third-party client will send.
+ *
+ * `rsa-v1_5-sha384` / `-sha512` are not registered names, but the previous
+ * implementation accepted them via prefix matching and the regression suite
+ * pins SHA-384, so they stay — explicitly, with the right hash.
+ */
+const ALGORITHMS = Object.freeze({
+  // --- RFC 9421 registry ---
+  'rsa-pss-sha512': { canonical: 'rsa-pss-sha512', kty: 'RSA', hash: 'sha512', rsaPadding: 'pss' },
+  'rsa-v1_5-sha256': { canonical: 'rsa-v1_5-sha256', kty: 'RSA', hash: 'sha256', rsaPadding: 'pkcs1' },
+  'rsa-v1_5-sha384': { canonical: 'rsa-v1_5-sha384', kty: 'RSA', hash: 'sha384', rsaPadding: 'pkcs1' },
+  'rsa-v1_5-sha512': { canonical: 'rsa-v1_5-sha512', kty: 'RSA', hash: 'sha512', rsaPadding: 'pkcs1' },
+  'ecdsa-p256-sha256': { canonical: 'ecdsa-p256-sha256', kty: 'EC', hash: 'sha256', curve: 'prime256v1', jwkCrv: 'P-256' },
+  'ecdsa-p384-sha384': { canonical: 'ecdsa-p384-sha384', kty: 'EC', hash: 'sha384', curve: 'secp384r1', jwkCrv: 'P-384' },
+  'ecdsa-p521-sha512': { canonical: 'ecdsa-p521-sha512', kty: 'EC', hash: 'sha512', curve: 'secp521r1', jwkCrv: 'P-521' },
+  ed25519: { canonical: 'ed25519', kty: 'OKP', hash: null, jwkCrv: 'Ed25519' },
+  // --- JOSE aliases, mapped onto the SAME canonical algorithm ---
+  //
+  // The `canonical` field exists because one algorithm has several registered
+  // spellings and a JWK may be pinned with a different one than the signature
+  // declares. Node's WebCrypto, for instance, exports an Ed25519 public JWK
+  // with `alg: "Ed25519"` while JOSE clients send `alg="EdDSA"`. Comparing the
+  // raw strings rejected a perfectly valid signature.
+  rs256: { canonical: 'rsa-v1_5-sha256', kty: 'RSA', hash: 'sha256', rsaPadding: 'pkcs1' },
+  rs384: { canonical: 'rsa-v1_5-sha384', kty: 'RSA', hash: 'sha384', rsaPadding: 'pkcs1' },
+  rs512: { canonical: 'rsa-v1_5-sha512', kty: 'RSA', hash: 'sha512', rsaPadding: 'pkcs1' },
+  ps256: { canonical: 'rsa-pss-sha256', kty: 'RSA', hash: 'sha256', rsaPadding: 'pss' },
+  ps384: { canonical: 'rsa-pss-sha384', kty: 'RSA', hash: 'sha384', rsaPadding: 'pss' },
+  ps512: { canonical: 'rsa-pss-sha512', kty: 'RSA', hash: 'sha512', rsaPadding: 'pss' },
+  es256: { canonical: 'ecdsa-p256-sha256', kty: 'EC', hash: 'sha256', curve: 'prime256v1', jwkCrv: 'P-256' },
+  es384: { canonical: 'ecdsa-p384-sha384', kty: 'EC', hash: 'sha384', curve: 'secp384r1', jwkCrv: 'P-384' },
+  es512: { canonical: 'ecdsa-p521-sha512', kty: 'EC', hash: 'sha512', curve: 'secp521r1', jwkCrv: 'P-521' },
+  eddsa: { canonical: 'ed25519', kty: 'OKP', hash: null, jwkCrv: 'Ed25519' },
+});
+
+/** Algorithms advertised in discovery documents; kept in sync with the table. */
+export const SUPPORTED_SIGNATURE_ALGORITHMS = Object.freeze(Object.keys(ALGORITHMS));
+
+/**
+ * A verification failure. `publicMessage` is what the caller may see;
+ * `detail` is for the server log only.
+ */
+class VerificationFailure extends Error {
+  constructor({ status = 403, code = 'invalid_signature', publicMessage = 'Invalid HTTP Message Signature.', detail }) {
+    super(detail || publicMessage);
+    this.name = 'VerificationFailure';
+    this.status = status;
+    this.code = code;
+    this.publicMessage = publicMessage;
+    this.detail = detail || publicMessage;
+  }
+}
+
+function reject(detail, overrides = {}) {
+  throw new VerificationFailure({ detail, ...overrides });
+}
+
+// ---------------------------------------------------------------------------
+// SSRF protection for outbound JWKS fetches
+// ---------------------------------------------------------------------------
+
+/**
+ * True when a hostname or IP literal points somewhere a merchant's server
+ * must never be tricked into fetching: loopback, link-local (cloud metadata),
+ * RFC 1918, CGNAT, multicast, and IPv6 equivalents.
+ *
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isBlockedSsrfHostname(hostname) {
+  const host = String(hostname || '').trim().toLowerCase().replace(/^\[|\]$/g, '');
+  if (!host) return true;
+  if (host === 'localhost' || host.endsWith('.localhost') || host === '0.0.0.0') return true;
+  if (host === '::' || host === '::1') return true;
+  if (host.startsWith('127.')) return true;
+  if (host.startsWith('169.254.') || host.startsWith('fe80:')) return true;
+  if (host.startsWith('10.') || host.startsWith('192.168.')) return true;
+  // IPv6 unique-local (fc00::/7) and IPv4-mapped forms.
+  if (/^f[cd][0-9a-f]{2}:/.test(host)) return true;
+  if (host.startsWith('::ffff:')) return isBlockedSsrfHostname(host.slice('::ffff:'.length));
+
+  const parts = host.split('.');
+  if (parts.length === 4 && parts.every((part) => /^\d{1,3}$/.test(part))) {
+    const [a, b] = parts.map(Number);
+    if (parts.some((part) => Number(part) > 255)) return true;
+    if (a === 0 || a >= 224) return true; // "this network", multicast, reserved
+    if (a === 10) return true;
+    if (a === 127) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+    if (a === 198 && (b === 18 || b === 19)) return true; // benchmarking
+  }
+  return false;
+}
+
+/**
+ * Resolves a hostname and refuses it when ANY resolved address is private.
+ *
+ * Blocking by hostname alone is trivially bypassed: an attacker-controlled
+ * (or merely misconfigured) DNS name can resolve to 169.254.169.254. This
+ * still has a TOCTOU window against a rebinding attacker, but it closes the
+ * single-lookup bypass, which is the realistic case for a config mistake.
+ *
+ * @param {string} hostname
+ */
+async function assertPublicHostname(hostname) {
+  if (isBlockedSsrfHostname(hostname)) {
+    reject(`JWKS host "${hostname}" resolves to a private or reserved address`, { status: 503, code: 'jwks_blocked' });
+  }
+  // An IP literal needs no lookup; the check above already covered it.
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.includes(':')) return;
+  let addresses;
+  try {
+    addresses = await dns.promises.lookup(hostname, { all: true, verbatim: true });
+  } catch (err) {
+    reject(`JWKS host "${hostname}" could not be resolved: ${err.code || err.message}`, {
+      status: 503,
+      code: 'jwks_unreachable',
+    });
+  }
+  for (const { address } of addresses) {
+    if (isBlockedSsrfHostname(address)) {
+      reject(`JWKS host "${hostname}" resolves to the private address ${address}`, {
+        status: 503,
+        code: 'jwks_blocked',
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JWKS cache
+// ---------------------------------------------------------------------------
+
+/**
+ * A bounded, swept JWKS cache. Positive entries hold a `KeyObject`; negative
+ * entries record "this JWKS does not contain that kid" so an attacker cannot
+ * turn unknown key ids into one outbound HTTPS fetch per request.
+ */
+export function createJwksCache({ maxEntries = JWKS_CACHE_MAX_ENTRIES } = {}) {
+  const entries = new Map();
+
+  return {
+    get(cacheKey) {
+      const entry = entries.get(cacheKey);
+      if (!entry) return null;
+      if (entry.expires <= Date.now()) {
+        entries.delete(cacheKey);
+        return null;
+      }
+      return entry;
+    },
+    put(cacheKey, entry) {
+      if (entries.size >= maxEntries) {
+        const now = Date.now();
+        for (const [key, value] of entries) {
+          if (value.expires <= now) entries.delete(key);
+        }
+        if (entries.size >= maxEntries) {
+          const oldest = entries.keys().next().value;
+          if (oldest !== undefined) entries.delete(oldest);
+        }
+      }
+      entries.set(cacheKey, entry);
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    },
+  };
+}
+
+/** JWK members that indicate PRIVATE key material. */
+const PRIVATE_JWK_MEMBERS = ['d', 'p', 'q', 'dp', 'dq', 'qi', 'k'];
+
+/**
+ * Validates a JWK against the declared algorithm and turns it into a Node
+ * public `KeyObject`.
+ *
+ * @param {Record<string, unknown>} jwk
+ * @param {string} algName - lowercased alg parameter
+ * @returns {crypto.KeyObject}
+ */
+function importVerificationKey(jwk, algName) {
+  const spec = ALGORITHMS[algName];
+  if (!spec) reject(`unsupported signature algorithm "${algName}"`);
+
+  if (!jwk || typeof jwk !== 'object') reject('JWKS entry is not an object');
+
+  // A symmetric key in a published JWKS is a public secret: anyone who can
+  // read the JWKS could forge signatures. Refuse rather than "support HMAC".
+  if (jwk.kty === 'oct') {
+    reject('JWKS contains a symmetric (oct) key; published symmetric keys are forgeable');
+  }
+  for (const member of PRIVATE_JWK_MEMBERS) {
+    if (jwk[member] !== undefined) {
+      reject(`JWKS entry contains private key material ("${member}")`);
+    }
+  }
+  if (jwk.kty !== spec.kty) {
+    reject(`JWKS key type "${jwk.kty}" does not match algorithm "${algName}" (expects ${spec.kty})`);
+  }
+  if (spec.jwkCrv && jwk.crv !== spec.jwkCrv) {
+    reject(`JWKS curve "${jwk.crv}" does not match algorithm "${algName}" (expects ${spec.jwkCrv})`);
+  }
+  if (jwk.use !== undefined && jwk.use !== 'sig') {
+    reject(`JWKS entry declares use "${jwk.use}"; only "sig" keys may verify signatures`);
+  }
+  if (jwk.key_ops !== undefined) {
+    if (!Array.isArray(jwk.key_ops) || !jwk.key_ops.includes('verify')) {
+      reject('JWKS entry key_ops does not permit "verify"');
+    }
+  }
+  if (typeof jwk.alg === 'string') {
+    // Compare CANONICAL algorithms, not raw spellings: `Ed25519` and `EdDSA`
+    // are the same algorithm, as are `RS256` and `rsa-v1_5-sha256`.
+    const pinned = ALGORITHMS[jwk.alg.toLowerCase()];
+    if (!pinned) {
+      reject(`JWKS entry is pinned to unrecognized alg "${jwk.alg}"`);
+    }
+    if (pinned.canonical !== spec.canonical) {
+      reject(`JWKS entry is pinned to alg "${jwk.alg}" but the signature declares "${algName}"`);
+    }
+  }
+
+  let key;
+  try {
+    key = crypto.createPublicKey({ key: jwk, format: 'jwk' });
+  } catch (err) {
+    reject(`JWKS entry could not be imported: ${err.message}`);
+  }
+  if (key.type !== 'public') reject('JWKS entry did not import as a public key');
+
+  const details = key.asymmetricKeyDetails || {};
+  if (spec.kty === 'RSA') {
+    const bits = Number(details.modulusLength || 0);
+    if (!(bits >= MIN_RSA_MODULUS_BITS)) {
+      reject(`RSA key is ${bits || 'an unknown number of'} bits; the minimum is ${MIN_RSA_MODULUS_BITS}`);
+    }
+  }
+  if (spec.curve && details.namedCurve !== spec.curve) {
+    reject(`resolved EC key uses curve "${details.namedCurve}" but algorithm "${algName}" requires "${spec.curve}"`);
+  }
+  if (spec.kty === 'OKP' && key.asymmetricKeyType !== 'ed25519') {
+    reject(`resolved key type "${key.asymmetricKeyType}" is not ed25519`);
+  }
+  return key;
+}
+
+/**
+ * Validates a JWKS document shape and finds the entry for a key id.
+ *
+ * @param {unknown} jwks
+ * @param {string} keyid
+ * @returns {Record<string, unknown>|null}
+ */
+function selectJwk(jwks, keyid) {
+  if (!jwks || typeof jwks !== 'object' || !Array.isArray(jwks.keys)) {
+    reject('configured JWKS is invalid: expected an object with a "keys" array', {
+      status: 503,
+      code: 'jwks_invalid',
+    });
+  }
+  if (jwks.keys.length > JWKS_MAX_KEYS) {
+    reject(`configured JWKS declares ${jwks.keys.length} keys; the maximum is ${JWKS_MAX_KEYS}`, {
+      status: 503,
+      code: 'jwks_invalid',
+    });
+  }
+  const matches = jwks.keys.filter((candidate) => candidate && candidate.kid === keyid);
+  if (matches.length > 1) {
+    // Two keys with one kid means "which key verified this?" has no answer.
+    reject(`configured JWKS contains ${matches.length} keys with kid "${keyid}"`, {
+      status: 503,
+      code: 'jwks_ambiguous',
+    });
+  }
+  return matches[0] || null;
+}
+
+/**
+ * Fetches a JWKS over HTTPS with SSRF, redirect, timeout and size limits.
+ *
+ * @param {string} url
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<unknown>}
+ */
+async function fetchJwks(url, fetchImpl) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    reject('configured agentJwksUrl is not a valid URL', { status: 503, code: 'jwks_misconfigured' });
+  }
+  if (parsed.protocol !== 'https:') {
+    reject('configured agentJwksUrl must use HTTPS', { status: 503, code: 'jwks_misconfigured' });
+  }
+  if (parsed.username || parsed.password) {
+    reject('configured agentJwksUrl must not embed credentials', { status: 503, code: 'jwks_misconfigured' });
+  }
+  await assertPublicHostname(parsed.hostname);
+
+  let response;
+  try {
+    response = await fetchImpl(parsed.href, {
+      redirect: 'error',
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(JWKS_FETCH_TIMEOUT_MS),
+    });
+  } catch (err) {
+    reject(`JWKS fetch failed: ${err.message}`, { status: 503, code: 'jwks_unreachable' });
+  }
+  if (!response.ok) {
+    reject(`JWKS request failed with HTTP ${response.status}`, { status: 503, code: 'jwks_unreachable' });
+  }
+  const declared = Number(response.headers?.get?.('content-length') || 0);
+  if (declared > JWKS_MAX_BYTES) {
+    reject('JWKS response is too large', { status: 503, code: 'jwks_invalid' });
+  }
+  const text = await response.text();
+  if (text.length > JWKS_MAX_BYTES) {
+    reject('JWKS response is too large', { status: 503, code: 'jwks_invalid' });
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    reject('JWKS response is not valid JSON', { status: 503, code: 'jwks_invalid' });
+  }
+}
+
+/**
+ * Resolves the public key for a key id, with caching.
+ *
+ * @returns {Promise<crypto.KeyObject>}
+ */
+async function resolveKey({ keyid, algName, jwks, jwksUrl, jwksCache, namespace, fetchImpl }) {
+  if (!jwks && !jwksUrl) {
+    reject('RFC 9421 verification is not configured', {
+      status: 503,
+      code: 'jwks_unconfigured',
+      publicMessage:
+        'RFC 9421 verification is not configured for this store. '
+        + 'Set config.agentJwks or config.agentJwksUrl to your agent population\'s JWKS.',
+    });
+  }
+
+  // The cache key identifies the KEY SET BY CONTENT, not merely as "inline".
+  //
+  // This matters now that the replay namespace is derived from the store's
+  // baseUrl rather than a random per-instance UUID: two middleware instances
+  // for the same store but with DIFFERENT inline JWKS would otherwise share the
+  // cache entry, and instance B would happily verify against instance A's key.
+  // Fingerprinting the document keeps distinct key sets distinct while still
+  // letting identical configuration share cache across instances.
+  const source = jwks
+    ? `inline:${crypto.createHash('sha256').update(JSON.stringify(jwks.keys ?? jwks)).digest('base64url').slice(0, 22)}`
+    : `url:${jwksUrl}`;
+  // The algorithm is part of the cache key too: the same kid verified under a
+  // different alg is a different (rejected) policy decision, and caching only
+  // by kid would let one accepted alg poison another.
+  const cacheKey = `${namespace}\u0000${source}\u0000${keyid}\u0000${algName}`;
+
+  const cached = jwksCache.get(cacheKey);
+  if (cached?.key) return cached.key;
+  if (cached?.negative) reject(cached.detail || 'configured JWKS does not contain the requested key id');
+
+  const document = jwks || (await fetchJwks(jwksUrl, fetchImpl));
+  const jwk = selectJwk(document, keyid);
+  if (!jwk) {
+    const detail = 'configured JWKS does not contain the requested key id';
+    jwksCache.put(cacheKey, { negative: true, detail, expires: Date.now() + JWKS_NEGATIVE_TTL_MS });
+    reject(detail);
+  }
+
+  let key;
+  try {
+    key = importVerificationKey(jwk, algName);
+  } catch (err) {
+    // Cache the rejection: a policy mismatch is stable for this kid+alg, and
+    // re-deriving it on every request is free amplification.
+    const detail = err instanceof VerificationFailure ? err.detail : err.message;
+    jwksCache.put(cacheKey, { negative: true, detail, expires: Date.now() + JWKS_NEGATIVE_TTL_MS });
+    throw err;
+  }
+  jwksCache.put(cacheKey, { key, expires: Date.now() + JWKS_POSITIVE_TTL_MS });
+  return key;
+}
+
+// ---------------------------------------------------------------------------
+// Signature verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifies a signature over one candidate base.
+ *
+ * @param {string} algName
+ * @param {crypto.KeyObject} key
+ * @param {Buffer} signature
+ * @param {string} base
+ * @returns {boolean}
+ */
+function verifyOverBase(algName, key, signature, base) {
+  const spec = ALGORITHMS[algName];
+  const data = Buffer.from(base, 'utf8');
+
+  if (spec.kty === 'OKP') {
+    // Ed25519 signs the message directly and is always 64 bytes.
+    if (signature.length !== 64) return false;
+    return crypto.verify(null, data, key, signature);
+  }
+
+  if (spec.kty === 'EC') {
+    // RFC 9421 / JOSE / WebCrypto all use raw r||s. Node defaults to DER,
+    // which is why every real ECDSA signature failed before this line.
+    const expectedLength = { prime256v1: 64, secp384r1: 96, secp521r1: 132 }[spec.curve];
+    if (signature.length !== expectedLength) return false;
+    return crypto.verify(spec.hash, data, { key, dsaEncoding: 'ieee-p1363' }, signature);
+  }
+
+  const keyInput = spec.rsaPadding === 'pss'
+    ? {
+      key,
+      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+      saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST,
+    }
+    : { key, padding: crypto.constants.RSA_PKCS1_PADDING };
+  return crypto.verify(spec.hash, data, keyInput, signature);
+}
+
+/**
+ * Extracts and validates the signature parameters from a parsed
+ * `Signature-Input` dictionary member.
+ */
+function readSignatureParams(member) {
+  const params = member.params;
+  const created = params.get('created');
+  const expires = params.get('expires');
+  const nonce = params.get('nonce');
+  const alg = params.get('alg');
+  const keyid = params.get('keyid');
+
+  if (!Number.isSafeInteger(created)) reject('signature parameter "created" must be an integer');
+  if (!Number.isSafeInteger(expires)) reject('signature parameter "expires" must be an integer');
+  if (typeof nonce !== 'string') reject('signature parameter "nonce" must be a string');
+  if (typeof alg !== 'string') reject('signature parameter "alg" must be a string');
+  if (typeof keyid !== 'string') reject('signature parameter "keyid" must be a string');
+
+  for (const name of params.keys()) {
+    if (!['created', 'expires', 'nonce', 'alg', 'keyid', 'tag'].includes(name)) {
+      reject(`unknown signature parameter "${name}"`);
+    }
+  }
+  return { created, expires, nonce, alg, keyid };
+}
+
+/**
+ * Verifies an RFC 9421 signed request.
+ *
+ * @param {object} options
+ * @param {object} options.req - the Express request (for body bytes)
+ * @param {import('./signature-base.js').SignatureRequestContext} options.requestContext
+ * @param {string} options.signatureHeader
+ * @param {string} options.signatureInputHeader
+ * @param {object|null} options.jwks
+ * @param {string|null} options.jwksUrl
+ * @param {ReturnType<typeof createJwksCache>} options.jwksCache
+ * @param {{ claim: (key: string, expiresAtMs: number) => boolean|Promise<boolean> }} options.nonceCache
+ * @param {string} options.nonceNamespace
+ * @param {number} options.maxAgeMs
+ * @param {number} options.clockSkewMs
+ * @param {boolean} [options.requireAuthority=true]
+ * @param {Set<string>|null} [options.expectedAuthorities] - normalized
+ *   authorities this deployment legitimately answers for. When provided, a
+ *   request whose Host is not one of them is refused, which is what makes
+ *   `@authority` an actual cross-host replay defence rather than a
+ *   self-consistent echo of a spoofable header.
+ * @param {boolean} [options.acceptLegacyProfile=false]
+ * @param {boolean} [options.allowReserializedBody=false]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {number} [options.nowMs]
+ * @returns {Promise<{ ok: true, keyid: string, identity: string, profile: string }
+ *   | { ok: false, status: number, code: string, publicMessage: string, detail: string }>}
+ */
+export async function verifyHttpMessageSignature(options) {
+  const {
+    req,
+    requestContext,
+    signatureHeader,
+    signatureInputHeader,
+    jwks = null,
+    jwksUrl = null,
+    jwksCache,
+    nonceCache,
+    nonceNamespace,
+    maxAgeMs,
+    clockSkewMs,
+    requireAuthority = true,
+    expectedAuthorities = null,
+    acceptLegacyProfile = false,
+    allowReserializedBody = false,
+    fetchImpl = fetch,
+    nowMs = Date.now(),
+  } = options;
+
+  try {
+    // --- 0. Is a trust root configured at all? -----------------------------
+    // A pure configuration check with no cost, hoisted to the front so the
+    // merchant sees "configure your JWKS" rather than some downstream symptom
+    // of the same missing configuration.
+    if (!jwks && !jwksUrl) {
+      reject('RFC 9421 verification is not configured', {
+        status: 503,
+        code: 'jwks_unconfigured',
+        publicMessage:
+          'RFC 9421 verification is not configured: set config.agentJwks or config.agentJwksUrl '
+          + 'to your agent population\'s JWKS.',
+      });
+    }
+
+    // --- 1. Parse both headers as structured fields -------------------------
+    let inputDict;
+    let signatureDict;
+    try {
+      inputDict = parseDictionary(signatureInputHeader);
+      signatureDict = parseDictionary(signatureHeader);
+    } catch (err) {
+      if (err instanceof StructuredFieldError) {
+        reject(`Signature/Signature-Input is not a valid structured field: ${err.message}`);
+      }
+      throw err;
+    }
+
+    // Structural and protocol-capability errors below carry an ACTIONABLE
+    // public message: they describe this store's published protocol surface,
+    // not its secrets, and a legitimate agent needs them to correct itself.
+    // Key-resolution and crypto failures stay generic (see the defaults on
+    // `reject`), because those would form a verification-state oracle.
+    if (inputDict.size !== 1) {
+      reject(`Signature-Input carries ${inputDict.size} labels; exactly one is supported`, {
+        code: 'multi_label',
+        publicMessage: 'Multi-label HTTP Message Signatures are not supported; send exactly one signature label.',
+      });
+    }
+    if (signatureDict.size !== 1) {
+      reject(`Signature carries ${signatureDict.size} labels; exactly one is supported`, {
+        code: 'multi_label',
+        publicMessage: 'Multi-label HTTP Message Signatures are not supported; send exactly one signature label.',
+      });
+    }
+    const [label, inputMember] = [...inputDict.entries()][0];
+    const [signatureLabel, signatureMember] = [...signatureDict.entries()][0];
+    if (label !== signatureLabel) {
+      reject(`Signature label "${signatureLabel}" does not match Signature-Input label "${label}"`, {
+        code: 'label_mismatch',
+        publicMessage: 'Signature and Signature-Input labels do not match.',
+      });
+    }
+    if (!inputMember.isInnerList) {
+      reject('Signature-Input value must be an inner list of covered components', {
+        code: 'malformed_signature_input',
+        publicMessage: 'Signature-Input must be a structured-field inner list of covered components.',
+      });
+    }
+    if (!(signatureMember.value instanceof ByteSequence)) {
+      reject('Signature value must be a byte sequence', {
+        code: 'malformed_signature',
+        publicMessage: 'Signature must be a structured-field byte sequence (sig1=:base64:).',
+      });
+    }
+    const signatureBytes = signatureMember.value.bytes;
+    if (signatureBytes.length === 0 || signatureBytes.length > 1024) {
+      reject(`signature is ${signatureBytes.length} bytes, which is outside the accepted range`);
+    }
+
+    // --- 2. Covered components --------------------------------------------
+    const components = inputMember.items.map((item) => {
+      if (typeof item.value !== 'string') {
+        reject('every covered component identifier must be a string');
+      }
+      return { name: item.value, params: item.params };
+    });
+    const componentNames = new Set(components.map((component) => component.name));
+
+    // --- 3. Signature parameters ------------------------------------------
+    const { created, expires, nonce, alg, keyid } = readSignatureParams(inputMember);
+    const algName = alg.toLowerCase();
+    if (!ALGORITHMS[algName]) {
+      reject(`unsupported signature algorithm "${alg}"`, {
+        code: 'alg_unsupported',
+        // The accepted algorithm set is already published in
+        // /ap2/capabilities and /openapi.json, so naming it is not disclosure.
+        publicMessage: `Unsupported signature algorithm. This store accepts: ${SUPPORTED_SIGNATURE_ALGORITHMS.join(', ')}.`,
+      });
+    }
+    if (!KEYID_PATTERN.test(keyid)) {
+      reject('keyid must be 1-256 printable ASCII characters', { code: 'keyid_invalid' });
+    }
+    if (/^https?:\/\//i.test(keyid)) {
+      reject('remote keyid URLs are not accepted; configure a trusted JWKS and use its exact key id', {
+        code: 'keyid_remote',
+        publicMessage: 'Remote keyid URLs are not accepted; use a key id from this store\'s configured JWKS.',
+      });
+    }
+    if (!NONCE_PATTERN.test(nonce)) {
+      reject('nonce must be 16-256 printable ASCII characters', {
+        code: 'nonce_invalid',
+        publicMessage: 'The signature nonce must be 16-256 printable ASCII characters.',
+      });
+    }
+
+    // --- 4. Freshness ------------------------------------------------------
+    // Freshness failures are disclosed: an agent with a skewed clock or a
+    // stale signature must be able to tell that apart from a bad key, and the
+    // window is a published policy rather than a secret.
+    const createdMs = created * 1000;
+    const expiresMs = expires * 1000;
+    const staleness = { code: 'signature_stale', publicMessage: 'HTTP Message Signature is expired or outside the allowed lifetime.' };
+    if (expires <= created) reject('"expires" must be after "created"', staleness);
+    if (createdMs > nowMs + clockSkewMs) reject('signature was created in the future', staleness);
+    if (createdMs < nowMs - maxAgeMs) reject('signature is older than the accepted window', staleness);
+    if (expiresMs < nowMs - clockSkewMs) reject('signature has expired', staleness);
+    if (expiresMs - createdMs > maxAgeMs) reject('signature lifetime exceeds the accepted maximum', staleness);
+
+    // --- 5. Body digest ----------------------------------------------------
+    // Any request with a body MUST cover content-digest; without it the
+    // signature says nothing about the payload being acted on.
+    let bodyBytes;
+    try {
+      bodyBytes = resolveBodyBytes(req, { allowReserializedBody });
+    } catch (err) {
+      reject(err.message, {
+        status: 503,
+        code: 'raw_body_unavailable',
+        publicMessage: 'This store cannot verify signed request bodies. Contact the store operator.',
+      });
+    }
+    if (bodyBytes.length > 0 && !componentNames.has('content-digest')) {
+      reject('signatures over a request with a body must cover content-digest', {
+        code: 'digest_not_covered',
+        publicMessage: 'Signatures over a request with a body must cover content-digest.',
+      });
+    }
+    if (componentNames.has('content-digest')) {
+      const digestResult = verifyContentDigest(requestContext.header('content-digest'), bodyBytes);
+      // Disclosed: the caller computed this digest itself, so telling it the
+      // digest did not match the received body reveals nothing it did not
+      // already know, and it is the single most useful debugging signal.
+      if (!digestResult.ok) {
+        reject(digestResult.reason, {
+          code: 'digest_mismatch',
+          publicMessage: 'The content-digest header does not match the received request body.',
+        });
+      }
+    }
+
+    // --- 6. Required components -------------------------------------------
+    // Strict mode binds the authority, which is what prevents a signature
+    // captured at store A from being replayed against store B.
+    const strictRequired = requireAuthority
+      ? STRICT_REQUIRED_COMPONENTS
+      : STRICT_REQUIRED_COMPONENTS.filter((name) => name !== '@authority');
+    const strictSatisfied = strictRequired.every((name) => componentNames.has(name));
+    const legacySatisfied = LEGACY_REQUIRED_COMPONENTS.every((name) => componentNames.has(name));
+
+    if (!strictSatisfied) {
+      if (!acceptLegacyProfile || !legacySatisfied) {
+        const missing = strictRequired.filter((name) => !componentNames.has(name));
+        reject(`signature must cover ${missing.join(', ')}`, {
+          publicMessage: `HTTP Message Signatures for this store must cover ${strictRequired.join(', ')} and content-digest.`,
+        });
+      }
+    }
+
+    // Covering @authority only binds the host if we also know which hosts are
+    // ours. Otherwise an attacker replaying a signature captured at store A
+    // simply sends `Host: store-a.com`, and the base reconstructs identically.
+    if (expectedAuthorities instanceof Set && expectedAuthorities.size > 0) {
+      const presented = normalizeAuthority(requestContext.authority, requestContext.scheme);
+      if (!expectedAuthorities.has(presented)) {
+        reject(
+          `request authority "${presented || '(absent)'}" is not one this deployment answers for`,
+          {
+            code: 'authority_rejected',
+            publicMessage: 'The request Host header is not served by this store.',
+          },
+        );
+      }
+    }
+
+    // --- 7. Key resolution -------------------------------------------------
+    const key = await resolveKey({
+      keyid,
+      algName,
+      jwks,
+      jwksUrl,
+      jwksCache,
+      namespace: nonceNamespace,
+      fetchImpl,
+    });
+
+    // --- 8. Canonicalize and verify ---------------------------------------
+    // Strict first. The legacy profile is only attempted when the merchant
+    // opted in, and only after the conformant base failed, so enabling it
+    // never weakens a signature that already verifies strictly.
+    const profilesToTry = [PROFILE_STRICT];
+    if (acceptLegacyProfile) profilesToTry.push(PROFILE_LEGACY);
+
+    let matchedProfile = null;
+    let lastBaseError = null;
+    for (const profile of profilesToTry) {
+      if (profile === PROFILE_STRICT && !strictSatisfied) continue;
+      if (profile === PROFILE_LEGACY && !legacySatisfied) continue;
+      let base;
+      try {
+        base = buildSignatureBase({
+          components,
+          signatureParamsRaw: inputMember.raw,
+          request: requestContext,
+          profile,
+        });
+      } catch (err) {
+        if (err instanceof SignatureBaseError) {
+          lastBaseError = err;
+          continue;
+        }
+        throw err;
+      }
+      if (verifyOverBase(algName, key, signatureBytes, base)) {
+        matchedProfile = profile;
+        break;
+      }
+    }
+
+    if (!matchedProfile) {
+      if (lastBaseError) reject(`signature base could not be built: ${lastBaseError.message}`);
+      reject(`signature did not verify for keyid "${keyid}" (alg ${algName})`);
+    }
+
+    // --- 9. Single-use nonce ----------------------------------------------
+    // The record must survive at least as long as this signature could still
+    // be accepted, otherwise a near-expired signature records a nonce for a
+    // second and then replays inside the remaining skew window.
+    const replayKey = `${nonceNamespace}:rfc:${keyid}:${nonce}`;
+    const retainUntilMs = Math.max(expiresMs, nowMs + maxAgeMs + clockSkewMs);
+    const claimed = await nonceCache.claim(replayKey, retainUntilMs);
+    if (!claimed) {
+      reject(`nonce "${nonce}" has already been used for keyid "${keyid}"`, {
+        code: 'nonce_reused',
+        publicMessage: 'HTTP Message Signature nonce has already been used.',
+      });
+    }
+
+    return { ok: true, keyid, identity: `rfc:${keyid}`, profile: matchedProfile };
+  } catch (err) {
+    if (err instanceof VerificationFailure) {
+      return {
+        ok: false,
+        status: err.status,
+        code: err.code,
+        publicMessage: err.publicMessage,
+        detail: err.detail,
+      };
+    }
+    // Never let an unexpected internal error be interpreted as success, and
+    // never leak its text to the caller.
+    return {
+      ok: false,
+      status: 403,
+      code: 'invalid_signature',
+      publicMessage: 'Invalid HTTP Message Signature.',
+      detail: `unexpected verification error: ${err?.message || err}`,
+    };
+  }
+}