@blamejs/core 0.10.8 → 0.10.11

package/CHANGELOG.md

@@ -8,6 +8,9 @@ upgrading across more than a few patches at a time.
 
 ## v0.10.x
 
+- 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/).
+- v0.10.9 (2026-05-17) — **Ergonomic helpers bundle (A / B / C / D / E / H).** Six small DX primitives bundled into one release. **(a) `b.safePath.resolve` / `.resolveOrNull` / `.validate`** — path-traversal-safe multi-segment resolve. Refuses absolute / UNC / drive-letter `rel`, NUL bytes, C0 control chars, bidi-override codepoints (CVE-2021-42574 Trojan Source class), URL-encoded + fullwidth + division-slash path separators, Windows reserved device names CON / PRN / AUX / NUL / COM[0-9] / LPT[0-9] on EVERY platform (closes [CVE-2025-27210](https://nvd.nist.gov/vuln/detail/CVE-2025-27210) cross-mount class), trailing-`.`/trailing-space segments under windows-mode, NTFS Alternate Data Stream markers ([CVE-2024-12217](https://nvd.nist.gov/vuln/detail/CVE-2024-12217) class), and `..` segments that escape `base` after lexical resolve. Optional `opts.realpath: true` adds symlink-escape detection via `fs.realpathSync.native`. Every documented failure mode → coded refusal (`safe-path/absolute-rel` / `null-byte` / `bidi` / `win-reserved` / `escapes-base` / etc.); no best-effort path. **(b) `b.bootGates.run([{ name, fn, timeoutMs?, exitCode?, onFail? }], opts?)`** — sequential boot-invariant runner. Each gate runs in order; on first failure: emits `bootgates.failed` audit, runs the gate's `onFail` callback (swallows + audits onFail throws), writes a single-line failure summary via `opts.log`, and calls the operator-supplied `opts.exit(code)`. The default `exit` throws `BootGatesError("bootgates/no-exit-wired")` rather than calling `process.exit` directly (lib/ never terminates the process — the CLI surface owns that wiring). Each gate runs under a 60s default `timeoutMs` budget configurable per-gate; overall budget via `opts.overallTimeoutMs`. **(c) `b.metrics.snapshot.shadowRegistry({ namespace, counters, gauges, info, cardinalityCap?, onCardinalityExceeded? })`** — namespaced shadow registry that mirrors a subset of a primary registry's metrics for export to systems needing isolated views (sidecar / per-tenant scrape endpoint / compliance-tagged subset). Cardinality cap (default 10000 per metric name) closes the [client_golang CVE-2022-21698](https://nvd.nist.gov/vuln/detail/CVE-2022-21698) unbounded-cardinality DoS class; policy is `drop` (default), `audit-only`, or `refuse`. Emits `metrics.shadow.cardinality_dropped` audit (rate-limited to 1/sec per shadow registry). **(d) Per-instance `agent.reloadCerts({ cert, key, ca })` on `b.pqcAgent.create()` returns** — long-running daemons that rotate TLS material via explicit `b.pqcAgent.create()` agents previously needed a process restart; the new instance method tests the new material via `tls.createSecureContext`, swaps `agent.options` atomically, closes idle keep-alive sockets via `agent.destroy()` (in-flight sockets complete naturally), and emits `pqcagent.reloadCerts` audit. Cert/key mismatch surfaces as `pqcagent/reload-mismatch` with the OpenSSL chain; CA bundle parse failures surface as `pqcagent/reload-bad-ca`. **(e) `b.metrics.snapshot.render(snap, { format: "text", groups })`** — operator-readable text format gains an `opts.groups` map that sections the output (`== HTTP ==` / `== Queue ==` / `== TLS ==`); fields not named in any group fall to `== Other ==`. Group ordering preserved per insertion order. Prometheus / OpenMetrics formats unchanged. **(h) ISO-8601 date strings render-eligible in the text format** — timestamps shaped as `2026-05-17T20:00:00.000Z` (length-bounded at 64 chars) now render verbatim in the text format instead of degrading to `[skipped: non-numeric]`; the Prometheus format gets a parallel `<name>_epoch_ms` gauge so downstream alerting can compute durations per OpenMetrics 1.0 §3.4 (Timestamps MUST be float64 Unix-epoch). Non-ISO strings continue to skip in Prometheus (label-value injection defense). **New compliance scaffold:** new namespace `b.bootGates`. New audit namespaces: `bootgates`, `metrics`. **Operator impact:** no breaking changes. `b.bootGates.run` callers MUST supply `opts.exit: process.exit.bind(process)` from their daemon main() if they want the failure path to terminate the process — the default-throw shape exists so lib/-internal callers can't accidentally `process.exit` from inside a primitive. `b.safePath.resolve` is a brand-new primitive; existing code is unaffected. References: [Node.js path.resolve docs](https://nodejs.org/api/path.html#pathresolvepaths) · [CVE-2025-27210 Windows device-name bypass](https://nvd.nist.gov/vuln/detail/CVE-2025-27210) · [CVE-2024-12217 NTFS ADS](https://nvd.nist.gov/vuln/detail/CVE-2024-12217) · [CVE-2021-42574 Trojan Source](https://nvd.nist.gov/vuln/detail/CVE-2021-42574) · [CVE-2022-21698 Prometheus cardinality DoS](https://nvd.nist.gov/vuln/detail/CVE-2022-21698) · [OpenMetrics 1.0 spec](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md) · [CVE-2026-21637 SNI sync-throw](https://nvd.nist.gov/vuln/detail/CVE-2026-21637).
 - v0.10.8 (2026-05-17) — **EU AI Act Art. 50 + AB-853 + CAC implicit label + AIBOM + operator-surfaced DX primitives.** Calendar-bound release ahead of the 2026-08-02 EU AI Act Art. 50 transparency / California SB-942-as-amended-by-AB-853 effective date and the live (2025-09-01) China CAC GB 45438-2025 labeling regime. Three new AI-transparency surfaces + three operator-surfaced DX primitives (issues #91 / #92 / #93). **(a) `b.ai.aiContentDetect.report`** — inbound-asset provenance detector. Operators extract C2PA-COSE envelopes / CAC implicit-label JSON / IPTC PhotoMetadata via their format-specific muxer and feed the artifacts to `report({...})`; the framework verifies signatures, anchors against an operator-pinned trust list, and returns a normalized provenance report for the AB-853 §22757.21 disclosure UI. Trust-list-empty surfaces as an alert rather than silent acceptance. Profile / posture cascade: `ca-ab-853`, `ca-sb-942`, `eu-ai-act-art-50`, `cac-genai-label` pin to `strict` (refuse on signer not on trust list); `nist-ai-600-1`, `iso-42001`, `iso-23894`, `nist-ai-rmf` pin to `balanced`. **(b) `b.contentCredentials.cacImplicitLabel` + `b.contentCredentials.cacImplicitLabelRead`** — China CAC (Cyberspace Administration) "Measures for Labeling AI-Generated Synthetic Content" + mandatory standard GB 45438-2025 implicit metadata emitter and reverse parser. Validates the 18-character Chinese unified social credit code (统一社会信用代码 per GB 32100-2015), `aigcMarker` field, and `contentKind` enum at the config-time tier. Operators co-emit alongside the C2PA-COSE manifest by declaring `cac-genai-label` posture on the existing `b.contentCredentials.build`. **(c) `b.ai.modelManifest.build` / `.sign` / `.verify`** — CycloneDX 1.6 ML-BOM (AI bill of materials) emitter. EU AI Act Art. 11 + Annex IV require technical documentation for high-risk AI systems; CycloneDX 1.6 ML-BOM is the de-facto serialization (and forward-positioned for EU CRA 2027-12-11 — Regulation (EU) 2024/2847 requires SBOM-style documentation for AI components in products with digital elements). Emits `bomFormat: "CycloneDX"` + `specVersion: "1.6"` + `serialNumber` UUIDv4 URN + `metadata.timestamp` + `metadata.tools[]` + `metadata.component` (primary model with `type: "machine-learning-model"`) + `components[]` datasets + `properties[]` hyperparameters (per CycloneDX spec issue #702 EU CRA alignment) + `formulation[]` workflows + `services[]` external model APIs. ML-DSA-87 signature over canonical-JSON-1785 representation; verify path NEVER trusts an embedded "signedBytes" field — defends the CVE-2025-29774 / CVE-2025-29775 xml-crypto-style signature-substitution class. Self-validates required CycloneDX 1.6 fields at emit time. **(d) `b.atomicFile.conflictPath`** — filesystem-portable conflict-suffix path builder (issue #91). `notes.md` → `notes.conflict-2026-05-17T19-30-00Z.md`; Windows-safe (no `:` / `.`), extension-preserving, dotfile-aware, optional `tag` + `suffix` disambiguator for same-second collisions. Composes the existing `b.atomicFile.pathTimestamp`. **(e) `b.promisePool.create`** — bounded-concurrency promise pool (issue #92). The gap between `b.workerPool` (worker-thread CPU-bound work) and `b.queue` (durable cross-process messaging). `run(taskFn)` / `fire(taskFn)` / `drain({ close? })` shape with back-pressure on enqueue, queueLimit refusal, composes with `b.appShutdown` for drain-on-shutdown. No hidden retry — operators compose `b.retry.withRetry` inside the task body when they want it. **(f) `b.sdNotify.send` / `.ready` / `.stopping` / `.reloading` / `.watchdog`** — sd_notify protocol surface for systemd Type=notify daemons (issue #93). Reads `$NOTIFY_SOCKET` via `b.parsers.safeEnv.readVar`, dispatches `READY=1` / `STOPPING=1` / `RELOADING=1` / `WATCHDOG=1` via `systemd-notify(1)` with `execFile` (no shell). No-op (with audit) when `$NOTIFY_SOCKET` is unset (foreground / container / non-systemd init). Compose with `b.appShutdown.create` for the STOPPING signal; compose with a periodic watchdog interval for systemd's auto-restart-on-hang guarantee. **(g) `b.crypto.randomInt` substrate** — exported alongside the v0.10.7 substrate to give the new AIBOM UUID generator a single greppable random-int path. **(h) New compliance postures in `b.contentCredentials` / `b.ai.aiContentDetect` / `b.ai.modelManifest`:** `ca-ab-853`, `ca-sb-942`, `eu-ai-act-art-50`, `eu-ai-act-art-11`, `cac-genai-label`, `nist-ai-600-1`, `nist-ai-rmf`, `iso-42001`, `iso-23894`. **(i) New audit namespaces:** `aibom` (aibom.signed / aibom.verified), `aicontentdetect` (aicontentdetect.report), `sdnotify` (sdnotify.send / sdnotify.send.skipped). **Deferred to v0.10.9:** in-tree IPTC PhotoMetadata reader for `digitalSourceType` field — operators pre-parse with their tool of choice and pass via `opts.ipmd`. **Operator impact:** no breaking changes. Operators already declaring `eu-ai-act-art-50` posture should pin a trust list via the new primitive before turning on default-on detection in production; AB-853 §22757.21 platform-detection obligations are 2027-01-01 effective so there's runway. References: [EU AI Act Regulation (EU) 2024/1689](https://eur-lex.europa.eu/eli/reg/2024/1689) · [California SB-942 + AB-853](https://leginfo.legislature.ca.gov/faces/billNavClient.xhtml?bill_id=202320240SB942) · [CAC GB 45438-2025](http://www.cac.gov.cn/2025-03/14/c_1742700786675936.htm) · [C2PA 2.1 / 2.2 spec](https://c2pa.org/specifications/specifications/2.2/) · [CycloneDX 1.6 ML-BOM](https://cyclonedx.org/docs/1.6/json/) · [OWASP CycloneDX AI/ML-BOM Authoritative Guide](https://owasp.org/www-project-cyclonedx/) · [NIST AI 600-1 Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf) · [ISO/IEC 42001:2023](https://www.iso.org/standard/81230.html) · [systemd-notify(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-notify.html) · [CVE-2025-29774](https://nvd.nist.gov/vuln/detail/CVE-2025-29774) · [CVE-2025-29775](https://nvd.nist.gov/vuln/detail/CVE-2025-29775) · [CVE-2025-32711 EchoLeak](https://nvd.nist.gov/vuln/detail/CVE-2025-32711).
 - v0.10.7 (2026-05-17) — **Mail-stack P3 / P4 hardening sweep.** Twenty-plus refusals + observability additions across the four mail listeners, the DKIM verifier, ARC signer, MIME parser, and the DNS / DSN / List-* guards. No new public primitives; one substrate addition (`b.crypto.randomInt`); two new operator-visible opts on the submission listener. **(a) `b.crypto.randomInt(min, max)`** — substrate wrapper that routes every framework integer draw through one greppable primitive. Migrates the inline `nodeCrypto.randomInt` sites in `b.network.dns` / `b.network.dns.resolver` (DNS query-ID), `b.mail.auth` (DMARC `pct` sampling), and `b.externalDb` (transaction-retry jitter) so the audit trail is uniform and future detectors see one shape. **(b) `b.mail.server.submission.create({ requireDkim, dkimRequireMode })`** — outbound DKIM-required gate per Yahoo / Google 2024 bulk-sender alignment. `requireDkim` defaults `true` under `strict` profile (`false` under `balanced` / `permissive`). `dkimRequireMode` is `"self"` (signer's `d=` must match authenticated identity's domain), `"any"` (any signer present), or `"off"` (no gate). Default `"any"`. Submission listener that doesn't carry a `DKIM-Signature:` header at DATA-end refuses with `5.7.20`. **(c) `b.mail.server.{mx,submission}.create({ allowSmtpUtf8 })`** — single per-listener SMTPUTF8 (RFC 6531) switch threaded end-to-end into `guardSmtpCommand.validate`. Default `false`. Operators that accept EAI envelopes flip to `true` and the toggle reaches every wire-line guard call. **(d) DKIM verifier signature-count cap.** `b.mail.dkim.verify` now refuses (`policy` verdict) rather than silently truncating when a message carries more `DKIM-Signature` headers than `maxSignatures` (default 8). The opt is range-checked at config time against a ceiling of 16; out-of-range throws `dkim/bad-max-signatures`. Closes a verifier-fan-out DoS shape per RFC 6376 §6.1. Emits `dkim.verify.signature_count_cap` audit on the refusal so postmasters see DoS attempts in the authentication-results stream. **(e) MX listener size-overrun + observability.** `MAIL FROM SIZE=` is now reconciled against the actual DATA byte count after dot-stuffing reversal — senders that understate `SIZE=` to probe `maxMessageBytes` get `552 5.3.4` rather than silently accepted, with `mail.server.mx.size_overrun` audit. Refused-recipient list (bounded at 32 per transaction) now surfaces in the `data_accepted` / `delivered` audit metadata. Write-backpressure on every reply attaches a once-per-socket `mail.server.mx.write_backpressure` audit so operators see stalled connections without flooding on every reply. **(f) IMAP refinements.** `APPEND mailbox [flags] [date-time] {literal}` now honors the optional RFC 9051 §6.3.12 date-time argument (parsed into `internalDate` ms-epoch, refused with `BAD` rather than silently falling back to `Date.now()`). `FETCH` / `STORE` outside of Selected state now respond `BAD` (RFC 9051 §6.4.5 / §6.4.6 — protocol-context violation, not policy refusal). `LOGIN` quoted-string args honor `\"` / `\\` escape pairs per the RFC 9051 §5.1 grammar (the prior shape terminated at the first `"`, letting a hostile client smuggle `LOGIN "alice\"@example.com" "pw"` past the username binding). **(g) ARC signer hop-count ceiling.** `b.mail.arc.sign` extracts prior hops with the RFC 8617 §5 50-hop cap; an inbound chain claiming >50 hops or an out-of-range `i=` tag is refused rather than enumerated. **(h) MIME parser charset + observability.** `b.safeMime.parse` now decodes `utf-16` (RFC 2781 §3.3 BOM detection + BE default), `utf-16be`, and `utf-16le` end-to-end — the prior shape advertised `utf-16` / `utf-16be` in the allowlist but only decoded `utf-16le`. `binary` Content-Transfer-Encoding is removed from the default allowlist (RFC 3030 §3 — `binary` requires explicit BINARYMIME negotiation; operators that wire BINARYMIME opt back in via `transferEncodingAllowlist: [..., "binary"]`). Control-character refusal errors now report the BYTE offset (via `Buffer.byteLength` on the JS string prefix) rather than the UTF-16 code-unit index, so audit lines align with wire-level inspection. **(i) DKIM / DMARC / ARC / iPrev / DSN tightening.** `b.guardDsn` splits the RFC 3464 §2.1.1 block separator on literal `\r\n\r\n` only (the prior `\n\s*\n` accepted `\v` / `\f` whitespace as a block boundary, letting a hostile sender bend the per-message vs per-recipient boundary). `b.guardMessageId` now validates id-left + id-right against RFC 5322 §3.2.3 dot-atom-text shape under `strict` profile; `b.guardListId` extends the localhost FQDN exception to `.local` (RFC 6762) and `.lan` (draft-chapin-rfc2606bis). **(j) `b.guardListUnsubscribe` SSRF defense.** HTTPS one-click URIs now refuse IP-literal hosts (v4 + v6), reserved-local hostnames (`localhost` / `localhost.localdomain` / `ip6-localhost` / `ip6-loopback`), and reserved-local TLD suffixes (`.local` / `.lan` / `.internal`). New optional `allowedHosts` opt provides a domain allowlist — when supplied, every HTTPS host (or any ancestor) must be on the list. **(k) `b.mailStore` JMAP objectid bump to 128 bits.** RFC 8474 §1.5.1 — the prior 24-char hex prefix cut entropy to 96 bits; full 32-char hex restores 128 bits. **Operator impact:** Submission listeners on `strict` profile WITHOUT operator-side DKIM signing (`b.mail.dkim.sign` pre-relay) now refuse outbound DATA — operators in this state either wire DKIM signing, opt to `dkimRequireMode: "off"`, or step down to `balanced`. `b.mail.dkim.verify` callers passing `maxSignatures > 16` now throw at config time — clamp via the opt or rely on the framework default. `b.safeMime.parse` callers that legitimately receive `binary` Content-Transfer-Encoding (BINARYMIME-aware downstream pipelines) opt back in via `transferEncodingAllowlist`. `b.guardListUnsubscribe.validate` callers that legitimately rely on IP-literal one-click URIs (test harnesses, internal-network operators) opt in via `allowedHosts: ["10.0.0.0/8"]` style ancestor matches. **Deferred to v0.10.8 / v0.10.12:** per-tenant pepper on `b.mailStore` derived hashes (`from_hash` / `message_id_hash`) ships in v0.10.12 alongside the `b.agent.tenant` adoption refactor; the schema migration is too invasive to fold into this patch. `b.mailStore` forensic-recovery columns (original Content-Transfer-Encoding + charset preserved alongside decoded body) defer to v0.10.8 — the schema change carries its own backwards-compatibility surface. References: [RFC 9051 IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051), [RFC 6376 DKIM §6.1](https://www.rfc-editor.org/rfc/rfc6376#section-6.1), [RFC 6531 SMTPUTF8](https://www.rfc-editor.org/rfc/rfc6531), [RFC 3030 BINARYMIME](https://www.rfc-editor.org/rfc/rfc3030), [RFC 2781 UTF-16 BOM](https://www.rfc-editor.org/rfc/rfc2781), [RFC 1870 SMTP SIZE](https://www.rfc-editor.org/rfc/rfc1870), [RFC 8474 JMAP objectid](https://www.rfc-editor.org/rfc/rfc8474), [RFC 8617 ARC §5](https://www.rfc-editor.org/rfc/rfc8617#section-5), [RFC 3464 DSN §2.1.1](https://www.rfc-editor.org/rfc/rfc3464#section-2.1.1), [RFC 5322 Message Format §3.2.3](https://www.rfc-editor.org/rfc/rfc5322#section-3.2.3), [RFC 6761 Reserved Domain Names](https://www.rfc-editor.org/rfc/rfc6761), [Yahoo / Gmail bulk-sender 2024](https://blog.google/products/gmail/gmail-security-authentication-spam-protection/).
 - v0.10.6 (2026-05-17) — **Vendored-SBOM CycloneDX 1.6 conformance + cosign verification recipe pin.** Build-side + verification-side improvements; no runtime changes. **(a) `scripts/build-vendored-sbom.js` per-component `cpe` field** — every vendored bundle gets a CPE 2.3 string (`cpe:2.3:a:<vendor>:<product>:<version>:*:*:*:*:*:*:*`). CISA / NVD CVE-matching tools (Dependency-Track, OWASP Dependency-Check, Snyk SBOM Monitor) match CVE advisories against components by CPE; the prior emit had no CPE field, so vendored bundles were invisible to operator-side CVE scanners. **(b) Per-component `supplier` block** — `metadata.supplier` (framework-level) was already populated; each vendored bundle now also carries its own `components[].supplier` with the upstream maintainer / org per [SLSA v1.0 provenance requirements](https://slsa.dev/spec/v1.0/provenance) — operators auditing the SBOM see both the framework supplier (blamejs) AND the vendored bundle's upstream supplier (noble-curves, noble-ciphers, etc.) at the component level. **(c) `metadata.lifecycles[].externalReferences[]`** — CycloneDX 1.6 §4.4.2 requires `lifecycles` entries to carry build-provenance references (workflow URL, run ID); the npm-publish workflow now populates these so the SBOM points back at the SLSA-attesting workflow run that produced the tarball. **(d) Sub-component `dependsOn` graph** — when a vendored bundle exposes sub-components (e.g. `noble-ciphers` exports `xchacha20poly1305` + `aes-gcm` as named sub-modules), each sub-component now emits its own SBOM entry with a `dependencies` edge pointing to its parent (CycloneDX 1.6 §4.7). Operators get the full transitive graph instead of just the top-level vendored bundle. **(e) `_licenseFor()` inline-path fix** — the path-resolution branch that handles vendored bundles whose `package.json` is under `lib/vendor/<name>/package.json` now correctly returns the SPDX `license.id` (was returning `null` for that branch, causing CycloneDX-validator warnings). **(f) `SECURITY.md` cosign verification recipe pinned to workflow path + tag-ref** — the operator-side recipe now constrains `cosign verify-blob --certificate-identity-regexp` to the specific workflow file (`.github/workflows/npm-publish.yml`) + tag-ref shape (`refs/tags/v[0-9]+\.[0-9]+\.[0-9]+`), refusing certificates issued for any other workflow or ref class. Also documents `--rekor-url` for operators running on an air-gapped network with a local transparency log + offline TUF root path for `cosign initialize --root <local-root.json>`. **(g) `.github/workflows/npm-publish.yml` recipe comment** synchronized to match the SECURITY.md recipe so operators copy-pasting from either source see identical verification steps. **Operator impact:** SBOM consumers that previously saw vendored bundles as opaque now see CPE-matched components with proper supplier attribution + transitive sub-component graph. The Sigstore-keyless verification recipe is more restrictive (rejects certificates issued for non-`npm-publish.yml` workflows on this repo) — operators already verifying against the prior recipe see the same successful verification with the tighter identity match. References: [CycloneDX 1.6 §4](https://cyclonedx.org/docs/1.6/json/), [CPE 2.3 spec](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7695.pdf), [SLSA v1.0 provenance](https://slsa.dev/spec/v1.0/provenance), [Sigstore cosign verify-blob](https://docs.sigstore.dev/cosign/verifying/verify/), [TUF specification](https://theupdateframework.github.io/specification/latest/).

package/index.js

@@ -57,6 +57,11 @@ var crypto = require("./lib/crypto");
 // remembering separate top-level namespaces. Implementations live in
 // the dedicated lib files; these are thin aliases.
 crypto.hpke = require("./lib/crypto-hpke");
+// Both PQ-HPKE drafts behind one opt-in sub-namespace — see
+// lib/crypto-hpke-pq.js. Operators that need a draft-codepoint
+// shape reach for b.crypto.hpke.pq.connolly / .wg explicitly; the
+// stable b.crypto.hpke.seal stays IANA-codepoint-neutral.
+crypto.hpke.pq = require("./lib/crypto-hpke-pq");
 crypto.httpSig = require("./lib/http-message-signature");
 var tlsExporter = require("./lib/tls-exporter");
 var router = require("./lib/router");
@@ -267,6 +272,7 @@ var time = require("./lib/time");
 var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
 mail.rbl = require("./lib/mail-rbl");
+mail.serverRegistry = require("./lib/mail-server-registry");
 mail.greylist = require("./lib/mail-greylist");
 mail.helo = require("./lib/mail-helo");
 mail.deploy = require("./lib/mail-deploy");
@@ -405,6 +411,11 @@ module.exports = {
   },
   promisePool:      require("./lib/promise-pool"),
   sdNotify:         require("./lib/sd-notify"),
+  safePath:         require("./lib/safe-path"),
+  bootGates:        require("./lib/boot-gates"),
+  // b.jose.jwe.experimental — see lib/jose-jwe-experimental.js for
+  // the codepoint-stability contract.
+  jose:             { jwe: { experimental: require("./lib/jose-jwe-experimental") } },
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/ai-model-manifest.js

@@ -49,7 +49,7 @@ var VALID_DATA_TYPES = Object.freeze({
   "machine-learning-model": true, manifest: true, "operating-system": true,
   patch: true, platform: true, "test-case": true,
 });
-var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;                                // allow:duplicate-regex — ISO-8601 instant shape ships in three primitives (metrics text-render, content-credentials, mail-server-imap APPEND); each is bounded by its own caller and the regex itself is 50 bytes — extracting into a cross-module dep wouldn't carry its weight
 var BOM_REF_RE = /^[A-Za-z0-9._:/+-]{1,256}$/;                                                  // allow:raw-byte-literal — CycloneDX bom-ref string-length cap, not bytes
 
 function _requireString(obj, key, ownerName) {

package/lib/audit.js

@@ -299,6 +299,9 @@ var FRAMEWORK_NAMESPACES = [
   "aibom",            // b.ai.modelManifest (aibom.signed / aibom.verified — CycloneDX 1.6 ML-BOM)
   "aicontentdetect",  // b.ai.aiContentDetect (aicontentdetect.report — AB-853 / EU AI Act Art. 50 inbound provenance)
   "sdnotify",         // b.sdNotify (sdnotify.send / sdnotify.send.skipped — systemd Type=notify)
+  "bootgates",        // b.bootGates (bootgates.passed / bootgates.failed / bootgates.onfail_threw — boot-invariant runner)
+  "metrics",          // b.metrics.snapshot.shadowRegistry (metrics.shadow.cardinality_dropped — namespaced metrics export)
+  "jose",             // b.jose.jwe.experimental (jose.jwe.experimental.encrypt / .decrypt — ML-KEM-JWE pre-IANA)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/auth/dpop.js

@@ -77,7 +77,11 @@ function _b64urlDecode(s) {
   if (typeof s !== "string") {
     throw new AuthError("auth-dpop/bad-base64", "expected base64url string");
   }
-  return bCrypto.fromBase64Url(s);
+  try { return bCrypto.fromBase64Url(s); }
+  catch (_e) {
+    throw new AuthError("auth-dpop/bad-base64",
+      "DPoP segment is not valid base64url");
+  }
 }
 
 // Canonical JWK per RFC 7638 — keys present in lexicographic order,

package/lib/auth/fido-mds3.js

@@ -308,12 +308,28 @@ function _ttlFromNextUpdate(nextUpdateDate) {
 }
 
 // MDS3 nextUpdate per spec section 3.1.7 is "YYYY-MM-DD" (UTC midnight).
+// Round-trip the parsed components through `new Date(utcMs).getUTC*()`
+// and verify each field matches the input — Date.UTC silently
+// normalises impossible calendar dates (`2026-02-31` -> `2026-03-03`),
+// which would let a malformed MDS3 BLOB nextUpdate masquerade as a
+// valid future timestamp and influence the cache-TTL clamp downstream.
 function _parseNextUpdate(s) {
   if (typeof s !== "string") return null;
-  var m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);                                     // allow:raw-byte-literal — ISO-8601 date components
+  var m = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);                                    // allow:raw-byte-literal — ISO-8601 date components
   if (!m) return null;
-  var d = new Date(Date.UTC(parseInt(m[1], 10), parseInt(m[2], 10) - 1, parseInt(m[3], 10)));
-  return isFinite(d.getTime()) ? d : null;
+  var year  = parseInt(m[1], 10);
+  var month = parseInt(m[2], 10) - 1;
+  var day   = parseInt(m[3], 10);
+  if (day < 1 || day > 31 || month < 0 || month > 11) return null;
+  var utcMs = Date.UTC(year, month, day);
+  if (!isFinite(utcMs)) return null;
+  var d = new Date(utcMs);
+  if (d.getUTCFullYear() !== year ||
+      d.getUTCMonth()    !== month ||
+      d.getUTCDate()     !== day) {
+    return null;
+  }
+  return d;
 }
 
 // Internal verify-blob helper used by both fetch (live HTTP) and the

package/lib/auth/jwt.js

@@ -91,7 +91,8 @@ function _b64urlEncode(buf) { return bCrypto.toBase64Url(buf); }
 
 function _b64urlDecode(s) {
   if (typeof s !== "string") throw new AuthError("auth-jwt/malformed", "expected base64url string");
-  return bCrypto.fromBase64Url(s);
+  try { return bCrypto.fromBase64Url(s); }
+  catch (_e) { throw new AuthError("auth-jwt/malformed", "JWT segment is not valid base64url"); }
 }
 
 function _toKeyObject(pemOrKey, kind) {

package/lib/auth/oauth.js

@@ -245,7 +245,8 @@ function _b64urlEncode(buf) { return bCrypto.toBase64Url(buf); }
 
 function _b64urlDecode(s) {
   if (typeof s !== "string") throw new OAuthError("auth-oauth/bad-base64", "expected base64url string");
-  return bCrypto.fromBase64Url(s);
+  try { return bCrypto.fromBase64Url(s); }
+  catch (_e) { throw new OAuthError("auth-oauth/bad-base64", "segment is not valid base64url"); }
 }
 
 function _generateRandomToken(bytes) {
@@ -274,11 +275,22 @@ function _validateUrl(url, allowHttp, label) {
   var isLocalhostHttp = false;
   try {
     var parsed = new URL(url);                                                                  // allow:raw-new-url — RFC 9700 §4.1.1 localhost-exception lookup; safeUrl re-validates below for non-localhost paths
+    // Strip trailing root-zone dot before the localhost compare.
+    // RFC 1034 §3.1 — `localhost.` resolves identically to `localhost`;
+    // without the strip, an attacker who registers `evil.com` as a
+    // public OAuth issuer and supplies `http://localhost./...` (with
+    // a trailing dot) slips past the equality check on a name that
+    // some DNS configurations resolve to a different target than the
+    // operator expects.
+    var rawHost = parsed.hostname || "";
+    while (rawHost.length > 0 && rawHost.charAt(rawHost.length - 1) === ".") {
+      rawHost = rawHost.slice(0, -1);
+    }
     if (parsed.protocol === "http:" &&
-        (parsed.hostname === "localhost" ||
-         parsed.hostname === "127.0.0.1" ||
-         parsed.hostname === "[::1]" ||
-         parsed.hostname === "::1")) {
+        (rawHost === "localhost" ||
+         rawHost === "127.0.0.1" ||
+         rawHost === "[::1]" ||
+         rawHost === "::1")) {
       isLocalhostHttp = true;
     }
   } catch (_e) { /* malformed; let safeUrl surface the canonical error below */ }

package/lib/auth/status-list.js

@@ -69,7 +69,13 @@ var MAX_LIST_BYTES = C.BYTES.mib(1);
 
 function _b64url(buf) { return bCrypto.toBase64Url(buf); }
 
-function _fromB64url(s) { return bCrypto.fromBase64Url(s); }
+function _fromB64url(s) {
+  try { return bCrypto.fromBase64Url(s); }
+  catch (_e) {
+    throw new StatusListError("status-list/bad-base64",
+      "status-list segment is not valid base64url");
+  }
+}
 
 function _validateBits(bits) {
   if (!SUPPORTED_BIT_SIZES[bits]) {

package/lib/boot-gates.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * @module b.bootGates
+ * @nav    Process
+ * @title  Boot Gates
+ *
+ * @intro
+ *   Sequential gate runner for boot-time invariants — vault unseal,
+ *   KEM key load, TLS material presence, DB schema migration, etc.
+ *   Each gate is `{ name, fn, timeoutMs?, exitCode?, onFail? }`; the
+ *   runner walks them in order and on FIRST failure:
+ *
+ *     1. emits `bootgates.failed { name, error, durationMs }` audit,
+ *     2. runs `onFail(err)` if provided (await async; swallows
+ *        throws + emits a separate `bootgates.onfail_threw` audit),
+ *     3. writes a single-line failure summary to stderr,
+ *     4. calls `process.exit(gate.exitCode || 1)`.
+ *
+ *   On success: emits `bootgates.passed { name, durationMs }` and
+ *   proceeds. Returns `{ passed, totalMs }` when EVERY gate passes.
+ *
+ *   Replaces the open-coded boot sequence operators write per-process
+ *   (try / log / process.exit) with one greppable primitive that
+ *   composes audit observability and gate-specific timeouts.
+ *
+ * @card
+ *   Sequential boot-invariant runner — gate, audit, exit with the right exit code. The thing every daemon main() reaches for.
+ */
+
+var C = require("./constants");
+var audit = require("./audit");
+var safeAsync = require("./safe-async");
+var { defineClass } = require("./framework-error");
+
+var BootGatesError = defineClass("BootGatesError", { alwaysPermanent: true });
+
+var DEFAULT_GATE_TIMEOUT_MS = C.TIME.seconds(60);
+var DEFAULT_EXIT_CODE = 1;
+
+/**
+ * @primitive b.bootGates.run
+ * @signature b.bootGates.run(gates, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.appShutdown.create, b.audit.safeEmit
+ *
+ * Walk `gates` in order, awaiting each `fn`. First failure stops the
+ * sequence and (after `onFail` + audit + stderr) calls
+ * `process.exit(gate.exitCode || opts.exitCode || 1)`. Returns
+ * `{ passed: string[], totalMs: number }` on full success.
+ *
+ * @opts
+ *   exitCode:        number,           // default 1 — overall fall-through
+ *   log:             function,         // default console.error.bind(console)
+ *   exit:            function,         // test seam; default process.exit
+ *   overallTimeoutMs: number,          // cap across the full sequence
+ *
+ * @example
+ *   await b.bootGates.run([
+ *     { name: "vault.unseal",       fn: async function () { await b.vault.unseal(); } },
+ *     { name: "tls.material",       fn: async function () { await loadTls(); } },
+ *     { name: "db.schemaMigration", fn: async function () { await migrate(); },
+ *       onFail: async function () { await db.close(); } },
+ *   ]);
+ */
+async function run(gates, opts) {
+  opts = opts || {};
+  if (!Array.isArray(gates) || gates.length === 0) {
+    throw new BootGatesError("bootgates/bad-input",
+      "b.bootGates.run: gates must be a non-empty array");
+  }
+  var log = typeof opts.log === "function" ? opts.log : function (msg) {
+    process.stderr.write(msg + "\n");
+  };
+  // Default exit handler invokes process.exit on the platform — guarded
+  // behind the opt because lib/ code is forbidden from calling
+  // process.exit directly (codebase-patterns rule "no process.exit() in
+  // lib/ (CLI surface only)"); the indirection routes through an opts-
+  // supplied function so test code substitutes a capture, and the CLI
+  // (bin/blamejs.js) is the one that wires the real exit call. When
+  // opts.exit isn't supplied, the boot-gate failure path bubbles a
+  // throw rather than terminating the process — operators that wire
+  // bootGates from their daemon main() pass `exit: process.exit.bind(process)`.
+  var exit = typeof opts.exit === "function" ? opts.exit : function (code) {
+    var e = new BootGatesError("bootgates/no-exit-wired",
+      "b.bootGates.run: gate failed (exitCode=" + code + ") but no opts.exit handler was supplied; " +
+      "operators wire opts.exit to process.exit.bind(process) in their daemon main()");
+    e.exitCode = code;
+    throw e;
+  };
+  var overallTimeoutMs = opts.overallTimeoutMs;
+  var t0 = Date.now();
+  var passed = [];
+
+  for (var i = 0; i < gates.length; i += 1) {
+    var gate = gates[i];
+    if (!gate || typeof gate.name !== "string" || gate.name.length === 0 ||
+        typeof gate.fn !== "function") {
+      throw new BootGatesError("bootgates/bad-gate",
+        "b.bootGates.run: gates[" + i + "] must be { name: string, fn: function }");
+    }
+    var timeoutMs = gate.timeoutMs || DEFAULT_GATE_TIMEOUT_MS;
+    if (typeof timeoutMs !== "number" || !isFinite(timeoutMs) || timeoutMs < 1) {
+      throw new BootGatesError("bootgates/bad-timeout",
+        "b.bootGates.run: gates[" + i + "].timeoutMs must be a positive finite number");
+    }
+    var gateT0 = Date.now();
+    var failure = null;
+    try {
+      await safeAsync.withTimeout(Promise.resolve().then(gate.fn), timeoutMs,
+        new BootGatesError("bootgates/timeout",
+          "b.bootGates.run: gate '" + gate.name + "' exceeded " + timeoutMs + "ms"));
+    } catch (err) {
+      failure = err;
+    }
+    if (overallTimeoutMs !== undefined &&
+        Date.now() - t0 > overallTimeoutMs && failure === null) {
+      failure = new BootGatesError("bootgates/overall-timeout",
+        "b.bootGates.run: overall budget " + overallTimeoutMs + "ms exceeded after gate '" +
+        gate.name + "'");
+    }
+    var durationMs = Date.now() - gateT0;
+    if (failure !== null) {
+      try {
+        audit.safeEmit({
+          action:   "bootgates.failed",
+          outcome:  "failure",
+          metadata: { name: gate.name, error: (failure && failure.message) || String(failure),
+                      durationMs: durationMs },
+        });
+      } catch (_e) { /* drop-silent */ }
+      if (typeof gate.onFail === "function") {
+        try {
+          await Promise.resolve().then(function () { return gate.onFail(failure); });
+        } catch (oe) {
+          try {
+            audit.safeEmit({
+              action:   "bootgates.onfail_threw",
+              outcome:  "failure",
+              metadata: { name: gate.name, error: (oe && oe.message) || String(oe) },
+            });
+          } catch (_e2) { /* drop-silent */ }
+        }
+      }
+      log("[bootgates] FAILED gate=" + gate.name + " durationMs=" + durationMs +
+          " error=" + ((failure && failure.message) || String(failure)));
+      if (failure && failure.stack) log(failure.stack);
+      var code = gate.exitCode || opts.exitCode || DEFAULT_EXIT_CODE;
+      exit(code);
+      // The test seam swaps `exit` out; in that case we still surface
+      // a synthetic return value so the caller's promise resolves.
+      return { passed: passed, failed: gate.name, exitCode: code, totalMs: Date.now() - t0 };
+    }
+    try {
+      audit.safeEmit({
+        action:   "bootgates.passed",
+        outcome:  "success",
+        metadata: { name: gate.name, durationMs: durationMs },
+      });
+    } catch (_e3) { /* drop-silent */ }
+    if (typeof opts.onPassed === "function") {
+      try { opts.onPassed({ name: gate.name, durationMs: durationMs }); }
+      catch (_e4) { /* drop-silent */ }
+    }
+    passed.push(gate.name);
+  }
+
+  return { passed: passed, totalMs: Date.now() - t0 };
+}
+
+module.exports = {
+  run:            run,
+  BootGatesError: BootGatesError,
+};

package/lib/crypto-hpke-pq.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * @module     b.crypto.hpke.pq
+ * @nav        Crypto
+ * @title      HPKE-PQ (experimental)
+ * @slug       crypto-hpke-pq
+ *
+ * @intro
+ *   Post-quantum HPKE variants under explicit opt-in. The IETF HPKE-WG
+ *   has two active drafts proposing ML-KEM as a KEM for RFC 9180:
+ *
+ *   - **`b.crypto.hpke.pq.connolly`** — draft-connolly-cfrg-hpke-mlkem-04
+ *     (individual draft; carries codepoint allocations today).
+ *   - **`b.crypto.hpke.pq.wg`** — draft-ietf-hpke-pq-03 (WG-adopted; the
+ *     more authoritative track but codepoints may still move before
+ *     IANA registration).
+ *
+ *   The framework ships BOTH behind opt-in namespaces rather than
+ *   picking a single draft prematurely. Each wrapper binds a draft-
+ *   distinguishing label into the RFC 9180 §5.1 `info` parameter so
+ *   an envelope sealed under one draft CANNOT be opened by the other
+ *   — the cross-draft substitution attack the IANA codepoint
+ *   normally prevents is enforced by the info-label binding.
+ *
+ *   Both wrappers compose the existing `b.crypto.hpke.seal` / `.open`
+ *   path (ML-KEM-1024 KEM + HKDF-SHA3-512 KDF + ChaCha20-Poly1305 AEAD
+ *   per framework PQC-first policy). Operators wanting to migrate to
+ *   the final IANA-registered codepoints (when they appear) call the
+ *   stable `b.crypto.hpke.seal` directly — the experimental wrappers
+ *   exist for operators integrating against systems that speak one of
+ *   the active drafts today.
+ *
+ * @card
+ *   Both HPKE-PQ drafts (connolly + ietf-hpke-pq) behind opt-in namespaces. Cross-draft substitution refused via info-label binding.
+ */
+
+var hpke = require("./crypto-hpke");
+
+// Draft-distinguishing labels. These prepend the operator's `info`
+// parameter so the RFC 9180 §5.1 suite_id binding catches any cross-
+// draft substitution attempt. The label is part of the AEAD AAD by
+// construction — an envelope sealed under `connolly-04` cannot be
+// opened by `wg-03` because the derived AEAD key diverges.
+var CONNOLLY_LABEL = "draft-connolly-cfrg-hpke-mlkem-04";
+var WG_LABEL       = "draft-ietf-hpke-pq-03";
+
+function _prependLabel(label, info) {
+  if (info === undefined || info === null) return label;
+  var infoBytes = Buffer.isBuffer(info) ? info : Buffer.from(String(info), "utf8");
+  // Treat empty info the same as omitted — RFC 9180's `info`
+  // parameter is bytes-or-absent; an empty string and `undefined`
+  // produce the same key schedule under the underlying HPKE. The
+  // wrapper MUST preserve that equivalence so a seal({...}) (no
+  // info) round-trips with an open({ info: "" }) (and vice versa)
+  // without false AEAD-tag failures.
+  if (infoBytes.length === 0) return label;
+  return Buffer.concat([Buffer.from(label + "/", "utf8"), infoBytes]);
+}
+
+function _wrappedSeal(label, opts) {
+  opts = opts || {};
+  var bound = Object.assign({}, opts, { info: _prependLabel(label, opts.info) });
+  return hpke.seal(bound);
+}
+
+function _wrappedOpen(label, opts) {
+  opts = opts || {};
+  var bound = Object.assign({}, opts, { info: _prependLabel(label, opts.info) });
+  return hpke.open(bound);
+}
+
+/**
+ * @primitive b.crypto.hpke.pq.connolly.seal
+ * @signature b.crypto.hpke.pq.connolly.seal(opts)
+ * @since     0.10.10
+ * @status    experimental
+ * @related   b.crypto.hpke.pq.wg.seal, b.crypto.hpke.pq.connolly.open
+ *
+ * Seal a payload under draft-connolly-cfrg-hpke-mlkem-04 codepoints.
+ * Returns `{ enc, ciphertext }`; the framework's existing
+ * `b.crypto.hpke.seal` semantics apply (ML-KEM-1024 + HKDF-SHA3-512 +
+ * ChaCha20-Poly1305 per project policy). Opens ONLY via
+ * `b.crypto.hpke.pq.connolly.open` — cross-draft substitution into
+ * `b.crypto.hpke.pq.wg.open` refuses by construction.
+ *
+ * @opts
+ *   recipientPubKey: string,        // ML-KEM-1024 PEM
+ *   plaintext:       Buffer|string,
+ *   info:            Buffer|string, // application context
+ *   aad:             Buffer|string, // additional authenticated data
+ *
+ * @example
+ *   var pair   = b.crypto.hpke.generateKeyPair();
+ *   var sealed = b.crypto.hpke.pq.connolly.seal({
+ *     recipientPubKey: pair.publicKey,
+ *     plaintext:       "hello",
+ *     info:            "app/topic",
+ *   });
+ */
+function connollySeal(opts) { return _wrappedSeal(CONNOLLY_LABEL, opts); }
+
+/**
+ * @primitive b.crypto.hpke.pq.connolly.open
+ * @signature b.crypto.hpke.pq.connolly.open(opts)
+ * @since     0.10.10
+ * @status    experimental
+ * @related   b.crypto.hpke.pq.connolly.seal
+ *
+ * Open a draft-connolly-cfrg-hpke-mlkem-04 envelope produced by
+ * `connolly.seal`. Refuses envelopes sealed under `wg.seal` (the
+ * info-label binding catches cross-draft substitution).
+ *
+ * @opts
+ *   privateKey:  string,         // ML-KEM-1024 PEM
+ *   enc:         Buffer,
+ *   ciphertext:  Buffer,
+ *   info:        Buffer|string,
+ *   aad:         Buffer|string,
+ *
+ * @example
+ *   var pt = b.crypto.hpke.pq.connolly.open({
+ *     privateKey: pair.privateKey, enc: sealed.enc,
+ *     ciphertext: sealed.ciphertext, info: "app/topic",
+ *   });
+ */
+function connollyOpen(opts) { return _wrappedOpen(CONNOLLY_LABEL, opts); }
+
+/**
+ * @primitive b.crypto.hpke.pq.wg.seal
+ * @signature b.crypto.hpke.pq.wg.seal(opts)
+ * @since     0.10.10
+ * @status    experimental
+ * @related   b.crypto.hpke.pq.connolly.seal, b.crypto.hpke.pq.wg.open
+ *
+ * Seal under draft-ietf-hpke-pq-03 codepoints (the WG-adopted PQ-HPKE
+ * draft). Otherwise identical contract to `b.crypto.hpke.pq.connolly.seal`.
+ *
+ * @opts
+ *   recipientPubKey: string,        // ML-KEM-1024 PEM
+ *   plaintext:       Buffer|string,
+ *   info:            Buffer|string,
+ *   aad:             Buffer|string,
+ *
+ * @example
+ *   var sealed = b.crypto.hpke.pq.wg.seal({
+ *     recipientPubKey: pair.publicKey,
+ *     plaintext:       "hello",
+ *   });
+ */
+function wgSeal(opts) { return _wrappedSeal(WG_LABEL, opts); }
+
+/**
+ * @primitive b.crypto.hpke.pq.wg.open
+ * @signature b.crypto.hpke.pq.wg.open(opts)
+ * @since     0.10.10
+ * @status    experimental
+ * @related   b.crypto.hpke.pq.wg.seal
+ *
+ * Open a draft-ietf-hpke-pq-03 envelope produced by `wg.seal`.
+ *
+ * @opts
+ *   privateKey:  string,
+ *   enc:         Buffer,
+ *   ciphertext:  Buffer,
+ *   info:        Buffer|string,
+ *   aad:         Buffer|string,
+ *
+ * @example
+ *   var pt = b.crypto.hpke.pq.wg.open({
+ *     privateKey: pair.privateKey, enc: sealed.enc,
+ *     ciphertext: sealed.ciphertext,
+ *   });
+ */
+function wgOpen(opts) { return _wrappedOpen(WG_LABEL, opts); }
+
+module.exports = {
+  connolly: {
+    seal:  connollySeal,
+    open:  connollyOpen,
+    label: CONNOLLY_LABEL,
+  },
+  wg: {
+    seal:  wgSeal,
+    open:  wgOpen,
+    label: WG_LABEL,
+  },
+};

package/lib/crypto.js

@@ -1218,7 +1218,13 @@ function decrypt(ciphertext, privateKeys, opts) {
   if (packed[0] !== C.ENVELOPE_MAGIC) {
     throw new Error("Invalid envelope: unsupported format");
   }
-  return decryptEnvelope(packed, privateKeys);
+  // `opts.raw: true` returns the decrypted Buffer rather than the
+  // utf8-decoded string. Callers carrying binary plaintext (JWE
+  // experimental wrapper, future signed-blob carriers) opt in to keep
+  // arbitrary bytes lossless; default stays utf8-string for backwards
+  // compatibility with the existing API contract.
+  return decryptEnvelope(packed, privateKeys,
+    opts && opts.raw === true ? { raw: true } : undefined);
 }
 
 function decryptEnvelope(packed, privateKeys, internalOpts) {
@@ -1283,9 +1289,11 @@ function decryptEnvelope(packed, privateKeys, internalOpts) {
   // dispatched on. A tampered header (algorithm-substitution attack)
   // surfaces here as a Poly1305 tag verification failure.
   var headerAad = packed.subarray(0, 4);                                          // allow:raw-byte-literal — envelope-header byte slice
-  return Buffer.from(
+  var plainBuf = Buffer.from(
     xchacha20poly1305(symmetricKey, nonce, headerAad).decrypt(packed.subarray(pos))
-  ).toString("utf8");
+  );
+  if (internalOpts && internalOpts.raw === true) return plainBuf;
+  return plainBuf.toString("utf8");
 }
 
 // ---- Symmetric buffer encrypt/decrypt (for storage) ----

package/lib/guard-list-id.js

@@ -230,7 +230,12 @@ function validate(headerValue, opts) {
   // `lan` (IETF draft-chapin-rfc2606bis). All three are non-routable
   // single-network labels and the FQDN floor doesn't apply.
   var lastLabel = parts[parts.length - 1].toLowerCase();
-  var isLocalScopeTld = lastLabel === "localhost" || lastLabel === "local" || lastLabel === "lan";
+  // List-Id (RFC 2919) is a dot-atom-text token NOT a wire-format
+  // hostname; the value goes through dot-atom-text validation upstream
+  // so a `localhost.` label-suffix is already refused at the segment-
+  // shape level (an empty trailing segment fails the dot-atom-text
+  // grammar). No trailing-dot bypass surface here.
+  var isLocalScopeTld = lastLabel === "localhost" || lastLabel === "local" || lastLabel === "lan"; // allow:hostname-compare-trailing-dot — see comment above; List-Id parts already split on `.` so trailing-dot label is empty and refused upstream
   if (caps.requireFqdn) {
     if (parts.length < 3 && !isLocalScopeTld) {                                                          // allow:raw-byte-literal — FQDN requires ≥ 3 labels for non-local-scope namespace
       return _refuse("list-id has < 3 labels for non-local-scope namespace (FQDN required under '" +