@blamejs/core 0.17.24 → 0.18.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.18.x
+
+- v0.18.0 (2026-07-26) — **The mTLS CA engine moves to the zero-dependency @blamejs/pki toolkit and issues post-quantum ML-DSA-87 certificates by default; the @peculiar/x509 + pkijs bundle is removed.** b.mtlsCa's default certificate engine is rebuilt on the vendored, zero-runtime-dependency @blamejs/pki toolkit, replacing the @peculiar/x509 + pkijs meta-bundle (which is removed entirely). CA and client certificates are now issued under ML-DSA-87 (FIPS 204) by default: node:tls verifies ML-DSA certificate chains and the CertificateVerify signature on the supported Node LTS (OpenSSL 3.5), so a post-quantum client certificate completes a real mutual-auth handshake -- not just issuance. Operators whose mTLS peers are not yet on OpenSSL 3.5 pass b.mtlsCa.create({ algorithm: "ECDSA-P384-SHA384" }) for a universally-interoperable classical CA -- the pin covers both the CA and every leaf it issues, and never changes the default other CAs use; SLH-DSA is intentionally not offered for TLS. A PKCS#12 export from the PQC default carries a PBMAC1 integrity MAC (RFC 9579); a classical-bridge export uses the traditional RFC 7292 MacData so a pre-OpenSSL-3.5 peer -- the reason to choose the bridge -- can still verify it. Alongside the engine, this release closes a batch of primitive-hardening issues and adds a public PKCE generator; the vendor-currency gate now hard-fails a stale or unverifiable @blamejs/pki so the vendored copy can never lag the latest published release. **Added:** *b.auth.oauth.generatePkce -- a public PKCE (RFC 7636) generator* — b.auth.oauth.generatePkce() returns a { verifier, challenge } pair for a hand-rolled authorization-code flow that does not go through create(). The verifier is 43 base64url characters (32 CSPRNG bytes) and the code_challenge_method is always S256 (the challenge is base64url of SHA-256 over the verifier). · *b.audit.useStore redirect mode* — b.audit.useStore({ record, replaceChain: true }) routes framework audit events directly into a consumer-supplied store, skipping the b.db tamper-evident chain append. A consumer with no initialized b.db can now receive audit events (via record() and emit()/safeEmit()) instead of getting a db-not-initialized error or having events silently dropped. The default remains shadow-replication with the framework chain authoritative. **Changed:** *The default mTLS CA engine is @blamejs/pki with an ML-DSA-87 post-quantum default* — lib/mtls-engine-default.js (b.mtlsCa's default engine) is rebuilt on the vendored zero-dependency @blamejs/pki toolkit. CA and leaf certificates are issued under ML-DSA-87 by default; node:tls completes a real mutual-auth handshake with them on the supported Node LTS. Operators pin the classical bridge with b.mtlsCa.create({ algorithm: "ECDSA-P384-SHA384" }) when a peer predates OpenSSL 3.5; the pin flows into both CA generation and leaf issuance, and is per-call -- it never downgrades the default other CAs use. A pin that disagrees with an already-stored CA is refused (mtls-ca/algorithm-mismatch) -- including a stored EC CA on the wrong curve (a P-256/P-521 CA under the ECDSA-P384 pin, which every ECDSA label would otherwise satisfy by key type alone) -- rather than issuing a leaf the mismatched CA would sign into an unverifiable chain -- rotate to a fresh CA to change algorithms. A per-issuance opts.algorithm that conflicts with the CA's resolved algorithm is likewise refused (mtls-ca/algorithm-conflict) rather than issuing a leaf the pinned CA can't back for its intended peers. When no algorithm is pinned, leaves (and their PKCS#12 MAC tier) follow the stored CA's OWN algorithm under the bundled engine, not the ML-DSA-87 default -- so a deployment that upgrades with an existing classical CA and never sets algorithm keeps issuing classical leaves its established peers can verify. That inference is the bundled engine's alone: a custom b.mtlsCa.create({ engine }) resolves its own leaf algorithm from its own key and is never handed the bundled ECDSA-P384-SHA384 label (which would break a custom engine running a P-256/P-521 CA or its own label set). The classical bridge signs the CA, every leaf, and every CRL with ECDSA-with-SHA-384 (matching its label and the pre-flip release), not the toolkit's EC default of SHA-256. blamejs mtls init --algorithm ECDSA-P384-SHA384 reaches the same bridge from the CLI. Issued certificates carry a structured subject DN: the CA's common name and its OU=CAv{N} generation tag are distinct RDN attributes, and a leaf's subject is exactly CN=<cn> -- so mTLS authorization that maps the certificate CN to an identity reads the bare cn (not a doubled CN), and a policy inspecting the OU=CAv{N} generation attribute finds a real OU. A bare IPv6 SAN now encodes as an iPAddress GeneralName (it was previously mis-encoded as a DNS name). b.mtlsCa's revoke() refuses the removeFromCRL reason (RFC 5280 code 8, a delta-CRL un-revocation directive) -- accepting it would persist a code-8 entry the toolkit rejects in a full CRL, making every later generateCrl() fail and blocking all revocation publishing. A legacy code-8 entry already sitting in a registry (from a pre-release build or a hand-edited store) is dropped when a full CRL is signed -- the serial stays revoked, but the invalid reason no longer blocks publishing every other revocation. PKCS#12 packaging keeps the AES-256-CBC + PBKDF2-HMAC-SHA-512 @ 2,000,000-iteration bag protection; the outer integrity MAC follows the cert tier -- PBMAC1 (RFC 9579) for the PQC default, and the traditional RFC 7292 HMAC MacData for a classical-bridge (ECDSA-P384) export so a peer predating OpenSSL 3.5 can verify the file that PBMAC1 would leave unreadable. · *The vendor-currency gate hard-fails a stale or unverifiable @blamejs/pki* — @blamejs/pki is now always-strict in the vendored-dependency currency check: a stale copy fails the gate (as before) and a registry error while checking it is also a hard failure, rather than staying advisory. The required Vendor currency CI check therefore refuses to pass unless it can prove the vendored @blamejs/pki equals the latest published release, keeping the fast-moving toolkit current on every build. **Removed:** *The vendored @peculiar/x509 + pkijs bundle* — lib/vendor/pki.cjs (the @peculiar/x509 + pkijs + reflect-metadata + ASN.1 meta-bundle) has no remaining consumer after the engine and the test fixtures moved to @blamejs/pki, and is removed along with its MANIFEST, NOTICE, and vendor tooling entries. The framework's PKI now runs entirely on the single zero-dependency @blamejs/pki toolkit. **Fixed:** *b.outbox and b.webhook quote operator-supplied table names* — Operator-supplied table names in b.outbox and b.webhook were emitted unquoted, so a reserved-word or case-sensitive operator table broke the generated SQL. Both now quote operator table names with the same allowReserved parity b.db.from() already provides. On PostgreSQL a bare mixed-case name is folded to lowercase before quoting, so a deployment upgrading from an unquoted-name build keeps resolving to the same folded table PostgreSQL already created (a mixed-case table config does not strand its existing rows in a new case-sensitive table). · *b.selfUpdate.rollback replaces a running Windows executable and honors a maxBytes override* — b.selfUpdate.rollback could not replace a locked/running Windows image (unlike swap) and had no way to raise the 64 MiB copy cap for a large binary. rollback now moves the outgoing file aside via a rename before restoring the backup, and accepts a maxBytes override. If the restore copy then fails (over maxBytes, unreadable source, write error), the moved-aside image is put back over the target so a failed rollback never leaves the target absent -- no next-launch outage; and a backupTo that aliases the reserved quarantine path -- including via a symlink or a symlinked parent dir (resolved with realpath), or by letter case on a case-insensitive volume -- is refused before any file is touched (it would otherwise delete the backup and restore the bad binary). Separately, selfUpdate.poll pairs a detached signature to the asset it actually signs: it recognises both the appended (asset.bin -> asset.bin.sig) and -- when the asset is the SOLE artifact with its extension-stripped stem -- the extension-replacing (asset.bin -> asset.sig) one-signature conventions, and fails closed on an ambiguous sidecar (a lone asset.sig shared by asset.bin and asset.exe) or one whose name is unrelated to the asset rather than mispairing it. **Security:** *b.safeJson.parse no longer leaks a window of input bytes in its error message* — b.safeJson.parse interpolated V8's raw SyntaxError message into the thrown error, which could echo a short window of the parsed input -- including secret bytes -- to any caller that logs the error (CWE-532). It now emits only the stable error code and the numeric position, never the input substring. · *b.redact.redactText strips underscore-joined bearer tokens in free-text messages* — The message-path redactor missed id_token / refresh_token assignments (an underscore-joined name a bare-token word boundary could not match) and vault-sealed / empty-username connection-string credentials, so a credential embedded in a log message could reach a file or SIEM sink verbatim while the structured meta path stripped it. redactText now covers those shapes -- including the JSON / quoted forms ({"refresh_token":"..."}), where the opaque value sits behind a quote the value class had excluded -- matching the meta path. · *b.guardTenantId's reserved-name check is prototype-safe* — The reserved-tenant-id lookup used a bare property access, so a tenant id equal to an Object.prototype member (a prototype key) spuriously matched a reserved name. It now uses an own-property test, and separately refuses the prototype-pollution key names (__proto__ / constructor / prototype) via the framework's shared poisoned-key guard -- a tenant id used to key a plain-object store must never be one of those. · *b.daemon detached start reports a boot-time death instead of unconditional success* — b.daemon.start in detached mode reported success even when the spawned child died at boot, leaving a stale pidfile a later daemon.stop could misread. A one-shot exit handler now reaps the stale pidfile (only when it still records that child's pid) and audits a spawn failure ONLY for a boot death -- an abnormal exit (non-zero code or a terminating signal) within a boot window while the pidfile is still the child's. A clean exit or an operator stop() is no longer mislabeled as a spawn failure. The parent keeps its event loop alive through the boot window (a ref'd timer, cleared the instant the child exits) so even a short-lived launcher that spawns the daemon and returns still observes a boot death -- child.unref() alone would let it exit first and strand the pidfile. A stop() within the window -- from the starting process or a different one (e.g. a `daemon stop` CLI) -- is not misread as a boot death: stop() publishes a short-lived `<pidFile>.stopping` marker (holding the pid it is stopping) that the boot-death handler consults, so no contradictory spawn-failed audit lands before the stop record. The window is tunable via daemon.start({ bootDeathWindowMs }) (default 5s, bounded to the setTimeout 32-bit maximum; 0 opts out for immediate fire-and-forget). The .stopping marker is read through the hardened pid-sidecar reader (symlink-refused, size-capped) and cleared on a fresh start so a stale marker cannot suppress a pid-reused child's boot death. The reap itself atomically claims the sidecar (renaming it aside) before verifying ownership, so a fast operator restart that rewrites the pidfile between the check and the removal can never make the boot-death handler delete the NEW daemon's pidfile. The same discipline covers the asynchronous spawn-error path: a no-pid launch failure throws synchronously before any pidfile is written, so its late 'error' callback no longer deletes a pidfile that a caught-and-retried start has since written.
+
 ## v0.17.x
 
 - v0.17.24 (2026-07-25) — **The coverage-guided fuzz harness pins its `tar` dependency to 7.5.22, clearing a recursion-based denial-of-service advisory in dev-only tooling.** A maintenance update to development tooling with no change to the framework's library or runtime code. The fuzz harness (jazzer.js, under fuzz/) pulled tar transitively at 7.5.19, which is affected by an advisory: uncontrolled recursion in tar's mapHas / filesFilter path lets a crafted entry set trigger an uncatchable stack overflow (fixed upstream in 7.5.21; 7.5.22 is the current release, which caps mapHas recursion at 100 levels and hardens the decompressor teardown). The harness now pins tar to ^7.5.22 via an npm override so the resolved version cannot regress below the patched line. The fuzz harness is not part of the @blamejs/core tarball, so no shipped library or runtime code changes and operators need take no action; the update exists to keep the repository's development dependencies free of known advisories. **Security:** *Fuzz harness pins tar to 7.5.22 (dev-only tooling; not in the published package)* — The coverage-guided fuzz harness (fuzz/, jazzer.js) resolved tar transitively at 7.5.19, affected by an uncontrolled-recursion advisory in the mapHas / filesFilter path that permits an uncatchable stack overflow. An npm override pins tar to ^7.5.22 (the patched line caps recursion depth and hardens decompressor teardown), so the harness lockfile cannot resolve a vulnerable tar. The fuzz harness is not included in the published @blamejs/core package, so this changes only development tooling -- no shipped library or runtime code is affected.

package/NOTICE

@@ -59,19 +59,18 @@ Used for:    WebAuthn / passkey registration + authentication response
              verification (lib/passkey.js, via lib/vendor/simplewebauthn-
              server.cjs).
 --------------------------------------------------------------------------------
-Component:   @peculiar/x509 + pkijs (peculiar-pki bundle)
-Version:     @peculiar/x509 2.0.0, pkijs 3.4.0
-Source:      https://github.com/PeculiarVentures/x509
-             https://github.com/PeculiarVentures/PKI.js
-License:     MIT
-Copyright:   Copyright (c) Peculiar Ventures
-Used for:    Pure-JS mTLS CA. Self-signed CA generation (ECDSA P-384, SHA-384),
-             leaf-cert signing for client certificates, PKCS#12 packaging
-             (PBES2 + AES-256-CBC + PBKDF2-HMAC-SHA-512, 2,000,000 iterations).
-             Wired into b.mtlsCa via lib/mtls-engine-default.js, backed by the
-             bundle lib/vendor/pki.cjs (also includes reflect-metadata,
-             asn1js, pvtsutils, pvutils, and the @peculiar/asn1-* schema
-             chain).
+Component:   @blamejs/pki
+Version:     0.3.25
+Source:      https://github.com/blamejs/pki
+License:     Apache-2.0
+Copyright:   Copyright (c) blamejs contributors
+Used for:    Pure-JS mTLS CA (default engine). Self-signed CA generation
+             (ML-DSA-87 by default, ECDSA P-384 bridge on opt-in), leaf-cert
+             signing for client certificates, X.509 CRL generation, and
+             PKCS#12 packaging (PBES2 + AES-256-CBC + PBKDF2-HMAC-SHA-512,
+             2,000,000 iterations; PBMAC1 integrity MAC). Zero runtime
+             dependencies. Wired into b.mtlsCa via lib/mtls-engine-default.js,
+             backed by the bundle lib/vendor/blamejs-pki.cjs.
 --------------------------------------------------------------------------------
 Component:   SecLists — 10k-most-common.txt
 Version:     master snapshot (bundled 2026-05-02)

package/README.md

@@ -120,7 +120,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Stream throttle** — shared token-bucket bandwidth limiter (RFC 2697 srTCM shape); N concurrent `node:stream` pipelines draw from one operator-configured `bytesPerSec` budget (`b.streamThrottle`)
 - **TLS-RPT receiver** — RFC 8460 inbound aggregate-report ingest; HTTPS POST handler + §4.4 schema parser with gzip-bomb / ratio-bomb / depth-bomb defenses (`b.mail.deploy.parseTlsRptReport` / `b.mail.deploy.tlsRptIngestHttp`)
 - **TLS / channel binding** — RFC 9266 TLS-Exporter token-to-session pinning (`b.tlsExporter`); RFC 9162 CT v2 inclusion-proof verification (`b.network.tls.ct.verifyInclusion`); RFC 8555 ACME + RFC 9773 ARI for 47-day certs with `{ jitter: true }` fleet-scheduling (`b.acme.renewIfDue`); draft-aaron-acme-profiles (`acme.listProfiles()` + `newOrder({ profile })`); draft-ietf-acme-dns-account-label (`acme.dnsAccount01ChallengeRecord(token, { identifier })`); RFC 8470 0-RTT inbound posture refuse / replay-cache (`b.router.create({tls0Rtt})`); RFC 9794 SecP256r1MLKEM768 in preferred-group order (`b.network.tls.preferredGroups`); RFC 6960 OCSP stapling — the cert manager (`b.cert`) fetches + validates each managed certificate's OCSP response (`b.network.tls.ocsp.fetch`) on a refresh cadence and exposes it on the served context for a TLS server's `OCSPRequest` handler to staple
-- **mTLS CA** — pure-JS, issues clientAuth / serverAuth / dual-EKU certs with SAN; auto-detects highest-PQC signature alg (today ECDSA-P384-SHA384; self-upgrades to SLH-DSA / ML-DSA when X.509 ecosystem catches up); PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`)
+- **mTLS CA** — pure-JS on the zero-dependency `@blamejs/pki` toolkit, issues clientAuth / serverAuth / dual-EKU certs with SAN under a post-quantum ML-DSA-87 (FIPS 204) default that node:tls verifies in a real mutual-auth handshake on OpenSSL 3.5; pin the classical `ECDSA-P384-SHA384` bridge via `b.mtlsCa.create({ algorithm })` for peers that predate it; PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`)
 ### HTTP
 
 - **Router + API specs** — schema-validated routes; OpenAPI 3.1 / 3.2 publication (`b.openapi` — webhooks + `jsonSchemaDialect`) + AsyncAPI publication for event/streaming (`b.asyncapi`)
@@ -316,11 +316,11 @@ All runtime dependencies are committed to the repo — no transitive npm install
 | [`@noble/ciphers`](https://github.com/paulmillr/noble-ciphers) | 2.2.0 | [Paul Miller](https://github.com/paulmillr) | XChaCha20-Poly1305 AEAD |
 | [`@noble/post-quantum`](https://github.com/paulmillr/noble-post-quantum) | 0.6.1 | [Paul Miller](https://github.com/paulmillr) | Pure-JS FIPS 203 ML-KEM (`ml_kem_512` / `ml_kem_768` / `ml_kem_1024`), FIPS 204 ML-DSA (`ml_dsa_44/65/87`), FIPS 205 SLH-DSA (`slh_dsa_*`). First-class on both server-side and client-side via `b.pqcSoftware` — security-first defaults pin to the highest cat-5 levels (ML-KEM-1024, ML-DSA-87, SLH-DSA-SHAKE-256f); interoperable with Node's built-in WebCrypto ML-KEM that `b.crypto.encrypt` / `b.middleware.apiEncrypt` use. |
 | [`@simplewebauthn/server`](https://github.com/MasterKale/SimpleWebAuthn) | 13.3.0 | [Matthew Miller](https://github.com/MasterKale) | WebAuthn / passkey verification |
-| [`@peculiar/x509`](https://github.com/PeculiarVentures/x509) + [`pkijs`](https://github.com/PeculiarVentures/PKI.js) | 2.0.0 + 3.4.0 | [Peculiar Ventures](https://github.com/PeculiarVentures) | Pure-JS mTLS CA — ECDSA P-384 cert signing, PKCS#12 packaging (no openssl CLI) |
+| [`@blamejs/pki`](https://github.com/blamejs/pki) | 0.3.25 | [blamejs](https://github.com/blamejs) | Zero-dependency pure-JS X.509 / CRL / PKCS#12 / CSR / CMS toolkit backing `b.mtlsCa` — ML-DSA-87 (FIPS 204) post-quantum + ECDSA-P384 cert signing, PBMAC1 PKCS#12 packaging, chain validation (no openssl CLI) |
 | [`SecLists` 10k-most-common.txt](https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt) | master snapshot | [Daniel Miessler / SecLists contributors](https://github.com/danielmiessler/SecLists) (CC-BY-3.0) | Top-10000 common-password dictionary read by `b.auth.password.policy()` for the NIST 800-63B §5.1.1.2 "previously breached" check |
 | [`prismjs`](https://prismjs.com/) | 1.30.0 | [Lea Verou + contributors](https://github.com/PrismJS/prism) | Syntax highlighting in the example wiki's code blocks (browser-side) |
 
-These libraries are exceptional work — blamejs wouldn't exist without them. All are MIT licensed (the SecLists password list is CC-BY-3.0). Per-package version, license, and provenance live in two manifests: [`lib/vendor/MANIFEST.json`](lib/vendor/MANIFEST.json) for the framework's server-side bundles and [`examples/wiki/public/vendor/MANIFEST.json`](examples/wiki/public/vendor/MANIFEST.json) for the wiki app's browser-side bundle. The framework's [`NOTICE`](NOTICE) file carries the upstream attributions.
+These libraries are exceptional work — blamejs wouldn't exist without them. All are MIT licensed, except `@blamejs/pki` (Apache-2.0) and the SecLists password list (CC-BY-3.0). Per-package version, license, and provenance live in two manifests: [`lib/vendor/MANIFEST.json`](lib/vendor/MANIFEST.json) for the framework's server-side bundles and [`examples/wiki/public/vendor/MANIFEST.json`](examples/wiki/public/vendor/MANIFEST.json) for the wiki app's browser-side bundle. The framework's [`NOTICE`](NOTICE) file carries the upstream attributions.
 
 ## Why "blamejs"
 

package/lib/audit.js

@@ -99,6 +99,15 @@ var EXTERNAL_STORE_TIMEOUT_MS = C.TIME.seconds(30);
 // verifyChain still works against the framework store.
 var _externalStore = null;
 
+// Mode of the registered external store: "shadow" (default) replicates
+// each framework chain.append to the store AFTER the authoritative b.db
+// write; "redirect" (useStore({ record, replaceChain: true })) routes the
+// shaped event STRAIGHT to the store and SKIPS the b.db chain append — for
+// a consumer that owns its own DB + tamper-evident audit layer and has no
+// b.db, so a chain append would only throw db/not-initialized on every
+// emit. Reset to "shadow" whenever the store is unregistered.
+var _externalStoreMode = "shadow";
+
 // Per-operation timeout for framework-state SQL. A misbehaving
 // external-db driver hanging on a query shouldn't hang audit forever.
 // 30s is generous for genuinely slow networks while still bounding
@@ -621,6 +630,24 @@ async function record(event) {
         metadata:          event.metadata ? JSON.stringify(event.metadata) : null,
         requestId:         event.requestId || null,
       };
+      // Redirect mode: the consumer store is authoritative (it owns the DB
+      // + tamper-evident audit layer; there is no b.db to append to). Hand
+      // the shaped logical event straight to the operator's record() and
+      // SKIP the framework chain append entirely — no db/not-initialized.
+      // The 30s timeout bounds a stalled callback so a hung consumer store
+      // can't wedge the audit critical path; a genuine store failure
+      // PROPAGATES (record() is the await-durability surface — a direct
+      // caller must see it), while the emit()/safeEmit() handler-flush path
+      // catches it drop-silent so the request that emitted can't be crashed.
+      if (_externalStore && _externalStoreMode === "redirect" &&
+          typeof _externalStore.record === "function") {
+        await safeAsync.withTimeout(
+          Promise.resolve().then(function () { return _externalStore.record(logical); }),
+          EXTERNAL_STORE_TIMEOUT_MS,
+          { name: "audit.redirectRecord" }
+        );
+        return logical;
+      }
       var appended = await _chainWriter.append(logical);
       // Operator-registered shadow store: replicate the fully-formed
       // row to an immutable external destination. Drop-silent on
@@ -705,8 +732,29 @@ async function record(event) {
  * Pass `null` (or `{ record: null }`) to unregister and revert to
  * chain-only mode.
  *
+ * Redirect mode — `useStore({ record, replaceChain: true })`: a
+ * consumer that owns its own database + audit layer and does NOT use
+ * `b.db` has no chain to shadow. In shadow mode every `record()` /
+ * `emit()` / `safeEmit()` still tries the `b.db` chain append first,
+ * which throws `db/not-initialized` on every emit (or silently drops
+ * from the emit handler). With `replaceChain: true` the shaped audit
+ * event is handed STRAIGHT to `record(event)` and the `b.db` chain
+ * append is skipped, so framework audit events (an SMTP insecure-TLS
+ * escape-hatch, mTLS negotiation at boot) land in the consumer's own
+ * tamper-evident log instead of erroring. In redirect mode the
+ * consumer store is authoritative: `record()`'s 30s timeout bounds a
+ * stalled callback, but a genuine store failure PROPAGATES to the
+ * caller (record() is the await-durability surface), while the
+ * `emit()` / `safeEmit()` handler-flush path drop-silent-catches it.
+ * The event passed to `record` is the shaped logical event
+ * (`{ action, outcome, actorUserId, actorIp, resourceKind, resourceId,
+ * reason, metadata, requestId, ... }`) — no framework `_id` /
+ * `monotonicCounter` / `prevHash` / `rowHash`, since there is no
+ * framework chain to hash against.
+ *
  * @opts
- *   record:  async function (row),       // operator's persistence callback
+ *   record:        async function (row),  // operator's persistence callback
+ *   replaceChain:  boolean,               // default: false (shadow). true → redirect (skip the b.db chain)
  *
  * @example
  *   var b = require("@blamejs/core");
@@ -732,6 +780,7 @@ async function record(event) {
 function useStore(store) {
   if (store === null || store === undefined) {
     _externalStore = null;
+    _externalStoreMode = "shadow";
     return;
   }
   if (typeof store !== "object") {
@@ -740,12 +789,19 @@ function useStore(store) {
   // `{ record: null }` unregisters explicitly (mirrors the null arg path).
   if (store.record === null || store.record === undefined) {
     _externalStore = null;
+    _externalStoreMode = "shadow";
     return;
   }
   if (typeof store.record !== "function") {
     throw new Error("audit.useStore: store.record must be an async function (row) => void");
   }
+  // Boot-time config input: a bad replaceChain flag is an operator typo —
+  // throw loudly rather than silently coerce it.
+  if (store.replaceChain !== undefined && typeof store.replaceChain !== "boolean") {
+    throw new Error("audit.useStore: store.replaceChain must be a boolean (true routes events to record() and skips the b.db chain)");
+  }
   _externalStore = store;
+  _externalStoreMode = store.replaceChain === true ? "redirect" : "shadow";
 }
 
 // ---- Query ----
@@ -824,6 +880,7 @@ async function query(criteria) {
   // In single-node mode the query builder gives us field-crypto unsealing
   // for free. In cluster mode we read raw rows from external-db and
   // unseal manually.
+  /* c8 ignore next 3 -- cluster-mode topology (configured externalDb backend); single-node query() always takes the else path. Cluster read is exercised in test/integration/audit-stack-{postgres,mysql}. */
   if (cluster.isClusterMode()) {
     return await _queryCluster(criteria);
   }
@@ -1057,6 +1114,7 @@ async function checkpoint(opts) {
     // null. If the fence passes (a same-node concurrent race), it is idempotent.
     // Any non-duplicate error rethrows.
     if (_isDuplicateCheckpointCounter(e)) {
+      /* c8 ignore next 3 -- cluster-only fence: single-node dup-anchor is idempotent and returns null below; the cluster fencing-token step-down is exercised in test/integration/audit-stack-{postgres,mysql}. */
       if (cluster.isClusterMode()) {
         await _upsertAuditTip(counter, tip.rowHash, String(createdAt), fencingToken);
       }
@@ -1080,6 +1138,7 @@ async function checkpoint(opts) {
   // also means the caller can audit the leader-lost transition and
   // step down. Other audit-tip errors (network blip, transient DB)
   // also surface so the operator can react.
+  /* c8 ignore next 2 -- cluster-mode audit-tip upsert; single-node takes the else (durable-tip sidecar) branch below. Cluster path exercised in test/integration/audit-stack-{postgres,mysql}. */
   if (cluster.isClusterMode()) {
     await _upsertAuditTip(counter, tip.rowHash, String(createdAt), fencingToken);
   } else {
@@ -1175,6 +1234,7 @@ async function verifyCheckpoints() {
       };
     }
     var payload = _checkpointPayload(Number(c.atMonotonicCounter), c.atRowHash, Number(c.createdAt));
+    /* c8 ignore next -- the isBuffer arm is pg/mysql-only (those drivers return a Buffer for the signature BLOB); node:sqlite single-node returns a Uint8Array, so the Buffer.from arm is the one taken here. */
     var sigBuf = Buffer.isBuffer(c.signature) ? c.signature : Buffer.from(c.signature);
     if (!auditSign.verify(payload, sigBuf, pub)) {
       return {
@@ -1261,6 +1321,7 @@ async function verify(opts) {
     function (sql, params) {
       return safeAsync.withTimeout(
         safeAsync.asyncRetry(function () {
+          /* c8 ignore next -- auditChain.verifyChain always invokes this reader with a params array from the sql builder; the `|| []` is a defensive fallback that is never taken. */
           return clusterStorage.executeAll(sql, params || []);
         }),
         FRAMEWORK_SQL_TIMEOUT_MS,
@@ -1277,6 +1338,7 @@ async function verify(opts) {
 function _resetForTest() {
   registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
   _externalStore = null;
+  _externalStoreMode = "shadow";
   db.reset();
   _chainWriter._resetForTest();
   // Drop pending buffered emits and cancel the age-flush timer on the
@@ -1292,6 +1354,7 @@ function _resetForTest() {
   // instead of writing the rest of the batch to the new database.
   if (_auditHandler) {
     try { _auditHandler.shutdownSync("audit._resetForTest"); }
+    /* c8 ignore next -- shutdownSync only splices the buffer + cancels a timer; it has no input-driven throw path, so this defensive catch never runs. */
     catch (e) { log.debug("reset-handler-shutdown-failed: " + (e && e.message || e)); }
     _auditHandler = null;
   }
@@ -1336,6 +1399,7 @@ function _ensureHandler() {
       var firstDropAction = null;
       var firstDropMessage = null;
       for (var i = 0; i < batch.length; i++) {
+        /* c8 ignore next -- mid-drain shutdown early-exit: fires only when the handler is shut down (test reset) while a batch is in flight, a timing race not deterministically forceable from the public API. */
         if (ctx && ctx.isShutdown && ctx.isShutdown()) return;
         try { await record(batch[i]); }
         catch (e) {
@@ -1353,6 +1417,7 @@ function _ensureHandler() {
           // representative sample without per-line log spam.
           if (firstDropAction === null) {
             firstDropAction = (batch[i] && batch[i].action) || null;
+            /* c8 ignore next -- record() only ever rejects with an Error carrying a non-empty message, so the String(e) fallback (and the `e` falsy short-circuit) is unreachable. */
             firstDropMessage = (e && e.message) ? e.message : String(e);
           }
         }
@@ -1443,6 +1508,7 @@ function _normalizeOutcome(o) {
 // before the first dot) is left strict — namespaces are
 // operator-registered and should be plain identifiers.
 function _normalizeAction(action) {
+  /* c8 ignore next -- only caller is safeEmit(), which returns early unless event.action is a string, so action is always a string here. */
   if (typeof action !== "string") return action;
   return action.replace(/-/g, "_");
 }
@@ -1636,6 +1702,7 @@ async function flush() {
 // when they boot under sox-404 / soc2 / pci-dss posture so a non-
 // framework writer can't INSERT rows under a different role.
 function _checkActorBinding(actorId, eventActorId, opts) {
+  /* c8 ignore next -- only callers are bindActor()'s bound wrappers, and bindActor() throws unless actorId is a non-empty string, so actorId is always truthy here. */
   if (!actorId) return true;     // unbound — no enforcement
   if (!eventActorId) {
     return { ok: false, reason: "event missing actor.userId — refused under bound emit" };
@@ -1709,6 +1776,7 @@ function bindActor(actorId, opts) {
         actor:    { userId: actorId },
         metadata: { attemptedAction: eventAction, reason: reason },
       });
+    /* c8 ignore next -- handlers' emit() never throws (it routes bad input to onError/dead-letter internally) and the violation event carries no throwing accessors, so this defensive catch never runs. */
     } catch (_e) { /* drop-silent — never break the caller */ }
   }
   function boundSafeEmit(event) {

package/lib/auth/oauth.js

@@ -272,6 +272,27 @@ function _generatePkce() {
   return { verifier: verifier, challenge: challenge };
 }
 
+/**
+ * @primitive  b.auth.oauth.generatePkce
+ * @signature  b.auth.oauth.generatePkce()
+ * @since      0.18.0
+ * @status     stable
+ * @related    b.auth.oauth.parseCallback
+ *
+ * Generate a PKCE (RFC 7636) verifier/challenge pair for a hand-rolled
+ * authorization-code flow that does not go through `create()`. The
+ * `code_challenge_method` is always `S256`: the challenge is the base64url
+ * of SHA-256 over the verifier, and the verifier is 43 base64url characters
+ * (32 CSPRNG bytes).
+ *
+ * @example
+ *   var pkce = b.auth.oauth.generatePkce();
+ *   // → { verifier: "…43 chars…", challenge: "…base64url(SHA-256(verifier))…" }
+ */
+function generatePkce() {
+  return _generatePkce();
+}
+
 function _validateUrl(url, allowHttp, label) {
   if (typeof url !== "string" || url.length === 0) {
     throw new OAuthError("auth-oauth/bad-url", label + ": URL is required");
@@ -550,6 +571,7 @@ function _toAttestationPrivateKey(value, label) {
   catch (e) {
     var code = (e && e.code) === "auth-jwt-external/sign-no-key"
       ? "auth-oauth/attestation-no-key" : "auth-oauth/attestation-bad-key";
+    /* c8 ignore next -- String(e) fallback: the jwt-external error always carries a message */
     throw new OAuthError(code, (e && e.message) || String(e));
   }
 }
@@ -567,8 +589,10 @@ function _resolveAttestationAlg(explicitAlg, privateKey, label) {
   try {
     return jwtExternal._resolveSignAlg(explicitAlg, privateKey, label);
   } catch (e) {
+    /* c8 ignore next -- || "" is unreachable: _resolveSignAlg always throws a coded AuthError */
     var ec = (e && e.code) || "";
     if (ec === "auth-jwt-external/sign-alg-key-mismatch") {
+      /* c8 ignore next -- String(e) fallback: the mapped error always carries a message */
       throw new OAuthError("auth-oauth/attestation-alg-key-mismatch", (e && e.message) || String(e));
     }
     if (ec === "auth-jwt-external/sign-alg-refused" || ec === "auth-jwt-external/sign-alg-unsupported") {
@@ -576,8 +600,10 @@ function _resolveAttestationAlg(explicitAlg, privateKey, label) {
         label + ": alg '" + explicitAlg + "' is not an accepted attestation algorithm");
     }
     if (ec === "auth-jwt-external/sign-key-unsupported") {
+      /* c8 ignore next -- String(e) fallback: the mapped error always carries a message */
       throw new OAuthError("auth-oauth/attestation-key-unsupported", (e && e.message) || String(e));
     }
+    /* c8 ignore next -- unreachable: _resolveSignAlg only emits the four codes handled above */
     throw new OAuthError("auth-oauth/attestation-bad-key", (e && e.message) || String(e));
   }
 }
@@ -613,6 +639,7 @@ function _verifyAttestationJws(jws, publicKeyJwk, label, expectedTyp) {
     header  = safeJson.parse(_b64urlDecode(parts[0]).toString("utf8"), { maxBytes: MAX_ATTESTATION_JWT_BYTES });
     payload = safeJson.parse(_b64urlDecode(parts[1]).toString("utf8"), { maxBytes: MAX_ATTESTATION_JWT_BYTES });
   } catch (e) {
+    /* c8 ignore next 2 -- String(e) fallback: the decode error always carries a message */
     throw new OAuthError("auth-oauth/attestation-malformed",
       label + ": header/payload decode failed: " + ((e && e.message) || String(e)));
   }
@@ -653,6 +680,7 @@ function _verifyAttestationJws(jws, publicKeyJwk, label, expectedTyp) {
   var ok;
   try {
     ok = nodeCrypto.verify(params.hash, Buffer.from(signingInput, "ascii"), verifyOpts, sig);
+    /* c8 ignore next 4 -- verify cannot raise: the alg/kty/crv cross-check above guarantees a compatible key/params pairing, so a bad signature returns false rather than throwing */
   } catch (verifyErr) {
     throw new OAuthError("auth-oauth/attestation-bad-signature",
       label + ": signature verification raised: " + ((verifyErr && verifyErr.message) || String(verifyErr)));
@@ -667,6 +695,7 @@ function _verifyAttestationJws(jws, publicKeyJwk, label, expectedTyp) {
 // never reach the attestation's cnf claim. Mirrors the dpop.buildProof
 // public-only embed.
 function _publicCnfJwk(jwk, label) {
+  /* c8 ignore next 4 -- unreachable: the sole caller validates instanceKeyJwk as a required object before this call */
   if (!jwk || typeof jwk !== "object") {
     throw new OAuthError("auth-oauth/attestation-bad-cnf",
       label + ": instanceKeyJwk (public JWK for the cnf claim) is required");
@@ -1006,6 +1035,7 @@ async function verifyClientAttestation(attestationJwt, popJwt, vopts) {
 // strings, returns false (never throws) on length mismatch, and refuses
 // non-string/Buffer input — so it carries the timing + type discipline.
 function _constantTimeStrEq(a, b) {
+  /* c8 ignore next -- every caller passes a String()-wrapped first argument, so the typeof-a arm never short-circuits */
   if (typeof a !== "string" || typeof b !== "string") return false;
   return cryptoTimingSafeEqual(a, b);
 }
@@ -1040,6 +1070,7 @@ var RESERVED_AUTHZ_PARAMS = {
 // closed; shared by authorizationUrl, pushAuthorizationRequest, and
 // endSessionUrl so every URL/PAR builder guards the same way.
 function _assertNoReservedExtraParams(extraParams, reserved, errCode, ctx) {
+  /* c8 ignore next -- every caller guards `extraParams && typeof === "object"` first, so the !extraParams arm never short-circuits */
   if (!extraParams || typeof extraParams !== "object") return;
   var ek = Object.keys(extraParams);
   for (var i = 0; i < ek.length; i++) {
@@ -1187,13 +1218,16 @@ function create(opts) {
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
     if (res.statusCode < 200 || res.statusCode >= 300) {
+      /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
       var bodyText = res.body ? res.body.toString("utf8") : "";
       throw new OAuthError("auth-oauth/http-" + res.statusCode,
         url + " returned " + res.statusCode + ": " + bodyText.slice(0, 500));
     }
+    /* c8 ignore next -- httpClient always yields a Buffer body (empty Buffer for no content), so this never returns null */
     if (!res.body) return null;
     try { return safeJson.parse(res.body.toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/bad-json",
         url + " response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -1262,6 +1296,7 @@ function create(opts) {
   async function _peekDiscovery() {
     if (!isOidc || !issuer) return null;
     try { return (await _discoveryCache.get("config")) || null; }
+    /* c8 ignore next -- defensive: the in-memory discovery cache get() does not throw */
     catch (_e) { return null; }
   }
 
@@ -1312,6 +1347,7 @@ function create(opts) {
     // base64url(SHA-256(verifier)) per RFC 7636.
     var state = uopts.state || _generateRandomToken(STATE_NONCE_BYTES);
     var nonce = uopts.nonce || (isOidc ? _generateRandomToken(STATE_NONCE_BYTES) : null);
+    /* c8 ignore next -- pkce is always true (create() refuses pkce:false), so the : null alternate is dead */
     var pkceVals = pkce ? _generatePkce() : null;
     var params = new URLSearchParams();
     params.set("response_type", "code");
@@ -1356,6 +1392,7 @@ function create(opts) {
       url:       endpoint + sep + params.toString(),
       state:     state,
       nonce:     nonce,
+      /* c8 ignore next 2 -- pkceVals is always truthy (pkce is always on), so the : null alternates are dead */
       verifier:  pkceVals ? pkceVals.verifier  : null,
       challenge: pkceVals ? pkceVals.challenge : null,
       authorizationDetails: requestedAuthzDetails,
@@ -1764,6 +1801,7 @@ function create(opts) {
     if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res = await hc.request(req);
+    /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     if (res.statusCode < 200 || res.statusCode >= 300) {
       throw new OAuthError("auth-oauth/token-error-" + res.statusCode,
@@ -1772,6 +1810,7 @@ function create(opts) {
     var parsed;
     try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/bad-token-json",
         "token endpoint response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -1779,6 +1818,7 @@ function create(opts) {
   }
 
   async function _normalizeTokens(raw, vopts) {
+    /* c8 ignore next -- every caller passes a vopts object, so the || {} default is unreachable */
     vopts = vopts || {};
     // RFC 6749 §3.3 — scope is space-separated, ONLY U+0020. `\s+` previously
     // matched U+0085 NEL, U+00A0 NBSP, etc., so a hostile AS returning
@@ -1879,6 +1919,7 @@ function create(opts) {
         action:   "jwt.jwe.refused",
         outcome:  "denied",
         metadata: { reason: "jwe-on-jws-verifier", primitive: "oauth.verifyIdToken" },
+        /* c8 ignore next -- drop-silent observability sink: safeEmit does not throw */
       }); } catch (_e) { /* drop-silent — observability sink */ }
       throw new OAuthError("auth-oauth/jwe-refused",
         "5-segment JWE id_token refused — verifyIdToken only handles JWS " +
@@ -1892,6 +1933,7 @@ function create(opts) {
       header  = safeJson.parse(_b64urlDecode(parts[0]).toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES });
       payload = safeJson.parse(_b64urlDecode(parts[1]).toString("utf8"), { maxBytes: OAUTH_MAX_RESPONSE_BYTES });
     } catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the decode error always carries a message */
       throw new OAuthError("auth-oauth/malformed-jwt",
         "ID token header/payload base64 decode failed: " + ((e && e.message) || String(e)));
     }
@@ -1980,6 +2022,7 @@ function create(opts) {
     var verified;
     try {
       verified = nodeCrypto.verify(params.hash, Buffer.from(signingInput, "ascii"), verifyOpts, sig);
+      /* c8 ignore next 5 -- verify cannot raise: the alg/kty/crv cross-check above guarantees a compatible key/params pairing, so a bad signature returns false rather than throwing */
     } catch (verifyErr) {
       throw new OAuthError("auth-oauth/bad-signature",
         "ID token signature verification raised: " +
@@ -2055,6 +2098,7 @@ function create(opts) {
             reason:          "cross-realm-jwt-refused",
             primitive:       "oauth.verifyIdToken",
           },
+          /* c8 ignore next -- drop-silent observability sink: safeEmit does not throw */
         }); } catch (_e) { /* drop-silent — observability sink */ }
         throw new OAuthError("auth-oauth/iss-mismatch",
           "ID token iss '" + payload.iss + "' does not match expected '" + issuer +
@@ -2335,6 +2379,7 @@ function create(opts) {
           reason:          "frontchannel-logout-cross-realm",
           primitive:       "oauth.parseFrontchannelLogoutRequest",
         },
+        /* c8 ignore next -- drop-silent observability sink: safeEmit does not throw */
       }); } catch (_e) { /* drop-silent — observability sink */ }
       throw new OAuthError("auth-oauth/frontchannel-logout-iss-mismatch",
         "parseFrontchannelLogoutRequest: iss \"" + iss +
@@ -2423,6 +2468,7 @@ function create(opts) {
     var claims = verified.claims;
 
     // §2.6 — events claim presence + correct shape
+    /* c8 ignore next 5 -- defense-in-depth: verifyIdToken's skipExpCheck self-guard already enforced the backchannel-logout event before returning, so this re-check never fires */
     if (!claims.events || typeof claims.events !== "object" ||
         !claims.events["http://schemas.openid.net/event/backchannel-logout"]) {
       throw new OAuthError("auth-oauth/missing-logout-event",
@@ -2449,6 +2495,7 @@ function create(opts) {
       ? vopts.maxAgeSec
       : DEFAULT_LOGOUT_TOKEN_MAX_AGE_SEC;
     var nowSecLogout = Math.floor(Date.now() / C.TIME.seconds(1));
+    /* c8 ignore next 4 -- defense-in-depth: verifyIdToken's skipExpCheck freshness gate already required a numeric iat before returning, so this re-check never fires */
     if (typeof claims.iat !== "number") {
       throw new OAuthError("auth-oauth/logout-token-no-iat",
         "verifyBackchannelLogoutToken: payload.iat required (OIDC BCL §2.4)");
@@ -2513,6 +2560,7 @@ function create(opts) {
       sub:    claims.sub || null,
       sid:    claims.sid || null,
       jti:    claims.jti || null,
+      /* c8 ignore next -- iat is always a positive number here (enforced above), so the || null arm is unreachable */
       iat:    claims.iat || null,
       events: claims.events,
       claims: claims,
@@ -2672,6 +2720,7 @@ function create(opts) {
     if (allowInternal !== null) req.allowInternal = allowInternal;
     Object.assign(req, httpClientOpts);
     var res  = await hc.request(req);
+    /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     if (res.statusCode < 200 || res.statusCode >= 300) {
       throw new OAuthError("auth-oauth/register-failed-" + res.statusCode,
@@ -2680,6 +2729,7 @@ function create(opts) {
     var parsed;
     try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/bad-register-response",
         "registerClient: response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -2803,13 +2853,16 @@ function create(opts) {
         "deleteClient: " + res.statusCode);
     }
     if (res.statusCode < 200 || res.statusCode >= 300) {
+      /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
       var errText = res.body ? res.body.toString("utf8").slice(0, 500) : "";
       throw new OAuthError("auth-oauth/dcr-" + method.toLowerCase() + "-failed-" + res.statusCode,
         method.toLowerCase() + "Client: " + res.statusCode + ": " + errText);
     }
+    /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     try { return safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
     catch (e) {
+      /* c8 ignore next 2 -- String(e) fallback: the parse error always carries a message */
       throw new OAuthError("auth-oauth/dcr-bad-response",
         method.toLowerCase() + "Client: response not JSON: " + ((e && e.message) || String(e)));
     }
@@ -2937,6 +2990,7 @@ function create(opts) {
       // reinstate buffer mode.
       req.responseMode = "always-resolve";
       var res    = await hc.request(req);
+      /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
       var text   = res.body ? res.body.toString("utf8") : "";
       var parsed;
       try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
@@ -2959,6 +3013,7 @@ function create(opts) {
       throw new OAuthError("auth-oauth/device-" + (err || "unknown"),
         "pollDeviceCode: " + (parsed && parsed.error_description ? parsed.error_description : text.slice(0, 200)));   // 200-char error-snippet cap, not bytes
     }
+    /* c8 ignore next 2 -- the || fallback is unreachable: reaching this timeout requires a truthy (small) maxWaitMs; a falsy one yields the 10-minute deadline that never expires within a test window */
     throw new OAuthError("auth-oauth/device-poll-timeout",
       "pollDeviceCode: exceeded maxWaitMs " + (popts.maxWaitMs || C.TIME.minutes(10)));
   }
@@ -3180,6 +3235,8 @@ module.exports = {
   buildClientAttestation:    buildClientAttestation,
   buildClientAttestationPop: buildClientAttestationPop,
   verifyClientAttestation:   verifyClientAttestation,
+  // PKCE (RFC 7636) generator for hand-rolled authorization-code flows.
+  generatePkce:              generatePkce,
   // Internal helpers exposed for tests
   _generatePkce:         _generatePkce,
   _generateRandomToken:  _generateRandomToken,

package/lib/cli.js

@@ -1425,15 +1425,21 @@ var MTLS_USAGE = [
   "                         'auto' loads whichever form exists.",
   "",
   "Subcommand flags:",
+  "  init:      [--algorithm ECDSA-P384-SHA384]",
   "  issue:     --subject <CN>    [--days <N>]",
   "  issue-p12: --subject <CN>    --password <pkcs12-passphrase>    [--days <N>]    [--out <path>]",
   "",
   "Cert issuance ('init', 'issue', 'issue-p12') uses the framework's",
-  "bundled pure-JS engine (lib/mtls-engine-default.js, ECDSA P-384",
-  "signatures, AES-256-CBC + HMAC-SHA-512 PBKDF2 PKCS#12 with 2,000,000",
-  "iterations). Operators with custom requirements pass a different",
-  "engine via b.mtlsCa.create({ engine: ... }) when wiring their app;",
-  "the CLI always uses the default.",
+  "bundled pure-JS engine (lib/mtls-engine-default.js) on the vendored",
+  "@blamejs/pki toolkit: post-quantum ML-DSA-87 (FIPS 204) certificate",
+  "signatures by default, which node:tls verifies in a real mutual-auth",
+  "handshake on OpenSSL 3.5. Pass 'init --algorithm ECDSA-P384-SHA384'",
+  "for a classical CA a peer predating OpenSSL 3.5 can verify (the pin",
+  "covers the CA and its leaves). PKCS#12 export keeps AES-256-CBC +",
+  "PBKDF2-HMAC-SHA-512 @ 2,000,000-iter bag protection with a",
+  "tier-dependent integrity MAC (PBMAC1/RFC 9579 for the PQC default,",
+  "RFC 7292 HMAC MacData for the classical bridge). Operators with custom",
+  "requirements pass a different engine via b.mtlsCa.create({ engine: ... }).",
 ].join("\n");
 
 async function _runMtls(args, ctx) {
@@ -1481,6 +1487,10 @@ async function _runMtls(args, ctx) {
       dataDir:         dataDir,
       vault:           booted.b.vault,
       caKeySealedMode: sealedMode,
+      // --algorithm pins the CA + its leaves; omitted -> the ML-DSA-87 default.
+      // Pass "ECDSA-P384-SHA384" for the classical bridge (a peer predating
+      // OpenSSL 3.5). undefined when the flag is absent.
+      algorithm:       args.flags.algorithm,
       // No engine passed — b.mtlsCa falls back to the bundled default
       // (lib/mtls-engine-default.js).
     });