@blamejs/core 0.8.87 → 0.8.89

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.89 (2026-05-11) — **Hotfix: `b.earlyHints.send()` case-variant link bypass + new `b.mail.srs` Sender Rewriting Scheme**. **Hotfix (PRIMARY)**: pre-v0.8.89, supplying both `link` (lowercase) AND `Link` (capital, or any other case variant) to `b.earlyHints.send()` bypassed the validator. `opts.link` got the dedicated `_validateLink` pass and was assigned to `headers.link`; the trailing header loop then iterated `Object.keys(opts)`, skipped only the exact-match `"link"` key, and for `"Link"` lowercased the name and wrote `headers.link = opts.Link` — overwriting the validated value with unvalidated content. Malformed Link headers (missing `rel=`, unknown relation, oversized) reached `writeEarlyHints()` despite the API contract. The fix collapses all opt keys to a single canonical lowercase map up front; duplicate case-variants of any header (not just `link`) now refuse with `early-hints/duplicate-header` so operators see the collision instead of getting silent winner-take-all behavior. Capital `Link` alone (no lowercase variant) still works — it goes through the same validator. Tests added: case-variant-collision refuse, capital-Link-alone validates, capital-Link with malformed value still throws `bad-link`. **New**: `b.mail.srs.create({ secret, forwarderDomain, expiryDays? })` — Sender Rewriting Scheme (SRS0) implementation for forwarder envelope-from rewriting so the next-hop SPF check passes and bounces route correctly back to the original sender. Returns `{ rewrite, reverse }`. `rewrite(addr)` produces an SRS-encoded `SRS0=HHHH=TT=domain=local@forwarder.example` form; `reverse(srs)` decodes back to the original sender, verifying the HMAC-SHA-256 short-tag (operator-supplied secret), the day-stamp expiry window (default 30 days), and the canonical 4-field SRS0 grammar. Refuses tampered tags via `srs/bad-tag`, expired rewrites via `srs/expired`, double-SRS-encoding via `srs/already-rewritten` (SRS1 wrapping deferred; operator demand TBD), and bad address shapes via `srs/bad-address`. HMAC uses `b.crypto.timingSafeEqual` for tag comparison so the verification side stays constant-time against operator-controlled tag inputs.
+- 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,212 @@
+"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);
+  }
+
+  // Lowercase every key up front so case-variants (`Link`, `LINK`,
+  // `LiNk`) collapse to the same canonical key. Without this pass
+  // a caller could supply both `link` (which gets validated) AND
+  // `Link` (which the validator's `if (name === "link") continue;`
+  // would skip), then the lowercase rewrite in the trailing loop
+  // would overwrite the validated value with unvalidated content.
+  // Refuse the collision explicitly rather than silently pick one;
+  // operators should pass each header exactly once.
+  var canonical = {};
+  var rawKeys = Object.keys(opts);
+  for (var rk = 0; rk < rawKeys.length; rk += 1) {
+    var rawName = rawKeys[rk];
+    var lowerName = rawName.toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(canonical, lowerName)) {
+      throw new EarlyHintsError("early-hints/duplicate-header",
+        "earlyHints.send: duplicate header '" + lowerName + "' " +
+        "(case-variant supplied twice — pass each header exactly once)");
+    }
+    canonical[lowerName] = opts[rawName];
+  }
+
+  var headers = {};
+
+  if (canonical.link === undefined || canonical.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(canonical.link) ? canonical.link : [canonical.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 canonicalKeys = Object.keys(canonical);
+  for (var k = 0; k < canonicalKeys.length; k += 1) {
+    var name = canonicalKeys[k];
+    if (name === "link") continue;
+    if (REFUSED_HEADERS.indexOf(name) !== -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 canonical[name] !== "string" && !Array.isArray(canonical[name])) {
+      throw new EarlyHintsError("early-hints/bad-header-value",
+        "earlyHints.send: header '" + name + "' must be a string or string[]", true);
+    }
+    headers[name] = canonical[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-srs.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * @module     b.mail.srs
+ * @nav        Mail
+ * @title      SRS — Sender Rewriting Scheme
+ * @order      450
+ *
+ * @intro
+ *   Sender Rewriting Scheme (SRS0 / SRS1) — when a forwarder
+ *   retransmits a message it received, SPF on the next hop will
+ *   typically fail because the envelope-from sender is the original
+ *   sender's domain, but the message is now coming from the
+ *   forwarder's IP. SRS rewrites the envelope-from local-part to
+ *   encode the original sender + a HMAC signature; the receiver
+ *   verifies + reverses to deliver bounces correctly.
+ *
+ *   Wire format (SRS0):
+ *
+ *     SRS0=HHH=TT=domain=local@forwarder.example
+ *
+ *   Where:
+ *     - `HHH` is the first 4 chars of base32(HMAC-SHA-256(secret,
+ *       lowercase(TT=domain=local))) — short-tag binding the rewrite
+ *       to the operator's signing secret
+ *     - `TT` is a 2-character base32 day-of-time stamp (mod-1024
+ *       day rotation; rejects rewrites older than ~30 days)
+ *     - `domain` is the original sender's domain
+ *     - `local` is the original sender's local-part
+ *     - `forwarder.example` is the rewriting forwarder's domain
+ *
+ *   SRS1 (double-forward case): when an already-SRS0-encoded address
+ *   gets forwarded a second time, SRS1 wraps the SRS0 envelope
+ *   instead of re-encoding from scratch, preserving the original
+ *   sender chain.
+ *
+ *   `b.mail.srs.create({ secret, forwarderDomain })` returns
+ *   `{ rewrite, reverse }`. `rewrite(originalSender)` produces the
+ *   SRS-encoded address; `reverse(srsAddress)` decodes back to the
+ *   original sender + verifies the HMAC.
+ *
+ * @card
+ *   SRS Sender Rewriting Scheme — forwarder envelope-from rewriting with HMAC-bound day-rotated tags so the next-hop SPF check passes and bounces route correctly back to the original sender.
+ */
+
+var nodeCrypto    = require("node:crypto");
+var blamejsCrypto = require("./crypto");
+var validateOpts  = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var SrsError = defineClass("SrsError", { alwaysPermanent: true });
+
+// SRS spec: 2-char base32 day stamp. The rotation cycle is 1024 days
+// (32 * 32) which is ~2.8 years; valid-window is the operator-supplied
+// expiry (default 30 days).
+var BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
+
+function _base32Encode(buf) {
+  var out = "";
+  var bits = 0;
+  var value = 0;
+  for (var i = 0; i < buf.length; i += 1) {
+    value = (value << 8) | buf[i];                                                                 // allow:raw-byte-literal — byte-aligned shift
+    bits += 8;                                                                                     // allow:raw-byte-literal — bits-per-byte constant
+    while (bits >= 5) {
+      out += BASE32.charAt((value >>> (bits - 5)) & 31);
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += BASE32.charAt((value << (5 - bits)) & 31);
+  return out;
+}
+
+function _hashTag(secret, hashInput) {
+  var mac = nodeCrypto.createHmac("sha256", secret).update(hashInput.toLowerCase(), "utf8").digest();
+  return _base32Encode(mac.subarray(0, 4)).slice(0, 4);                                            // allow:raw-byte-literal — SRS spec 4-char short-tag
+}
+
+function _dayStamp(nowMs) {
+  // Days since epoch, mod 1024. Two-char base32 = 1024 possible values.
+  var days = Math.floor(nowMs / 86400000) % 1024;                                                  // allow:raw-byte-literal — ms-per-day + mod-1024 SRS rotation
+  return BASE32.charAt(days >>> 5) + BASE32.charAt(days & 31);                                     // allow:raw-byte-literal — 5-bit base32 split
+}
+
+function _dayDiff(stamp, nowMs) {
+  if (typeof stamp !== "string" || stamp.length !== 2) return Infinity;
+  var hi = BASE32.indexOf(stamp.charAt(0));
+  var lo = BASE32.indexOf(stamp.charAt(1));
+  if (hi < 0 || lo < 0) return Infinity;
+  var stampVal = (hi << 5) | lo;                                                                   // allow:raw-byte-literal — 5-bit base32 split
+  var nowVal = Math.floor(nowMs / 86400000) % 1024;                                                // allow:raw-byte-literal — ms-per-day + mod-1024 rotation
+  // Modular distance — assume positive (rewrites in the future are
+  // refused via _dayDiff > 0 callers).
+  var diff = (nowVal - stampVal + 1024) % 1024;                                                    // allow:raw-byte-literal — mod-1024 rotation
+  return diff;
+}
+
+/**
+ * @primitive b.mail.srs.create
+ * @signature b.mail.srs.create(opts)
+ * @since     0.8.89
+ * @status    stable
+ *
+ * Build an SRS rewriter bound to the operator's forwarder domain +
+ * HMAC signing secret. Returns `{ rewrite, reverse }`.
+ *
+ * @opts
+ *   secret:           string,   // operator's HMAC-SHA-256 signing secret (>=32 bytes recommended)
+ *   forwarderDomain:  string,   // the forwarder's own domain (where bounces land)
+ *   expiryDays:       number,   // default 30 — reject reverse() of rewrites older than this
+ *
+ * @example
+ *   var srs = b.mail.srs.create({
+ *     secret:          b.crypto.generateToken(64),
+ *     forwarderDomain: "forwarder.example",
+ *   });
+ *
+ *   // Inbound: alice@bob.com → forwarder → carol@dest.com
+ *   var rewritten = srs.rewrite("alice@bob.com");
+ *   // → "SRS0=HHHH=TT=bob.com=alice@forwarder.example"
+ *
+ *   // Bounce arrives back at SRS0=...; decode to deliver
+ *   var original = srs.reverse(rewritten);
+ *   // → "alice@bob.com"
+ */
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new SrsError("srs/bad-opts",
+      "srs.create: opts required (secret + forwarderDomain)", true);
+  }
+  validateOpts.requireNonEmptyString(
+    opts.secret, "srs.create.secret", SrsError, "srs/bad-secret");
+  validateOpts.requireNonEmptyString(
+    opts.forwarderDomain, "srs.create.forwarderDomain", SrsError, "srs/bad-forwarder");
+  if (opts.secret.length < 16) {                                                                   // allow:raw-byte-literal — minimum HMAC secret length
+    throw new SrsError("srs/bad-secret",
+      "srs.create: secret must be >= 16 chars (operator-supplied entropy floor)");
+  }
+  var expiryDays = opts.expiryDays !== undefined ? opts.expiryDays : 30;                           // allow:raw-byte-literal — default expiry window in days
+  if (typeof expiryDays !== "number" || !Number.isInteger(expiryDays) ||
+      expiryDays < 1 || expiryDays > 1024) {                                                       // allow:raw-byte-literal — SRS rotation cycle cap
+    throw new SrsError("srs/bad-expiry",
+      "srs.create: expiryDays must be an integer 1..1024 (SRS rotation cycle)");
+  }
+  var secret = opts.secret;
+  var forwarderDomain = opts.forwarderDomain;
+
+  function rewrite(originalAddress, nowMs) {
+    validateOpts.requireNonEmptyString(
+      originalAddress, "srs.rewrite.address", SrsError, "srs/bad-address");
+    var at = originalAddress.lastIndexOf("@");
+    if (at <= 0 || at === originalAddress.length - 1) {
+      throw new SrsError("srs/bad-address",
+        "srs.rewrite: address must be in localPart@domain form");
+    }
+    var localPart = originalAddress.slice(0, at);
+    var domain    = originalAddress.slice(at + 1);
+    if (localPart.length > 64 || domain.length > 253) {                                            // allow:raw-byte-literal — RFC 5321 local-part / domain caps
+      throw new SrsError("srs/bad-address",
+        "srs.rewrite: localPart / domain exceeds RFC 5321 length cap");
+    }
+    // Refuse SRS double-encoding from this primitive — operator must
+    // use srs1Rewrite() for already-SRS0 inputs (deferred per the
+    // v1-defensible decision: SRS1 wrapping is rare in operator
+    // deployments and adds substantial spec surface).
+    if (/^SRS[01]=/i.test(localPart)) {
+      throw new SrsError("srs/already-rewritten",
+        "srs.rewrite: address already SRS-encoded; chain forwarding through SRS1 is not yet supported (operator demand TBD)");
+    }
+    var now = typeof nowMs === "number" ? nowMs : Date.now();
+    var ts  = _dayStamp(now);
+    var hashInput = ts + "=" + domain + "=" + localPart;
+    var tag = _hashTag(secret, hashInput);
+    return "SRS0=" + tag + "=" + ts + "=" + domain + "=" + localPart + "@" + forwarderDomain;
+  }
+
+  function reverse(srsAddress, nowMs) {
+    validateOpts.requireNonEmptyString(
+      srsAddress, "srs.reverse.address", SrsError, "srs/bad-address");
+    var at = srsAddress.lastIndexOf("@");
+    if (at <= 0 || at === srsAddress.length - 1) {
+      throw new SrsError("srs/bad-address",
+        "srs.reverse: address must be in srsLocal@forwarder form");
+    }
+    var localPart  = srsAddress.slice(0, at);
+    var rcptDomain = srsAddress.slice(at + 1);
+    // Allow case-insensitive SRS0 prefix per the spec. Check this
+    // FIRST so an obviously-non-SRS0 input (`plain@example.com`)
+    // gets the specific not-srs0 verdict instead of the more general
+    // wrong-forwarder verdict.
+    if (!/^SRS0=/i.test(localPart)) {
+      throw new SrsError("srs/not-srs0",
+        "srs.reverse: address local-part does not start with SRS0=");
+    }
+    // Domain binding — the rewriter is scoped to a specific forwarder
+    // domain, and reverse() must verify the bounce arrived at THAT
+    // domain. Otherwise an SRS0 local-part signed with the same
+    // secret but addressed to a different forwarder (multi-domain
+    // deployment, or a misrouted DNS record) would still verify, and
+    // the operator would mis-deliver the bounce. RFC 5321 §2.3.5
+    // says domains are case-insensitive, so compare lowercased.
+    if (rcptDomain.toLowerCase() !== forwarderDomain.toLowerCase()) {
+      throw new SrsError("srs/wrong-forwarder",
+        "srs.reverse: bounce addressed to '" + rcptDomain + "' but rewriter " +
+        "is bound to forwarderDomain '" + forwarderDomain + "'");
+    }
+    var rest = localPart.slice(5);
+    var parts = rest.split("=");
+    if (parts.length < 4) {
+      throw new SrsError("srs/malformed",
+        "srs.reverse: expected SRS0=tag=ts=domain=local local-part shape (need >= 4 '=' fields)");
+    }
+    var tag = parts[0];
+    var ts  = parts[1];
+    var origDomain = parts[2];
+    var origLocal  = parts.slice(3).join("=");      // local-part may itself contain '='
+    // Verify tag.
+    var hashInput = ts + "=" + origDomain + "=" + origLocal;
+    var expectedTag = _hashTag(secret, hashInput);
+    if (!_timingSafeStringEqual(tag, expectedTag)) {
+      throw new SrsError("srs/bad-tag",
+        "srs.reverse: HMAC tag does not verify (wrong secret or tampered envelope-from)");
+    }
+    // Verify expiry window.
+    var now = typeof nowMs === "number" ? nowMs : Date.now();
+    var dayDiff = _dayDiff(ts, now);
+    if (dayDiff > expiryDays) {
+      throw new SrsError("srs/expired",
+        "srs.reverse: rewrite is " + dayDiff + " days old; expiry window is " + expiryDays + " days");
+    }
+    return origLocal + "@" + origDomain;
+  }
+
+  return Object.freeze({
+    rewrite:  rewrite,
+    reverse:  reverse,
+    forwarderDomain: forwarderDomain,
+  });
+}
+
+function _timingSafeStringEqual(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  return blamejsCrypto.timingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+
+module.exports = {
+  create:   create,
+  SrsError: SrsError,
+};

package/lib/mail.js

@@ -1818,9 +1818,12 @@ function feedbackId(opts) {
   return parts.join(":");
 }
 
+var mailSrs = require("./mail-srs");
+
 module.exports = {
   create:      create,
   feedbackId:  feedbackId,
+  srs:         mailSrs,
   MailError:   MailError,
   unsubscribe: mailUnsubscribe,
   // RFC 3492 Punycode IDN domain encode/decode (b.mail.toAscii /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.87",
+  "version": "0.8.89",
   "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:76b81036-9214-4a75-8cc8-d7f4aa841982",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-11T17:46:06.986Z",
+    "timestamp": "2026-05-11T18:49:35.055Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.87",
+      "bom-ref": "@blamejs/core@0.8.89",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.87",
+      "version": "0.8.89",
       "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.89",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.87",
+      "ref": "@blamejs/core@0.8.89",
       "dependsOn": []
     }
   ]