@blamejs/core 0.14.14 → 0.14.17

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.14.x
 
+- v0.14.17 (2026-05-31) — **In-session API-encrypt errors stay confidential, and the encrypted client can read them.** When b.middleware.apiEncrypt is active, a normal response is sealed in the { _ct } envelope, but a terminal error that bypassed res.json (an error page, a validation refusal, an RFC 9457 problem+json document, a deny-middleware body) shipped in plaintext on the otherwise-encrypted channel, and the b.httpClient.encrypted client threw on the response shape because it tried to decrypt every reply. This release makes errors symmetric: those four sinks now seal their body in the same envelope a success uses whenever a session is active (via a new req.apiEncryptEncode the middleware installs after a successful decrypt), and the client gains a responseMode: "passthrough" that reads a non-2xx — decrypting an in-session error and returning a plaintext one verbatim — instead of throwing. Errors raised before a session exists (a Bearer 401, a handshake rejection, a replay refusal) deliberately stay plaintext and human-readable. Two adjacent streaming fixes ride along: a streamed (responseMode "stream") non-2xx now keeps a bounded prefix of the error body on the thrown error instead of draining it, and an SSE channel closed by a transport fault audits as a failure with a reason rather than looking like a clean operator close. **Added:** *`b.httpClient.encrypted` gains `responseMode: "passthrough"`* — The encrypted client defaults to `responseMode: "reject"` (a non-2xx rejects, exactly as before). Set `responseMode: "passthrough"` at create time, or per request, to resolve a non-2xx instead: the result is `{ statusCode, headers, body, ok }`, where `body` is the decrypted object when the reply carries an encrypted `_ct` envelope (an in-session error) and the parsed plaintext otherwise (a pre-session error such as a Bearer 401 or a proxy 502). The additive `ok` boolean (status 200–299) is present on every result. This lets a client read an error's status and detail instead of failing on the response shape. · *`req.apiEncryptEncode` — the in-session error encoder* — `b.middleware.apiEncrypt` installs `req.apiEncryptEncode(obj)` after it successfully decrypts a request body. It returns the same `{ _ct }` (plus `_sid` / `_ctr` in per-session mode) envelope a normal response uses, so a terminal handler that writes its body directly (bypassing the wrapped `res.json`) can keep an error confidential on the encrypted channel. It is present only after a valid decrypt, so every pre-session path has no encoder and its errors stay plaintext. **Changed:** *In-session terminal errors are sealed in the encrypted envelope* — The error page (JSON branch), the router's schema-validation refusal, `b.problemDetails.respond` (now accepting an optional `req`), and the access-deny middleware now seal their error body via `req.apiEncryptEncode` when a session is active — so an in-session error no longer ships as plaintext while the surrounding traffic is encrypted. A sealed problem+json is labelled `application/json` (the envelope), not `application/problem+json`. With no active session (or if encoding fails) the body stays plaintext and readable, unchanged. · *Streamed non-2xx responses preserve a bounded error-body prefix* — `b.httpClient.request({ responseMode: "stream" })` (and `b.httpClient.downloadStream`, which composes it) previously drained and discarded the body of a `>= 400` response. The rejection is unchanged, but the thrown error now carries a bounded (16 KiB) prefix of the body on `err.body`, so a caller can read the problem+json / error detail. The prefix is collected through `b.safeBuffer.boundedChunkCollector`, so a hostile oversized error body can't accumulate unbounded. · *SSE transport-fault close audits as a failure* — An SSE channel closed by a transport fault (a stream `error`, a failed heartbeat write) now emits its `sse.channel_closed` audit event with `outcome: "failure"` and a `reason`, instead of the `"success"` outcome an intentional `channel.close()` records — so an operator's evidence stream can tell a dropped connection from a clean shutdown. **Security:** *Error bodies no longer leak in plaintext on an encrypted channel* — Before this release, a request that established an apiEncrypt session but then failed (validation error, access denial, server error rendered through the error page or problem-details) returned its error body in plaintext, even though every successful response on the same channel was encrypted — exposing error detail (paths, field names, refusal reasons) to a network observer. In-session errors are now encrypted symmetrically with successes; pre-session errors, which a client must be able to read to recover, remain plaintext by design. **Migration:** *Opt into reading non-2xx encrypted errors* — No change is required for existing callers — `b.httpClient.encrypted` still defaults to `responseMode: "reject"` (throw on non-2xx). To read an error's status and decrypted detail, create the client with `responseMode: "passthrough"` (or pass it per request) and branch on the returned `ok` / `statusCode`. The new `ok` field is additive and does not affect existing `{ statusCode, headers, body }` consumers.
+
+- v0.14.16 (2026-05-31) — **Connection entry-point ports are validated at config time.** Six connection entry points previously read opts.port with a bare `|| <default>` fallback, silently coercing a string, negative, NaN, or out-of-range port instead of catching the operator's typo. A new b.validateOpts.optionalPort enforces the RFC 6335 §6 wire-valid range and is wired into b.mail.smtpTransport, b.ntpCheck.querySingle, b.networkDns.useDnsOverTls, b.networkNts (KE handshake / query / facade), b.redisClient.create, and createApp().listen — each now throws at construction with a clear message naming the bad value. The app.listen / createApp bind site opts into allowZero so port 0 (the legitimate ephemeral-bind sentinel) still works; the five outbound-connect sites require [1,65535]. **Added:** *`b.validateOpts.optionalPort`* — A config-time port validator: `optionalPort(value, label, errorClass, code, opts?)` returns an omitted (`undefined` / `null`) port unchanged, and otherwise requires an integer in the RFC 6335 §6 wire-valid range [1,65535] — rejecting a string, negative, NaN, Infinity, fractional, or out-of-range value. Pass `{ allowZero: true }` for a listen-bind site where port 0 is the OS ephemeral-bind sentinel. The thrown message reports the offending shape (so `Infinity` / `"443"` stay visible), and routes a caller-supplied typed framework error (or a plain Error when none is given), matching the existing `optionalPositiveFinite` family. **Changed:** *Connection entry points reject a malformed port at construction* — `b.mail.smtpTransport`, `b.ntpCheck.querySingle`, `b.networkDns.useDnsOverTls`, `b.networkNts.performKeHandshake` / `query` / `querySingle`, `b.redisClient.create`, and `createApp().listen` (plus the `createApp` constructor's default port) now validate `opts.port` and throw synchronously on a non-integer / out-of-range value rather than coercing it through `||` to a default. This is a behavior change for a caller that was passing a non-canonical port (e.g. the string `"587"` or a NaN) and relying on the silent fallback — pass an integer in [1,65535] instead (or `0` for an ephemeral `createApp().listen` bind). `b.ntpCheck` gains a typed `NtpCheckError` for this (it had no error class before). **Detectors:** *Connection entry points must compose the port validator* — A new check flags a lib connection entry point that reads `opts.port` / `opts.kePort` / `opts.ntpPort` with a `|| <default>` fallback without composing `b.validateOpts.optionalPort` (or the equivalent `numericBounds.isPositiveFiniteInt` + 65535 cap), so an unvalidated port read can't slip back in. **Migration:** *Pass an integer port to connection primitives* — If you were passing a non-integer or out-of-range `opts.port` to a mail / NTP / NTS / DNS-over-TLS / Redis transport or to `createApp().listen` and relying on the silent `|| default` fallback, that now throws at construction. Pass an integer in [1,65535]; for an ephemeral `createApp().listen` bind, pass `0` (still accepted).
+
 - v0.14.14 (2026-05-31) — **Recognized consent purposes with lawful-basis gating, and a new b.privacy namespace for annual EdTech vendor-review attestations.** Closes the student-data gap where an educational-only consent purpose and an annual third-party vendor-review report were described but never implemented. b.consent gains a recognized-purpose vocabulary: a purpose value matching a recognized key carries lawful-basis constraints that grant() enforces, and the named educational-only purpose (FERPA's school-official exception and California's SOPIPA) refuses a legitimate_interests lawful basis. The new b.privacy namespace ships vendorReview(), a builder for the dated, clause-by-clause annual EdTech third-party / processor review FERPA and SOPIPA expect a school or district to keep — it computes whether every required clause (no targeted advertising, no commercial profiling, no sale of student data, deletion on request, school-official designation, and so on) is attested, names the gaps, and stamps a 365-day re-review clock. Free-form consent purposes keep working unchanged, so the vocabulary is opt-in and additive. **Added:** *`b.consent` recognized-purpose vocabulary + lawful-basis gating* — `b.consent.recognizedPurpose(name)` looks up a recognized purpose and `b.consent.listPurposes()` enumerates them. When a `grant({ purpose })` value matches a recognized key, `grant()` enforces that purpose's lawful-basis constraints; the `educational-only` purpose forbids a `legitimate_interests` basis (FERPA 34 CFR 99.31(a)(1) school-official exception; California SOPIPA Cal. B&P 22584; FTC school-authorized COPPA consent 16 CFR 312.5(c)(10)) and marks the data commercial-use-prohibited. The commercial-use prohibition is an operator trust-boundary obligation — `isGranted()` does not re-derive it. Any purpose value NOT in the vocabulary stays free-form and unconstrained, so existing callers are unaffected; the hash-chain column set is unchanged, so `b.consent.verify()` over existing rows is unaffected. · *`b.privacy.vendorReview` — annual EdTech vendor-review attestation* — A new `b.privacy` namespace whose `vendorReview(opts)` builds the dated third-party / processor review a FERPA school-official arrangement and California SOPIPA expect for every vendor that touches student data. The operator supplies a boolean attestation per clause (educational-purpose-only, no-targeted-advertising, no-commercial-profiling, no-sale-of-student-data, security-safeguards, deletion-on-request, sub-processor-currency, breach-notification, school-official-designation, directory-information-handling); `vendorReview` validates the shape, computes whether every required clause is attested (`attested`) and which are not (`gaps`), and stamps `reviewedAt` plus a 365-day `nextReviewDueAt` re-review clock. `b.privacy.listVendorReviewClauses()` returns the clause set with citations. Operator-feeds-metadata: the frozen report is not framework-persisted — compose it into your retention / audit / export sink. A best-effort `privacy.vendor_review.recorded` audit event fires when an audit sink is wired. **Detectors:** *A gated consent purpose must go through `b.consent`* — A new check flags any lib code that mints a consent row with a hardcoded `educational-only` purpose literal without composing the recognized-purpose vocabulary — which would record the value while never enforcing its FERPA / SOPIPA lawful-basis constraint.
 
 - v0.14.13 (2026-05-31) — **Close advertised-but-missing surface: SRS1 chained forwarding, DCQL array-wildcard claim paths, and in-memory safe-archive extraction.** Three primitives advertised a capability in their documentation or card but refused or omitted it at runtime; this release implements each. b.mail.srs gains srs1Rewrite for the SRS1 double-forward (and multi-hop) case — previously the @intro described SRS1 and create() threw, pointing at a function that was never exported. b.safeArchive gains extractToMemory, the in-memory counterpart to extract for read-only / serverless filesystems — previously the card advertised in-memory extraction but the orchestrator required a destination directory. b.auth.oid4vp.matchDcql now honours a null claims-path segment as the array wildcard the OpenID4VP DCQL spec defines, rather than refusing it as unsupported while the card advertised DCQL. A stale version-pinned wording in a safe-archive error message is corrected. Every change is additive or message-only — no existing caller changes behaviour. **Added:** *`b.mail.srs` SRS1 chained forwarding — `srs1Rewrite`* — `b.mail.srs.create(...)` now returns `srs1Rewrite` alongside `rewrite` / `reverse`. `srs1Rewrite(srsAddress)` chains an already-SRS0 (or SRS1) envelope-from for a further forwarding hop: it keeps the original SRS0 body verbatim, prepends the SRS0 originator's domain, and binds the pair with this forwarder's own HMAC-SHA-256 tag — no new timestamp, no repeated original local-part — emitting `SRS1=tag=originator==<SRS0-body>@thisForwarder`. `reverse()` now detects an SRS1 address, verifies this hop's tag and forwarder-domain binding, and unwraps exactly one hop back to the originator's SRS0 so a multi-hop bounce routes straight to the forwarder that can recover the original sender. Typed failure modes: `srs/not-srs0` (input not SRS-encoded), `srs/malformed` (missing the `==` separator), `srs/bad-tag` (tampered), `srs/too-long` (chain exceeds the RFC 5321 256-octet path limit). Implements the Sender Rewriting Scheme SRS1 wire format; the second-hop SPF rationale is RFC 7208 §2.4. · *`b.safeArchive.extractToMemory` — in-memory safe extraction* — An async generator counterpart to `b.safeArchive.extract` for read-only / serverless filesystems: it resolves the source, sniffs the format, auto-unwraps recipient (`BAWRP`) / passphrase (`BAWPP`) envelopes, and dispatches to the zip / tar / tar.gz reader's in-memory `extractEntries()`, yielding `{ name, bytes, size }` per regular-file entry without ever writing to disk. It takes no `destination`. Every defense the disk path runs applies unchanged: the zip-bomb caps (entry-count / per-entry / total / expansion-ratio), the `b.guardArchive` metadata cascade (Zip-Slip / path-traversal / symlink-escape / encrypted-entry refusal, CVE-2025-3445 class), and the entry-type policy. The disk-only realpath-agreement check (CVE-2025-4517 PATH_MAX TOCTOU defense) is intentionally absent — there is no extraction root — so the archive-level name refusals carry containment. Trusted-stream sources are refused upfront (the adversarial-safe central-directory walk needs random access). gzip magic per RFC 1952 §2.3.1. **Fixed:** *OID4VP DCQL `null` claim-path segment now resolves the array wildcard* — `b.auth.oid4vp.matchDcql` previously threw `auth-oid4vp/null-path-segment-not-supported` for a `null` claims-path segment while the namespace card advertised DCQL — under-disclosing a legitimate presentation (CWE-863). Per OpenID4VP 1.0 §7.1.1 a `null` segment selects all elements of the array at that depth; the matcher now recurses over array elements with existence semantics (with DCQL value-matching applied to any selected leaf), composed to arbitrary depth. A `null` segment on a non-array node — like an integer index into a non-array, or a string key into an array — is a clean non-match, not a thrown error, because the matcher walks holder credential data rather than operator config. String and integer claim paths are byte-identical to before; only queries that previously threw now succeed or fail cleanly. · *safe-archive trusted-stream refusal message no longer cites a stale version* — The thrown `safe-archive/trusted-stream-unsupported` message and its comment claimed trusted-stream extraction was "deferred to v0.12.8 / when the v0.12.8 sequential extract path lands." That path shipped long ago — `b.archive.read.zip.fromTrustedStream` and the tar sequential mode exist — so the message now points at them as present capabilities and drops the version-pinned wording. The error code is unchanged. **Detectors:** *A primitive may not advertise a capability and then throw an unimplemented stub* — A new check flags a bare `not yet supported` / `operator demand TBD` / `not supported in v1` refusal in a lib throw string (comments excluded). A defer is only complete with a written re-open condition; the SRS1 and DCQL stubs that this release implements both carried this bare-defer shape, and the detector keeps it from re-entering. · *DCQL `null` path segments must recurse, never refuse* — A new check flags the `null path segment not supported` refusal shape in `lib/auth/oid4vp.js`, so the spec-mandated array wildcard cannot be re-stubbed. · *`extractToMemory` must stay disk-free* — A new check flags any `writeFileSync` / `renameSync` / `mkdirSync` / `createWriteStream` inside the `extractToMemory` generator body, so the read-only / serverless contract cannot regress into a disk write.

package/lib/app.js

@@ -93,6 +93,7 @@ var nodeFs = require("node:fs");
 var nodePath = require("node:path");
 var appShutdown = require("./app-shutdown");
 var audit = require("./audit");
+var validateOpts = require("./validate-opts");
 var C = require("./constants");
 var cluster = require("./cluster");
 var db = require("./db");
@@ -139,6 +140,9 @@ async function createApp(opts) {
   if (!opts.dataDir || typeof opts.dataDir !== "string") {
     throw new Error("createApp: opts.dataDir is required");
   }
+  // Constructor-time default port (used by listen() when listenOpts.port is
+  // omitted); allowZero for the ephemeral-bind sentinel.
+  validateOpts.optionalPort(opts.port, "createApp: opts.port", undefined, undefined, { allowZero: true });
   var dataDir = nodePath.resolve(opts.dataDir);
   if (!nodeFs.existsSync(dataDir)) {
     nodeFs.mkdirSync(dataDir, { recursive: true });
@@ -279,6 +283,10 @@ async function createApp(opts) {
 
   function listen(listenOpts) {
     listenOpts = listenOpts || {};
+    // Port 0 is the legitimate ephemeral-bind sentinel for a listen socket
+    // (RFC 6335 §6 / POSIX bind), so allowZero — but a non-integer / NaN /
+    // out-of-range port is an operator typo that must fail at boot.
+    validateOpts.optionalPort(listenOpts.port, "createApp.listen: listenOpts.port", undefined, undefined, { allowZero: true });
     var port = (listenOpts.port !== undefined) ? listenOpts.port
              : (opts.port !== undefined) ? opts.port
              : 0;

package/lib/error-page.js

@@ -394,8 +394,12 @@ function create(opts) {
       if (mode === "dev" && info.stack && showStack && info.status >= 500) {
         errorObj.stack = info.stack;
       }
+      var errorBody = { error: errorObj };
+      if (req && typeof req.apiEncryptEncode === "function") {
+        try { errorBody = req.apiEncryptEncode(errorBody); } catch (_e) { errorBody = { error: errorObj }; }
+      }
       _writeResponse(res, info.status, "application/json; charset=utf-8",
-        JSON.stringify({ error: errorObj }));
+        JSON.stringify(errorBody));
       return;
     }
 

package/lib/http-client.js

@@ -378,6 +378,39 @@ function _isPermanentStatus(statusCode) {
   return false;
 }
 
+// Reject a streamed non-2xx response, preserving a bounded prefix of the
+// error body (problem+json / encrypted error) on err.body instead of
+// silently draining it.
+function _rejectStreamHttpError(stream, errorClass, statusCode, statusMessage, reject) {
+  var cap = C.BYTES.kib(16);
+  var collector = safeBuffer.boundedChunkCollector({ maxBytes: cap });
+  var done = false;
+  function finish() {
+    if (done) return;
+    done = true;
+    var e = _makeError(errorClass, "HTTP_ERROR",
+      "HTTP " + statusCode + (statusMessage ? " " + statusMessage : ""),
+      _isPermanentStatus(statusCode), statusCode);
+    e.body = collector.result();
+    reject(e);
+  }
+  // Collect at most `cap` bytes of the error body, slicing each chunk to the
+  // remaining room so the bounded collector never overflows. As soon as the
+  // prefix is full, reject + destroy the stream — don't leave the request
+  // promise pending while a large / slow error body drains to its close.
+  stream.on("data", function (c) {
+    if (done) return;
+    var room = cap - collector.bytesCollected();
+    if (room > 0) collector.push(c.length > room ? c.subarray(0, room) : c);
+    if (collector.bytesCollected() >= cap) {
+      if (typeof stream.destroy === "function") stream.destroy();
+      finish();
+    }
+  });
+  stream.on("end", finish);
+  stream.on("error", finish);
+}
+
 // h2 sends headers as lowercased keys plus :method / :path / :scheme /
 // :authority pseudo-headers. Convert from h1-shaped headers.
 function _toH2Headers(method, u, headers) {
@@ -1421,10 +1454,8 @@ function _requestH1(transport, u, opts) {
 
       if (responseMode === "stream") {
         if (res.statusCode >= 400 && responseMode !== "always-resolve") {
-          res.resume();
-          return _reject(_makeError(opts.errorClass, "HTTP_ERROR",
-            "HTTP " + res.statusCode + " " + (res.statusMessage || ""),
-            _isPermanentStatus(res.statusCode), res.statusCode));
+          _rejectStreamHttpError(res, opts.errorClass, res.statusCode, res.statusMessage || "", _reject);
+          return;
         }
         if (onDownloadProgress || onChunk) {
           // Wrap the stream so chunks emit progress + onChunk to the
@@ -1639,9 +1670,8 @@ function _requestH2(transport, u, opts) {
 
       if (responseMode === "stream") {
         if (statusCode >= 400 && responseMode !== "always-resolve") {
-          stream.resume();
-          return _reject(_makeError(opts.errorClass, "HTTP_ERROR",
-            "HTTP " + statusCode, _isPermanentStatus(statusCode), statusCode));
+          _rejectStreamHttpError(stream, opts.errorClass, statusCode, "", _reject);
+          return;
         }
         if (onChunkH2) {
           var passthroughH2 = new nodeStream.PassThrough();

package/lib/mail.js

@@ -767,6 +767,7 @@ function smtpTransport(opts) {
       "dkimSigner must be an object with a .sign(rfc822) method " +
       "(see b.mail.dkim.create)", true);
   }
+  validateOpts.optionalPort(opts.port, "smtp transport: opts.port", MailError, "mail/smtp-misconfigured");
   var port = opts.port || 587;
   var useImplicitTLS = port === 465 || opts.implicitTls === true;
   var rejectUnauthorized = opts.rejectUnauthorized !== false;

package/lib/middleware/api-encrypt.js

@@ -440,6 +440,21 @@ function create(opts) {
     });
   }
 
+  // _encodeEnvelope — build the wire envelope for a single response
+  // body. In per-request mode it 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 _encodeEnvelope(data, sessionKey, sessionCtx) {
+    var ptBuf = Buffer.from(JSON.stringify(data), "utf8");
+    var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey);
+    var encrypted = { _ct: ctBuf.toString("base64") };
+    if (sessionCtx) {
+      encrypted._sid = sessionCtx.sid;
+      encrypted._ctr = sessionCtx.responseCtr;
+    }
+    return encrypted;
+  }
+
   // _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
@@ -448,13 +463,7 @@ function create(opts) {
     var origJson = res.json;
     res.json = function (data) {
       try {
-        var ptBuf = Buffer.from(JSON.stringify(data), "utf8");
-        var ctBuf = bCrypto.encryptPacked(ptBuf, sessionKey);
-        var encrypted = { _ct: ctBuf.toString("base64") };
-        if (sessionCtx) {
-          encrypted._sid = sessionCtx.sid;
-          encrypted._ctr = sessionCtx.responseCtr;
-        }
+        var encrypted = _encodeEnvelope(data, sessionKey, sessionCtx);
         if (typeof origJson === "function") {
           return origJson.call(res, encrypted);
         }
@@ -669,6 +678,10 @@ function create(opts) {
     req.apiEncryptSessionKey = sessionKey;
     if (sessionCtx) req.apiEncryptSession = { sid: sessionCtx.sid };
 
+    // Error-path encoder for terminal writers that bypass res.json; set
+    // only here (after a valid decrypt) so pre-session errors stay plaintext.
+    req.apiEncryptEncode = function (data) { return _encodeEnvelope(data, sessionKey, sessionCtx); };
+
     _wrapResJson(res, sessionKey, sessionCtx);
     _maybePrune();
 
@@ -895,6 +908,7 @@ function httpClientEncrypted(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "pubkey", "baseUrl", "headers", "method", "maxDecryptedBytes", "keying",
+    "responseMode",
   ], "middleware.apiEncrypt.httpClient");
   if (!opts.pubkey) {
     throw _err("CLIENT_INVALID_PUBKEY",
@@ -904,6 +918,16 @@ function httpClientEncrypted(opts) {
     ? opts.maxDecryptedBytes
     : C.BYTES.mib(4);
   var keying = opts.keying != null ? opts.keying : "per-request";
+  // responseMode controls how a non-2xx / non-encrypted response is
+  // handled: "reject" (default) keeps the core throwing on non-2xx and
+  // requires an encrypted `_ct` body; "passthrough" resolves any status
+  // and returns a plaintext body verbatim when it carries no `_ct`.
+  var responseModeDefault = opts.responseMode != null ? opts.responseMode : "reject";
+  if (responseModeDefault !== "reject" && responseModeDefault !== "passthrough") {
+    throw _err("CLIENT_BAD_OPT",
+      "httpClient.encrypted: responseMode must be 'reject' (default) or 'passthrough', got " +
+      JSON.stringify(opts.responseMode), 500);
+  }
   var clientCtx = client({
     pubkey: opts.pubkey,
     maxDecryptedBytes: maxDecryptedBytes,
@@ -929,6 +953,12 @@ function httpClientEncrypted(opts) {
   async function request(reqOpts) {
     reqOpts = reqOpts || {};
     var url = _resolveUrl(reqOpts);
+    var mode = (reqOpts && reqOpts.responseMode != null) ? reqOpts.responseMode : responseModeDefault;
+    if (mode !== "reject" && mode !== "passthrough") {
+      throw _err("CLIENT_BAD_OPT",
+        "httpClient.encrypted.request: responseMode must be 'reject' (default) or 'passthrough', got " +
+        JSON.stringify(reqOpts.responseMode), 500);
+    }
     var encrypted = clientCtx.encryptRequest(
       reqOpts.body !== undefined ? reqOpts.body : null
     );
@@ -947,16 +977,24 @@ function httpClientEncrypted(opts) {
     }
 
     var rawBody = Buffer.from(JSON.stringify(encrypted.body), "utf8");
-    var resp = await httpClient().request(Object.assign({
+    var requestArgs = Object.assign({
       url:     url,
       method:  reqOpts.method || defaultMethod,
       headers: headers,
       body:    rawBody,
-    }, passThrough));
+    }, passThrough);
+    // In passthrough mode a non-2xx status resolves instead of throwing,
+    // so the caller can inspect the (possibly plaintext) error body.
+    if (mode === "passthrough") {
+      requestArgs.responseMode = "always-resolve";
+    }
+    var resp = await httpClient().request(requestArgs);
+
+    var ok = resp.statusCode >= 200 && resp.statusCode < 300;
 
     // Empty body → no decryption (e.g. 204 No Content).
     if (!resp.body || resp.body.length === 0) {
-      return { statusCode: resp.statusCode, headers: resp.headers, body: null };
+      return { statusCode: resp.statusCode, headers: resp.headers, body: null, ok: ok };
     }
     var parsed;
     try { parsed = safeJson.parse(resp.body.toString("utf8"), { maxBytes: maxDecryptedBytes }); }
@@ -964,10 +1002,19 @@ function httpClientEncrypted(opts) {
       throw _err("CLIENT_RESPONSE_NOT_JSON",
         "httpClient.encrypted: response body is not valid JSON: " + e.message);
     }
+    // passthrough: decrypt only an encrypted envelope; return a plaintext
+    // body verbatim. reject: always decrypt (throws on a missing _ct).
+    var body;
+    if (mode === "passthrough") {
+      body = (parsed && typeof parsed._ct === "string") ? encrypted.decryptResponse(parsed) : parsed;
+    } else {
+      body = encrypted.decryptResponse(parsed);
+    }
     return {
       statusCode: resp.statusCode,
       headers:    resp.headers,
-      body:       encrypted.decryptResponse(parsed),
+      body:       body,
+      ok:         ok,
     };
   }
 

package/lib/middleware/deny-response.js

@@ -125,13 +125,18 @@ function denyResponse(req, res, ctx) {
         res.setHeader(hk[h], extra[hk[h]]);
       }
     }
-    problemDetails.respond(res, problem);
+    problemDetails.respond(res, problem, req);
     return undefined;
   }
 
   var head = _mergeInto({ "Content-Type": ctx.contentType }, extra);
+  var denyOut = (ctx.body === undefined || ctx.body === null) ? ""
+    : (typeof ctx.body === "string" ? ctx.body : JSON.stringify(ctx.body));
+  if (ctx.body !== undefined && ctx.body !== null && req && typeof req.apiEncryptEncode === "function") {
+    try { denyOut = JSON.stringify(req.apiEncryptEncode(ctx.body)); } catch (_e) { /* plaintext kept */ }
+  }
   res.writeHead(ctx.status, head);
-  res.end((ctx.body === undefined || ctx.body === null) ? "" : ctx.body);
+  res.end(denyOut);
   return undefined;
 }
 

package/lib/network-dns.js

@@ -253,6 +253,7 @@ function useDnsOverTls(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "port", "servername", "ca"], "dns.useDnsOverTls");
   validateOpts.requireNonEmptyString(opts.host, "dns.useDnsOverTls: host", DnsError, "dns/bad-dot-host");
+  validateOpts.optionalPort(opts.port, "dns.useDnsOverTls: opts.port", DnsError, "dns/bad-dot-port");
   if (opts.ca !== undefined && opts.ca !== null &&
       !Buffer.isBuffer(opts.ca) && typeof opts.ca !== "string" && !Array.isArray(opts.ca)) {
     throw new DnsError("dns/bad-dot-ca",

package/lib/network-nts.js

@@ -241,6 +241,7 @@ function performKeHandshake(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "port", "servername", "aead", "ca", "timeoutMs"], "nts.performKeHandshake");
   validateOpts.requireNonEmptyString(opts.host, "nts.performKeHandshake: host", NtsError, "nts/bad-host");
+  validateOpts.optionalPort(opts.port, "nts.performKeHandshake: opts.port", NtsError, "nts/bad-ke-port");
   var timeoutMs = opts.timeoutMs || C.TIME.seconds(10);
   return new Promise(function (resolve, reject) {
     var settled = false;
@@ -408,6 +409,7 @@ function _walkExtensions(msg, startOff) {
 function querySingle(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "port", "aeadId", "c2sKey", "s2cKey", "cookies", "timeoutMs"], "nts.querySingle");
+  validateOpts.optionalPort(opts.port, "nts.querySingle: opts.port", NtsError, "nts/bad-ntp-port");
   if (!Buffer.isBuffer(opts.c2sKey) || opts.c2sKey.length === 0) {
     throw new NtsError("nts/no-c2s-key", "nts.querySingle: c2sKey required (Buffer)");
   }
@@ -542,6 +544,8 @@ function querySingle(opts) {
 async function query(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "kePort", "ntpPort", "aead", "ca", "timeoutMs", "servername"], "nts.query");
+  validateOpts.optionalPort(opts.kePort, "nts.query: opts.kePort", NtsError, "nts/bad-ke-port");
+  validateOpts.optionalPort(opts.ntpPort, "nts.query: opts.ntpPort", NtsError, "nts/bad-ntp-port");
   var ke = await performKeHandshake({
     host:       opts.host,
     port:       opts.kePort,

package/lib/ntp-check.js

@@ -48,10 +48,16 @@ var dgram = require("node:dgram");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
 var observability = lazyRequire(function () { return require("./observability"); });
 
+// Config-time misuse (a bad opts.port) throws a typed, permanent error so an
+// operator catches the typo at boot rather than as a Promise rejection.
+var NtpCheckError = defineClass("NtpCheckError", { alwaysPermanent: true });
+
 // NTP epoch: 1900-01-01. Unix epoch: 1970-01-01. Offset: 70 years incl. 17
 // leap days = 2,208,988,800 seconds.
 var NTP_TO_UNIX_OFFSET_SECONDS = 2208988800;
@@ -166,6 +172,7 @@ function _resetThresholdsForTest() {
  */
 function querySingle(server, opts) {
   opts = opts || {};
+  validateOpts.optionalPort(opts.port, "ntpCheck.querySingle: opts.port", NtpCheckError, "ntp/bad-port");
   var port = opts.port || DEFAULT_PORT;
   var timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
 
@@ -445,6 +452,7 @@ function monitor(opts) {
 
 module.exports = {
   querySingle:               querySingle,
+  NtpCheckError:             NtpCheckError,
   checkDrift:                checkDrift,
   bootCheck:                 bootCheck,
   monitor:                   monitor,

package/lib/problem-details.js

@@ -313,7 +313,7 @@ function fromError(err, opts2) {
 
 /**
  * @primitive b.problemDetails.respond
- * @signature b.problemDetails.respond(res, problem)
+ * @signature b.problemDetails.respond(res, problem, req?)
  * @since     0.8.84
  * @status    stable
  * @related   b.problemDetails.create, b.problemDetails.fromError
@@ -339,7 +339,7 @@ function fromError(err, opts2) {
  *   // res.body:     <JSON-stringified problem>
  *   // res.statusCode: 400
  */
-function respond(res, problem) {
+function respond(res, problem, req) {
   if (!res || typeof res !== "object" || typeof res.setHeader !== "function" ||
       typeof res.end !== "function") {
     throw new ProblemDetailsError("problem-details/bad-res",
@@ -352,8 +352,20 @@ function respond(res, problem) {
   var status = (typeof problem.status === "number" && Number.isInteger(problem.status) &&
                 problem.status >= 100 && problem.status <= 599) ? problem.status : 500;            // HTTP status range + default 500
   var body = JSON.stringify(problem);
+  // Seal the problem body when an encrypted session is active — the
+  // encoder is present only after a request body decrypted, so its
+  // envelope decrypts identically on the client. Pre-session paths
+  // leave req/encoder absent and keep plaintext problem+json. An
+  // encryption failure falls back to plaintext rather than crashing.
+  var contentType = "application/problem+json";
+  if (req && typeof req.apiEncryptEncode === "function") {
+    try {
+      body = JSON.stringify(req.apiEncryptEncode(problem));
+      contentType = "application/json";
+    } catch (_e) { /* keep plaintext problem+json */ }
+  }
   res.statusCode = status;
-  res.setHeader("Content-Type", "application/problem+json");
+  res.setHeader("Content-Type", contentType);
   res.setHeader("Cache-Control", "no-store");
   res.end(body);
 }

package/lib/redis-client.js

@@ -155,9 +155,17 @@ function _frameToValue(frame) {
 function create(opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(opts.url, "redis.create: opts.url", RedisError, "BAD_OPTS");
+  // Validate an operator-supplied opts.port up front for a clear typo
+  // message (e.g. the string "6379" or a negative value).
+  validateOpts.optionalPort(opts.port, "redis.create: opts.port", RedisError, "BAD_OPTS");
   var parsed = _parseRedisUrl(opts.url);
   var host = opts.host || parsed.host;
   var port = opts.port || parsed.port;
+  // Re-validate the RESOLVED port. A url-supplied port (redis://h:0,
+  // redis://h:99999) is not range-checked by _parseRedisUrl, so without
+  // this an outbound connect could inherit a zero / out-of-range port that
+  // the opts.port guard above never sees.
+  validateOpts.optionalPort(port, "redis.create: resolved port (opts.port or url)", RedisError, "BAD_OPTS");
   var useTls = opts.tls !== undefined ? !!opts.tls : parsed.tls;
   var password = opts.password !== undefined ? opts.password : parsed.password;
   var username = opts.username !== undefined ? opts.username : parsed.username;

package/lib/router.js

@@ -112,13 +112,20 @@ function _validateRouteSpec(spec, method, pattern) {
   }
 }
 
-function _writeValidationError(res, where, errors) {
+function _writeValidationError(req, res, where, errors) {
   if (res.writableEnded || res.headersSent) return;
-  var body = JSON.stringify({
+  var payload = {
     error: "validation",
     where: where,
     issues: errors,
-  });
+  };
+  var body = JSON.stringify(payload);
+  // Seal the body when an encrypted session is active; pre-session paths
+  // (Bearer auth, handshake reject, replay refusal) lack the encoder and
+  // stay plaintext. An encryption failure falls back to the plaintext body.
+  if (req && typeof req.apiEncryptEncode === "function") {
+    try { body = JSON.stringify(req.apiEncryptEncode(payload)); } catch (_e) { /* plaintext body kept */ }
+  }
   res.writeHead(HTTP_STATUS.BAD_REQUEST, {
     "Content-Type":   "application/json; charset=utf-8",
     "Content-Length": Buffer.byteLength(body),
@@ -131,17 +138,17 @@ function _makeSchemaValidator(spec) {
   return function schemaValidator(req, res, next) {
     if (spec.params && req.params !== undefined) {
       var pp = spec.params.safeParse(req.params);
-      if (!pp.ok) return _writeValidationError(res, "params", pp.errors);
+      if (!pp.ok) return _writeValidationError(req, res, "params", pp.errors);
       req.params = pp.value;
     }
     if (spec.query && req.query !== undefined) {
       var qq = spec.query.safeParse(req.query);
-      if (!qq.ok) return _writeValidationError(res, "query", qq.errors);
+      if (!qq.ok) return _writeValidationError(req, res, "query", qq.errors);
       req.query = qq.value;
     }
     if (spec.body && req.body !== undefined) {
       var bb = spec.body.safeParse(req.body);
-      if (!bb.ok) return _writeValidationError(res, "body", bb.errors);
+      if (!bb.ok) return _writeValidationError(req, res, "body", bb.errors);
       req.body = bb.value;
     }
     next();

package/lib/sse.js

@@ -287,7 +287,7 @@ function create(req, res, opts) {
     _writeRaw(":" + text + "\n\n");
   }
 
-  function close() {
+  function close(cause) {
     if (closed) return;
     closed = true;
     if (heartbeatTimer) {
@@ -296,10 +296,12 @@ function create(req, res, opts) {
     }
     try { res.end(); } catch (_e) { /* already destroyed */ }
     if (auditOn) {
+      var closeMeta = { lastEventId: lastEventId };
+      if (cause) closeMeta.reason = cause.reason || "fault";
       audit.safeEmit({
         action:   "sse.channel_closed",
-        outcome:  "success",
-        metadata: { lastEventId: lastEventId },
+        outcome:  cause ? "failure" : "success",
+        metadata: closeMeta,
       });
     }
   }
@@ -308,7 +310,7 @@ function create(req, res, opts) {
   // the heartbeat timer.
   if (typeof res.on === "function") {
     res.on("close",  close);
-    res.on("error",  function (_e) { close(); });
+    res.on("error",  function (_e) { close({ reason: "stream-error" }); });
     res.on("finish", function () { closed = true; if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } });
   }
 
@@ -325,7 +327,7 @@ function create(req, res, opts) {
     heartbeatTimer = setInterval(function () {
       if (closed) return;
       try { _writeRaw(":keepalive\n\n"); }
-      catch (_e) { close(); }
+      catch (_e) { close({ reason: "heartbeat-write-failed" }); }
     }, heartbeatMs).unref();
   }
 

package/lib/validate-opts.js

@@ -27,6 +27,8 @@
  * a typed error wrap the call.
  */
 
+var numericBounds = require("./numeric-bounds");
+
 function _format(primitive, unknownKey, allowedKeys) {
   return primitive + ": unknown option '" + unknownKey + "'. " +
     "Allowed keys: " + allowedKeys.slice().sort().join(", ") + ".";
@@ -150,6 +152,26 @@ function optionalFunction(value, label, errorClass, code) {
   return value;
 }
 
+// optionalPort — a TCP/UDP port number must be an integer in the wire-valid
+// range (RFC 6335 §6). Outbound-connect sites require [1,65535]; pass
+// { allowZero: true } for a listen-bind site where port 0 is the legitimate
+// ephemeral-bind sentinel the OS replaces with a kernel-assigned port. Uses
+// numericBounds.shape() in the message so Infinity / NaN / "443" stay visible.
+function optionalPort(value, label, errorClass, code, opts) {
+  if (value === undefined || value === null) return value;
+  opts = opts || {};
+  var ok = opts.allowZero
+    ? (numericBounds.isNonNegativeFiniteInt(value) && value <= 65535)
+    : (numericBounds.isPositiveFiniteInt(value) && value <= 65535);
+  if (!ok) {
+    _throw(errorClass, code, (label || "opt") + " must be " +
+           (opts.allowZero ? "0 (ephemeral) or " : "") +
+           "an integer in [" + (opts.allowZero ? 0 : 1) + ",65535], got " + numericBounds.shape(value),
+           "validate-opts/bad-port");
+  }
+  return value;
+}
+
 // applyDefaults — resolve every key in DEFAULTS against opts. For each
 // key, the operator's value (if not undefined) wins; otherwise the
 // default is used. Returns a new plain object — NOT a frozen one, so
@@ -391,6 +413,7 @@ module.exports.optionalBoolean = optionalBoolean;
 module.exports.optionalPositiveInt = optionalPositiveInt;
 module.exports.optionalFiniteNonNegative = optionalFiniteNonNegative;
 module.exports.optionalPositiveFinite = optionalPositiveFinite;
+module.exports.optionalPort = optionalPort;
 module.exports.optionalFunction = optionalFunction;
 module.exports.optionalNonEmptyString = optionalNonEmptyString;
 module.exports.optionalNonEmptyStringArray = optionalNonEmptyStringArray;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.14.14",
+  "version": "0.14.17",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:d4bb0c68-2752-4234-ac11-14ff95eaf273",
+  "serialNumber": "urn:uuid:e5d17e91-0802-4373-b6b4-f26370a14472",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T20:49:54.998Z",
+    "timestamp": "2026-06-01T03:23:48.524Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.14",
+      "bom-ref": "@blamejs/core@0.14.17",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.14",
+      "version": "0.14.17",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.14.14",
+      "purl": "pkg:npm/%40blamejs/core@0.14.17",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.14",
+      "ref": "@blamejs/core@0.14.17",
       "dependsOn": []
     }
   ]