@blamejs/core 0.7.0 → 0.7.4

package/lib/framework-error.js

@@ -172,6 +172,17 @@ var TestingError          = defineClass("TestingError",          { alwaysPermane
 // "account is currently locked" condition is NOT an error — recordFailure
 // returns { locked: true, lockedUntil } so the caller decides the response.
 var LockoutError          = defineClass("LockoutError",          { alwaysPermanent: true });
+// FileUploadError is alwaysPermanent: chunk-hash mismatch / oversized
+// chunk / oversized total file / manifest verification failure are all
+// caller-shape errors that won't succeed on retry. Operators wrap the
+// route handler with their own retry policy if they want client-side
+// resumability.
+var FileUploadError       = defineClass("FileUploadError",       { alwaysPermanent: true });
+// StaticServeError covers the download-side surface of staticServe.create.
+// withStatusCode: true so the framework can translate to operator-meaningful
+// HTTP responses (403 permission_denied, 404 not_found, 412 precondition_failed,
+// 416 range_not_satisfiable, 429 quota_exceeded, 451 retention_blocked).
+var StaticServeError      = defineClass("StaticServeError",      { withStatusCode: true });
 
 module.exports = {
   FrameworkError:         FrameworkError,
@@ -199,4 +210,6 @@ module.exports = {
   NotifyError:            NotifyError,
   TestingError:           TestingError,
   LockoutError:           LockoutError,
+  FileUploadError:        FileUploadError,
+  StaticServeError:       StaticServeError,
 };

package/lib/log-stream-syslog.js

@@ -220,7 +220,7 @@ function create(config) {
       sock = net.connect(connectOpts, onConnect);
     }
     sock.unref && sock.unref();
-    sock.on("error", function () { /* defer to 'close' for reconnect */ });
+    sock.on("error", function () { /* reconnect handled in the close listener */ });
     sock.on("close", function () {
       sockReady = false;
       connecting = false;

package/lib/middleware/api-encrypt.js

@@ -116,6 +116,16 @@ var DEFAULT_REPLAY_WINDOW_MS = C.TIME.minutes(5);
 var DEFAULT_CONTENT_TYPES = ["application/json"];
 var SESSION_KEY_BYTES = C.BYTES.bytes(32);
 var REQUEST_NONCE_BYTES = C.BYTES.bytes(16);
+var DEFAULT_SESSION_TTL_MS = C.TIME.minutes(15);
+// 1024 ≈ "a session with a thousand response rotations" — round-number
+// kibi-aligned default; operators raise this for chat / streaming sessions
+// or lower it for strict per-key forward-secrecy postures.
+var DEFAULT_SESSION_MAX_RESPONSES = 0x400;
+// SID format: UUID-shaped string. Operators with their own session-id
+// vocabulary subscribe to the same shape (cluster-storage / cache backends
+// already index on string keys).
+var SID_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+var SID_MAX_LENGTH = C.BYTES.bytes(64);
 
 function _err(code, message, statusCode) {
   return new ApiEncryptError(code, message, true, statusCode || 400);
@@ -161,6 +171,57 @@ function _resolveKeypairs(opts) {
 
 var HTTP_STATUS = requestHelpers.HTTP_STATUS;
 
+// _defaultSessionStore — in-memory session table for single-process
+// deployments. Operators with multi-replica deploys pass an
+// operator-supplied store (b.cache.create({ backend: "cluster" }) or any
+// `{ get, set, delete }`-shaped handle). Per-replica isolation in default
+// mode means sticky sessions; the limit is documented in the wiki.
+//
+//   .get(sid)  → row | null
+//   .set(sid, row, { ttlMs }) → void
+//   .delete(sid) → void
+//
+// Each row stores:
+//   { sessionKey: Buffer, lastReqCtr: int, responsesEmitted: int,
+//     createdAt: ms, expiresAt: ms, lastUsedAt: ms }
+function _defaultSessionStore() {
+  var rows = new Map();
+  return {
+    get: function (sid) {
+      var row = rows.get(sid);
+      if (!row) return null;
+      if (Date.now() > row.expiresAt) {
+        rows.delete(sid);
+        return null;
+      }
+      return row;
+    },
+    set: function (sid, row /* opts */) {
+      rows.set(sid, row);
+    },
+    delete: function (sid) {
+      rows.delete(sid);
+    },
+    purgeExpired: function () {
+      var now = Date.now();
+      var purged = 0;
+      rows.forEach(function (row, sid) {
+        if (now > row.expiresAt) { rows.delete(sid); purged += 1; }
+      });
+      return purged;
+    },
+    size: function () { return rows.size; },
+    close: function () { rows.clear(); },
+  };
+}
+
+function _validSid(sid) {
+  return typeof sid === "string" &&
+         sid.length > 0 &&
+         sid.length <= SID_MAX_LENGTH &&
+         SID_RE.test(sid);
+}
+
 function _writeRejection(res, code, body) {
   if (res.headersSent || res.writableEnded) return;
   if (typeof res.writeHead === "function") {
@@ -177,6 +238,9 @@ function create(opts) {
     "keypair", "keypairs", "replayWindowMs", "pruneIntervalMs",
     "nonceStore", "exemptPaths", "contentTypes", "audit",
     "maxDecryptedBytes", "trustProxy",
+    // Per-session keying mode (opt-in; per-request stays default).
+    "keying", "sessionStore", "sessionTtlMs", "sessionMaxResponses",
+    "observability",
   ], "middleware.apiEncrypt");
   var keypairs       = _resolveKeypairs(opts);
   var activeKeypair  = keypairs[0];
@@ -210,6 +274,70 @@ function create(opts) {
   var trustProxy     = opts.trustProxy === true;
   var lastPruneAt    = 0;
 
+  // ---- per-session keying opts ----
+  var keying = opts.keying != null ? opts.keying : "per-request";
+  if (keying !== "per-request" && keying !== "per-session") {
+    throw _err("BAD_OPT",
+      "apiEncrypt: keying must be 'per-request' (default) or 'per-session', got " +
+      JSON.stringify(opts.keying), 500);
+  }
+  var sessionTtlMs = opts.sessionTtlMs != null ? opts.sessionTtlMs : DEFAULT_SESSION_TTL_MS;
+  var sessionMaxResponses = opts.sessionMaxResponses != null
+    ? opts.sessionMaxResponses : DEFAULT_SESSION_MAX_RESPONSES;
+  if (typeof sessionTtlMs !== "number" || !isFinite(sessionTtlMs) || sessionTtlMs <= 0) {
+    throw _err("BAD_OPT",
+      "apiEncrypt: sessionTtlMs must be a positive finite number (ms), got " +
+      JSON.stringify(opts.sessionTtlMs), 500);
+  }
+  if (typeof sessionMaxResponses !== "number" || !isFinite(sessionMaxResponses) ||
+      sessionMaxResponses <= 0 || Math.floor(sessionMaxResponses) !== sessionMaxResponses) {
+    throw _err("BAD_OPT",
+      "apiEncrypt: sessionMaxResponses must be a positive finite integer, got " +
+      JSON.stringify(opts.sessionMaxResponses), 500);
+  }
+  // sessionStore — duck-typed handle exposing { get, set, delete }. The
+  // helper optionalObjectWithMethod only checks one method; here we need
+  // three. Inline shape kept; not a generic enough pattern to warrant a
+  // separate helper.
+  if (opts.sessionStore !== undefined && opts.sessionStore !== null) {
+    var ss = opts.sessionStore;
+    var ssOk = typeof ss === "object" &&
+               typeof ss.get === "function" &&
+               typeof ss.set === "function" &&
+               typeof ss.delete === "function";
+    if (!ssOk) {
+      throw _err("BAD_OPT",
+        "apiEncrypt: sessionStore must expose { get(sid), set(sid, row, opts?), delete(sid) } " +
+        "(b.cache.create() is shape-compatible)", 500);
+    }
+  }
+  var sessionStore = (keying === "per-session" && opts.sessionStore)
+    ? opts.sessionStore
+    : (keying === "per-session" ? _defaultSessionStore() : null);
+  // Observability tap — per-session emits counters for sessions
+  // established / replay-rejected / expired / rotated. Per-request mode
+  // ignores this opt; the existing events.API_ENCRYPT_FAILURE channel
+  // already carries failure shape there.
+  validateOpts.observabilityShape(opts.observability,
+    "apiEncrypt", ApiEncryptError, "BAD_OPT");
+  var observabilityHandle = opts.observability || null;
+  function _emitObs(name, value, labels) {
+    if (observabilityHandle) {
+      observabilityHandle.safeEvent(name, value, labels || {});
+    }
+  }
+  function _emitSessionAudit(action, info) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action: action, outcome: info.outcome || "success",
+        metadata: info.metadata || {},
+        actor: info.actor || null,
+        requestId: info.requestId || null,
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
   function _isExempt(req) {
     var p = req.pathname || (req.url || "/").split("?")[0];
     for (var i = 0; i < exemptPaths.length; i++) {
@@ -267,13 +395,21 @@ function create(opts) {
     });
   }
 
-  function _wrapResJson(res, sessionKey) {
+  // _wrapResJson — install res.json that encrypts the response with the
+  // session key. In per-request mode the response is `{ _ct }`; in
+  // per-session mode it carries `{ _ct, _sid, _ctr }` so the client can
+  // detect tampered / replayed responses with a monotonic counter check.
+  function _wrapResJson(res, sessionKey, sessionCtx) {
     var origJson = res.json;
     res.json = function (data) {
       try {
         var ptBuf = Buffer.from(JSON.stringify(data), "utf8");
         var ctBuf = crypto.encryptPacked(ptBuf, sessionKey);
         var encrypted = { _ct: ctBuf.toString("base64") };
+        if (sessionCtx) {
+          encrypted._sid = sessionCtx.sid;
+          encrypted._ctr = sessionCtx.responseCtr;
+        }
         if (typeof origJson === "function") {
           return origJson.call(res, encrypted);
         }
@@ -294,6 +430,19 @@ function create(opts) {
     };
   }
 
+  // _decryptEkToSessionKey — try every keypair in order; returns the
+  // 32-byte sessionKey buffer or null on AEAD failure across all keypairs.
+  function _decryptEkToSessionKey(ek) {
+    for (var ki = 0; ki < keypairs.length; ki++) {
+      try {
+        var sessionKeyB64 = crypto.decrypt(ek, keypairs[ki]);
+        var candidate = Buffer.from(sessionKeyB64, "base64");
+        if (candidate.length === SESSION_KEY_BYTES) return candidate;
+      } catch (_e) { /* try next keypair */ }
+    }
+    return null;
+  }
+
   async function middleware(req, res, next) {
     if (_isExempt(req)) return next();
     if (!_matchesContentType(req)) return next();
@@ -303,58 +452,158 @@ function create(opts) {
       _emitFailure(req, "shape");
       return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
     }
-    var ek = body._ek, ct = body._ct, ts = body._ts, nonce = body._nonce;
-    if (typeof ek !== "string" || typeof ct !== "string" ||
-        typeof ts !== "number" || typeof nonce !== "string") {
+
+    var now = Date.now();
+    var ct = body._ct, ts = body._ts;
+    if (typeof ct !== "string" || typeof ts !== "number") {
       _emitFailure(req, "shape");
       return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
     }
-
-    // Replay window — must be within ±replayWindowMs of server clock.
-    var now = Date.now();
     if (Math.abs(now - ts) > replayWindowMs) {
       _emitFailure(req, "stale");
       return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
     }
 
-    // Nonce check + insert atomically. Loser of the insert race
-    // (= already-seen nonce within the replay window) is a replay.
-    // Hash the nonce before storage so a leaked DB / table dump
-    // doesn't reveal the original 16-byte client nonces (the spec's
-    // "sealed nonce hash"). SHA3 is deterministic so PRIMARY KEY
-    // conflict detection still works.
-    var nonceHash = crypto.sha3Hash(nonce, "hex");
-    var expireAt = now + replayWindowMs;
-    var freshNonce;
-    try { freshNonce = await nonceStore.checkAndInsert(nonceHash, expireAt); }
-    catch (_e) {
-      _emitFailure(req, "nonce-store-error");
-      return _writeRejection(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "nonce-store-unavailable" });
-    }
-    if (!freshNonce) {
-      _emitFailure(req, "replay");
-      return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
-    }
-
-    // Decrypt _ek → session key. During a rotation overlap window,
-    // some clients still hold the previous server pubkey — try each
-    // keypair in order. The active keypair is keypairs[0]; older
-    // rotated-out keypairs follow. AEAD failure on every keypair =
-    // genuine bad ciphertext.
+    // Per-request OR per-session bootstrap path: shape includes _ek + _nonce.
+    // Per-session subsequent path: shape includes _sid + _ctr (no _ek).
+    var ek = body._ek, nonce = body._nonce, sid = body._sid, ctr = body._ctr;
     var sessionKey = null;
-    for (var ki = 0; ki < keypairs.length; ki++) {
-      try {
-        var sessionKeyB64 = crypto.decrypt(ek, keypairs[ki]);
-        var candidate = Buffer.from(sessionKeyB64, "base64");
-        if (candidate.length === SESSION_KEY_BYTES) {
-          sessionKey = candidate;
-          break;
+    var sessionCtx = null;             // null = per-request mode response shape
+    var session = null;
+
+    if (typeof ek === "string" && typeof nonce === "string") {
+      // ---- Bootstrap path (per-request mode OR first request of session) ----
+      var nonceHash = crypto.sha3Hash(nonce, "hex");
+      var expireAt = now + replayWindowMs;
+      var freshNonce;
+      try { freshNonce = await nonceStore.checkAndInsert(nonceHash, expireAt); }
+      catch (_e) {
+        _emitFailure(req, "nonce-store-error");
+        return _writeRejection(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "nonce-store-unavailable" });
+      }
+      if (!freshNonce) {
+        _emitFailure(req, "replay");
+        return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
+      }
+      sessionKey = _decryptEkToSessionKey(ek);
+      if (!sessionKey) {
+        _emitFailure(req, "tag");
+        return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
+      }
+      if (keying === "per-session") {
+        if (!_validSid(sid)) {
+          _emitFailure(req, "shape");
+          return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
         }
-      } catch (_e) { /* try next keypair */ }
-    }
-    if (!sessionKey) {
-      _emitFailure(req, "tag");
-      return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
+        if (typeof ctr !== "number" || !isFinite(ctr) || ctr < 0 || Math.floor(ctr) !== ctr) {
+          _emitFailure(req, "shape");
+          return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
+        }
+        // Bootstrap a new session row keyed by sid.
+        session = {
+          sessionKey:       sessionKey,
+          lastReqCtr:       ctr,
+          responsesEmitted: 0,
+          createdAt:        now,
+          lastUsedAt:       now,
+          expiresAt:        now + sessionTtlMs,
+        };
+        try { await sessionStore.set(sid, session, { ttlMs: sessionTtlMs }); }
+        catch (_e) {
+          _emitFailure(req, "session-store-error");
+          return _writeRejection(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "session-store-unavailable" });
+        }
+        _emitObs("apiEncrypt.session.created", 1, { mode: "per-session" });
+        _emitSessionAudit("apiEncrypt.session.created", {
+          actor: requestHelpers.extractActorContext(req),
+          metadata: { sid: sid, expiresAt: session.expiresAt },
+          requestId: req.requestId || null,
+        });
+        sessionCtx = { sid: sid, responseCtr: 1 };
+        session.responsesEmitted = 1;
+      }
+    } else if (keying === "per-session" &&
+               typeof sid === "string" && typeof ctr === "number") {
+      // ---- Per-session subsequent-request path ----
+      if (!_validSid(sid)) {
+        _emitFailure(req, "shape");
+        return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
+      }
+      if (!isFinite(ctr) || ctr < 0 || Math.floor(ctr) !== ctr) {
+        _emitFailure(req, "shape");
+        return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
+      }
+      try { session = await sessionStore.get(sid); }
+      catch (_e) {
+        _emitFailure(req, "session-store-error");
+        return _writeRejection(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "session-store-unavailable" });
+      }
+      if (!session) {
+        _emitObs("apiEncrypt.session.unknown", 1, {});
+        _emitFailure(req, "session-unknown");
+        return _writeRejection(res, HTTP_STATUS.UNAUTHORIZED, { error: "session-unknown" });
+      }
+      if (now > session.expiresAt) {
+        try { await sessionStore.delete(sid); } catch (_e) { /* best-effort */ }
+        _emitObs("apiEncrypt.session.expired", 1, {});
+        _emitSessionAudit("apiEncrypt.session.expired", {
+          outcome: "denied",
+          actor: requestHelpers.extractActorContext(req),
+          metadata: { sid: sid, reason: "ttl_exceeded" },
+          requestId: req.requestId || null,
+        });
+        _emitFailure(req, "session-expired");
+        return _writeRejection(res, HTTP_STATUS.UNAUTHORIZED, { error: "session-expired" });
+      }
+      if (session.responsesEmitted >= sessionMaxResponses) {
+        try { await sessionStore.delete(sid); } catch (_e) { /* best-effort */ }
+        _emitObs("apiEncrypt.session.rotated", 1, { reason: "max_responses" });
+        _emitSessionAudit("apiEncrypt.session.rotated", {
+          actor: requestHelpers.extractActorContext(req),
+          metadata: { sid: sid, reason: "max_responses_exceeded",
+                      responsesEmitted: session.responsesEmitted },
+          requestId: req.requestId || null,
+        });
+        _emitFailure(req, "session-rotation-required");
+        return _writeRejection(res, HTTP_STATUS.UNAUTHORIZED, { error: "session-rotation-required" });
+      }
+      // Replay defense: counter MUST strictly increase.
+      if (ctr <= session.lastReqCtr) {
+        _emitObs("apiEncrypt.session.replay_rejected", 1, {});
+        _emitSessionAudit("apiEncrypt.session.replay_rejected", {
+          outcome: "denied",
+          actor: requestHelpers.extractActorContext(req),
+          metadata: { sid: sid, receivedCtr: ctr, lastSeen: session.lastReqCtr },
+          requestId: req.requestId || null,
+        });
+        _emitFailure(req, "counter-replay");
+        return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
+      }
+      sessionKey = session.sessionKey;
+      if (Buffer.isBuffer(sessionKey) === false) {
+        // Operator-supplied store may have JSON-serialised the buffer.
+        // Accept hex / base64 / Uint8Array and coerce.
+        if (typeof sessionKey === "string") {
+          sessionKey = Buffer.from(sessionKey, "base64");
+        } else if (sessionKey && sessionKey.type === "Buffer" && Array.isArray(sessionKey.data)) {
+          sessionKey = Buffer.from(sessionKey.data);
+        } else if (sessionKey instanceof Uint8Array) {
+          sessionKey = Buffer.from(sessionKey);
+        }
+      }
+      if (!Buffer.isBuffer(sessionKey) || sessionKey.length !== SESSION_KEY_BYTES) {
+        _emitFailure(req, "session-store-error");
+        return _writeRejection(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "session-store-unavailable" });
+      }
+      session.lastReqCtr = ctr;
+      session.lastUsedAt = now;
+      session.responsesEmitted += 1;
+      try { await sessionStore.set(sid, session, { ttlMs: session.expiresAt - now }); }
+      catch (_e) { /* best-effort — request still proceeds */ }
+      sessionCtx = { sid: sid, responseCtr: session.responsesEmitted };
+    } else {
+      _emitFailure(req, "shape");
+      return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
     }
 
     // Decrypt _ct → cleartext payload bytes → JSON object.
@@ -373,8 +622,9 @@ function create(opts) {
     // data (e.g. send a follow-up encrypted SSE event).
     req.body = clearObj;
     req.apiEncryptSessionKey = sessionKey;
+    if (sessionCtx) req.apiEncryptSession = { sid: sessionCtx.sid };
 
-    _wrapResJson(res, sessionKey);
+    _wrapResJson(res, sessionKey, sessionCtx);
     _maybePrune();
 
     return next();
@@ -403,7 +653,11 @@ function create(opts) {
   middleware.publishPublicKey = publishPublicKey;
   middleware.close = function () {
     if (typeof nonceStore.close === "function") nonceStore.close();
+    if (sessionStore && typeof sessionStore.close === "function") sessionStore.close();
   };
+  // Expose for tests / operator dashboards. Counts are 0 in per-request mode.
+  middleware.sessionStore = sessionStore;
+  middleware.keying = keying;
 
   return middleware;
 }
@@ -417,7 +671,7 @@ function create(opts) {
 
 function client(opts) {
   opts = opts || {};
-  validateOpts(opts, ["pubkey", "maxDecryptedBytes"], "middleware.apiEncrypt.client");
+  validateOpts(opts, ["pubkey", "maxDecryptedBytes", "keying"], "middleware.apiEncrypt.client");
   if (!opts.pubkey || typeof opts.pubkey !== "object") {
     throw _err("CLIENT_INVALID_PUBKEY",
       "apiEncrypt.client: opts.pubkey is required ({ publicKey, ecPublicKey })", 500);
@@ -431,8 +685,87 @@ function client(opts) {
   var maxDecryptedBytes = opts.maxDecryptedBytes != null
     ? opts.maxDecryptedBytes
     : C.BYTES.mib(4);
+  var keying = opts.keying != null ? opts.keying : "per-request";
+  if (keying !== "per-request" && keying !== "per-session") {
+    throw _err("CLIENT_BAD_OPT",
+      "apiEncrypt.client: keying must be 'per-request' (default) or 'per-session', got " +
+      JSON.stringify(opts.keying), 500);
+  }
+
+  if (keying === "per-request") {
+    return { encryptRequest: _encryptPerRequest, keying: keying };
+  }
+
+  // Per-session: stateful client. encryptRequest mutates internal counter.
+  // First call sends the bootstrap envelope; subsequent calls omit _ek/_nonce
+  // and increment the counter. Operator can call resetSession() to force a
+  // new bootstrap (e.g. after server returns "session-expired").
+  var perSessionKey = null;
+  var perSessionSid = null;
+  var perSessionReqCtr = 0;
+  var perSessionLastResCtr = 0;
+
+  function _resetSession() {
+    perSessionKey = crypto.generateBytes(SESSION_KEY_BYTES);
+    perSessionSid = _generateUuidV4();
+    perSessionReqCtr = 0;
+    perSessionLastResCtr = 0;
+  }
 
-  function encryptRequest(payload) {
+  function _decryptPerSessionResponse(responseBody) {
+    if (!responseBody || typeof responseBody !== "object" ||
+        typeof responseBody._ct !== "string") {
+      throw _err("CLIENT_RESPONSE_SHAPE",
+        "apiEncrypt.client: response missing _ct field");
+    }
+    if (typeof responseBody._sid !== "string" || responseBody._sid !== perSessionSid) {
+      throw _err("CLIENT_RESPONSE_SID",
+        "apiEncrypt.client: response sid does not match opened session");
+    }
+    if (typeof responseBody._ctr !== "number" || responseBody._ctr <= perSessionLastResCtr) {
+      throw _err("CLIENT_RESPONSE_REPLAY",
+        "apiEncrypt.client: response counter is not strictly increasing " +
+        "(got " + responseBody._ctr + ", lastSeen " + perSessionLastResCtr + ")");
+    }
+    perSessionLastResCtr = responseBody._ctr;
+    var resCtBuf = Buffer.from(responseBody._ct, "base64");
+    var resPtBuf = crypto.decryptPacked(resCtBuf, perSessionKey);
+    return safeJson.parse(resPtBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
+  }
+
+  function _encryptPerSession(payload) {
+    if (payload === undefined) payload = null;
+    if (!perSessionKey) _resetSession();
+    var ts = Date.now();
+    var ptBuf = Buffer.from(JSON.stringify(payload), "utf8");
+    var ctBuf = crypto.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");
+      body = {
+        _ek:    ek,
+        _ct:    ctBuf.toString("base64"),
+        _ts:    ts,
+        _nonce: nonce,
+        _sid:   perSessionSid,
+        _ctr:   perSessionReqCtr,
+      };
+    } else {
+      // Subsequent — sid + ctr only. KEM material amortized across the session.
+      body = {
+        _ct:    ctBuf.toString("base64"),
+        _ts:    ts,
+        _sid:   perSessionSid,
+        _ctr:   perSessionReqCtr,
+      };
+    }
+    return { body: body, decryptResponse: _decryptPerSessionResponse };
+  }
+
+  function _encryptPerRequest(payload) {
     if (payload === undefined) payload = null;
     var sessionKey = crypto.generateBytes(SESSION_KEY_BYTES);
     var ek = crypto.encrypt(sessionKey.toString("base64"), pubkey);
@@ -447,9 +780,6 @@ function client(opts) {
         _ts:    ts,
         _nonce: requestNonce,
       },
-      // Captured-closure decrypt — safe to pass back to the caller.
-      // sessionKey lives only in this closure; once the closure goes
-      // out of scope it can be garbage-collected.
       decryptResponse: function (responseBody) {
         if (!responseBody || typeof responseBody !== "object" ||
             typeof responseBody._ct !== "string") {
@@ -463,7 +793,35 @@ function client(opts) {
     };
   }
 
-  return { encryptRequest: encryptRequest };
+  return {
+    encryptRequest: _encryptPerSession,
+    resetSession:   _resetSession,
+    sessionInfo:    function () {
+      return {
+        sid: perSessionSid,
+        reqCtr: perSessionReqCtr,
+        lastResCtr: perSessionLastResCtr,
+      };
+    },
+    keying: keying,
+  };
+}
+
+// _generateUuidV4 — UUID v4 from 16 random bytes, formatted dash-separated.
+// Used for client-side session-id generation in per-session keying.
+// 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
+  // Set version (4) and variant (10x) bits per RFC 4122.
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  var hex = b.toString("hex");
+  return hex.slice(0, 8) + "-" +                        // allow:raw-byte-literal — RFC 4122 hex offsets
+         hex.slice(8, 12) + "-" +                       // allow:raw-byte-literal
+         hex.slice(12, 16) + "-" +                      // allow:raw-byte-literal
+         hex.slice(16, 20) + "-" +                      // allow:raw-byte-literal
+         hex.slice(20, 32);                             // allow:raw-byte-literal
 }
 
 // ---- Server-to-server convenience ----
@@ -491,7 +849,7 @@ function client(opts) {
 function httpClientEncrypted(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "pubkey", "baseUrl", "headers", "method", "maxDecryptedBytes",
+    "pubkey", "baseUrl", "headers", "method", "maxDecryptedBytes", "keying",
   ], "middleware.apiEncrypt.httpClient");
   if (!opts.pubkey) {
     throw _err("CLIENT_INVALID_PUBKEY",
@@ -500,7 +858,12 @@ function httpClientEncrypted(opts) {
   var maxDecryptedBytes = opts.maxDecryptedBytes != null
     ? opts.maxDecryptedBytes
     : C.BYTES.mib(4);
-  var clientCtx     = client({ pubkey: opts.pubkey, maxDecryptedBytes: maxDecryptedBytes });
+  var keying = opts.keying != null ? opts.keying : "per-request";
+  var clientCtx = client({
+    pubkey: opts.pubkey,
+    maxDecryptedBytes: maxDecryptedBytes,
+    keying: keying,
+  });
   var baseUrl       = opts.baseUrl ? String(opts.baseUrl).replace(/\/$/, "") : "";
   var defaultHdrs   = opts.headers || {};
   var defaultMethod = opts.method  || "POST";

package/lib/middleware/db-role-for.js

@@ -113,14 +113,9 @@ function create(opts) {
 
   validateOpts.optionalFunction(opts.resolve, "middleware.dbRoleFor: resolve", DbRoleForError, "db-role-for/bad-opt");
   validateOpts.optionalFunction(opts.responder, "middleware.dbRoleFor: responder", DbRoleForError, "db-role-for/bad-opt");
-  if (opts.permissions !== undefined && opts.permissions !== null) {
-    if (typeof opts.permissions !== "object" ||
-        typeof opts.permissions.dbRoleFor !== "function") {
-      throw _err("db-role-for/bad-opt",
-        "middleware.dbRoleFor: permissions must be a b.permissions instance " +
-        "(missing dbRoleFor method)");
-    }
-  }
+  validateOpts.optionalObjectWithMethod(opts.permissions, "dbRoleFor",
+    "middleware.dbRoleFor: permissions", DbRoleForError, "db-role-for/bad-opt",
+    "must be a b.permissions instance (missing dbRoleFor method)");
   if (opts.defaultRole !== undefined && opts.defaultRole !== null) {
     if (typeof opts.defaultRole !== "string" || opts.defaultRole.length === 0) {
       throw _err("db-role-for/bad-opt",

package/lib/notify.js

@@ -154,11 +154,9 @@ function _validateCreateOpts(opts) {
       typeof opts.defaultBreaker !== "object") {
     throw _err("BAD_OPT", "notify.create: defaultBreaker must be a b.retry.CircuitBreaker opts object");
   }
-  if (opts.queue !== undefined && opts.queue !== null) {
-    if (typeof opts.queue !== "object" || typeof opts.queue.enqueue !== "function") {
-      throw _err("BAD_OPT", "notify.create: queue must be a b.queue-shaped handle (enqueue fn)");
-    }
-  }
+  validateOpts.optionalObjectWithMethod(opts.queue, "enqueue",
+    "notify.create: queue", NotifyError, "BAD_OPT",
+    "must be a b.queue-shaped handle (enqueue fn)");
   validateOpts.optionalFunction(opts.clock, "notify.create: clock", NotifyError);
 }