@blamejs/core 0.6.27 → 0.6.29

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.29** (2026-05-02) — CI cleanup. **shellcheck gate green**: `docker/init/generate-certs.sh`'s footer line counted output via `ls "$CERT_DIR" | wc -l` (SC2012 — fragile on filenames with newlines or quoting metacharacters); replaced with `find "$CERT_DIR" -maxdepth 1 -mindepth 1 | wc -l`. Same semantics, robust to any cert filename pki-init might end up writing. **shellcheck added to the documented pre-push gate list** in CONTRIBUTING.md alongside smoke / wiki e2e / eslint / api-snapshot / primitive-section validators — CI's `Lint summary` job has always run it, but the local-dev recipe didn't, so contributors hit it post-push instead of catching it locally. **eslint pin alignment**: `.github/PULL_REQUEST_TEMPLATE.md` and CONTRIBUTING.md still pinned `eslint@10` even though v0.6.16 swapped CI runners to `eslint@latest`; both bumped to `@latest` to match the forward-track posture of every other CI tool. No framework code changes; the script + doc updates never ship in the npm package (excluded by `files` array).
+- **0.6.28** (2026-05-02) — bug-finding pass: live integration test suite + every framework bug it caught. **`b.ssrfGuard.checkUrl` cloud-metadata hard-deny** — `allowInternal: true` no longer permits 169.254.169.254 (AWS / GCP / Azure metadata). Loopback / private / link-local / reserved stay allowInternal-overridable per existing semantics; cloud-metadata is unconditional because a blanket override would let any compromised request exfiltrate instance credentials. **`b.mtlsCa` issues server certs and dual-EKU certs** — `generateClientCert({ usage: "client" | "server" | "both", sans: [...] })`. `usage` controls EKU (`client` = clientAuth, `server` = serverAuth, `both` = both); `sans` accepts `DNS:` / `IP:` / bare-DNS entries; serverAuth without an explicit SAN auto-adds the CN. Operators wiring inbound mTLS reverse-proxy fronts no longer hit "unsuitable certificate purpose" on the handshake. **`b.mtlsCa` algorithm auto-detect** — the engine probes webcrypto + the vendored x509 library at first cert issuance and picks the highest-PQC option that round-trips: SLH-DSA-SHAKE-256f → SLH-DSA-SHAKE-128f → ML-DSA-87 → ML-DSA-65 → ECDSA-P384-SHA384 (current bridge — what the X.509 ecosystem accepts today). When the bridge condition lifts and the vendor refresh ships, the same `b.mtlsCa.create(...)` call self-upgrades; `b.mtlsCa.status().cert.label` and `.posture` surface the chosen algorithm. **`b.redisClient.create({ ca, servername })`** — managed-Redis / on-prem-cluster operators connecting over `rediss://` against a private CA can pin trust roots; `servername` auto-suppresses for IP literals so `rediss://127.0.0.1:6380` no longer trips node:tls's IP-as-SNI rule. **`b.network.dns.useDnsOverTls` / `useDnsOverHttps` accept `ca`** — same trust-pinning surface for self-signed / private-PKI DoT and DoH endpoints. **DoT TLS handshake errors** now route as DnsError on the lookup promise rather than leaking as `unhandledRejection` — the secureConnect / error event-listener race had let cert-verification failures escape the per-query Promise wrapping. **DoT socket lifecycle** — was unconditionally `sock.unref()`'d after construct, causing node to exit during in-flight lookups when no other I/O kept the loop alive; now ref'd while a query is in flight and unref'd when idle. **`b.ntpCheck.querySingle` honours IPv6 servers** — was hardcoded to `dgram.createSocket("udp4")`, so `::1` / `fd00::…` queries failed with EINVAL; now auto-detects family from the server string. **`b.logStream.shutdown` drains in-flight emit microtasks** before closing sink fds — fire-and-forget emits queued just before shutdown were silently dropped because `close()` ran ahead of the microtask. **`b.logStream` webhook-sink `close()` flushes BEFORE setting `closed = true`** — `_flush`'s while loop bailed on `!closed`, leaving any records buffered just before shutdown stranded. **Integration test suite** (`test/integration/`, runner at `scripts/test-integration.js`) — 13 live test files across `b.redisClient` plain + TLS, `b.queue` Redis backend lifecycle, `b.mail` SMTP + STARTTLS + multi-rcpt + dot-stuffing transparency, `b.mail.dkim` rsa-sha256 + ed25519-sha256 + bad-algorithm reject, `b.ntpCheck` v4 + v6 + bootCheck + bad-host + bad-port, `b.network.dns` plain + DoT + DoH with strict CA pinning + bad-servername + cache, `b.network.heartbeat` http + tcp + state-change callbacks, `b.objectStore` sigv4 PUT / GET / list / delete on plain HTTP + TLS variants, `b.cache` memory + Redis-backed cluster, `b.httpClient` direct + Squid forward proxy + TLS pin, `b.ssrfGuard` classify + checkUrl + cloud-metadata block, `b.logStream` local + webhook + deferred-syslog error path, `b.mtlsCa` CA bootstrap + clientAuth + serverAuth + dual-EKU live mTLS handshakes. Companion `docker-compose.test.yml` stands up redis (plain + TLS) / postgres / mysql / mongo / minio (HTTP + HTTPS variants) / rabbitmq (plain + TLS) / nats / syslog / ntp / mailpit / coredns (plain + DoT + DoH) / haproxy / caddy / mitmproxy / squid / pki-init (auto-generates Ed25519 CA + per-service leaf certs into a docker volume); host port bindings dual-stack on `127.0.0.1` AND `[::1]`. `scripts/check-services.js` does host-side TCP / TLS handshake / SNTPv4 / DNS-A / Redis-PING / SMTP-banner / HTTP probes across every endpoint; `scripts/test-integration.js` exports the test CA via `docker cp` and sets `NODE_EXTRA_CA_CERTS` per-test child process so the framework's TLS verification stays strict (no `rejectUnauthorized: false` bypass anywhere in the test surface). **Test architecture rule** — live tests go in `test/integration/`, NEVER in `test/layer-N-*/`: smoke must remain pure (no docker dependency, runs in CI / on a developer laptop / inside prepack-guard) and a "skip silently when service is down" branch in a layer-N test makes the gate's pass count misleading and masks bugs that only surface against a live backend. The `0.6.27` `queue-redis.test.js` was moved to `test/integration/queue-redis.test.js` to enforce this. Smoke and wiki e2e green; integration suite ships green against the docker-compose stack.
 - **0.6.27** (2026-05-02) — Redis backend for `b.queue` so multi-replica apps can share a single queue without each needing to be cluster leader. **Bespoke RESP2 client** (`lib/redis-client.js`) — zero npm runtime deps. TCP via `node:net` + TLS via `node:tls` (`rediss://` auto-detected), legacy single-arg AUTH + ACL `AUTH user pass`, `SELECT db`, pipelining, exponential-backoff reconnect, EVAL helper. **`b.queue` protocol "redis"** (`lib/queue-redis.js`) — full enqueue/lease/extendLease/complete/fail/sweepExpired/size/purge/dlqList/dlqRetry/dlqSize parity with the local backend. Atomicity comes from server-side Lua scripts so concurrent consumers can't double-lease and a sweep can't race a complete. Storage layout: per-job HASH (sealed payload + lastError via `cryptoField.sealRow("_blamejs_jobs", row)` — same crypto config as the local backend), per-queue ready ZSET scored by availableAt, per-queue inflight ZSET scored by leaseExpiresAt, per-queue dlq ZSET scored by finishedAt, plus a queues SET so sweepExpired walks every known queue without a global secondary index. Cron-repeat handled in `complete()` JS — re-enqueues the next firing as a fresh jobId with availableAt=next-cron-fire. **`b.queue.bootFromEnv({ env })`** — env-driven init mirroring `b.network.bootFromEnv` and `b.logStream.bootFromEnv`. Reads `BLAMEJS_QUEUE_PROTOCOL` (`local`|`redis`), `BLAMEJS_QUEUE_REDIS_URL`, `BLAMEJS_QUEUE_REDIS_PASSWORD`, `BLAMEJS_QUEUE_REDIS_USERNAME`, `BLAMEJS_QUEUE_REDIS_TLS`, `BLAMEJS_QUEUE_REDIS_KEY_PREFIX`. Operators flip from local to Redis without a code change; both wiki docker-compose configs declare the new env knobs. Removed `redis` from `DEFERRED_PROTOCOLS`. **Out of scope for v1** (deferred to follow-up patches with explicit re-open conditions): Redis Cluster (slot-routing), Sentinel (managed primary failover), priority ordering on the Redis backend (queue-local supports `priority` opt; Redis backend orders strictly by availableAt for v1), flow children with `dependsOn` cascade. **Wiki**: queue-cache page documents the Redis backend opts schema, bootFromEnv, and the layout. **Tests**: 24 RESP2 protocol parser unit tests (`test/layer-0-primitives/redis-client.test.js`) cover URL parsing, command encoding (binary-safe), every reply type (simple string / error / integer / bulk / nil bulk / nested array / pipelined / incomplete-mid-frame). Live Redis round-trip tests (`test/layer-0-primitives/queue-redis.test.js`) cover enqueue+lease, availableAt scheduling, visibility-timeout sweep, fail+retry path, DLQ list/retry/size, extendLease, purge, and concurrent-leaser no-double-lease — skip cleanly when `BLAMEJS_TEST_REDIS_URL` is not set so the smoke suite passes on dev boxes without a Redis container. Smoke 6780 OK.
 - **0.6.26** (2026-05-02) — `blamejs restore` and `blamejs audit verify-chain` subcommands wrap the existing `b.restore` and `b.audit.verifyChain` primitives so operators can drive them from runbooks without writing app code. **`blamejs restore`**: `list` (enumerate bundles in storage), `inspect` (manifest summary without touching live data), `apply` (live in-place restore with rollback preserved), `rollback` (revert to most-recent OR named restore point), `list-rollbacks` (enumerate preserved rollback points). Two ways to identify a bundle — `--bundle <dir>` matches the shape `blamejs backup extract` produces (parent dir is treated as storage root, basename as bundle id), or `--storage-root <root> --bundle-id <id>` for multi-bundle stores. `apply` honors `--max-pulled-bytes` / `--max-pulled-files` (defaults 4 GiB / 100K), `--rollback-root` (default `<data-dir>.rollbacks`), `--no-audit`, and `BLAMEJS_BACKUP_PASSPHRASE` env. **`blamejs audit verify-chain`**: walks the live audit chain end-to-end, reports tampering with `breakAt` / `breakRowId` / expected-vs-actual prevHash; honours `--max-rows` to bound long walks; default table is `audit_log`. **Wiki CLI snapshot test now validates subcommand pairs**, not just top commands. Walks every wiki + README invocation of the form `blamejs <cmd> <sub>` and verifies that <sub> exists in the perCommand[<cmd>].subcommands list parsed from `lib/cli.js`. Surfaced one real drift on first run: `examples/wiki/seeders/prod/pages/backup-restore.js` documented `blamejs audit verify-signing` after vault rotation, but no such subcommand existed (only `verify-bundle`); fixed by shipping the new `verify-chain` subcommand and updating the wiki to reference it. Two top-level command gaps surfaced and fixed: `blamejs restore` (now real) and `blamejs network status` (was prose-promised in `network-config.js`; reworded to point at `b.network.snapshot()` for /healthz / custom diagnostics routes since wiring a CLI command for it is operator-side work). README CLI table updated with `restore` row and the two new audit subcommands.
 - **0.6.25** (2026-05-02) — `b.logStream` gains an AWS CloudWatch Logs sink AND framework-level env wiring. **CloudWatch sink**: `protocol: "cloudwatch"` POSTs `PutLogEvents` over HTTPS with SigV4 signing (service `logs`); operator pre-creates the log group + log stream (the framework does NOT auto-create). Honors IAM role + STS session-token credentials. Respects all three CloudWatch caps automatically: 10,000 events / 1 MiB total payload / 256 KiB-per-event. Per-event oversize dropped at `emit()`-time with `onDrop` fired (truncated message in the drop notification). Per-batch oversize split mid-flush. Permanent AWS errors (`ResourceNotFoundException` / `AccessDeniedException` / `InvalidParameterException` / `UnrecognizedClientException` / `SerializationException`) skip the retry budget. `InvalidSequenceTokenException` (legacy CW accounts) extracts the expected token from the error message and retries with it once. `lib/object-store/sigv4.js` `signRequest()` is now service-agnostic — accepts `opts.service` (default still `"s3"` for back-compat). Removed `cloudwatch` from `DEFERRED_PROTOCOLS`. **`b.logStream.bootFromEnv({ env })`**: framework-level env-driven init mirroring `b.network.bootFromEnv`. Reads `BLAMEJS_LOG_STREAM_PROTOCOL` (`local`/`webhook`/`otlp`/`cloudwatch`), `BLAMEJS_LOG_STREAM_URL`, `BLAMEJS_LOG_STREAM_TOKEN`, `BLAMEJS_LOG_STREAM_SERVICE_NAME`, `BLAMEJS_LOG_STREAM_SERVICE_VERSION`, `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_GROUP`, `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_STREAM`, `BLAMEJS_LOG_STREAM_PATH`, plus standard AWS_*. Operators get a working log-stream sink without writing build-app code. Wiki app's `build-app.js` replaced its inline env-reading with one `b.logStream.bootFromEnv()` call; both docker-compose configs declare the new env knobs. **Wiki env-snapshot test**: parallel to api-snapshot.json — walks `process.env.X` / `env.X` / `safeEnv.readVar("X")` reads in the wiki app + framework `lib/`, walks docker-compose env declarations, captures the union as `examples/wiki/env-snapshot.json`, fails the e2e gate when env vars are added/removed without updating the snapshot OR when source-only / compose-only gaps appear (env knob declared but unread, env read but undocumented). The validator immediately surfaced 13 real gaps in the wiki app: 5 `WIKI_*` env vars read by source but missing from docker-compose (`WIKI_VAULT_MODE`, `WIKI_DB_AT_REST`, `WIKI_AUDIT_SIGNING_MODE`, `WIKI_BIND`, `WIKI_SITE_URL`), 2 framework env vars (`BLAMEJS_AUDIT_SIGNING_MODE`, `BLAMEJS_TMPDIR`) read by `lib/db.js` via `safeEnv.readVar` but never declared in the wiki's compose configs, and 6 dead env knobs in compose that nothing read. All 13 fixed. Update workflow: `BLAMEJS_UPDATE_ENV_SNAPSHOT=1 node examples/wiki/test/validate-env-snapshot.js` (mirrors the api-snapshot UX). Wiki observability page documents the new sink alongside webhook + otlp; README "What ships in the box" calls out all four log-stream sinks. Tests cover endpoint resolution, event-byte accounting, batch sorting + sequence-token round-trip, permanent-error classifier, validation, round-trip via mock CloudWatch, STS session-token propagation, ResourceNotFoundException no-retry path, 256 KiB per-event hard cap, dispatcher integration, AND batch splitting on the 1-MiB cap (5 quarter-MB events POST as 4 + 1 batches).

package/README.md

@@ -43,8 +43,8 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 
 - **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows on the local SQLite backend OR a shared Redis backend for multi-replica deploys (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
 - **Identity & access** — passwords (Argon2id) + policy primitive (NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles, HaveIBeenPwned k-anonymity breach check, length / context / dictionary / complexity rules, rotation + history) (`b.auth.password`); passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions with optional IP / UA fingerprint drift detection + anomaly scoring, brute-force lockout (`b.auth.*`, `b.session`); RBAC + optional per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule approval workflow with m-of-n quorum + cooling-off lock + approver-role gate + cancellation (`b.dualControl`).
-- **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
-- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), DNS with IPv6 / DoH / DoT / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
+- **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA that issues clientAuth / serverAuth / dual-EKU certs with SAN entries and auto-detects the highest-PQC signature algorithm the vendored x509 library accepts (today: ECDSA-P384-SHA384 bridge; self-upgrades to SLH-DSA / ML-DSA when the X.509 ecosystem catches up), PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
+- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate (cloud-metadata IPs hard-denied unconditionally; private / loopback / link-local overridable per call), scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), IPv4-or-IPv6 NTP servers, DNS with IPv6 / DoH / DoT (private-CA trust pinning via `opts.ca`) / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
 - **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector, AWS CloudWatch Logs via SigV4), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).

package/lib/log-stream-webhook.js

@@ -168,9 +168,14 @@ function create(config) {
   }
 
   async function close() {
-    closed = true;
+    // Drain BEFORE flipping closed=true. _flush()'s while loop bails on
+    // !closed, so flipping the flag first leaves any buffered records
+    // stranded — the very records the operator queued just before
+    // calling shutdown(). Order: stop the timer, drain, then refuse
+    // any new enqueues by setting closed.
     if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
     await _flush();
+    closed = true;
   }
 
   function stats() {

package/lib/log-stream.js

@@ -79,6 +79,10 @@ var audit = lazyRequire(function () { return require("./audit"); });
 
 var initialized = false;
 var sinks = {};
+// Pending emit promises, tracked so shutdown can drain them before
+// closing sink fds. Without this, fire-and-forget emits queued just
+// before shutdown raced with close() and silently dropped records.
+var _inflight = new Set();
 var minLevel = "info";
 var incomingHandlers = [];
 
@@ -124,11 +128,14 @@ function emit(level, message, meta) {
 
   // Fire-and-forget to all sinks. Sink errors don't bubble — they're
   // captured by audit (system.log.sink-failure) so an external sink
-  // outage doesn't take down the app's request handlers.
+  // outage doesn't take down the app's request handlers. Pending
+  // emits are tracked in _inflight so shutdown() can drain them
+  // before closing fds (otherwise records queued just before
+  // shutdown would be lost when close() ran ahead of the microtask).
   Object.keys(sinks).forEach(function (name) {
     var sink = sinks[name];
     if (!_shouldEmit(level, sink.levelFilter)) return;
-    Promise.resolve()
+    var p = Promise.resolve()
       .then(function () { return sink.raw.emit(record); })
       .catch(function (e) {
         audit().safeEmit({
@@ -138,6 +145,8 @@ function emit(level, message, meta) {
           metadata: { sink: name, level: level },
         });
       });
+    _inflight.add(p);
+    p.then(function () { _inflight.delete(p); }, function () { _inflight.delete(p); });
   });
 }
 
@@ -183,6 +192,12 @@ async function deliverIncoming(payload, opts) {
 
 async function shutdown() {
   if (!initialized) return;
+  // Drain any in-flight emits before closing sink fds so records
+  // queued just before shutdown actually reach disk / the wire.
+  if (_inflight.size > 0) {
+    try { await Promise.all(Array.from(_inflight)); }
+    catch (_e) { /* sink errors already audited via the catch above */ }
+  }
   for (var name in sinks) {
     try {
       if (typeof sinks[name].raw.close === "function") await sinks[name].raw.close();

package/lib/mtls-engine-default.js

@@ -48,10 +48,103 @@ class MtlsEngineError extends FrameworkError {
   }
 }
 
-var CA_KEY_ALG    = { name: "ECDSA", namedCurve: "P-384" };
-var CA_SIG_ALG    = { name: "ECDSA", hash: "SHA-384" };
 var CA_KEY_USAGES = ["sign", "verify"];
 
+// Algorithm priority — each entry probed at first use; the first one
+// the vendored x509 library AND webcrypto can both honour wins.
+// Ordered highest-PQC-posture first so the engine self-upgrades the
+// moment the vendor bundle gains PQ-sig X.509 support.
+//
+// keyAlg: passed to webcrypto.subtle.generateKey + import
+// sigAlg: passed to x509.X509CertificateGenerator.create
+// label : surfaced via b.mtlsCa.status() so operators can audit
+//         which algorithm the in-flight CA generation is using
+var ALG_CANDIDATES = [
+  // Pure-PQC stateless hash-based — matches lib/audit-sign's posture.
+  // FIPS 205 (SPHINCS+ family). Awaiting node:tls + browser cert-store
+  // verification support; currently issuance-only on most stacks.
+  {
+    label:  "SLH-DSA-SHAKE-256f",
+    keyAlg: { name: "SLH-DSA-SHAKE-256f" },
+    sigAlg: { name: "SLH-DSA-SHAKE-256f" },
+    posture: "pqc-pure",
+  },
+  {
+    label:  "SLH-DSA-SHAKE-128f",
+    keyAlg: { name: "SLH-DSA-SHAKE-128f" },
+    sigAlg: { name: "SLH-DSA-SHAKE-128f" },
+    posture: "pqc-pure",
+  },
+  // Pure-PQC lattice — FIPS 204 (Dilithium family). Smaller than SLH-DSA,
+  // accepted by the same emerging cert-store deployments.
+  {
+    label:  "ML-DSA-87",
+    keyAlg: { name: "ML-DSA-87" },
+    sigAlg: { name: "ML-DSA-87" },
+    posture: "pqc-pure",
+  },
+  {
+    label:  "ML-DSA-65",
+    keyAlg: { name: "ML-DSA-65" },
+    sigAlg: { name: "ML-DSA-65" },
+    posture: "pqc-pure",
+  },
+  // Documented bridge — used until cert ecosystems verify the above.
+  // The framework's hybrid KEM posture (X25519MLKEM768) covers handshake
+  // KEX; these certs sign with ECDSA P-384 + SHA-384.
+  {
+    label:  "ECDSA-P384-SHA384",
+    keyAlg: { name: "ECDSA", namedCurve: "P-384" },
+    sigAlg: { name: "ECDSA", hash: "SHA-384" },
+    posture: "classical",
+  },
+];
+
+// First-call probe cache. Re-runs after engine reload (test reset path).
+var _selectedAlg = null;
+
+async function _probeCandidate(c) {
+  try {
+    var pair = await webcrypto.subtle.generateKey(c.keyAlg, true, CA_KEY_USAGES);
+    if (!pair || !pair.publicKey) return false;
+    // Also confirm the x509 generator accepts the sigAlg by issuing a
+    // throwaway self-signed cert. Some keyAlgs work in webcrypto but
+    // aren't yet wired through @peculiar/x509's encoder — without this
+    // round-trip we'd select an algorithm we can't actually mint certs
+    // with and hit a confusing failure on first issuance.
+    await x509.X509CertificateGenerator.create({
+      serialNumber: "01",
+      subject:      "CN=probe",
+      issuer:       "CN=probe",
+      notBefore:    new Date(),
+      notAfter:     new Date(Date.now() + 1000),
+      signingAlgorithm: c.sigAlg,
+      publicKey:    pair.publicKey,
+      signingKey:   pair.privateKey,
+    });
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+async function _selectAlgorithm() {
+  if (_selectedAlg) return _selectedAlg;
+  for (var i = 0; i < ALG_CANDIDATES.length; i++) {
+    var c = ALG_CANDIDATES[i];
+    var ok = await _probeCandidate(c);
+    if (ok) { _selectedAlg = c; return c; }
+  }
+  // Should never happen — ECDSA-P384-SHA384 is universal.
+  throw new MtlsEngineError("mtls-engine/no-algorithm",
+    "no candidate algorithm passed the webcrypto + x509 probe");
+}
+
+// Backwards-compat shape for callers that read these directly. Resolved
+// lazily so the algorithm choice is the first-probe result.
+var CA_KEY_ALG = null;
+var CA_SIG_ALG = null;
+
 var P12_CONTENT_ENC = { name: "AES-CBC", length: 256 };
 var P12_KDF_HASH    = "SHA-512";
 var P12_MAC_HASH    = "SHA-512";
@@ -63,6 +156,7 @@ var DEFAULT_CA_NAME     = "blamejs CA";
 var BAG_ID_KEY          = "1.2.840.113549.1.12.10.1.2"; // pkcs-12-pkcs-8ShroudedKeyBag
 var BAG_ID_CERT         = "1.2.840.113549.1.12.10.1.3"; // pkcs-12-certBag
 var EKU_CLIENT_AUTH_OID = "1.3.6.1.5.5.7.3.2";
+var EKU_SERVER_AUTH_OID = "1.3.6.1.5.5.7.3.1";
 
 function _pemBlock(label, der) {
   var b64 = Buffer.from(der).toString("base64");
@@ -106,6 +200,8 @@ async function generateCa(opts) {
     ? Math.floor(opts.generation) : 1;
   var caName = opts.name || DEFAULT_CA_NAME;
 
+  var alg = await _selectAlgorithm();
+  CA_KEY_ALG = alg.keyAlg; CA_SIG_ALG = alg.sigAlg;
   var keys = await webcrypto.subtle.generateKey(CA_KEY_ALG, true, CA_KEY_USAGES);
   var now  = new Date();
   var ca = await x509.X509CertificateGenerator.createSelfSigned({
@@ -137,12 +233,58 @@ async function signClientCert(opts) {
     ? Math.floor(opts.validityDays) : LEAF_DEFAULT_DAYS;
   var cn = _normaliseCn(opts.cn);
 
+  // Extended Key Usage: defaults to clientAuth (the historical behaviour).
+  // Operators issuing server certs for inbound mTLS reverse-proxy fronts
+  // pass `usage: "server"` (sets serverAuth EKU), or `usage: "both"`
+  // (clientAuth + serverAuth — dual-purpose certs for service-to-service
+  // mTLS where the same workload is both initiator and acceptor).
+  var usage = opts.usage || "client";
+  var ekuOids = [];
+  if (usage === "client" || usage === "both") ekuOids.push(EKU_CLIENT_AUTH_OID);
+  if (usage === "server" || usage === "both") ekuOids.push(EKU_SERVER_AUTH_OID);
+  if (ekuOids.length === 0) {
+    throw new MtlsEngineError("mtls-engine/bad-usage",
+      "signClientCert: opts.usage must be 'client' | 'server' | 'both', got " +
+      JSON.stringify(opts.usage));
+  }
+
+  // Subject Alternative Names — required for serverAuth (modern TLS
+  // clients only honor SANs, not CN). Accept opts.sans as an array of
+  // strings (DNS names by default; "DNS:foo" / "IP:1.2.3.4" forms also).
+  var sanExt = null;
+  if (Array.isArray(opts.sans) && opts.sans.length > 0) {
+    var sanEntries = opts.sans.map(function (s) {
+      var str = String(s);
+      if (/^DNS:/i.test(str)) return { type: "dns", value: str.slice(4) };
+      if (/^IP:/i.test(str))  return { type: "ip",  value: str.slice(3) };
+      // Bare entries default to DNS — matches operator expectation
+      return { type: "dns", value: str };
+    });
+    sanExt = new x509.SubjectAlternativeNameExtension(sanEntries);
+  } else if (usage === "server" || usage === "both") {
+    // serverAuth without a SAN is unverifiable by modern TLS clients.
+    // Auto-add the CN as a DNS SAN so the most common case "just works".
+    sanExt = new x509.SubjectAlternativeNameExtension([{ type: "dns", value: cn }]);
+  }
+
+  var alg = await _selectAlgorithm();
+  CA_KEY_ALG = alg.keyAlg; CA_SIG_ALG = alg.sigAlg;
   var caKey   = await _importPemPrivateKey(opts.caKeyPem, CA_KEY_ALG, ["sign"]);
   var caCert  = _parseCertPem(opts.caCertPem);
   var clientKeys = await webcrypto.subtle.generateKey(CA_KEY_ALG, true, CA_KEY_USAGES);
 
   var now      = new Date();
   var notAfter = new Date(now.getTime() + C.TIME.days(validityDays));
+  var extensions = [
+    new x509.BasicConstraintsExtension(false, undefined, true),
+    new x509.KeyUsagesExtension(
+      x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyEncipherment,
+      true
+    ),
+    new x509.ExtendedKeyUsageExtension(ekuOids, true),
+  ];
+  if (sanExt) extensions.push(sanExt);
+
   var clientCert = await x509.X509CertificateGenerator.create({
     serialNumber: crypto.generateToken(16),
     subject: "CN=" + cn,
@@ -152,14 +294,7 @@ async function signClientCert(opts) {
     signingAlgorithm: CA_SIG_ALG,
     publicKey: clientKeys.publicKey,
     signingKey: caKey,
-    extensions: [
-      new x509.BasicConstraintsExtension(false, undefined, true),
-      new x509.KeyUsagesExtension(
-        x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyEncipherment,
-        true
-      ),
-      new x509.ExtendedKeyUsageExtension([EKU_CLIENT_AUTH_OID], true),
-    ],
+    extensions: extensions,
   });
   var pem = await _exportKeyPairToPem(clientKeys);
   return {
@@ -168,6 +303,7 @@ async function signClientCert(opts) {
     ca:        opts.caCertPem,
     issuedAt:  now.toISOString(),
     expiresAt: notAfter.toISOString(),
+    usage:     usage,
   };
 }
 
@@ -265,7 +401,18 @@ async function packageP12(opts) {
 
 function algorithmEnvelope() {
   return {
-    cert: { keyAlg: CA_KEY_ALG, sigAlg: CA_SIG_ALG },
+    cert: {
+      keyAlg:   CA_KEY_ALG,
+      sigAlg:   CA_SIG_ALG,
+      label:    _selectedAlg && _selectedAlg.label,
+      posture:  _selectedAlg && _selectedAlg.posture,
+      // Operators querying status() before any cert has been issued
+      // get the candidate priority list — the engine probes lazily so
+      // the chosen algorithm isn't known until first use.
+      priority: ALG_CANDIDATES.map(function (c) {
+        return { label: c.label, posture: c.posture };
+      }),
+    },
     p12:  {
       contentEncryption: P12_CONTENT_ENC,
       kdfHash: P12_KDF_HASH,

package/lib/network-dns.js

@@ -136,7 +136,7 @@ function setCacheTtlMs(ms, negativeMs) {
 
 function useDnsOverHttps(opts) {
   opts = opts || {};
-  validateOpts(opts, ["provider", "url", "method"], "dns.useDnsOverHttps");
+  validateOpts(opts, ["provider", "url", "method", "ca"], "dns.useDnsOverHttps");
   var url = opts.url;
   if (!url && opts.provider) {
     var p = String(opts.provider).toLowerCase();
@@ -155,22 +155,34 @@ function useDnsOverHttps(opts) {
       "dns.useDnsOverHttps: method must be 'GET' | 'POST' | undefined (auto), got " +
       JSON.stringify(method));
   }
-  STATE.doh = { url: url, method: method };
+  if (opts.ca !== undefined && opts.ca !== null &&
+      !Buffer.isBuffer(opts.ca) && typeof opts.ca !== "string" && !Array.isArray(opts.ca)) {
+    throw new DnsError("dns/bad-doh-ca",
+      "dns.useDnsOverHttps: ca must be a PEM string, Buffer, or array of either");
+  }
+  STATE.doh = { url: url, method: method, ca: opts.ca || null };
   _clearCache();
   _emitObs("network.dns.doh.set", { url: url, method: method || "auto" });
 }
 
 function useDnsOverTls(opts) {
   opts = opts || {};
-  validateOpts(opts, ["host", "port", "servername"], "dns.useDnsOverTls");
+  validateOpts(opts, ["host", "port", "servername", "ca"], "dns.useDnsOverTls");
   if (typeof opts.host !== "string" || opts.host.length === 0) {
     throw new DnsError("dns/bad-dot-host", "dns.useDnsOverTls: host required");
   }
+  if (opts.ca !== undefined && opts.ca !== null &&
+      !Buffer.isBuffer(opts.ca) && typeof opts.ca !== "string" && !Array.isArray(opts.ca)) {
+    throw new DnsError("dns/bad-dot-ca",
+      "dns.useDnsOverTls: ca must be a PEM string, Buffer, or array of either");
+  }
   STATE.dot = {
     host:       opts.host,
     port:       opts.port || 853,
     servername: opts.servername || opts.host,
+    ca:         opts.ca || null,
   };
+  _resetDotPool();
   _clearCache();
   _emitObs("network.dns.dot.set", { host: STATE.dot.host, port: STATE.dot.port });
 }
@@ -278,6 +290,7 @@ async function _dohLookup(host, family) {
       minVersion: "TLSv1.3",
       ecdhCurve:  C.TLS_GROUP_CURVE_STR,
     };
+    if (STATE.doh.ca) reqOpts.ca = STATE.doh.ca;
     if (usePost) {
       reqOpts.headers["content-type"]   = "application/dns-message";
       reqOpts.headers["content-length"] = enc.buf.length;
@@ -317,14 +330,19 @@ function _dotPoolKey() {
 }
 
 function _dotConnect() {
-  var sock = tls.connect({
+  var connectOpts = {
     host:       STATE.dot.host,
     port:       STATE.dot.port,
     servername: STATE.dot.servername,
     minVersion: "TLSv1.3",
     ecdhCurve:  C.TLS_GROUP_CURVE_STR,
-  });
-  sock.unref && sock.unref();
+  };
+  if (STATE.dot.ca) connectOpts.ca = STATE.dot.ca;
+  var sock = tls.connect(connectOpts);
+  // The pool entry is ref()'d while a query is in flight and unref()'d
+  // when idle — _dotLookup toggles this around its query. Calling
+  // unref() unconditionally here let node exit during a normal lookup
+  // when no other I/O kept the event loop alive.
   return sock;
 }
 
@@ -352,9 +370,18 @@ async function _dotLookup(host, family) {
       idle:       true,
       ready:      new Promise(function (res, rej) {
         sock.once("secureConnect", function () { res(); });
-        sock.once("error", function (e) { rej(e); });
+        sock.once("error", function (e) {
+          rej(new DnsError("dns/dot-handshake",
+            "DoT TLS handshake to " + STATE.dot.host + ":" + STATE.dot.port +
+            " failed: " + ((e && e.message) || String(e))));
+        });
       }),
     };
+    // Pre-attach a no-op observer so a handshake failure isn't reported
+    // as an unhandledRejection in the window between this assignment
+    // and the first lookup awaiting entry.ready. The real reject path
+    // routes through _dotLookup's then(_, onErr) handler below.
+    entry.ready.catch(function () { /* observed; routed via per-lookup handler */ });
     _dotPool.set(key, entry);
     sock.on("error", function () { _dotEvict(key); });
     sock.on("close", function () { if (_dotPool.get(key) === entry) _dotPool.delete(key); });
@@ -365,6 +392,8 @@ async function _dotLookup(host, family) {
   entry._tail = waitTicket.then(function () {
     return new Promise(function (resolve, reject) {
       entry.idle = false;
+      // Hold the event loop open while a query is in flight.
+      try { entry.sock.ref(); } catch (_e) {}
       Promise.resolve(entry.ready).then(function () {
         var lenBuf = Buffer.alloc(2);
         lenBuf.writeUInt16BE(enc.buf.length, 0);
@@ -378,6 +407,9 @@ async function _dotLookup(host, family) {
           entry.sock.removeListener("error", onErr);
           entry.idle = true;
           entry.lastUsedAt = Date.now();
+          // Release the event-loop hold so an idle pool socket doesn't
+          // keep node alive between queries.
+          try { entry.sock.unref(); } catch (_e) {}
           if (err) reject(err); else resolve(val);
         }
         function onData(chunk) {
@@ -398,6 +430,13 @@ async function _dotLookup(host, family) {
         entry.sock.on("error", onErr);
         entry.sock.write(lenBuf);
         entry.sock.write(enc.buf);
+      }, function (handshakeErr) {
+        // entry.ready rejected (TLS handshake / cert verification failure).
+        // Route as the lookup's reject so callers see a real DnsError
+        // instead of an unhandledRejection from the TLSSocket event.
+        entry.idle = true;
+        try { entry.sock.unref(); } catch (_e) {}
+        reject(handshakeErr);
       });
     });
   });

package/lib/ntp-check.js

@@ -86,7 +86,11 @@ function querySingle(server, opts) {
   var timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
 
   return new Promise(function (resolve, reject) {
-    var socket = dgram.createSocket("udp4");
+    // udp6 for IPv6 literals (`::1`, `fd00::…`), udp4 otherwise. Without
+    // this branch a query to an IPv6 NTP host fails with EINVAL because
+    // you can't send IPv6 packets through a udp4 socket.
+    var family = server.indexOf(":") !== -1 ? "udp6" : "udp4";
+    var socket = dgram.createSocket(family);
     var settled = false;
 
     function done(err, result) {

package/lib/redis-client.js

@@ -162,6 +162,17 @@ function create(opts) {
   var commandTimeoutMs = Number(opts.commandTimeoutMs) || 10000;
   var maxReconnectAttempts = opts.maxReconnectAttempts === undefined ? 10
                                                                     : Number(opts.maxReconnectAttempts);
+  // TLS verification controls. Operators using rediss:// against private
+  // CAs (managed Redis services, on-prem clusters with internal PKI)
+  // pin the trust roots via opts.ca; rejectUnauthorized stays on by
+  // default — never weaken verification to make a connection succeed.
+  var caBundle = opts.ca || null;
+  // SNI is only legal for hostnames; IP literals must omit servername.
+  var servername = opts.servername;
+  if (servername === undefined) {
+    servername = (/^\d+\.\d+\.\d+\.\d+$/.test(host) || host.indexOf(":") !== -1)
+                   ? undefined : host;
+  }
 
   var socket = null;
   var connected = false;
@@ -260,7 +271,10 @@ function create(opts) {
           reject(_err("CONNECT", "redis connect failed: " + ((e && e.message) || String(e))));
         }
         if (useTls) {
-          sock = tls.connect({ host: host, port: port, servername: host }, onOk);
+          var tlsConnectOpts = { host: host, port: port };
+          if (servername) tlsConnectOpts.servername = servername;
+          if (caBundle)   tlsConnectOpts.ca = caBundle;
+          sock = tls.connect(tlsConnectOpts, onOk);
         } else {
           sock = net.connect({ host: host, port: port }, onOk);
         }

package/lib/ssrf-guard.js

@@ -339,6 +339,25 @@ async function checkUrl(url, opts) {
     var category = classify(addr);
     if (!category) continue;
 
+    // Cloud-metadata IPs are NEVER allowed — they leak instance
+    // credentials (AWS IMDS, GCP metadata, Azure IMDS) and a blanket
+    // allowInternal bypass would let any compromised request exfiltrate
+    // them. Operators with a legitimate need to talk to the metadata
+    // service do it through the cloud SDK with explicit IAM, never
+    // through the framework's outbound HTTP. Same hard-deny applies
+    // to allowInternal=[cidr-list]: the list grants exception for
+    // private ranges, not for the metadata IP that happens to fall
+    // inside link-local.
+    if (category === "cloud-metadata") {
+      throw new ErrorClass(
+        "URL '" + parsed.toString() + "' resolves to " + addr +
+        " (cloud-metadata) — blocked unconditionally; allowInternal does NOT override " +
+        "this class because metadata IPs leak instance credentials",
+        "ssrf-guard/blocked-cloud-metadata",
+        { url: parsed.toString(), ip: addr, category: category }
+      );
+    }
+
     if (allowInternal === true) continue;
     if (Array.isArray(allowInternal) && allowInternal.some(function (cidr) {
       return cidrContains(cidr, addr);

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:2f9c38f8-03fa-4e5b-aa89-79d42c1df348",
+  "serialNumber": "urn:uuid:438bf95a-273c-4fba-b130-bb7dddcdb3de",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T15:55:03.075Z",
+    "timestamp": "2026-05-02T18:04:26.378Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.27",
+      "bom-ref": "@blamejs/core@0.6.29",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.27",
+      "version": "0.6.29",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.27",
+      "purl": "pkg:npm/%40blamejs/core@0.6.29",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.27",
+      "ref": "@blamejs/core@0.6.29",
       "dependsOn": []
     }
   ]