@blamejs/core 0.10.9 → 0.10.12

package/CHANGELOG.md

@@ -8,6 +8,9 @@ upgrading across more than a few patches at a time.
 
 ## v0.10.x
 
+- 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/).
 - 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/).

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");
@@ -407,6 +413,9 @@ module.exports = {
   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/audit.js

@@ -301,6 +301,7 @@ var FRAMEWORK_NAMESPACES = [
   "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/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 '" +