@blamejs/core 0.8.86 → 0.8.88

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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).
 - v0.8.84 (2026-05-11) — **Supply-chain hardening trio + HTTP-API hygiene primitives**. **Supply chain**: CodeQL SAST workflow (`.github/workflows/codeql.yml` — PR + push-to-main + weekly Mon-05:31-UTC schedule) running the `security-extended` query pack against the JavaScript surface (catches SQL injection, XSS, prototype pollution, command injection, ReDoS, unsafe deserialization, SSRF, hardcoded credentials beyond what OSV-Scanner sees; findings surface as SARIF in the Security tab); `npm audit signatures` step in `npm-publish.yml` that verifies the cryptographic signing chain for every package in the install tree against the npm registry's public keys before the publish step runs (regression-defense — the framework ships zero npm runtime deps so the tree is trivially empty today; if a future patch accidentally adds a runtime dep, the gate refuses an unsigned registry entry before tag-push triggers a release); vendored SBOM signing extends the existing cosign-keyless flow to sign `sbom.vendored.cdx.json` alongside `sbom.cdx.json` and attaches both `.sigstore` bundles to the GitHub Release. **HTTP-API hygiene primitives**: new `b.problemDetails` family implementing RFC 9457 Problem Details for HTTP APIs (`create({ type, title, status, detail, instance, ...extensions })` builds a frozen problem doc with field validation; `fromError(err)` converts a `FrameworkError` into a problem doc with `type` derived from `err.code` against a configurable base URI; `respond(res, problem)` writes the response with `Content-Type: application/problem+json` + `Cache-Control: no-store` per RFC 9457 §3 + RFC 9111 §5.2.2.5; `validate(doc)` parses inbound problem docs from upstream APIs with shape refusal). New `b.middleware.idempotencyKey` implementing draft-ietf-httpapi-idempotency-key (replay-safe POST/PUT/PATCH/DELETE — operator-supplied store interface with first-party `memoryStore({ maxEntries })`; cached fingerprint = method + path + sha3-256(body); 422 + `idempotency/key-reuse-mismatch` problem-details on same-key-different-body per draft §4.3; 5xx responses are NOT cached because replaying a transient infrastructure failure is not idempotent; default TTL 24h; default methods POST/PUT/PATCH/DELETE). The v0.8.84 git tag landed on a wrong commit due to a release-workflow ordering issue and the npm publish for 0.8.84 did not ship; operators upgrade directly from 0.8.83 to 0.8.85 (which carries the same primitives as part of the combined ship).

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");
@@ -187,6 +188,7 @@ var auth = {
   lockout:  require("./lib/auth/lockout"),
   dpop:     require("./lib/auth/dpop"),
   aal:      require("./lib/auth/aal"),
+  fal:      require("./lib/auth/fal"),
   statusList: require("./lib/auth/status-list"),
   sdJwtVc:    require("./lib/auth/sd-jwt-vc"),
   stepUp:     require("./lib/auth/step-up"),
@@ -376,6 +378,7 @@ module.exports = {
   problemDetails:   problemDetails,
   cacheStatus:      cacheStatus,
   serverTiming:     serverTiming,
+  earlyHints:       earlyHints,
   gateContract:     gateContract,
   guardCsv:         guardCsv,
   guardHtml:        guardHtml,

package/lib/auth/fal.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * @module     b.auth.fal
+ * @nav        Identity & Access
+ * @title      NIST 800-63-4 FAL Classifier
+ * @order      120
+ *
+ * @intro
+ *   NIST SP 800-63-4 Federation Assurance Levels — FAL1 / FAL2 /
+ *   FAL3. While AAL describes the rigor of authentication (what the
+ *   user did to prove they are who they say they are), FAL describes
+ *   the rigor of the FEDERATION assertion that carried that
+ *   authentication from the IdP to the RP.
+ *
+ *   FAL bands per NIST 800-63C-4:
+ *
+ *     FAL1: Bearer assertion delivered through the front channel
+ *           (typical OIDC ID token over the browser redirect).
+ *           Signed by the IdP; verified by the RP. No audience
+ *           binding beyond the standard `aud` claim.
+ *
+ *     FAL2: Bearer assertion delivered through the back channel
+ *           OR front-channel assertion that is encrypted to the RP.
+ *           Replay-protection nonce required. Typical OIDC
+ *           Authorization Code Flow with mTLS or DPoP-bound token.
+ *
+ *     FAL3: Holder-of-Key assertion. RP verifies the subject
+ *           cryptographically holds a key bound to the assertion
+ *           (mTLS client-cert pinned to the subject, DPoP-bound +
+ *           audience-restricted, OR SAML HoK SubjectConfirmation).
+ *           Defeats stolen-bearer-token replay.
+ *
+ *   Operators classify the FAL of an incoming federation assertion
+ *   via `fromAssertion(opts)` — pass the assertion's properties
+ *   (channel, encrypted, hokBinding, etc.) and get back the band.
+ *   Compose with `b.middleware.requireFal({ minimum: "FAL2" })` for
+ *   the gate.
+ *
+ * @card
+ *   NIST 800-63-4 Federation Assurance Level classifier — describes the rigor of the federation assertion (FAL1 bearer / FAL2 encrypted-or-back-channel / FAL3 Holder-of-Key) carried from IdP to RP.
+ */
+
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+var FAL1 = "FAL1";
+var FAL2 = "FAL2";
+var FAL3 = "FAL3";
+
+var BANDS = Object.freeze([FAL1, FAL2, FAL3]);
+
+function _bandRank(band) {
+  if (band === FAL1) return 1;
+  if (band === FAL2) return 2;
+  if (band === FAL3) return 3;
+  return 0;
+}
+
+/**
+ * @primitive b.auth.fal.isValidBand
+ * @signature b.auth.fal.isValidBand(band)
+ * @since     0.8.87
+ * @status    stable
+ *
+ * Predicate returning `true` when `band` is one of the documented
+ * FAL band strings (`"FAL1"` / `"FAL2"` / `"FAL3"`).
+ *
+ * @example
+ *   b.auth.fal.isValidBand("FAL2");  // → true
+ *   b.auth.fal.isValidBand("FALX");  // → false
+ */
+function isValidBand(band) {
+  return _bandRank(band) > 0;
+}
+
+/**
+ * @primitive b.auth.fal.meets
+ * @signature b.auth.fal.meets(actualBand, requiredBand)
+ * @since     0.8.87
+ * @status    stable
+ *
+ * Predicate returning `true` when `actualBand` satisfies the
+ * `requiredBand` floor (FAL3 ≥ FAL2 ≥ FAL1). Invalid band strings
+ * 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("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);
+}
+
+/**
+ * @primitive b.auth.fal.fromAssertion
+ * @signature b.auth.fal.fromAssertion(opts)
+ * @since     0.8.87
+ * @status    stable
+ *
+ * Classify an incoming federation assertion's FAL band per NIST
+ * 800-63C-4. Returns one of `"FAL1"` / `"FAL2"` / `"FAL3"`. Throws
+ * `auth/bad-fal-opts` on missing required fields.
+ *
+ *   - HoK binding (mTLS client-cert pinned, DPoP-bound, SAML HoK) → FAL3
+ *   - Back-channel delivery OR encrypted-to-RP front-channel +
+ *     replay-protection nonce → FAL2
+ *   - Anything else → FAL1
+ *
+ * The classifier is 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.
+ *
+ * @opts
+ *   channel:           "front" | "back",        // REQUIRED
+ *   encrypted:         boolean,                  // assertion encrypted to RP
+ *   replayProtected:   boolean,                  // nonce / jti / iat binding present
+ *   hokBinding:        "mtls" | "dpop" | "saml-hok" | null,
+ *                                                // proof-of-possession binding present
+ *   bearerOnly:        boolean,                  // alias for hokBinding === null
+ *
+ * @example
+ *   var fal = b.auth.fal.fromAssertion({
+ *     channel:         "back",
+ *     encrypted:       false,
+ *     replayProtected: true,
+ *     hokBinding:      null,
+ *   });
+ *   // → "FAL2"
+ *
+ *   var fal3 = b.auth.fal.fromAssertion({
+ *     channel:         "back",
+ *     hokBinding:      "mtls",
+ *     replayProtected: true,
+ *   });
+ *   // → "FAL3"
+ */
+function fromAssertion(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new AuthError("auth/bad-fal-opts",
+      "fal.fromAssertion: opts required (channel + replayProtected at minimum)");
+  }
+  if (opts.channel !== "front" && opts.channel !== "back") {
+    throw new AuthError("auth/bad-fal-opts",
+      "fal.fromAssertion: channel must be 'front' or 'back'");
+  }
+  var hokBinding = opts.hokBinding;
+  if (hokBinding !== undefined && hokBinding !== null) {
+    if (hokBinding !== "mtls" && hokBinding !== "dpop" && hokBinding !== "saml-hok") {
+      throw new AuthError("auth/bad-fal-opts",
+        "fal.fromAssertion: hokBinding must be 'mtls' | 'dpop' | 'saml-hok' | null");
+    }
+  }
+
+  // FAL3 — Holder-of-Key with replay protection.
+  if (hokBinding && opts.replayProtected === true) {
+    return FAL3;
+  }
+
+  // FAL2 — back-channel OR encrypted front-channel, with replay protection.
+  var replaySafe = opts.replayProtected === true;
+  if (replaySafe && (opts.channel === "back" || opts.encrypted === true)) {
+    return FAL2;
+  }
+
+  // Everything else — FAL1 (bearer front-channel).
+  return FAL1;
+}
+
+/**
+ * @primitive b.auth.fal.requireFal
+ * @signature b.auth.fal.requireFal(minimumBand)
+ * @since     0.8.87
+ * @status    stable
+ * @related   b.auth.fal.fromAssertion
+ *
+ * Build a guard that throws `auth/fal-insufficient` when the
+ * supplied band is below the minimum. The middleware form
+ * (`b.middleware.requireFal`) wraps this guard at the request layer.
+ *
+ * @example
+ *   var fal3Only = b.auth.fal.requireFal("FAL3");
+ *   fal3Only(req.session.federationFal);
+ *   // throws auth/fal-insufficient if not FAL3
+ */
+function requireFal(minimumBand) {
+  validateOpts.requireNonEmptyString(
+    minimumBand, "fal.requireFal.minimumBand", AuthError, "auth/bad-fal-band");
+  if (!isValidBand(minimumBand)) {
+    throw new AuthError("auth/bad-fal-band",
+      "fal.requireFal: minimumBand must be one of " + BANDS.join(", "));
+  }
+  return function falGuard(actualBand) {
+    if (!isValidBand(actualBand) || !meets(actualBand, minimumBand)) {
+      throw new AuthError("auth/fal-insufficient",
+        "fal.requireFal: actual band '" + actualBand + "' does not meet minimum '" + minimumBand + "'");
+    }
+    return actualBand;
+  };
+}
+
+module.exports = {
+  FAL1:           FAL1,
+  FAL2:           FAL2,
+  FAL3:           FAL3,
+  BANDS:          BANDS,
+  isValidBand:    isValidBand,
+  meets:          meets,
+  fromAssertion:  fromAssertion,
+  requireFal:     requireFal,
+};

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/lib/mail.js

@@ -1735,8 +1735,92 @@ function create(opts) {
   };
 }
 
+/**
+ * @primitive b.mail.feedbackId
+ * @signature b.mail.feedbackId(opts)
+ * @since     0.8.87
+ * @status    stable
+ * @related   b.mail.create
+ *
+ * Build a Gmail Feedback Loop (FBL) Feedback-ID header value per
+ * Google's FBL convention: a colon-separated 4-tuple
+ * `CampaignID:CustomerID:MailType:SenderID`. Setting Feedback-ID on
+ * outbound mail lets Gmail surface per-campaign abuse-rate metrics
+ * back via the Postmaster Tools API so operators see spam
+ * complaints aggregated by their own campaign vocabulary instead of
+ * by SMTP envelope-sender alone.
+ *
+ * Refuses missing / empty fields (`mail/bad-feedback-id-field`),
+ * fields containing `:` (would corrupt the 4-tuple separator), and
+ * fields longer than 64 bytes (Gmail truncates beyond ~64 chars per
+ * field). Operators set the result via `mail.create({ headers:
+ * { "Feedback-ID": b.mail.feedbackId({...}) } })` or attach it to
+ * an individual send().
+ *
+ * @opts
+ *   campaignId:  string,   // operator's campaign tag (e.g. "wk26-promo")
+ *   customerId:  string,   // operator's tenant or user-segment id
+ *   mailType:    string,   // operator-defined message type (e.g. "marketing")
+ *   senderId:    string,   // operator's app / IP-pool / domain reputation id
+ *
+ * @example
+ *   var feedbackId = b.mail.feedbackId({
+ *     campaignId: "wk26-promo",
+ *     customerId: "acme",
+ *     mailType:   "marketing",
+ *     senderId:   "mail-pool-1",
+ *   });
+ *   // → "wk26-promo:acme:marketing:mail-pool-1"
+ *
+ *   mail.send({
+ *     to:      "...",
+ *     headers: { "Feedback-ID": feedbackId },
+ *   });
+ */
+function feedbackId(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new MailError("mail/bad-feedback-id-opts",
+      "feedbackId: opts required (campaignId + customerId + mailType + senderId)");
+  }
+  var fields = [
+    { key: "campaignId", value: opts.campaignId },
+    { key: "customerId", value: opts.customerId },
+    { key: "mailType",   value: opts.mailType   },
+    { key: "senderId",   value: opts.senderId   },
+  ];
+  var parts = [];
+  for (var i = 0; i < fields.length; i += 1) {
+    var f = fields[i];
+    if (typeof f.value !== "string" || f.value.length === 0) {
+      throw new MailError("mail/bad-feedback-id-field",
+        "feedbackId: " + f.key + " must be a non-empty string");
+    }
+    if (f.value.length > 64) {                                                                     // allow:raw-byte-literal — Gmail FBL per-field cap, not byte arithmetic
+      throw new MailError("mail/bad-feedback-id-field",
+        "feedbackId: " + f.key + " exceeds 64 chars (Gmail FBL truncation threshold)");
+    }
+    if (f.value.indexOf(":") !== -1) {
+      throw new MailError("mail/bad-feedback-id-field",
+        "feedbackId: " + f.key + " contains ':' which is the field separator");
+    }
+    // Refuse CR/LF (header-injection) + control chars. Walk codepoints
+    // manually because eslint's no-control-regex refuses control-char
+    // ranges in regex literals regardless of escape form.
+    for (var ci = 0; ci < f.value.length; ci += 1) {
+      var code = f.value.charCodeAt(ci);
+      if (code < 32 || code === 127) {                                                             // allow:raw-byte-literal — C0 + DEL codepoint range
+        throw new MailError("mail/bad-feedback-id-field",
+          "feedbackId: " + f.key + " contains control characters");
+      }
+    }
+    parts.push(f.value);
+  }
+  return parts.join(":");
+}
+
 module.exports = {
   create:      create,
+  feedbackId:  feedbackId,
   MailError:   MailError,
   unsubscribe: mailUnsubscribe,
   // RFC 3492 Punycode IDN domain encode/decode (b.mail.toAscii /

package/lib/network-dns.js

@@ -1670,8 +1670,47 @@ function _resetForTest() {
   _resetDotPool();
 }
 
+/**
+ * @primitive b.network.dns.isNullMx
+ * @signature b.network.dns.isNullMx(mxRecords)
+ * @since     0.8.87
+ * @status    stable
+ *
+ * RFC 7505 Null-MX check — returns `true` when the supplied MX
+ * records signal "this domain does not accept email" (a single MX
+ * record with priority 0 and exchange `.`). Operators sending mail
+ * call this before delivery to skip domains that have explicitly
+ * opted out of email. Returns `false` for any other shape (zero
+ * records, multiple records, non-zero priority, non-`.` exchange).
+ *
+ * MX records are expected in the `{ priority, exchange }` shape
+ * returned by `node:dns.resolveMx` (or `b.network.dns.resolve(host,
+ * "MX")`). Operator supplies the records; this is a pure
+ * classifier, no network call.
+ *
+ * @example
+ *   var node = require("node:dns/promises");
+ *   var mx;
+ *   try { mx = await node.resolveMx("example.com"); }
+ *   catch (e) { mx = []; }
+ *   if (b.network.dns.isNullMx(mx)) {
+ *     throw new Error("example.com publishes Null-MX (RFC 7505) — does not accept email");
+ *   }
+ */
+function isNullMx(mxRecords) {
+  if (!Array.isArray(mxRecords) || mxRecords.length !== 1) return false;
+  var only = mxRecords[0];
+  if (!only || typeof only !== "object") return false;
+  if (only.priority !== 0) return false;
+  // node's resolveMx returns the exchange as "" (empty) when the
+  // RDATA is "." (root); other resolvers may keep "." literal. Accept
+  // both.
+  return only.exchange === "" || only.exchange === ".";
+}
+
 module.exports = {
   setServers:                  setServers,
+  isNullMx:                    isNullMx,
   getServers:                  getServers,
   setResultOrder:              setResultOrder,
   setFamily:                   setFamily,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.86",
+  "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:94157e54-2402-4932-84de-96074af286be",
+  "serialNumber": "urn:uuid:75038048-e27a-4af6-a354-0cabce037597",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-11T17:16:07.899Z",
+    "timestamp": "2026-05-11T18:13:26.544Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.86",
+      "bom-ref": "@blamejs/core@0.8.88",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.86",
+      "version": "0.8.88",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.86",
+      "purl": "pkg:npm/%40blamejs/core@0.8.88",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.86",
+      "ref": "@blamejs/core@0.8.88",
       "dependsOn": []
     }
   ]