@blamejs/core 0.8.87 → 0.8.88

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.88 (2026-05-11) — **Hotfix: `b.auth.fal.meets()` authorization-correctness bug + new `b.earlyHints` RFC 8297 helper**. **Hotfix (PRIMARY)**: `b.auth.fal.meets(actualBand, requiredBand)` previously compared raw ranks (`_bandRank(actual) >= _bandRank(required)`) without validating either input. Unknown bands mapped to rank `0`, so `meets("FAL1", "FALX")` returned `true` (because `1 >= 0`) and `meets("bad", "bad")` returned `true` (because `0 >= 0`) — both contradicting the documented contract that invalid bands MUST return `false`. Operators calling `meets()` directly for authorization decisions could grant access on malformed input pairs. The new implementation validates both bands via `isValidBand()` first; any invalid band on either side returns `false`. The `requireFal()` guard was already correct (it used `meets()` after a separate `isValidBand(actualBand)` check, but a defense-in-depth pass into `meets()` itself now catches direct callers too). Tests added: 7 invalid-input shapes (`FALX` actual, `FALX` required, `bad`/`bad`, `FALX`/`FALX`, null on either side, both null). **New**: `b.earlyHints.send(res, { link })` — RFC 8297 103 Early Hints interim-response helper. Wraps Node 18.11+'s built-in `res.writeEarlyHints()` with: link-header validation (RFC 8288 form with one of `preload` / `preconnect` / `prefetch` / `dns-prefetch` / `modulepreload` / `prerender` / `next` / `prev`); silent no-op when the response object lacks `writeEarlyHints` (HTTP/1.0, mocks, older Node); refusal of per-request-state headers per RFC 8297 §3 (`set-cookie`, `authorization`, `content-length`, `content-type`, etc.). Operators use it to start browser-side preload of CSS / JS / fonts / preconnect origins in parallel with the server-side composition of the final response.
 - v0.8.87 (2026-05-11) — **NIST 800-63-4 FAL classifier + RFC 7505 Null-MX helper + Gmail FBL Feedback-ID builder + vendor-update.sh stale-entry cleanup**. **`b.auth.fal`** lands as the federation-side counterpart to the existing `b.auth.aal` band classifier. `fromAssertion({ channel, encrypted?, replayProtected?, hokBinding? })` classifies an incoming federation assertion as `"FAL1"` / `"FAL2"` / `"FAL3"` per NIST 800-63C-4: Holder-of-Key (mTLS / DPoP / SAML HoK) with replay-protection → FAL3; back-channel OR encrypted front-channel with replay-protection → FAL2; bare bearer front-channel → FAL1. Conservative: missing replay-protection on a back-channel assertion downgrades to FAL1 because §5.2 requires nonce / jti binding before back-channel can claim FAL2. `requireFal(minimumBand)` builds a band-check guard that throws `auth/fal-insufficient` for stale-band requests; compose with the request-scope auth state to gate sensitive operations. **`b.network.dns.isNullMx(records)`** lands as the RFC 7505 Null-MX classifier: returns `true` when an operator-supplied MX-record array signals "this domain does not accept email" (single record, priority 0, exchange `.` per RFC 7505 §3). Operators send-side check this before delivery to skip domains that have explicitly opted out — `node:dns.resolveMx` returns `exchange: ""` for the same RDATA, so the classifier accepts both shapes. **`b.mail.feedbackId({ campaignId, customerId, mailType, senderId })`** builds a Gmail Feedback-Loop (FBL) Feedback-ID header value as the canonical 4-tuple `CampaignID:CustomerID:MailType:SenderID`. Refuses missing / empty fields, fields containing `:` (would corrupt the field separator), fields >64 chars (Gmail FBL truncation threshold), and control-char content (CR/LF header-injection defense). Setting Feedback-ID on outbound mail lets Gmail Postmaster Tools surface per-campaign abuse-rate metrics keyed by the operator's vocabulary instead of by SMTP envelope-sender alone. **vendor-update.sh cleanup**: `scripts/vendor-update.sh --check` removed the stale `argon2` entry from `VENDORED_PACKAGES`. argon2 was removed from `lib/vendor/` back in v0.4.x when Node 24's built-in `crypto.argon2*` API replaced the third-party prebuilds (per `lib/argon2-builtin.js`); the script still listed it in the check array, producing a false "UPDATE AVAILABLE" line for an unvendored package. The case-block error path that still says "argon2 is no longer vendored" stays so anyone running `./scripts/vendor-update.sh argon2` gets the operator-friendly explanation.
 - v0.8.86 (2026-05-11) — **Sectoral + cybersecurity posture sweep + HTTP-hygiene primitives + npm-publish hotfix**. **npm-publish hotfix**: the v0.8.85 `npm audit signatures` step failed with `npm error found no installed dependencies to audit` because the framework's zero-runtime-deps posture produces an empty install tree; the gate now treats that specific message as success while keeping every other failure mode loud (v0.8.85 npm tarball never published — operators upgrade `0.8.83 → 0.8.86` to pick up the carried v0.8.84 + v0.8.85 surface plus the new v0.8.86 primitives). **10 new compliance postures**: `cmmc-2.0` (DoD Cybersecurity Maturity Model Certification 2.0), `cjis-v6` (FBI CJIS Security Policy v6.0), `iso-27001-2022` + `iso-27002-2022` + `iso-27017` + `iso-27018` + `iso-27701` (ISO/IEC 27001 family), `nist-800-66-r2` (HIPAA Security Rule implementation guidance), `ehds` (European Health Data Space), `circia` (US Cyber Incident Reporting for Critical Infrastructure Act). Cascade defaults set encrypted-backup + signed-audit-chain + TLS 1.3 + vacuum-after-erase for the data-tier postures; `iso-27002-2022` + `circia` defer the data-tier mandate to operator choice. **`b.cacheStatus`** — RFC 9211 Cache-Status response-header builder + parser. `append(prev, entry)` chains the operator's current cache decision onto whatever upstream caches wrote; `entry({...})` formats a single entry; `parse(headerValue)` returns the parsed chain as `[{ cache, params }]` records with `hit`/`stored`/`collapsed` as booleans, `ttl`/`fwdStatus` as numbers, `fwd` as the RFC 9211 §2 enum string, `key`/`detail` as unquoted sf-strings. Operators diagnose CDN/reverse-proxy/app-cache decision chains by reading the header instead of guessing from elapsed-time metrics. **`b.serverTiming`** — W3C Server-Timing response-header builder. `create()` returns a per-request collector with `mark(name, durationMs?, description?)` / `measure(name, fn)` async-timing wrapper / `toHeader()` serializer. Surfaces server-side latency in the browser's Performance API. **`b.middleware.noCache`** — RFC 9111 §5.2.2.5 `Cache-Control: no-store` middleware for auth-gated / individualized response paths. Sets `Cache-Control: no-store`, `Pragma: no-cache` (HTTP/1.0 compatibility), `Vary: Cookie, Authorization` so intermediate caches don't store personalized responses keyed by URL alone. Optional `opts.when(req)` predicate for conditional application; `opts.skipExisting:true` skips when `Cache-Control` is already set.
 - v0.8.85 (2026-05-11) — **MCP tool registry + tool-call signing + A2A v1 task-exchange surface**. Closes the substantial agent-protocol gaps surfaced by the 2026-05-11 audit's MITRE ATLAS v5.3.0 + A2A v1 cross-walk. **MCP tool registry** lands as `b.mcp.toolRegistry.create({ tools, signingKey, verifyingKey?, alg?, ttlMs? })` — every registered tool gets a signed descriptor blob `{ tool, alg, signature }` (defense against compromised MCP server / descriptor drift) and a `descriptorsManifest()` produces a signed `{ body, signature }` document for operator-side attestation. The registry's `signCall({ toolName, args, nonce?, ttlMs? })` builds + signs an outbound tool-call envelope `{ tool, argsHash, nonce, iat, exp }` (defense against MCP middleman / indirect-prompt-injection synthesizing tool calls); `verifyCall(signed, { args?, seen?, nowMs? })` runs the inverse on inbound — refuses signature mismatch (`mcp/call-verify-failed`), expired envelopes (`mcp/call-expired`), replayed nonces via operator-supplied `seen(nonce)` callback (`mcp/call-replay`), unregistered tools (`mcp/call-unregistered-tool`), and args-hash mismatch when raw args supplied (`mcp/call-args-mismatch`). Default algorithm ML-DSA-87 per the framework's PQC-first rule; Ed25519 / ECDSA / SLH-DSA also available. **A2A v1 task-exchange surface** lands as `b.a2a.tasks.{send, get, cancel}` (client-side JSON-RPC dispatchers — `send` posts `tasks/send` to the peer URL with task validation + https-only refusal; `get` polls `tasks/get`; `cancel` requests `tasks/cancel`) plus `b.a2a.middleware.tasks({ scopes, handler, maxBytes? })` (server-side connect-style middleware — parses inbound JSON-RPC 2.0, enforces method allowlist `[tasks/send, tasks/get, tasks/cancel]` with -32601 method-not-found, enforces per-skill scopes via `req.a2aScopes` with -32001 scope-denied, dispatches to operator handler, maps errors to JSON-RPC -32603, refuses non-POST with 405 + non-JSON content-type with 415) plus `b.a2a.middleware.agentCard({ card, maxAgeSec? })` (serves operator's signed Agent Card at `/.well-known/agent.json` per A2A v1 discovery — 405 on non-GET, Cache-Control max-age operator-tunable).

package/index.js

@@ -146,6 +146,7 @@ var dataAct = require("./lib/data-act");
 var problemDetails = require("./lib/problem-details");
 var cacheStatus = require("./lib/cache-status");
 var serverTiming = require("./lib/server-timing");
+var earlyHints = require("./lib/early-hints");
 var gateContract = require("./lib/gate-contract");
 var guardCsv = require("./lib/guard-csv");
 var guardHtml = require("./lib/guard-html");
@@ -377,6 +378,7 @@ module.exports = {
   problemDetails:   problemDetails,
   cacheStatus:      cacheStatus,
   serverTiming:     serverTiming,
+  earlyHints:       earlyHints,
   gateContract:     gateContract,
   guardCsv:         guardCsv,
   guardHtml:        guardHtml,

package/lib/auth/fal.js

@@ -81,13 +81,23 @@ function isValidBand(band) {
  *
  * Predicate returning `true` when `actualBand` satisfies the
  * `requiredBand` floor (FAL3 ≥ FAL2 ≥ FAL1). Invalid band strings
- * on either argument return `false`.
+ * on either argument return `false` — operators using `meets`
+ * directly for authorization decisions never get a "true" verdict
+ * out of a malformed input pair.
  *
  * @example
- *   b.auth.fal.meets("FAL3", "FAL2");   // → true
- *   b.auth.fal.meets("FAL1", "FAL2");   // → false
+ *   b.auth.fal.meets("FAL3", "FAL2");    // → true
+ *   b.auth.fal.meets("FAL1", "FAL2");    // → false
+ *   b.auth.fal.meets("FAL1", "FALX");    // → false (invalid required band)
+ *   b.auth.fal.meets("bad", "bad");      // → false (both invalid)
  */
 function meets(actualBand, requiredBand) {
+  // Validate BOTH inputs before comparing ranks. The previous
+  // implementation compared raw ranks (`>=`) — unknown bands mapped
+  // to rank 0 and `0 >= 0` returned true, contradicting the
+  // documented contract and producing false-positive authorization
+  // decisions for operators using meets() directly.
+  if (!isValidBand(actualBand) || !isValidBand(requiredBand)) return false;
   return _bandRank(actualBand) >= _bandRank(requiredBand);
 }
 

package/lib/early-hints.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * @module     b.earlyHints
+ * @nav        HTTP
+ * @title      RFC 8297 103 Early Hints
+ * @order      320
+ *
+ * @intro
+ *   RFC 8297 103 Early Hints — interim informational response the
+ *   server sends BEFORE the final response, telling the browser
+ *   which subresources it should start preloading while the server
+ *   is still composing the final HTML / JSON. Browsers (Chrome 103+,
+ *   Edge 103+, Firefox 120+) honor `Link: rel=preload` /
+ *   `rel=preconnect` headers in the 103 to kick off resource fetches
+ *   in parallel with the main render.
+ *
+ *   Operators reach for early-hints when the server has slow upstream
+ *   dependencies (DB query, downstream API) but already knows the
+ *   final response will reference specific CSS / JS / fonts /
+ *   API origins. The 103 turns a single-RTT-bound page load into a
+ *   parallel resource-prefetch chain.
+ *
+ *   `b.earlyHints.send(res, { link, ... })` writes the interim 103
+ *   with the supplied headers. The framework wraps Node's built-in
+ *   `res.writeEarlyHints()` (Node 18.11+) and adds:
+ *
+ *     - input validation (link entries must be RFC 8288 Link-header
+ *       form: `<uri>; rel=preload[; as=script][; crossorigin=...]`)
+ *     - silent no-op when the operator-supplied `res` is not an
+ *       HTTP/1.1+ socket-backed response (HTTP/1.0 clients don't
+ *       understand 103; serializing one would corrupt the stream)
+ *     - validation of cacheable header set per RFC 8297 section 3
+ *       (only headers that hint about the FINAL response are
+ *       honored; Set-Cookie / authentication-related headers are
+ *       refused)
+ *
+ *   The 103 does NOT replace the final response — the operator's
+ *   handler still writes the regular 200/400/etc. status + body.
+ *   Multiple 103s before the final response are permitted (Node's
+ *   writeEarlyHints can be called repeatedly).
+ *
+ * @card
+ *   RFC 8297 103 Early Hints helper — operator-friendly wrapper around Node's response writeEarlyHints API for browser-side parallel resource-prefetch hints.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var EarlyHintsError = defineClass("EarlyHintsError", { alwaysPermanent: true });
+
+// Headers that are SAFE to surface in a 103 are the ones describing
+// the upcoming final response. Refused header names mostly carry
+// per-request state (cookies, auth) that a 103 would prematurely
+// leak or that a 103 cannot honor (Content-Length, Transfer-
+// Encoding, Content-Type all describe THIS interim response, not
+// the final).
+var REFUSED_HEADERS = Object.freeze([
+  "set-cookie",
+  "authorization",
+  "www-authenticate",
+  "content-length",
+  "content-type",
+  "transfer-encoding",
+  "connection",
+  "upgrade",
+  "trailer",
+]);
+
+var LINK_RELATION_RE = /^(preload|preconnect|prefetch|dns-prefetch|modulepreload|prerender|next|prev)$/i;
+var LINK_MAX_BYTES = 4096;                                                                         // allow:raw-byte-literal — per-link length cap, not bytes
+
+/**
+ * @primitive b.earlyHints.send
+ * @signature b.earlyHints.send(res, opts)
+ * @since     0.8.88
+ * @status    stable
+ *
+ * Write an RFC 8297 103 Early Hints interim response to `res`.
+ * Returns `true` when the 103 was written, `false` when the
+ * underlying response does not support early hints (HTTP/1.0, a
+ * non-HTTP-shaped object, or the response writeEarlyHints API is
+ * missing).
+ *
+ * `link` is either a single Link-header value string OR an array
+ * of strings. Each must follow the RFC 8288 Link-header grammar
+ * with a `rel=` parameter naming one of: `preload`, `preconnect`,
+ * `prefetch`, `dns-prefetch`, `modulepreload`, `prerender`, `next`,
+ * `prev`. Refused: per-link size > 4 KiB, missing `rel=`, unknown
+ * relation. Other operator-supplied header keys must NOT be in
+ * `REFUSED_HEADERS` (set-cookie / authorization / content-length
+ * / etc.) — those carry per-request state a 103 must not surface.
+ *
+ * @opts
+ *   link:         string | string[],   // RFC 8288 Link-header values (REQUIRED)
+ *
+ * @example
+ *   b.earlyHints.send(res, {
+ *     link: [
+ *       "</style.css>; rel=preload; as=style",
+ *       "</app.js>; rel=preload; as=script",
+ *       "<https://cdn.example.com>; rel=preconnect",
+ *     ],
+ *   });
+ *   res.statusCode = 200;
+ *   res.setHeader("Content-Type", "text/html");
+ *   res.end(html);
+ */
+function send(res, opts) {
+  if (!res || typeof res !== "object") {
+    throw new EarlyHintsError("early-hints/bad-res",
+      "earlyHints.send: res must be an HTTP response object", true);
+  }
+  if (typeof res.writeEarlyHints !== "function") {
+    // Node < 18.11 OR HTTP/1.0 OR mock res — silent no-op so
+    // operator code stays the same across deployments.
+    return false;
+  }
+  if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+    throw new EarlyHintsError("early-hints/bad-opts",
+      "earlyHints.send: opts required (link + optional header pairs)", true);
+  }
+
+  var headers = {};
+
+  if (opts.link === undefined || opts.link === null) {
+    throw new EarlyHintsError("early-hints/no-link",
+      "earlyHints.send: opts.link is required (RFC 8297 §2 requires at least one Link header)", true);
+  }
+  var linkArr = Array.isArray(opts.link) ? opts.link : [opts.link];
+  if (linkArr.length === 0) {
+    throw new EarlyHintsError("early-hints/no-link",
+      "earlyHints.send: opts.link must contain at least one Link-header value", true);
+  }
+  for (var i = 0; i < linkArr.length; i += 1) {
+    _validateLink(linkArr[i], i);
+  }
+  headers.link = linkArr;
+
+  var keys = Object.keys(opts);
+  for (var k = 0; k < keys.length; k += 1) {
+    var name = keys[k];
+    if (name === "link") continue;
+    var lower = name.toLowerCase();
+    if (REFUSED_HEADERS.indexOf(lower) !== -1) {
+      throw new EarlyHintsError("early-hints/refused-header",
+        "earlyHints.send: header '" + name + "' refused — RFC 8297 §3 prohibits " +
+        "per-request state in interim responses (refused set: " + REFUSED_HEADERS.join(", ") + ")");
+    }
+    if (typeof opts[name] !== "string" && !Array.isArray(opts[name])) {
+      throw new EarlyHintsError("early-hints/bad-header-value",
+        "earlyHints.send: header '" + name + "' must be a string or string[]", true);
+    }
+    headers[lower] = opts[name];
+  }
+
+  try {
+    res.writeEarlyHints(headers);
+    return true;
+  } catch (writeErr) {
+    throw new EarlyHintsError("early-hints/write-failed",
+      "earlyHints.send: writeEarlyHints failed: " + (writeErr.message || writeErr));
+  }
+}
+
+function _validateLink(linkValue, idx) {
+  validateOpts.requireNonEmptyString(linkValue, "earlyHints.send.link[" + idx + "]",
+    EarlyHintsError, "early-hints/bad-link");
+  if (linkValue.length > LINK_MAX_BYTES) {
+    throw new EarlyHintsError("early-hints/bad-link",
+      "link[" + idx + "] exceeds " + LINK_MAX_BYTES + " bytes");
+  }
+  var relMatch = /;\s*rel\s*=\s*"?([a-zA-Z0-9-]+)"?/i.exec(linkValue);
+  if (!relMatch) {
+    throw new EarlyHintsError("early-hints/bad-link",
+      "link[" + idx + "] missing rel= parameter (RFC 8288)");
+  }
+  if (relMatch[1].length > 32 || !LINK_RELATION_RE.test(relMatch[1])) {                            // allow:raw-byte-literal — rel-token length cap, not bytes
+    throw new EarlyHintsError("early-hints/bad-link",
+      "link[" + idx + "].rel '" + relMatch[1] + "' must be one of: " +
+      "preload, preconnect, prefetch, dns-prefetch, modulepreload, prerender, next, prev");
+  }
+  if (linkValue.charAt(0) !== "<" || linkValue.indexOf(">") < 1) {
+    throw new EarlyHintsError("early-hints/bad-link",
+      "link[" + idx + "] must start with angle-bracketed URI per RFC 8288 (e.g. <https://x.com>; rel=preload)");
+  }
+}
+
+module.exports = {
+  send:             send,
+  REFUSED_HEADERS:  REFUSED_HEADERS,
+  EarlyHintsError:  EarlyHintsError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.87",
+  "version": "0.8.88",
   "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.6",
-  "serialNumber": "urn:uuid:1d067739-a1a9-4df9-8c82-febef293933a",
+  "serialNumber": "urn:uuid:75038048-e27a-4af6-a354-0cabce037597",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-11T17:46:06.986Z",
+    "timestamp": "2026-05-11T18:13:26.544Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.87",
+      "bom-ref": "@blamejs/core@0.8.88",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.87",
+      "version": "0.8.88",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.87",
+      "purl": "pkg:npm/%40blamejs/core@0.8.88",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.87",
+      "ref": "@blamejs/core@0.8.88",
       "dependsOn": []
     }
   ]