@blamejs/core 0.7.79 → 0.7.81

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.81** (2026-05-06) — `b.middleware.hostAllowlist` — DNS rebinding defense. Refuses requests whose `Host` header doesn't match the operator-supplied allowlist; the DNS rebinding chain (attacker DNS flips evil.com → 127.0.0.1, browser still believes the URL string says "evil.com" so same-origin policy lets the JS read the response, but the operator's localhost is what actually serves) is closed by checking the post-DNS-resolution `Host` header on the framework's side. **`b.middleware.hostAllowlist({ hosts, denyStatus?, denyBody?, audit? })`** — operators pass an allowlist of canonical Host values (with or without port). Wildcard-leading entries (`*.example.com`) match any single label; `app.sub.example.com` does NOT match `*.example.com` (multi-label rejected by design — a wildcard certificate authority issues only single-label intermediate). Entries without a port match any port; entries with a port require exact match. Default `denyStatus: 421` (RFC 7540 §9.1.2 "Misdirected Request"); default `denyBody: "Misdirected Request"`. Audit emits `network.host_allowlist.denied` with the reason (`missing-host` / `host-not-in-allowlist`) and the actual Host value for triage. Operators running explicitly-public services that accept arbitrary subdomains (multi-tenant forum shapes) skip this middleware entirely; there's no per-request opt-out.
+
+- **0.7.80** (2026-05-06) — `b.middleware.securityTxt` (RFC 9116) + SQLite `secure_delete=ON` at DB boot. **`b.middleware.securityTxt({ contact, expires, encryption?, policy?, ack?, preferredLanguages?, hiring?, canonical?, alsoAtRoot?, audit? })`** serves a static body at `/.well-known/security.txt` (and root `/security.txt` when `alsoAtRoot: true`) per RFC 9116. Operators wire it on their app so security researchers know where to find the disclosure policy. The `Contact:` and `Expires:` fields are REQUIRED per §2.5; the framework throws at config-time when either is missing AND when `expires` is in the past (RFC 9116 §2.5.5). All field values are CR/LF/NUL-screened (header injection defense). Body is built once at create() and served with `Content-Length` + `Cache-Control: public, max-age=86400` + `X-Content-Type-Options: nosniff`. **SQLite `PRAGMA secure_delete=ON`** is now applied at `b.db.init` time alongside the existing PRAGMA block. SQLite normally just unlinks rows from the B-tree; the underlying page bytes survive on disk until a new write reuses the slot. With `secure_delete=ON`, freed pages are overwritten with zeros so a forensic recovery against the encrypted database file can't reconstruct deleted rows. The cost is one extra write per delete — already dominated by the framework's audit-chain emissions on every DSR erase / cascade fan-out.
+
 - **0.7.79** (2026-05-06) — PQC TLS handshake key shares + DB hardening sweep (3 items). **`b.network.tls.pqc`** — operator-facing TLS 1.3 key-share configuration. The framework's app-layer envelope has been PQC-first since v0.7.28 (ML-KEM-1024 + X25519 hybrid for sealed records); this slice extends PQC posture down to the **TLS handshake itself**. `b.network.tls.pqc.setKeyShares(["X25519MLKEM768", "X25519", "secp256r1"])` configures the TLS 1.3 key-share groups the framework's `https.Server` / `https.Agent` advertises. The first listed group is the operator priority; the peer picks the first mutually supported entry. **`X25519MLKEM768`** is the IETF draft-kwiatkowski-tls-ecdhe-mlkem-02 hybrid KEM that negotiates post-quantum + classical in one handshake — forward-secrecy survives both classical-CRQC and future quantum cryptanalysis. Default list is `["X25519MLKEM768", "X25519", "secp256r1"]` so the framework attempts hybrid first, falls back to classical X25519 with peers that don't support the hybrid (most of the public web today), and to `secp256r1` for legacy peers. **`b.network.tls.applyToContext({ base })`** now threads the configured key-share list through as the `groups` option to Node's TLS context (operators who explicitly set `groups` in their `base` config keep the override). Operators wanting classical-only call `b.network.tls.pqc.setKeyShares(["X25519"])`; calling `.resetKeyShares()` restores the default. Requires Node 24+ with OpenSSL 3.5+ for the X25519MLKEM768 group; older Node falls back silently to the classical entries. **DB hardening: PRAGMA integrity_check at boot** — `b.db.init` now runs `PRAGMA integrity_check` after the existing PRAGMA block and refuses boot if SQLite reports anything other than `"ok"`. Catches B-tree corruption at boot rather than letting it surface mid-query when the engine stumbles on a bad page. Skip via `opts.skipIntegrityCheck: true` for tmpfs-only fixtures (audited reason). **DB hardening: migration-lock holder ID boot token** — `lib/external-db-migrate.js:_lockHolderId()` now appends a per-process random 8-byte boot token, so a recycled PID-on-hostname slot after a container restart can't be misattributed back to the new boot when reading stale lock rows. Closes the PID-reuse-across-container-restart concurrent-ownership window flagged in the v0.7.67 audit batch.
 
 - **0.7.78** (2026-05-06) — `b.cloudEvents.wrap` / `.parse` — CloudEvents 1.0 envelope (cloudevents.io/spec/v1.0). Vendor-neutral event-format spec adopted by AWS EventBridge, Knative, Azure Event Grid, Google Eventarc, Datadog, and the broader CNCF event ecosystem; operators wrap outbound events from webhook / pubsub / queue boundaries to interop with these consumers without each consumer learning a bespoke shape. **`b.cloudEvents.wrap({ source, type, data?, subject?, time?, id?, datacontenttype?, dataschema?, extensions? })`** produces a CloudEvents 1.0 envelope: required attributes (`id` auto-minted as RFC 4122 v4 UUID when omitted, `source`, `specversion="1.0"`, `type`, `time` auto-set to `new Date().toISOString()`), optional attributes (`subject`, `datacontenttype` auto-set to `"application/json"` when `data` is JSON-serializable or `"application/octet-stream"` when `data` is a `Buffer` — base64-encoded into `data_base64`, `dataschema`), plus operator-defined extension attributes that conform to the §3.1 naming rules (lowercase ASCII alnum, 1-20 chars). **`b.cloudEvents.parse(envelope)`** validates the envelope shape and returns a structured form with `extensions` surfaced as a separate object so consumers can route on operator-defined fields without grepping the envelope. Refuses `data` + `data_base64` together (CloudEvents §3.1.1), unsupported specversion, missing required attributes, malformed extension names. **Test cleanup**: the `testAuditSafeEmitRedacts` smoke fixture from v0.7.75 now registers the `test` audit namespace before emitting so the audit handler's noise log line ("namespace 'test' is not registered") doesn't appear in CI smoke output.

package/lib/db.js

@@ -681,6 +681,15 @@ async function init(opts) {
   // structured `foreignKeys` declarations actually constrain writes.
   runSql(database, "PRAGMA foreign_keys=ON");
 
+  // PRAGMA secure_delete=ON — SQLite normally just unlinks rows from
+  // the B-tree; the underlying page bytes survive on disk until a new
+  // write reuses the slot. With secure_delete=ON, freed pages are
+  // overwritten with zeros so a forensic recovery against the file
+  // can't reconstruct deleted rows. The cost is one extra write per
+  // delete, which the framework's audit-and-DSR-erase path already
+  // dominates with audit-chain emissions and cascade fan-out.
+  runSql(database, "PRAGMA secure_delete=ON");
+
   // PRAGMA integrity_check — refuse boot on B-tree corruption (per
   // audit-batch finding). SQLite returns "ok" for a healthy database;
   // any other result means corruption. Catching it at boot beats

package/lib/middleware/host-allowlist.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * host-allowlist — DNS rebinding defense.
+ *
+ * Refuses requests whose `Host` header doesn't match the operator-
+ * supplied allowlist. The DNS rebinding attack chain is:
+ *
+ *   1. Attacker sets a short-TTL DNS record for evil.com pointing
+ *      at their own server.
+ *   2. Victim's browser visits attacker's page; the page issues
+ *      fetch() requests to evil.com.
+ *   3. Attacker's DNS now answers evil.com → 127.0.0.1 (or the
+ *      operator's internal IP).
+ *   4. Browser, applying same-origin policy on the URL string,
+ *      thinks fetch() is hitting evil.com — but the connection
+ *      lands on the operator's localhost / internal service.
+ *   5. The operator's service serves whatever it would serve to
+ *      its own admin UI; the JS reads the response.
+ *
+ * Defense: refuse the request unless the `Host` header (the part
+ * the operator's server actually sees) matches a known origin.
+ *
+ *   var allow = b.middleware.hostAllowlist({
+ *     hosts:        ["app.example.com", "app.example.com:443"],
+ *     denyStatus:   421,           // RFC 7540 §9.1.2 "Misdirected Request"
+ *     denyBody:     "Misdirected Request",
+ *     audit:        true,
+ *   });
+ *   router.use(allow);
+ *
+ * Operators behind a CDN / proxy that rewrites the Host header set
+ * `hosts` to the post-rewrite values. Wildcard-leading entries
+ * (`*.example.com`) match any single label. Localhost is explicitly
+ * allowed only when the operator lists it.
+ *
+ * Operators running an explicitly-public service (anyone-can-host-
+ * the-domain shapes — e.g. a forum that serves arbitrary subdomains)
+ * skip this middleware entirely; there's no opt-out per request.
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var HostAllowlistError = defineClass("HostAllowlistError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("../audit"); });
+
+function _normalizeHostEntry(s) {
+  // Lowercase + strip whitespace. Per RFC 7230 §5.4 the Host header is
+  // case-insensitive on the host portion.
+  if (typeof s !== "string") return null;
+  var t = s.trim().toLowerCase();
+  if (t.length === 0) return null;
+  return t;
+}
+
+// Match a single allowlist entry against an actual Host header value.
+// Wildcards: `*.example.com` matches `app.example.com` but not
+// `app.sub.example.com` (single-label only). Exact host:port match
+// is supported when the entry includes a port; entries without a port
+// match any port.
+function _matches(entry, actual) {
+  if (entry === actual) return true;
+  // Wildcard prefix
+  if (entry.indexOf("*.") === 0) {
+    var suffix = entry.slice(1);                 // ".example.com"
+    var actualHost = actual.split(":")[0];
+    if (actualHost.length <= suffix.length) return false;
+    if (actualHost.slice(-suffix.length) !== suffix) return false;
+    var prefix = actualHost.slice(0, actualHost.length - suffix.length);
+    if (prefix.indexOf(".") !== -1) return false;  // single-label
+    return true;
+  }
+  // Port-stripped equality — entry without port matches any port
+  if (entry.indexOf(":") === -1 && actual.indexOf(":") !== -1) {
+    var actualNoPort = actual.split(":")[0];
+    return entry === actualNoPort;
+  }
+  return false;
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.hostAllowlist", HostAllowlistError);
+  validateOpts(opts, [
+    "hosts", "denyStatus", "denyBody", "audit",
+  ], "middleware.hostAllowlist");
+
+  if (!Array.isArray(opts.hosts) || opts.hosts.length === 0) {
+    throw new HostAllowlistError("host-allowlist/no-hosts",
+      "middleware.hostAllowlist: opts.hosts must be a non-empty array of allowed Host header values");
+  }
+  var hosts = [];
+  for (var i = 0; i < opts.hosts.length; i += 1) {
+    var n = _normalizeHostEntry(opts.hosts[i]);
+    if (!n) {
+      throw new HostAllowlistError("host-allowlist/bad-host",
+        "middleware.hostAllowlist: hosts[" + i + "] is not a non-empty string");
+    }
+    hosts.push(n);
+  }
+
+  var denyStatus = (typeof opts.denyStatus === "number") ? opts.denyStatus : 421;  // allow:raw-byte-literal — HTTP 421 status
+  var denyBody = typeof opts.denyBody === "string" ? opts.denyBody : "Misdirected Request";
+  var auditOn = opts.audit !== false;
+
+  return function hostAllowlistMiddleware(req, res, next) {
+    var raw = req.headers && req.headers.host;
+    if (typeof raw !== "string" || raw.length === 0) {
+      // RFC 7230 §5.4 — a request without a Host header is malformed
+      // for HTTP/1.1; HTTP/2 maps :authority into req.headers.host
+      // automatically. Reject either shape.
+      _deny(res, denyStatus, denyBody);
+      _emitDenied(req, "missing-host");
+      return;
+    }
+    var actual = raw.toLowerCase();
+    var matched = false;
+    for (var hi = 0; hi < hosts.length; hi += 1) {
+      if (_matches(hosts[hi], actual)) { matched = true; break; }
+    }
+    if (!matched) {
+      _deny(res, denyStatus, denyBody);
+      _emitDenied(req, "host-not-in-allowlist", actual);
+      return;
+    }
+    return next();
+  };
+
+  function _deny(res, status, body) {
+    if (res.headersSent) return;
+    res.writeHead(status, {
+      "Content-Type":   "text/plain; charset=utf-8",
+      "Content-Length": Buffer.byteLength(body),
+    });
+    res.end(body);
+  }
+
+  function _emitDenied(req, reason, actual) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:  "network.host_allowlist.denied",
+        outcome: "fail",
+        actor:   { clientIp: requestHelpers.clientIp(req) },
+        metadata: {
+          reason:  reason,
+          host:    actual || null,
+          route:   req.url,
+        },
+      });
+    } catch (_e) { /* drop-silent — observability sink failure */ }
+  }
+}
+
+module.exports = {
+  create: create,
+};

package/lib/middleware/index.js

@@ -33,6 +33,7 @@ var fetchMetadata = require("./fetch-metadata");
 var gpc = require("./gpc");
 var headers = require("./headers");
 var health = require("./health");
+var hostAllowlist = require("./host-allowlist");
 var networkAllowlist = require("./network-allowlist");
 var rateLimit = require("./rate-limit");
 var requestId = require("./request-id");
@@ -40,6 +41,7 @@ var requestLog = require("./request-log");
 var requireAal = require("./require-aal");
 var requireAuth = require("./require-auth");
 var securityHeaders = require("./security-headers");
+var securityTxt = require("./security-txt");
 var sse = require("./sse");
 
 module.exports = {
@@ -62,11 +64,13 @@ module.exports = {
   compression:      compression.create,
   cookies:          cookies.create,
   cspNonce:         cspNonce.create,
+  securityTxt:      securityTxt.create,
   sse:              sse.create,
   requestLog:       requestLog.create,
   apiEncrypt:       apiEncrypt,
   dbRoleFor:        dbRoleFor.create,
   dpop:             dpop.create,
+  hostAllowlist:    hostAllowlist.create,
   networkAllowlist: networkAllowlist.create,
 
   // Module exports for advanced use (constants, raw factory access)
@@ -87,11 +91,13 @@ module.exports = {
     health:           health,
     compression:      compression,
     cspNonce:         cspNonce,
+    securityTxt:      securityTxt,
     sse:              sse,
     requestLog:       requestLog,
     apiEncrypt:       apiEncrypt,
     dbRoleFor:        dbRoleFor,
     dpop:             dpop,
+    hostAllowlist:    hostAllowlist,
     networkAllowlist: networkAllowlist,
   },
 };

package/lib/middleware/security-txt.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * security-txt middleware — RFC 9116 /.well-known/security.txt emitter.
+ *
+ * Operators wire this on their app so security researchers know where
+ * to find the disclosure policy. The middleware serves a static body
+ * at `/.well-known/security.txt` (and root `/security.txt` when
+ * opts.alsoAtRoot is true) per RFC 9116 §3 ("Format" — text/plain
+ * with one field per line, "Field: value" pairs).
+ *
+ *   var txt = b.middleware.securityTxt({
+ *     contact:   ["mailto:security@example.com", "https://example.com/security/report"],
+ *     expires:   "2027-01-01T00:00:00Z",
+ *     encryption:["https://example.com/pgp.asc"],
+ *     policy:    "https://example.com/security/policy",
+ *     ack:       "https://example.com/security/hall-of-fame",
+ *     preferredLanguages: ["en"],
+ *   });
+ *   router.use(txt);
+ *
+ * Per RFC 9116 §2.5, `Contact:` and `Expires:` are REQUIRED. The
+ * middleware throws at config-time when either is missing.
+ *
+ * Per §2.5.1, `Expires:` MUST be a future timestamp; the framework
+ * also throws when the operator-supplied `expires` is in the past.
+ */
+
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var SecurityTxtError = defineClass("SecurityTxtError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _arrayOfStrings(value, label) {
+  if (value === undefined || value === null) return [];
+  var arr = Array.isArray(value) ? value : [value];
+  for (var i = 0; i < arr.length; i += 1) {
+    if (typeof arr[i] !== "string" || arr[i].length === 0) {
+      throw new SecurityTxtError("security-txt/bad-" + label,
+        label + "[" + i + "] must be a non-empty string");
+    }
+    if (/[\r\n\0]/.test(arr[i])) {
+      throw new SecurityTxtError("security-txt/bad-" + label,
+        label + "[" + i + "] contains forbidden CR/LF/NUL");
+    }
+  }
+  return arr;
+}
+
+function _isoFuture(s) {
+  if (typeof s !== "string" || s.length === 0) return false;
+  var d = new Date(s);
+  if (isNaN(d.getTime())) return false;
+  return d.getTime() > Date.now();
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.securityTxt", SecurityTxtError);
+  validateOpts(opts, [
+    "contact", "expires", "encryption", "policy", "ack",
+    "preferredLanguages", "hiring", "canonical",
+    "alsoAtRoot", "audit",
+  ], "middleware.securityTxt");
+
+  var contact = _arrayOfStrings(opts.contact, "contact");
+  if (contact.length === 0) {
+    throw new SecurityTxtError("security-txt/no-contact",
+      "middleware.securityTxt: contact is required (RFC 9116 §2.5.3)");
+  }
+  validateOpts.requireNonEmptyString(opts.expires,
+    "middleware.securityTxt: expires", SecurityTxtError, "security-txt/no-expires");
+  if (!_isoFuture(opts.expires)) {
+    throw new SecurityTxtError("security-txt/expires-in-past",
+      "middleware.securityTxt: expires must be a future ISO 8601 timestamp (got '" + opts.expires + "')");
+  }
+  var encryption = _arrayOfStrings(opts.encryption, "encryption");
+  var policy     = _arrayOfStrings(opts.policy,     "policy");
+  var ack        = _arrayOfStrings(opts.ack,        "ack");
+  var canonical  = _arrayOfStrings(opts.canonical,  "canonical");
+  var hiring     = _arrayOfStrings(opts.hiring,     "hiring");
+  var prefLangs  = _arrayOfStrings(opts.preferredLanguages, "preferredLanguages");
+
+  // Build the body once at create time — the response is identical
+  // for every request and the Content-Length is known up front.
+  var lines = [];
+  for (var i = 0; i < contact.length; i += 1) lines.push("Contact: " + contact[i]);
+  lines.push("Expires: " + opts.expires);
+  for (var ei = 0; ei < encryption.length; ei += 1) lines.push("Encryption: " + encryption[ei]);
+  for (var pi = 0; pi < policy.length; pi += 1) lines.push("Policy: " + policy[pi]);
+  for (var ai = 0; ai < ack.length; ai += 1) lines.push("Acknowledgments: " + ack[ai]);
+  for (var ci = 0; ci < canonical.length; ci += 1) lines.push("Canonical: " + canonical[ci]);
+  for (var hi = 0; hi < hiring.length; hi += 1) lines.push("Hiring: " + hiring[hi]);
+  if (prefLangs.length > 0) lines.push("Preferred-Languages: " + prefLangs.join(", "));
+  var body = lines.join("\n") + "\n";
+  var bodyBuf = Buffer.from(body, "utf8");
+  var alsoAtRoot = opts.alsoAtRoot === true;
+
+  return function securityTxtMiddleware(req, res, next) {
+    var url = req.url || "";
+    // Strip query string for the path comparison.
+    var qIdx = url.indexOf("?");
+    var path = qIdx === -1 ? url : url.slice(0, qIdx);
+    var matches = (path === "/.well-known/security.txt") ||
+                  (alsoAtRoot && path === "/security.txt");
+    if (!matches) return next();
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(405, {                                                       // allow:raw-byte-literal — HTTP 405 status
+        "Allow":          "GET, HEAD",
+        "Content-Type":   "text/plain; charset=utf-8",
+        "Content-Length": 18,                                                    // allow:raw-byte-literal — len of "Method Not Allowed"
+      });
+      res.end("Method Not Allowed");
+      return;
+    }
+    res.writeHead(200, {                                                         // allow:raw-byte-literal — HTTP 200 status
+      "Content-Type":     "text/plain; charset=utf-8",
+      "Content-Length":   bodyBuf.length,
+      "Cache-Control":    "public, max-age=86400",
+      "X-Content-Type-Options": "nosniff",
+    });
+    if (req.method === "HEAD") { res.end(); return; }
+    res.end(bodyBuf);
+    try { observability().safeEvent("middleware.securityTxt.served", 1, { path: path }); }
+    catch (_e) { /* obs best-effort */ }
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.79",
+  "version": "0.7.81",
   "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:70a3e68a-1a5d-4506-ae41-38e159762dfe",
+  "serialNumber": "urn:uuid:cff2cdad-8420-45be-b8ae-a4b9ec79c49a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T05:26:16.435Z",
+    "timestamp": "2026-05-06T05:43:30.523Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.79",
+      "bom-ref": "@blamejs/core@0.7.81",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.79",
+      "version": "0.7.81",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.79",
+      "purl": "pkg:npm/%40blamejs/core@0.7.81",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.79",
+      "ref": "@blamejs/core@0.7.81",
       "dependsOn": []
     }
   ]