@blamejs/core 0.14.20 → 0.14.21

package/lib/mail-send-deliver.js

@@ -468,16 +468,25 @@ function create(opts) {
 
   var retryOpts = opts.retry || {};
   validateOpts(retryOpts, ["maxAttempts", "backoffMs"], "mail.send.deliver.create.retry");
-  var maxAttempts = typeof retryOpts.maxAttempts === "number" && retryOpts.maxAttempts > 0
-    ? Math.floor(retryOpts.maxAttempts) : DEFAULT_RETRY_BACKOFF_MS.length;
+  // Config-time entry-point opts: a typo (maxAttempts:"5", mxLookupMs:-1)
+  // must fail at create(), not silently fall back to the default. Absent
+  // keeps the default; present-but-bad throws. Matches opts.port above.
+  validateOpts.optionalPositiveInt(retryOpts.maxAttempts,
+    "mail.send.deliver.create.retry.maxAttempts", DeliverError, "deliver/bad-retry-maxAttempts");
+  var maxAttempts = retryOpts.maxAttempts !== undefined
+    ? retryOpts.maxAttempts : DEFAULT_RETRY_BACKOFF_MS.length;
   var backoffMs = Array.isArray(retryOpts.backoffMs) && retryOpts.backoffMs.length > 0
     ? retryOpts.backoffMs.slice() : DEFAULT_RETRY_BACKOFF_MS.slice();
 
   var timeouts = opts.timeouts || {};
   validateOpts(timeouts, ["mxLookupMs", "perHostMs"], "mail.send.deliver.create.timeouts");
-  var mxLookupTimeoutMs = typeof timeouts.mxLookupMs === "number" && timeouts.mxLookupMs > 0
+  validateOpts.optionalPositiveInt(timeouts.mxLookupMs,
+    "mail.send.deliver.create.timeouts.mxLookupMs", DeliverError, "deliver/bad-timeout-mxLookupMs");
+  validateOpts.optionalPositiveInt(timeouts.perHostMs,
+    "mail.send.deliver.create.timeouts.perHostMs", DeliverError, "deliver/bad-timeout-perHostMs");
+  var mxLookupTimeoutMs = timeouts.mxLookupMs !== undefined
     ? timeouts.mxLookupMs : DEFAULT_MX_LOOKUP_TIMEOUT_MS;
-  var perHostTimeoutMs = typeof timeouts.perHostMs === "number" && timeouts.perHostMs > 0
+  var perHostTimeoutMs = timeouts.perHostMs !== undefined
     ? timeouts.perHostMs : DEFAULT_PER_HOST_TIMEOUT_MS;
 
   var dsnOpts = opts.dsn || null;

package/lib/middleware/api-encrypt.js

@@ -289,18 +289,28 @@ function create(opts) {
   ], "middleware.apiEncrypt");
   var keypairs       = _resolveKeypairs(opts);
   var activeKeypair  = keypairs[0];
+  // replayWindowMs gates the timestamp-staleness check (Math.abs(now - ts)
+  // > replayWindowMs). A non-numeric value would make that comparison
+  // always false and SILENTLY disable the staleness defense, so a typo
+  // throws at boot rather than shipping an open replay window.
+  validateOpts.optionalPositiveFinite(opts.replayWindowMs,
+    "apiEncrypt: replayWindowMs", ApiEncryptError, "BAD_OPT");
   var replayWindowMs = opts.replayWindowMs || DEFAULT_REPLAY_WINDOW_MS;
   // Cap on decrypted-payload size handed to safeJson.parse. Defaults
   // to 4 MiB (bodyParser's default 1 MiB plus headroom for crypto +
   // base64 round-trip). Operators with chunkier inbound payloads
   // raise this; the framework refuses to parse anything larger as a
   // parse-bomb defense.
+  validateOpts.optionalPositiveInt(opts.maxDecryptedBytes,
+    "apiEncrypt: maxDecryptedBytes", ApiEncryptError, "BAD_OPT");
   var maxDecryptedBytes = opts.maxDecryptedBytes != null
     ? opts.maxDecryptedBytes
     : C.BYTES.mib(4);
   // The spec calls for a sweep cadence of replayWindowMs/2 — short
   // enough that expired nonces don't pile up but not so frequent the
   // sweep query becomes a hot path. Operators can override.
+  validateOpts.optionalPositiveFinite(opts.pruneIntervalMs,
+    "apiEncrypt: pruneIntervalMs", ApiEncryptError, "BAD_OPT");
   var pruneIntervalMs = opts.pruneIntervalMs != null
     ? opts.pruneIntervalMs : Math.max(C.TIME.seconds(30), Math.floor(replayWindowMs / 2));
   var nonceStore     = opts.nonceStore || nonceStoreLib.create({ backend: "memory" });
@@ -446,7 +456,11 @@ function create(opts) {
   // replayed responses with a monotonic counter check.
   function _encodeEnvelope(data, sessionKey, sessionCtx) {
     var ptBuf = Buffer.from(JSON.stringify(data), "utf8");
-    var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey);
+    // Response AAD binds _sid/_ctr so a captured response cannot be
+    // replayed to the client under a rewritten counter.
+    var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey,
+      _responseAad(sessionCtx ? sessionCtx.sid : undefined,
+                   sessionCtx ? sessionCtx.responseCtr : undefined));
     var encrypted = { _ct: ctBuf.toString("base64") };
     if (sessionCtx) {
       encrypted._sid = sessionCtx.sid;
@@ -527,6 +541,10 @@ function create(opts) {
 
     if (typeof ek === "string" && typeof nonce === "string") {
       // ---- Bootstrap path (per-request mode OR first request of session) ----
+      // The window-scoped claim TTL is sufficient HERE because _ts is
+      // AEAD-bound into _ct: a captured bootstrap envelope cannot have
+      // its timestamp rewritten, so past replayWindowMs the staleness
+      // gate above refuses it independently of this claim.
       var nonceHash = bCrypto.sha3Hash(nonce, "hex");
       var expireAt = now + replayWindowMs;
       var freshNonce;
@@ -553,11 +571,18 @@ function create(opts) {
           _emitFailure(req, "shape");
           return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
         }
-        // Bootstrap a new session row keyed by sid.
+        // Bootstrap a new session row keyed by sid. responsesEmitted is
+        // set to 1 (this bootstrap emits one response) BEFORE the store
+        // write so a cluster store — which serialises a copy at set() time
+        // rather than holding a live reference — persists the same count
+        // the next subsequent request reads. Mutating the local object
+        // after set() would leave the stored row at 0, making the next
+        // response counter restart from 1 (a non-monotonic response _ctr
+        // that trips the client's strictly-increasing replay check).
         session = {
           sessionKey:       sessionKey,
           lastReqCtr:       ctr,
-          responsesEmitted: 0,
+          responsesEmitted: 1,
           createdAt:        now,
           lastUsedAt:       now,
           expiresAt:        now + sessionTtlMs,
@@ -574,7 +599,6 @@ function create(opts) {
           requestId: req.requestId || null,
         });
         sessionCtx = { sid: sid, responseCtr: 1 };
-        session.responsesEmitted = 1;
       }
     } else if (keying === "per-session" &&
                typeof sid === "string" && typeof ctr === "number") {
@@ -633,6 +657,47 @@ function create(opts) {
         _emitFailure(req, "counter-replay");
         return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-rejected" });
       }
+      // Atomic replay gate (CWE-367). The monotonic counter check above is
+      // an ordering fast-path only: on a clustered session store, get(sid)
+      // returns a fresh deserialised copy per call, so two concurrent
+      // requests carrying the SAME valid ctr both observe the same
+      // lastReqCtr and both pass — double-execution replay. Claiming the
+      // (sid, ctr) tuple through the same atomic nonceStore the bootstrap
+      // path uses closes the window: exactly one concurrent request wins the
+      // insert; the loser is refused with the counter-replay shape. The
+      // "ctr:" prefix keeps this keyspace disjoint from the bootstrap
+      // nonceHash keyspace (a sha3 hex digest never starts with "ctr:").
+      // The claim must outlive the staleness window, not just span it:
+      // the post-handler sessionStore.set below is best-effort, so a
+      // failed write leaves lastReqCtr stale in the store, and _ts is
+      // plaintext envelope metadata (not bound into the AEAD) — were the
+      // claim to expire after replayWindowMs, the same captured
+      // (sid, ctr, _ct) could be replayed later with a fresh _ts, pass
+      // the stale monotonic check, re-claim the expired tuple, and
+      // execute twice. Claiming until session.expiresAt (the session is
+      // non-expired here, so that bound is in the future) keeps the
+      // tuple burned for as long as the session can accept requests;
+      // outstanding claims per session are bounded by
+      // sessionMaxResponses, and the memory nonce store fails closed at
+      // capacity.
+      var ctrKey = "ctr:" + sid + ":" + ctr;
+      var ctrFresh;
+      try { ctrFresh = await nonceStore.checkAndInsert(ctrKey, session.expiresAt); }
+      catch (_e) {
+        _emitFailure(req, "nonce-store-error");
+        return _writeRejection(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "nonce-store-unavailable" });
+      }
+      if (!ctrFresh) {
+        _emitObs("apiEncrypt.session.replay_rejected", 1, { lane: "atomic" });
+        _emitSessionAudit("apiEncrypt.session.replay_rejected", {
+          outcome: "denied",
+          actor: requestHelpers.extractActorContext(req),
+          metadata: { sid: sid, receivedCtr: ctr, lane: "atomic" },
+          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.
@@ -660,11 +725,15 @@ function create(opts) {
       return _writeRejection(res, HTTP_STATUS.BAD_REQUEST, { error: "encrypted-payload-required" });
     }
 
-    // Decrypt _ct → cleartext payload bytes → JSON object.
+    // Decrypt _ct → cleartext payload bytes → JSON object. The request
+    // AAD authenticates the plaintext envelope fields exactly as the
+    // client bound them — a rewritten _ts/_nonce/_sid/_ctr fails the
+    // AEAD tag here, so the staleness gate above operates on a
+    // timestamp the sender cannot forge after capture.
     var clearObj;
     try {
       var ctBuf = Buffer.from(ct, "base64");
-      var ptBuf = bCrypto.decryptPacked(ctBuf, sessionKey);
+      var ptBuf = bCrypto.decryptPacked(ctBuf, sessionKey, _requestAad(ts, nonce, sid, ctr));
       clearObj = safeJson.parse(ptBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
     } catch (_e) {
       _emitFailure(req, "tag");
@@ -740,6 +809,8 @@ function client(opts) {
       "apiEncrypt.client: pubkey.publicKey + ecPublicKey must be PEM strings", 500);
   }
   var pubkey = opts.pubkey;
+  validateOpts.optionalPositiveInt(opts.maxDecryptedBytes,
+    "apiEncrypt.client: maxDecryptedBytes", ApiEncryptError, "CLIENT_BAD_OPT");
   var maxDecryptedBytes = opts.maxDecryptedBytes != null
     ? opts.maxDecryptedBytes
     : C.BYTES.mib(4);
@@ -785,9 +856,23 @@ function client(opts) {
         "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 = bCrypto.decryptPacked(resCtBuf, perSessionKey);
+    // Response AAD authenticates _sid/_ctr — the monotonic counter
+    // check above reads plaintext fields, so without this binding a
+    // captured response could be replayed under a bumped _ctr.
+    var resPtBuf;
+    try {
+      resPtBuf = bCrypto.decryptPacked(resCtBuf, perSessionKey,
+        _responseAad(responseBody._sid, responseBody._ctr));
+    } catch (_e) {
+      throw _err("CLIENT_RESPONSE_TAMPERED",
+        "apiEncrypt.client: response failed authenticated decryption (ciphertext or envelope metadata tampered)");
+    }
+    // Advance the counter only AFTER authenticated decryption — were it
+    // committed before, a forged high _ctr (which fails the AEAD above)
+    // would poison the monotonic check and refuse every subsequent
+    // genuine response for the rest of the session.
+    perSessionLastResCtr = responseBody._ctr;
     return safeJson.parse(resPtBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
   }
 
@@ -795,14 +880,18 @@ function client(opts) {
     if (payload === undefined) payload = null;
     if (!perSessionKey) _resetSession();
     var ts = Date.now();
-    var ptBuf = Buffer.from(JSON.stringify(payload), "utf8");
-    var ctBuf = bCrypto.encryptPacked(ptBuf, perSessionKey);
     perSessionReqCtr += 1;
+    var ptBuf = Buffer.from(JSON.stringify(payload), "utf8");
+    var ctBuf;
     var body;
     if (perSessionReqCtr === 1) {
       // Bootstrap envelope — full _ek + _nonce; server stores sid → sessionKey.
+      // The plaintext metadata is AEAD-bound so a captured envelope
+      // cannot be replayed under a rewritten _ts/_nonce/_sid/_ctr.
       var ek = bCrypto.encrypt(perSessionKey.toString("base64"), pubkey);
       var nonce = bCrypto.generateBytes(REQUEST_NONCE_BYTES).toString("hex");
+      ctBuf = bCrypto.encryptPacked(ptBuf, perSessionKey,
+        _requestAad(ts, nonce, perSessionSid, perSessionReqCtr));
       body = {
         _ek:    ek,
         _ct:    ctBuf.toString("base64"),
@@ -813,6 +902,8 @@ function client(opts) {
       };
     } else {
       // Subsequent — sid + ctr only. KEM material amortized across the session.
+      ctBuf = bCrypto.encryptPacked(ptBuf, perSessionKey,
+        _requestAad(ts, undefined, perSessionSid, perSessionReqCtr));
       body = {
         _ct:    ctBuf.toString("base64"),
         _ts:    ts,
@@ -827,10 +918,13 @@ function client(opts) {
     if (payload === undefined) payload = null;
     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 = bCrypto.encryptPacked(ptBuf, sessionKey);
     var requestNonce = bCrypto.generateBytes(REQUEST_NONCE_BYTES).toString("hex");
     var ts = Date.now();
+    var ptBuf = Buffer.from(JSON.stringify(payload), "utf8");
+    // AEAD-bind _ts/_nonce so a captured per-request envelope cannot
+    // be replayed past the staleness window with a rewritten _ts.
+    var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey,
+      _requestAad(ts, requestNonce, undefined, undefined));
     return {
       body: {
         _ek:    ek,
@@ -845,7 +939,14 @@ function client(opts) {
             "apiEncrypt.client: response missing _ct field");
         }
         var resCtBuf = Buffer.from(responseBody._ct, "base64");
-        var resPtBuf = bCrypto.decryptPacked(resCtBuf, sessionKey);
+        var resPtBuf;
+        try {
+          resPtBuf = bCrypto.decryptPacked(resCtBuf, sessionKey,
+            _responseAad(undefined, undefined));
+        } catch (_e) {
+          throw _err("CLIENT_RESPONSE_TAMPERED",
+            "apiEncrypt.client: response failed authenticated decryption (ciphertext or envelope metadata tampered)");
+        }
         return safeJson.parse(resPtBuf.toString("utf8"), { maxBytes: maxDecryptedBytes });
       },
     };
@@ -865,6 +966,30 @@ function client(opts) {
   };
 }
 
+// AEAD associated-data builders — bind the envelope's PLAINTEXT
+// metadata into the ciphertext so a captured envelope cannot be
+// replayed with rewritten fields. `_ts` drives the staleness gate,
+// `_nonce` the bootstrap replay claim, `_sid`/`_ctr` the session
+// replay gates on requests and the client's monotonic counter check
+// on responses; none are confidential, but every one is
+// integrity-critical — rode plaintext, an attacker who captured an
+// envelope could refresh `_ts` past the staleness window or replay a
+// response under a bumped `_ctr`. Both halves of the protocol
+// (middleware + client) live in this module and MUST build
+// byte-identical strings; absent fields encode as the empty string so
+// the per-request and per-session shapes stay unambiguous.
+function _requestAad(ts, nonce, sid, ctr) {
+  return "blamejs-apienc/req/1|ts=" + String(ts) +
+         "|nonce=" + (typeof nonce === "string" ? nonce : "") +
+         "|sid=" + (typeof sid === "string" ? sid : "") +
+         "|ctr=" + (typeof ctr === "number" ? String(ctr) : "");
+}
+
+function _responseAad(sid, ctr) {
+  return "blamejs-apienc/res/1|sid=" + (typeof sid === "string" ? sid : "") +
+         "|ctr=" + (typeof ctr === "number" ? String(ctr) : "");
+}
+
 // _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`)
@@ -914,6 +1039,8 @@ function httpClientEncrypted(opts) {
     throw _err("CLIENT_INVALID_PUBKEY",
       "httpClient.encrypted: opts.pubkey is required (the callee's bootstrap doc)", 500);
   }
+  validateOpts.optionalPositiveInt(opts.maxDecryptedBytes,
+    "httpClient.encrypted: maxDecryptedBytes", ApiEncryptError, "CLIENT_BAD_OPT");
   var maxDecryptedBytes = opts.maxDecryptedBytes != null
     ? opts.maxDecryptedBytes
     : C.BYTES.mib(4);

package/lib/middleware/asyncapi-serve.js

@@ -173,6 +173,9 @@ function create(opts) {
       if (allowOriginHeader !== "*") headers["Vary"] = "Origin";
     }
     res.writeHead(200, headers);                                                     // HTTP 200
+    // HEAD carries the GET headers (incl. Content-Length) with no body
+    // (RFC 9110 §9.3.2).
+    if ((req.method || "GET").toUpperCase() === "HEAD") { res.end(); return; }
     res.end(body);
   }
 

package/lib/middleware/csp-report.js

@@ -135,8 +135,10 @@ function create(opts) {
       typeof opts.onReject !== "function") {
     throw new TypeError("middleware.cspReport: opts.onReject must be a function");
   }
-  var maxBytes = (typeof opts.maxBytes === "number" && isFinite(opts.maxBytes) && opts.maxBytes > 0)
-    ? opts.maxBytes : DEFAULT_MAX_BYTES;
+  validateOpts.optionalPositiveInt(opts.maxBytes, "middleware.cspReport: maxBytes");
+  var maxBytes = (opts.maxBytes === undefined || opts.maxBytes === null)
+    ? DEFAULT_MAX_BYTES : opts.maxBytes;
+  var auditOn  = opts.audit !== false;
   var onReport = (typeof opts.onReport === "function") ? opts.onReport : null;
   var onReject = (typeof opts.onReject === "function") ? opts.onReject : null;
 
@@ -176,13 +178,15 @@ function create(opts) {
     for (var i = 0; i < reports.length; i++) {
       var normalized = _normalizeOne(reports[i]);
       if (!normalized) continue;
-      try {
-        audit().safeEmit({
-          action:  "csp.violation",
-          outcome: "failure",
-          metadata: Object.assign({ type: normalized.type, url: normalized.url }, normalized.body),
-        });
-      } catch (_e) { /* audit best-effort */ }
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "csp.violation",
+            outcome: "failure",
+            metadata: Object.assign({ type: normalized.type, url: normalized.url }, normalized.body),
+          });
+        } catch (_e) { /* audit best-effort */ }
+      }
       if (onReport) {
         try { onReport(normalized); } catch (_e) { /* hook best-effort */ }
       }

package/lib/middleware/openapi-serve.js

@@ -179,6 +179,9 @@ function create(opts) {
       if (allowOriginHeader !== "*") headers["Vary"] = "Origin";
     }
     res.writeHead(200, headers);                                                    // HTTP 200
+    // HEAD carries the GET headers (incl. Content-Length) with no body
+    // (RFC 9110 §9.3.2).
+    if ((req.method || "GET").toUpperCase() === "HEAD") { res.end(); return; }
     res.end(body);
   }