@blamejs/core 0.10.12 → 0.10.13

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.10.x
 
+- v0.10.13 (2026-05-18) — **`b.cms` CMS codec + `b.streamThrottle` bandwidth limiter + histogram-aware snapshot writer + Windows-safe daemonize.** **`b.cms` — RFC 5652 Cryptographic Message Syntax codec.** New crypto primitive: in-tree CMS encoder + decoder built on the existing `b.asn1Der` walker and the vendored noble-post-quantum primitives. **(a) `b.cms.encodeSignedData({ encapContent, digestAlg, signers })`** — emits a DER-encoded `ContentInfo` carrying `SignedData` per RFC 5652 §5 with PQC signers: ML-DSA-65 + ML-DSA-87 ([RFC 9909](https://www.rfc-editor.org/rfc/rfc9909.html)) and SLH-DSA-SHAKE-256f ([RFC 9881](https://www.rfc-editor.org/rfc/rfc9881.html)). Digest algorithms are SHA3-256 or SHA3-512 (PQC-first; SHA-2 family refused with `cms/bad-digest`). Signed-attributes carry `contentType` + `messageDigest` + `signingTime` in DER-canonical SET-OF ordering; the signature input re-tags the IMPLICIT `[0]` to the universal SET (`0x31`) per §5.4 paragraph 3 so signatures round-trip with any conforming verifier. Signer identifiers carry the full `issuerAndSerialNumber` extracted from the operator-supplied cert DER ([RFC 5652 §10.2.4](https://www.rfc-editor.org/rfc/rfc5652#section-10.2.4)). **(b) `b.cms.encodeEnvelopedData({ plaintext, recipients })`** — emits a DER-encoded `ContentInfo` carrying `EnvelopedData` with `KEMRecipientInfo` recipients per [RFC 9629](https://www.rfc-editor.org/rfc/rfc9629.html) and ML-KEM-1024 per [RFC 9936](https://www.rfc-editor.org/rfc/rfc9936.html). Each recipient encapsulates against the operator-supplied ML-KEM-1024 public key; the framework's SHAKE256 KDF derives a 32-byte content-encryption KEK from the KEM shared-secret bound to the literal label `cms/kemri/chacha20-poly1305` (so a key derived for this composition cannot be confused with one derived for any other framework path). Content encryption is ChaCha20-Poly1305 ([RFC 8103](https://www.rfc-editor.org/rfc/rfc8103.html) OID); the AEAD tag makes Efail-class CBC-malleability impossible by construction ([CVE-2017-17688](https://nvd.nist.gov/vuln/detail/CVE-2017-17688) / [CVE-2017-17689](https://nvd.nist.gov/vuln/detail/CVE-2017-17689)). **(c) `b.cms.decode(buf, { maxBytes? })`** — returns `{ contentType, content }` where `contentType` is the dotted-OID string and `content` is the inner `asn1-der` node. Refuses input past `maxBytes` (default 64 MiB), non-SEQUENCE top-level, missing `[0] EXPLICIT` content, and malformed OID encodings (closes the [CVE-2022-47629](https://nvd.nist.gov/vuln/detail/CVE-2022-47629) libksba class via the existing `b.asn1Der` strict-decode posture). **(d) Refusal posture documented in `lib/cms-codec.js` @intro**: only PQC signature algorithms (`cms/bad-sig-alg`), only ML-KEM-1024 recipients (`cms/bad-recipient-type`), non-empty signers / recipients required at encode (`cms/no-signers` / `cms/no-recipients`). **Operator impact:** no breaking changes; new primitive at `b.cms`. **Deferred to v0.10.14:** the on-the-wire S/MIME 4.0 layer ([RFC 8551](https://www.rfc-editor.org/rfc/rfc8551.html) `multipart/signed` framing, base64 DER body, `micalg` mapping) and OpenPGP encrypt + decrypt + WKD discovery ([RFC 9580](https://www.rfc-editor.org/rfc/rfc9580.html) §5.1 / §5.13 packets plus [draft-koch-openpgp-webkey-service](https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/)) land together so the mail-crypto surface lights up coherently rather than half-on-each-side across two patches. AuthEnvelopedData ([RFC 5083](https://www.rfc-editor.org/rfc/rfc5083.html)) as a distinct `ContentInfo` shape is deferred — EnvelopedData with ChaCha20-Poly1305 is already AEAD by construction; the §5083 OID rewrap lights up alongside S/MIME for peers that refuse the EnvelopedData form. References: [RFC 5652 CMS](https://www.rfc-editor.org/rfc/rfc5652.html) · [RFC 9629 KEMRecipientInfo](https://www.rfc-editor.org/rfc/rfc9629.html) · [RFC 9909 ML-DSA in X.509+CMS](https://www.rfc-editor.org/rfc/rfc9909.html) · [RFC 9881 SLH-DSA in X.509+CMS](https://www.rfc-editor.org/rfc/rfc9881.html) · [RFC 9936 ML-KEM in CMS](https://www.rfc-editor.org/rfc/rfc9936.html) · [RFC 8103 ChaCha20-Poly1305 in CMS](https://www.rfc-editor.org/rfc/rfc8103.html). **(e) `b.streamThrottle` — token-bucket bandwidth limiter.** New primitive: `b.streamThrottle.create({ bytesPerSec, burstBytes? })` returns a shared token bucket whose `.transform()` instances each consume from the same budget. The missing primitive between per-request rate-limit and per-process worker pools: N parallel transfers share the operator-configured byte budget rather than each getting their own. Composes with `node:stream.pipeline` as a regular `stream.Transform`; chunks larger than `burstBytes` refuse with `stream-throttle/oversize-chunk` unless `transform({ allowOversize: true })`. Algorithm is the [RFC 2697 srTCM](https://www.rfc-editor.org/rfc/rfc2697.html) single-rate token-bucket shape, with lazy refill so there is no per-throttle background timer. **(f) Histogram-aware metrics snapshot writer.** `b.metrics.snapshot.startWriter` gains an opt-in `registry` field. When supplied, the JSON snapshot grows a `metrics` field carrying every registered counter / gauge / histogram in structured form — histograms include `buckets` + `observations: [{ labels, counts, sum, count }]`, so sidecar readers compose `histogram_quantile()` against the snapshot file without running a separate `/metrics` HTTP endpoint. `fileMode` default unchanged (0o640). **(g) Windows-safe daemonize.** `b.daemon.start` detached-fork mode now branches by platform. POSIX continues inheriting the parent-opened log FD via `stdio: ["ignore", logFd, logFd]` (unchanged). Windows now uses `stdio: "ignore"` + `windowsHide: true` so the child has no inherited handles that the OS invalidates on parent exit — the previously-broken Windows daemonize path now produces a survivable detached process. The child is responsible for opening its own log file (operators pass `--log` in `opts.args`). `daemon.started` audit gains `stdioMode` so operators can grep for the chosen strategy. **Closes: [#94](https://github.com/blamejs/blamejs/issues/94), [#100](https://github.com/blamejs/blamejs/issues/100), [#101](https://github.com/blamejs/blamejs/issues/101); also closes [#92](https://github.com/blamejs/blamejs/issues/92) and [#93](https://github.com/blamejs/blamejs/issues/93) (already shipped in v0.10.9 as `b.promisePool` / `b.sdNotify` — left open until now).**
 - v0.10.12 (2026-05-18) — **`b.agent.tenant` adoption across the mail-server listeners.** The v0.10.11 shared `b.mail.serverRegistry` primitive gains optional `opts.tenantScope` (a `b.agent.tenant.create()` instance) + `opts.agentTenantId` (the tenant this listener serves). When supplied, every method dispatch first gates on `tenantScope.check(state.actor, agentTenantId)` BEFORE guard validation or audit emission; cross-tenant access surfaces as the v0.9.25-typed `agent-tenant/cross-tenant-access-refused` which the listener's catch-path converts to the protocol's `BAD` / `NO` refusal reply. **(a) `b.mail.server.imap.create({ tenantScope, agentTenantId })`** — IMAP dispatch is gated for every command after AUTH. **(b) `b.mail.server.jmap.create({ tenantScope, agentTenantId })`** — JMAP per-method dispatch routes through the tenant scope alongside its existing per-`accountId` isolation. **(c) `b.mail.server.managesieve.create({ tenantScope, agentTenantId })`** — ManageSieve same pattern. **(d) `b.mail.server.submission.create({ tenantScope, agentTenantId })`** — submission listener gates at the AUTH-success boundary (before `state.actor` is committed) so cross-tenant authentication surfaces as `535 5.7.0 Authentication rejected (cross-tenant)` and the SMTP envelope never begins under the wrong tenant. **(e) `b.mail.server.pop3.create({ tenantScope, agentTenantId })`** — same AUTH-success gate; cross-tenant refusal returns `-ERR Authentication rejected (cross-tenant)`. New audit events: `mail.server.submission.cross_tenant_refused` and `mail.server.pop3.cross_tenant_refused`. **Operator impact:** no breaking changes — `tenantScope` / `agentTenantId` are optional; operators not running multi-tenant see identical behavior. Operators with multi-tenant deployments wire `b.agent.tenant.create({...})` once and pass the same scope to every per-tenant listener instance — cross-tenant isolation becomes structural rather than per-handler opt-in. **Deferred to v0.10.12.1:** per-tenant `b.mailStore` seal-key derivation via `tenantScope.derivedKey(tenantId, "seal")` and per-tenant audit namespaces via `tenantScope.auditFor(tenantId)`. Today every mail listener seals through the framework primary vault key — adequate for single-tenant and multi-tenant-trusted deployments; the v0.10.12.1 follow-up adds per-tenant key separation for compromise-isolation use cases. References: [RFC 9051 IMAP4rev2 §3 state machine](https://www.rfc-editor.org/rfc/rfc9051#section-3) · [RFC 8620 JMAP Core §1.6.2 accountId](https://www.rfc-editor.org/rfc/rfc8620#section-1.6.2) · [RFC 6409 Submission §6.1 actor-to-MAIL-FROM identity binding](https://www.rfc-editor.org/rfc/rfc6409#section-6.1) · [RFC 1939 POP3 §6 transaction state](https://www.rfc-editor.org/rfc/rfc1939#section-6) · v0.9.25 `b.agent.tenant` contract.
 - v0.10.11 (2026-05-18) — **Mail-server per-method registration sweep.** New shared primitive `b.mail.serverRegistry` (`lib/mail-server-registry.js`) replaces the hand-rolled `switch (verb)` dispatchers in the IMAP, JMAP, and ManageSieve listener factories. Operators can now override individual command / method handlers (e.g. IMAP `FETCH`, JMAP `Email/query`, ManageSieve `PUTSCRIPT`) via `opts.overrides: { NAME: { fn, maxHandlerBytes, maxHandlerMs } }` without re-implementing wire-protocol state machines or bypassing the guard substrate. **(a) Per-handler resource budgets — required at registration.** Operators MUST supply `maxHandlerBytes` (≤ 256 MiB) and `maxHandlerMs` (≤ 5 min) on every override; the registration throws `mail-server-registry/bad-max-handler-bytes` / `bad-max-handler-ms` on missing or out-of-range budgets. Defends [CVE-2024-34055](https://nvd.nist.gov/vuln/detail/CVE-2024-34055) (Cyrus authenticated OOM) and [CVE-2026-26312](https://nvd.nist.gov/vuln/detail/CVE-2026-26312) (Stalwart malformed nested `message/rfc822` cyclical OOM) by forcing operators to declare the resource ceiling explicitly. **(b) Catalogue gate.** Per-protocol method names outside the IANA / RFC catalogue refuse registration unless `allowExperimental: true` is supplied — opting in audits the registration so operators can grep for off-spec handlers. **(c) Guard chain preserved.** The listener factories run `b.guardImapCommand` / `b.guardJmap` / `b.guardManagesieveCommand` BEFORE the registry lookup; operator overrides cannot bypass the wire-protocol validation, smuggling defenses, or rate-limit budgets. **(d) Handler timeout.** Promise-returning handlers wrap through `b.safeAsync.withTimeout(maxHandlerMs)`; a runaway override raises `mail-server-registry/handler-timeout` rather than pinning the connection. **(e) Defaults seeded.** IMAP picks up 30 verbs (CAPABILITY, NOOP, LOGOUT, ID, STARTTLS, AUTHENTICATE, LOGIN, ENABLE, SELECT, EXAMINE, LIST, STATUS, NAMESPACE, APPEND, CHECK, CLOSE, UNSELECT, EXPUNGE, FETCH, STORE, UID, IDLE, DONE — plus the previously-undispatched SEARCH / CREATE / DELETE / RENAME / SUBSCRIBE / UNSUBSCRIBE / COPY / MOVE which default to `NO not-configured` until operator overrides); ManageSieve picks up 12 verbs (CAPABILITY, NOOP, STARTTLS, LOGOUT, AUTHENTICATE, HAVESPACE, PUTSCRIPT, LISTSCRIPTS, SETACTIVE, GETSCRIPT, DELETESCRIPT, RENAMESCRIPT); JMAP wraps the existing `opts.methods` map with a one-time deprecation audit (`mail.server.jmap.methods_opt_deprecated`) and routes through the same registry — operators migrate to `opts.overrides` with explicit budgets. **(f) New audit event:** `mail.serverRegistry.method_dispatch` carries `{ protocol, name, source: "builtin" | "operator-override" }` on every dispatch; `mail.serverRegistry.experimental_registration` audits opt-in off-catalogue registrations. **Operator impact:** existing JMAP `opts.methods` callers see the deprecation audit but continue to function (legacy auto-budget = 10 MiB / 30 s); existing IMAP / ManageSieve operators have no migration burden — the listener factories continue to accept the same opts shape. Operators wiring NEW overrides MUST supply explicit budgets. References: [RFC 9051 IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051) · [RFC 8620 JMAP Core](https://www.rfc-editor.org/rfc/rfc8620) · [RFC 8621 JMAP for Mail](https://www.rfc-editor.org/rfc/rfc8621) · [RFC 5804 ManageSieve](https://www.rfc-editor.org/rfc/rfc5804) · [RFC 2971 IMAP4 ID](https://www.rfc-editor.org/rfc/rfc2971) · [RFC 2177 IMAP IDLE](https://www.rfc-editor.org/rfc/rfc2177) · [CVE-2024-34055](https://nvd.nist.gov/vuln/detail/CVE-2024-34055) · [CVE-2026-26312](https://nvd.nist.gov/vuln/detail/CVE-2026-26312).
 - v0.10.10 (2026-05-17) — **PQC envelope completion (experimental).** Two new opt-in PQC-protocol primitives behind explicit experimental namespaces. **(a) `b.jose.jwe.experimental.encrypt` / `.decrypt`** — RFC 7516 compact-serialization JWE with ML-KEM-1024 key encapsulation and XChaCha20-Poly1305 AEAD content encryption. Lives under `b.jose.jwe.experimental` because the JOSE PQC IANA codepoint registration ([draft-ietf-jose-pqc-kem-05](https://datatracker.ietf.org/doc/draft-ietf-jose-pqc-kem/)) hasn't finalized — the namespace name is the contract: codepoints may change between minors without affecting the framework's stable surface. Header carries `{ alg: "ML-KEM-1024", enc: "XC20P", "x-blamejs-experimental": true }`; decrypt refuses any envelope missing the experimental marker (defends a stable-system consumer that accidentally ingests an experimental envelope and treats it as IANA-compliant). Header bytes route through `b.safeJson.parse` for proto-pollution / depth / size defenses; header is byte-capped at 4 KiB. **(b) `b.crypto.hpke.pq.connolly.seal` / `.open` + `b.crypto.hpke.pq.wg.seal` / `.open`** — both active PQ-HPKE drafts behind explicit opt-in: [draft-connolly-cfrg-hpke-mlkem-04](https://datatracker.ietf.org/doc/draft-connolly-cfrg-hpke-mlkem/) (individual; codepoints today) and [draft-ietf-hpke-pq-03](https://datatracker.ietf.org/doc/draft-ietf-hpke-pq/) (WG-adopted). Each wrapper binds a draft-distinguishing label into the RFC 9180 §5.1 `info` parameter so cross-draft substitution (sealing under connolly and opening as wg, or vice versa) refuses by construction — the derived AEAD key diverges and Poly1305 verify fails. Both compose the existing `b.crypto.hpke.seal` / `.open` core (ML-KEM-1024 KEM + HKDF-SHA3-512 + ChaCha20-Poly1305 per project PQC-first policy); the wrappers add the draft-isolation label without touching the wire-format primitives. **New audit namespace:** `jose` (`jose.jwe.experimental.encrypt` / `.decrypt`). **Operator impact:** no breaking changes. The stable `b.crypto.hpke.seal` and the existing `b.crypto.encrypt` envelope shape are unaffected. Operators integrating against systems speaking one of the active PQ-HPKE drafts use the explicit `.pq.connolly` / `.pq.wg` paths; operators wanting IANA-final codepoints wait for graduation to the stable surface (one-minor deprecation window will ship when IANA registration lands). The framework refuses to silently pick a winner between the two drafts. **Deferred to follow-up:** COSE-PQ signatures (draft-ietf-cose-pqc-* — pending IANA codepoint registration), JWE JSON serialization variant (compact-only at this experimental tier), FIPS 203 KAT test vectors against the vendored bundle (test-corpus addition; functional parity is established by the existing v0.8.41 hybrid-KEM verify path). References: [draft-ietf-jose-pqc-kem-05](https://datatracker.ietf.org/doc/draft-ietf-jose-pqc-kem/) · [draft-connolly-cfrg-hpke-mlkem-04](https://datatracker.ietf.org/doc/draft-connolly-cfrg-hpke-mlkem/) · [draft-ietf-hpke-pq-03](https://datatracker.ietf.org/doc/draft-ietf-hpke-pq/) · [RFC 9180 HPKE](https://www.rfc-editor.org/rfc/rfc9180.html) · [RFC 7516 JWE](https://www.rfc-editor.org/rfc/rfc7516.html) · [FIPS 203 ML-KEM](https://csrc.nist.gov/pubs/fips/203/final) · [draft-irtf-cfrg-xchacha XChaCha20-Poly1305](https://datatracker.ietf.org/doc/draft-irtf-cfrg-xchacha/).

package/README.md

@@ -95,6 +95,8 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`)
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
 - **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`)
+- **CMS codec** — RFC 5652 Cryptographic Message Syntax encoder + decoder with PQC signers (ML-DSA-65 / ML-DSA-87 / SLH-DSA-SHAKE-256f; RFC 9909 + 9881) and KEMRecipientInfo recipients (ML-KEM-1024; RFC 9629 + 9936); ChaCha20-Poly1305 content encryption (RFC 8103) so Efail-class malleability cannot apply (`b.cms`)
+- **Stream throttle** — shared token-bucket bandwidth limiter (RFC 2697 srTCM shape); N concurrent `node:stream` pipelines draw from one operator-configured `bytesPerSec` budget (`b.streamThrottle`)
 - **TLS / channel binding** — RFC 9266 TLS-Exporter token-to-session pinning (`b.tlsExporter`); RFC 9162 CT v2 inclusion-proof verification (`b.network.tls.ct.verifyInclusion`); RFC 8555 ACME + RFC 9773 ARI for 47-day certs with `{ jitter: true }` fleet-scheduling (`b.acme.renewIfDue`); draft-aaron-acme-profiles (`acme.listProfiles()` + `newOrder({ profile })`); draft-ietf-acme-dns-account-label (`acme.dnsAccount01ChallengeRecord(token, { identifier })`); RFC 8470 0-RTT inbound posture refuse / replay-cache (`b.router.create({tls0Rtt})`); RFC 9794 SecP256r1MLKEM768 in preferred-group order (`b.network.tls.preferredGroups`)
 - **mTLS CA** — pure-JS, issues clientAuth / serverAuth / dual-EKU certs with SAN; auto-detects highest-PQC signature alg (today ECDSA-P384-SHA384; self-upgrades to SLH-DSA / ML-DSA when X.509 ecosystem catches up); PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`)
 ### HTTP

package/index.js

@@ -375,9 +375,13 @@ var watcher = require("./lib/watcher");
 var localDbThin = require("./lib/local-db-thin");
 var daemon = require("./lib/daemon");
 var selfUpdate = require("./lib/self-update");
+var cmsCodec = require("./lib/cms-codec");
+var streamThrottle = require("./lib/stream-throttle");
 
 module.exports = {
   crypto:           crypto,
+  cms:              cmsCodec,
+  streamThrottle:   streamThrottle,
   router:           router,
   constants:        constants,
   vault:            vault,

package/lib/cms-codec.js

@@ -0,0 +1,685 @@
+"use strict";
+/**
+ * @module b.cms
+ * @nav    Crypto
+ * @title  CMS Codec
+ *
+ * @intro
+ *   RFC 5652 Cryptographic Message Syntax encoder + decoder built on
+ *   the framework's existing `b.asn1Der` substrate and the vendored
+ *   noble-post-quantum primitives (`b.pqcSoftware.ml_dsa_*` /
+ *   `ml_kem_1024` / `slh_dsa_shake_256f`). Re-opens the CMS forward-
+ *   watch item from the 2026-05-08 audit (deferred-with-condition
+ *   pending operator-side demand from the live mail-stack listeners).
+ *   Operator-demand condition is now met by the inbound MX + JMAP
+ *   listeners (v0.9.45–v0.9.50).
+ *
+ *   Scope (v0.10.13):
+ *
+ *   - **ContentInfo** wrapper (RFC 5652 §3) for all top-level emissions.
+ *   - **SignedData** (§5) encode + decode with PQC signer support
+ *     (ML-DSA-65 per RFC 9909 §5, ML-DSA-87 per RFC 9909 §6,
+ *     SLH-DSA-SHAKE-256f per RFC 9881). The signature input is the
+ *     DER-encoded SET OF signed-attributes with the IMPLICIT [0] tag
+ *     re-tagged to the universal SET tag per §5.4 third paragraph.
+ *   - **EnvelopedData** (§6) encode with `KEMRecipientInfo` (RFC 9629)
+ *     for ML-KEM-1024 recipients (RFC 9936). The content-encryption
+ *     key is wrapped under a KEK derived from the KEM shared-secret
+ *     via HKDF-SHA3-512; content is encrypted with ChaCha20-Poly1305
+ *     (RFC 8103 OID). Efail-class CBC-malleability is impossible by
+ *     construction — every CMS content blob emitted by this module
+ *     carries an AEAD tag.
+ *   - Strict DER on emit (canonical: lexicographic SET-OF ordering,
+ *     minimal-length encoding, no indefinite length).
+ *
+ *   Deferred from v0.10.13 (each with documented condition):
+ *
+ *   - **AuthEnvelopedData** (RFC 5083) as a distinct ContentInfo
+ *     ciphertext shape. Operator demand is not yet surfaced — every
+ *     v0.10.13 emission uses EnvelopedData with the ChaCha20-Poly1305
+ *     content-encryption OID, which is already AEAD by construction.
+ *     Defer condition: at least one interop case requires a peer that
+ *     refuses EnvelopedData and accepts only the §5083 ContentInfo
+ *     OID. Cheap escape hatch: operators on such a peer compose
+ *     `b.asn1Der` directly to rewrap an EnvelopedData blob into an
+ *     AuthEnvelopedData ContentInfo. Lights up in v0.10.14 alongside
+ *     `b.mail.smime` sign + verify, where the on-the-wire S/MIME 4.0
+ *     content shape calls for it.
+ *   - **`b.cms.decode` parse-tree of inner SignedData / EnvelopedData**
+ *     beyond the ContentInfo wrapper. v0.10.13 returns the inner
+ *     SEQUENCE bytes as `content` (an asn1-der node); callers that
+ *     need fielded access walk it via `b.asn1Der.readSequence`. The
+ *     fielded decoders ship alongside S/MIME verify in v0.10.14 where
+ *     they're actually consumed.
+ *
+ *   Refusal posture:
+ *
+ *   - Top-level must be SEQUENCE { OID, [0] EXPLICIT content }; any
+ *     other shape throws `cms/bad-content-info`.
+ *   - Recipient/signer counts must be non-empty (`cms/no-signers` /
+ *     `cms/no-recipients`).
+ *   - Only PQC signature algorithms are accepted (`cms/bad-sig-alg`).
+ *   - Only ML-KEM-1024 recipients are accepted (`cms/bad-recipient-type`).
+ *   - Input past `opts.maxBytes` (default 64 MiB) throws `cms/oversize`.
+ *
+ * @card
+ *   RFC 5652 CMS codec (SignedData + EnvelopedData) on b.asn1Der + vendored noble-post-quantum. PQC signers per RFC 9909 / 9881; ML-KEM-1024 recipients per RFC 9629 / 9936. AEAD-only content (ChaCha20-Poly1305) — Efail-class malleability cannot apply.
+ */
+
+var nodeCrypto = require("node:crypto");
+var asn1 = require("./asn1-der");
+var bCrypto = require("./crypto");
+var pqcSoftware = require("./pqc-software");
+var { defineClass } = require("./framework-error");
+var audit = require("./audit");
+
+var CmsCodecError = defineClass("CmsCodecError", { alwaysPermanent: true });
+
+// Common CMS OIDs (RFC 5652, RFC 5083, RFC 9629, RFC 9909, RFC 9881).
+var OID = Object.freeze({
+  data:               "1.2.840.113549.1.7.1",
+  signedData:         "1.2.840.113549.1.7.2",
+  envelopedData:      "1.2.840.113549.1.7.3",
+  authEnvelopedData:  "1.2.840.113549.1.9.16.1.23",   // RFC 5083
+  // PQC signature algorithms (RFC 9909, RFC 9881).
+  mldsa44:            "2.16.840.1.101.3.4.3.17",
+  mldsa65:            "2.16.840.1.101.3.4.3.18",
+  mldsa87:            "2.16.840.1.101.3.4.3.19",
+  slhDsaShake256f:    "2.16.840.1.101.3.4.3.31",
+  // PQC KEM algorithms (RFC 9935, RFC 9936).
+  mlkem768:           "2.16.840.1.101.3.4.4.2",
+  mlkem1024:          "2.16.840.1.101.3.4.4.3",
+  // KEMRecipientInfo type (RFC 9629 §3).
+  kemri:              "1.2.840.113549.1.9.16.13.3",
+  // Symmetric content encryption — ChaCha20-Poly1305 (RFC 8103 IANA codepoint).
+  chacha20Poly1305:   "1.2.840.113549.1.9.16.3.18",
+  // KDF — SHAKE256 XOF (NIST SP 800-185), the framework's PQC-first
+  // KDF substrate (`b.crypto.kdf` wraps it). OID per NIST registry.
+  shake256:           "2.16.840.1.101.3.4.2.12",
+  // Signed-attribute attribute types.
+  contentType:        "1.2.840.113549.1.9.3",
+  messageDigest:      "1.2.840.113549.1.9.4",
+  signingTime:        "1.2.840.113549.1.9.5",
+  // Digest algorithms (SHA3-256 / -512 — framework PQC-first hash family).
+  sha3_256:           "2.16.840.1.101.3.4.2.8",
+  sha3_512:           "2.16.840.1.101.3.4.2.10",
+});
+
+// Refusal ceilings.
+var MAX_DEPTH       = 32;                                                                             // allow:raw-byte-literal — ASN.1 recursion ceiling
+var DEFAULT_MAX_LEN = 64 * 1024 * 1024;                                                               // allow:raw-byte-literal — 64 MiB default decode cap
+
+// Universal-tag bytes used in encode helpers.
+var TAG_SEQUENCE = 0x30;                                                                              // allow:raw-byte-literal — ASN.1 SEQUENCE constructed
+var TAG_SET      = 0x31;                                                                              // allow:raw-byte-literal — ASN.1 SET constructed
+var TAG_UTCTIME  = 0x17;                                                                              // allow:raw-byte-literal — UTCTime universal
+var TAG_GENTIME  = 0x18;                                                                              // allow:raw-byte-literal — GeneralizedTime universal
+
+/**
+ * @primitive b.cms.encodeSignedData
+ * @signature b.cms.encodeSignedData(opts)
+ * @since     0.10.13
+ * @status    stable
+ * @related   b.cms.decode, b.cms.encodeEnvelopedData
+ *
+ * Encode an RFC 5652 §5 SignedData ContentInfo with PQC signer
+ * support. The output is a DER-encoded Buffer ready for embedding in
+ * S/MIME `application/pkcs7-mime; smime-type=signed-data` parts or
+ * for standalone CMS-over-network use.
+ *
+ * @opts
+ *   encapContent:    Buffer,                          // bytes to sign
+ *   digestAlg:       "sha3-256" | "sha3-512",         // default sha3-512
+ *   signers:         [{ certificate: Buffer, secretKey: Uint8Array, sigAlg: string }],
+ *   certificates:    Buffer[],                        // additional DER certs (optional)
+ *   detached:        boolean,                         // default false; true → omit encapContent
+ *
+ * @example
+ *   var pq = b.pqcSoftware;
+ *   var kp = pq.ml_dsa_65.keygen();
+ *   var bytes = b.cms.encodeSignedData({
+ *     encapContent: Buffer.from("payload"),
+ *     digestAlg:    "sha3-512",
+ *     signers:      [{ certificate: certDer, secretKey: kp.secretKey, sigAlg: "ML-DSA-65" }],
+ *   });
+ */
+function encodeSignedData(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new CmsCodecError("cms/bad-opts", "encodeSignedData: opts required");
+  }
+  if (!Buffer.isBuffer(opts.encapContent)) {
+    throw new CmsCodecError("cms/bad-encap", "encodeSignedData: encapContent must be a Buffer");
+  }
+  if (!Array.isArray(opts.signers) || opts.signers.length === 0) {
+    throw new CmsCodecError("cms/no-signers",
+      "encodeSignedData: opts.signers must be a non-empty array");
+  }
+  var digestAlg = opts.digestAlg || "sha3-512";
+  if (digestAlg !== "sha3-256" && digestAlg !== "sha3-512") {
+    throw new CmsCodecError("cms/bad-digest",
+      "encodeSignedData: digestAlg must be 'sha3-256' or 'sha3-512' " +
+      "(PQC-first; SHA-2 family not accepted in v1)");
+  }
+  var digestOid = digestAlg === "sha3-256" ? OID.sha3_256 : OID.sha3_512;
+  var detached = opts.detached === true;
+
+  // Message digest over encapContent (SHA3-256 or SHA3-512 per opts.digestAlg).
+  var msgDigest = nodeCrypto.createHash(digestAlg).update(opts.encapContent).digest();
+
+  // digestAlgorithms SET — one entry per distinct digest algorithm used.
+  var digestAlgs = asn1.writeNode(TAG_SET, _algorithmIdentifier(digestOid));
+
+  // EncapsulatedContentInfo.
+  var encapInfo = _encapsulatedContentInfo(opts.encapContent, detached);
+
+  // Optional certificates [0] IMPLICIT — operator-supplied DER cert blobs.
+  var certsBlock = Buffer.alloc(0);
+  if (Array.isArray(opts.certificates) && opts.certificates.length > 0) {
+    var concat = Buffer.concat(opts.certificates.map(function (c) {
+      if (!Buffer.isBuffer(c)) {
+        throw new CmsCodecError("cms/bad-cert",
+          "encodeSignedData: certificates entries must be DER Buffers");
+      }
+      return c;
+    }));
+    // certificates [0] IMPLICIT CertificateSet — CertificateSet is a SET
+    // of certificates (constructed), so this wrap is the constructed
+    // form per RFC 5652 §5.1.
+    certsBlock = _writeImplicitConstructed(0, concat);
+  }
+
+  // signerInfos SET — one SignerInfo per signer.
+  var sigInfos = opts.signers.map(function (s) {
+    return _signerInfo(s, msgDigest, digestOid);
+  });
+  var signerInfosSet = asn1.writeNode(TAG_SET, Buffer.concat(sigInfos));
+
+  // SignedData SEQUENCE per §5.1.
+  var signedDataSeq = asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeInteger(Buffer.from([1])),                                                              // allow:raw-byte-literal — CMSVersion 1 per §5.1
+    digestAlgs,
+    encapInfo,
+    certsBlock,
+    signerInfosSet,
+  ]));
+
+  // ContentInfo wrapper.
+  var contentInfo = asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeOid(OID.signedData),
+    asn1.writeContextExplicit(0, signedDataSeq),
+  ]));
+  try {
+    audit.safeEmit({
+      action:   "cms.signedData.encoded",
+      outcome:  "success",
+      actor:    {},
+      metadata: { signerCount: opts.signers.length, digestAlg: digestAlg, detached: detached },
+    });
+  } catch (_e) { /* drop-silent */ }
+  return contentInfo;
+}
+
+/**
+ * @primitive b.cms.encodeEnvelopedData
+ * @signature b.cms.encodeEnvelopedData(opts)
+ * @since     0.10.13
+ * @status    stable
+ * @related   b.cms.decode, b.cms.encodeSignedData
+ *
+ * Encode an RFC 5652 §6 EnvelopedData ContentInfo with ML-KEM-1024
+ * recipients per RFC 9629 (KEMRecipientInfo) + RFC 9936 (ML-KEM in
+ * CMS). The content-encryption key is wrapped under a KEK derived
+ * from the per-recipient KEM shared-secret via HKDF-SHA3-512;
+ * content is encrypted with ChaCha20-Poly1305 so Efail-class
+ * malleability cannot apply.
+ *
+ * @opts
+ *   plaintext:    Buffer,                              // bytes to encrypt
+ *   recipients:   [{ type: "kem-mlkem-1024", publicKey: Uint8Array, recipientId: Buffer }],
+ *
+ * @example
+ *   var pq = b.pqcSoftware;
+ *   var kp = pq.ml_kem_1024.keygen();
+ *   var bytes = b.cms.encodeEnvelopedData({
+ *     plaintext:  Buffer.from("secret"),
+ *     recipients: [{ type: "kem-mlkem-1024", publicKey: kp.publicKey, recipientId: Buffer.from([1]) }],
+ *   });
+ */
+function encodeEnvelopedData(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new CmsCodecError("cms/bad-opts", "encodeEnvelopedData: opts required");
+  }
+  if (!Buffer.isBuffer(opts.plaintext)) {
+    throw new CmsCodecError("cms/bad-plaintext", "encodeEnvelopedData: plaintext must be a Buffer");
+  }
+  if (!Array.isArray(opts.recipients) || opts.recipients.length === 0) {
+    throw new CmsCodecError("cms/no-recipients",
+      "encodeEnvelopedData: opts.recipients must be a non-empty array");
+  }
+  // Fresh ChaCha20-Poly1305 content key.
+  var contentKey = bCrypto.generateBytes(32);                                                         // allow:raw-byte-literal — 256-bit ChaCha20 key
+
+  // recipientInfos SET — one KEMRecipientInfo per recipient.
+  var ris = opts.recipients.map(function (r) {
+    return _recipientInfo(r, contentKey);
+  });
+  var recipientInfosSet = asn1.writeNode(TAG_SET, Buffer.concat(ris));
+
+  // EncryptedContentInfo + ChaCha20-Poly1305 ciphertext.
+  var encContent = _encryptedContentInfo(opts.plaintext, contentKey);
+
+  // EnvelopedData SEQUENCE per §6.1. CMSVersion 4 (RFC 9629 §3 — when
+  // any RecipientInfo is OtherRecipientInfo, here KEMRecipientInfo).
+  var envelopedSeq = asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeInteger(Buffer.from([4])),                                                              // allow:raw-byte-literal — CMSVersion 4 per RFC 9629 §3
+    recipientInfosSet,
+    encContent,
+  ]));
+  var contentInfo = asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeOid(OID.envelopedData),
+    asn1.writeContextExplicit(0, envelopedSeq),
+  ]));
+  try {
+    audit.safeEmit({
+      action:   "cms.envelopedData.encoded",
+      outcome:  "success",
+      actor:    {},
+      metadata: { recipientCount: opts.recipients.length },
+    });
+  } catch (_e) { /* drop-silent */ }
+  return contentInfo;
+}
+
+/**
+ * @primitive b.cms.decode
+ * @signature b.cms.decode(buf, opts?)
+ * @since     0.10.13
+ * @status    stable
+ * @related   b.cms.encodeSignedData, b.cms.encodeEnvelopedData
+ *
+ * Decode a CMS ContentInfo from `buf` (DER bytes). Returns
+ * `{ contentType, content }` where `contentType` is the dotted-OID
+ * string (e.g. `"1.2.840.113549.1.7.2"` for SignedData) and
+ * `content` is the inner asn1-der node (SignedData / EnvelopedData /
+ * other) — operators walk it via `b.asn1Der.readSequence`. Fielded
+ * decoders for SignedData / EnvelopedData ship in v0.10.14 alongside
+ * S/MIME sign+verify.
+ *
+ * Refuses input past `opts.maxBytes` (default 64 MiB), top-level
+ * non-SEQUENCE shapes, missing OID + [0] EXPLICIT child pair.
+ *
+ * @opts
+ *   maxBytes:    number,            // default 64 MiB
+ *
+ * @example
+ *   var ci = b.cms.decode(derBytes);
+ *   ci.contentType;  // → "1.2.840.113549.1.7.2"
+ */
+function decode(buf, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(buf)) {
+    throw new CmsCodecError("cms/bad-input", "decode: buf must be a Buffer");
+  }
+  var maxBytes = opts.maxBytes || DEFAULT_MAX_LEN;
+  if (buf.length > maxBytes) {
+    throw new CmsCodecError("cms/oversize",
+      "decode: input " + buf.length + " bytes exceeds maxBytes=" + maxBytes);
+  }
+  var node;
+  try { node = asn1.readNode(buf); }
+  catch (e) {
+    throw new CmsCodecError("cms/bad-asn1",
+      "decode: ASN.1 parse failed: " + ((e && e.message) || String(e)));
+  }
+  if (!(node.tag === asn1.TAG.SEQUENCE && node.constructed)) {
+    throw new CmsCodecError("cms/bad-content-info",
+      "decode: top-level must be SEQUENCE (got tag 0x" + node.tag.toString(16) + ")");                // allow:raw-byte-literal — hex radix for error-message formatting
+  }
+  // ContentInfo SEQUENCE children: { contentType OID, [0] EXPLICIT ANY }.
+  var children;
+  try { children = asn1.readSequence(node.value); }
+  catch (e2) {
+    throw new CmsCodecError("cms/bad-content-info",
+      "decode: ContentInfo body parse failed: " + ((e2 && e2.message) || String(e2)));
+  }
+  if (children.length < 2) {
+    throw new CmsCodecError("cms/bad-content-info",
+      "decode: ContentInfo SEQUENCE must have 2 children (contentType + [0] content)");
+  }
+  var contentType;
+  try { contentType = asn1.readOid(children[0]); }
+  catch (e3) {
+    throw new CmsCodecError("cms/bad-oid",
+      "decode: contentType OID parse failed: " + ((e3 && e3.message) || String(e3)));
+  }
+  // [0] EXPLICIT content — unwrap via asn1.unwrapExplicit(node, expectedTagNumber).
+  var inner;
+  try { inner = asn1.unwrapExplicit(children[1], 0); }
+  catch (e4) {
+    throw new CmsCodecError("cms/bad-explicit-content",
+      "decode: [0] EXPLICIT content unwrap failed: " + ((e4 && e4.message) || String(e4)));
+  }
+  return { contentType: contentType, content: inner };
+}
+
+// ---- Internal helpers -----------------------------------------------------
+
+// OIDs whose AlgorithmIdentifier specifies ABSENT parameters per their
+// publishing RFC — emitting NULL here would make the CMS structure
+// non-conformant for strict validators (Codex P1 finding on PR #102).
+// ML-DSA per RFC 9909 §3, SLH-DSA per RFC 9881 §3, ML-KEM per
+// RFC 9936 §3. SHAKE-family per FIPS 202 (NIST registry — absent params).
+var ABSENT_PARAM_OIDS = new Set([
+  "2.16.840.1.101.3.4.3.17",  // ml_dsa_44
+  "2.16.840.1.101.3.4.3.18",  // ml_dsa_65
+  "2.16.840.1.101.3.4.3.19",  // ml_dsa_87
+  "2.16.840.1.101.3.4.3.31",  // slh_dsa_shake_256f
+  "2.16.840.1.101.3.4.4.2",   // ml_kem_768
+  "2.16.840.1.101.3.4.4.3",   // ml_kem_1024
+  "2.16.840.1.101.3.4.2.12",  // shake256 (KDF/digest — absent params)
+]);
+
+function _algorithmIdentifier(oidStr) {
+  // SEQUENCE { algorithm OID, parameters ANY DEFINED BY algorithm OPTIONAL }.
+  // PQC OIDs (RFC 9909 / 9881 / 9936) MUST emit with parameters ABSENT;
+  // legacy non-PQC OIDs (SHA-2 / SHA-3 hash OIDs in this module, ChaCha20-
+  // Poly1305 wrap OID) still carry the historical NULL parameter shape
+  // that fielded CMS toolchains expect.
+  if (ABSENT_PARAM_OIDS.has(oidStr)) {
+    return asn1.writeNode(TAG_SEQUENCE, asn1.writeOid(oidStr));
+  }
+  return asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeOid(oidStr),
+    asn1.writeNull(),
+  ]));
+}
+
+function _writeImplicitConstructed(tagNumber, payload) {
+  // [N] IMPLICIT context-specific CONSTRUCTED — for wrapping SEQUENCE /
+  // SET payloads (e.g. certificates [0], crls [1], OtherRecipientInfo
+  // value).
+  var tagByte = 0xa0 | (tagNumber & 0x1f);                                                            // allow:raw-byte-literal — context-specific constructed mask
+  return asn1.writeNode(tagByte, payload);
+}
+
+function _writeImplicitPrimitive(tagNumber, value) {
+  // [N] IMPLICIT context-specific PRIMITIVE — for wrapping primitive
+  // ASN.1 types (OCTET STRING / INTEGER / OID) that have been IMPLICIT-
+  // tagged. The constructed bit MUST NOT be set or strict CMS parsers
+  // reject the structure (Codex P1 finding on PR #102 — RecipientIdentifier
+  // CHOICE's SubjectKeyIdentifier alternative is `[0] IMPLICIT OCTET STRING`,
+  // a primitive type).
+  var tagByte = 0x80 | (tagNumber & 0x1f);                                                            // allow:raw-byte-literal — context-specific primitive mask
+  return asn1.writeNode(tagByte, value);
+}
+
+function _encapsulatedContentInfo(content, detached) {
+  // EncapsulatedContentInfo: SEQUENCE { eContentType OID, eContent [0] EXPLICIT OCTET STRING? }
+  var inner = [asn1.writeOid(OID.data)];
+  if (!detached) {
+    inner.push(asn1.writeContextExplicit(0, asn1.writeOctetString(content)));
+  }
+  return asn1.writeNode(TAG_SEQUENCE, Buffer.concat(inner));
+}
+
+function _signerInfo(signer, msgDigest, digestOid) {
+  if (!signer || typeof signer !== "object") {
+    throw new CmsCodecError("cms/bad-signer", "signer entry must be an object");
+  }
+  if (!Buffer.isBuffer(signer.certificate)) {
+    throw new CmsCodecError("cms/bad-signer-cert",
+      "signer.certificate must be a DER Buffer");
+  }
+  if (signer.sigAlg !== "ML-DSA-65" && signer.sigAlg !== "ML-DSA-87" &&
+      signer.sigAlg !== "SLH-DSA-SHAKE-256f") {
+    throw new CmsCodecError("cms/bad-sig-alg",
+      "signer.sigAlg must be ML-DSA-65 / ML-DSA-87 / SLH-DSA-SHAKE-256f " +
+      "(PQC-first; RSA / ECDSA not accepted)");
+  }
+  if (!(signer.secretKey instanceof Uint8Array)) {
+    throw new CmsCodecError("cms/bad-signer-key",
+      "signer.secretKey must be a Uint8Array from the matching PQC keygen");
+  }
+  var sigAlgOid;
+  var pqcAlg;
+  if (signer.sigAlg === "ML-DSA-65")        { sigAlgOid = OID.mldsa65;         pqcAlg = pqcSoftware.ml_dsa_65; }
+  else if (signer.sigAlg === "ML-DSA-87")   { sigAlgOid = OID.mldsa87;         pqcAlg = pqcSoftware.ml_dsa_87; }
+  else                                       { sigAlgOid = OID.slhDsaShake256f; pqcAlg = pqcSoftware.slh_dsa_shake_256f; }
+
+  // signedAttrs SET OF Attribute — IMPLICIT [0] tagged in the SignerInfo.
+  // For the signature input we re-tag as universal SET (0x31) per
+  // RFC 5652 §5.4 paragraph 3.
+  var signedAttrs = _signedAttrs({
+    contentType:   OID.data,
+    messageDigest: msgDigest,
+    signingTime:   signer.signingTime instanceof Date ? signer.signingTime : new Date(),
+  });
+  // signedAttrs is already `31 LL VV...` — re-tag to `A0 LL VV...` for the
+  // SignerInfo, and use the original `31 LL VV...` form as the signature
+  // input.
+  var signatureInput = signedAttrs;
+  var signedAttrsImplicit = Buffer.concat([Buffer.from([0xa0]),                                       // allow:raw-byte-literal — IMPLICIT [0] tag per RFC 5652 §5.3
+                                            signedAttrs.slice(1)]);
+
+  var signature;
+  try {
+    // noble signature: sign(msg, secretKey) → Uint8Array.
+    var sigBytes = pqcAlg.sign(new Uint8Array(signatureInput), signer.secretKey);
+    signature = Buffer.from(sigBytes);
+  } catch (e) {
+    throw new CmsCodecError("cms/sign-failed",
+      "SignerInfo signature failed: " + ((e && e.message) || String(e)));
+  }
+
+  // SignerInfo SEQUENCE per §5.3 (issuerAndSerialNumber variant — CMSVersion 1).
+  return asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeInteger(Buffer.from([1])),                                                              // allow:raw-byte-literal — CMSVersion 1 for issuerAndSerialNumber
+    _issuerAndSerialNumber(signer.certificate),
+    _algorithmIdentifier(digestOid),
+    signedAttrsImplicit,
+    _algorithmIdentifier(sigAlgOid),
+    asn1.writeOctetString(signature),
+  ]));
+}
+
+function _signedAttrs(attrs) {
+  // SET OF Attribute — DER canonical: sort entries by encoded bytes (X.690 §11.6).
+  var entries = [];
+  entries.push(_attribute(OID.contentType,   asn1.writeOid(attrs.contentType)));
+  entries.push(_attribute(OID.messageDigest, asn1.writeOctetString(attrs.messageDigest)));
+  entries.push(_attribute(OID.signingTime,   _encodeTime(attrs.signingTime)));
+  entries.sort(Buffer.compare);
+  return asn1.writeNode(TAG_SET, Buffer.concat(entries));
+}
+
+function _attribute(typeOid, valueBuf) {
+  // Attribute ::= SEQUENCE { attrType OID, attrValues SET OF ANY }
+  return asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeOid(typeOid),
+    asn1.writeNode(TAG_SET, valueBuf),
+  ]));
+}
+
+function _encodeTime(date) {
+  var pad = function (n) { return n < 10 ? "0" + n : String(n); };
+  var y = date.getUTCFullYear();
+  var mm = pad(date.getUTCMonth() + 1);
+  var dd = pad(date.getUTCDate());
+  var hh = pad(date.getUTCHours());
+  var mi = pad(date.getUTCMinutes());
+  var ss = pad(date.getUTCSeconds());
+  if (y >= 1950 && y <= 2049) {
+    var yy = pad(y % 100);
+    return asn1.writeNode(TAG_UTCTIME, Buffer.from(yy + mm + dd + hh + mi + ss + "Z", "ascii"));
+  }
+  return asn1.writeNode(TAG_GENTIME, Buffer.from(String(y) + mm + dd + hh + mi + ss + "Z", "ascii"));
+}
+
+function _issuerAndSerialNumber(certDer) {
+  // RFC 5280 §4.1 Certificate SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue }.
+  // tbsCertificate SEQUENCE { [0] version?, serialNumber INTEGER, signature AlgId, issuer Name, ... }
+  // We extract `issuer Name` (SEQUENCE) + `serialNumber` (INTEGER) and wrap as
+  // SEQUENCE { issuer, serialNumber } per RFC 5652 §10.2.4.
+  var cert;
+  try { cert = asn1.readNode(certDer); }
+  catch (e) {
+    throw new CmsCodecError("cms/bad-cert", "certificate DER parse failed: " + ((e && e.message) || String(e)));
+  }
+  if (cert.tag !== asn1.TAG.SEQUENCE) {
+    throw new CmsCodecError("cms/bad-cert", "certificate top-level is not a SEQUENCE");
+  }
+  var certChildren;
+  try { certChildren = asn1.readSequence(cert.value); }
+  catch (e2) {
+    throw new CmsCodecError("cms/bad-cert", "certificate body parse failed: " + ((e2 && e2.message) || String(e2)));
+  }
+  if (certChildren.length < 1 || certChildren[0].tag !== asn1.TAG.SEQUENCE) {
+    throw new CmsCodecError("cms/bad-cert", "certificate has no tbsCertificate SEQUENCE");
+  }
+  var tbsChildren;
+  try { tbsChildren = asn1.readSequence(certChildren[0].value); }
+  catch (e3) {
+    throw new CmsCodecError("cms/bad-cert", "tbsCertificate body parse failed: " + ((e3 && e3.message) || String(e3)));
+  }
+  // Optional [0] EXPLICIT version then serialNumber INTEGER.
+  var idx = 0;
+  if (tbsChildren[idx] && tbsChildren[idx].tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC &&
+      tbsChildren[idx].tag === 0) {
+    idx += 1;
+  }
+  var serialNode = tbsChildren[idx];
+  if (!serialNode || serialNode.tag !== asn1.TAG.INTEGER) {
+    throw new CmsCodecError("cms/bad-cert", "tbsCertificate has no serialNumber INTEGER");
+  }
+  idx += 1;
+  // Skip signature AlgId (SEQUENCE).
+  if (!tbsChildren[idx] || tbsChildren[idx].tag !== asn1.TAG.SEQUENCE) {
+    throw new CmsCodecError("cms/bad-cert", "tbsCertificate has no signature AlgorithmIdentifier");
+  }
+  idx += 1;
+  // Issuer Name (SEQUENCE).
+  var issuerNode = tbsChildren[idx];
+  if (!issuerNode || issuerNode.tag !== asn1.TAG.SEQUENCE) {
+    throw new CmsCodecError("cms/bad-cert", "tbsCertificate has no issuer Name SEQUENCE");
+  }
+  // Reconstruct the full DER bytes of issuer (header + value) and
+  // serialNumber (header + value) — readNode gave us value-only Buffers.
+  var issuerDer = _reEncodeNode(issuerNode);
+  var serialDer = _reEncodeNode(serialNode);
+  return asn1.writeNode(TAG_SEQUENCE, Buffer.concat([issuerDer, serialDer]));
+}
+
+function _reEncodeNode(node) {
+  // Reconstruct the TLV bytes of `node` — asn1-der's readNode returns the
+  // value slice but the issuerAndSerialNumber surface needs the full
+  // TLV. writeNode rebuilds canonical DER from the original tag byte +
+  // value bytes; the tag byte is reconstructed from tagClass + constructed +
+  // tag number.
+  var classBits  = (node.tagClass & 0x03) << 6;                                                       // allow:raw-byte-literal — tag-class shift
+  var consBit    = node.constructed ? 0x20 : 0x00;                                                    // allow:raw-byte-literal — constructed bit
+  var tagBits    = node.tag & 0x1f;                                                                   // allow:raw-byte-literal — short-form tag
+  var tagByte    = classBits | consBit | tagBits;
+  return asn1.writeNode(tagByte, node.value);
+}
+
+function _recipientInfo(recipient, contentKey) {
+  // RFC 9629 KEMRecipientInfo wrapped in [1] IMPLICIT OtherRecipientInfo
+  // SEQUENCE per §3:
+  //   ori [4] IMPLICIT OtherRecipientInfo
+  //   OtherRecipientInfo ::= SEQUENCE { oriType OID, oriValue ANY DEFINED BY oriType }
+  //   oriType = id-ori-kem (RFC 9629 §3)
+  //   oriValue = KEMRecipientInfo SEQUENCE { version, rid, kem, kemct, kdf, kekLength, ukm?, wrap, encryptedKey }
+  if (!recipient || typeof recipient !== "object") {
+    throw new CmsCodecError("cms/bad-recipient", "recipient must be an object");
+  }
+  if (recipient.type !== "kem-mlkem-1024") {
+    throw new CmsCodecError("cms/bad-recipient-type",
+      "recipient.type must be 'kem-mlkem-1024' " +
+      "(other KEMs / KEKRecipientInfo / KeyAgreeRecipientInfo deferred)");
+  }
+  if (!(recipient.publicKey instanceof Uint8Array)) {
+    throw new CmsCodecError("cms/bad-recipient-key",
+      "recipient.publicKey must be a Uint8Array from b.pqcSoftware.ml_kem_1024.keygen()");
+  }
+  if (!Buffer.isBuffer(recipient.recipientId)) {
+    throw new CmsCodecError("cms/bad-recipient-id",
+      "recipient.recipientId must be a Buffer (SubjectKeyIdentifier or issuer-and-serial-number DER)");
+  }
+  // KEM encapsulate against the recipient's ML-KEM-1024 public key.
+  var encap;
+  try { encap = pqcSoftware.ml_kem_1024.encapsulate(recipient.publicKey); }
+  catch (e) {
+    throw new CmsCodecError("cms/kem-encap-failed",
+      "ML-KEM-1024 encapsulation failed: " + ((e && e.message) || String(e)));
+  }
+  // Derive 32-byte KEK from the KEM shared secret via SHAKE256 (the
+  // framework's PQC-first KDF). The info-label binds the derivation to
+  // the CMS KEMRecipientInfo + ChaCha20-Poly1305 wrap context so a key
+  // derived here cannot be confused with a key derived for any other
+  // composition path.
+  var infoLabel = Buffer.from("cms/kemri/chacha20-poly1305", "ascii");
+  var kdfInput  = Buffer.concat([Buffer.from(encap.sharedSecret), infoLabel]);
+  var kek       = bCrypto.kdf(kdfInput, 32);                                                          // allow:raw-byte-literal — 256-bit KEK
+  // Wrap the content key under the KEK using ChaCha20-Poly1305.
+  var wrapped;
+  try { wrapped = bCrypto.encryptPacked(contentKey, kek); }
+  catch (e2) {
+    throw new CmsCodecError("cms/wrap-failed",
+      "content-key wrap failed: " + ((e2 && e2.message) || String(e2)));
+  }
+  // KEMRecipientInfo SEQUENCE.
+  // Simplified ordering, version 0 per RFC 9629 §3.
+  var kemRi = asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeInteger(Buffer.from([0])),                                                              // allow:raw-byte-literal — KEMRecipientInfo version 0
+    // rid CHOICE per RFC 9629 §3: this module ships the [0] IMPLICIT
+    // SubjectKeyIdentifier alternative — SKI is `[0] IMPLICIT OCTET
+    // STRING` (PRIMITIVE per RFC 5652 §10.2.4). The constructed form
+    // (0xa0) is the IssuerAndSerialNumber CHOICE alternative; this
+    // module picks SKI for KEM recipients since the operator-supplied
+    // recipientId is opaque key-identifier bytes.
+    _writeImplicitPrimitive(0, recipient.recipientId),
+    _algorithmIdentifier(OID.mlkem1024),                                                              // kem
+    asn1.writeOctetString(Buffer.from(encap.cipherText)),                                             // kemct
+    _algorithmIdentifier(OID.shake256),                                                               // kdf
+    asn1.writeInteger(Buffer.from([32])),                                                             // allow:raw-byte-literal — kekLength = 32 bytes
+    _algorithmIdentifier(OID.chacha20Poly1305),                                                       // wrap (also used as content-encryption AlgId; same OID)
+    asn1.writeOctetString(wrapped),                                                                   // encryptedKey
+  ]));
+  // OtherRecipientInfo SEQUENCE { oriType OID, oriValue ANY DEFINED BY oriType }
+  // wrapped in [4] IMPLICIT context tag per RFC 5652 §6.2 RecipientInfo
+  // CHOICE alternative.
+  var oriValue = Buffer.concat([
+    asn1.writeOid(OID.kemri),
+    kemRi,
+  ]);
+  return asn1.writeNode(0xa4, oriValue);                                                              // allow:raw-byte-literal — [4] IMPLICIT context-specific constructed (ori CHOICE)
+}
+
+function _encryptedContentInfo(plaintext, contentKey) {
+  // EncryptedContentInfo SEQUENCE { contentType OID, contentEncryptionAlgorithm AlgId,
+  // encryptedContent [0] IMPLICIT OCTET STRING OPTIONAL }
+  // The ChaCha20-Poly1305 ciphertext is the framework's encryptPacked output
+  // (nonce ‖ ciphertext ‖ tag). Operators decoding with a non-blamejs CMS
+  // peer need to know the framework wire format — documented in @intro.
+  var ct;
+  try { ct = bCrypto.encryptPacked(plaintext, contentKey); }
+  catch (e) {
+    throw new CmsCodecError("cms/encrypt-failed",
+      "content encryption failed: " + ((e && e.message) || String(e)));
+  }
+  return asn1.writeNode(TAG_SEQUENCE, Buffer.concat([
+    asn1.writeOid(OID.data),
+    _algorithmIdentifier(OID.chacha20Poly1305),
+    _writeImplicitPrimitive(0, ct),
+  ]));
+}
+
+module.exports = {
+  encodeSignedData:    encodeSignedData,
+  encodeEnvelopedData: encodeEnvelopedData,
+  decode:              decode,
+  OID:                 OID,
+  MAX_DEPTH:           MAX_DEPTH,
+  DEFAULT_MAX_LEN:     DEFAULT_MAX_LEN,
+  CmsCodecError:       CmsCodecError,
+};

package/lib/daemon.js

@@ -237,13 +237,37 @@ function start(opts) {
       throw new DaemonError("daemon/already-running",
         "daemon.start: pidFile '" + pidFile + "' held by live PID " + existingLive);
     }
-    var logFd = logFile ? _openLogFd(logFile) : "ignore";
+    // Detached-stdio strategy diverges by platform:
+    //
+    //   POSIX: inherit the parent's open log FD via stdio so the child
+    //   writes to the operator's log file without re-opening it. POSIX
+    //   keeps the FD alive across the parent's exit; the child sees it
+    //   as fd 1 / 2 and writes normally.
+    //
+    //   Windows: passing a parent-opened FD through stdio causes the
+    //   child to die the moment the parent's handle is closed (the OS
+    //   ref-counts file handles per-process and the inherited handle
+    //   becomes invalid on parent exit). The Windows-safe pattern is
+    //   `stdio: "ignore"` + `windowsHide: true` so the child has no
+    //   inherited handles to lose, and the operator's child code opens
+    //   the log file itself once its logger initialises. The child is
+    //   responsible for `--log` parsing on Windows — pass it via
+    //   `opts.args` and let the application code handle the open.
+    var isWindows = process.platform === "win32";
+    var logFd = (!isWindows && logFile) ? _openLogFd(logFile) : null;
+    var spawnStdio;
+    if (isWindows || logFd === null) {
+      spawnStdio = "ignore";
+    } else {
+      spawnStdio = ["ignore", logFd, logFd];
+    }
     var child;
     try {
       child = processSpawn.spawn(opts.command, opts.args || [], {
-        detached: true,
-        stdio:    ["ignore", logFd, logFd],
-        cwd:      typeof opts.cwd === "string" ? opts.cwd : undefined,
+        detached:    true,
+        stdio:       spawnStdio,
+        cwd:         typeof opts.cwd === "string" ? opts.cwd : undefined,
+        windowsHide: isWindows ? true : undefined,
       });
     } catch (e) {
       try { if (typeof logFd === "number") nodeFs.closeSync(logFd); }
@@ -267,6 +291,7 @@ function start(opts) {
       logFile:     logFile,
       commandKind: "detached-fork",
       pid:         child.pid,
+      stdioMode:   isWindows ? "ignore-windows" : (logFd === null ? "ignore" : "inherit-logfd"),
     });
     log("daemon started (detached) pid=" + child.pid + " pidFile=" + pidFile);
     return { pid: child.pid, pidFile: pidFile, logFile: logFile, mode: "detached" };

package/lib/mail-crypto-pgp.js

@@ -60,15 +60,16 @@
  *   Deferred from v1 (each with the documented condition for opting in):
  *     - In-process encrypt + decrypt (Message Encrypted Session Key +
  *       Symmetrically Encrypted Integrity Protected Data packets,
- *       RFC 9580 §5.1 / §5.13). Defer condition: no operator demand
- *       surfaced for in-process encrypt-to-recipient yet. Operators
- *       wanting at-rest encrypted mail blobs compose `b.vault` +
- *       `b.cryptoField`; operators wanting wire-level encrypt-to-
- *       recipient with WKD key discovery wait for v0.9.59 once
- *       `b.publicSuffix` + WKD lookup are confirmed. Cheap escape
- *       hatch: operators wire a third-party OpenPGP library in their
- *       own consumer code and call sign() / verify() on the resulting
- *       cleartext blob.
+ *       RFC 9580 §5.1 / §5.13) and WKD key discovery (draft-koch-
+ *       openpgp-webkey-service). Defer condition: ships in v0.10.14
+ *       alongside `b.mail.crypto.smime` sign + verify — the CMS
+ *       substrate `b.cms` landed in v0.10.13 unblocked the S/MIME
+ *       side, and OpenPGP encrypt rides the same release so the
+ *       mail-crypto surface lights up coherently rather than half-
+ *       on-each-side across two patches. Cheap escape hatch (pre-
+ *       v0.10.14): operators wire a third-party OpenPGP library in
+ *       their own consumer code and call this module's sign() /
+ *       verify() on the resulting cleartext blob.
  *     - v6 signature packets (RFC 9580 §5.2.3, packet version 6 with
  *       SHA2-512 fingerprints and salted hashes). Defer condition: v6
  *       is not yet emitted by GnuPG 2.4 LTS or by Sequoia stable, so

package/lib/mail-crypto-smime.js

@@ -64,38 +64,22 @@
  *     packet decoder shipped in `b.mail.crypto.pgp` — but with
  *     dramatically more shape variation across implementations.
  *
- *     Defer condition: no operator demand has surfaced for in-process
- *     S/MIME verification; operators receiving S/MIME-signed mail
- *     today either (a) trust the gateway's authentication-results
- *     header (composed via `b.mail.authResults`) and treat S/MIME as
- *     a downstream concern, or (b) run S/MIME verification in their
- *     own consumer code with a vetted CMS library. Reopen this
- *     surface when ALL of the following hold:
- *       1. At least one operator surfaces concrete demand for
- *          in-process S/MIME verify (use case + sample message
- *          shape).
- *       2. A vendorable ASN.1 BER/DER decoder lands in `lib/vendor/`
- *          under the framework's vendoring discipline (MANIFEST.json
- *          + sha256 pin + no transitive deps), OR an operator
- *          provides a tested decoder we can fold in directly.
- *       3. RFC 8551 §2.5 + RFC 5652 §11 conformance test vectors are
- *          available to drive the implementation. (NIST PKITS-style
- *          test vectors exist for X.509 chain validation; equivalent
- *          coverage for CMS SignedData is sparser.)
+ *     Reopen condition: the in-tree CMS substrate (`b.cms`) shipped
+ *     in v0.10.13 — the RFC 5652 SignedData encode + decode + PQC
+ *     signer dispatch is now available. The S/MIME wire layer
+ *     (multipart/signed framing, micalg mapping, base64 DER body,
+ *     Content-Type parameters) lights up on top of `b.cms` in
+ *     v0.10.14 alongside `b.mail.crypto.pgp` encrypt + decrypt + WKD
+ *     discovery, so operators get the full mail-crypto surface in a
+ *     single release rather than half of each side.
  *
- *     Cheap escape hatch: operators wire `node-forge` / `pkijs` /
- *     openssl(1) (via child_process) in their own consumer code,
- *     extract the signed payload + signature components, and compose
- *     with `b.mail.authResults` to record the verification outcome
- *     for downstream policy. The S/MIME wire-format constants
- *     (Content-Type protocol parameter, micalg mapping, base64 DER
- *     framing) are stable and operator-side code interoperates with
- *     any inbound S/MIME-signed message regardless of this module's
- *     state.
- *
- *     v2 reopen tag: the next minor (v0.9.60+) once the conditions
- *     above are met. The deferred surface lights up sign+verify
- *     together so operators never see a half-implementation.
+ *     Cheap escape hatch (pre-v0.10.14): operators wanting in-process
+ *     S/MIME today compose `b.cms.encodeSignedData` directly with a
+ *     hand-written multipart/signed wrapper. The MIME framing is two
+ *     parts (the signed content + `application/pkcs7-signature` body
+ *     carrying the base64-encoded CMS DER from `b.cms`); the helper
+ *     in v0.10.14 collapses that into `b.mail.crypto.smime.sign({ ... })`
+ *     so the next-release path is additive, not a rewrite.
  *
  * RFC citations:
  *   - RFC 8551 (S/MIME 4.0 Message Specification, April 2019;

package/lib/metrics.js

@@ -783,23 +783,66 @@ function _resetForTest() {
  *   path:        string,    // absolute path to write the snapshot
  *   intervalMs:  number,    // milliseconds between flushes (>=100)
  *   fields:      Function,  // returns an object — written as JSON
+ *   registry:    object,    // optional `b.metrics.create()` handle — adds a
+ *                           //   structured `metrics` field carrying every
+ *                           //   registered counter / gauge / histogram (incl.
+ *                           //   bucket counts) so sidecar readers compose
+ *                           //   histogram_quantile() against the snapshot
  *   fileMode:    number,    // POSIX mode (default 0o640 — owner rw, group r)
  *
  * @example
+ *   var registry = b.metrics.create();
+ *   var latency  = registry.histogram("op_latency_seconds", { buckets: [0.01, 0.1, 1] });
  *   var stop = b.metrics.snapshot.startWriter({
  *     path:       "/run/blamejs/metrics.json",
  *     intervalMs: 5000,
- *     fields:     function () {
- *       return {
- *         uptimeMs:    process.uptime() * 1000,
- *         queueDepth:  myQueue.size,
- *         lastSyncAt:  lastSyncAt,
- *       };
- *     },
+ *     registry:   registry,
+ *     fields:     function () { return { uptimeMs: process.uptime() * 1000 }; },
  *   });
- *   // ... on SIGTERM:
+ *   // Snapshot file: { writtenAt, fields, metrics: { op_latency_seconds: { type, buckets, observations: [{ labels, counts, sum, count }] } } }
  *   stop();
  */
+function _serializeRegistry(registry) {
+  // Walk every registered metric in the registry.metrics Map and emit
+  // a JSON-friendly structured shape. Histograms get full buckets +
+  // bucket counts so downstream consumers compose
+  // `histogram_quantile()` against the snapshot without a separate
+  // exposition endpoint (issue #100).
+  var out = {};
+  var names = registry.metrics instanceof Map
+    ? Array.from(registry.metrics.keys()).sort()
+    : Object.keys(registry.metrics).sort();
+  for (var i = 0; i < names.length; i += 1) {
+    var name = names[i];
+    var m = registry.metrics instanceof Map ? registry.metrics.get(name) : registry.metrics[name];
+    if (!m) continue;
+    var entry = { type: m.type, help: m.help || "", labelNames: m.labelNames || [] };
+    if (m.type === "histogram") {
+      entry.buckets = m.buckets.slice();
+      entry.observations = [];
+      var hKeys = m.values instanceof Map ? Array.from(m.values.keys()).sort() : Object.keys(m.values).sort();
+      for (var hi = 0; hi < hKeys.length; hi += 1) {
+        var hv = m.values instanceof Map ? m.values.get(hKeys[hi]) : m.values[hKeys[hi]];
+        entry.observations.push({
+          labels: hv.labels,
+          counts: hv.counts.slice(),
+          sum:    hv.sum,
+          count:  hv.count,
+        });
+      }
+    } else {
+      entry.observations = [];
+      var vKeys = m.values instanceof Map ? Array.from(m.values.keys()).sort() : Object.keys(m.values).sort();
+      for (var vi = 0; vi < vKeys.length; vi += 1) {
+        var vv = m.values instanceof Map ? m.values.get(vKeys[vi]) : m.values[vKeys[vi]];
+        entry.observations.push({ labels: vv.labels, value: vv.value });
+      }
+    }
+    out[name] = entry;
+  }
+  return out;
+}
+
 function snapshotStartWriter(opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(opts.path,
@@ -813,8 +856,21 @@ function snapshotStartWriter(opts) {
     throw new MetricsError("metrics-snapshot/bad-fields",
       "metrics.snapshot.startWriter: opts.fields must be a function returning the snapshot object");
   }
+  // Issue #100 — optional `registry` handle pulls every registered
+  // metric into a structured `metrics` field in the JSON snapshot:
+  // counters / gauges as `{ value }` per label set, histograms as
+  // `{ buckets, observations }` with bucket counts + sum + count.
+  // Sidecar readers compose `histogram_quantile()` against the
+  // snapshot file without running a separate /metrics endpoint.
+  if (opts.registry !== undefined && opts.registry !== null &&
+      (typeof opts.registry !== "object" || typeof opts.registry.metrics !== "object")) {
+    throw new MetricsError("metrics-snapshot/bad-registry",
+      "metrics.snapshot.startWriter: opts.registry must be a metrics registry " +
+      "(from b.metrics.create()) or omitted");
+  }
   var p          = opts.path;
   var fieldsFn   = opts.fields;
+  var registry   = opts.registry || null;
   var intervalMs = opts.intervalMs;
   // CRYPTO-6 — file mode for the atomic write. Default 0o640
   // (owner rw, group r, world none). Operators with a sidecar
@@ -844,6 +900,10 @@ function snapshotStartWriter(opts) {
       writtenAt: new Date().toISOString(),
       fields:    snap,
     };
+    if (registry) {
+      try { payload.metrics = _serializeRegistry(registry); }
+      catch (e2) { log("snapshot.metrics serialize failed: " + ((e2 && e2.message) || String(e2))); }
+    }
     try {
       // CRYPTO-6 — default 0o640 (owner rw, group r, world none) so
       // operator-supplied snapshot fields aren't world-readable on a

package/lib/stream-throttle.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * @module     b.streamThrottle
+ * @nav        Networking
+ * @title      Stream Throttle
+ * @order      130
+ * @slug       stream-throttle
+ *
+ * @card
+ *   Shared token-bucket bandwidth limiter for `node:stream` pipelines.
+ *   Caps aggregate bytes-per-second across N concurrent streams that
+ *   draw from the same bucket — the missing primitive between per-
+ *   request rate-limit and per-process worker pool.
+ *
+ * @intro
+ *   `b.streamThrottle.create({ bytesPerSec, burstBytes })` returns a
+ *   token bucket that hands out `transform()` instances; every
+ *   transform consumes from the same shared bucket. Operators wiring
+ *   bulk-transfer daemons (object-storage fan-out, log shippers,
+ *   replication readers) compose a single throttle and apply it
+ *   to every concurrent transfer — N parallel transforms share the
+ *   `bytesPerSec` budget rather than each getting their own.
+ *
+ *   Algorithm:
+ *
+ *   - Bucket holds up to `burstBytes` tokens (default = `bytesPerSec`,
+ *     i.e. one second of headroom). Tokens refill at `bytesPerSec`
+ *     bytes per second, capped at `burstBytes`. Refill is computed
+ *     lazily on every chunk write so there is no per-throttle timer.
+ *   - On each chunk, the transform asks the bucket for the chunk's
+ *     byte count. If enough tokens are available, the chunk passes
+ *     immediately and the tokens are decremented. If not, the
+ *     transform sleeps for `ceil((bytes - tokens) / bytesPerSec * 1000)`
+ *     ms and then retries — the chunk is forwarded as-is once the
+ *     debt is paid.
+ *
+ *   Composes with:
+ *
+ *   - `node:stream.pipeline(src, throttle.transform(), dst)` — the
+ *     transform is a regular `stream.Transform`, so backpressure
+ *     flows in both directions without operator wiring.
+ *   - `b.appShutdown` — the throttle has no background timer; once
+ *     every transform finishes its `_transform`, the bucket is
+ *     garbage-collected with the surrounding daemon.
+ *
+ *   Refusal posture:
+ *
+ *   - `bytesPerSec <= 0` / non-finite throws `stream-throttle/bad-rate`.
+ *   - `burstBytes < bytesPerSec` throws `stream-throttle/bad-burst`
+ *     (smaller burst than refill rate would stall on a single full-rate
+ *     chunk forever).
+ *   - Chunks larger than `burstBytes` would never fit in the bucket;
+ *     `transform({ allowOversize: true })` opts into splitting them
+ *     across multiple wait windows. Default refuses with a typed error
+ *     so operators catch this at config time.
+ *
+ *   RFC + reference:
+ *
+ *   - [RFC 2697 srTCM](https://www.rfc-editor.org/rfc/rfc2697.html) — single-rate
+ *     three-color marker, the canonical token-bucket shape this primitive
+ *     implements (single PIR + CBS, no committed burst tier).
+ *   - [Wikipedia: Token bucket](https://en.wikipedia.org/wiki/Token_bucket).
+ */
+
+var nodeStream = require("node:stream");
+var { defineClass } = require("./framework-error");
+
+var StreamThrottleError = defineClass("StreamThrottleError", { alwaysPermanent: true });
+
+// Milliseconds-per-second conversion factor — used for rate arithmetic
+// (bytes/sec ↔ wait-ms). This is a unit-conversion constant, not a
+// memory cap or protocol-byte literal; the framework's C.TIME / C.BYTES
+// helpers don't apply.
+var MS_PER_SECOND = 1000;                                                                             // allow:raw-byte-literal — ms/sec unit conversion // allow:raw-time-literal — ms/sec unit conversion
+var NS_PER_MS     = 1e6;                                                                              // allow:raw-byte-literal — ns/ms unit conversion
+var MS_PER_SECOND_HRTIME = 1000;                                                                      // allow:raw-byte-literal — hrtime seconds→ms // allow:raw-time-literal — hrtime seconds→ms
+
+/**
+ * @primitive b.streamThrottle.create
+ * @signature b.streamThrottle.create(opts)
+ * @since     0.10.13
+ * @status    stable
+ * @related   b.streamThrottle
+ *
+ * Create a shared token bucket. Returns `{ transform(opts?), state() }`.
+ * `transform(tOpts?)` returns a `stream.Transform` that consumes from
+ * the shared bucket; multiple transforms returned from the same
+ * bucket share the rate budget. `state()` returns
+ * `{ bytesPerSec, burstBytes, tokens, lastRefillMs }` for observation.
+ *
+ * Refill resilience: `_refill` clamps elapsed-since-last-refill to
+ * the "empty-to-full" duration (`burstBytes / bytesPerSec` seconds)
+ * so an NTP clock step or VM resume can't credit hours of pent-up
+ * tokens into the bucket in a single call.
+ *
+ * @opts
+ *   bytesPerSec:  number,    // refill rate (bytes per second; required, > 0)
+ *   burstBytes:   number,    // bucket capacity (default = bytesPerSec)
+ *
+ * `transform(tOpts)` opts:
+ *   allowOversize: boolean,  // permit chunks larger than burstBytes (default false)
+ *   maxWaitMs:     number,   // per-chunk wait ceiling — when set, any
+ *                            //   computed wait > maxWaitMs refuses the chunk
+ *                            //   with `stream-throttle/wait-exceeds-max`
+ *                            //   instead of silently pinning the pipeline.
+ *
+ * @example
+ *   var throttle = b.streamThrottle.create({ bytesPerSec: 5 * 1024 * 1024 });
+ *   await new Promise(function (resolve, reject) {
+ *     require("node:stream").pipeline(src, throttle.transform(), dst,
+ *       function (e) { return e ? reject(e) : resolve(); });
+ *   });
+ */
+function create(opts) {
+  opts = opts || {};
+  if (typeof opts.bytesPerSec !== "number" || !isFinite(opts.bytesPerSec) || opts.bytesPerSec <= 0) {
+    throw new StreamThrottleError("stream-throttle/bad-rate",
+      "streamThrottle.create: opts.bytesPerSec must be a finite number > 0, got " + opts.bytesPerSec);
+  }
+  var bytesPerSec = opts.bytesPerSec;
+  var burstBytes  = opts.burstBytes !== undefined ? opts.burstBytes : bytesPerSec;
+  if (typeof burstBytes !== "number" || !isFinite(burstBytes) || burstBytes <= 0) {
+    throw new StreamThrottleError("stream-throttle/bad-burst",
+      "streamThrottle.create: opts.burstBytes must be a finite number > 0, got " + burstBytes);
+  }
+  if (burstBytes < bytesPerSec) {
+    throw new StreamThrottleError("stream-throttle/bad-burst",
+      "streamThrottle.create: opts.burstBytes (" + burstBytes + ") must be >= bytesPerSec (" +
+      bytesPerSec + ") — a smaller burst than refill rate stalls forever on a single full-rate chunk");
+  }
+  var tokens     = burstBytes;
+  var lastRefill = _hrtimeMs();
+
+  // Cap how far elapsed-since-last-refill can stretch in one call.
+  // Without the cap, a system clock jump (NTP step / VM resume / a
+  // process suspended in a debugger) credits the bucket with enough
+  // tokens to drain hours of pent-up backlog in a single chunk —
+  // defeating the rate ceiling for the recovery window. The cap
+  // is `burstBytes / bytesPerSec` seconds — exactly the time it
+  // takes to refill an empty bucket to full at the configured rate
+  // — so legitimate idle periods recover correctly while clock
+  // skew never overshoots.
+  var maxElapsedMs = Math.ceil((burstBytes / bytesPerSec) * MS_PER_SECOND);
+
+  function _refill() {
+    var now      = _hrtimeMs();
+    var elapsed  = now - lastRefill;
+    if (elapsed > maxElapsedMs) elapsed = maxElapsedMs;
+    if (elapsed > 0) {
+      tokens     = Math.min(burstBytes, tokens + (elapsed / MS_PER_SECOND) * bytesPerSec);
+      lastRefill = now;
+    }
+  }
+
+  function _consume(bytes, allowOversize) {
+    if (bytes > burstBytes && !allowOversize) {
+      throw new StreamThrottleError("stream-throttle/oversize-chunk",
+        "chunk of " + bytes + " bytes exceeds burstBytes=" + burstBytes +
+        "; pass transform({ allowOversize: true }) to split across wait windows");
+    }
+    _refill();
+    if (tokens >= bytes) {
+      tokens -= bytes;
+      return 0;
+    }
+    // Bucket has a deficit. Deduct the full chunk's bytes — the bucket
+    // goes negative — and tell the caller to wait for the deficit to
+    // refill. Subsequent _refill() calls re-accumulate from there, so
+    // the next consume sees an accurate budget. A parallel transform
+    // hitting the same bucket while it is negative also waits.
+    var deficitBytes = bytes - tokens;
+    var waitMs       = Math.ceil((deficitBytes / bytesPerSec) * MS_PER_SECOND);
+    tokens -= bytes;
+    return waitMs;
+  }
+
+  function transform(tOpts) {
+    tOpts = tOpts || {};
+    var allowOversize = tOpts.allowOversize === true;
+    // Per-chunk wait ceiling. A misconfigured operator passing
+    // chunkBytes / bytesPerSec ratios that schedule a 10-minute
+    // single-chunk wait would otherwise pin the pipeline silently;
+    // when `maxWaitMs` is set, any computed wait > maxWaitMs refuses
+    // the chunk with `stream-throttle/wait-exceeds-max`. Defaults to
+    // omitted (no ceiling) for back-compat with operators wanting
+    // the historical "wait however long" behavior.
+    var maxWaitMs = tOpts.maxWaitMs;
+    if (maxWaitMs !== undefined &&
+        (typeof maxWaitMs !== "number" || !isFinite(maxWaitMs) || maxWaitMs <= 0)) {
+      throw new StreamThrottleError("stream-throttle/bad-max-wait",
+        "transform: maxWaitMs must be a finite number > 0, got " + maxWaitMs);
+    }
+    return new nodeStream.Transform({
+      transform: function (chunk, _enc, cb) {
+        var buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        var bytes = buf.length;
+        var waitMs;
+        try { waitMs = _consume(bytes, allowOversize); }
+        catch (e) { cb(e); return; }
+        if (maxWaitMs !== undefined && waitMs > maxWaitMs) {
+          cb(new StreamThrottleError("stream-throttle/wait-exceeds-max",
+            "computed wait " + waitMs + "ms exceeds maxWaitMs=" + maxWaitMs +
+            " (chunk=" + bytes + " bytes, rate=" + bytesPerSec + " bytes/s) — " +
+            "reduce chunk size, increase rate, or raise maxWaitMs"));
+          return;
+        }
+        if (waitMs === 0) { cb(null, buf); return; }
+        setTimeout(function () { cb(null, buf); }, waitMs);
+      },
+    });
+  }
+
+  function state() {
+    _refill();
+    return {
+      bytesPerSec: bytesPerSec,
+      burstBytes:  burstBytes,
+      tokens:      tokens,
+      lastRefillMs: lastRefill,
+    };
+  }
+
+  return { transform: transform, state: state };
+}
+
+function _hrtimeMs() {
+  // hrtime returns [s, ns] integer pair; convert to ms float.
+  var t = process.hrtime();
+  return t[0] * MS_PER_SECOND_HRTIME + t[1] / NS_PER_MS;
+}
+
+module.exports = {
+  create:              create,
+  StreamThrottleError: StreamThrottleError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.10.12",
+  "version": "0.10.13",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:c0157c5c-5ef3-45a3-aef2-004727f9fd8c",
+  "serialNumber": "urn:uuid:7f2411e6-1488-4a9f-954b-bef06640070c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-18T06:22:30.244Z",
+    "timestamp": "2026-05-18T20:01:39.367Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.10.12",
+      "bom-ref": "@blamejs/core@0.10.13",
       "type": "library",
       "name": "blamejs",
-      "version": "0.10.12",
+      "version": "0.10.13",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.10.12",
+      "purl": "pkg:npm/%40blamejs/core@0.10.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.10.12",
+      "ref": "@blamejs/core@0.10.13",
       "dependsOn": []
     }
   ]