@blamejs/core 0.7.80 → 0.7.82

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.82** (2026-05-06) — `b.mail.bimi` — BIMI record builder + verifier (RFC 9091). BIMI publishes a sender's brand logo URL in DNS so receiving MTAs can render it next to the message in supported clients (Gmail, Yahoo, Apple Mail). **`b.mail.bimi.recordShape({ logoUrl, vmcUrl?, selector? })`** produces the canonical `v=BIMI1; l=https://...; a=https://...` TXT-record string per RFC 9091 §4. Both `l=` (SVG logo URL) and `a=` (Verified Mark Certificate URL per RFC 9091 §6) are HTTPS-required (refuses `http://`). All field values are CR/LF/NUL/semicolon-screened so a hostile URL can't inject a record-separator into the published TXT. **`b.mail.bimi.fetchPolicy(domain, { selector?, dnsLookup? })`** queries `<selector>._bimi.<domain>` (default selector `"default"`) and returns the structured record `{ v, l, a }` or `null` when no policy is published / record is malformed. **`b.mail.bimi.parseRecord(text)`** parses any operator-supplied TXT body — semicolon-separated `key=value` pairs per RFC 9091 §4. The framework does NOT validate the SVG / VMC contents against the RFC §5/§6 profiles — operators feed those to their own asset pipeline; the fetch primitive is a thin DNS lookup that returns the structured record so an operator dashboard or SMTP send-time preflight can verify the publication. BIMI is layered on a passing DMARC posture (the receiver requires DMARC quarantine/reject); operators with the existing `b.mail.dmarc` posture set up benefit from BIMI rendering immediately on receivers that honor it.
+
+- **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.

package/lib/mail-bimi.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * BIMI — Brand Indicators for Message Identification (RFC 9091).
+ *
+ * BIMI records publish a sender's brand logo URL in DNS so receiving
+ * MTAs can render it next to the message in supported clients
+ * (Gmail, Yahoo, Apple Mail). The record format is:
+ *
+ *   default._bimi.<domain>  IN  TXT  "v=BIMI1; l=https://...; a=https://..."
+ *
+ * - `l=` URL to the SVG logo file (Tiny PS Profile per RFC 9091 §5)
+ * - `a=` URL to the Verified Mark Certificate (VMC) — RFC 9091 §6
+ *
+ * BIMI is layered on a passing DMARC posture (the receiver requires
+ * DMARC to be at quarantine or reject). No-op for senders without
+ * DMARC enforcement.
+ *
+ * Surface:
+ *   b.mail.bimi.recordShape({ logoUrl, vmcUrl?, selector? })  → string
+ *   b.mail.bimi.fetchPolicy(domain, opts?)                    → { v, l, a } | null
+ *   b.mail.bimi.parseRecord(text)                             → { v, l, a } | null
+ *
+ * The framework does NOT validate the SVG / VMC contents against the
+ * RFC 9091 §5/§6 profiles — operators feed those to their own asset
+ * pipeline. The fetch primitive is a thin DNS lookup that returns
+ * the structured record so an operator dashboard or SMTP send-time
+ * preflight can verify the publication.
+ */
+
+var dns = require("node:dns");
+var dnsPromises = dns.promises;
+var validateOpts = require("./validate-opts");
+var safeUrl = require("./safe-url");
+var C = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var BimiError = defineClass("BimiError", { alwaysPermanent: true });
+
+var BIMI_VERSION = "BIMI1";
+var BIMI_DEFAULT_SELECTOR = "default";
+var BIMI_RECORD_MAX_BYTES = C.BYTES.kib(2);
+
+function _validateUrl(url, label) {
+  // RFC 9091 §4.2 — `l=` and `a=` MUST be HTTPS URLs.
+  try {
+    safeUrl.parse(url, { allowedProtocols: ["https:"] });
+  } catch (e) {
+    throw new BimiError("mail-bimi/bad-" + label,
+      "bimi: " + label + " must be an https:// URL — got '" + url + "': " +
+      ((e && e.message) || String(e)));
+  }
+}
+
+function recordShape(opts) {
+  validateOpts.requireObject(opts, "bimi.recordShape", BimiError);
+  validateOpts(opts, ["logoUrl", "vmcUrl", "selector"], "bimi.recordShape");
+  validateOpts.requireNonEmptyString(opts.logoUrl,
+    "bimi.recordShape: logoUrl", BimiError, "mail-bimi/no-logo");
+  _validateUrl(opts.logoUrl, "logoUrl");
+  if (opts.vmcUrl !== undefined && opts.vmcUrl !== null) {
+    validateOpts.requireNonEmptyString(opts.vmcUrl,
+      "bimi.recordShape: vmcUrl", BimiError, "mail-bimi/bad-vmc");
+    _validateUrl(opts.vmcUrl, "vmcUrl");
+  }
+  // No CR/LF/NUL/semicolon — defense-in-depth so a hostile URL can't
+  // inject a record-separator sequence into the published TXT.
+  if (/[\r\n\0;]/.test(opts.logoUrl)) {
+    throw new BimiError("mail-bimi/bad-logo",
+      "bimi.recordShape: logoUrl contains forbidden control / record-separator characters");
+  }
+  if (opts.vmcUrl && /[\r\n\0;]/.test(opts.vmcUrl)) {
+    throw new BimiError("mail-bimi/bad-vmc",
+      "bimi.recordShape: vmcUrl contains forbidden control / record-separator characters");
+  }
+
+  var fields = ["v=" + BIMI_VERSION, "l=" + opts.logoUrl];
+  if (opts.vmcUrl) fields.push("a=" + opts.vmcUrl);
+  return fields.join("; ");
+}
+
+function parseRecord(text) {
+  if (typeof text !== "string" || text.length === 0) return null;
+  if (text.length > BIMI_RECORD_MAX_BYTES) return null;                          // bound BEFORE parse — TXT-record sanity cap
+  // RFC 9091 §4 — semicolon-separated, key=value, leading "v=BIMI1".
+  var parts = text.split(";");
+  var rv = { v: null, l: null, a: null };
+  for (var i = 0; i < parts.length; i += 1) {
+    var p = parts[i].trim();
+    if (p.length === 0) continue;
+    var eq = p.indexOf("=");
+    if (eq === -1) continue;
+    var k = p.slice(0, eq).trim().toLowerCase();
+    var v = p.slice(eq + 1).trim();
+    if (k === "v" || k === "l" || k === "a") rv[k] = v;
+  }
+  if (rv.v !== BIMI_VERSION || !rv.l) return null;
+  return rv;
+}
+
+async function fetchPolicy(domain, opts) {
+  validateOpts.requireNonEmptyString(domain,
+    "bimi.fetchPolicy: domain", BimiError, "mail-bimi/bad-domain");
+  opts = opts || {};
+  var selector = opts.selector || BIMI_DEFAULT_SELECTOR;
+  var qname = selector + "._bimi." + domain;
+  var records;
+  try {
+    if (opts.dnsLookup) records = await opts.dnsLookup(qname, "TXT");
+    else records = await dnsPromises.resolveTxt(qname);
+  } catch (e) {
+    if (e && (e.code === "ENOTFOUND" || e.code === "ENODATA")) return null;
+    throw new BimiError("mail-bimi/lookup-failed",
+      "bimi.fetchPolicy: TXT lookup for " + qname + " failed: " +
+      ((e && e.message) || String(e)));
+  }
+  // RFC 9091 §4.1 — a TXT lookup may return multiple chunks; pick
+  // the first record that begins with v=BIMI1.
+  for (var i = 0; i < (records || []).length; i += 1) {
+    var rec = records[i];
+    var s = Array.isArray(rec) ? rec.join("") : String(rec);
+    var parsed = parseRecord(s);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+module.exports = {
+  recordShape:  recordShape,
+  parseRecord:  parseRecord,
+  fetchPolicy:  fetchPolicy,
+  BIMI_VERSION: BIMI_VERSION,
+  BimiError:    BimiError,
+};

package/lib/mail.js

@@ -71,6 +71,7 @@ var httpClient = lazyRequire(function () { return require("./http-client"); });
 var guardEmail = lazyRequire(function () { return require("./guard-email"); });
 var mailDkim = require("./mail-dkim");
 var mailAuth = require("./mail-auth");
+var mailBimi = require("./mail-bimi");
 var mailUnsubscribe = require("./mail-unsubscribe");
 var net = lazyRequire(function () { return require("net"); });
 var nodeUrl = require("url");
@@ -1102,6 +1103,7 @@ module.exports = {
   dmarc:       mailAuth.dmarc,
   arc:         mailAuth.arc,
   authResults: mailAuth.authResults,
+  bimi:        mailBimi,
   // Test-only export: lets unit tests inspect the wire format without
   // standing up a TLS-capable SMTP fixture. Operators don't call this.
   _buildRfc822ForTest: _buildRfc822,

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");
@@ -69,6 +70,7 @@ module.exports = {
   apiEncrypt:       apiEncrypt,
   dbRoleFor:        dbRoleFor.create,
   dpop:             dpop.create,
+  hostAllowlist:    hostAllowlist.create,
   networkAllowlist: networkAllowlist.create,
 
   // Module exports for advanced use (constants, raw factory access)
@@ -95,6 +97,7 @@ module.exports = {
     apiEncrypt:       apiEncrypt,
     dbRoleFor:        dbRoleFor,
     dpop:             dpop,
+    hostAllowlist:    hostAllowlist,
     networkAllowlist: networkAllowlist,
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.80",
+  "version": "0.7.82",
   "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:1dbeaa45-dcef-4b96-9342-08799488a713",
+  "serialNumber": "urn:uuid:3d6daca5-7eec-417f-a793-a338db272d40",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T05:36:24.642Z",
+    "timestamp": "2026-05-06T05:54:05.145Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.80",
+      "bom-ref": "@blamejs/core@0.7.82",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.80",
+      "version": "0.7.82",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.80",
+      "purl": "pkg:npm/%40blamejs/core@0.7.82",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.80",
+      "ref": "@blamejs/core@0.7.82",
       "dependsOn": []
     }
   ]