@blamejs/core 0.6.13 → 0.6.21

package/lib/file-type.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * file-type — magic-byte content detection.
+ *
+ * MIME on a multipart upload comes from the CLIENT — a malicious
+ * uploader can label a polyglot HTML payload as "image/png" and the
+ * Content-Type header alone won't catch it. This primitive inspects
+ * the leading bytes of a buffer against a hardcoded magic-byte
+ * registry and returns the actual format independently of the
+ * advertised MIME.
+ *
+ *   var detected = b.fileType.detect(buffer);
+ *   // → { mime: "image/png", extension: "png", category: "image" }
+ *   //   OR null when no signature matches
+ *
+ *   var ok = b.fileType.assertOneOf(buffer, ["image/png", "image/jpeg", "application/pdf"]);
+ *   // → throws FileTypeError if the actual format isn't in the allowlist
+ *
+ * Coverage targets the formats most likely to flow through a typical
+ * web app's upload boundary: images (PNG/JPEG/GIF/WEBP/AVIF/HEIC),
+ * documents (PDF/DOCX/XLSX/PPTX), archives (ZIP/RAR/7Z/TAR/GZ),
+ * audio/video (MP3/MP4/WEBM), and a small set of executable formats
+ * to deny on upload (PE/ELF/Mach-O). Operators with format coverage
+ * outside this list either pass an `extra` registry to extend, or
+ * fall back to libmagic via an external sandbox process.
+ *
+ * Validation policy:
+ *   - detect(buffer) → returns null on bad input rather than throwing
+ *     (saved-for-later analysis often runs against partial reads)
+ *   - assertOneOf(buffer, allowlist[, opts]) throws on mismatch.
+ *     Operator opt: `allowEmpty: true` to permit zero-length buffers
+ *     (default false — empty multipart parts are usually a mistake).
+ *
+ * Out of scope (operator brings their own):
+ *   - Content disarm (CDR — strip Office macros, PDF JS, etc.).
+ *     CDR is genuinely hard and format-specific; operators with that
+ *     requirement reach for a sandbox like dangerzone or vmray.
+ *   - Polyglot file detection (a single file that is BOTH valid PDF
+ *     AND valid HTML). detect() returns the first signature match;
+ *     true polyglot defense needs structural validation per format.
+ *   - Filename-extension validation. The framework's view is:
+ *     extensions are operator-controlled metadata, magic bytes are
+ *     the wire truth.
+ */
+var { defineClass } = require("./framework-error");
+
+var FileTypeError = defineClass("FileTypeError", { alwaysPermanent: true });
+var _err = FileTypeError.factory;
+
+// Signature registry. Each entry: { name, mime, extension, category,
+// offset, magic: Buffer | [Buffer, ...], extra?: function(buffer)→bool }.
+// Order matters — earlier entries win on ambiguous matches (e.g. ZIP
+// shape catches OOXML, so OOXML-specific entries come FIRST).
+var SIGNATURES = [
+  // ---- Office Open XML (DOCX/XLSX/PPTX) ----
+  // OOXML files are ZIP archives whose central directory contains
+  // [Content_Types].xml. The cheap shape-check is the ZIP local-file
+  // header (0x50 0x4B 0x03 0x04) PLUS the filename "[Content_Types].xml"
+  // appearing within the first 256 bytes — present for every
+  // well-formed OOXML produced by Office / LibreOffice / etc.
+  { name: "docx", mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    extension: "docx", category: "document",
+    offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
+    extra: function (buf) {
+      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      return head.indexOf("word/") !== -1 || head.indexOf("[Content_Types].xml") !== -1 && head.indexOf("word") !== -1;
+    } },
+  { name: "xlsx", mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    extension: "xlsx", category: "document",
+    offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
+    extra: function (buf) {
+      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      return head.indexOf("xl/") !== -1;
+    } },
+  { name: "pptx", mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    extension: "pptx", category: "document",
+    offset: 0, magic: Buffer.from([0x50, 0x4B, 0x03, 0x04]),
+    extra: function (buf) {
+      var head = buf.subarray(0, Math.min(buf.length, 4096)).toString("binary");
+      return head.indexOf("ppt/") !== -1;
+    } },
+  // ---- Plain ZIP (after OOXML so OOXML wins) ----
+  { name: "zip", mime: "application/zip", extension: "zip", category: "archive",
+    offset: 0, magic: [
+      Buffer.from([0x50, 0x4B, 0x03, 0x04]),     // standard local file header
+      Buffer.from([0x50, 0x4B, 0x05, 0x06]),     // empty archive
+      Buffer.from([0x50, 0x4B, 0x07, 0x08]),     // spanned archive
+    ] },
+
+  // ---- Images ----
+  { name: "png",  mime: "image/png",  extension: "png", category: "image",
+    offset: 0, magic: Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]) },
+  { name: "jpeg", mime: "image/jpeg", extension: "jpg", category: "image",
+    offset: 0, magic: Buffer.from([0xFF, 0xD8, 0xFF]) },
+  { name: "gif",  mime: "image/gif",  extension: "gif", category: "image",
+    offset: 0, magic: [Buffer.from("GIF87a", "ascii"), Buffer.from("GIF89a", "ascii")] },
+  { name: "webp", mime: "image/webp", extension: "webp", category: "image",
+    offset: 0, magic: Buffer.from("RIFF", "ascii"),
+    extra: function (buf) {
+      return buf.length >= 12 && buf.subarray(8, 12).toString("ascii") === "WEBP";
+    } },
+  { name: "bmp",  mime: "image/bmp",  extension: "bmp", category: "image",
+    offset: 0, magic: Buffer.from([0x42, 0x4D]) },
+  { name: "tiff", mime: "image/tiff", extension: "tiff", category: "image",
+    offset: 0, magic: [
+      Buffer.from([0x49, 0x49, 0x2A, 0x00]),     // little-endian
+      Buffer.from([0x4D, 0x4D, 0x00, 0x2A]),     // big-endian
+    ] },
+  { name: "avif", mime: "image/avif", extension: "avif", category: "image",
+    offset: 4, magic: Buffer.from("ftypavif", "ascii") },
+  { name: "heic", mime: "image/heic", extension: "heic", category: "image",
+    offset: 4, magic: [
+      Buffer.from("ftypheic", "ascii"),
+      Buffer.from("ftypheix", "ascii"),
+      Buffer.from("ftypmif1", "ascii"),
+      Buffer.from("ftypmsf1", "ascii"),
+    ] },
+
+  // ---- Documents (non-OOXML) ----
+  { name: "pdf",  mime: "application/pdf", extension: "pdf", category: "document",
+    offset: 0, magic: Buffer.from("%PDF-", "ascii") },
+  { name: "rtf",  mime: "application/rtf", extension: "rtf", category: "document",
+    offset: 0, magic: Buffer.from("{\\rtf", "ascii") },
+  // CFB (Compound File Binary) — old Office (.doc/.xls/.ppt before 2007),
+  // also MSI installers.
+  { name: "cfb",  mime: "application/x-cfb", extension: "doc", category: "document",
+    offset: 0, magic: Buffer.from([0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1]) },
+
+  // ---- Archives ----
+  { name: "rar",  mime: "application/vnd.rar", extension: "rar", category: "archive",
+    offset: 0, magic: [
+      Buffer.from([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00]),       // RAR 1.5
+      Buffer.from([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00]), // RAR 5
+    ] },
+  { name: "7z",   mime: "application/x-7z-compressed", extension: "7z", category: "archive",
+    offset: 0, magic: Buffer.from([0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C]) },
+  { name: "gz",   mime: "application/gzip", extension: "gz", category: "archive",
+    offset: 0, magic: Buffer.from([0x1F, 0x8B]) },
+  { name: "bz2",  mime: "application/x-bzip2", extension: "bz2", category: "archive",
+    offset: 0, magic: Buffer.from("BZh", "ascii") },
+  { name: "xz",   mime: "application/x-xz", extension: "xz", category: "archive",
+    offset: 0, magic: Buffer.from([0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00]) },
+  { name: "tar",  mime: "application/x-tar", extension: "tar", category: "archive",
+    offset: 257, magic: Buffer.from("ustar", "ascii") },
+
+  // ---- Audio / video ----
+  { name: "mp3",  mime: "audio/mpeg", extension: "mp3", category: "audio",
+    offset: 0, magic: [
+      Buffer.from([0x49, 0x44, 0x33]),  // ID3v2 tag
+      Buffer.from([0xFF, 0xFB]),        // MPEG audio frame (no ID3)
+      Buffer.from([0xFF, 0xF3]),
+      Buffer.from([0xFF, 0xF2]),
+    ] },
+  { name: "mp4",  mime: "video/mp4", extension: "mp4", category: "video",
+    offset: 4, magic: [
+      Buffer.from("ftypisom", "ascii"),
+      Buffer.from("ftypiso2", "ascii"),
+      Buffer.from("ftypmp42", "ascii"),
+      Buffer.from("ftypM4V ", "ascii"),
+    ] },
+  { name: "webm", mime: "video/webm", extension: "webm", category: "video",
+    offset: 0, magic: Buffer.from([0x1A, 0x45, 0xDF, 0xA3]) },
+
+  // ---- Executables (operators usually DENY these on upload) ----
+  { name: "pe",     mime: "application/x-msdownload", extension: "exe", category: "executable",
+    offset: 0, magic: Buffer.from([0x4D, 0x5A]) },
+  { name: "elf",    mime: "application/x-executable", extension: "elf", category: "executable",
+    offset: 0, magic: Buffer.from([0x7F, 0x45, 0x4C, 0x46]) },
+  { name: "macho",  mime: "application/x-mach-binary", extension: "macho", category: "executable",
+    offset: 0, magic: [
+      Buffer.from([0xFE, 0xED, 0xFA, 0xCE]),     // 32-bit BE
+      Buffer.from([0xFE, 0xED, 0xFA, 0xCF]),     // 64-bit BE
+      Buffer.from([0xCE, 0xFA, 0xED, 0xFE]),     // 32-bit LE
+      Buffer.from([0xCF, 0xFA, 0xED, 0xFE]),     // 64-bit LE
+      Buffer.from([0xCA, 0xFE, 0xBA, 0xBE]),     // universal binary (also Java .class)
+    ] },
+];
+
+function _matchesAt(buf, offset, magic) {
+  if (buf.length < offset + magic.length) return false;
+  for (var i = 0; i < magic.length; i++) {
+    if (buf[offset + i] !== magic[i]) return false;
+  }
+  return true;
+}
+
+function _entryMatches(entry, buf) {
+  var magics = Array.isArray(entry.magic) ? entry.magic : [entry.magic];
+  var matched = false;
+  for (var i = 0; i < magics.length; i++) {
+    if (_matchesAt(buf, entry.offset || 0, magics[i])) { matched = true; break; }
+  }
+  if (!matched) return false;
+  if (typeof entry.extra === "function") {
+    try { return !!entry.extra(buf); }
+    catch (_e) { return false; }
+  }
+  return true;
+}
+
+function detect(buf, opts) {
+  if (!Buffer.isBuffer(buf)) {
+    if (buf instanceof Uint8Array) buf = Buffer.from(buf);
+    else return null;
+  }
+  if (buf.length === 0) return null;
+  var registry = SIGNATURES;
+  if (opts && Array.isArray(opts.extra) && opts.extra.length > 0) {
+    // Operator-extended registry: extras come FIRST so an operator can
+    // override a built-in (e.g. tighten OOXML check) without forking.
+    registry = opts.extra.concat(SIGNATURES);
+  }
+  for (var i = 0; i < registry.length; i++) {
+    var entry = registry[i];
+    if (_entryMatches(entry, buf)) {
+      return { mime: entry.mime, extension: entry.extension, category: entry.category, name: entry.name };
+    }
+  }
+  return null;
+}
+
+function assertOneOf(buf, allowlist, opts) {
+  opts = opts || {};
+  if (!Buffer.isBuffer(buf) && !(buf instanceof Uint8Array)) {
+    throw _err("BAD_INPUT", "fileType.assertOneOf: input must be a Buffer or Uint8Array, got " + typeof buf);
+  }
+  if (Buffer.isBuffer(buf) === false) buf = Buffer.from(buf);
+  if (buf.length === 0) {
+    if (opts.allowEmpty === true) return null;
+    throw _err("EMPTY", "fileType.assertOneOf: input is zero bytes");
+  }
+  if (!Array.isArray(allowlist) || allowlist.length === 0) {
+    throw _err("BAD_OPT", "fileType.assertOneOf: allowlist must be a non-empty array");
+  }
+  var detected = detect(buf, opts);
+  if (!detected) {
+    throw _err("UNKNOWN_TYPE",
+      "fileType.assertOneOf: no signature matched the leading bytes (advertised MIME cannot be trusted alone)");
+  }
+  // allowlist entries match against `mime` OR `name` OR `category` —
+  // operators can pin "image/png" specifically OR "image" for the
+  // whole image bucket.
+  var allowed = false;
+  for (var i = 0; i < allowlist.length; i++) {
+    if (allowlist[i] === detected.mime ||
+        allowlist[i] === detected.name ||
+        allowlist[i] === detected.category) {
+      allowed = true; break;
+    }
+  }
+  if (!allowed) {
+    throw _err("DISALLOWED_TYPE",
+      "fileType.assertOneOf: detected '" + detected.mime + "' (" + detected.name +
+      ", category=" + detected.category + ") not in allowlist " + JSON.stringify(allowlist));
+  }
+  return detected;
+}
+
+module.exports = {
+  detect:        detect,
+  assertOneOf:   assertOneOf,
+  FileTypeError: FileTypeError,
+  // Internal — exposed so tests can introspect the registry shape.
+  _SIGNATURES:   SIGNATURES,
+};

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,
   };
 }

package/lib/http-client.js

@@ -73,6 +73,7 @@ var safeAsync = require("./safe-async");
 var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
 var ssrfGuard = require("./ssrf-guard");
+var networkProxy = require("./network-proxy");
 var { FrameworkError } = require("./framework-error");
 
 // Per-origin transport cache. Entry is either the resolved transport
@@ -97,8 +98,8 @@ var { FrameworkError } = require("./framework-error");
 // node's TLS layer — see TLS_SESSION_RESUMPTION_NOTES below).
 var _transports = new Map();
 
-// TLS session resumption notes — what we get for free vs. what's
-// out of reach today:
+// TLS session resumption notes — what's automatic vs. what's not
+// exposed by Node's public API:
 //
 //   keepAlive Agent (h1) / long-lived ClientHttp2Session (h2) means
 //   the WARM-CONNECTION case is zero-handshake — better than 0-RTT.
@@ -114,7 +115,8 @@ var _transports = new Map();
 //
 //   QUIC/h3 changes this calculus: 0-RTT is a first-class feature
 //   built into the protocol, with replay protection at the QUIC
-//   layer. We'll plumb it through when h3 lands.
+//   layer. The framework's `b.httpClient` is HTTP/1.1 + HTTP/2 only;
+//   operators wanting h3 wire their own client.
 
 // Pool tuning for the HTTP-client transport cache. Keep-alive is
 // shorter than the standalone pqc-agent default (1s vs 30s) because
@@ -670,6 +672,71 @@ function _requestSingle(opts) {
     return Promise.reject(e);
   }
 
+  // Optional outbound destination allowlist. When opts.allowedHosts
+  // is set, only URLs whose hostname is on the list are permitted.
+  // Layer above safeUrl (scheme/userinfo gate) and above ssrfGuard
+  // (IP-class gate) — operators with strict egress policies pin the
+  // outbound destinations the app is allowed to talk to so a
+  // compromised process can't reach arbitrary upstreams.
+  //
+  // Entry forms (each entry is a string OR an object):
+  //   "api.partner.com"            — exact host match
+  //   ".partner.com"               — suffix match: "api.partner.com" yes,
+  //                                  "evilpartner.com" no
+  //   "*.partner.com"              — same as ".partner.com" (DNS-glob shape
+  //                                  operators expect from firewall configs)
+  //   { host: "api.x.com", methods: ["GET","HEAD"] }
+  //                                — method-restricted entry; methods omitted
+  //                                  = any method
+  //
+  // A disallowed call rejects with HOST_DISALLOWED AND emits an
+  // audit event when opts.audit is wired (operator gets a structured
+  // signal that the application tried to reach somewhere it shouldn't).
+  if (Array.isArray(opts.allowedHosts) && opts.allowedHosts.length > 0) {
+    var host = u.hostname.toLowerCase();
+    var method = (opts.method || "GET").toUpperCase();
+    var ok = false;
+    for (var ai = 0; ai < opts.allowedHosts.length; ai++) {
+      var entry = opts.allowedHosts[ai];
+      var allow, allowedMethods = null;
+      if (typeof entry === "object" && entry !== null) {
+        allow = String(entry.host || "").toLowerCase();
+        if (Array.isArray(entry.methods) && entry.methods.length > 0) {
+          allowedMethods = entry.methods.map(function (m) { return String(m).toUpperCase(); });
+        }
+      } else {
+        allow = String(entry || "").toLowerCase();
+      }
+      if (allow.length === 0) continue;
+      // Normalise "*.x.com" to ".x.com" for the suffix match path.
+      if (allow.charAt(0) === "*" && allow.charAt(1) === ".") allow = allow.slice(1);
+      var matched = false;
+      if (allow.charAt(0) === ".") {
+        if (host === allow.slice(1) || host.endsWith(allow)) matched = true;
+      } else if (host === allow) {
+        matched = true;
+      }
+      if (!matched) continue;
+      if (allowedMethods !== null && allowedMethods.indexOf(method) === -1) continue;
+      ok = true;
+      break;
+    }
+    if (!ok) {
+      if (opts.audit && typeof opts.audit.safeEmit === "function") {
+        try {
+          opts.audit.safeEmit({
+            action:   "system.httpclient.host_denied",
+            outcome:  "denied",
+            resource: { kind: "outbound.http", id: host },
+            metadata: { method: method, url: opts.url, allowedHostsCount: opts.allowedHosts.length },
+          });
+        } catch (_e) { /* audit best-effort */ }
+      }
+      return Promise.reject(_makeError(opts.errorClass, "HOST_DISALLOWED",
+        "host '" + host + "' not in allowedHosts (method=" + method + ")", true));
+    }
+  }
+
   // Attach jar-derived Cookie header BEFORE the request fires; record
   // Set-Cookie response headers AFTER. Both halves run when opts.jar
   // is set; redirect-following naturally re-runs both paths per hop
@@ -702,6 +769,17 @@ function _requestSingle(opts) {
       }, u, opts);
     }
 
+    var proxyAgent = null;
+    try { proxyAgent = networkProxy.agentFor(u); } catch (_e) { proxyAgent = null; }
+    if (proxyAgent) {
+      return _requestH1({
+        kind:   "h1",
+        lib:    u.protocol === "https:" ? https : http,
+        agent:  proxyAgent,
+        lookup: undefined,
+      }, u, opts);
+    }
+
     return _getTransport(u, opts, ips).then(function (transport) {
       if (transport.kind === "h2") return _requestH2(transport, u, opts);
       return _requestH1(transport, u, opts);