@blamejs/core 0.6.20 → 0.6.22

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.22** (2026-05-02) — `b.queue.enqueue({ availableAt })` is now honoured. Previously the local-protocol enqueue() ignored opts.availableAt entirely, recomputing from `Date.now() + delaySeconds*1000`. The cron-repeat path passes both fields (the exact next-fire ms in availableAt + the floored seconds in delaySeconds), and the enqueue's recomputation lost sub-second precision plus drifted on the internal clock-vs-caller delta. Symptoms: cron-scheduled jobs landed up to 999ms off the intended boundary; the queue-flow-repeat smoke test was intermittently flaky on slow CI runners (caught by ubuntu-latest on the v0.6.21 commit). Fix: enqueue() honours opts.availableAt directly when finite; falls back to delaySeconds-based shorthand otherwise. Operators relying on `enqueue({ availableAt: T })` for non-cron scheduled jobs (e.g. "deliver this notification at exactly 09:00 tomorrow") now get the requested time instead of nowMs+0.
+- **0.6.21** (2026-05-02) — closes the medium / low audit findings flagged after v0.6.18. **Cluster cache `invalidateTag`** now actually works — the cluster backend gained a `_blamejs_cache_tags` junction table (`(cacheKey, tag)` PK + index on `tag`), tag-aware `set` / `del` / `clear` / `_sweep`, plus `getTags(key)`. The old NOT_SUPPORTED-on-cluster path is gone; multi-tag rotation, mid-flight tag replacement on update, and namespace-scoped sweeps all covered. **Multi-column cursor pagination** — `b.pagination.cursor({ orderBy: [{column,direction},...] })` accepts a string (single column), an array of strings (multi, all using `opts.direction`), or an array of `{column,direction}` objects (mixed directions). The keyset WHERE expands to the standard OR cascade so successive pages can't skip or repeat rows when ties on the leading columns are broken by trailing ones. `_id` is appended as a tiebreaker if not in the chain. The Query class also gained chained `orderBy(col, dir)` calls — second-and-later calls extend a multi-column ORDER BY in the SQL. Cursor format is bumped to encode `{ orderKey, vals, forward }` instead of the old `{ orderBy, dir, orderByVal, id, forward }` — pre-1.0 break, no compat shim. **DoH POST mode** (RFC 8484 §4.1) — `b.network.dns.useDnsOverHttps({ method })` accepts `"GET" | "POST" | undefined` (auto). Auto switches to POST when the GET URL would exceed 2048 bytes (long DNS names). **DoT connection pooling** — per-`(host:port)` cached TLS socket with a 2-minute idle timeout, serialized in-flight queries per socket. Eliminates the per-query handshake. **INI parser** shipped as `b.parsers.ini` — covers Windows .ini / .gitconfig / systemd-unit / php.ini / tox.ini shape: sections (incl. `[parent.child]` / `[parent "child"]` nesting), `;` and `#` comments (inline + leading), single + double quoting with `\n` `\t` `\\` `\"` `\'` escapes, boolean coercion (`true`/`false`/`yes`/`no`/`on`/`off`), decimal + hex integers + floats. Prototype-pollution defense (`__proto__` / `constructor` / `prototype` rejected). Duplicate-key policy throws by default; `onDuplicate: "first" | "last"` opts in to silent shadowing. Section / per-section key / value-bytes caps configurable. **Cookie-jar file persistence** — `b.httpClient.cookieJar.create({ persist: "file", file: "/abs/path", vault: b.vault })` loads at construct, debounce-flushes on every set/clear, plus `flush()` and `close()` for explicit lifecycle. With `vault`, on-disk bytes are sealed; without, plaintext JSON (operator chooses). **Comment cleanups per rule §4** — `vault/index.js` stale `// later` removed, `mail.js` "future patch" wording rewritten as scope, `bundler.js` "What it does NOT do today (deliberately deferred)" rewritten as "Out of scope", `archive.js` "v1 scope cuts (deferred)" rewritten as "Out of scope", `framework-schema.js` "next release" wording rewritten to describe what's actually shipped, `http-client.js` "out of reach today" / "we'll plumb it through when h3 lands" rewritten as scope statements. **README CLI section** updated to reflect the v0.6.17 + v0.6.18 + v0.6.19 + v0.6.20 additions (security / config-drift / file-type / password / erase / retention) — was missing 6 subcommands.
 - **0.6.20** (2026-05-02) — CI / packaging fix-up. The npm-publish workflow's "Attach SBOM as release asset" step started failing with HTTP 422 ("Cannot upload assets to an immutable release") because the operator's manual `gh release create` had already been published when the workflow ran. Two changes: (1) `sbom.cyclonedx.json` is now bundled into the npm tarball (`files` block in package.json), so `npm install @blamejs/core && cat node_modules/@blamejs/core/sbom.cyclonedx.json` is the canonical SBOM access path. The prepack guard's known-allowed list covers the just-in-time generation. (2) The workflow's GH-release-attach step is now non-fatal: it tries to upload, logs a warning if the release is immutable, and lets the publish proceed regardless. The npm tarball is the load-bearing artifact; the GitHub release attachment was only ever supplementary. `.gitignore` adds `sbom.cyclonedx.json` so a stray local `npm sbom` doesn't pollute the repo.
 - **0.6.19** (2026-05-02) — closes the critical + high gaps surfaced by the v0.6.18 audit. **Critical**: `b.network.ntp.nts.querySingle` now actually verifies the server reply with the s2cKey — extracts the AUTHENTICATOR_AND_ENC extension, AEAD-decrypts with AAD = bytes-before-authenticator, fails closed (`nts/auth-failed` / `nts/no-authenticator`) when verification fails. Server-supplied new cookies in the encrypted plaintext are appended to the cookie pool and the consumed cookie popped (real RFC 8915 cookie rotation). Previously the function returned `authenticated: true` while only checking the unique-identifier echo — any MITM that mirrored the request's 32-byte unique field could spoof timestamps. **High**: `azure-blob.presignedUploadPolicy` now throws `PRESIGN_NOT_SUPPORTED` instead of silently returning a SAS PUT URL when operators asked for POST policy semantics — Azure SAS has no body-size cap and the previous shape was a misleading mismatch (operator error message points at presignedUploadUrl + post-upload HEAD as the alternative). `b.auth.password.policy` now ships the SecLists top-10000 common-password list bundled (CC-BY-3.0, `lib/vendor/common-passwords-top-10000.txt`), loaded lazily on first `policy.check()` call; `password` / `dragon` / `qwerty` / etc. now reject with `policy/forbidden-common`; `useBundledCommon: false` per-policy bypasses if operator ships their own list. `b.network.tls` adds `removeCa(fingerprint256)` / `removeCaByLabel(label)` / `clearAll()` / `purgeExpired()` / `expiringSoon(windowMs)` so operators can rotate corp DPI CAs without process restart; every removal audits with subject + fingerprint + reason. `b.network.dns.setResultOrder("ipv6first")` now flips the order on the DoH / DoT dual-stack fallback paths too (was only sorting OS-resolver results). `b.network.dns.resolve4` / `resolve6` / `resolveAaaa` now use real DNS-protocol queries (`dns.promises.resolve4` / `_dohLookup` / `_dotLookup`) instead of aliasing `lookup()` — operator semantics now match Node's standard library (skips `/etc/hosts`, mDNS). `b.network.socket.setDefaultLinger` removed from the silent no-op path; now throws `socket/linger-not-supported` with operator guidance to use `socket.destroy()` (abort) vs `socket.end()` (graceful) since Node's public `net.Socket` has no `setLinger()`. **Internal**: every `new XxxError(...)` call across `lib/network*.js` was passing args in the wrong order (message-then-code instead of code-then-message), making `e.code` return human messages and `e.message` return slash-codes — operators relying on `e.code` for error handling got the wrong field. All 50+ throws fixed across `lib/network.js` / `network-dns.js` / `network-proxy.js` / `network-tls.js` / `network-heartbeat.js` / `network-nts.js`. **CI**: `.gitleaks.toml` adds `test/smoke.js` to the path allowlist and pins the historical commit + fingerprint that tripped the jwt rule on a `REDACTED` placeholder; `npm-publish.yml` job permissions bumped from `contents: read` to `contents: write` so `gh release upload sbom.cyclonedx.json` no longer 403s.
 - **0.6.18** (2026-05-02) — `b.network` primitive — single namespace for runtime-configurable network behaviour. `b.network.ntp` adds tunable warn / fatal drift thresholds, env-var bindings (`BLAMEJS_NTP_SERVERS` / `BLAMEJS_NTP_TIMEOUT_MS` / `BLAMEJS_NTP_DRIFT_WARN_MS` / `BLAMEJS_NTP_DRIFT_FATAL_MS`), and authenticated-time support: `b.network.ntp.nts.query(opts)` performs an NTS-KE handshake (RFC 8915) over TLS 1.3 with the framework's PQC-hybrid group preference, extracts C2S / S2C keys via the standardized TLS exporter, and authenticates NTPv4 packets with AES-SIV-CMAC-256 (mandatory-to-implement, in-house) or AEAD-CHACHA20-POLY1305 — no extra vendored deps. `b.network.dns` exposes operator-pinned resolvers, IPv4 / IPv6 / dual-stack family selection, ipv4first / verbatim / ipv6first ordering, DNS lookup timeout (Node's native `dns.lookup` has none), in-memory positive + negative cache, and DoH / DoT (cloudflare / google / quad9 / custom URL) — `b.ssrfGuard` and `b.httpClient` route through it when configured. `b.network.proxy` honours `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` / `ALL_PROXY` (lower- and upper-case) with CIDR + suffix + wildcard `NO_PROXY` matching, basic-auth via `BLAMEJS_PROXY_AUTH`, CONNECT tunnels for HTTPS through HTTP proxies; `b.httpClient` picks up the agent automatically. `b.network.tls` is a runtime-overridable trust store: `addCa(pemOrPath)` / `addCaBundle(path)` / `useSystemTrust()` / `getTrustStore()` for deep-packet-inspection deploys behind Zscaler / Netskope / corporate Squid + custom CA — Node's `NODE_EXTRA_CA_CERTS` only works at boot; this primitive accepts adds at any time and `b.pqcAgent` picks them up immediately. Every `addCa` audits with subject + issuer + fingerprint256 + validity + isSelfSigned. `b.security.assertProduction({ allowDpiTrust })` refuses to boot in production with installed CAs unless explicitly allowed. `b.network.heartbeat` adds application-level liveness probes for upstream services (HTTP / TCP / NTP probe types, healthy → degraded → down state machine with consecutive-failure threshold, audit on state change, observability counters per probe). `b.network.socket` gives operator-tunable defaults for `TCP_NODELAY` / `SO_KEEPALIVE` / `SO_LINGER`. `b.network.bootFromEnv()` reads every supported env var at startup and applies in the right order so configuration takes effect before the first outbound socket; the wiki app's docker-compose configs ship every knob with a default-empty value (production overlay tightens DNS lookup timeout + cache TTL + `NTP_STRICT=1` + `SOCKET_NO_DELAY=1`). `.gitleaks.toml` was previously gitignored by the deny-all-dotfiles allowlist; it is now allowlisted so CI's secret-scan job loads the framework's allowlist and stops failing on `.gitleaks.toml: no such file or directory`. New wiki page `/network-config` documents all six sub-primitives.

package/README.md

@@ -71,18 +71,26 @@ Full primitive-by-primitive docs live at [blamejs.com](https://blamejs.com), whi
 `blamejs` ships an operator-facing CLI for the recurring ops work. Each subcommand boots a headless app instance from `--data-dir` (no HTTP listener), runs the operation, and shuts down. Same vault + DB + audit chain the running app uses.
 
 ```
-blamejs migrate    up | down | status                   --db <path> [--dir <path>]
-blamejs seed       run | status                         --db <path> --env <name> [--dir <path>]
-blamejs vault      status | seal | unseal | rotate      --data-dir <path>
-blamejs backup     inspect | verify | extract           --bundle <dir>
-blamejs api-key    issue | revoke | list | rotate | verify   --data-dir <path> --namespace <ns>
-blamejs mtls       status | show-cert | init | issue | issue-p12   --data-dir <path>
-blamejs audit      archive | export | verify-bundle | purge
-blamejs api-snapshot   capture | compare                --file <path>
-blamejs dev        --command <cmd> [--watch <dir>...]
+blamejs migrate       up | down | status                          --db <path> [--dir <path>]
+blamejs seed          run | status                                --db <path> --env <name> [--dir <path>]
+blamejs dev           --command <cmd> [--watch <dir>...]
+blamejs api-snapshot  capture | compare                           --file <path>
+blamejs api-key       issue | revoke | list | rotate | verify     --data-dir <path> --namespace <ns>
+blamejs audit         archive | export | verify | purge           --data-dir <path>
+blamejs backup        inspect | verify | extract                  --bundle <path>
+blamejs mtls          status | show-cert | init | issue | issue-p12  --data-dir <path>
+blamejs vault         status | seal | unseal | rotate             --data-dir <path>
+blamejs security      assert                                      --data-dir <path>
+blamejs config-drift  inspect | verify                            --data-dir <path>
+blamejs file-type     detect <file>                               [--allowlist image,pdf,...]
+blamejs password      check                                       --plaintext "..." [--profile pci-4.0|nist-aal2|hipaa-aal2] [--breach-check] [--email <e>] [--username <u>]
+blamejs erase         --table <t> --row-id <id> --confirm         --data-dir <path>
+blamejs retention     preview | run                               --data-dir <path> --table <t> --age-field <col> --ttl-ms <n> [--action soft-delete|delete|erase] [--soft-delete-field <col>]
+blamejs version
+blamejs help [<command>]
 ```
 
-Pass `--help` to any subcommand for the full flag list. Passphrases for crypto-backed operations resolve from the appropriate env var (`BLAMEJS_VAULT_PASSPHRASE`, `BLAMEJS_BACKUP_PASSPHRASE`, `BLAMEJS_AUDIT_PASSPHRASE`) so they don't end up in shell history.
+Pass `--help` to any subcommand for the full flag list (`blamejs api-key --help` etc.). Passphrases for crypto-backed operations resolve from the appropriate env var (`BLAMEJS_VAULT_PASSPHRASE`, `BLAMEJS_BACKUP_PASSPHRASE`, `BLAMEJS_AUDIT_PASSPHRASE`) so they don't end up in shell history.
 
 ## Reference app + deployment
 

package/lib/archive.js

@@ -21,16 +21,17 @@
  *   - UTF-8 file names (sets the EFS bit per APPNOTE 6.3.4)
  *   - Modification time defaults to "now"; operators override per file
  *
- * v1 scope cuts (deferred):
- *   - ZIP64 (>4 GiB archives, >65535 files) — operators with that
- *     scale bring their own
+ * Out of scope:
+ *   - ZIP64 (>4 GiB archives, >65535 files) — operators at that scale
+ *     bring their own toolset
  *   - Encryption — `b.crypto.encryptPacked` produces a sealed bundle
  *     for the operator's encryption-at-rest needs; ZIP-native
  *     password encryption is broken-by-design
- *   - Streaming write (toStream) — toBuffer() is enough for the
- *     "download my data" shape; operators streaming gigabytes
- *     have a different toolset
- *   - Reading / extraction — write-only for now
+ *   - Streaming write (toStream) — toBuffer() covers the "download my
+ *     data" shape; operators streaming gigabytes use the operator-side
+ *     toolset
+ *   - Reading / extraction — write-only; operators use node:zlib +
+ *     yauzl (or unzip in shell) for read paths
  */
 var zlib = require("node:zlib");
 var fs   = require("node:fs");

package/lib/bundler.js

@@ -2,24 +2,24 @@
 /**
  * bundler — content-hashed asset pipeline + manifest.
  *
- * What this primitive does today:
+ * What this primitive does:
  *   - Reads each named entry from disk
  *   - Computes a content hash (SHA3-512, first 16 hex chars)
  *   - Writes the entry to outdir/<name>.<hash>.<ext> for cache-busting
  *   - Emits manifest.json mapping logical name → hashed filename
  *   - Optionally watches entries and rebuilds on change
  *
- * What it does NOT do today (deliberately deferred):
+ * Out of scope (operators bring their own tool when they need these):
  *   - Module-graph resolution (esbuild-style multi-file bundling)
  *   - Tree shaking, dead-code elimination, AST transforms
  *   - Source maps
- *   - Minification (a regex-based pass mishandles comments inside
- *     string and regex literals; AST-based minification waits for the
- *     esbuild-wasm vendoring slice)
+ *   - Minification (an AST-based pass would need a vendored ESM parser;
+ *     the framework's `b.bundler` is the cache-bust + manifest layer,
+ *     not a full bundler)
  *
- * Operators with multi-file ESM source either pre-concat manually and
- * point bundler at the result, or use an external tool today; the
- * bundler primitive's interface stays stable when full bundling lands.
+ * Operators with multi-file ESM source pre-concat manually and point
+ * bundler at the result, or use an external bundler that emits the
+ * concatenated entry — `b.bundler` then hashes + manifests the output.
  *
  *   var bundler = b.bundler.create({
  *     entries:   { app: "./public/js/app.js", styles: "./public/css/app.css" },

package/lib/cache.js

@@ -74,11 +74,6 @@
  *
  * What is NOT in the box:
  *
- *   - Tag invalidation on the cluster backend — invalidating tagged
- *     entries across cluster nodes ties to a future distributed-pubsub
- *     slice. invalidateTag against a cluster-backend cache throws
- *     NOT_SUPPORTED today; operators wanting cluster-scope tag wipe
- *     run their own DELETE against _blamejs_cache.
  *   - maxBytes on the cluster backend — per-row size accounting against
  *     a shared table would mean an aggregate query on every set. The
  *     operator controls cluster-table size with their own pruning if
@@ -509,28 +504,98 @@ function _clusterBackend(cfg) {
     catch (_e) { return undefined; }
   }
 
-  async function set(key, value, expiresAt) {
+  async function set(key, value, expiresAt, meta) {
     var json = JSON.stringify(value);
     var storedExpires = (expiresAt === Infinity) ? Number.MAX_SAFE_INTEGER : expiresAt;
     var now = clock();
+    var ck = _composedKey(key);
     // SQLite + Postgres both honor ON CONFLICT (cacheKey) DO UPDATE.
     await clusterStorage.execute(
       "INSERT INTO _blamejs_cache (cacheKey, valueJson, expiresAt, updatedAt) " +
       "VALUES (?, ?, ?, ?) " +
       "ON CONFLICT (cacheKey) DO UPDATE SET " +
       "valueJson = ?, expiresAt = ?, updatedAt = ?",
-      [_composedKey(key), json, storedExpires, now, json, storedExpires, now]
+      [ck, json, storedExpires, now, json, storedExpires, now]
+    );
+    // Tag handling: drop any prior tags for this key (tags can change
+    // across sets), then INSERT the new ones. The PRIMARY KEY on
+    // (cacheKey, tag) makes the INSERT idempotent if duplicate tags
+    // sneak in.
+    var tags = meta && Array.isArray(meta.tags) ? meta.tags : null;
+    await clusterStorage.execute(
+      "DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?",
+      [ck]
     );
+    if (tags && tags.length > 0) {
+      for (var i = 0; i < tags.length; i++) {
+        await clusterStorage.execute(
+          "INSERT INTO _blamejs_cache_tags (cacheKey, tag) VALUES (?, ?) " +
+          "ON CONFLICT (cacheKey, tag) DO NOTHING",
+          [ck, tags[i]]
+        );
+      }
+    }
   }
 
   async function del(key) {
+    var ck = _composedKey(key);
     var result = await clusterStorage.execute(
       "DELETE FROM _blamejs_cache WHERE cacheKey = ?",
-      [_composedKey(key)]
+      [ck]
     );
+    // Drop any matching tag rows. Best-effort: a stale tag row pointing
+    // at a non-existent cacheKey is dropped on the next invalidateTag
+    // sweep (by the JOIN-shape DELETE) anyway.
+    await clusterStorage.execute(
+      "DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?",
+      [ck]
+    ).catch(function () { /* best-effort */ });
     return !!(result && result.rowCount && result.rowCount > 0);
   }
 
+  async function invalidateTag(tag) {
+    // Find every cacheKey carrying the tag (namespace-scoped via the LIKE
+    // on the composed key), delete from the cache table + the junction.
+    var like = namespace + ":%";
+    var keysResult = await clusterStorage.execute(
+      "SELECT cacheKey FROM _blamejs_cache_tags WHERE tag = ? AND cacheKey LIKE ?",
+      [tag, like]
+    );
+    var keys = (keysResult && keysResult.rows) || [];
+    if (keys.length === 0) {
+      // Nothing to invalidate; still drop any orphan tag rows for
+      // this tag scoped to our namespace.
+      await clusterStorage.execute(
+        "DELETE FROM _blamejs_cache_tags WHERE tag = ? AND cacheKey LIKE ?",
+        [tag, like]
+      );
+      return 0;
+    }
+    var purged = 0;
+    for (var i = 0; i < keys.length; i++) {
+      var ck = keys[i].cacheKey;
+      var r = await clusterStorage.execute(
+        "DELETE FROM _blamejs_cache WHERE cacheKey = ?",
+        [ck]
+      );
+      if (r && r.rowCount > 0) purged += r.rowCount;
+      await clusterStorage.execute(
+        "DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?",
+        [ck]
+      );
+    }
+    return purged;
+  }
+
+  async function getTags(key) {
+    var result = await clusterStorage.execute(
+      "SELECT tag FROM _blamejs_cache_tags WHERE cacheKey = ?",
+      [_composedKey(key)]
+    );
+    if (!result || !result.rows) return [];
+    return result.rows.map(function (r) { return r.tag; });
+  }
+
   async function has(key) {
     // Existence check without recency bump — cluster backend doesn't
     // track LRU at all, so "without bumping" is automatic. Honors
@@ -551,6 +616,11 @@ function _clusterBackend(cfg) {
       "DELETE FROM _blamejs_cache WHERE cacheKey LIKE ?",
       [like]
     );
+    // Drop matching tag rows in the same namespace.
+    await clusterStorage.execute(
+      "DELETE FROM _blamejs_cache_tags WHERE cacheKey LIKE ?",
+      [like]
+    ).catch(function () { /* best-effort */ });
     return (result && result.rowCount) || 0;
   }
 
@@ -568,10 +638,24 @@ function _clusterBackend(cfg) {
   async function _sweep() {
     var now = clock();
     var like = namespace + ":%";
+    // Capture the to-be-purged keys first so we can drop matching tag
+    // rows in the same sweep — keeps the junction table free of orphans
+    // pointing at expired cacheKeys.
+    var expiredResult = await clusterStorage.execute(
+      "SELECT cacheKey FROM _blamejs_cache WHERE cacheKey LIKE ? AND expiresAt <= ?",
+      [like, now]
+    );
+    var expiredKeys = (expiredResult && expiredResult.rows) || [];
     await clusterStorage.execute(
       "DELETE FROM _blamejs_cache WHERE cacheKey LIKE ? AND expiresAt <= ?",
       [like, now]
     );
+    for (var i = 0; i < expiredKeys.length; i++) {
+      await clusterStorage.execute(
+        "DELETE FROM _blamejs_cache_tags WHERE cacheKey = ?",
+        [expiredKeys[i].cacheKey]
+      ).catch(function () { /* best-effort */ });
+    }
   }
 
   function _startSweep(intervalMs) {
@@ -583,15 +667,17 @@ function _clusterBackend(cfg) {
   }
 
   return {
-    name:         "cluster",
-    get:          get,
-    set:          set,
-    del:          del,
-    has:          has,
-    clear:        clear,
-    size:         size,
-    close:        close,
-    _startSweep:  _startSweep,
+    name:           "cluster",
+    get:            get,
+    set:            set,
+    del:            del,
+    has:            has,
+    clear:          clear,
+    size:           size,
+    close:          close,
+    invalidateTag:  invalidateTag,
+    getTags:        getTags,
+    _startSweep:    _startSweep,
   };
 }
 
@@ -865,9 +951,8 @@ function create(opts) {
     if (typeof backend.invalidateTag !== "function") {
       throw _err("NOT_SUPPORTED",
         "cache.invalidateTag: backend '" + (backend.name || "custom") +
-        "' does not support tag invalidation. Tags are memory-backend only " +
-        "in this release; the cluster backend gains tag support alongside " +
-        "the distributed-invalidation slice.");
+        "' does not implement invalidateTag. Operator-supplied custom backends " +
+        "must export invalidateTag(tag) → number to participate in tag-based wipes.");
     }
     var purged;
     try { purged = await backend.invalidateTag(tag); }

package/lib/db-query.js

@@ -148,7 +148,21 @@ class Query {
     if (direction !== "asc" && direction !== "desc") {
       throw new Error("orderBy direction must be 'asc' or 'desc'");
     }
-    this._orderBy = { field: field, direction: direction.toUpperCase() };
+    var entry = { field: field, direction: direction.toUpperCase() };
+    if (this._orderBy === null) {
+      // First call — keep the back-compat single-object shape so any
+      // legacy reader that does `query._orderBy.field` keeps working.
+      this._orderBy = entry;
+      return this;
+    }
+    // Second-or-later call — promote to an array. Multi-column ORDER BY
+    // is the keyset-pagination tiebreaker pattern: ORDER BY createdAt
+    // DESC, _id DESC means same-second rows still have a total order.
+    if (Array.isArray(this._orderBy)) {
+      this._orderBy.push(entry);
+    } else {
+      this._orderBy = [this._orderBy, entry];
+    }
     return this;
   }
 
@@ -173,7 +187,12 @@ class Query {
   _orderLimitOffset() {
     var s = "";
     if (this._orderBy) {
-      s += ' ORDER BY "' + this._orderBy.field + '" ' + this._orderBy.direction;
+      var entries = Array.isArray(this._orderBy) ? this._orderBy : [this._orderBy];
+      var fragments = [];
+      for (var i = 0; i < entries.length; i++) {
+        fragments.push('"' + entries[i].field + '" ' + entries[i].direction);
+      }
+      s += " ORDER BY " + fragments.join(", ");
     }
     if (this._limit !== null)  s += " LIMIT "  + this._limit;
     if (this._offset !== null) s += " OFFSET " + this._offset;

package/lib/db.js

@@ -399,6 +399,21 @@ var FRAMEWORK_SCHEMA = [
     indexes: ["expiresAt"],
     sealedFields: [],
   },
+  {
+    // _blamejs_cache_tags — junction table for tag→cacheKey lookup
+    // backing b.cache.invalidateTag(t) on the cluster backend. Composite
+    // PK (cacheKey, tag) lets one cacheKey carry many tags; index on
+    // tag makes invalidation a single indexed scan. Cleared together
+    // with the matching _blamejs_cache rows on del / clear / sweep.
+    name: "_blamejs_cache_tags",
+    columns: {
+      cacheKey:   "TEXT NOT NULL",
+      tag:        "TEXT NOT NULL",
+    },
+    primaryKey: ["cacheKey", "tag"],
+    indexes:    ["tag"],
+    sealedFields: [],
+  },
   {
     // _blamejs_seeders — registry of applied seed files for the
     // b.seeders primitive (lib/seeders.js). Composite PK (env, name)

package/lib/framework-schema.js

@@ -16,20 +16,26 @@
  *   _blamejs_audit_log external-db name
  *
  * The mapping is exposed via tableName(local) so write-dispatch code
- * (next release) can use a single name reference.
+ * (cluster-storage.js) uses a single name reference and the
+ * dialect-aware ensureSchema fans out the DDL to either the local-
+ * SQLite (db.js's FRAMEWORK_SCHEMA) or the external-db backend.
  *
  * Dialects: Postgres + SQLite. Both support CREATE TABLE IF NOT EXISTS,
  * CREATE INDEX IF NOT EXISTS, and the same column types modulo
- * INTEGER/BIGINT and BLOB/BYTEA differences. MySQL is not yet
- * supported — operators on MySQL must wait for that adapter.
+ * INTEGER/BIGINT and BLOB/BYTEA differences. MySQL is not currently
+ * supported — operators on MySQL must use one of the supported
+ * dialects until a MySQL adapter ships.
  *
  * What ensureSchema does NOT do:
  *   - Migrate existing audit_log rows from local SQLite into external-db.
  *     That migration belongs to a separate operator-driven tool.
  *   - Verify chain integrity in external-db. That happens at boot via
- *     the audit module's regular verify() path once dispatch lands.
- *   - Install append-only triggers. Trigger syntax differs across
- *     dialects and is being deferred to the next release.
+ *     the audit module's regular verify() path on every read.
+ *   - Install append-only triggers. The framework's tamper-evidence
+ *     model is the audit chain's hash linkage + SLH-DSA-signed
+ *     checkpoints — triggers would add a defense-in-depth layer
+ *     but they're not load-bearing for the threat model. Operators
+ *     who want triggers add them per their dialect's syntax.
  *
  * Public API:
  *   await frameworkSchema.ensureSchema({ externalDbBackend, dialect })
@@ -114,6 +120,11 @@ var LOCAL_TO_EXTERNAL = Object.freeze({
   // values, BIGINT expiresAt for ttl. Indexed on expiresAt for the
   // periodic prune query.
   _blamejs_cache:     "_blamejs_cache",
+  // _blamejs_cache_tags — junction table for tag-based cache
+  // invalidation on the cluster backend. Composite PK
+  // (cacheKey, tag) lets a single cacheKey carry many tags;
+  // index on tag makes invalidateTag(t) a single indexed scan.
+  _blamejs_cache_tags: "_blamejs_cache_tags",
   // _blamejs_seeders — registry of applied seed files for b.seeders
   // (lib/seeders.js). Composite PK (env, name) lets the same filename
   // apply per env. Mirrors the local-SQLite shape in db.js
@@ -561,6 +572,26 @@ function _cacheDDL(dialect) {
   };
 }
 
+// _blamejs_cache_tags — tag→cacheKey junction for cluster-backend
+// tag invalidation. b.cache.invalidateTag(t) finds matching cacheKeys
+// via the indexed `tag` column, deletes them from _blamejs_cache, and
+// drops the junction rows. Cleared on cache.clear() and del() too.
+function _cacheTagsDDL(_dialect) {
+  // Junction table is TEXT-only — no dialect-specific INT / BLOB needed.
+  var name = LOCAL_TO_EXTERNAL._blamejs_cache_tags;
+  return {
+    create:
+      "CREATE TABLE IF NOT EXISTS " + name + " (" +
+      "  cacheKey  TEXT NOT NULL," +
+      "  tag       TEXT NOT NULL," +
+      "  PRIMARY KEY (cacheKey, tag)" +
+      ")",
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_" + name + "_tag ON " + name + " (tag)",
+    ],
+  };
+}
+
 // _blamejs_break_glass_policies — column-level break-glass policy
 // registry. One row per (table) declares which columns are
 // glass-locked + the operator's grant rules. Sealed columns hide
@@ -658,6 +689,7 @@ async function ensureSchema(opts) {
     _sessionsDDL(dialect),
     _jobsDDL(dialect),
     _cacheDDL(dialect),
+    _cacheTagsDDL(dialect),
     _seedersDDL(dialect),
     _seedersLockDDL(dialect),
     _breakGlassPoliciesDDL(dialect),

package/lib/http-client-cookie-jar.js

@@ -6,24 +6,41 @@
  * (login → list → mutate → logout, OAuth code-exchange → userinfo, etc.)
  * carry the right Cookie header without operators threading it by hand.
  * RFC 6265 attribute coverage: Domain / Path / Expires / Max-Age /
- * HttpOnly / Secure / SameSite. Public Suffix List awareness is
- * deliberately deferred — operators wiring jars against trusted
- * domains don't need it; re-open if a real cross-eTLD bug surfaces.
+ * HttpOnly / Secure / SameSite. Public Suffix List (PSL) awareness is
+ * out of scope — operators wiring jars against trusted upstream
+ * domains don't need it; for cross-eTLD safety in untrusted contexts,
+ * use a per-domain jar and validate the host against an allowlist.
  *
  *   var jar = b.httpClient.cookieJar.create();      // in-memory
  *   await b.httpClient.request({ url: loginUrl, method: "POST", body, jar });
  *   await b.httpClient.request({ url: meUrl, jar });   // session cookie attaches
  *
- * Vault-encrypted persistence — every cookie value is sealed via
- * b.vault.seal before it lands in the jar's store, so a memory dump or
- * core file doesn't expose plaintext values:
+ * Three persistence modes:
  *
- *   var jar = b.httpClient.cookieJar.create({ persist: "vault", vault: b.vault });
+ *   memory  — in-process Map. Restart loses everything.
+ *   vault   — every cookie value is sealed via b.vault.seal before it
+ *             lands in the in-process Map, so a memory dump or core
+ *             file doesn't expose plaintext values:
  *
- * The jar's lifecycle is per-process — restart loses cookies regardless
- * of persist mode. File-backed and cluster-shared persistence are
- * deferred; operators wanting durability serialize via getAll() and
- * restore via setFromSerialized() at boot.
+ *               b.httpClient.cookieJar.create({ persist: "vault", vault: b.vault })
+ *
+ *   file    — on-disk persistence at opts.file (absolute path). Loaded
+ *             at create() if the file exists; flushed (debounced via
+ *             opts.flushDebounceMs, default 100ms) on every set / clear
+ *             / setFromSerialized. Pass `vault` alongside `file` to
+ *             seal the on-disk bytes; without vault the file is
+ *             plaintext JSON (operator chose the threat model).
+ *
+ *               b.httpClient.cookieJar.create({
+ *                 persist: "file",
+ *                 file:    "/var/lib/myapp/jar.json",
+ *                 vault:   b.vault,           // optional but recommended
+ *               })
+ *
+ * The file mode survives process restart. Cluster-shared persistence
+ * (multiple nodes sharing one jar) is out of scope; operators with
+ * that need wire a custom jar via the same shape as the returned
+ * object (setFromResponse / cookieHeaderFor / getAll / etc.).
  *
  * Outbound filtering follows RFC 6265 §5.4:
  *   - Domain: exact-host match by default; Domain attribute allows
@@ -43,6 +60,8 @@
  *   }
  */
 
+var fs = require("node:fs");
+var path = require("node:path");
 var C = require("./constants");
 var safeUrl = require("./safe-url");
 var { defineClass } = require("./framework-error");
@@ -51,10 +70,11 @@ var CookieJarError = defineClass("CookieJarError", { alwaysPermanent: true });
 var _err = CookieJarError.factory;
 
 var DEFAULTS = Object.freeze({
-  persist: "memory",
+  persist:        "memory",
+  flushDebounceMs: 100,
 });
 
-var VALID_PERSIST = new Set(["memory", "vault"]);
+var VALID_PERSIST = new Set(["memory", "vault", "file"]);
 var VALID_SAMESITE = new Set(["Strict", "Lax", "None"]);
 
 // ---- Set-Cookie parser ----
@@ -130,7 +150,7 @@ function create(opts) {
   opts = opts || {};
   var persist = opts.persist === undefined ? DEFAULTS.persist : opts.persist;
   if (!VALID_PERSIST.has(persist)) {
-    throw _err("BAD_OPT", "cookieJar.create: persist must be 'memory' or 'vault', got " +
+    throw _err("BAD_OPT", "cookieJar.create: persist must be 'memory' | 'vault' | 'file', got " +
       JSON.stringify(persist));
   }
   var vault = opts.vault || null;
@@ -140,6 +160,22 @@ function create(opts) {
         "cookieJar.create: persist: 'vault' requires opts.vault with seal/unseal (pass b.vault)");
     }
   }
+  var filePath = null;
+  if (persist === "file") {
+    if (typeof opts.file !== "string" || opts.file.length === 0) {
+      throw _err("BAD_OPT",
+        "cookieJar.create: persist: 'file' requires opts.file (absolute path)");
+    }
+    filePath = opts.file;
+    // Refuse relative paths so a process running in a different cwd
+    // doesn't accidentally serialize to a sibling directory.
+    if (!path.isAbsolute(filePath)) {
+      throw _err("BAD_OPT",
+        "cookieJar.create: opts.file must be an absolute path, got " + JSON.stringify(filePath));
+    }
+  }
+  var flushDebounceMs = (typeof opts.flushDebounceMs === "number" && opts.flushDebounceMs >= 0)
+    ? opts.flushDebounceMs : DEFAULTS.flushDebounceMs;
   var clock = typeof opts.clock === "function" ? opts.clock : Date.now;
 
   // Storage map keyed by `<domain>|<path>|<name>` so a (domain, path)
@@ -377,14 +413,78 @@ function create(opts) {
     return rows;
   }
 
+  // ---- File persistence ----
+  // When persist === "file", load on construct + flush on every write
+  // (debounced). On-disk format is JSON of getAll() output. If a vault
+  // is also passed, the file is sealed via vault.seal so the on-disk
+  // bytes are encrypted at rest; otherwise plaintext (operator chose
+  // the threat model by passing or omitting vault).
+  var flushTimer = null;
+  function _flushSync() {
+    if (!filePath) return;
+    var rows = getAll();
+    var serialized = JSON.stringify(rows);
+    var blob = vault ? vault.seal(serialized) : serialized;
+    fs.writeFileSync(filePath, blob);
+  }
+  function _scheduleFlush() {
+    if (!filePath) return;
+    if (flushTimer) return;
+    flushTimer = setTimeout(function () {
+      flushTimer = null;
+      try { _flushSync(); } catch (_e) { /* operator can call flush() to retry */ }
+    }, flushDebounceMs);
+    if (flushTimer.unref) flushTimer.unref();
+  }
+  function flush() {
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    _flushSync();
+  }
+  function close() {
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    if (filePath) try { _flushSync(); } catch (_e) { /* best-effort */ }
+  }
+
+  // Wrap mutating entrypoints so each write schedules a flush. The
+  // wrappers go on the returned object — the underlying function
+  // declarations stay intact so other internal callers reach them.
+  var setFromResponseAndFlush = function (reqUrl, hdr) {
+    setFromResponse(reqUrl, hdr); _scheduleFlush();
+  };
+  var clearAndFlush = function (filter) {
+    var n = clear(filter); _scheduleFlush(); return n;
+  };
+  var setFromSerializedAndFlush = function (rows) {
+    setFromSerialized(rows); _scheduleFlush();
+  };
+
+  // Initial load from file. Missing file is fine (first run).
+  if (filePath && fs.existsSync(filePath)) {
+    try {
+      var raw = fs.readFileSync(filePath, "utf8");
+      var serialized = vault ? vault.unseal(raw) : raw;
+      if (serialized && serialized.length > 0) {
+        var rows = JSON.parse(serialized);
+        setFromSerialized(rows);
+      }
+    } catch (e) {
+      throw _err("LOAD_FAILED",
+        "cookieJar.create: failed to load persist file '" + filePath + "': " +
+        (e.message || String(e)));
+    }
+  }
+
   return {
-    setFromResponse:    setFromResponse,
+    setFromResponse:    filePath ? setFromResponseAndFlush   : setFromResponse,
     cookieHeaderFor:    cookieHeaderFor,
     getAll:             getAll,
-    clear:              clear,
+    clear:              filePath ? clearAndFlush             : clear,
     size:               size,
-    setFromSerialized:  setFromSerialized,
+    setFromSerialized:  filePath ? setFromSerializedAndFlush : setFromSerialized,
+    flush:              flush,
+    close:              close,
     persist:            persist,
+    file:               filePath,
     _storeForTest:      _storeForTest,
   };
 }