@blamejs/core 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.5** (2026-05-06) — Vendor-currency CI gate + `b.middleware.requireMtls` primitive. **Vendor-currency check** — `scripts/check-vendor-currency.js` + new CI job in `ci.yml` assert every npm-mapped vendored bundle in `lib/vendor/MANIFEST.json` matches the latest published version on the npm registry. Per-component check on meta-bundles (e.g. `peculiar-pki` → `@peculiar/x509` + `pkijs`). Master-branch corpus entries (`SecLists`) are checked against the GitHub Commits API for the bundled file's path on the source repo's default branch — if the upstream has commits newer than the manifest's `bundledAt` date, the gate fails. Registry errors stay advisory unless `BLAMEJS_VENDOR_CURRENCY_STRICT=1`. Operators run locally with `npm run check:vendor-currency`. **`b.middleware.requireMtls`** — new soft-enforcement middleware that rejects requests without an authenticated client certificate. Composes with `b.crypto.hashCertFingerprint` / `isCertRevoked` (added in v0.8.4) so operators pass `fingerprintAllowList: [...]` and `denyList: [...]` and the middleware does the constant-time match. `req.peerCert` + `req.peerFingerprint` are attached for downstream handlers. Audits `mtls.required.allowed` / `mtls.required.refused` with reason metadata.
+
 - **0.8.4** (2026-05-06) — Supply-chain scanner findings + outbound HTTP posture + npm-publish unblock. **Outbound network surface** — `b.observability.otlpExporter` no longer defaults to `globalThis.fetch`; the default transport is now `b.httpClient` (`node:https` through the framework's PQC-hybrid agent + cert-pinning + SSRF guard). The prior default leaked an outbound network surface that supply-chain scanners flagged because it sat outside the framework's TLS posture; operators on fetch-only edge runtimes still override via `opts.fetchImpl`. **Dev-mode child-process isolation** — `b.dev.create()` now lazy-requires `child_process` (was top-level — flagged on every install regardless of whether `b.dev` was used) and refuses to construct when `NODE_ENV=production` unless the operator passes `opts.allowProduction:true` with an audited reason. A misconfigured production deploy that accidentally wires the dev-mode restart loop now crashes loudly at boot rather than spawning shells on every save. **Outbound posture additions** — `b.httpClient.request` adds `responseMode: "always-resolve"` (every response resolves with `{statusCode, headers, body}` regardless of HTTP status) plus `onRedirect({from, to, hop, headersStripped, statusCode, method})` hook (operators can throw to abort or rewrite the redirect chain). `b.wsClient.connect` adds `urlFor(attempt)` and `tlsOptsFor(attempt)` per-dial overrides for between-reconnect URL / TLS rotation; the new URL is re-validated through `ssrfGuard` so a hostile upstream can't redirect a reconnecting client at a private address. `b.wsClient` swallows post-`close()` `ECONNRESET` / `EPIPE` so a clean shutdown doesn't surface a noisy unhandled-error event. `b.pqcAgent.create({ ecdhCurve })` accepts a caller-supplied stricter list — operators can drop a group from the framework default but cannot widen with non-PQ groups (the prior hardcoded value blocked legitimate per-deployment narrowing). **Crypto helpers** — `b.crypto.hashCertFingerprint(pem|der)` returns `{ hex, colon }` SHA3-512 digests and `b.crypto.isCertRevoked(pemOrDer, denyList)` does a constant-time match. **Scheduler surface** — `b.scheduler.register(name, intervalMs, fn)` shorthand for the every-N-ms registration shape; `b.scheduler.getStatus()` returns an aggregate health surface for probes / dashboards (started flag, isLeader, per-task list, totals). **npm-publish unblock** — `test/layer-0-primitives/sd-jwt-vc.test.js` was asserting `DEFAULT_ALG === "ES256"` after v0.8.1 flipped the default to `ML-DSA-87`; the assertion now matches the lib (and `DEFAULT_HASH_ALG` for `sha3-512`). v0.8.1 / v0.8.2 / v0.8.3 all failed the npm-publish gate on this single test; this release re-enables the publish workflow.
 
 - **0.8.3** (2026-05-06) — Release-gate fixes + post-v0.8.2 hardening. Wiki primitive-section validator gate flagged `b.middleware.csrfProtect` opts-key drift — the `requireOrigin` opt added in v0.8.1 wasn't documented in the wiki seeder; now listed alongside `checkOrigin` / `allowedOrigins`. Gitleaks secret-scan gate flagged `{ privateKey, cipherText }` KEM-envelope shapes in `lib/crypto.js` error messages + `CHANGELOG.md` v0.8.0 entry as generic-api-key false positives — `.gitleaks.toml` adds an explicit regex allowlist for the parameter-name shape and pins the v0.8.0 commit fingerprints. Functional additions: `b.httpClient.request` adds `responseMode: "always-resolve"` opt — every request resolves with `{ statusCode, headers, body }` regardless of HTTP status (operators using the framework as an inbound-proxy upstream no longer have to wrap each call in a try/catch to recover the body of a 4xx/5xx). `b.wsClient` swallows post-close `ECONNRESET` / `EPIPE` errors so a clean `close()` doesn't surface a noisy unhandled-error event when the kernel races the FIN with an in-flight write. `SECURITY.md` documents the `allowInternal: true` test-pattern (legitimate same-host integration tests opt in explicitly with audited reason — never as a production default).

package/lib/middleware/index.js

@@ -47,6 +47,7 @@ var requireAal = require("./require-aal");
 var requireAuth = require("./require-auth");
 var requireContentType = require("./require-content-type");
 var requireMethods = require("./require-methods");
+var requireMtls = require("./require-mtls");
 var requireStepUp = require("./require-step-up");
 var securityHeaders = require("./security-headers");
 var securityTxt = require("./security-txt");
@@ -70,6 +71,7 @@ module.exports = {
   requireAuth:      requireAuth.create,
   requireContentType: requireContentType.create,
   requireMethods:   requireMethods.create,
+  requireMtls:      requireMtls.create,
   requireStepUp:    requireStepUp.create,
   csrfProtect:      csrfProtect.create,
   fetchMetadata:    fetchMetadata.create,
@@ -113,6 +115,7 @@ module.exports = {
     requireAuth:      requireAuth,
     requireContentType: requireContentType,
     requireMethods:   requireMethods,
+    requireMtls:      requireMtls,
     requireStepUp:    requireStepUp,
     csrfProtect:      csrfProtect,
     fetchMetadata:    fetchMetadata,

package/lib/middleware/require-mtls.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * requireMtls middleware — soft-enforcement gate for routes that
+ * require a client certificate.
+ *
+ * Operators terminate TLS at the framework's HTTPS server with
+ * `requestCert: true` (the framework already wires this when
+ * `b.app({ tlsOptions: { requestCert: true, ca: [...] } })` is
+ * configured). For routes that MUST receive an authenticated peer
+ * cert — e.g. the inbound side of an mTLS service mesh, OAuth 2.0
+ * mTLS Client Authentication (RFC 8705), or operator-specific
+ * service-to-service endpoints — wire this middleware in front of
+ * the route to reject any request that didn't present a valid
+ * client cert.
+ *
+ *   var requireMtls = b.middleware.requireMtls({
+ *     fingerprintAllowList: [
+ *       "AB:CD:EF:...",                 // colon-separated SHA3-512 hex
+ *     ],
+ *     denyList:             [],          // explicit revocations
+ *     onAuthenticated:      function (req, res, next) {
+ *       req.peerSubject = req.peerCert.subject;
+ *       next();
+ *     },
+ *     audit:                b.audit,
+ *   });
+ *   router.use("/internal", requireMtls);
+ *
+ * Failure modes (all reject 401):
+ *   - No peer cert presented (client did not negotiate mTLS)
+ *   - Peer cert present but unauthorized at TLS layer
+ *     (req.client.authorized === false)
+ *   - Fingerprint not on the operator-supplied allow-list
+ *   - Fingerprint on the operator-supplied deny-list
+ *
+ * Audit shape (when audit is wired): emits `mtls.required.allowed`
+ * (success) or `mtls.required.refused` (denied) with the peer-cert
+ * fingerprint + subject + reason in metadata. Drop-silent if no
+ * audit is wired.
+ *
+ * The fingerprint allow / deny comparison routes through
+ * b.crypto.isCertRevoked — both forms (lowercase hex / uppercase
+ * colon-separated) match. Allow-list of empty / null = "any
+ * peer cert authorized at the TLS layer"; specifying a non-empty
+ * allow-list ALSO requires the fingerprint to match.
+ */
+
+var defineClass = require("../framework-error").defineClass;
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+
+var crypto = lazyRequire(function () { return require("../crypto"); });
+var audit  = lazyRequire(function () { return require("../audit"); });
+
+var RequireMtlsError = defineClass("RequireMtlsError", { alwaysPermanent: true });
+
+function _normalizeFingerprintEntry(entry) {
+  if (typeof entry !== "string" || entry.length === 0) {
+    throw new RequireMtlsError("require-mtls/bad-fingerprint",
+      "fingerprint allow/deny entries must be non-empty strings " +
+      "(SHA3-512 hex or colon-separated form)");
+  }
+  return entry;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "fingerprintAllowList", "denyList",
+    "onAuthenticated", "audit",
+    "auditAction", "errorMessage",
+  ], "middleware.requireMtls");
+
+  var allowList = Array.isArray(opts.fingerprintAllowList)
+    ? opts.fingerprintAllowList.map(_normalizeFingerprintEntry) : null;
+  var denyList = Array.isArray(opts.denyList)
+    ? opts.denyList.map(_normalizeFingerprintEntry) : [];
+  var onAuthenticated = typeof opts.onAuthenticated === "function" ? opts.onAuthenticated : null;
+  var auditOn  = opts.audit !== false;
+  var actionBase = typeof opts.auditAction === "string" && opts.auditAction.length > 0
+    ? opts.auditAction : "mtls.required";
+  var errorMessage = typeof opts.errorMessage === "string" && opts.errorMessage.length > 0
+    ? opts.errorMessage : "client certificate required";
+
+  function _emit(outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   actionBase + (outcome === "success" ? ".allowed" : ".refused"),
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit is best-effort, never blocks the request */ }
+  }
+
+  function _refuse(res, reason, metadata) {
+    _emit("denied", Object.assign({ reason: reason }, metadata || {}));
+    if (typeof res.writeHead === "function") {
+      res.writeHead(401, {
+        "Content-Type":     "application/json; charset=utf-8",
+        "WWW-Authenticate": "Mutual",
+        "Cache-Control":    "no-store",
+      });
+      res.end(JSON.stringify({ error: errorMessage, reason: reason }));
+    }
+  }
+
+  return function requireMtlsMiddleware(req, res, next) {
+    // Node's TLSSocket exposes:
+    //   req.client.authorized           — boolean, peer cert chain valid
+    //   req.client.authorizationError   — string when authorized=false
+    //   req.socket.getPeerCertificate() — the cert (raw + parsed fields)
+    // Behind a TLS-terminating proxy (e.g. nginx, envoy) operators
+    // pass the peer cert as a header (X-Client-Cert) and pre-populate
+    // req.peerCert before this middleware fires. We don't inject a
+    // proxy-header parser here — that's an operator-side decision tied
+    // to the chosen proxy's signing model.
+    var sock = req.socket || req.connection || null;
+    var authorized = sock && sock.authorized === true;
+    var peerCert = req.peerCert || null;
+    if (!peerCert && sock && typeof sock.getPeerCertificate === "function") {
+      try { peerCert = sock.getPeerCertificate(true) || null; }
+      catch (_e) { peerCert = null; }
+    }
+
+    if (!authorized) {
+      var authzError = (sock && sock.authorizationError) || "no-peer-cert";
+      return _refuse(res, "tls-unauthorized", { authorizationError: String(authzError) });
+    }
+    if (!peerCert || !peerCert.raw) {
+      return _refuse(res, "no-peer-cert", {});
+    }
+
+    // Compute fingerprint via the framework's SHA3-512 helper. Buffer
+    // form: peerCert.raw is the DER. Hex/colon both available for
+    // allow/deny matching.
+    var fp;
+    try {
+      fp = crypto().hashCertFingerprint(peerCert.raw);
+    } catch (e) {
+      return _refuse(res, "fingerprint-failed", { error: (e && e.message) || String(e) });
+    }
+
+    if (denyList.length > 0 && crypto().isCertRevoked(peerCert.raw, denyList)) {
+      return _refuse(res, "fingerprint-on-deny-list", {
+        fingerprint: fp.colon,
+        subject:     (peerCert.subject && peerCert.subject.CN) || null,
+      });
+    }
+    if (allowList && allowList.length > 0 && !crypto().isCertRevoked(peerCert.raw, allowList)) {
+      return _refuse(res, "fingerprint-not-allowed", {
+        fingerprint: fp.colon,
+        subject:     (peerCert.subject && peerCert.subject.CN) || null,
+      });
+    }
+
+    // Authenticated — attach the parsed peer cert + fingerprint to
+    // the request so downstream handlers don't have to re-parse, then
+    // emit success and call next (or operator's onAuthenticated hook).
+    req.peerCert        = peerCert;
+    req.peerFingerprint = fp;
+    _emit("success", {
+      fingerprint: fp.colon,
+      subject:     (peerCert.subject && peerCert.subject.CN) || null,
+    });
+    if (onAuthenticated) {
+      try { return onAuthenticated(req, res, next); }
+      catch (e) {
+        return _refuse(res, "on-authenticated-threw", { error: (e && e.message) || String(e) });
+      }
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create:           create,
+  RequireMtlsError: RequireMtlsError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -70,7 +70,8 @@
   ],
   "scripts": {
     "test": "node test/smoke.js",
-    "prepack": "node scripts/check-pack-against-gitignore.js"
+    "prepack": "node scripts/check-pack-against-gitignore.js",
+    "check:vendor-currency": "node scripts/check-vendor-currency.js"
   },
   "dependencies": {},
   "devDependencies": {}

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:91e8b760-7fe3-4fef-a317-8b1e4f8cc238",
+  "serialNumber": "urn:uuid:1f60d33c-fc3b-4da1-a753-bb1c98de9968",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T22:02:35.725Z",
+    "timestamp": "2026-05-06T22:33:10.715Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.4",
+      "bom-ref": "@blamejs/core@0.8.5",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.4",
+      "version": "0.8.5",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.4",
+      "purl": "pkg:npm/%40blamejs/core@0.8.5",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.4",
+      "ref": "@blamejs/core@0.8.5",
       "dependsOn": []
     }
   ]