@blamejs/core 0.8.88 → 0.8.90

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.90 (2026-05-11) — **RFC 8689 REQUIRETLS support** (`b.mail.requireTls`). Per-message TLS-requirement signaling between sender and receiver MTAs. Complements MTA-STS / DANE (policy-side, domain-scoped) with a per-message knob that overrides policy when the operator wants stricter-than-policy delivery — message bounces instead of falling back to cleartext if no downstream MTA can deliver under TLS. **`peerSupports(ehloLines)`**: walks a parsed EHLO response and returns `true` when the peer advertised the `REQUIRETLS` keyword; case-insensitive per RFC 5321 §2.4; refuses substring matches (`FOO-REQUIRETLS-BAR` does NOT match); empty / non-array input returns `false`. **`mailFromExtension({ requireTls })`**: builds the trailing `" REQUIRETLS"` token to append to a MAIL FROM line; refuses non-boolean flag value (a truthy-but-wrong-shape value like `"yes"` throws instead of silently succeeding). **`parseTlsRequiredHeader(headerValue)`**: parses the RFC 8689 §5 `TLS-Required` header — returns `"no"` only when the value is the literal token `no` (case-insensitive, ignoring whitespace) per spec; any other non-empty value returns `"yes"` (RFC 8689 §5: "any value other than 'No' MUST be treated as if the field had been absent" — conservative strict path); returns `null` for absent / empty / non-string input; refuses control characters on the **raw** header value before `trim()` runs so a leading `\n` / trailing `\r` / NUL / DEL byte can no longer slip past as the literal token `no` (ASCII HT remains permitted as structural folding whitespace).
+- 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. Domain-binding check: `reverse(srs)` refuses with `srs/wrong-forwarder` when the SRS0 address's `@domain` part doesn't match the rewriter's `forwarderDomain` (case-insensitive per RFC 5321 §2.3.5) so a tag signed with the same secret but addressed to a different forwarder domain can no longer be accepted. Refuses tampered tags via `srs/bad-tag`, expired rewrites via `srs/expired`, double-SRS-encoding via `srs/already-rewritten`, 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.

package/lib/early-hints.js

@@ -120,13 +120,34 @@ function send(res, 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 (opts.link === undefined || opts.link === null) {
+  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(opts.link) ? opts.link : [opts.link];
+  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);
@@ -136,21 +157,20 @@ function send(res, opts) {
   }
   headers.link = linkArr;
 
-  var keys = Object.keys(opts);
-  for (var k = 0; k < keys.length; k += 1) {
-    var name = keys[k];
+  var canonicalKeys = Object.keys(canonical);
+  for (var k = 0; k < canonicalKeys.length; k += 1) {
+    var name = canonicalKeys[k];
     if (name === "link") continue;
-    var lower = name.toLowerCase();
-    if (REFUSED_HEADERS.indexOf(lower) !== -1) {
+    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 opts[name] !== "string" && !Array.isArray(opts[name])) {
+    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[lower] = opts[name];
+    headers[name] = canonical[name];
   }
 
   try {

package/lib/mail-require-tls.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * @module     b.mail.requireTls
+ * @nav        Mail
+ * @title      REQUIRETLS — RFC 8689
+ * @order      460
+ *
+ * @intro
+ *   RFC 8689 SMTP REQUIRETLS — per-message TLS-requirement signaling
+ *   between sender and receiver MTAs. The sender advertises that the
+ *   message MUST NOT be relayed over a cleartext (non-TLS) hop; if
+ *   no downstream MTA can deliver under TLS, the message bounces
+ *   instead of falling back to cleartext. Complements MTA-STS / DANE
+ *   (which are policy-side, domain-scoped) with a per-message
+ *   knob that overrides the policy when the operator wants
+ *   stricter-than-policy delivery.
+ *
+ *   Wire surface (RFC 8689 §3):
+ *
+ *     EHLO peer advertises:  250 REQUIRETLS
+ *     Client sends:          MAIL FROM:<sender> REQUIRETLS
+ *     Server replies:        250 OK             (or 550 if it can't honor)
+ *
+ *   Header surface (RFC 8689 §5):
+ *
+ *     TLS-Required: No       Explicit operator override; sender
+ *                            requests REQUIRETLS-style behavior be
+ *                            DISABLED for this message even if the
+ *                            policy infrastructure (MTA-STS / DANE)
+ *                            says otherwise. Use sparingly — primary
+ *                            use case is delivery to legacy peers
+ *                            during a controlled migration.
+ *
+ *   This module ships:
+ *
+ *     b.mail.requireTls.peerSupports(ehloLines) → boolean
+ *       Walks EHLO response lines and returns true when the peer
+ *       advertised the REQUIRETLS keyword.
+ *
+ *     b.mail.requireTls.mailFromExtension({ requireTls }) → string
+ *       Returns the trailing " REQUIRETLS" token (or empty string)
+ *       to append to a MAIL FROM line.
+ *
+ *     b.mail.requireTls.parseTlsRequiredHeader(headerValue) → "yes" | "no" | null
+ *       Parses the TLS-Required header field per §5. Returns "no"
+ *       only when the value is the literal token "no" (case-
+ *       insensitive); any other value returns "yes" (the conservative
+ *       default — operators must opt OUT explicitly, never default to
+ *       fall-back-to-cleartext). null when the header is absent.
+ *
+ * @card
+ *   RFC 8689 REQUIRETLS — per-message TLS-requirement signaling between MTAs (EHLO keyword + MAIL FROM extension + TLS-Required header parser).
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var RequireTlsError = defineClass("RequireTlsError", { alwaysPermanent: true });
+
+var REQUIRETLS_TOKEN = "REQUIRETLS";
+
+/**
+ * @primitive b.mail.requireTls.peerSupports
+ * @signature b.mail.requireTls.peerSupports(ehloLines)
+ * @since     0.8.90
+ * @status    stable
+ *
+ * Walk a parsed EHLO response and return `true` when the peer
+ * advertised the `REQUIRETLS` keyword. `ehloLines` is the array of
+ * post-greeting capability lines returned by the SMTP transport
+ * (each entry is the capability token, e.g. `"SIZE 10485760"`,
+ * `"PIPELINING"`, `"REQUIRETLS"`). Case-insensitive match per RFC
+ * 5321 §2.4 (EHLO keywords are uppercase by convention but
+ * comparison is case-insensitive).
+ *
+ * Returns `false` for empty / non-array input — operators who can't
+ * parse the EHLO get a definitive "not supported" verdict rather
+ * than a throw, matching the "defensive request-shape reader"
+ * convention used elsewhere.
+ *
+ * @example
+ *   var ehlo = ["mail.example.com", "PIPELINING", "SIZE 10485760", "REQUIRETLS", "STARTTLS"];
+ *   b.mail.requireTls.peerSupports(ehlo);  // → true
+ *
+ *   b.mail.requireTls.peerSupports(["PIPELINING", "SIZE 10485760"]);  // → false
+ */
+function peerSupports(ehloLines) {
+  if (!Array.isArray(ehloLines)) return false;
+  for (var i = 0; i < ehloLines.length; i += 1) {
+    var line = ehloLines[i];
+    if (typeof line !== "string") continue;
+    // Keyword is everything up to the first space (RFC 5321 §4.1.1.1).
+    var sp = line.indexOf(" ");
+    var keyword = sp === -1 ? line : line.slice(0, sp);
+    if (keyword.toUpperCase() === REQUIRETLS_TOKEN) return true;
+  }
+  return false;
+}
+
+/**
+ * @primitive b.mail.requireTls.mailFromExtension
+ * @signature b.mail.requireTls.mailFromExtension(opts)
+ * @since     0.8.90
+ * @status    stable
+ *
+ * Build the trailing SMTP MAIL FROM extension token for REQUIRETLS.
+ * Returns `" REQUIRETLS"` (with a leading space, ready to append)
+ * when `opts.requireTls === true`; empty string otherwise. The
+ * primitive does NOT validate the operator's address — that's the
+ * SMTP transport's job. This only emits the standard-defined token
+ * suffix.
+ *
+ * Refuses non-object opts. `requireTls` must be a boolean when
+ * provided (any other type throws `mail-require-tls/bad-flag`) so
+ * a truthy-but-wrong-shape value (e.g. `"yes"`) doesn't silently
+ * succeed.
+ *
+ * @opts
+ *   requireTls: boolean,   // true to emit " REQUIRETLS"; falsy/absent → ""
+ *
+ * @example
+ *   var line = "MAIL FROM:<alice@example.com>" +
+ *              b.mail.requireTls.mailFromExtension({ requireTls: true });
+ *   // → "MAIL FROM:<alice@example.com> REQUIRETLS"
+ */
+function mailFromExtension(opts) {
+  if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+    throw new RequireTlsError("mail-require-tls/bad-opts",
+      "mailFromExtension: opts must be a non-null object", true);
+  }
+  if (opts.requireTls === undefined || opts.requireTls === false) return "";
+  if (opts.requireTls !== true) {
+    throw new RequireTlsError("mail-require-tls/bad-flag",
+      "mailFromExtension: requireTls must be a boolean (got " + typeof opts.requireTls + ")");
+  }
+  return " " + REQUIRETLS_TOKEN;
+}
+
+/**
+ * @primitive b.mail.requireTls.parseTlsRequiredHeader
+ * @signature b.mail.requireTls.parseTlsRequiredHeader(headerValue)
+ * @since     0.8.90
+ * @status    stable
+ *
+ * Parse the RFC 8689 §5 `TLS-Required` header field. Returns:
+ *
+ *   - `"no"` when the value is the literal token `no` (case-
+ *     insensitive, ignoring surrounding whitespace) — the sender
+ *     EXPLICITLY opts out of REQUIRETLS-style behavior for this
+ *     message.
+ *   - `"yes"` for any other non-empty value — conservative default
+ *     so an operator who set a typo / malformed value still gets
+ *     the strict path (RFC 8689 §5: "if a recipient receives a
+ *     message containing a TLS-Required field with any value other
+ *     than 'No', it MUST be treated as if the field had been
+ *     absent").
+ *   - `null` when the header is absent / empty / not a string —
+ *     operator code branches on null vs "yes" / "no".
+ *
+ * Refuses CR / LF / NUL in the value (header-injection-shape inputs
+ * shouldn't reach a parser that's downstream of header splitters
+ * anyway, but a defensive check here catches operator-side mistakes).
+ *
+ * @example
+ *   b.mail.requireTls.parseTlsRequiredHeader("No");      // → "no"
+ *   b.mail.requireTls.parseTlsRequiredHeader("no");      // → "no"
+ *   b.mail.requireTls.parseTlsRequiredHeader("  no  ");  // → "no"
+ *   b.mail.requireTls.parseTlsRequiredHeader("yes");     // → "yes"
+ *   b.mail.requireTls.parseTlsRequiredHeader("anything"); // → "yes" (RFC 8689 §5 default)
+ *   b.mail.requireTls.parseTlsRequiredHeader("");        // → null
+ *   b.mail.requireTls.parseTlsRequiredHeader(undefined); // → null
+ */
+function parseTlsRequiredHeader(headerValue) {
+  if (typeof headerValue !== "string") return null;
+  // Refuse control characters defensively on the RAW value — scanning
+  // after trim() would strip leading/trailing \r\n\t etc. before the
+  // check ran, letting a header-injection-shape input like "\nno" or
+  // "no\r" slip past as the literal "no" token. Validate the original
+  // string so the contract ("control bytes are refused") holds for any
+  // position in the value.
+  for (var i = 0; i < headerValue.length; i += 1) {
+    var code = headerValue.charCodeAt(i);
+    // ASCII HT (0x09) is structural folding whitespace in HTTP/email
+    // headers — strip-equivalent at the parser layer, so the trim()
+    // below absorbs it. Everything else in C0 + DEL is rejected.
+    if (code === 9) continue;                                                                       // allow:raw-byte-literal — ASCII HT codepoint
+    if (code < 32 || code === 127) {                                                               // allow:raw-byte-literal — C0 + DEL codepoint range
+      throw new RequireTlsError("mail-require-tls/bad-header-value",
+        "parseTlsRequiredHeader: value contains control characters");
+    }
+  }
+  var trimmed = headerValue.trim();
+  if (trimmed.length === 0) return null;
+  if (trimmed.toLowerCase() === "no") return "no";
+  // RFC 8689 §5 — any other value treated as if absent (strict path).
+  return "yes";
+}
+
+module.exports = {
+  peerSupports:            peerSupports,
+  mailFromExtension:       mailFromExtension,
+  parseTlsRequiredHeader:  parseTlsRequiredHeader,
+  REQUIRETLS_TOKEN:        REQUIRETLS_TOKEN,
+  RequireTlsError:         RequireTlsError,
+};
+
+// Reserved for future field validation paths; kept in canonical
+// require ordering.
+void validateOpts;

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,14 @@ function feedbackId(opts) {
   return parts.join(":");
 }
 
+var mailRequireTls = require("./mail-require-tls");
+var mailSrs        = require("./mail-srs");
+
 module.exports = {
   create:      create,
   feedbackId:  feedbackId,
+  requireTls:  mailRequireTls,
+  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.88",
+  "version": "0.8.90",
   "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:75038048-e27a-4af6-a354-0cabce037597",
+  "serialNumber": "urn:uuid:860a5246-eb35-4113-adf2-886982273421",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-11T18:13:26.544Z",
+    "timestamp": "2026-05-11T19:04:39.738Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.88",
+      "bom-ref": "@blamejs/core@0.8.90",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.88",
+      "version": "0.8.90",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.88",
+      "purl": "pkg:npm/%40blamejs/core@0.8.90",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.88",
+      "ref": "@blamejs/core@0.8.90",
       "dependsOn": []
     }
   ]