@blamejs/core 0.9.46 → 0.10.1

package/lib/middleware/dpop.js

@@ -75,6 +75,7 @@ function _nonceManager(rotateSec) {
   var rotateMs = C.TIME.seconds(rotateSec);
   var current = null;
   var previous = null;
+  var shutdown = false;
   function _fresh() {
     return {
       nonce:    bCrypto.generateBytes(DPOP_NONCE_BYTES).toString("base64url"),
@@ -93,11 +94,43 @@ function _nonceManager(rotateSec) {
     }
   }
   return {
-    issue: function () { _maybeRotate(); return current.nonce; },
+    issue: function () {
+      if (shutdown) return null;
+      _maybeRotate();
+      return current.nonce;
+    },
     accepts: function (n) {
+      if (shutdown) return false;
       _maybeRotate();
       if (typeof n !== "string" || n.length === 0) return false;
-      return (current && n === current.nonce) || (previous && n === previous.nonce);
+      // Constant-time compare so server-issued nonce probing can't
+      // narrow the rolling-pair bytes via response-timing — matches
+      // the timingSafeEqual discipline on the DPoP-proof nonce.
+      if (current && bCrypto.timingSafeEqual(n, current.nonce)) return true;
+      if (previous && bCrypto.timingSafeEqual(n, previous.nonce)) return true;
+      return false;
+    },
+    // AUTH-36 — hot-reload coexistence. Operators redeploying without
+    // a clean process restart need a way to drain in-flight clients
+    // before swapping the middleware instance. shutdown() returns no
+    // fresh nonces and refuses every presented nonce, so the
+    // surrounding middleware emits 401 + use_dpop_nonce on the old
+    // instance and the new instance owns the trust anchor cleanly.
+    shutdown: function () { shutdown = true; current = null; previous = null; },
+    // revoke() — rotate both rolling-pair slots, invalidating every
+    // outstanding nonce immediately. Useful after a suspected nonce
+    // leak. Distinct from shutdown(): the manager keeps serving fresh
+    // nonces afterwards.
+    revoke: function () {
+      previous = null;
+      current  = _fresh();
+    },
+    _state: function () {
+      return {
+        shutdown: shutdown,
+        current:  current ? current.nonce : null,
+        previous: previous ? previous.nonce : null,
+      };
     },
   };
 }
@@ -229,7 +262,7 @@ function create(opts) {
 
   function _freshNonce() { return nonceMgr ? nonceMgr.issue() : null; }
 
-  return async function dpopMiddleware(req, res, next) {
+  var middleware = async function dpopMiddleware(req, res, next) {
     var proofHeader = req.headers && req.headers.dpop;
     if (typeof proofHeader !== "string" || proofHeader.length === 0) {
       return _writeUnauthorized(res,
@@ -241,6 +274,18 @@ function create(opts) {
       return _writeUnauthorized(res, "invalid_dpop_proof",
         "multiple DPoP headers are not allowed");
     }
+    // AUTH-15 — RFC 9449 §4.1 single-value invariant. node:http
+    // collapses repeated headers into a comma-joined string when the
+    // client ships `DPoP: proof1, DPoP: proof2`; the Array.isArray
+    // check above catches the multi-value array shape but a
+    // comma-joined string slips past. Refuse explicitly so a buggy /
+    // hostile client can't smuggle two proofs past the verifier (the
+    // verify() call below would only see the first one, leaving the
+    // second unprocessed).
+    if (proofHeader.indexOf(",") !== -1) {
+      return _writeUnauthorized(res, "invalid_dpop_proof",
+        "multiple DPoP proofs in one header value are not allowed");
+    }
 
     var htu = (typeof opts.getHtu === "function" ? opts.getHtu(req) : _reconstructHtu(req, opts));
     if (!htu) {
@@ -340,6 +385,16 @@ function create(opts) {
     }
     return next();
   };
+
+  // AUTH-36 — surface the nonce manager's lifecycle hooks on the
+  // returned middleware so hot-reload deploys can drain in-flight
+  // clients before swapping instances. shutdown() refuses every
+  // subsequent proof + issues no fresh nonces; revoke() rotates the
+  // rolling pair without disabling the manager (useful after a
+  // suspected nonce leak). Both are no-ops when requireNonce is off.
+  middleware.shutdown = function () { if (nonceMgr) nonceMgr.shutdown(); };
+  middleware.revoke   = function () { if (nonceMgr) nonceMgr.revoke();   };
+  return middleware;
 }
 
 module.exports = {

package/lib/middleware/idempotency-key.js

@@ -161,19 +161,44 @@ function memoryStore(opts) {
  *     `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:**
+ * **Defense-in-depth defaults — every option below ships on by default:**
  *
- *   - `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.
+ *   - `hashKeys: true` (since 0.9.15) — 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` (since 0.9.15) — `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.
+ *   - `aad: true` (since 0.9.58 — CRYPTO-1) — sealed columns are bound
+ *     via Additional Authenticated Data to (table, k, column,
+ *     schemaVersion) so a DB-write attacker can't copy a sealed
+ *     header/body cell from one row to another (which previously
+ *     decrypted cleanly under plain `vault.seal`). Existing v0.9.15-
+ *     v0.9.57 dbStore tables continue to read because unsealRow auto-
+ *     detects the envelope shape; lazy re-seal on next `set()` upgrades
+ *     each row to AAD form. Operators wanting a one-shot migration
+ *     call `b.middleware.idempotencyKey.resealMigrate(store)`.
+ *   - `fingerprintSeal: true` (since 0.9.58 — CRYPTO-4) — the request
+ *     `fingerprint` column carries an HMAC under a vault-derived
+ *     secret instead of a bare SHA3-256 of method+path+body. The
+ *     compare path is constant-time so the column doubles as a
+ *     mismatch oracle without offline-brute-force exposure.
+ *   - `bodyFingerprintFallback: "deny"` (since 0.9.58 — SUBSTRATE-13) —
+ *     when neither `bodyFingerprint` nor `req._rawBody`/`req.body` is
+ *     populated for a body-bearing method, the middleware previously
+ *     silently degraded the fingerprint to method+path. Set to
+ *     `"deny"` (the new default) and the middleware refuses the
+ *     request with HTTP 400 `idempotency/missing-body-fingerprint`
+ *     instead. Operators with a documented "no body" use case set
+ *     `bodyFingerprintFallback: "method-path-only"` to restore the
+ *     pre-0.9.58 behavior — the audit chain still emits
+ *     `idempotency.empty_body_fingerprint` so the misorder is visible.
  *
  * Lazily-expired: `get(key)` returns `null` for any row whose
  * `expires_at` has passed. The cleanup is scoped by the observed
@@ -203,6 +228,8 @@ function memoryStore(opts) {
  *   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
+ *   aad?:       boolean,  // default true — AAD-bind seal to (table,k,column) so a DB-write attacker can't cross-row swap (CRYPTO-1)
+ *   fingerprintSeal?: boolean, // default true — HMAC fingerprint under a vault-derived secret instead of bare sha3-256 (CRYPTO-4)
  *
  * @example
  *   // single-process daemon, framework's internal sqlite, both defaults on:
@@ -237,6 +264,15 @@ function dbStore(opts) {
   var doInit   = opts.init     !== false;
   var hashKeys = opts.hashKeys !== false;
   var sealReq  = opts.seal     !== false;
+  // CRYPTO-1 — AAD-bind sealing to (table, k, column) by default.
+  // Forms a defense-in-depth pair with seal: cross-row swap fails
+  // Poly1305 even when the attacker controls the DB layer.
+  var aadOn    = opts.aad      !== false;
+  // CRYPTO-4 — HMAC the fingerprint under a vault-derived secret by
+  // default. Bare SHA3-256 of method+path+body is offline-brute-
+  // forceable for any DB-dump attacker; HMAC under a vault secret
+  // forces them to break the vault first.
+  var fpSealOn = opts.fingerprintSeal !== false;
   var db = opts.db;
 
   // Probe vault readiness with a sentinel seal. If vault.init() hasn't
@@ -247,6 +283,8 @@ function dbStore(opts) {
   var sealEnabled = false;
   if (sealReq) {
     try {
+      // allow:seal-without-aad — vault-readiness probe; throwaway
+      // sentinel value, not row-bound data
       vault.seal("__idempotency_seal_probe__");
       sealEnabled = true;
     } catch (_vaultErr) {
@@ -259,13 +297,42 @@ function dbStore(opts) {
 
   // Register the table with cryptoField. registerTable is idempotent
   // — subsequent dbStore() calls with the same tableName re-declare
-  // the same sealedFields and no-op.
+  // the same sealedFields and no-op. CRYPTO-1: when aad is on,
+  // (table, k, column) is threaded into the AEAD AAD so a DB-write
+  // attacker can't copy a sealed value between rows.
   if (sealEnabled) {
     cryptoField.registerTable(tableNameRaw, {
       sealedFields: ["headers", "body"],
+      aad:          aadOn,
+      rowIdField:   "k",
+      schemaVersion: "1",
     });
   }
 
+  // CRYPTO-4 — derive a per-vault HMAC secret for fingerprint sealing.
+  // The vault root key is the trust root; without it the secret is
+  // unrecoverable. Lazy: only derived when fpSealOn is enabled AND the
+  // vault is ready, so test fixtures that haven't initialized the
+  // vault still construct a dbStore (the fingerprint then falls back
+  // to bare sha3-256 with a single audit warning).
+  var fpHmacSecret = null;
+  if (fpSealOn) {
+    try {
+      // Use vault.aad.buildContextAad as a stable derivation input;
+      // the derivedHashSalt is per-deployment so the same dbStore
+      // instance across hosts converges on the same HMAC key.
+      var fpDeriveInput = "idempotency.fingerprint:" + tableNameRaw + ":" +
+        vault.getDerivedHashSalt().toString("hex");
+      fpHmacSecret = bCrypto.kdf(Buffer.from(fpDeriveInput, "utf8"), C.BYTES.bytes(32));
+    } catch (_fpErr) {
+      _emitAudit("idempotency.fingerprint_seal_skipped_no_vault",
+        { tableName: tableNameRaw,
+          reason: "vault.getDerivedHashSalt() unavailable; fingerprint falls back to plain sha3-256" },
+        "warning");
+      fpHmacSecret = null;
+    }
+  }
+
   if (doInit) {
     db.prepare("CREATE TABLE IF NOT EXISTS " + qTable + " (" +
       "k TEXT PRIMARY KEY, " +
@@ -279,9 +346,12 @@ function dbStore(opts) {
   }
 
   // Prepared statements. status_code + expires_at stay non-sealed
-  // so audit/forensic SELECTs don't have to unseal-everything.
+  // so audit/forensic SELECTs don't have to unseal-everything. The
+  // `k` column is selected even when not strictly needed for read
+  // because cryptoField.unsealRow uses it as the rowId in AAD when
+  // the table is AAD-bound (CRYPTO-1).
   var stmtGet = db.prepare(
-    "SELECT fingerprint, status_code, headers, body, expires_at FROM " +
+    "SELECT k, fingerprint, status_code, headers, body, expires_at FROM " +
     qTable + " WHERE k = ?");
   var stmtUpsert = db.prepare(
     "INSERT INTO " + qTable +
@@ -302,6 +372,13 @@ function dbStore(opts) {
     return bCrypto.namespaceHash("idempotency-key", rawKey);
   }
 
+  // CRYPTO-4 — emit / compare HMAC-shape fingerprints. The store
+  // round-trips the column as plain text (no transformation per-get);
+  // sealing happens at MINT time (when the middleware builds the
+  // fingerprint and hands it to set()). The store's responsibility is
+  // pass-through. The middleware's `_fingerprintRequest` consults
+  // `store.fingerprintMode` to know whether to HMAC.
+
   return {
     get: function (rawKey) {
       var row = stmtGet.get(_k(rawKey));
@@ -314,16 +391,26 @@ function dbStore(opts) {
       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);
+          // CRYPTO-13 — decryption failure used to delete the row,
+          // which let an attacker probe key presence via a "tamper +
+          // observe subsequent SELECT" oracle. The fix: emit audit,
+          // return null, do NOT delete. TTL sweeps stale rows out
+          // bounded by ttlMs; an out-of-band sweeper handles the
+          // corrupt-but-not-yet-expired case.
+          _emitAudit("idempotency.unseal_failed",
+            { tableName: tableNameRaw,
+              keyHash:   _hashKey(rawKey),
+              reason:    String(_unsealErr && _unsealErr.message || _unsealErr) },
+            "warning");
           return null;
         }
       }
       var headersObj;
       try {
-        headersObj = safeJson.parse(liveRow.headers, { maxBytes: 4 * 1024 * 1024 });               // allow:raw-byte-literal — 4 MiB headers ceiling
+        // CRYPTO-22 — route through C.BYTES.mib(4); raw `4 * 1024 * 1024`
+        // was a drift smell flagged by codebase-patterns. 4 MiB ceiling
+        // unchanged.
+        headersObj = safeJson.parse(liveRow.headers, { maxBytes: C.BYTES.mib(4) });
       } catch (_jsonErr) {
         // Parse failure has two distinct causes:
         //   1. Genuine corruption (truncated row, encoding mishap) — drop.
@@ -336,7 +423,8 @@ function dbStore(opts) {
         //      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;
+          (liveRow.headers.indexOf("vault:") === 0 ||
+           liveRow.headers.indexOf("vault.aad:") === 0);
         if (!lookedSealed) {
           stmtDeleteStale.run(_k(rawKey), row.expires_at);
         }
@@ -368,9 +456,56 @@ function dbStore(opts) {
     delete: function (rawKey) {
       stmtDelete.run(_k(rawKey));
     },
+    // CRYPTO-4 — the middleware consults this hook to HMAC the
+    // method+path+body digest under a vault-derived secret before
+    // insert + compare. Returns null when fpSeal is disabled OR the
+    // vault wasn't ready at construction; the middleware then falls
+    // back to bare sha3-256.
+    fingerprintHmac: function (preimageBytes) {
+      if (!fpSealOn || !fpHmacSecret) return null;
+      return nodeCrypto.createHmac("sha3-256", fpHmacSecret)
+        .update(preimageBytes).digest("hex");
+    },
+    // CRYPTO-1 — operator helper: walk the table and reseal every row
+    // under the AAD form. Existing v0.9.15-v0.9.57 rows continue to
+    // read on a per-row basis (unsealRow auto-detects shape), but
+    // operators wanting an explicit migration step call this once.
+    // Idempotent; rows already AAD-sealed pass through unchanged.
+    resealMigrate: function () {
+      if (!sealEnabled || !aadOn) {
+        return { migrated: 0, skipped: 0, reason: "aad-or-seal-disabled" };
+      }
+      var migrated = 0;
+      var skipped = 0;
+      var rows = db.prepare("SELECT k, fingerprint, status_code, headers, body, expires_at FROM " +
+        qTable).all();
+      for (var i = 0; i < rows.length; i += 1) {
+        var r = rows[i];
+        // If headers/body already start with vault.aad: this row is
+        // already migrated.
+        var alreadyAad = typeof r.headers === "string" &&
+          r.headers.indexOf("vault.aad:") === 0 &&
+          typeof r.body === "string" &&
+          r.body.indexOf("vault.aad:") === 0;
+        if (alreadyAad) { skipped += 1; continue; }
+        var unsealed;
+        try { unsealed = cryptoField.unsealRow(tableNameRaw, r); }
+        catch (_e) { skipped += 1; continue; }
+        var resealed = cryptoField.sealRow(tableNameRaw, unsealed);
+        stmtUpsert.run(
+          resealed.k, resealed.fingerprint, resealed.status_code,
+          resealed.headers, resealed.body, resealed.expires_at);
+        migrated += 1;
+      }
+      _emitAudit("idempotency.reseal_migrate_complete",
+        { tableName: tableNameRaw, migrated: migrated, skipped: skipped });
+      return { migrated: migrated, skipped: skipped, reason: null };
+    },
     _tableName:   tableNameRaw,
     _hashKeys:    hashKeys,
     _sealEnabled: sealEnabled,
+    _aadOn:       aadOn,
+    _fpSealOn:    fpSealOn && fpHmacSecret !== null,
   };
 }
 
@@ -387,21 +522,27 @@ function _validateStore(store, where) {
   }
 }
 
-function _fingerprintRequest(req, bodyBytes) {
-  // Fingerprint = method + path + body sha3-256. Per the draft §4.3,
-  // a key+body mismatch is a client-side mistake; our fingerprint
-  // covers method + path so a client reusing a key across different
-  // endpoints is also caught. Body hash uses SHA3-256 to match the
-  // framework's PQC-first crypto posture (SHA-256 is fine for
-  // collision-resistance here but we use SHA3 for codebase
-  // uniformity).
-  var hash = nodeCrypto.createHash("sha3-256");
-  hash.update((req.method || "GET") + "\n");
-  hash.update((req.url || "/") + "\n");
-  if (bodyBytes && bodyBytes.length > 0) {
-    hash.update(bodyBytes);
+function _fingerprintRequest(req, bodyBytes, store) {
+  // Fingerprint preimage = method + path + body. Per the draft §4.3,
+  // a key+body mismatch is a client-side mistake; our preimage covers
+  // method + path so a client reusing a key across different
+  // endpoints is also caught. CRYPTO-4: when the store exposes a
+  // `fingerprintHmac` hook (dbStore with fingerprintSeal:true + vault
+  // ready), the preimage is HMAC'd under a vault-derived secret so a
+  // DB dump leaks neither the preimage nor a brute-forceable digest.
+  // The middleware then compares the HMAC'd column directly; both
+  // sides of the compare use the same secret so the equality is
+  // exact, no key-recovery is performed on the dump side.
+  var preimage = Buffer.concat([
+    Buffer.from((req.method || "GET") + "\n", "utf8"),
+    Buffer.from((req.url || "/") + "\n", "utf8"),
+    bodyBytes && bodyBytes.length > 0 ? bodyBytes : Buffer.alloc(0),
+  ]);
+  if (store && typeof store.fingerprintHmac === "function") {
+    var hmacOut = store.fingerprintHmac(preimage);
+    if (hmacOut !== null) return hmacOut;
   }
-  return hash.digest("hex");
+  return nodeCrypto.createHash("sha3-256").update(preimage).digest("hex");
 }
 
 function _emitAudit(action, metadata, outcome) {
@@ -461,6 +602,15 @@ function _emitAudit(action, metadata, outcome) {
  *   requireIdempotencyKey: boolean,  // default: false — refuse missing-key
  *   bodyFingerprint:       function, // (req) => Buffer|string|object|null — operator-supplied body extractor
  *   maxBodyBytes:          number,   // default: 1 MiB — replay-cache body cap
+ *   bodyFingerprintFallback: string, // default "deny" (SUBSTRATE-13) — when neither
+ *                                    // bodyFingerprint nor req._rawBody / req.body is
+ *                                    // available for POST/PUT/PATCH, refuse with HTTP 400
+ *                                    // idempotency/missing-body-fingerprint instead of
+ *                                    // silently degrading the fingerprint to method+path.
+ *                                    // Set to "method-path-only" to restore the pre-0.9.58
+ *                                    // behavior (the audit chain still logs
+ *                                    // idempotency.empty_body_fingerprint so the
+ *                                    // misorder is visible in operator review).
  *
  * **Mount order — idempotency MUST run AFTER body-parser.** The hook
  * (and the default `req._rawBody||req.body` lookup) reads request
@@ -519,6 +669,22 @@ function create(opts) {
     opts.bodyFingerprint, "idempotencyKey.bodyFingerprint",
     IdempotencyError, "idempotency/bad-body-fingerprint"
   ) || null;
+  // SUBSTRATE-13 — default "deny" refuses body-bearing requests that
+  // arrive with neither req._rawBody / req.body NOR an operator-
+  // supplied bodyFingerprint hook. The silent-degrade-to-method+path
+  // path was a §4.3 violation (same key + different body returned
+  // false replays); the runtime now refuses with HTTP 400 instead.
+  // Operators with a documented "method-path-only" use case opt in.
+  var bodyFpFallback = "deny";
+  if (opts.bodyFingerprintFallback !== undefined) {
+    if (opts.bodyFingerprintFallback !== "deny" &&
+        opts.bodyFingerprintFallback !== "method-path-only") {
+      throw new IdempotencyError("idempotency/bad-body-fingerprint-fallback",
+        "idempotencyKey: opts.bodyFingerprintFallback must be \"deny\" or \"method-path-only\", got " +
+        JSON.stringify(opts.bodyFingerprintFallback), true);
+    }
+    bodyFpFallback = opts.bodyFingerprintFallback;
+  }
 
   // Per-response collector cap. Idempotency replay only makes sense
   // for response bodies that fit in memory; the cap is operator-
@@ -595,11 +761,11 @@ function create(opts) {
 
     // Misordered-mount detector — body-bearing method reached us
     // with neither a parsed body nor a raw-body buffer. Most likely
-    // body-parser hasn't run yet, which silently degrades the
-    // fingerprint to method+path. Emit a warning so the audit log
-    // surfaces the misconfiguration. (Genuinely empty POST bodies
-    // also trip this — acceptable cost; the audit field captures the
-    // distinction via `hasRawBody`/`hasParsedBody`.)
+    // body-parser hasn't run yet, which used to silently degrade the
+    // fingerprint to method+path; SUBSTRATE-13 (v0.9.58) makes that
+    // case refuse with HTTP 400 by default. The audit emit fires in
+    // both fallback modes so operator review surfaces the
+    // misconfiguration regardless of the chosen fallback.
     if (!bodyBytes && (method === "POST" || method === "PUT" || method === "PATCH")) {
       _emitAudit("idempotency.empty_body_fingerprint",
         {
@@ -608,11 +774,24 @@ function create(opts) {
           hasRawBody:      Boolean(req._rawBody),
           hasParsedBody:   req.body !== undefined && req.body !== null,
           hasFingerprintHook: Boolean(bodyFingerprintFn),
+          fallback:        bodyFpFallback,
         },
-        "warning");
+        bodyFpFallback === "deny" ? "denied" : "warning");
+      if (bodyFpFallback === "deny") {
+        var missingBody = problemDetails().create({
+          type:   problemDetails().getBase() + "/idempotency/missing-body-fingerprint",
+          title:  "Idempotency body fingerprint unavailable",
+          status: 400,                                                                               // allow:raw-byte-literal — HTTP status 400 Bad Request
+          detail: "The idempotency middleware could not derive a body fingerprint for this " +
+                  "request. Mount body-parser BEFORE the idempotency middleware, OR provide an " +
+                  "opts.bodyFingerprint(req) hook. To restore the pre-0.9.58 method+path-only " +
+                  "behavior, set opts.bodyFingerprintFallback=\"method-path-only\".",
+        });
+        return problemDetails().respond(res, missingBody);
+      }
     }
 
-    var fingerprint = _fingerprintRequest(req, bodyBytes);
+    var fingerprint = _fingerprintRequest(req, bodyBytes, opts.store);
 
     var cached = null;
     try { cached = opts.store.get(key); }
@@ -743,9 +922,43 @@ function _redactKey(key) {
   return key.slice(0, 4) + "..." + key.slice(-2) + " (len=" + key.length + ")";                    // allow:raw-byte-literal — log-redaction prefix/suffix lengths
 }
 
+/**
+ * @primitive b.middleware.idempotencyKey.resealMigrate
+ * @signature b.middleware.idempotencyKey.resealMigrate(store)
+ * @since     0.9.58
+ * @related   b.middleware.idempotencyKey.dbStore
+ *
+ * One-shot operator helper that walks a dbStore's table and reseals
+ * every row under the AAD-bound envelope shape introduced in v0.9.58
+ * (CRYPTO-1). Existing v0.9.15-v0.9.57 rows continue to read on a
+ * per-row basis (unsealRow auto-detects shape) so a deploy without
+ * this call is correct, but operators who want to upgrade in bulk
+ * call this once after upgrading.
+ *
+ * Returns `{ migrated, skipped, reason }`. `migrated` counts rows
+ * rewritten with AAD-bound ciphertext; `skipped` counts rows already
+ * AAD-shaped or that failed unseal under the current key (those rows
+ * stay in place and surface via the standard
+ * `idempotency.unseal_failed` audit on next read). `reason` is null
+ * on success; populated when the store doesn't support migration
+ * (in-memory store, custom operator-supplied store, etc.).
+ *
+ * @example
+ *   var store = b.middleware.idempotencyKey.dbStore({ db: myDb });
+ *   var info  = b.middleware.idempotencyKey.resealMigrate(store);
+ *   logger.info("idempotency migration", info);
+ */
+function resealMigrate(store) {
+  if (!store || typeof store.resealMigrate !== "function") {
+    return { migrated: 0, skipped: 0, reason: "store-does-not-support-reseal" };
+  }
+  return store.resealMigrate();
+}
+
 module.exports = create;
 module.exports.create     = create;
 module.exports.memoryStore = memoryStore;
 module.exports.dbStore     = dbStore;
+module.exports.resealMigrate = resealMigrate;
 module.exports.DEFAULT_METHODS = DEFAULT_METHODS;
 module.exports.IdempotencyError = IdempotencyError;