@blamejs/core 0.9.14 → 0.9.15

package/lib/middleware/api-encrypt.js

@@ -96,7 +96,7 @@
  *   public/private routes can debug their wiring.
  */
 
-var crypto = require("../crypto");
+var bCrypto = require("../crypto");
 var C = require("../constants");
 var lazyRequire = require("../lazy-require");
 var nonceStoreLib = require("../nonce-store");
@@ -449,7 +449,7 @@ function create(opts) {
     res.json = function (data) {
       try {
         var ptBuf = Buffer.from(JSON.stringify(data), "utf8");
-        var ctBuf = crypto.encryptPacked(ptBuf, sessionKey);
+        var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey);
         var encrypted = { _ct: ctBuf.toString("base64") };
         if (sessionCtx) {
           encrypted._sid = sessionCtx.sid;
@@ -480,7 +480,7 @@ function create(opts) {
   function _decryptEkToSessionKey(ek) {
     for (var ki = 0; ki < keypairs.length; ki++) {
       try {
-        var sessionKeyB64 = crypto.decrypt(ek, keypairs[ki]);
+        var sessionKeyB64 = bCrypto.decrypt(ek, keypairs[ki]);
         var candidate = Buffer.from(sessionKeyB64, "base64");
         if (candidate.length === SESSION_KEY_BYTES) return candidate;
       } catch (_e) { /* try next keypair */ }
@@ -518,7 +518,7 @@ function create(opts) {
 
     if (typeof ek === "string" && typeof nonce === "string") {
       // ---- Bootstrap path (per-request mode OR first request of session) ----
-      var nonceHash = crypto.sha3Hash(nonce, "hex");
+      var nonceHash = bCrypto.sha3Hash(nonce, "hex");
       var expireAt = now + replayWindowMs;
       var freshNonce;
       try { freshNonce = await nonceStore.checkAndInsert(nonceHash, expireAt); }
@@ -655,7 +655,7 @@ function create(opts) {
     var clearObj;
     try {
       var ctBuf = Buffer.from(ct, "base64");
-      var ptBuf = crypto.decryptPacked(ctBuf, sessionKey);
+      var ptBuf = bCrypto.decryptPacked(ctBuf, sessionKey);
       clearObj = safeJson.parse(ptBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
     } catch (_e) {
       _emitFailure(req, "tag");
@@ -751,7 +751,7 @@ function client(opts) {
   var perSessionLastResCtr = 0;
 
   function _resetSession() {
-    perSessionKey = crypto.generateBytes(SESSION_KEY_BYTES);
+    perSessionKey = bCrypto.generateBytes(SESSION_KEY_BYTES);
     perSessionSid = _generateUuidV4();
     perSessionReqCtr = 0;
     perSessionLastResCtr = 0;
@@ -774,7 +774,7 @@ function client(opts) {
     }
     perSessionLastResCtr = responseBody._ctr;
     var resCtBuf = Buffer.from(responseBody._ct, "base64");
-    var resPtBuf = crypto.decryptPacked(resCtBuf, perSessionKey);
+    var resPtBuf = bCrypto.decryptPacked(resCtBuf, perSessionKey);
     return safeJson.parse(resPtBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
   }
 
@@ -783,13 +783,13 @@ function client(opts) {
     if (!perSessionKey) _resetSession();
     var ts = Date.now();
     var ptBuf = Buffer.from(JSON.stringify(payload), "utf8");
-    var ctBuf = crypto.encryptPacked(ptBuf, perSessionKey);
+    var ctBuf = bCrypto.encryptPacked(ptBuf, perSessionKey);
     perSessionReqCtr += 1;
     var body;
     if (perSessionReqCtr === 1) {
       // Bootstrap envelope — full _ek + _nonce; server stores sid → sessionKey.
-      var ek = crypto.encrypt(perSessionKey.toString("base64"), pubkey);
-      var nonce = crypto.generateBytes(REQUEST_NONCE_BYTES).toString("hex");
+      var ek = bCrypto.encrypt(perSessionKey.toString("base64"), pubkey);
+      var nonce = bCrypto.generateBytes(REQUEST_NONCE_BYTES).toString("hex");
       body = {
         _ek:    ek,
         _ct:    ctBuf.toString("base64"),
@@ -812,11 +812,11 @@ function client(opts) {
 
   function _encryptPerRequest(payload) {
     if (payload === undefined) payload = null;
-    var sessionKey = crypto.generateBytes(SESSION_KEY_BYTES);
-    var ek = crypto.encrypt(sessionKey.toString("base64"), pubkey);
+    var sessionKey = bCrypto.generateBytes(SESSION_KEY_BYTES);
+    var ek = bCrypto.encrypt(sessionKey.toString("base64"), pubkey);
     var ptBuf = Buffer.from(JSON.stringify(payload), "utf8");
-    var ctBuf = crypto.encryptPacked(ptBuf, sessionKey);
-    var requestNonce = crypto.generateBytes(REQUEST_NONCE_BYTES).toString("hex");
+    var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey);
+    var requestNonce = bCrypto.generateBytes(REQUEST_NONCE_BYTES).toString("hex");
     var ts = Date.now();
     return {
       body: {
@@ -832,7 +832,7 @@ function client(opts) {
             "apiEncrypt.client: response missing _ct field");
         }
         var resCtBuf = Buffer.from(responseBody._ct, "base64");
-        var resPtBuf = crypto.decryptPacked(resCtBuf, sessionKey);
+        var resPtBuf = bCrypto.decryptPacked(resCtBuf, sessionKey);
         return safeJson.parse(resPtBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
       },
     };
@@ -857,7 +857,7 @@ function client(opts) {
 // Slice offsets are RFC 4122 UUID hex-byte boundaries (`xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx`)
 // — protocol-fixed values, not byte sizes. allow:raw-byte-literal
 function _generateUuidV4() {
-  var b = crypto.generateBytes(16);                     // allow:raw-byte-literal — UUID is exactly 16 bytes
+  var b = bCrypto.generateBytes(16);                     // allow:raw-byte-literal — UUID is exactly 16 bytes
   // Set version (4) and variant (10x) bits per RFC 4122.
   b[6] = (b[6] & 0x0f) | 0x40;
   b[8] = (b[8] & 0x3f) | 0x80;

package/lib/middleware/body-parser.js

@@ -100,7 +100,7 @@
  *     dots collapsed, control characters stripped, length capped at 255.
  *     Tmp file path is generated by the framework, never derived from
  *     the operator-supplied filename — so a malicious filename can't
- *     collide with a sensitive path.
+ *     collide with a sensitive nodePath.
  *   - Multipart parser refuses fields whose `name` is in POISONED_KEYS
  *     (consistent with the JSON path).
  *   - Tmp files set with mode 0o600, parent dir created with 0o700.
@@ -108,12 +108,12 @@
  *     error) so a crashing handler doesn't leak files.
  */
 
-var fs = require("fs");
+var nodeFs = require("fs");
 var os = require("os");
-var path = require("path");
+var nodePath = require("path");
 var nodeCrypto = require("node:crypto");
 var atomicFile      = require("../atomic-file");
-var crypto          = require("../crypto");
+var bCrypto         = require("../crypto");
 var lazyRequire     = require("../lazy-require");
 var requestHelpers  = require("../request-helpers");
 var safeBuffer      = require("../safe-buffer");
@@ -682,7 +682,7 @@ async function _parseMultipart(req, opts, ctParams) {
   }
   // Resolve tmpDir per-request so directory-creation failure surfaces as a
   // structured error rather than a deferred fs throw.
-  var tmpDir = opts.tmpDir || path.join(os.tmpdir(), "blamejs-uploads");
+  var tmpDir = opts.tmpDir || nodePath.join(os.tmpdir(), "blamejs-uploads");
   try { atomicFile.ensureDir(tmpDir, 0o700); }
   catch (e) {
     throw new BodyParserError(
@@ -733,7 +733,7 @@ async function _parseMultipart(req, opts, ctParams) {
     currentFilename = null;
     currentMime = null;
     currentTmpPath = null;
-    if (currentFd !== null) { try { fs.closeSync(currentFd); } catch (_e) { /* fd already closed */ } currentFd = null; }
+    if (currentFd !== null) { try { nodeFs.closeSync(currentFd); } catch (_e) { /* fd already closed */ } currentFd = null; }
     currentSize = 0;
     currentHash = null;
     currentBuf = null;
@@ -762,10 +762,10 @@ async function _parseMultipart(req, opts, ctParams) {
   }
 
   function _cleanup() {
-    if (currentFd !== null) { try { fs.closeSync(currentFd); } catch (_e) { /* fd already closed */ } currentFd = null; }
-    if (currentTmpPath) { try { fs.unlinkSync(currentTmpPath); } catch (_e) { /* tmp file already removed */ } }
+    if (currentFd !== null) { try { nodeFs.closeSync(currentFd); } catch (_e) { /* fd already closed */ } currentFd = null; }
+    if (currentTmpPath) { try { nodeFs.unlinkSync(currentTmpPath); } catch (_e) { /* tmp file already removed */ } }
     for (var i = 0; i < files.length; i++) {
-      try { fs.unlinkSync(files[i].path); } catch (_e) { /* tmp file already removed */ }
+      try { nodeFs.unlinkSync(files[i].path); } catch (_e) { /* tmp file already removed */ }
     }
   }
 
@@ -945,10 +945,10 @@ async function _parseMultipart(req, opts, ctParams) {
 
               // Generate the tmp path — never derived from the
               // operator-supplied filename.
-              var unique = crypto.generateToken(C.BYTES.bytes(16));
-              currentTmpPath = path.join(tmpDir, "blamejs-up-" + unique);
+              var unique = bCrypto.generateToken(C.BYTES.bytes(16));
+              currentTmpPath = nodePath.join(tmpDir, "blamejs-up-" + unique);
               try {
-                currentFd = fs.openSync(currentTmpPath, "wx", 0o600);
+                currentFd = nodeFs.openSync(currentTmpPath, "wx", 0o600);
               } catch (e) {
                 done(new BodyParserError("body-parser/multipart-tmp-open",
                   "could not open multipart tmp file: " + ((e && e.message) || String(e)),
@@ -1027,7 +1027,7 @@ async function _parseMultipart(req, opts, ctParams) {
                 try {
                   var written = 0;
                   while (written < bodyChunk.length) {
-                    written += fs.writeSync(currentFd, bodyChunk, written, bodyChunk.length - written);
+                    written += nodeFs.writeSync(currentFd, bodyChunk, written, bodyChunk.length - written);
                   }
                 } catch (e) {
                   done(new BodyParserError("body-parser/multipart-tmp-write",
@@ -1068,7 +1068,7 @@ async function _parseMultipart(req, opts, ctParams) {
               // fileFilter rejected — already recorded in filesRejected; no
               // tmp file was opened, nothing to clean up here.
             } else if (currentFd !== null) {
-              try { fs.closeSync(currentFd); } catch (_e) { /* fd already closed */ }
+              try { nodeFs.closeSync(currentFd); } catch (_e) { /* fd already closed */ }
               currentFd = null;
               files.push({
                 field:    currentField,
@@ -1247,7 +1247,7 @@ function create(opts) {
           if (cleanedUp) return;
           cleanedUp = true;
           for (var i = 0; i < mpResult.files.length; i++) {
-            try { fs.unlinkSync(mpResult.files[i].path); } catch (_e) { /* tmp file already removed */ }
+            try { nodeFs.unlinkSync(mpResult.files[i].path); } catch (_e) { /* tmp file already removed */ }
           }
         }
         res.on("finish", cleanup);
@@ -1500,7 +1500,7 @@ module.exports = {
   BodyParserError:  BodyParserError,
   // Standalone async helpers — surfaced via b.parsers.{json,multipart}.
   // The middleware composes these so the request-handling pipeline and
-  // the operator-callable surface share one parsing path.
+  // the operator-callable surface share one parsing nodePath.
   parseJson:        parseJsonStandalone,
   parseMultipart:   parseMultipartStandalone,
   // Internal helpers exposed for tests + the csrf-protect refactor.

package/lib/middleware/compression.js

@@ -90,7 +90,7 @@
 
 var zlib = require("node:zlib");
 var C = require("../constants");
-var nb = require("../numeric-bounds");
+var numericBounds = require("../numeric-bounds");
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
@@ -271,12 +271,12 @@ function create(opts) {
   var threshold;
   if (opts.threshold === undefined) {
     threshold = DEFAULT_OPTS.threshold;
-  } else if (nb.isNonNegativeFiniteInt(opts.threshold)) {
+  } else if (numericBounds.isNonNegativeFiniteInt(opts.threshold)) {
     threshold = opts.threshold;
   } else {
     throw new CompressionError("compression/bad-opt",
       "middleware.compression: threshold must be a non-negative finite integer; got " +
-        nb.shape(opts.threshold));
+        numericBounds.shape(opts.threshold));
   }
   var encodings     = Array.isArray(opts.encodings) && opts.encodings.length > 0
                         ? opts.encodings.slice() : DEFAULT_OPTS.encodings.slice();

package/lib/middleware/csp-nonce.js

@@ -113,7 +113,7 @@
  */
 
 var C = require("../constants");
-var crypto = require("../crypto");
+var bCrypto = require("../crypto");
 var numericBounds = require("../numeric-bounds");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
@@ -283,7 +283,7 @@ function create(opts) {
   // Pre-fix the typeof-only check accepted Infinity / NaN — both
   // bypassed the `< MIN_NONCE_BYTES` guard (NaN < N is always false,
   // Infinity < N is always false), then crashed per-request when
-  // `crypto.generateBytes(Infinity)` hit ERR_OUT_OF_RANGE. Route through
+  // `bCrypto.generateBytes(Infinity)` hit ERR_OUT_OF_RANGE. Route through
   // shared numeric-bounds (positive finite int) before the lower-bound
   // check so the typo / coercion is caught at create() time.
   if (!numericBounds.isPositiveFiniteInt(nonceBytes)) {
@@ -322,7 +322,7 @@ function create(opts) {
   if (opts.placeholder === undefined) {
     // OS-RNG → SHAKE256 → hex via the framework random helper.
     placeholder = PLACEHOLDER_PREFIX +
-                  crypto.generateToken(PLACEHOLDER_RAND_BYTES) +
+                  bCrypto.generateToken(PLACEHOLDER_RAND_BYTES) +
                   PLACEHOLDER_SUFFIX;
   } else if (typeof opts.placeholder !== "string" || opts.placeholder.length === 0) {
     throw new CspNonceError("csp-nonce/bad-placeholder",
@@ -336,7 +336,7 @@ function create(opts) {
     // Generate the nonce. Cheap (16 bytes from getrandom → SHAKE256 →
     // base64 encode); do it always for consistency unless `always:
     // false` was set explicitly.
-    var nonce = crypto.generateBytes(nonceBytes).toString("base64");
+    var nonce = bCrypto.generateBytes(nonceBytes).toString("base64");
 
     // Attach to req for handler access.
     req[property] = nonce;

package/lib/middleware/health.js

@@ -100,7 +100,7 @@
  */
 
 var C = require("../constants");
-var nb = require("../numeric-bounds");
+var numericBounds = require("../numeric-bounds");
 var requestHelpers = require("../request-helpers");
 var safeAsync = require("../safe-async");
 var validateOpts = require("../validate-opts");
@@ -179,22 +179,22 @@ function create(opts) {
   var defaultTimeoutMs;
   if (opts.defaultTimeoutMs === undefined) {
     defaultTimeoutMs = DEFAULT_TIMEOUT_MS;
-  } else if (nb.isPositiveFiniteInt(opts.defaultTimeoutMs)) {
+  } else if (numericBounds.isPositiveFiniteInt(opts.defaultTimeoutMs)) {
     defaultTimeoutMs = opts.defaultTimeoutMs;
   } else {
     throw new HealthError("health/bad-opt",
       "defaultTimeoutMs must be a positive finite integer; got " +
-        nb.shape(opts.defaultTimeoutMs));
+        numericBounds.shape(opts.defaultTimeoutMs));
   }
   var cacheMs;
   if (opts.cacheMs === undefined) {
     cacheMs = 0;
-  } else if (nb.isNonNegativeFiniteInt(opts.cacheMs)) {
+  } else if (numericBounds.isNonNegativeFiniteInt(opts.cacheMs)) {
     cacheMs = opts.cacheMs;
   } else {
     throw new HealthError("health/bad-opt",
       "cacheMs must be a non-negative finite integer; got " +
-        nb.shape(opts.cacheMs));
+        numericBounds.shape(opts.cacheMs));
   }
   var includeMeta = opts.includeMeta !== false;
   var version = opts.version || null;
@@ -237,12 +237,12 @@ function create(opts) {
     var timeoutMs;
     if (copts.timeoutMs === undefined) {
       timeoutMs = defaultTimeoutMs;
-    } else if (nb.isPositiveFiniteInt(copts.timeoutMs)) {
+    } else if (numericBounds.isPositiveFiniteInt(copts.timeoutMs)) {
       timeoutMs = copts.timeoutMs;
     } else {
       throw new HealthError("health/bad-opt",
         "registerCheck: timeoutMs must be a positive finite integer; got " +
-          nb.shape(copts.timeoutMs));
+          numericBounds.shape(copts.timeoutMs));
     }
     checks.push({
       name:      name,

package/lib/middleware/idempotency-key.js

@@ -46,6 +46,9 @@ var numericBounds = require("../numeric-bounds");
 var safeBuffer    = require("../safe-buffer");
 var safeJson      = require("../safe-json");
 var safeSql       = require("../safe-sql");
+var bCrypto       = require("../crypto");
+var cryptoField   = require("../crypto-field");
+var vault         = require("../vault");
 var { defineClass } = require("../framework-error");
 
 var audit          = lazyRequire(function () { return require("../audit"); });
@@ -136,7 +139,7 @@ function memoryStore(opts) {
  * @signature b.middleware.idempotencyKey.dbStore(opts)
  * @since     0.9.14
  * @status    stable
- * @related   b.middleware.idempotencyKey, b.middleware.idempotencyKey.memoryStore, b.db
+ * @related   b.middleware.idempotencyKey, b.middleware.idempotencyKey.memoryStore, b.db, b.cryptoField
  *
  * Persistent-backed store for `idempotencyKey` middleware. Implements
  * the same three-method interface as `memoryStore` (`get` / `set` /
@@ -148,30 +151,62 @@ function memoryStore(opts) {
  *
  *   - multiple processes share the request-handling fleet (forks
  *     behind a load balancer, multi-instance K8s deployment) and a
- *     retry can land on a different process than the original
- *     request — only a shared store satisfies the §2 replay
- *     semantics across the fleet;
+ *     retry can land on a different process than the original;
  *   - the daemon may restart between the original request and the
  *     retry (graceful rolling deploy, OOM kill, planned reboot) —
  *     `memoryStore` is volatile, `dbStore` survives the restart;
  *   - audit / compliance review needs to walk historic
- *     idempotency cache decisions — `dbStore` is queryable with
- *     `SELECT * FROM <tableName>`, `memoryStore` is opaque.
+ *     idempotency cache decisions queryable with
+ *     `SELECT k, status_code, expires_at FROM <tableName>` —
+ *     non-sealed columns are forensic-queryable without unsealing.
+ *
+ * **Defense-in-depth defaults (since 0.9.15) — both can be opted out:**
+ *
+ *   - `hashKeys: true` — operator-supplied keys are sha3-512
+ *     namespace-hashed via `b.crypto.namespaceHash("idempotency-key",
+ *     key)` before insert/lookup. The `k` column carries the hash, not
+ *     the raw key. Operator keys often carry PII (order numbers,
+ *     emails, vendor prefixes); the DB never sees them.
+ *   - `seal: true` — `headers` and `body` columns are sealed via
+ *     `b.cryptoField.sealRow` (vault-managed key, AEAD envelope) so a
+ *     DB dump leaks neither cached response bodies nor headers.
+ *     Requires `b.vault.init(...)` to have run; falls back to plain-
+ *     text with a one-shot audit warning when vault isn't ready, so
+ *     test-fixture / boot-script callers still work.
  *
  * Lazily-expired: `get(key)` returns `null` for any row whose
- * `expires_at` has passed (the row is deleted on the same call).
- * `set(key, value, ttlMs)` upserts on conflict so a concurrent retry
- * landing on a different process doesn't error out. `delete(key)` is
- * idempotent (no-op when absent).
+ * `expires_at` has passed. The cleanup is scoped by the observed
+ * `expires_at` so a concurrent upsert from a sibling process isn't
+ * clobbered.
+ *
+ * **Schema (v0.9.15, split columns):**
+ *
+ * ```
+ *   k             TEXT PRIMARY KEY   -- hashed key when hashKeys=true
+ *   fingerprint   TEXT NOT NULL      -- request method+path+body digest
+ *   status_code   INTEGER NOT NULL   -- forensic-queryable
+ *   headers       TEXT NOT NULL      -- JSON, sealed when seal=true
+ *   body          TEXT NOT NULL      -- base64, sealed when seal=true
+ *   expires_at    INTEGER NOT NULL
+ * ```
+ *
+ * **Migration note**: v0.9.14 used a single `v` JSON envelope column.
+ * Operators with a v0.9.14 table must `DROP TABLE <tableName>;` (or
+ * pick a fresh `tableName`) before upgrading — `CREATE TABLE IF NOT
+ * EXISTS` won't migrate column layout. Pre-v1 the framework breaks
+ * across patch versions for security correctness.
  *
  * @opts
  *   db:         object,   // required — sqlite-shaped: { prepare(sql) → { run, get, all } }
  *   tableName?: string,   // default "blamejs_idempotency_keys"; validated via b.safeSql.validateIdentifier
  *   init?:      boolean,  // default true — run CREATE TABLE IF NOT EXISTS at construction
+ *   hashKeys?:  boolean,  // default true — store sha3-512 namespace-hash of the key, not the raw key
+ *   seal?:      boolean,  // default true — seal headers + body via b.cryptoField when vault is ready
  *
  * @example
- *   // single-process daemon, framework's internal sqlite:
+ *   // single-process daemon, framework's internal sqlite, both defaults on:
  *   var b = require("blamejs");
+ *   await b.vault.init({ dataDir: "/var/lib/myapp" });
  *   await b.db.init({ dataDir: "/var/lib/myapp", schema: [] });
  *   var store = b.middleware.idempotencyKey.dbStore({ db: b.db });
  *   var mw = b.middleware.idempotencyKey({
@@ -179,16 +214,6 @@ function memoryStore(opts) {
  *     ttlMs: b.constants.TIME.hours(24),
  *   });
  *   app.use(mw);
- *
- * @example
- *   // multi-process fleet, shared better-sqlite3 instance over WAL:
- *   var Database = require("better-sqlite3");
- *   var db = new Database("/var/lib/myapp/idempotency.db", { fileMustExist: false });
- *   db.pragma("journal_mode = WAL");
- *   var store = b.middleware.idempotencyKey.dbStore({
- *     db:        db,
- *     tableName: "request_idempotency",
- *   });
  */
 function dbStore(opts) {
   opts = opts || {};
@@ -197,12 +222,9 @@ function dbStore(opts) {
       "dbStore: opts.db must be a sqlite-shaped database with a `prepare(sql)` method", true);
   }
   var tableNameRaw = opts.tableName !== undefined ? opts.tableName : "blamejs_idempotency_keys";
-  // Quote-and-validate in one step. safeSql.quoteIdentifier runs
-  // validateIdentifier internally (rejects bad shape / reserved
-  // words / sqlite_-prefixed names) and emits the dialect-correct
-  // double-quoted form. Identifier ALWAYS reaches SQL through the
-  // quoted form — defense-in-depth so a future shape-regex bypass
-  // can't reach raw concatenation. Per PR #44 review.
+  // Quote-and-validate via safeSql.quoteIdentifier — runs
+  // validateIdentifier internally + emits the dialect-correct quoted
+  // form. Identifier always reaches SQL through the quoted form.
   var qTable;
   try { qTable = safeSql.quoteIdentifier(tableNameRaw, "sqlite"); }
   catch (sqlErr) {
@@ -211,65 +233,143 @@ function dbStore(opts) {
       (sqlErr && sqlErr.message ? sqlErr.message : String(sqlErr)), true);
   }
   var qIndex = safeSql.quoteIdentifier(tableNameRaw + "_expires_idx", "sqlite");
-  var doInit = opts.init !== false;
+  var doInit   = opts.init     !== false;
+  var hashKeys = opts.hashKeys !== false;
+  var sealReq  = opts.seal     !== false;
   var db = opts.db;
 
+  // Probe vault readiness with a sentinel seal. If vault.init() hasn't
+  // run (test fixture / boot-script / operator simply hasn't wired the
+  // posture yet) sealing falls back to plaintext for the lifetime of
+  // this dbStore instance and a single audit warning emits so the
+  // posture gap is visible in the chain.
+  var sealEnabled = false;
+  if (sealReq) {
+    try {
+      vault.seal("__idempotency_seal_probe__");
+      sealEnabled = true;
+    } catch (_vaultErr) {
+      _emitAudit("idempotency.seal_skipped_no_vault",
+        { tableName: tableNameRaw,
+          reason: "vault.init() has not run; sealing falls back to plaintext" },
+        "warning");
+    }
+  }
+
+  // Register the table with cryptoField. registerTable is idempotent
+  // — subsequent dbStore() calls with the same tableName re-declare
+  // the same sealedFields and no-op.
+  if (sealEnabled) {
+    cryptoField.registerTable(tableNameRaw, {
+      sealedFields: ["headers", "body"],
+    });
+  }
+
   if (doInit) {
     db.prepare("CREATE TABLE IF NOT EXISTS " + qTable + " (" +
       "k TEXT PRIMARY KEY, " +
-      "v TEXT NOT NULL, " +
+      "fingerprint TEXT NOT NULL, " +
+      "status_code INTEGER NOT NULL, " +
+      "headers TEXT NOT NULL, " +
+      "body TEXT NOT NULL, " +
       "expires_at INTEGER NOT NULL)").run();
     db.prepare("CREATE INDEX IF NOT EXISTS " + qIndex + " ON " +
       qTable + "(expires_at)").run();
   }
 
-  // Prepare once; reused on every store call. Statements cache to the
-  // framework's bounded prepare-cache automatically when db = b.db.
-  var stmtGet         = db.prepare("SELECT v, expires_at FROM " + qTable + " WHERE k = ?");
-  var stmtUpsert      = db.prepare("INSERT INTO " + qTable + "(k, v, expires_at) VALUES (?, ?, ?) " +
-    "ON CONFLICT(k) DO UPDATE SET v = excluded.v, expires_at = excluded.expires_at");
-  var stmtDelete      = db.prepare("DELETE FROM " + qTable + " WHERE k = ?");
-  // Conditional delete — only removes the row when expires_at still
-  // matches the version we observed. In a multi-process deployment
-  // another process can upsert the same key between our SELECT and
-  // DELETE; an unconditional `DELETE WHERE k = ?` would erase the
-  // FRESH replacement and turn a valid cached response into a miss
-  // (idempotency replay broken under concurrent retries). Per Codex
-  // P1 on PR #44.
+  // Prepared statements. status_code + expires_at stay non-sealed
+  // so audit/forensic SELECTs don't have to unseal-everything.
+  var stmtGet = db.prepare(
+    "SELECT fingerprint, status_code, headers, body, expires_at FROM " +
+    qTable + " WHERE k = ?");
+  var stmtUpsert = db.prepare(
+    "INSERT INTO " + qTable +
+    "(k, fingerprint, status_code, headers, body, expires_at) " +
+    "VALUES (?, ?, ?, ?, ?, ?) " +
+    "ON CONFLICT(k) DO UPDATE SET " +
+    "  fingerprint = excluded.fingerprint, " +
+    "  status_code = excluded.status_code, " +
+    "  headers     = excluded.headers, " +
+    "  body        = excluded.body, " +
+    "  expires_at  = excluded.expires_at");
   var stmtDeleteStale = db.prepare("DELETE FROM " + qTable +
     " WHERE k = ? AND expires_at <= ?");
+  var stmtDelete = db.prepare("DELETE FROM " + qTable + " WHERE k = ?");
+
+  function _k(rawKey) {
+    if (!hashKeys) return rawKey;
+    return bCrypto.namespaceHash("idempotency-key", rawKey);
+  }
 
   return {
-    get: function (key) {
-      var row = stmtGet.get(key);
+    get: function (rawKey) {
+      var row = stmtGet.get(_k(rawKey));
       if (!row) return null;
       if (row.expires_at < Date.now()) {
-        // Scoped delete by the observed expires_at so a concurrent
-        // upsert that wrote a fresher row isn't clobbered.
-        stmtDeleteStale.run(key, row.expires_at);
+        stmtDeleteStale.run(_k(rawKey), row.expires_at);
         return null;
       }
-      // safeJson.parse with bounded maxBytes — even though row.v is
-      // written by our own .set() below, a multi-process deployment
-      // shares the table across processes; a misbehaving sibling
-      // could write a huge value that OOMs the reader. The default
-      // maxBodyBytes (1 MiB) bounds what the middleware captures, so
-      // a 4 MiB ceiling here gives headroom for JSON-envelope overhead.
-      try { return safeJson.parse(row.v, { maxBytes: 4 * 1024 * 1024 }); }                           // allow:raw-byte-literal — 4 MiB row-value ceiling
-      catch (_e) {
-        // Corrupt row — scope the delete by the observed expires_at so
-        // a concurrent upsert of valid bytes survives.
-        stmtDeleteStale.run(key, row.expires_at);
+      var liveRow = row;
+      if (sealEnabled) {
+        try { liveRow = cryptoField.unsealRow(tableNameRaw, row); }
+        catch (_unsealErr) {
+          // Decryption failed (key rotation gap / corrupt envelope).
+          // Treat as miss + drop the row so the handler runs fresh
+          // and we capture a re-sealable replacement.
+          stmtDeleteStale.run(_k(rawKey), row.expires_at);
+          return null;
+        }
+      }
+      var headersObj;
+      try {
+        headersObj = safeJson.parse(liveRow.headers, { maxBytes: 4 * 1024 * 1024 });               // allow:raw-byte-literal — 4 MiB headers ceiling
+      } catch (_jsonErr) {
+        // Parse failure has two distinct causes:
+        //   1. Genuine corruption (truncated row, encoding mishap) — drop.
+        //   2. The row was sealed by a sibling process (vault: prefix
+        //      present) but THIS process has sealEnabled=false (vault
+        //      not initialized OR opts.seal=false). The row is valid
+        //      cross-process state we just can't read locally;
+        //      DELETING it would clobber another process's cache and
+        //      turn a hit into a miss with potential side-effect re-
+        //      execution. Treat as miss + LEAVE the row in place.
+        //      Per Codex P1 on PR #45.
+        var lookedSealed = typeof liveRow.headers === "string" &&
+          liveRow.headers.indexOf("vault:") === 0;
+        if (!lookedSealed) {
+          stmtDeleteStale.run(_k(rawKey), row.expires_at);
+        }
         return null;
       }
+      return {
+        fingerprint: liveRow.fingerprint,
+        statusCode:  liveRow.status_code,
+        headers:     headersObj,
+        body:        liveRow.body,
+      };
     },
-    set: function (key, value, ttlMs) {
-      stmtUpsert.run(key, JSON.stringify(value), Date.now() + ttlMs);
+    set: function (rawKey, value, ttlMs) {
+      var rowOut = {
+        k:           _k(rawKey),
+        fingerprint: value.fingerprint,
+        status_code: value.statusCode,
+        headers:     JSON.stringify(value.headers || {}),
+        body:        value.body || "",
+        expires_at:  Date.now() + ttlMs,
+      };
+      if (sealEnabled) {
+        rowOut = cryptoField.sealRow(tableNameRaw, rowOut);
+      }
+      stmtUpsert.run(
+        rowOut.k, rowOut.fingerprint, rowOut.status_code,
+        rowOut.headers, rowOut.body, rowOut.expires_at);
     },
-    delete: function (key) {
-      stmtDelete.run(key);
+    delete: function (rawKey) {
+      stmtDelete.run(_k(rawKey));
     },
-    _tableName: tableNameRaw,
+    _tableName:   tableNameRaw,
+    _hashKeys:    hashKeys,
+    _sealEnabled: sealEnabled,
   };
 }