@blamejs/blamejs-shop 0.3.11 → 0.3.13

package/lib/vendor/blamejs/lib/vault/index.js

@@ -102,11 +102,12 @@ function resolvePaths(dataDir) {
     plaintext:         nodePath.join(dataDir, "vault.key"),
     sealed:            nodePath.join(dataDir, "vault.key.sealed"),
     derivedHashSalt:   nodePath.join(dataDir, "vault.derived-hash-salt"),
+    derivedHashMacKey: nodePath.join(dataDir, "vault.derived-hash-mac.sealed"),
   };
 }
 
 // derivedHashSalt — per-deployment salt for crypto-field
-// derivedHashes (D-H1). Pre-v0.8.42 the deterministic
+// derivedHashes. Pre-v0.8.42 the deterministic
 // sha3(namespace + plaintext) shape allowed cross-deployment
 // rainbow + cross-table correlation; binding a 32-byte
 // per-deployment salt closes that class without breaking
@@ -175,6 +176,66 @@ function getDerivedHashSalt() {
   return _cachedDerivedHashSalt;
 }
 
+// derivedHashMacKey — per-deployment SECRET key for crypto-field's
+// keyed (hmac-shake256) derived-hash mode. Unlike the salt, this is
+// SEALED at rest (vault.derived-hash-mac.sealed), so an attacker with
+// disk access alone cannot recompute the keyed digest and correlate
+// low-entropy plaintexts. Like the salt, it is keypair-bound and
+// survives a passphrase-only rotation; an ENVELOPE rotation re-seals it
+// because it is registered in rotate's additionalSealed sweep.
+function _readOrCreateDerivedHashMacKey() {
+  if (!paths) {
+    throw new VaultError("vault/not-initialized",
+      "vault.getDerivedHashMacKey() requires init()");
+  }
+  if (nodeFs.existsSync(paths.derivedHashMacKey)) {
+    var sealed = atomicFile.readSync(paths.derivedHashMacKey, { encoding: "utf8" }).trim();
+    var b64 = unseal(sealed);
+    var key = Buffer.from(b64, "base64");
+    if (key.length !== 32) {                                                        // 32-byte (256-bit) MAC key
+      throw new VaultError("vault/derived-hash-mac-key-corrupted",
+        "vault.derived-hash-mac key must unseal to exactly 32 bytes; got " + key.length);
+    }
+    return key;
+  }
+  var nodeCrypto = require("node:crypto");
+  var raw = nodeCrypto.randomBytes(32);                                            // 32-byte MAC key
+  atomicFile.writeSync(paths.derivedHashMacKey, seal(raw.toString("base64")), { fileMode: 0o600 });
+  log("generated per-deployment derivedHash MAC key at " + paths.derivedHashMacKey);
+  return raw;
+}
+
+var _cachedDerivedHashMacKey = null;
+/**
+ * @primitive b.vault.getDerivedHashMacKey
+ * @signature b.vault.getDerivedHashMacKey()
+ * @since     0.14.7
+ * @related   b.vault.getDerivedHashSalt, b.cryptoField.registerTable
+ *
+ * Returns the 32-byte per-deployment SECRET key that backs crypto-
+ * field's keyed (`hmac-shake256`) derived-hash mode. Generated once on
+ * first use, SEALED at rest (`vault.derived-hash-mac.sealed`, mode
+ * `0o600`) so disk access alone does not expose it, and re-sealed by an
+ * envelope vault rotation. Distinct from `getDerivedHashSalt`, which is
+ * a non-secret salt stored in plaintext.
+ *
+ * Throws `VaultError("vault/not-initialized")` before `init()`, or
+ * `vault/derived-hash-mac-key-corrupted` if the sealed file does not
+ * unseal to exactly 32 bytes.
+ *
+ * @example
+ *   await b.vault.init({ dataDir: "/var/lib/blamejs", mode: "plaintext" });
+ *   var k = b.vault.getDerivedHashMacKey();
+ *   k.length;           // → 32
+ *   Buffer.isBuffer(k); // → true
+ */
+function getDerivedHashMacKey() {
+  if (_cachedDerivedHashMacKey === null) {
+    _cachedDerivedHashMacKey = _readOrCreateDerivedHashMacKey();
+  }
+  return _cachedDerivedHashMacKey;
+}
+
 // ---- Init dispatch ----
 
 /**
@@ -620,6 +681,7 @@ module.exports = {
   seal:                  seal,
   unseal:                unseal,
   getDerivedHashSalt:    getDerivedHashSalt,
+  getDerivedHashMacKey:  getDerivedHashMacKey,
   _zeroizeAndReplace:    _zeroizeAndReplace,
   aad:                   vaultAad,
   getKeysJson:           getKeysJson,
@@ -633,6 +695,7 @@ module.exports = {
   _resetForTest:         function () {
     if (currentPassphrase) safeBuffer.secureZero(currentPassphrase);
     keys = null; initialized = false; currentPassphrase = null; paths = null; currentMode = null;
+    _cachedDerivedHashSalt = null; _cachedDerivedHashMacKey = null;
   },
   _getKeysForTest:       function () { return keys; },
   _getPathsForTest:      function () { return paths; },

package/lib/vendor/blamejs/lib/vault/rotate.js

@@ -651,6 +651,25 @@ async function rotate(opts) {
       _reSealValue(current, oldKeys, newKeys), { mode: 0o600 });
   }
 
+  // 3b. Framework-managed crypto-field derived-hash files — always
+  // rotated regardless of operator opts.paths, so the staging copy is
+  // complete. The plaintext salt is copied verbatim; the SEALED MAC key
+  // (keyed hmac-shake256 mode) is re-sealed under the new keypair so an
+  // envelope rotation doesn't orphan it (a passphrase-only rotation
+  // re-seals to the same value since the keypair is unchanged).
+  var saltSrc = nodePath.join(dataDir, "vault.derived-hash-salt");
+  if (nodeFs.existsSync(saltSrc)) {
+    nodeFs.copyFileSync(saltSrc, nodePath.join(stagingDir, "vault.derived-hash-salt"));
+  }
+  var macSrc = nodePath.join(dataDir, "vault.derived-hash-mac.sealed");
+  if (nodeFs.existsSync(macSrc)) {
+    var macCurrent = nodeFs.readFileSync(macSrc, "utf8").trim();
+    if (macCurrent.indexOf(C.VAULT_PREFIX) === 0) {
+      nodeFs.writeFileSync(nodePath.join(stagingDir, "vault.derived-hash-mac.sealed"),
+        _reSealValue(macCurrent, oldKeys, newKeys), { mode: 0o600 });
+    }
+  }
+
   // 4. decrypt + rotate + re-encrypt db.enc
   _emit(progress, { phase: "rotate_db" });
   var encDbPath = nodePath.join(dataDir, paths.encryptedDb);

package/lib/vendor/blamejs/lib/vendor-data.js

@@ -306,7 +306,7 @@ function _loadAndVerify(name) {
 // Memoized — "sha256:" + sha256(pemToRaw(PUBKEY_PEM)). Matches the
 // canonical fingerprint shape `scripts/vendor-data-gen.js` writes into
 // each .data.js's `metadata.publicKeyFingerprint`. Computed lazily on
-// first verify (also lazily by verifyAll at boot). CRYPTO-11 — every
+// first verify (also lazily by verifyAll at boot). Every
 // per-entry verify cross-checks this against the entry's declared
 // `meta.publicKeyFingerprint` so a pubkey-swap attack fails before
 // signature verify even runs.

package/lib/vendor/blamejs/package.json

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

package/lib/vendor/blamejs/release-notes/v0.14.7.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.14.7",
+  "date": "2026-05-30",
+  "headline": "Storage and audit-trail hardening: queries are gated to declared columns, raw SQL refuses embedded literals, the database key is bound to its location, sealed-column lookup hashes gain a keyed mode, audit-chain purges can require dual control, and breach deadlines ship a running clock",
+  "summary": "This release tightens the data and audit layers against a set of failure modes that were previously reachable. Database queries are now checked against the columns a table declared in its schema: a reference to an undeclared column fails closed by default instead of silently matching nothing, and the `whereRaw` escape hatch refuses an embedded string literal so values bind through placeholders. The database encryption key is sealed with its purpose, data directory, and key path as additional authenticated data, so a key file cannot be relocated to another deployment and unsealed there; an older key without that binding upgrades itself on first load. Sealed-column equality-lookup hashes can now be computed as a keyed MAC (HMAC-SHAKE256) off a per-deployment key, making the lookup hash unforgeable without that key, while the salted-SHA3 default is unchanged. Purging the tamper-evident audit chain can be placed under a two-authorizer dual-control grant so one operator cannot erase it alone, and database credential-rejection audits now record which relation the rejected credential tried to reach. Finally, breach-notification deadlines get a running clock that raises approaching and passed alerts as each regime's window elapses. One behavior change to note: the column gate defaults to reject — if a service issues queries against columns it did not declare in its schema, set `db.init({ columnGate: \"warn\" })` (audited, allowed) or `\"off\"` while the schema is reconciled.",
+  "sections": [
+    {
+      "heading": "Added",
+      "items": [
+        {
+          "title": "Column-membership gate on every query",
+          "body": "`b.db.from(table)` now checks each referenced column against the table's declared schema. The mode is set with `db.init({ columnGate: \"reject\" | \"warn\" | \"off\" })` (default `reject`), and `query.allowedColumns([...])` narrows a single query to an explicit allowlist that is always enforced. `b.db.getDeclaredColumns(table)` returns a table's declared column names (or `null` for an unknown table). This is defense in depth against typo'd or caller-influenced column names reaching the SQL layer (CWE-89)."
+        },
+        {
+          "title": "Keyed mode for sealed-column lookup hashes",
+          "body": "Equality-lookup (\"derived\") hashes for sealed columns can be computed as `hmac-shake256` — a keyed MAC over a per-deployment key — instead of the default `salted-sha3`. Set it per table with `cryptoField.registerTable(name, { derivedHashMode: \"hmac-shake256\" })` or per column with `{ from, mode: \"hmac-shake256\" }`. The keyed hash is unforgeable and un-correlatable without the deployment's MAC key, which raises the bar against offline lookup-table attacks on low-entropy sealed values (CWE-916). `b.vault.getDerivedHashMacKey()` exposes the 32-byte per-deployment key; it is created on first use and re-sealed across key rotation automatically."
+        },
+        {
+          "title": "Dual-control gate on audit-chain purge",
+          "body": "`b.auditTools.purge` accepts `dualControlGrant`. When `audit_log` is placed under dual control, a verified archive and `confirm: true` are no longer sufficient: the purge additionally requires a consumed m-of-n grant whose action is bound to the purge, so a grant minted for another operation cannot be replayed and one operator cannot erase the tamper-evident chain alone (NIST SP 800-53 AU-9, separation of duties)."
+        },
+        {
+          "title": "Running clock for breach-notification deadlines",
+          "body": "`b.incident.report.createDeadlineClock({ notify, approachThresholds })` tracks open incidents and raises `deadline_approaching` and `deadline_passed` alerts as each regime's window elapses (GDPR 72h, DORA, NIS2, and the rest of the registry). Alerts are deduplicated per incident and stage, suppressed once a submission stage is acknowledged, and the clock can run on an interval or be ticked manually."
+        }
+      ]
+    },
+    {
+      "heading": "Changed",
+      "items": [
+        {
+          "title": "Queries against undeclared columns now fail closed by default",
+          "body": "The column gate defaults to `reject`: a query that references a column the table did not declare throws rather than silently matching nothing. A service that intentionally queries undeclared columns can set `db.init({ columnGate: \"warn\" })` to audit and allow, or `\"off\"` to disable the gate, while its schema is reconciled. Framework-declared columns (including `_id` and derived-hash columns) are always members."
+        }
+      ]
+    },
+    {
+      "heading": "Security",
+      "items": [
+        {
+          "title": "Database encryption key bound to its location",
+          "body": "`db.key.enc` is sealed with additional authenticated data over its purpose, resolved data directory, and resolved key path. A sealed key copied to a different deployment or path no longer unseals there — the AEAD authentication fails — which prevents silent key relocation. A legacy key sealed without this binding is detected and re-sealed in the bound format on first load, with no operator action required."
+        },
+        {
+          "title": "`whereRaw` refuses embedded string literals",
+          "body": "`whereRaw(sql, params)` and `WhereBuilder.raw(sql, params)` reject a raw fragment containing a string literal (`'...'`); values must bind through the `params` array. A static, operator-controlled literal can opt in with `{ allowLiterals: true }`. This closes a path where a value concatenated into a raw fragment would reintroduce SQL injection (CWE-89)."
+        },
+        {
+          "title": "Credential-rejection audits record the attempted relation",
+          "body": "A `db.auth.failed` audit row (SQLSTATE 28000 / 28P01 / 42501) now carries `attemptedTable`, the relation the rejected credential tried to reach, extracted defensively from the statement. Triage can scope the blast radius of a credential-abuse event without correlating back to the raw SQL log (CWE-778)."
+        }
+      ]
+    },
+    {
+      "heading": "Detectors",
+      "items": [
+        {
+          "title": "Audit-purge dual-control gate",
+          "body": "A new check fails the build if a call to `purgeAuditChain` appears in a file that does not also route through the dual-control gate, so a future caller cannot physically delete chain rows without two-authorizer enforcement."
+        },
+        {
+          "title": "Raw-SQL literal/interpolation guard",
+          "body": "A new check fails the build on a `whereRaw` / `.raw` call whose SQL argument is built by template interpolation or string concatenation, keeping the bound-params discipline enforceable in framework code."
+        },
+        {
+          "title": "Hand-rolled lookup-hash guard",
+          "body": "A new check fails the build if a sealed-column lookup hash is derived from the per-deployment salt outside the canonical helper, so call sites cannot bypass the keyed-mode and per-column mode policy."
+        },
+        {
+          "title": "Auth-audit attempted-relation guard",
+          "body": "A new check fails the build if a `db.auth.failed` audit is emitted in a file that does not name `attemptedTable`, so the forensic field cannot be dropped from a future emitter."
+        }
+      ]
+    }
+  ]
+}

package/lib/vendor/blamejs/scripts/release.js

@@ -88,16 +88,41 @@ function _bumpMinor(version) {
   return parts[0] + "." + (parts[1] + 1) + ".0";
 }
 
+// Quote a single argument for a Windows cmd.exe command line. Tokens
+// made only of safe characters pass through unquoted; anything else is
+// double-quoted with embedded quotes doubled.
+function _quoteWinArg(a) {
+  a = String(a);
+  if (/^[A-Za-z0-9_@.\-/:=]+$/.test(a)) return a;
+  return '"' + a.replace(/"/g, '""') + '"';
+}
+
 function _run(cmd, args, opts) {
   opts = opts || {};
-  var rv = childProcess.spawnSync(cmd, args, {
+  args = args || [];
+  var spawnCmd = cmd;
+  var spawnArgs = args;
+  var useShell = false;
+  if (_needsShell(cmd)) {
+    // Windows resolves npm / npx through .cmd shims that can only be
+    // launched via a shell (the CVE-2024-27980 mitigation refuses to
+    // spawn .cmd files without one). Node 26's DEP0190 deprecates
+    // pairing an args ARRAY with shell:true because the args would be
+    // concatenated onto the command line without escaping — a quoting /
+    // injection hazard. Build a single, explicitly-quoted command
+    // string and pass NO args array, which is the supported shape.
+    spawnCmd = [cmd].concat(args.map(_quoteWinArg)).join(" ");
+    spawnArgs = undefined;
+    useShell = true;
+  }
+  var rv = childProcess.spawnSync(spawnCmd, spawnArgs, {
     cwd:    opts.cwd   || ROOT,
     stdio:  opts.stdio || "inherit",
     env:    Object.assign({}, process.env, opts.env || {}),
-    shell:  _needsShell(cmd),
+    shell:  useShell,
   });
   if (rv.status !== 0 && !opts.allowFail) {
-    throw new Error("release: " + cmd + " " + (args || []).join(" ") +
+    throw new Error("release: " + cmd + " " + args.join(" ") +
                     " failed with status " + rv.status);
   }
   return rv;

package/lib/vendor/blamejs/test/layer-0-primitives/audit-tools-dual-control.test.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * b.auditTools.purge dual-control gate.
+ *
+ * When audit_log is placed under dual control, physically purging the
+ * audit chain requires a consumed m-of-n grant in addition to a
+ * verified archive and confirm:true — one operator must not be able to
+ * erase the tamper-evident chain alone. The grant's action is also
+ * bound, so a grant minted for a different operation can't be replayed
+ * against a purge.
+ */
+
+var helpers = require("../helpers");
+var b              = helpers.b;
+var check          = helpers.check;
+var fs             = helpers.fs;
+var os             = helpers.os;
+var path           = helpers.path;
+var setupTestDb    = helpers.setupTestDb;
+var teardownTestDb = helpers.teardownTestDb;
+
+var PASS = Buffer.from("operator-passphrase");
+var PURGE_ACTION = "auditTools.purge";
+
+async function _seedAuditRows(count) {
+  b.audit.registerNamespace("test");
+  for (var i = 0; i < count; i++) {
+    await b.audit.record({
+      actor: { userId: "u-" + i }, action: "test.seeded", outcome: "success", metadata: { i: i },
+    });
+  }
+}
+
+async function _expectCode(fn, code) {
+  var threw = null;
+  try { await fn(); } catch (e) { threw = e; }
+  return threw && threw.code === code;
+}
+
+async function run() {
+  var dir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-at-dc-"));
+  try {
+    await setupTestDb(dir);
+    await _seedAuditRows(5);
+    await b.audit.checkpoint();
+
+    var out = path.join(dir, "bundles", "archive-dc");
+    await b.auditTools.archive({ before: Date.now() + 1000, out: out, passphrase: PASS });
+
+    // Simulate audit_log being under dual control (m-of-n). The gate
+    // override returns a gate descriptor for the audit_log table; the
+    // denial branches all fire before any chain mutation, so the same
+    // verified bundle is reused across them.
+    var sawTable = null;
+    var gate = function (table) { sawTable = table; return { m: 2, n: 3 }; };
+
+    // No grant → refused.
+    check("purge under dual control refuses without a grant",
+      await _expectCode(function () {
+        return b.auditTools.purge({ archive: out, passphrase: PASS, confirm: true, checkDualControlGate: gate });
+      }, "audit-tools/dual-control-required"));
+    check("gate was consulted for the audit_log table", sawTable === "audit_log");
+
+    // Grant not ready (not a consumed m-of-n grant) → refused.
+    check("purge refuses a not-ready grant",
+      await _expectCode(function () {
+        return b.auditTools.purge({
+          archive: out, passphrase: PASS, confirm: true, checkDualControlGate: gate,
+          dualControlGrant: { ready: false, action: PURGE_ACTION },
+        });
+      }, "audit-tools/dual-control-grant-not-ready"));
+
+    // Grant minted for a different action → refused (action binding).
+    check("purge refuses a grant bound to a different action",
+      await _expectCode(function () {
+        return b.auditTools.purge({
+          archive: out, passphrase: PASS, confirm: true, checkDualControlGate: gate,
+          dualControlGrant: { ready: true, action: "db.eraseHard" },
+        });
+      }, "audit-tools/dual-control-grant-mismatch"));
+
+    // Confirm the chain is still intact — no denial mutated it.
+    var beforeRows = await b.clusterStorage.executeAll("SELECT COUNT(*) as c FROM audit_log");
+    check("audit_log untouched by denied purges", Number(beforeRows[0].c) >= 5);
+
+    // Valid consumed grant for the purge action → proceeds.
+    var pres = await b.auditTools.purge({
+      archive: out, passphrase: PASS, confirm: true, checkDualControlGate: gate,
+      dualControlGrant: { ready: true, action: PURGE_ACTION },
+    });
+    check("purge with a valid grant succeeds", pres.purged === true);
+    check("purge reports dual-control was consumed", pres.dualControlConsumed === true);
+    check("purge deleted rows", pres.rowsDeleted > 0);
+
+    // No gate (audit_log not under dual control) → confirm + archive
+    // alone is sufficient (no grant required) — the gate is opt-in.
+    var noGateResult = b.auditTools.purge;
+    check("purge surface present", typeof noGateResult === "function");
+  } finally {
+    await teardownTestDb(dir);
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) {}
+  }
+
+  console.log("OK — audit-tools dual-control tests");
+}
+
+module.exports = { run: run };
+if (require.main === module) {
+  // Rethrow on failure so Node surfaces the error and exits non-zero,
+  // instead of logging the caught error object — a taint analyzer traces
+  // a logged error back to the test passphrase fixture (a non-secret
+  // constant) and raises a false clear-text-logging alert.
+  run().then(function () { process.exit(0); })
+       .catch(function (err) { process.exitCode = 1; throw err; });
+}

package/lib/vendor/blamejs/test/layer-0-primitives/codebase-patterns.test.js

@@ -309,6 +309,7 @@ var VALID_ALLOW_CLASSES = {
   "inline-require": 1,
   "inline-require-non-empty-string-validation": 1,
   "internal-binding-in-prose": 1,
+  "internal-narrative-comment": 1,
   "list-without-pagination": 1,
   "math-random-noncrypto": 1,
   "no-number-money-arithmetic": 1,
@@ -7951,6 +7952,101 @@ var KNOWN_ANTIPATTERNS = [
     reason: "Codex P1 on v0.11.4 PR #109 — b.audit.useStore({ record }) inlined await on operator-supplied callback. A stalled network call neither resolves nor rejects ⇒ b.audit.record() never returns, emit/safeEmit drains stall behind it; hot-path observability emission is supposed to be drop-silent on hangs. Defense: wrap every external-callback await in safeAsync.withTimeout. Detector catches future operator-supplied async hooks on the same shape (_externalStore / _userStore / _externalSink / _externalCb / _externalCallback / _externalHook).",
   },
 
+  {
+    // v0.14.7 — physically deleting audit-chain rows is a
+    // single-operator-can-erase-evidence risk. `auditTools.purge`
+    // (and the low-level `db.purgeAuditChain` it composes) MUST
+    // consult a dual-control gate — two distinct authorizers — before
+    // the destructive delete runs, so one compromised credential can't
+    // silently truncate the tamper-evident chain. The gate primitive
+    // is `db._checkDualControlGate(table)` (resolved at runtime); the
+    // purge path threads it via `_resolveDualControlGate(opts)` and
+    // refuses with `dual-control-required` when no grant is present.
+    //
+    // Detector: any lib/ call to `purgeAuditChain(` MUST appear in a
+    // file that also names the gate (`_checkDualControlGate` /
+    // `_resolveDualControlGate` / `dualControlGrant`). A new caller
+    // that physically deletes chain rows without routing through the
+    // gate trips here.
+    id: "audit-purge-without-dual-control-gate",
+    primitive: "auditTools.purge({ dualControlGrant }) / db.purgeAuditChain — physical audit-chain deletion MUST consult the dual-control gate (_checkDualControlGate / _resolveDualControlGate); one operator must not be able to erase the tamper-evident chain alone",
+    regex: /\bpurgeAuditChain\s*\(/,
+    requires: /_checkDualControlGate|_resolveDualControlGate|dualControlGrant/,
+    skipCommentLines: true,
+    allowlist: [],
+    reason: "v0.14.7 — audit-chain purge is irreversible and tamper-evidence-destroying. The discipline: the chain may only be truncated under a two-authorizer dual-control grant. db.js defines the gate (_checkDualControlGate) and audit-tools.js purge() resolves+enforces it (_resolveDualControlGate) before calling db().purgeAuditChain; both files satisfy the companion check. A future file that calls purgeAuditChain without naming the gate would let a single operator delete evidence — exactly the shape this blocks.",
+  },
+
+  {
+    // v0.14.7 — raw-SQL fragments passed to `whereRaw` / the
+    // WhereBuilder `.raw(sql, params)` escape hatch must parameterize
+    // values via the `params` array, NOT interpolate or concatenate
+    // them into the SQL string. `_assertRawNoStringLiteral` refuses an
+    // embedded `'...'` literal at runtime (unless the caller opts in
+    // with `allowLiterals`), but the static discipline is stronger:
+    // lib/ must never BUILD the raw SQL by `${...}` template
+    // interpolation or `"..." + value` string concatenation — that is
+    // the injection shape the bound-params API exists to prevent.
+    //
+    // Detector fires on a whereRaw/.raw call whose first argument is a
+    // template literal containing `${` or a string-concat expression.
+    // A no-arg `bodyParser.raw()` (different `.raw`) does not match —
+    // the regex requires an interpolated/concatenated string argument.
+    id: "whereraw-interpolated-or-concatenated-sql",
+    primitive: "whereRaw(sql, params) / qb.raw(sql, params) — pass values through the bound `params` array; never `${...}`-interpolate or `+`-concatenate them into the SQL string (that is the injection shape the params API prevents)",
+    regex: /(?:whereRaw|\.raw)\s*\(\s*(?:`[^`]*\$\{|["'][^"']*["']\s*\+|[A-Za-z_$][\w$]*\s*\+\s*["'`])/,
+    skipCommentLines: true,
+    allowlist: [],
+    reason: "v0.14.7 — b.db whereRaw / WhereBuilder.raw accept an operator SQL fragment plus a bound-params array. Concatenating or template-interpolating a value into the fragment defeats the placeholder binding and reintroduces SQL injection. lib/ has zero such call sites today; the detector keeps it that way (the runtime _assertRawNoStringLiteral gate is the operator-facing backstop, this is the framework-internal one). No-argument `.raw()` mountings (e.g. bodyParser.raw()) don't match — an interpolated/concatenated string argument is required.",
+  },
+
+  {
+    // v0.14.7 — equality-lookup ("derived") hashes for sealed columns
+    // must be computed through cryptoField._computeDerivedHash, which
+    // honours the per-table / per-column mode policy (salted-sha3 by
+    // default, hmac-shake256 opt-in keyed off vault.getDerivedHashMacKey).
+    // Hand-rolling `sha3Hash(vault.getDerivedHashSalt() + ns + value)`
+    // at a new site bypasses the keyed-MAC option AND the mode policy,
+    // and risks a static-salt regression if the salt source is changed
+    // for one caller but not the canonical helper.
+    //
+    // Detector: direct use of `getDerivedHashSalt().toString("hex") +`
+    // outside crypto-field.js (the canonical helper). The helper itself
+    // is allowlisted.
+    id: "derived-hash-handrolled-outside-crypto-field",
+    primitive: "cryptoField derived/lookup hashes — compute via _computeDerivedHash (honours salted-sha3 vs hmac-shake256 mode + vault.getDerivedHashMacKey); do not hand-roll sha3Hash(getDerivedHashSalt() + ns + value) at call sites",
+    regex: /getDerivedHashSalt\s*\(\s*\)\s*\.toString\s*\(\s*["']hex["']\s*\)\s*\+/,
+    skipCommentLines: true,
+    allowlist: [
+      // The canonical helper — _computeDerivedHash branches on mode here.
+      "lib/crypto-field.js",
+    ],
+    reason: "v0.14.7 — derived-hash equality lookups gained a keyed mode (hmac-shake256 off vault.getDerivedHashMacKey) alongside the salted-sha3 default. The mode decision lives in cryptoField._computeDerivedHash. A site that hand-derives the hash with getDerivedHashSalt() bypasses the keyed option and the per-column mode policy; only the canonical helper (crypto-field.js) may name the salt directly.",
+  },
+
+  {
+    // v0.14.7 — a `db.auth.failed` audit row must record WHICH
+    // relation the rejected credential attempted to reach
+    // (`attemptedTable`), so an operator triaging a credential-abuse
+    // event can scope blast radius without correlating to the raw SQL
+    // log. external-db extracts the target relation defensively
+    // (_extractTargetRelation) and stamps both resource.attemptedTable
+    // and the audit metadata. Emitting the auth-failure audit without
+    // it loses the forensic signal.
+    //
+    // Detector: an `action: "db.auth.failed"` audit emit MUST appear in
+    // a file that also names `attemptedTable`. The metric emitter
+    // (_emitMetric("db.auth.failed", ...)) uses a positional shape, not
+    // `action:`, so it doesn't match.
+    id: "db-auth-failed-audit-without-attempted-relation",
+    primitive: "db.auth.failed audit — stamp the attempted relation (attemptedTable, via _extractTargetRelation) on credential-rejection audit rows so blast radius is triageable without the raw SQL log",
+    regex: /action\s*:\s*["']db\.auth\.failed["']/,
+    requires: /attemptedTable/,
+    skipCommentLines: true,
+    allowlist: [],
+    reason: "v0.14.7 — external-db credential-rejection audits (SQLSTATE 28000 / 28P01 / 42501) now carry attemptedTable, the relation the rejected identity tried to touch, extracted defensively from the SQL. The detector requires any file emitting an action:'db.auth.failed' audit to also name attemptedTable so a future emitter can't drop the forensic field.",
+  },
+
 ];
 
 // @example placeholder detection lives in
@@ -10565,9 +10661,9 @@ function testPrimitiveReachability() {
 //               onDeny / problemDetails opts. A new deny-path
 //               middleware that hardcodes
 //               `res.writeHead(<4xx/5xx>, { "Content-Type": ... })`
-//               locks consumers out of the response shape — the
-//               integration-friction class that blocked downstream
-//               adoption (the rate-limit text/plain 429). ----
+//               locks consumers out of the response shape — which is
+//               what pinned rate-limit's 429 to text/plain before this
+//               convention existed. ----
 function testDenyPathComposesDenyResponse() {
   // class: deny-path-hardcoded-response
   var MW_ROOT = path.resolve(LIB_ROOT, "middleware");
@@ -10610,9 +10706,73 @@ function testDenyPathComposesDenyResponse() {
     violations);
 }
 
+// ---- Pattern: operator-facing source comments must describe the code,
+//               not the internal authoring process. These shapes are
+//               internal slice / bug / plan IDs, code-review-process
+//               residue (Codex P-levels, PR numbers), and dated
+//               decision parentheticals — none of which an operator
+//               reading the shipped source can map to anything in their
+//               own checkout. Genuinely operator-meaningful references
+//               (RFC / CVE / NIST / CWE, "since vX.Y.Z", established
+//               terse markers like D-M4 / AUTH-32) are NOT matched.
+//               Allowlist a false positive with `// allow:internal-
+//               narrative-comment`. ----
+function testNoInternalNarrativeComments() {
+  // class: internal-narrative-comment
+  var NARRATIVE = [
+    { re: /\b(?:SUBSTRATE|BUG|MAIL)-\d+\b/,        what: "internal slice/bug ID" },
+    { re: /\b(?:D-[MLH]\d+|AUTH-\d+|CRYPTO-\d+|SUPPLY-\d+)\b/, what: "internal domain/slice ID" },
+    { re: /\bCodex\s+P\d/,                          what: "code-review-process reference (Codex P#)" },
+    { re: /\bF-[A-Z]{2,}-\d+\b/,                    what: "internal feature/plan item ID" },
+    { re: /\bPR\s+#\d+\b/,                          what: "pull-request number (process residue)" },
+    { re: /\b[Aa]udit\s+\d{4}-\d{2}-\d{2}/,         what: "dated audit/decision residue" },
+    { re: /\bReported\s+\d{4}-\d{2}-\d{2}/,         what: "dated report residue" },
+    { re: /\bCore Rule\s+§\d/,                 what: "internal CLAUDE.md rule-number citation" },
+  ];
+  var files = _libFiles();
+  var bad = [];
+  var jsdocLineRe = /^\s*\*/;
+  for (var fi = 0; fi < files.length; fi++) {
+    var rel = _relPath(files[fi]);
+    var src = fs.readFileSync(files[fi], "utf8");
+    var lines = src.split("\n");
+    for (var li = 0; li < lines.length; li++) {
+      var line = lines[li];
+      // Scan the comment portion only: a ` * `-prefixed JSDoc line in
+      // full, or the text after a line's first `//`.
+      var comment = null;
+      if (jsdocLineRe.test(line)) {
+        comment = line;
+      } else {
+        var idx = line.indexOf("//");
+        if (idx !== -1) comment = line.slice(idx);
+      }
+      if (comment === null) continue;
+      for (var p = 0; p < NARRATIVE.length; p++) {
+        var m = comment.match(NARRATIVE[p].re);
+        if (m) {
+          bad.push({
+            file:    rel,
+            line:    li + 1,
+            content: NARRATIVE[p].what + ": `" + m[0] + "` in an operator-facing comment — " +
+                     "describe the change, not the internal process (strip the label / drop the " +
+                     "dated parenthetical / cite the public reason instead)",
+          });
+          break;
+        }
+      }
+    }
+  }
+  bad = _filterMarkers(bad, "internal-narrative-comment");
+  _report("operator-facing source comments must not carry internal-process narrative " +
+          "(slice / bug / plan IDs, Codex / PR references, dated decision parentheticals)",
+    bad);
+}
+
 async function run() {
   testPrimitiveReachability();
   testDenyPathComposesDenyResponse();
+  testNoInternalNarrativeComments();
   testNoOrphanAllowClass();
   testNoRawByteLiterals();
   testNoRawTimeLiterals();