@blamejs/core 0.14.14 → 0.14.16

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.14.x
 
+- 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/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/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/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/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.16",
   "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:44556dbf-5411-4644-ab81-5f0571d5e036",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T20:49:54.998Z",
+    "timestamp": "2026-06-01T02:09:53.597Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.14",
+      "bom-ref": "@blamejs/core@0.14.16",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.14",
+      "version": "0.14.16",
       "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.16",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.14",
+      "ref": "@blamejs/core@0.14.16",
       "dependsOn": []
     }
   ]