@request-seal/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## Unreleased
+
+- Align HTTP handle signing and the error vocabulary with RequestSeal 0.4.0: explicit `signingTimeout` bounds, `signer_algorithm_mismatch` with its exact message, and `signing_failed` with a bounded custody source on both forms. Handle deadlines start immediately before custody, after signature-base construction, and are capped at `signingTimeout` (default 5,000 ms) even under a longer caller Context. Generated-spec KeyHandle failures now report `signing_failed` (previously `signer_failed`); direct `handle.sign` malformed output now reports `invalid_signing_output` (previously `custodian_failure`). Add nullable core `message` and `source` fields; preserve callable `signer_failed` behavior. Re-pin the error extraction, shared corpus, and replay peer.
+- 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.
+- 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.
+- Require absolute ssh-agent sockets and preserve connection error parity; execute every README TypeScript fence against real inputs.
+- Validate literal discovery addresses before deadline dispatch; restore replay timer coverage beside caller cancellation and cap built-test concurrency at 4.
+- Add optional Node HTTP capture/replay, final response signing, bounded signed clients, Fetch signing and runtime-restricted verification, and caller-selected OpenSSH agent custody. Record exact Node/Deno/Bun wire observations and generated-key OpenSSL checks.
+- Hold the process only while a run is active: each run arms its own referenced deadline timer, so a run whose only pending work is a caller callback that never settles ends with `deadline_exceeded` at its deadline on Node, Deno and Bun instead of being dropped; idle and settled Contexts never keep a process alive; pass a Context signal to stop sooner.
+- Reject foreign `err()` and `adapterError` payloads with `TypeError`; accept any callable signer or KeyHandle for Accept-Signature fulfillment (an intentional divergence from the reference's two-argument function); permit shared stateless digest factories while rejecting overlapping operations on one session; check fetched cache results against their fetch clock and snapshots against the cache clock; decode every query key eagerly and classify TLS failures as the reference does; avoid idle timers for signal-free contexts and reattach cancellation listeners on reuse after internal release.
+- Redact every individual Verification in JSON and runtime inspection while preserving explicit canonical facts; accept callable signers, trust callbacks, and held-key resolvers without Function.length gates, including KeyHandle signing.
+- Document Web Bot Auth deadline phases, held-key fallback conditions, coverage-only nested evidence, host normalization differences, and generic principal narrowing. Verify origin confinement against two real loopback TLS peers.
+- Add source-bound Web Bot Auth protocol-00 signing and verification, trusted agent provenance, nested coverage evidence, and one profile-separated envelope replay claim.
+- Execute all fourteen Web Bot Auth corpus cases; preserve published bytes and rejection expectations. Add real signed TLS directory rotation/removal, OpenSSL byte agreement, and counting-store checks.
+- Permit explicit JOSE algorithm choices in discovery lookup while retaining key metadata restrictions; apply replay retention ceilings after the complete envelope's earliest end.
+- Match reference quorum assignment search and tie-breaking, check bindings incrementally and yield after about 10 ms of search work, and merge canonical identities with union-find.
+- Parse quorum signature dictionaries once, cache per-label bases by field schema, enforce asymmetric handle identity consistency when observed or supplied, and preserve configured failure order.
+- Align replay rejection, Accept-Signature validation precedence and reference string normalization; add caller-owned ordered fulfillment and redact quorum policies and composite results in JSON inspection; preserve custody deadlines during fulfillment.
+- Executed differential coverage: 2,160 count-only instances from the original brute force (any mode, up to 5 slots), plus 2,160 instances checked on assignments and reasons with bindings, merged and unknown identities, all modes and units, and 8 to 16 slots. The 14 recorded divergence cases are checked against the reference port.
+- Add branded quorum policies, identity-aware assignment with bounded exact search, nested and same-parameter bindings, and independent single-label verification facts.
+- Add RFC 9421 Accept-Signature parsing and verified-pool challenge matching; execute all three quorum and negotiation corpus cases.
+- Keep Context ownership release internal, align safe-number receipt bounds with claims, and reject corpus receipt/claim retention disagreements. Document required-content deadlines and verify-produced number ends.
+- Normalize caller replay store errors, accept the exact signed bigint retention lower bound, release replay child Context listeners, and preserve deadline_exceeded during required content checks.
+- Keep receipt construction internal, verify the packed PostgreSQL export, and require the real database URL in CI. PostgreSQL cross-language checks run where REQUESTSEAL_REPLAY_ELIXIR=1 and an Elixir toolchain with the pinned dependencies are present; the CI Elixir lane is separate work.
+- Add branded replay claims and receipts, shared exclusive retention arithmetic, a bounded single-isolate memory store, and the dependency-free replay-postgres subpath over caller-owned autocommit queries.
+- Execute all eleven v0.3.1 replay.claim cases, add a verbatim replay smoke case, and pass Context cancellation to the store while preventing a late commitment from reaching storage.
+- Add bounded compact JWS signing and verification, JWE encryption and authenticated decryption, one-level nesting, explicit policy snapshots, and separately branded results.
+- Add confined JOSE key-management capabilities, unconditional random fallback on unwrap failure, OAEP uniform-error tests and timing measurements, and reciprocal OpenSSL checks for RSA-OAEP (SHA-1 and SHA-256), A128GCMKW and A256GCMKW (empty AAD), and direct A128GCM and A256GCM in both directions.
+- Execute all v0.3.1 JWS/JWE cases and both JOSE Wycheproof batches; retain source verdicts, declared overrides, applicability counts, and the two exact Bun ECDSA limitations.
+- Re-pin error parity to RequestSeal v0.3.1 (commit b0d6f94); add `retention_exceeded` before replay commitment and storage when the retention end exceeds the clock bound.
+- Add explicit generic signing and verification, frozen policies and layered verifications, canonical fact serialization, and a caller-owned replay port.
+- Add RFC 9530 digests, bounded incremental SHA-2 with construction self-tests, and the Node-compatible hasher subpath.
+- Execute the shared signing and verification corpus and add a tooling smoke case for each new surface.
+- Preserve the discovery Node source type in built exports; refuse OS trust when Node has no non-empty system CA list. Retain cache rollback history through no-store, expiry and invalidation, and count CRLF within the chunk-line limit.
+- Run live corpus vendoring when offline mode is unset, independently of gh; align Deno permissions and extract error rules directly from the pinned commit.
+- Add bounded discovery sources, JWKS/directory/CIMD snapshots, directory possession proofs, source-bound key sets and resolutions, caller-owned caches, and the resolver bridge.
+- Add the `./discovery-node` HTTPS transport with pinned-address TLS connections, IANA address denial, exact exceptions, manual redirects, proxy exclusion, cancellation, and body/decompression ceilings.
+- All four `discovery.body` cases execute from the unchanged v0.3.1 corpus: 2,979 executed or runtime-limited items, 62 not applicable, and 23 pending out of 3,064; add real TLS, DNS, proxy, rotation and removal probes.
+- Add captured WebCrypto primitives, separate HTTP/JWS registries, fixed RSA-PSS parameters, and fixed-width ECDSA and canonical Ed25519 verification.
+- Add bounded DER/PEM codecs, validated RSA CRT import, private local key handles, public key formats and thumbprints, opaque identities, deadline containment, and confined RSA-OAEP/AES capabilities.
+- Add pinned RFC and Wycheproof vectors, OpenSSL reciprocity, crypto/key corpus surfaces, batch counts and overrides, canary checks, and HMAC timing measurements.
+- Keep deadline contexts reusable across nested and sequential runs; settlement releases only the active run, and idle contexts without caller or parent signals do not arm timers.
+- Bound JOSE deadline error parity to the crypto layer and reject invalid adapter constructor arguments with TypeError.
+- Add the ESM package scaffold, strict TypeScript build, web-only core typecheck, Node runtime lanes, Deno and Bun core lanes, and staged trusted-publishing workflow.
+- Add Result and eleven bounded error variants with parity against Elixir RequestSeal v0.3.1 (commit b0d6f94), including status-derived discovery retryability.
+- Add copied ByteString inputs, strict base64/base64url, ordered bounded I-JSON with exact number lexemes, and RFC numeric guards.
+- Add branded deadline contexts, callback fault containment, deep freezing, and own-key option snapshots.
+- Add the corpus loader, checksummed three-case tooling corpus, CLI, tamper checks, self-checks, and package boundary validation.
+- Run live corpus vendoring when gh is available and offline mode is unset; align Deno permissions and extract error rules directly from the pinned commit.
+- All four `discovery.body` cases execute from the unchanged v0.3.1 corpus: 2,965 executed or runtime-limited items, 62 not applicable, and 37 pending out of 3,064; add real TLS, DNS, proxy, rotation and removal probes.
+- Keep deadline contexts reusable across nested and sequential runs; settlement releases only the active run, and idle contexts do not arm timers.
+- Move the corpus pin to RequestSeal v0.3.1, index SHA-256 `222bae05fe7a240c6457ec02659e39f1785629290c7883dca404dd21d71f0398` (verified by `scripts/vendor-corpus.ts v0.3.1 --update-pin`).
+- Vendor the checksummed RequestSeal v0.3.0 conformance corpus; pin its release commit and index digest. Validate batch inventories, per-item pins and overrides, positive references, and execution counts. Report pending surfaces against a committed allowlist during development and block releases until complete coverage. Wycheproof overrides are declared pins with cited clauses and may replace valid, invalid, or acceptable published verdicts; HTTPWG and RFC 9421 batches reject overrides.
+- Require an explicit schema for Structured Fields parsing and caller-built tree serialization; parsed trees retain their schema. Revision strings disable inner lists unless a schema enables them.
+- Add parseField with ordered occurrence combination, selective uniqueKeys, and independent uniqueParameters policies.
+- Require RFC 3986 IPv6 or IPvFuture bracketed authorities; reject bracketed IPv4 forms and zone identifiers.
+- Pin canonical base64 padding: byte sequences with nonzero padding bits reject under the shared decoding rule.
+- Preserve immutable parsed bytes, snapshot caller-built signature parameters, and require branded messages for bases and related requests.
+- Align validation precedence and negative zero serialization; support exact bigint decimal coefficients below 10³⁰ with RFC decimal magnitude limits.
+- Add bounded RFC 8941/RFC 9651 Structured Fields parsing, ordered typed trees, unique mode, explicit schemas, and canonical serialization.
+- Add lossless HTTP message, field, body, and transport values with copied bytes, target-form validation, and optional Content-Digest generation.
+- Add all RFC 9421 signature-base components, related requests, trailers, Structured Fields selection, and exact query encoding.
+- Register four wire corpus surfaces and two upstream batch formats; add checksummed HTTPWG, RFC 9421, and real HTTP capture tests.
+- Keep the tooling smoke corpus independently pinned and excluded from the package.

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 BaseLabs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+RequestSeal (TypeScript)
+Copyright 2026 BaseLabs
+
+This product includes software developed by BaseLabs
+(https://github.com/baselabs).
+
+The error vocabulary corresponds to the Elixir RequestSeal reference
+(https://github.com/baselabs/request_seal) at v0.4.0 (commit b239287).
+No Elixir runtime is included or required.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+**Status:** development · **Kind:** overview · **Updated:** October 10, 2026 · **Governed by:** the public API and shared conformance corpus · **Review when:** package scope or installation changes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# RequestSeal
+
+RequestSeal will provide standards-based HTTP message signatures and JOSE for TypeScript applications using WebCrypto. The first npm release is pending.
+
+After publication:
+
+```sh
+npm install @request-seal/core
+```
+
+For development, use Node 22.12.0 or newer:
+
+```sh
+npm ci --ignore-scripts
+npm run check
+```
+
+The current package contains results, bounded errors, byte codecs, ordered JSON, numeric guards, deadline contexts, option snapshots, Structured Fields, lossless HTTP messages, RFC 9421 signature-base construction, cryptographic verification, public key formats, caller-owned local custody, HTTP signing and verification, explicit policies, content digests, quorum verification and Accept-Signature negotiation, compact JWS/JWE with one-level nesting, discovery snapshots and caches, and an explicit HTTPS discovery transport through `@request-seal/core/discovery-node`. See [multiple signatures](docs/reference/quorum.md), [JOSE APIs](docs/reference/jose.md), [signing and verification](docs/reference/sign-and-verify.md), [wire APIs](docs/reference/wire.md), [discovery](docs/reference/discovery.md), [error parity](docs/reference/error-parity.md), and [corpus format](docs/reference/corpus-format.md).
+
+```ts
+import { Custody, Crypto } from "@request-seal/core";
+
+// Generate example material; applications supply their own private PEM.
+const pair = await crypto.subtle.generateKey("Ed25519", true, ["sign", "verify"]);
+const der = new Uint8Array(await crypto.subtle.exportKey("pkcs8", pair.privateKey));
+const privatePem = "-----BEGIN PRIVATE KEY-----\n" +
+  btoa(Array.from(der, b => String.fromCharCode(b)).join("")) +
+  "\n-----END PRIVATE KEY-----";
+der.fill(0);
+const messageBytes = new TextEncoder().encode("RequestSeal example");
+const imported = await Custody.local("ed25519", privatePem);
+if (imported.ok) {
+  const handle = imported.value;
+  try {
+    const signature = await Crypto.sign("ed25519", handle, messageBytes);
+    if (signature.ok) {
+      const verified = await Crypto.verify("ed25519", handle, signature.value, messageBytes);
+      console.log(verified.ok);
+    }
+  } finally {
+    await handle.release();
+  }
+}
+```
+
+HTTP tokens and JWS selectors are separate: use `{jws: "EdDSA"}` explicitly for
+a JWS-bound handle. Handle methods accept a `withDeadline()` context.
+`PublicKey.import()` accepts public JWK, PEM, or SPKI DER; public exports preserve
+metadata restrictions and thumbprints follow RFC 7638. HMAC identities are optional
+caller-supplied nonsecret values, never hashes of secrets. RSA-OAEP handles unwrap
+into an AES operation capability; they return neither key bytes nor CryptoKey
+references. See the [custody threat model](docs/design/threat-model.md).
+
+## HTTP signing, verification, and digests
+
+Use `sign()` and `verify()` with explicit `Policy` values, caller-owned key
+resolvers, and replay storage. `Digest` handles RFC 9530 content digests;
+`DigestState` supports incremental hashing. See [signing and verification](docs/reference/sign-and-verify.md).
+
+## Web Bot Auth
+
+Verify a protocol-00 request with a caller-trusted, fresh directory `keySet`
+and captured branded `message`. The application supplies `now` in Unix seconds.
+
+```ts
+import { WebBotAuth, ok, type AgentRequest } from "@request-seal/core";
+
+const policy = WebBotAuth.Policy.create({
+  algorithms: ["ed25519"],
+  agents: ({ location }: AgentRequest) => ok(location === keySet.origin ? keySet : null),
+  cache: null,
+  freshness: { clock: () => now, maxAge: 60, skew: 5 },
+  content: "not_required",
+  replay: "not_required",
+});
+if (!policy.ok) throw new Error(policy.error.reason);
+const authenticated = await WebBotAuth.verify(message, policy.value);
+```
+
+Supply your own signed directory snapshot or explicitly configured discovery
+cache. Add required replay storage for nonce uniqueness. See
+[Web Bot Auth](docs/reference/web-bot-auth.md) for signing, trust, held keys,
+nested signatures, result facts, and replay commitments.
+
+## JOSE
+
+Use `JWS` for compact signing and verification, `JWE` for encryption and
+authenticated decryption, and `Nested` for one-level nesting. Supply explicit
+algorithm policies and caller-owned custody or `KeyManagement` capabilities.
+See [JOSE APIs](docs/reference/jose.md).
+
+## HTTP adapters and SSH custody
+
+Use `@request-seal/core/node-http` for Node ingress and clients, `@request-seal/core/fetch`
+for Fetch signing and proven Deno verification, and
+`@request-seal/core/custody-ssh-agent` for caller-selected OpenSSH custody.
+See [adapter contracts and framework recipes](docs/reference/adapters.md).
+
+```ts
+import {captureRequest, verifyRequest} from "@request-seal/core/node-http";
+
+async function authenticate(req, policy) {
+  const captured = await captureRequest(req); // Before body parsers.
+  if (!captured.ok) return captured;
+  const verified = await verifyRequest(req, policy, {label: "sig"});
+  if (!verified.ok) return verified;
+  // Feed the parser these authenticated bytes; the original stream is consumed.
+  req.body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(verified.value.bytes));
+  return verified;
+}
+```
+
+For Web Bot Auth, supply a branded `WebBotAuth.Policy` with caller-configured
+agent trust and discovery. The result is also available through `verification(req)`:
+
+```ts
+import {captureRequest, verifyWebBotAuth} from "@request-seal/core/node-http";
+
+async function authenticateBot(req, policy) {
+  const captured = await captureRequest(req); // Before body parsers.
+  if (!captured.ok) return captured;
+  return verifyWebBotAuth(req, policy, {timeoutMs: 5000});
+}
+```
+
+```ts
+import {signedFetch} from "@request-seal/core/fetch";
+
+async function send(url, spec, signer) {
+  return signedFetch(url, {method: "POST", body: "hello"}, {spec, signer});
+}
+```
+
+```ts
+import {createSshAgent} from "@request-seal/core/custody-ssh-agent";
+
+async function bindAgent(socketPath, publicKey) {
+  return createSshAgent("ed25519", socketPath, publicKey);
+}
+```
+
+The caller supplies the socket and branded public key and owns agent startup
+and key loading. Every returned signature is verified locally.
+
+Fetch verification returns `invalid_request` outside the tested Deno 2.5.6
+allowlist. Exact-target, cookie, and per-occurrence byte coverage remain refused.
+
+## Compatibility
+
+Compatibility is checked against the byte-preserved RequestSeal `v0.4.0` corpus. See [the corpus pin and update command](CONTRIBUTING.md). Development reports pending surfaces; releases require complete coverage.
+
+Node 22.12.0 and 24.21.0 and Deno 2.5.6 verify the pinned published vectors.
+Bun 1.3.14 WebCrypto rejects two valid Wycheproof ECDSA P-256 signatures:
+items 261 (`s = 2^128`) and 262 (`s = n - 2^128`). The consumer policy in
+[`tools/conformance/runtime-limits.json`](tools/conformance/runtime-limits.json)
+applies only to that exact version and reports both as `runtime_limited`.
+Published corpus verdicts stay valid. A stale entry, different rejection, unlisted
+divergence, or divergence on another Bun version fails conformance. See the
+[consumer runtime limitation contract](docs/reference/corpus-format.md#consumer-runtime-limitations)
+and [test API compatibility](CONTRIBUTING.md#runtime-test-compatibility).
+
+See [replay protection](docs/reference/replay.md) for the memory store and the
+optional `@request-seal/core/replay-postgres` query adapter.

package/dist/accept-signature.d.ts

@@ -0,0 +1,26 @@
+import { type InnerList } from "./structured-fields/index.ts";
+import { type Message as HttpMessage } from "./message/index.ts";
+import { type Result } from "./result.ts";
+export type SignatureRequest = Readonly<{
+    label: string;
+    components: InnerList;
+    parameters: Readonly<Record<string, string | true>>;
+}>;
+export type AcceptSignature = readonly SignatureRequest[];
+export declare function isAcceptSignature(v: unknown): v is AcceptSignature;
+export declare function applicable(requests: AcceptSignature, target: "request" | "response"): Result<AcceptSignature>;
+export declare function parseAcceptSignature(wire: unknown, options: unknown): Result<AcceptSignature>;
+export declare function serializeAcceptSignature(requests: unknown): Result<Uint8Array>;
+export type SignatureChoice = Readonly<{
+    algorithm: string;
+    created: number | null;
+    expires: number | null;
+}>;
+export type SignatureChooser = (request: SignatureRequest) => Result<SignatureChoice> | Promise<Result<SignatureChoice>>;
+/** Fulfill atomically through caller-owned selection and the single-signature API. */
+export declare function fulfillAcceptSignature(message: unknown, requests: unknown, chooser: unknown, signer: unknown, options?: unknown): Promise<Result<HttpMessage>>;
+export declare const AcceptSignature: Readonly<{
+    parse: typeof parseAcceptSignature;
+    serialize: typeof serializeAcceptSignature;
+    fulfill: typeof fulfillAcceptSignature;
+}>;