@request-seal/core 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## Unreleased
+
+## 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.
+- Sign Requests in runtimes without a Request body accessor (Firefox) by reading the already materialized body with the byte bound applied after the copy; a Request that merely hides its body stream still goes through the bounded reader. Fetch verification eligibility is checked before any Request is constructed, so an ineligible runtime never disturbs the caller's body. Node discovery reports `discovery/transport_unavailable` only when the runtime denies access to OS trust roots; other trust-store errors keep their existing reasons.
+- Test on Node 22.12.0, 24.21.0, and 26.11.1, Deno 2.5.6, and Bun 1.3.14, plus Chromium 156.0.8078.4, Firefox 157.0, and WebKit 27.2; document exact runtime limitations and OS trust permissions.
+- Return bounded `discovery/transport_unavailable` when system-root access is denied. Refuse ineligible Fetch verified delivery before consuming request bytes.
+- Try IPv6 discovery addresses before IPv4, stable within each family, and remove duplicate answers before the 64-address bound, as RequestSeal does. A host whose IPv6 route silently drops traffic now spends the deadline on the IPv6 address first.
+- Add the Profile extension surface with bounded package stamps, shared selected-label verification, profile-bound replay facts, and execution of all nine profile corpus cases.
+- Widen `Verification.profile` and `ReplayFacts.profile` to include extension stamps; exhaustive narrowing consumers must handle the two-string extension name tuple. `ProfileStamp<MetadataKey>` restricts named metadata to scalar values while runtime validation enforces integer, Unicode, and size bounds.
+- Encode explicit verification facts as UTF-8, convert null stamp metadata to the reference's empty string, and canonicalize whole-stamp key order for replay commitments. Bound name parts and keys to 255 Unicode code points and reject lone surrogates in every stamp string.
+- Render Deno inspection of Verifications, Web Bot Auth envelopes and policies, discovery values, key handles, public keys, key identities, content keys and JOSE results through the callback Deno passes to `Deno.customInspect`; Deno previously printed `[object Object]`. Each still shows only its redacted view.
+- Align crypto and custody with RequestSeal for Elixir 0.4.1: add trailing per-call `maxBytes` options (1–16,777,216; default 1,048,576), validate options before key and algorithm checks, enforce direct callback ceilings, and forward larger SSH-agent requests with bounded peer errors. Invalid byte options return `invalid_options`: crypto for `Crypto.sign`, `Crypto.verify` and `publicKey.verify`, custody for `KeyHandle.sign`, `KeyHandle.verify` and `KeyHandle.unwrap`, which accepts no `maxBytes`. `publicKey.verify` takes the same trailing options. `Crypto.sign`, `Crypto.verify` and `publicKey.verify` check the data size before key validity, as the reference does. Expose `Crypto.maxBytesCeiling()` and the exported `CRYPTO_MAX_BYTES_CEILING` and `CRYPTO_DEFAULT_MAX_BYTES` constants. A caller custodian's fourth argument carries the ceiling; custodians enforce their own input limit and pass the ceiling when delegating. The ssh-agent retains its practical payload limit, including protocol overhead: a peer refusal returns `custodian_protocol` through `KeyHandle.sign` and crypto `invalid_key` through `Crypto.sign`. Keep Message, Body, JWS, adapter, and SignatureBase limits fixed. Align the error vocabulary with RequestSeal for Elixir 0.4.1; retain the unchanged 0.4.0 conformance corpus.
+
+## 0.1.0 - October 10, 2026
+- Published to npm manually, without provenance, from commit d175327. It predates parity with RequestSeal for Elixir 0.4.1, the Profile extension surface and its nine conformance cases, the reciprocal exchange, the browser lanes and the developer documentation.
+- 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.