@request-seal/core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## Unreleased
 
+## 0.4.0 - October 17, 2026
+- Upgrade notes for callers: the new telemetry surface is entirely opt-in — no code changes unless you attach a subscriber; `Telemetry.attach` accepts at most sixteen subscribers and every event is a frozen six-field object whose `reason` values are the same parity rule ids the errors carry.
+- Add the versioned telemetry contract v1, mirroring RequestSeal for Elixir's `:telemetry` surface with zero dependencies: `Telemetry.attach(subscriber)` returns a caller-owned handle whose `detach` stops delivery, and five events carry bounded, low-cardinality payloads — `verify`, `verifyQuorum`, and `webBotAuthVerify` report `ok` or `error` with the parity rule id, layer, and bounded detail exactly as the caller receives them; `replayClaim` reports `claimed`, `already_claimed`, or `error`; `custodySign` reports `ok` or `error` with the custody reason. `durationMs` is monotonic milliseconds over the emitting call. No signature label, key ID, URL, principal, nonce, bytes, or exception message ever enters an event; internal faults (`core/internal.internal`) are countable through the closed reason vocabulary. A throwing subscriber degrades silently and never fails the operation it observes; attachment is bounded to sixteen concurrent subscribers. The event names, outcomes, and fields are additive-only within minor versions.
+
+
+Upgrade notes for callers: the discovery `Resolution.assertedAlgorithm` is now the normalized JOSE name (`JwsAlgorithm | null`) and an asserted key's `Resolution.algorithm` is the `{jws}` selector, so code matching the raw HTTP token string must compare JOSE names; a cache `fetch` callback may now receive a `validators` option and return a `NotModified` outcome (a callback that ignores both still works); `CoreError.retryable` is `boolean` and `discovery/resolution_failed` is retryable; a first `103` no longer fails a discovery fetch.
+- Re-run the reciprocal exchange against the published RequestSeal for Elixir 0.5.2: both interop peers pin Hex `request_seal == 0.5.2` with the release checksum, the CI reference clone tracks the v0.5.2 tag, and the executed exchange agrees with zero disagreements in every family and both directions (receipt under the project's check records).
+- Move the seven architecture decision records from `docs/adr/` into the maintainer's private record store and state each accepted decision in place in the threat model, mirroring the Elixir repository's relocation; public documents no longer reference the records and no library behavior changed.
+- Add `ddlIndex(table)` to `@request-seal/core/replay-postgres`, the retention-sweep index DDL mirroring the reference `ddl_index/1`: without it the periodic `DELETE ... WHERE retain_until <= now` scans the whole growing table; the table name is additionally bounded to 46 characters so the derived index identifier fits PostgreSQL's 63-byte limit.
+- Make `verify`, `verifyQuorum`, Web Bot Auth `verify`, and `sign` total at their entry points: an unexpected internal fault returns the new bounded `core/internal.internal` with the exception class (`TypeError`, `Error`, `throw`) as `detail` instead of escaping or masking as `invalid_options`/`invalid_policy`/`invalid_quorum`. Caller callbacks keep their deliberate classifications (a throwing key resolver stays `key_resolver_failed`, a failing signer `signer_failed`, a throwing extension pipeline step `invalid_policy`), and a defective label inside `verifyQuorum` becomes that label's nonqualifying internal fact rather than failing the whole call.
+- Bound the quorum assignment search by the caller's wall clock: a `Context` deadline that expires mid-search now preserves a satisfying best-so-far assignment and, when nothing satisfies, returns the new retryable `core/quorum.deadline` (the first retryable core reason; `CoreError.retryable` widens to `boolean`) instead of a custody error. Node exhaustion and deadline exhaustion share one rejection gate.
+- Split DNS resolution failures (RFC-level taxonomy from the reference): an authoritative NXDOMAIN on every query returns the new nonretryable `discovery/domain_not_found`, while any other resolution trouble returns `discovery/resolution_failed`, which is now retryable as the reference marks it.
+- Skip interim 1xx responses (RFC 9110 Section 15.2): up to four informational responses preceding the final status are skipped instead of rejecting the fetch with `unexpected_status`; a fifth interim or a 101 protocol switch still rejects.
+- Check a CIMD document's nested `jwks_uri` against the origin that served the document rather than the configured origin, so a permissive `redirectScope: "any_https"` with a cross-origin redirect to a mirror resolves the mirror's key set instead of failing `redirect_denied`.
+- Revalidate conditionally (RFC 9111 Section 4.3.4): a fetched key set carries the publisher's `ETag` (at most 512 bytes), `Discovery.fetchWithValidators(source, etag, storedLifetime, options)` sends `If-None-Match` and returns a `NotModified` outcome on 304 — the stored lifetime persists when the 304 carries no freshness directives, a 304 naming a different validator rejects `invalid_response`, and a validator never crosses a redirect. A cache wired with the conditional fetcher sends its stored validator when every stored key is still alive (a dead key forces a full fetch) and never for a CIMD source; `DiscoveryFetch` gains the `validators` option and the `NotModified` result — a breaking type change for 0.3.0.
+- Narrow the nested-JOSE inner `cty` rule to JOSE media types (RFC 7515 Sections 4.1.10 and 9.2.1): an inner JWS `cty` of `application/jose`, `application/jose+json`, `application/jws`, `application/jwe`, or `application/jwt` — case-insensitively, with parameters stripped before the abbreviation rule, so `JWT`, `jose`, and `JWT;x="a/b"` all classify — rejects `nesting_depth`, while any other inner `cty` such as `application/json` names ordinary typed payload content and verifies.
+- Re-pin the shared error vocabulary to RequestSeal for Elixir v0.5.2 (release commit `53b6690`): the extractor now reads 0.5.2's option-style retryable spellings, and the three new reasons arrive with the pin.
+- Accept both registry spellings of a JWK `alg` assertion and normalize once at import to the JOSE name, as RequestSeal for Elixir 0.5.2 already did. An RFC 7517 set that asserts `RS256` or `EdDSA` now resolves through either allowlist spelling — the HTTP identifier (`rsa-v1_5-sha256`) or the `{jws}` selector — and PS256 and PS384, which exist only as JOSE names, select by selector. A key whose `alg` names an algorithm this verifier never uses (an encryption key such as `RSA-OAEP`, or a name outside both registries) or a well-formed key of an unsupported `kty`/curve (RFC 7517 Section 5) is skipped while the rest of the set still resolves; an import failure classified `invalid_key` (an unknown `kty`, an unsupported curve, an oversized component) skips the same way, and an all-skipped set resolves empty with lookups failing closed. Leaked private members (`d`, `p`, `q`, `dp`, `dq`, `qi`, `oth`, `k`) still reject the whole set loudly before any skip decision, a malformed non-string `alg` still rejects, and `maxKeys` still counts every listed key. `Resolution.assertedAlgorithm` now carries the normalized JOSE name instead of the raw HTTP token, and an asserted key's `Resolution.algorithm` is the `{jws}` selector — breaking type changes for 0.3.0.
+- Zero discovery snapshot freshness when `no-store` or `no-cache` arrives qualified, as in `no-cache="content-type"` (RFC 9111 Sections 5.2.2.3 and 5.2.2.4, including the RFC 7234 quoted form whose member can itself contain commas). The zero-freshness check compared whole comma-split elements, so a qualified directive did not zero the lifetime and its keys cached up to the 86,400 s default `maxTtl`. The directive name before any `=` now decides, as RequestSeal for Elixir 0.5.2 already did.
+- Re-vendor the shared conformance corpus to RequestSeal for Elixir v0.5.2 and update the pin. The v0.5.2 corpus carries the same 294 byte-identical files as v0.4.0; the pin and index now record the new tag, release commit, and index digest.
+- Test on Node 22.23.1 in CI, beside 22.12.0, 24.21.0, and 26.11.1 (Linux only).
+- Match IP-literal discovery hosts against the certificate's IP addresses with OpenSSL (`X509Certificate.checkIP`). On Node 22.23.1, `tls.checkServerIdentity` normalizes the host with `domainToASCII` before its IP test, which turns `::1` into an empty string, so every `https://[IPv6]` source failed with `discovery/tls_failed`. DNS hosts still use `tls.checkServerIdentity`.
+- Report a missing or empty OS trust store as `discovery/transport_unavailable` instead of custody `unsupported_format` when `@request-seal/core/discovery-node` creates or fetches a `cacerts: "os"` source. Node before 22.15.0, including 22.12.0, and Deno 2.5.6 have no `tls.getCACertificates`; the refusal stays (bundled roots are never a fallback) but now has a discovery kind, the same as a denied store. Callers matching the old custody reason must update.
+- Add an optional `clock` to `Discovery.resolver`, so a key's freshness is checked on the same clock as the policy. With a cache, the clock decides only the returned key's freshness; the cache keeps fetching, storing, and expiring its entries on its own clock. A clock that throws or returns an invalid time gives `invalid_options`. Without it the key set bridge keeps system time, which disagreed with a policy running on a fixed or offset clock.
+- Give each request captured by `capture(server)` its own deadline: the new `timeoutMs` option (1 to 300,000 ms, default 5,000) applies per request, and `context` is now refused with `adapter/invalid_options`. A Context passed to `capture(server)` was one absolute deadline shared by every later request, so once it passed, every capture on that server failed with `custody/deadline_exceeded`.
+- Bound exact-input function signers by `signingTimeout` when no `context` is passed, as generated specs already did; the option was accepted and ignored, and such signers always ran under a fixed 5,000 ms deadline. A function that outlasts its `signingTimeout` now returns `signer_failed`.
+- Generate `Content-Digest` in `Message.request` and `Message.response` with the `crypto.subtle.digest` captured at load, as every other cryptographic operation already did; code that replaces the global after RequestSeal loads can no longer change a generated digest.
+- Declare a WebKit 27.2 limitation on Linux x64: the engine rejects PKCS8 import of an Ed25519 private key whose seed begins with `0x00`, so `Custody.local` returns `custody/invalid_key` for that form; pass such keys as JWK. The browser suite executes it with a fixed seed and uses published RFC 8032 keys instead of generating Ed25519 keys, which this engine intermittently fails to do. Correct the runtime matrix: Node 22.12.0 and Deno 2.5.6 refuse `cacerts: "os"`, Fetch verification is refused on every runtime except Deno 2.5.6 (including Node 22.12.0 and Bun 1.3.14), and WebKit verifies empty-message Ed25519 signatures on Linux.
+- Document supported versions and how to verify release provenance with `npm audit signatures` in SECURITY.md.
+- Documentation pass, with no library behavior change: correct option lists, defaults, limits, and error reasons across the guides and references against the source; add a key rotation guide and a glossary; replace the extension-profile sketch with an executed program and add an executed AES key-wrapping JOSE example; describe parameters, results, and errors in the API reference for `sign`, `verify`, and `Policy.create`; vary example domains; add npm keywords.
+
+### Migrating from 0.2.x
+- `capture(server, { context })` now returns `adapter/invalid_options`. Replace `context` with `timeoutMs` (1 to 300,000 ms, default 5,000), which gives each request its own deadline. Pass a `context` per call to `captureRequest` instead if you need one.
+- A function signer used with an exact-input spec (`signatureInput`) and no `context` now runs under `signingTimeout` (default 5,000 ms). A signer slower than its `signingTimeout` now fails with `signer_failed`; raise `signingTimeout` or pass a `context` with the deadline you want.
+- `@request-seal/core/discovery-node` now reports a missing or empty OS trust store as `discovery/transport_unavailable`. Code that matched custody `unsupported_format` for `cacerts: "os"` should match `discovery/transport_unavailable`, or supply DER roots in `cacerts`.
+
 ## 0.2.0 - October 11, 2026
 - Rewrite the README and add eleven usage guides, architecture decisions, and threat-model documentation. Every complete TypeScript example runs in CI; README verification excerpts are checked against the programs they come from. Generate the API reference with TypeDoc and publish it to GitHub Pages at https://baselabs.github.io/request-seal-typescript/. The migration guide compares behavior with `http-message-signatures` 1.0.6 using executed examples.
 - Verify interoperability with RequestSeal for Elixir 0.4.1 for every HTTP and JWS algorithm, all JWE alg/enc pairs, nested JWS-in-JWE, signed TLS Web Bot Auth directories, and shared PostgreSQL replay claims.
@@ -21,7 +57,7 @@
 - Rename the npm package from `request-seal` to `@request-seal/core` under the `request-seal` organization; use `@request-seal/core/<subpath>` for every subpath import.
 - Add captured Node HTTP Web Bot Auth verification, shared attempt storage, and executable signed TLS directory examples.
 - Reject concurrent capture consumers and retained length mismatches; derive HTTP/2 scheme from TLS and reject conflicting Host/authority.
-- Add captured-request quorum verification with shared replay and single-verification guards.
+- Add captured-request quorum verification with single-verification guards. Quorum verification refuses a required replay policy with `invalid_policy`; one replay claim belongs only after the complete quorum verifies.
 - Apply redirect method/body rules, validate redirect policy before delivery, remove Location fragments, and report actual client attempts.
 - Measure Fetch runtime overrides and eligibility in the wire lane; refuse Node sec-fetch-mode signing, empty-query targets on Node majors below 24, and planted runtime markers.
 - Deliver response signatures with their exact buffered bytes, use one clock for Date and created, and omit prohibited lengths.

package/README.md

@@ -1,4 +1,4 @@
-**Status:** maintained · **Kind:** overview · **Updated:** October 11, 2026 · **Governed by:** RFC 9421, RFC 9530, the Web Bot Auth protocol draft, and the executed examples in this file · **Review when:** package scope, installation, or the public API changes
+**Status:** maintained · **Kind:** overview · **Updated:** October 14, 2026 · **Governed by:** RFC 9421, RFC 9530, the Web Bot Auth protocol draft, and the executed examples in this file · **Review when:** package scope, installation, or the public API changes
 
 # RequestSeal
 
@@ -27,7 +27,7 @@ const key = await Custody.local("hmac-sha256", { hmac: crypto.getRandomValues(ne
 const server = createServer((req, res) => res.end(String(req.headers["signature-input"]))).listen(0, "127.0.0.1");
 await new Promise((ready) => server.once("listening", ready));
 const spec = { label: "sig", components: '("@method" "@authority" "@path")', algorithm: "hmac-sha256", expiresIn: 60 };
-const sent = await signedFetch(`http://127.0.0.1:${(server.address() as { port: number }).port}/orders`, { method: "GET" }, { spec, signer: key.ok ? key.value : assert.fail() });
+const sent = await signedFetch(`http://127.0.0.1:${(server.address() as { port: number }).port}/reports`, { method: "GET" }, { spec, signer: key.ok ? key.value : assert.fail() });
 assert.ok(sent.ok && (await sent.value.response.text()).startsWith('sig=("@method" "@authority" "@path")')); server.close();
 ```
 
@@ -44,7 +44,7 @@ const must = <T>(r: Result<T>): T => { assert.ok(r.ok); return (r as { value: T
 const key = must(await Custody.local("hmac-sha256", { hmac: crypto.getRandomValues(new Uint8Array(32)) }));
 const components = '("@method" "@authority" "@path")';
 const policy = must(Policy.create({ algorithms: ["hmac-sha256"], components, keyResolver: () => ok({ algorithm: "hmac-sha256", key }), freshness: { clock: () => Math.floor(Date.now() / 1000), maxAge: 60, skew: 5, requireExpires: true }, content: "not_required", replay: "not_required" }));
-const signed = must(await sign(must(await Message.request("GET", "https://api.example/orders", [], "")), { label: "sig", components, algorithm: "hmac-sha256", expiresIn: 60 }, key));
+const signed = must(await sign(must(await Message.request("GET", "https://api.example/documents", [], "")), { label: "sig", components, algorithm: "hmac-sha256", expiresIn: 60 }, key));
 must(await verify(signed, policy, { label: "sig" }));
 const altered = must(Message.create({ ...signed, method: "DELETE" }));
 const rejected = await verify(altered, policy, { label: "sig" });
@@ -231,7 +231,7 @@ await server.shutdown();
 
 ## Policy recipes
 
-A verifier states six choices: algorithms, required components, a key resolver, freshness, content checking, and replay. Nothing is defaulted. Copy the recipe closest to your case.
+A verifier states six choices: algorithms, required components, a key resolver, freshness, content checking, and replay. None of the six has a default. Copy the recipe closest to your case.
 
 ### Strict RFC 9421
 
@@ -267,7 +267,7 @@ const policy = must(Policy.create({
 
 // A partner signs a request, and it verifies exactly once.
 const signer = must(await Custody.local("ed25519", pair.privateKey.export({ type: "pkcs8", format: "pem" }) as string));
-const request = must(await Message.request("POST", "https://api.example.com/orders?id=7", [], '{"qty":2}', { digest: ["sha-256"] }));
+const request = must(await Message.request("POST", "https://api.example.com/tickets?id=7", [], '{"priority":2}', { digest: ["sha-256"] }));
 const signed = must(await sign(request, { label: "sig", components, algorithm: "ed25519", expiresIn: 60, keyid: "partner-1", digest: ["sha-256"] }, signer));
 must(await verify(signed, policy, { label: "sig" }));
 const again = await verify(signed, policy, { label: "sig" });
@@ -323,7 +323,7 @@ assert.ok(!again.ok && again.error.kind === "core" && again.error.reason === "re
 
 ## Reason to HTTP status (recommendation)
 
-Every failure is a `Result` with a bounded `error`; branch on `error.kind` and `error.reason`. This table is a recommendation, not a requirement. It is derived from the error vocabulary in [error parity](docs/reference/error-parity.md), and the [signing guide](docs/guides/signing-and-verifying.md#respond-to-a-rejection) holds the same mapping as a program that checks it covers every reason. Selectors use `kind/layer.reason` or `kind/reason`; `*` covers that family. An exact reason overrides its family row. The guide program is authoritative. Adapters wrap the underlying reason in `error.source`; map that. Any `retryable: true` error overrides the table with 503. For `adapter/limit`, 413 is an optional alternative to 400.
+Every failure is a `Result` with a bounded `error`; branch on `error.kind` and `error.reason`. This table is a recommendation, not a requirement. It is derived from the error vocabulary in [error parity](docs/reference/error-parity.md); [error reasons](docs/reference/errors.md) explains each reason and what to do about it, and the [signing guide](docs/guides/signing-and-verifying.md#respond-to-a-rejection) holds the same mapping as a program that checks it covers every reason. Selectors use `kind/layer.reason` or `kind/reason`; `*` covers that family. An exact reason overrides its family row. The guide program is authoritative. Adapters wrap the underlying reason in `error.source`; map that. Any `retryable: true` error overrides the table with 503. For `adapter/limit`, 413 is an optional alternative to 400.
 
 The reasoning, stated once: 400 means the message cannot be read, so resending the same bytes cannot help. 401 means the sender did not prove what your policy requires, and a fresh correct signature can. 403 means your configuration refuses a sender it understood. 500 means your own code or configuration is wrong. 503 means the failure is transient or the replay store is in trouble.
 
@@ -332,7 +332,7 @@ The reasoning, stated once: 400 means the message cannot be read, so resending t
 | 400 | `core/fields.*`, `core/negotiation.*`, `message/*`, `structured_fields/*`, `signature_base/*`, `digest/*`, `jose/input.*`, `jose/nesting.*`, `core/content.body_unavailable`, `core/content.digest_unsupported`, `core/crypto.signature_base_failed`, `core/input.invalid_message`, `core/input.invalid_request`, `core/input.limit`, `core/input.unsupported_component`, `crypto/invalid_data`, `adapter/invalid_request`, `adapter/limit`, `adapter/body_unavailable`, `adapter/digest_conflict`, `adapter/untrusted_proxy` |
 | 401 | `core/content.*`, `core/freshness.*`, `core/key.*`, `core/policy.*`, `core/quorum.*`, `core/replay.*`, `discovery/*`, `jose/crypto.*`, `jose/key.*`, `core/crypto.invalid_signature`, `core/fields.missing_signature`, `core/fields.missing_signature_input`, `core/fields.no_web_bot_auth_signature`, `core/fields.unknown_label`, `core/negotiation.negotiation_unfulfilled`, `crypto/invalid_signature`, `custody/invalid_signature`, `custody/decryption_failed`, `adapter/request_rejected`, `adapter/response_rejected` |
 | 403 | `core/binding.*`, `core/policy.test_key_rejected`, `discovery/revoked_key` |
-| 500 | `core/crypto.*`, `core/input.*`, `crypto/*`, `custody/*`, `adapter/*`, `core/binding.invalid_binding`, `core/binding.invalid_verification`, `core/fields.label_in_use`, `core/freshness.invalid_clock`, `core/key.key_resolver_failed`, `core/quorum.ambiguous_key_identity`, `core/replay.commitment_failed`, `discovery/invalid_options`, `discovery/invalid_source`, `discovery/ambiguous_key_source`, `discovery/transport_unavailable`, `jose/crypto.entropy_failure`, `jose/crypto.signer_failed`, `jose/input.invalid_options`, `jose/input.invalid_policy`, `jose/key.key_resolver_failed`, `replay/invalid_claim`, `replay/invalid_options`, `replay/invalid_store` |
+| 500 | `core/crypto.*`, `core/input.*`, `crypto/*`, `custody/*`, `adapter/*`, `core/binding.invalid_binding`, `core/binding.invalid_verification`, `core/fields.label_in_use`, `core/freshness.invalid_clock`, `core/key.key_resolver_failed`, `core/quorum.ambiguous_key_identity`, `core/internal.internal`, `core/replay.commitment_failed`, `discovery/invalid_options`, `discovery/invalid_source`, `discovery/domain_not_found`, `discovery/ambiguous_key_source`, `discovery/transport_unavailable`, `jose/crypto.entropy_failure`, `jose/crypto.signer_failed`, `jose/input.invalid_options`, `jose/input.invalid_policy`, `jose/key.key_resolver_failed`, `replay/invalid_claim`, `replay/invalid_options`, `replay/invalid_store` |
 | 503 | `replay/*`, `core/replay.store_failed`, `core/replay.store_timeout`, `core/replay.store_unavailable` |
 
 For core `agent_unresolved`, `timeout` and `source_unavailable` map to 503; `untrusted_agent` and `revoked_key` map to 403; other details map to 401.
@@ -378,15 +378,16 @@ RequestSeal reports what was cryptographically established and nothing more: the
 - [Key discovery](docs/guides/key-discovery.md)
 - [Signed and encrypted tokens (JOSE)](docs/guides/jose.md)
 - [Key custody](docs/guides/key-custody.md)
+- [Rotating keys](docs/guides/key-rotation.md)
 - [Testing](docs/guides/testing.md)
 - [Migrating from http-message-signatures](docs/guides/migrating-from-http-message-signatures.md)
 
 API: [generated reference](https://baselabs.github.io/request-seal-typescript/). Build it locally with `npm ci --ignore-scripts && npm run docs`, then open the generated `site-dist/index.html`.
 
-Reference: [signing and verification](docs/reference/sign-and-verify.md), [adapters](docs/reference/adapters.md), [Web Bot Auth](docs/reference/web-bot-auth.md), [replay](docs/reference/replay.md), [discovery](docs/reference/discovery.md), [JOSE](docs/reference/jose.md), [wire APIs](docs/reference/wire.md), [multiple signatures](docs/reference/quorum.md), [extension profiles](docs/reference/profiles.md), [error parity](docs/reference/error-parity.md), and [corpus format](docs/reference/corpus-format.md). Design records: the [threat model](docs/design/threat-model.md) and the [architecture decisions](docs/adr/README.md). To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
+Reference: [glossary](docs/reference/glossary.md), [error reasons](docs/reference/errors.md), [signing and verification](docs/reference/sign-and-verify.md), [adapters](docs/reference/adapters.md), [Web Bot Auth](docs/reference/web-bot-auth.md), [replay](docs/reference/replay.md), [discovery](docs/reference/discovery.md), [JOSE](docs/reference/jose.md), [wire APIs](docs/reference/wire.md), [multiple signatures](docs/reference/quorum.md), [extension profiles](docs/reference/profiles.md), [error parity](docs/reference/error-parity.md), [telemetry](docs/reference/telemetry.md), and [corpus format](docs/reference/corpus-format.md). Design record: the [threat model](docs/design/threat-model.md). To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Compatibility
 
-The core runs on Node 22.12.0, 24.21.0, and 26.11.1, Deno 2.5.6, and Bun 1.3.14. Fetch signs on those runtimes, but Fetch verification supports only Deno 2.5.6. HTTPS discovery requires Node; use caller-owned snapshots elsewhere. In browsers (Chromium 156.0.8078.4, Firefox 157.0, WebKit 27.2), the Fetch adapter signs only. Core `verify` checks a caller-built `Message` under an explicit policy without using the Fetch adapter. See the [runtime matrix](docs/reference/runtime-matrix.md) for exact tested versions, permissions, and limitations.
+The core runs on Node 22.12.0, 22.23.1, 24.21.0, and 26.11.1, Deno 2.5.6, and Bun 1.3.14. Fetch signs on those runtimes, but Fetch verification supports only Deno 2.5.6. HTTPS discovery requires Node; use caller-owned snapshots elsewhere. In browsers (Chromium 156.0.8078.4, Firefox 157.0, WebKit 27.2), the Fetch adapter signs only. Core `verify` checks a caller-built `Message` under an explicit policy without using the Fetch adapter. See the [runtime matrix](docs/reference/runtime-matrix.md) for exact tested versions, permissions, and limitations.
 
 Crypto, custody, and error vocabulary follow RequestSeal for Elixir 0.4.1; conformance uses its byte-preserved 0.4.0 corpus. See [the corpus pin](CONTRIBUTING.md) and [replay protection](docs/reference/replay.md).

package/dist/adapters/node-http/index.d.ts

@@ -59,7 +59,14 @@ export type ClientResponse = Readonly<{
 }>;
 /** Capture and retain a Node incoming request before body parsing. */
 export declare function captureRequest(req: unknown, options?: unknown): Promise<Result<Capture>>;
-/** Install early Node request capture on a server with explicit limits. */
+/**
+ * Install early Node request capture on a server with explicit limits.
+ *
+ * Options are `maxBytes`, `timeoutMs` (1 to 300,000 ms, default 5,000), and
+ * `trustedProxies`. Each request is captured under its own fresh `timeoutMs` deadline.
+ * A `context` is refused with `invalid_options`: one Context is one absolute deadline,
+ * and the registration outlives it.
+ */
 export declare function capture(server: unknown, options?: unknown): Result<Readonly<{
     /** Close this capability and release its retained state. */
     close: () => Result<true>;

package/dist/adapters/node-http/index.js

@@ -12,7 +12,8 @@ import { verifyWebBotAuth as coreVerifyWebBotAuth } from "../../web-bot-auth/ver
 import { parseAddress } from "../../discovery/address.js";
 import { isPolicy } from "../../policy.js";
 import { isAcceptSignature } from "../../accept-signature.js";
-import { run } from "../../context.js";
+import { run, withDeadline } from "../../context.js";
+import { timeoutMs as validTimeout } from "../../numbers.js";
 import { err, ok } from "../../result.js";
 import { MESSAGE_MAX_FIELD_BYTES, MESSAGE_MAX_FIELDS_BYTES, MESSAGE_MAX_OCCURRENCES, } from "../../constants.js";
 import * as S from "../support.js";
@@ -428,12 +429,26 @@ export async function captureRequest(req, options = {}) {
         return S.caught(e, "node-http", "capture", "invalid_options");
     }
 }
-/** Install early Node request capture on a server with explicit limits. */
+/**
+ * Install early Node request capture on a server with explicit limits.
+ *
+ * Options are `maxBytes`, `timeoutMs` (1 to 300,000 ms, default 5,000), and
+ * `trustedProxies`. Each request is captured under its own fresh `timeoutMs` deadline.
+ * A `context` is refused with `invalid_options`: one Context is one absolute deadline,
+ * and the registration outlives it.
+ */
 export function capture(server, options = {}) {
     try {
-        const a = captureOptions(options, ["maxBytes", "context", "trustedProxies"], "attach");
+        // A Context is one absolute deadline, so a registration that outlives it takes
+        // a per-request timeoutMs instead; each request gets its own fresh deadline.
+        const a = captureOptions(options, ["maxBytes", "timeoutMs", "trustedProxies"], "attach");
         S.maximum(a, "node-http", "attach");
-        S.context(a, "node-http", "attach");
+        const timeout = validTimeout(Object.hasOwn(a, "timeoutMs") ? a.timeoutMs : 5000);
+        S.need(timeout.ok, "node-http", "attach", "invalid_options");
+        const perRequest = Object.create(null);
+        for (const key of ["maxBytes", "trustedProxies"])
+            if (Object.hasOwn(a, key))
+                perRequest[key] = a[key];
         S.need(server !== null &&
             typeof server === "object" &&
             "prependListener" in server &&
@@ -441,7 +456,8 @@ export function capture(server, options = {}) {
             "removeListener" in server &&
             typeof server.removeListener === "function", "node-http", "attach", "invalid_options");
         const listener = (req) => {
-            void captureRequest(req, a);
+            const context = withDeadline({ timeoutMs: timeout.ok ? timeout.value : 5000 });
+            void captureRequest(req, context.ok ? Object.freeze({ ...perRequest, context: context.value }) : perRequest);
         };
         server.prependListener("request", listener);
         const close = () => {

package/dist/constants.d.ts

@@ -1,10 +1,10 @@
 /** The public package version. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.4.0";
 /** The immutable public conformance corpus release and index digest. */
 export declare const CORPUS_PIN: Readonly<{
-    tag: "v0.4.0";
-    commit: "b2392871933d99641a7cb2ca2726aefd20081dee";
-    indexSha256: "f37435eca377666ab45c2b8f580287263145268e03d9224c76e324e4afaded6f";
+    tag: "v0.5.2";
+    commit: "53b6690ccd5036d58b280d08cf0cacc6427262fe";
+    indexSha256: "ceb30bf713a6e34e6a15847b658a618d8f7568ee6a6c07bfbbf58fa5d143995e";
 }>;
 /** Default bounded Structured Fields parser limits. */
 export declare const STRUCTURED_FIELDS_LIMITS: Readonly<{

package/dist/constants.js

@@ -1,7 +1,7 @@
 /** The public package version. */
-export const VERSION = '0.2.0';
+export const VERSION = '0.4.0';
 /** The immutable public conformance corpus release and index digest. */
-export const CORPUS_PIN = Object.freeze({ tag: 'v0.4.0', commit: 'b2392871933d99641a7cb2ca2726aefd20081dee', indexSha256: 'f37435eca377666ab45c2b8f580287263145268e03d9224c76e324e4afaded6f' });
+export const CORPUS_PIN = Object.freeze({ tag: 'v0.5.2', commit: '53b6690ccd5036d58b280d08cf0cacc6427262fe', indexSha256: 'ceb30bf713a6e34e6a15847b658a618d8f7568ee6a6c07bfbbf58fa5d143995e' });
 // RequestSeal.StructuredFields ceilings at v0.4.0 (b239287).
 /** Default bounded Structured Fields parser limits. */
 export const STRUCTURED_FIELDS_LIMITS = Object.freeze({ maxBytes: 65_536, maxMembers: 1024, maxInnerItems: 256, maxParameters: 256, maxKeyBytes: 256, maxValueBytes: 16_384, maxNodes: 4096 });

package/dist/crypto/algorithm.d.ts

@@ -25,6 +25,10 @@ export type Spec = Readonly<{
     unwrap: boolean;
 }>;
 export declare function algorithms(): Result<readonly HttpAlgorithm[]>;
+/** The JOSE name for a source-asserted alg in either registry spelling; undefined outside both (PS256 and PS384 exist only as JOSE names). */
+export declare function assertedJose(value: string): JwsAlgorithm | undefined;
+/** The JOSE name for either allowlist spelling; total over every validated selector. */
+export declare function joseId(value: SigningAlgorithm): JwsAlgorithm;
 export declare function resolveAlgorithm(value: unknown, allowUnwrap?: boolean): Result<Spec>;
 export declare function selection(spec: Spec): CustodyAlgorithm;
 export declare function importParameters(spec: Spec): {

package/dist/crypto/algorithm.js

@@ -90,6 +90,18 @@ const http = Object.freeze({
 export function algorithms() {
     return ok(Object.freeze(Object.keys(http)));
 }
+/** The JOSE name for a source-asserted alg in either registry spelling; undefined outside both (PS256 and PS384 exist only as JOSE names). */
+export function assertedJose(value) {
+    return Object.hasOwn(http, value)
+        ? http[value]
+        : Object.hasOwn(jws, value)
+            ? value
+            : undefined;
+}
+/** The JOSE name for either allowlist spelling; total over every validated selector. */
+export function joseId(value) {
+    return typeof value === 'string' ? http[value] : value.jws;
+}
 export function resolveAlgorithm(value, allowUnwrap = false) {
     const invalid = () => err(cryptoError('unsupported_algorithm'));
     try {

package/dist/discovery/body.d.ts

@@ -1,17 +1,25 @@
 import { type Context } from "../context.ts";
 import { PublicKey } from "../public_key.ts";
-import { type HttpAlgorithm, type SigningAlgorithm } from "../crypto/algorithm.ts";
+import { type JwsAlgorithm, type SigningAlgorithm } from "../crypto/algorithm.ts";
 import { type Result } from "../result.ts";
 import { type DiscoverySource } from "./source.ts";
 /** Discovery proof status. @inline */
 export type Proof = "signed" | "unsigned" | "not_applicable";
+/** A conditional revalidation outcome: the stored representation is unchanged (RFC 9111 Section 4.3.4). */
+export type NotModified = Readonly<{
+    notModified: true;
+    etag: string;
+    fetchedAt: number;
+    expiresAt: number;
+}>;
 /** A branded resolved public key with origin, proof, and expiration facts. */
 export type Resolution = Readonly<{
     key: PublicKey;
     keyId: string;
     thumbprint: string;
     algorithm: SigningAlgorithm;
-    assertedAlgorithm: HttpAlgorithm | null;
+    /** The source's alg assertion normalized once at import to its JOSE name. */
+    assertedAlgorithm: JwsAlgorithm | null;
     origin: string;
     sourceType: DiscoverySource["type"];
     location: string;
@@ -34,6 +42,8 @@ export type KeySet = Readonly<{
     expiresAt: number;
     revision: string;
     proof: Proof;
+    /** The source's ETag validator, if it sent one; the cache revalidates with it. */
+    etag: string | null;
     /** Resolve an eligible key by identifier, allowed algorithms, and current time. */
     lookup: (keyId: unknown, algorithms: unknown, now?: number) => Promise<Result<Resolution>>;
 }>;

package/dist/discovery/body.js

@@ -1,7 +1,7 @@
 import { remainingMs } from "../context.js";
 import { decodeJson } from "../json.js";
 import { PublicKey } from "../public_key.js";
-import { resolveAlgorithm, algorithms, selection, } from "../crypto/algorithm.js";
+import { resolveAlgorithm, assertedJose, joseId, selection, } from "../crypto/algorithm.js";
 import { digest } from "../crypto/subtle.js";
 import { encodeBase64Url } from "../bytes.js";
 import { ok } from "../result.js";
@@ -59,7 +59,8 @@ export async function lookup(set, kid, allowed, now = systemClock(), transient =
             isResolution(entry) &&
             now < entry.expiresAt &&
             !set.source.revoked.includes(entry.thumbprint), "unknown_key");
-        const algorithm = choices.find((a) => (entry.assertedAlgorithm === null || entry.assertedAlgorithm === a) &&
+        const algorithm = choices.find((a) => (entry.assertedAlgorithm === null ||
+            entry.assertedAlgorithm === joseId(a)) &&
             entry.key.bind(a).ok);
         ensure(algorithm, "unknown_key");
         return ok(resolution({ ...entry, algorithm, revision: set.revision }));
@@ -125,14 +126,34 @@ export async function bodyKeys(doc, source, now, location = source.location, con
             !Array.isArray(input) &&
             Object.keys(input).length <= 32, "invalid_key_set");
         const j = input, asserted = j.alg;
+        // Leaked private members are a publisher blunder the whole set rejects
+        // loudly, before any skip decision: skipping must never hide them.
+        ensure(!["d", "p", "q", "dp", "dq", "qi", "oth", "k"].some((k) => Object.hasOwn(j, k)), "invalid_key_set");
+        // A key whose alg names an algorithm this verifier does not use — an
+        // encryption key, or a signing name outside both registries — cannot
+        // satisfy any signature policy: skip it and keep the rest of the set.
+        if (typeof asserted === "string" && assertedJose(asserted) === undefined)
+            continue;
         ensure(asserted === undefined ||
             asserted === null ||
-            (typeof asserted === "string" &&
-                unwrap(algorithms(), "invalid_key_set").includes(asserted)), "invalid_key_set");
+            typeof asserted === "string", "invalid_key_set");
+        // RFC 7517 sources assert standard JOSE names; either spelling normalizes
+        // once, here, to the JOSE name, which exists for every registry entry.
+        const normalized = typeof asserted === "string" ? assertedJose(asserted) : undefined;
         const imported = Object.assign(Object.create(null), j);
-        if (typeof asserted === "string")
-            imported.alg = unwrap(resolveAlgorithm(asserted), "invalid_key_set").jose;
-        const key = unwrap(await PublicKey.import(imported), "invalid_key_set");
+        if (normalized !== undefined)
+            imported.alg = normalized;
+        const attempt = await PublicKey.import(imported);
+        if (!attempt.ok) {
+            // A well-formed key this verifier cannot import for signature work (an
+            // unknown kty or curve, RFC 7517 Section 5) is skipped like an
+            // out-of-registry alg; other import failures stay set rejections.
+            if (attempt.error.kind !== "crypto" || attempt.error.reason !== "invalid_key")
+                ensure(false, "invalid_key_set");
+            ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
+            continue;
+        }
+        const key = attempt.value;
         ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
         const thumbprint = unwrap(await key.thumbprint(), "invalid_key_set");
         ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
@@ -143,14 +164,15 @@ export async function bodyKeys(doc, source, now, location = source.location, con
             j.kid === thumbprint, "invalid_key_set");
         const nbf = Object.hasOwn(j, "nbf") ? keyTime(j.nbf) : null, exp = Object.hasOwn(j, "exp") ? keyTime(j.exp) : null;
         const publicJwk = unwrap(key.jwk(), "invalid_key_set");
-        const algorithm = (asserted ??
-            (publicJwk.kty === "OKP"
+        const algorithm = normalized === undefined
+            ? (publicJwk.kty === "OKP"
                 ? "ed25519"
                 : publicJwk.kty === "EC"
                     ? publicJwk.crv === "P-256"
                         ? "ecdsa-p256-sha256"
                         : "ecdsa-p384-sha384"
-                    : "rsa-pss-sha512"));
+                    : "rsa-pss-sha512")
+            : { jws: normalized };
         if (key.bind(algorithm).ok &&
             (nbf === null || now >= nbf) &&
             (exp === null || now < exp) &&
@@ -161,7 +183,7 @@ export async function bodyKeys(doc, source, now, location = source.location, con
                 keyId: kid,
                 thumbprint,
                 algorithm,
-                assertedAlgorithm: (asserted ?? null),
+                assertedAlgorithm: normalized ?? null,
                 origin: sourceOrigin(sourceUrl(location)),
                 sourceType: source.type,
                 location,

package/dist/discovery/cache.d.ts

@@ -1,12 +1,16 @@
 import { type Result } from "../result.ts";
 import { type Context } from "../context.ts";
 import { type DiscoverySource } from "./source.ts";
-import { type KeySet, type Resolution } from "./body.ts";
-/** A caller-owned discovery transport callback. */
+import { type KeySet, type NotModified, type Resolution } from "./body.ts";
+/** A caller-owned discovery transport callback. With `validators`, an unchanged source answers 304 and the callback returns a `NotModified` outcome instead of a key set (RFC 9111 Section 4.3.4). */
 export type DiscoveryFetch = (source: DiscoverySource, options: {
     clock: () => number;
     context: Context;
-}) => Promise<Result<KeySet>>;
+    validators?: Readonly<{
+        etag: string;
+        lifetime: number;
+    }>;
+}) => Promise<Result<KeySet | NotModified>>;
 /** A caller-owned bounded cache of discovery key sets and failures. */
 export type DiscoveryCache = Readonly<{
     /** Refresh a source from an explicit snapshot or configured fetch callback. */
@@ -20,6 +24,12 @@ export type DiscoveryCache = Readonly<{
     /** Close this capability and release its retained state. */
     close: () => Result<true>;
 }>;
+/**
+ * Internal to the resolver bridge, not exported from the package: resolve with the
+ * cache's own clock for fetching, storing, negative caching, and entry freshness, and
+ * decide the key's freshness on `decision`.
+ */
+export declare function resolveOnClock(cache: DiscoveryCache, s: unknown, kid: unknown, input: unknown, decision: () => number): Promise<Result<Resolution>>;
 /** Check the private brand of a discovery cache. */
 export declare function isDiscoveryCache(v: unknown): v is DiscoveryCache;
 /** Validate cache options and create a branded discovery cache. */