@blamejs/core 0.9.38 → 0.9.40

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.40 (2026-05-15) — **`b.guardListId` — RFC 2919 List-Id header validator.** Companion to v0.9.39 `b.guardListUnsubscribe`; gates outbound mailing-list mail so the List-Id carries a well-formed identifier downstream filters + bulk-sender pipelines reliably route on. (1) **`b.guardListId.validate(headerValue, opts?)`** — parses bracketed (`<my-list.example.com>`), phrase-prefixed (`My Newsletter <my-list.example.com>`), and bare-identifier forms per RFC 2919 §2. Returns `{ action, listId, label, namespace, phrase, reason }`. Action one of `accept` / `refuse`. (2) **RFC 2919 §3 caps + ABNF** — list-id capped at 255 octets; header value capped at RFC 5322 §2.1.1 line cap (998 bytes); per-label shape per RFC 5322 §3.2.3 dot-atom-text. (3) **Phrase-smuggling defense** — phrase MUST NOT contain `<` / `>` (would smuggle a second bracketed identifier through the parser). Trailing content after `>` refused. Nested or unmatched brackets refused. (4) **CRLF / NUL / C0 / DEL refusal** — header-injection defense per RFC 5322 §3.2.5 + CVE-2026-32178 wire-protocol surface class. (5) **`localhost` namespace handling** (RFC 2919 §3) — strict requires the recommended 32-hex random component in the label (the SHOULD becomes operator-strict for HIPAA / PCI / GDPR / SOC2 postures); balanced / permissive accept without. (6) **FQDN namespace enforcement** under strict / balanced — list-id with single-label namespace (e.g. `mylist.test`) refused unless permissive. (7) Heuristic label / namespace split — last 2 dot-segments → namespace (matches typical DNS delegation); consumers needing PSL-accurate org-domain extraction compose `b.publicSuffix.organizationalDomain`. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-list-id.fuzz.js`. Registered as standalone guard with `KIND="list-id"`. Threat-model: List-Id forging (RFC 2919 §8 explicitly notes the identifier is NOT an authentication signal; operators wanting authentication compose b.mail.auth.dmarc / arc.verify), bulk-sender bucket-drop (Gmail 2024 keys on List-Id presence for Precedence: list / 5000+ daily-send mail).
+- v0.9.39 (2026-05-15) — **`b.guardListUnsubscribe` — RFC 2369 + RFC 8058 List-Unsubscribe / List-Unsubscribe-Post validator.** Gates the outbound submission path so messages carrying a List-Id (or any mailing-list shape) emit headers Gmail / Yahoo / Outlook one-click unsubscribe machinery actually accepts. (1) **`b.guardListUnsubscribe.validate({ listUnsubscribe, listUnsubscribePost }, opts?)`** — returns `{ action, reason, uris, hasHttpsUri, hasMailtoUri, postHeaderOk, oneClickReady }`. (2) **Gmail / Yahoo bulk-sender 2024 enforcement** — under strict requires at least one `https://` URI in the header (mailto: alone refused) + the paired `List-Unsubscribe-Post: List-Unsubscribe=One-Click` value EXACTLY (case-sensitive — Gmail silently fails one-click on mixed-case variants). (3) **Always-refused schemes** — `javascript:` / `data:` / `file:` / `vbscript:` / `blob:` refused regardless of profile (XSS / file-read class in mail-client rendering). (4) **`http://` refused under strict / balanced** — one-click endpoint MUST be TLS per RFC 8058 §2. Permissive accepts http for audit-only legacy use. (5) **Header-injection defense** — CRLF, NUL, C0 controls, DEL refused at validate time (RFC 5322 §3.2.5). (6) **Bounded surface** — per-URI byte cap (2 KiB strict / 4 KiB permissive), URI-count cap (4 / 8 / 16), header total byte cap (4 / 4 / 8 KiB). RFC 3986 §3.1 scheme shape; RFC 2369 §3.1 angle-bracket URI list. HTTPS URIs validated through `b.safeUrl.parse` with the framework's HTTPS allowlist. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-list-unsubscribe.fuzz.js`. Registered as a standalone guard with KIND="list-unsubscribe". Threat-model coverage: unsubscribe-link injection via AI-generated newsletter templates, open-redirect via List-Unsubscribe (operator validates target host downstream via own safeRedirect allowlist), mail-client mishandling (Outlook's mailto: auto-fetch history).
 - v0.9.38 (2026-05-15) — **Re-publish bundle: prefix npm tarball path with `./` so npm doesn't mis-classify it as a git spec.** v0.9.30 and v0.9.37 publish workflow runs both failed at exit 128 — npm 10+ interprets a relative tarball path containing `/` (`dist/blamejs-core-0.9.X.tgz`) as a git spec and attempts `git ls-remote ssh://git@github.com/dist/...tgz`, which the runner's SSH credentials can't auth against. v0.9.29-v0.9.37 never reached npm as a result; v0.9.28 remained the latest published version on the registry. v0.9.38 ships only the workflow path fix (no operator-facing primitive change vs v0.9.37) — operators upgrading from v0.9.28 see the full bundled surface delivered by v0.9.29-v0.9.37: agent.trace + agent.snapshot (v0.9.29 / v0.9.30), safeDns + network.dns.resolver (v0.9.31), guardSmtpCommand (v0.9.32), mail.rbl (v0.9.33), mail.greylist + lib/ip-utils (v0.9.34), mail.helo (v0.9.35), guardEnvelope (v0.9.36), guardDsn (v0.9.37).
 - v0.9.37 (2026-05-15) — **`b.guardDsn` — RFC 3464 Delivery Status Notification parser.** Reads the `message/delivery-status` MIME-part body bounces / delayed-delivery notices / successful-delivery confirmations carry and surfaces the per-recipient action + RFC 3463 enhanced status code so operator-side delivery-failure routing (`b.mail.bounce` retry curve, address-book invalidation, mailing-list cleanup, transactional-mail dead-letter) reads one shape regardless of MTA wording. (1) **`b.guardDsn.parse(deliveryStatusBody, opts?)`** — returns `{ perMessage: { reportingMta, originalEnvelopeId?, arrivalDate?, receivedFromMta? }, perRecipients: [{ finalRecipient, action, status, statusClass, diagnosticCode? }, ...], worstStatusClass, action }`. (2) **RFC 3464 mandatory-field enforcement** — Reporting-MTA required per §2.2.2; per-recipient Final-Recipient (§2.3.2), Action (§2.3.3) from `{ failed | delayed | delivered | relayed | expanded }` vocabulary, and Status (§2.3.4) in RFC 3463 `D.D.D` form all required. Missing-field → typed error (`guard-dsn/missing-{reporting-mta|final-recipient|action|status}`). (3) **RFC 3463 status-class verdict** — first digit drives routing: `2.x.y` → success / deliver; `4.x.y` → temporary / retry; `5.x.y` → permanent / invalidate. Worst class across recipients wins so a single permanent failure in a multi-recipient bounce flips `action: invalidate`. (4) **Defenses** — bounded body cap (256 KiB strict / 1 MiB balanced / 4 MiB permissive), per-DSN recipient cap (256 / 1024 / 4096), RFC 5322 §2.1.1 header-line cap (998 bytes), CRLF / NUL / C0 / DEL refusal for header-injection defense (CVE-2026-32178 .NET System.Net.Mail class on the inbound parse path). (5) **RFC 5322 §2.2 continuation lines** — values can wrap onto subsequent lines starting with whitespace; parser folds correctly. (6) **`rfc822;` address-type prefix** stripped per RFC 3464 §2.3.2 so consumers see canonical mailbox form. Three profiles + posture cascade (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-dsn.fuzz.js`.
 - v0.9.36 (2026-05-15) — **`b.guardEnvelope` — RFC 7489 §3.1 DMARC Identifier Alignment validator.** Focused gate exposing JUST the From-header-vs-SPF/DKIM alignment primitive so the v0.9.36 MX listener can short-circuit on alignment fail before the full DMARC TXT lookup, and operator middleware composing custom anti-spoofing policy can reuse alignment without dragging in the full `b.mail.auth.dmarc` orchestrator. (1) **`b.guardEnvelope.check(ctx, opts?)`** — ctx carries `fromHeaderDomain` + `spfResult: { result, domain }` + `dkimResults: [{ result, signingDomain }]`. Returns `{ spf, dkim, aligned, action }` — `aligned: true` when at least one of SPF/DKIM is identifier-aligned (RFC 7489 §3.1: From-domain matches SPF MailFrom OR DKIM d= under chosen mode). (2) **Strict vs relaxed match** (RFC 7489 §3.1.1 / §3.1.2) — strict requires exact FQDN match, relaxed (RFC 7489 §6.2 default) requires same organizational domain via `b.publicSuffix.organizationalDomain` (Public Suffix List). Per-call override via `spfMode: strict | relaxed` + `dkimMode`. (3) **Verdict shape** — `spf: { aligned, mode, domain, fromDomain, spfPass }`, `dkim: [<verdict>...]` (one per signature so multi-signer messages with mixed pass/fail are visible), `aligned: bool` (any-of), `action: accept | refuse`. Strict + balanced profiles refuse on alignment fail; permissive computes alignment but always accepts (operator score-tags downstream). (4) **CVE / threat model** — envelope-vs-header spoofing: `MAIL FROM:<service@aws-bounces.com>` passes SPF for aws-bounces.com but `From: payments@your-bank.example` — refused under strict. Public-suffix confusion: attacker can't claim `co.uk` as an org domain because PSL classifies it as a public suffix; `victim.co.uk` vs `attacker.co.uk` have different effective org domains. Same-org-different-subdomain attack under strict mode (operator opts to relaxed for legitimate cross-subdomain mail). (5) Posture cascades (hipaa / pci-dss / gdpr / soc2 → strict). Fuzz harness ships in `fuzz/guard-envelope.fuzz.js`. Registered as a standalone guard via `KIND: "envelope-alignment"` and NAME: "envelope".

package/index.js

@@ -164,6 +164,8 @@ var guardMessageId = require("./lib/guard-message-id");
 var guardSmtpCommand = require("./lib/guard-smtp-command");
 var guardEnvelope = require("./lib/guard-envelope");
 var guardDsn = require("./lib/guard-dsn");
+var guardListUnsubscribe = require("./lib/guard-list-unsubscribe");
+var guardListId = require("./lib/guard-list-id");
 var guardMailQuery = require("./lib/guard-mail-query");
 var guardMailCompose = require("./lib/guard-mail-compose");
 var guardMailReply = require("./lib/guard-mail-reply");
@@ -432,6 +434,8 @@ module.exports = {
   guardSmtpCommand: guardSmtpCommand,
   guardEnvelope:    guardEnvelope,
   guardDsn:         guardDsn,
+  guardListUnsubscribe: guardListUnsubscribe,
+  guardListId:      guardListId,
   guardMailQuery:   guardMailQuery,
   guardMailCompose: guardMailCompose,
   guardMailReply:   guardMailReply,

package/lib/guard-list-id.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * @module     b.guardListId
+ * @nav        Guards
+ * @title      Guard List-Id
+ * @order      466
+ *
+ * @intro
+ *   RFC 2919 `List-Id` header validator. Companion to
+ *   `b.guardListUnsubscribe`; gates the outbound submission path so
+ *   mailing-list mail carries a well-formed list identifier that
+ *   downstream mail-client filters + bulk-sender pipelines can
+ *   reliably route on.
+ *
+ *   ## RFC 2919 §2 ABNF
+ *
+ *   ```
+ *   list-id           = list-label "." list-id-namespace
+ *   list-label        = dot-atom-text       (RFC 5322)
+ *   list-id-namespace = domain-name / "localhost"
+ *   ```
+ *
+ *   Headers MAY surround the identifier in angle brackets and
+ *   prepend a phrase + comment:
+ *
+ *   ```
+ *   List-Id: My Newsletter <my-newsletter.example.com>
+ *   List-Id: (Comment text) <list-12345.example.com>
+ *   ```
+ *
+ *   This validator parses both bare-identifier and bracketed forms,
+ *   refusing the address-list-injection class.
+ *
+ *   ## Defenses
+ *
+ *   - **Length cap** — RFC 2919 §3 caps the list identifier at 255
+ *     octets. Total header value capped at 998 bytes per RFC 5322
+ *     §2.1.1 line cap.
+ *   - **CRLF + control-char refusal** — header-injection defense
+ *     (CVE-2026-32178 .NET System.Net.Mail class on the wire-protocol
+ *     surface; this primitive's job is the SEMANTIC shape).
+ *   - **Phrase-injection refusal** — Operator-supplied display
+ *     phrase mustn't carry CRLF / `<` / `>` outside the angle
+ *     brackets (a separate Bcc/Cc header smuggled into the phrase
+ *     fails the parse).
+ *   - **Domain shape** — dot-atom-text per RFC 5322 §3.2.3; LDH
+ *     labels per RFC 5321 §2.3.5; at least one `.` separator
+ *     (rejects bare `mylist` claims).
+ *   - **`localhost` namespace** — RFC 2919 §3 permits, but operator
+ *     MUST also carry the recommended 32-hex random component when
+ *     using `localhost`. Strict refuses unmanaged identifiers
+ *     missing the randomness suffix (`SHOULD` semantics).
+ *
+ *   ## CVE / threat model
+ *
+ *   - **List-Id forging** — RFC 2919 §8 explicitly notes the
+ *     identifier is NOT an authentication signal; this primitive
+ *     refuses the SHAPE-injection class (mailing-list pipelines
+ *     that crash or mis-route on malformed List-Id). Operators
+ *     wanting authentication compose b.mail.auth.dmarc.evaluate /
+ *     b.mail.auth.arc.verify on top.
+ *   - **Bulk-sender bucket-drop** — Gmail's 2024 bulk-sender
+ *     requirements key on List-Id presence for messages with
+ *     `Precedence: list` or 5000+ daily sends; malformed List-Id
+ *     drops the message into spam. This primitive surfaces the
+ *     refuse-at-submit verdict so operators see the issue at
+ *     send-time, not at delivery.
+ *
+ * @card
+ *   RFC 2919 List-Id validator. Parses bare + bracketed + phrase-prefixed forms; refuses CRLF / control-char / phrase-injection / non-LDH domain / >255-octet identifier / bare-host claim. Companion to b.guardListUnsubscribe for outbound mailing-list compliance.
+ */
+
+var C                  = require("./constants");
+var { defineClass }    = require("./framework-error");
+
+var GuardListIdError = defineClass("GuardListIdError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict: {
+    maxBytes:           998,                                                                             // allow:raw-byte-literal — RFC 5322 §2.1.1 line cap
+    maxListIdBytes:     255,                                                                             // allow:raw-byte-literal — RFC 2919 §3 cap
+    requireFqdn:        true,
+    requireRandomForLocalhost: true,
+    allowPhrase:        true,
+  },
+  balanced: {
+    maxBytes:           998,                                                                             // allow:raw-byte-literal — RFC 5322 §2.1.1 line cap
+    maxListIdBytes:     255,                                                                             // allow:raw-byte-literal — RFC 2919 §3 cap
+    requireFqdn:        true,
+    requireRandomForLocalhost: false,
+    allowPhrase:        true,
+  },
+  permissive: {
+    maxBytes:           C.BYTES.kib(4),
+    maxListIdBytes:     512,                                                                             // allow:raw-byte-literal — permissive max
+    requireFqdn:        false,
+    requireRandomForLocalhost: false,
+    allowPhrase:        true,
+  },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// RFC 5322 §3.2.3 dot-atom-text shape — alphanumeric + select
+// printable specials. We don't allow the full atext set because
+// the relaxed forms (`!`, `#`, `$`, etc.) almost never appear in
+// real-world list IDs and the strictness defends parser drift in
+// downstream consumers.
+var DOT_ATOM_LABEL_RE = /^[A-Za-z0-9](?:[A-Za-z0-9_-]*[A-Za-z0-9])?$/;                                  // allow:regex-no-length-cap — per-label repeat-cap matches RFC 5321 §2.3.5
+// 32-hex-char random component RFC 2919 §3 recommends for
+// `localhost` namespace identifiers. We test for AT LEAST 32 hex
+// chars somewhere in the list-label part.
+var RANDOM_HEX_RE = /[0-9a-fA-F]{32}/;                                                                  // allow:regex-no-length-cap — anchored repeat-cap
+
+/**
+ * @primitive b.guardListId.validate
+ * @signature b.guardListId.validate(headerValue, opts?)
+ * @since     0.9.40
+ * @status    stable
+ * @related   b.guardListUnsubscribe.validate, b.guardEmail.validateMessage
+ *
+ * Validate an RFC 2919 `List-Id` header value. Accepts:
+ *
+ *   - `<my-list.example.com>` (bracketed bare-identifier form)
+ *   - `My Newsletter <my-list.example.com>` (phrase + bracketed)
+ *   - `my-list.example.com` (bare, no brackets — RFC 2919 allows)
+ *
+ * Returns `{ action, listId, namespace, phrase?, reason }`.
+ * Action one of `"accept"` / `"refuse"`.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   var v = b.guardListId.validate("My Newsletter <newsletter.example.com>");
+ *   if (v.action === "accept") emit("List-Id: " + v.raw);
+ */
+function validate(headerValue, opts) {
+  opts = opts || {};
+  var caps = _resolveProfile(opts);
+  if (typeof headerValue !== "string") {
+    throw new GuardListIdError("guard-list-id/bad-input",
+      "validate: headerValue must be a string");
+  }
+  if (headerValue.length === 0) {
+    return _refuse("empty List-Id header value");
+  }
+  if (Buffer.byteLength(headerValue, "utf8") > caps.maxBytes) {
+    return _refuse("List-Id header exceeds maxBytes=" + caps.maxBytes + " (RFC 5322 §2.1.1)");
+  }
+  if (_hasControlChar(headerValue) || headerValue.indexOf("\r") !== -1 || headerValue.indexOf("\n") !== -1) {
+    return _refuse("header contains CRLF / NUL / C0 / DEL (header-injection defense)");
+  }
+
+  // Extract optional phrase + bracketed identifier OR bare identifier.
+  var trimmed = headerValue.trim();
+  var phrase  = null;
+  var listId  = null;
+  var lt = trimmed.indexOf("<");
+  if (lt !== -1) {
+    var gt = trimmed.indexOf(">", lt + 1);
+    if (gt === -1 || trimmed.indexOf("<", lt + 1) !== -1) {
+      return _refuse("malformed angle brackets in List-Id");
+    }
+    if (gt !== trimmed.length - 1) {
+      return _refuse("trailing content after '>' in List-Id");
+    }
+    phrase = trimmed.slice(0, lt).trim();
+    listId = trimmed.slice(lt + 1, gt).trim();
+    if (phrase.length > 0) {
+      if (!caps.allowPhrase) {
+        return _refuse("phrase before <list-id> refused by profile");
+      }
+      // Phrase-injection defense — phrase MUST NOT carry `<` / `>`
+      // (would smuggle a second bracketed identifier).
+      if (phrase.indexOf("<") !== -1 || phrase.indexOf(">") !== -1) {
+        return _refuse("phrase contains '<' or '>' (List-Id smuggling defense)");
+      }
+    }
+  } else {
+    // Bare identifier — RFC 2919 §3 allows.
+    listId = trimmed;
+  }
+
+  if (listId.length === 0) {
+    return _refuse("empty list-id (RFC 2919 §3)");
+  }
+  if (Buffer.byteLength(listId, "utf8") > caps.maxListIdBytes) {
+    return _refuse("list-id exceeds RFC 2919 §3 cap=" + caps.maxListIdBytes);
+  }
+
+  // RFC 2919 §2: `list-id = list-label "." list-id-namespace`.
+  // Both sides are dot-atom-text, so string parsing alone can't
+  // recover the boundary without Public Suffix List awareness
+  // (`team.example.com` could be label=team / ns=example.com OR
+  // label=team.example / ns=com). The earlier last-2-segment
+  // heuristic produced empty `label` for 2-label IDs (Codex P1 on
+  // PR #64), which violates RFC 2919 §2's required label "."
+  // namespace decomposition.
+  //
+  // Drop the heuristic split — surface only the raw `listId` (and
+  // the parsed `phrase`). Consumers that need an org-domain split
+  // compose `b.publicSuffix.organizationalDomain(listId)` directly,
+  // which is PSL-accurate (handles `.co.uk`, `.com.au`, etc.).
+  if (listId.indexOf(".") === -1) {
+    return _refuse("list-id missing '.' separator (RFC 2919 §2; bare-host '" + listId + "')");
+  }
+  var parts = listId.split(".");
+  for (var i = 0; i < parts.length; i += 1) {
+    if (parts[i].length === 0) {
+      return _refuse("empty label in list-id '" + listId + "' (RFC 5322 dot-atom-text)");
+    }
+    if (!DOT_ATOM_LABEL_RE.test(parts[i])) {                                                             // allow:regex-no-length-cap — label length-bounded by maxListIdBytes
+      return _refuse("label '" + parts[i] + "' not dot-atom-text shape (RFC 5322 §3.2.3)");
+    }
+  }
+  // RFC 2919 §2 requires AT LEAST one `.` (label + namespace);
+  // strict/balanced ALSO require the namespace to be a FQDN, which
+  // means a minimum of 3 labels total (label + ns-label + ns-tld)
+  // OR a 2-label list-id where the namespace is `localhost`.
+  if (caps.requireFqdn) {
+    var lastLabel = parts[parts.length - 1].toLowerCase();
+    if (parts.length < 3 && lastLabel !== "localhost") {                                                 // allow:raw-byte-literal — FQDN requires ≥ 3 labels for non-localhost
+      return _refuse("list-id has < 3 labels for non-localhost namespace (FQDN required under '" +
+        (opts.profile || DEFAULT_PROFILE) + "')");
+    }
+  }
+
+  // RFC 2919 §3: `localhost` namespace SHOULD carry 32-hex
+  // randomness in the label.
+  var isLocalhost = parts[parts.length - 1].toLowerCase() === "localhost";
+  if (isLocalhost) {
+    if (caps.requireRandomForLocalhost && !RANDOM_HEX_RE.test(listId)) {                                 // allow:regex-no-length-cap — listId length-bounded above
+      return _refuse("localhost namespace requires 32-hex random component per RFC 2919 §3 SHOULD");
+    }
+  }
+
+  return {
+    action:    "accept",
+    listId:    listId,
+    phrase:    phrase,
+    reason:    "List-Id compliant with RFC 2919 §2",
+  };
+}
+
+/**
+ * @primitive b.guardListId.compliancePosture
+ * @signature b.guardListId.compliancePosture(posture)
+ * @since     0.9.40
+ * @status    stable
+ *
+ * Return the effective profile name for a compliance posture, or
+ * `null` for unknown posture names.
+ *
+ * @example
+ *   b.guardListId.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _hasControlChar(s) {
+  for (var i = 0; i < s.length; i += 1) {
+    var c = s.charCodeAt(i);
+    if (c === 0x00 || c === 0x7f || (c < 0x20 && c !== 0x09)) {                                          // allow:raw-byte-literal — RFC 5322 control + TAB allow
+      return true;
+    }
+  }
+  return false;
+}
+
+function _refuse(reason) {
+  return {
+    action:    "refuse",
+    listId:    null,
+    phrase:    null,
+    reason:    reason,
+  };
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardListIdError("guard-list-id/bad-profile",
+      "guardListId: unknown profile '" + p + "'");
+  }
+  return PROFILES[p];
+}
+
+module.exports = {
+  validate:               validate,
+  compliancePosture:      compliancePosture,
+  PROFILES:               PROFILES,
+  COMPLIANCE_POSTURES:    COMPLIANCE_POSTURES,
+  GuardListIdError:       GuardListIdError,
+  NAME:                   "listId",
+  KIND:                   "list-id",
+};

package/lib/guard-list-unsubscribe.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * @module     b.guardListUnsubscribe
+ * @nav        Guards
+ * @title      Guard List-Unsubscribe
+ * @order      465
+ *
+ * @intro
+ *   RFC 2369 `List-Unsubscribe` + RFC 8058 one-click
+ *   `List-Unsubscribe-Post` header validator. Gates the outbound
+ *   submission path's marketing / transactional mail so messages
+ *   carrying a `List-Id` (or any mailing-list shape) emit headers
+ *   that Gmail / Yahoo / Outlook one-click unsubscribe machinery
+ *   actually accepts.
+ *
+ *   ## Why this primitive vs. inline header construction
+ *
+ *   Gmail's bulk-sender requirements (effective 2024-02) and Yahoo's
+ *   matching policy refuse mail that doesn't carry the RFC 8058 pair
+ *   correctly. Operators get senders rate-limited or buckets-dropped
+ *   when the headers are malformed. Common pitfalls this primitive
+ *   refuses:
+ *
+ *     - **No HTTPS URI** — Gmail+Yahoo require at least one
+ *       `https://` URI in the `List-Unsubscribe` header. `mailto:`
+ *       alone is no longer sufficient post-2024.
+ *     - **`http://` instead of `https://`** — refused; one-click
+ *       endpoint MUST be TLS.
+ *     - **`javascript:` / `data:` / `file:` schemes** — always
+ *       refused regardless of context.
+ *     - **`List-Unsubscribe-Post: List-Unsubscribe=One-Click`** —
+ *       MUST be EXACTLY this token. Operator-supplied variants
+ *       (`OneClick`, `one-click`, lowercased `=` value) refused.
+ *     - **HTTPS URI without paired `List-Unsubscribe-Post`** — the
+ *       Post header opts the endpoint into one-click. Without it,
+ *       Gmail's UI treats the HTTPS URI as a regular link (operator
+ *       loses the inbox-list "Unsubscribe" button).
+ *
+ *   ## Verdict shape
+ *
+ *   ```js
+ *   {
+ *     action:        "accept" | "refuse",
+ *     reason:        string,
+ *     uris:          [{ scheme, raw, oneClickEligible }, ...],
+ *     hasHttpsUri:   bool,
+ *     hasMailtoUri:  bool,
+ *     postHeaderOk:  bool,
+ *     oneClickReady: bool,
+ *   }
+ *   ```
+ *
+ *   Under `strict` (default for HIPAA / PCI / GDPR / SOC2 mailings
+ *   that need bulk-sender compliance), `oneClickReady: false` →
+ *   `action: "refuse"`. Under `balanced`, the primitive returns the
+ *   verdict but always accepts — operator's outbound pipeline makes
+ *   the policy decision downstream.
+ *
+ *   ## CVE / threat model
+ *
+ *   - **Unsubscribe-link injection** — operator's template-rendered
+ *     `List-Unsubscribe` could be tampered through prompt-injection
+ *     into an AI-generated newsletter. CRLF refused (header
+ *     injection); `javascript:` / `data:` / `file:` refused (XSS via
+ *     mail-client rendering); URL length cap (default 2048).
+ *   - **Open-redirect via List-Unsubscribe** — operator validates the
+ *     HTTPS URI's target host with their own `safeRedirect` /
+ *     `safeUrl` allowlist downstream; this guard checks the SHAPE,
+ *     not the operator's target-host policy.
+ *   - **Email client mishandling** (Outlook's history of fetching
+ *     `mailto:` automatically) — the primitive doesn't render the
+ *     header; consumers using it inside `b.guardEmail.validateMessage`
+ *     get layered defense.
+ *
+ * @card
+ *   RFC 2369 + RFC 8058 List-Unsubscribe / List-Unsubscribe-Post validator. Refuses non-HTTPS one-click URIs, javascript:/data:/file: schemes, missing Post header, malformed Post token. Gmail+Yahoo bulk-sender compliance defense.
+ */
+
+var C                  = require("./constants");
+var { defineClass }    = require("./framework-error");
+var safeUrl            = require("./safe-url");
+
+var GuardListUnsubscribeError = defineClass("GuardListUnsubscribeError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict: {
+    maxBytes:           C.BYTES.kib(4),
+    maxUris:            4,                                                                               // allow:raw-byte-literal — URI-count cap
+    maxUriBytes:        2048,                                                                            // allow:raw-byte-literal — per-URI byte cap
+    requireHttpsUri:    true,
+    requirePostHeader:  true,
+    refuseHttp:         true,
+  },
+  balanced: {
+    maxBytes:           C.BYTES.kib(4),
+    maxUris:            8,                                                                               // allow:raw-byte-literal — URI-count cap
+    maxUriBytes:        2048,                                                                            // allow:raw-byte-literal — per-URI byte cap
+    requireHttpsUri:    false,
+    requirePostHeader:  false,
+    refuseHttp:         true,
+  },
+  permissive: {
+    maxBytes:           C.BYTES.kib(8),
+    maxUris:            16,                                                                              // allow:raw-byte-literal — URI-count cap
+    maxUriBytes:        4096,                                                                            // allow:raw-byte-literal — per-URI byte cap
+    requireHttpsUri:    false,
+    requirePostHeader:  false,
+    refuseHttp:         false,
+  },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// RFC 8058 §2: Post header value MUST be exactly
+// `List-Unsubscribe=One-Click`. Token is case-sensitive per Gmail /
+// Yahoo bulk-sender enforcement (mixed-case variants silently fail
+// one-click on Gmail).
+var ONE_CLICK_POST_VALUE = "List-Unsubscribe=One-Click";
+
+// Always-refused schemes regardless of profile (XSS / mail-client
+// rendering / local-file-read class).
+var DANGEROUS_SCHEMES = Object.freeze({
+  "javascript:": true,
+  "data:":       true,
+  "file:":       true,
+  "vbscript:":   true,
+  "blob:":       true,
+});
+
+/**
+ * @primitive b.guardListUnsubscribe.validate
+ * @signature b.guardListUnsubscribe.validate(headers, opts?)
+ * @since     0.9.39
+ * @status    stable
+ * @related   b.guardEmail.validateMessage, b.safeMime.parse
+ *
+ * Validate the RFC 2369 / RFC 8058 header pair on an outbound
+ * marketing or transactional message. Returns the verdict shape;
+ * operator's submission listener consults `verdict.action` to
+ * accept / refuse the send.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   var v = b.guardListUnsubscribe.validate({
+ *     listUnsubscribe:      "<mailto:u@x.com?subject=unsub>, <https://x.com/unsub?id=42>",
+ *     listUnsubscribePost:  "List-Unsubscribe=One-Click",
+ *   });
+ *   if (v.action === "refuse") throw new Error(v.reason);
+ */
+function validate(headers, opts) {
+  opts = opts || {};
+  var caps = _resolveProfile(opts);
+  if (!headers || typeof headers !== "object") {
+    throw new GuardListUnsubscribeError("guard-list-unsubscribe/bad-input",
+      "validate: headers must be a plain object");
+  }
+  if (typeof headers.listUnsubscribe !== "string" || headers.listUnsubscribe.length === 0) {
+    throw new GuardListUnsubscribeError("guard-list-unsubscribe/bad-input",
+      "validate: headers.listUnsubscribe must be a non-empty string");
+  }
+  var raw = headers.listUnsubscribe;
+  if (Buffer.byteLength(raw, "utf8") > caps.maxBytes) {
+    return _verdict("refuse", "List-Unsubscribe header exceeds maxBytes=" + caps.maxBytes,
+      { uris: [], hasHttpsUri: false, hasMailtoUri: false, postHeaderOk: false });
+  }
+  if (raw.indexOf("\r") !== -1 || raw.indexOf("\n") !== -1) {
+    return _verdict("refuse", "header contains CR/LF (RFC 5322 §3.2.5 header-injection refusal)",
+      { uris: [], hasHttpsUri: false, hasMailtoUri: false, postHeaderOk: false });
+  }
+  if (_hasControlChar(raw)) {
+    return _verdict("refuse", "header contains NUL / C0 / DEL control char",
+      { uris: [], hasHttpsUri: false, hasMailtoUri: false, postHeaderOk: false });
+  }
+
+  var uriParts = _extractUris(raw, caps.maxUris);
+  if (uriParts === null) {
+    return _verdict("refuse", "more than maxUris=" + caps.maxUris + " URIs in List-Unsubscribe",
+      { uris: [], hasHttpsUri: false, hasMailtoUri: false, postHeaderOk: false });
+  }
+  if (uriParts.length === 0) {
+    return _verdict("refuse", "List-Unsubscribe has no <URI> elements (RFC 2369 §3.1)",
+      { uris: [], hasHttpsUri: false, hasMailtoUri: false, postHeaderOk: false });
+  }
+
+  var classified = [];
+  var hasHttpsUri  = false;
+  var hasMailtoUri = false;
+  for (var i = 0; i < uriParts.length; i += 1) {
+    var u = uriParts[i];
+    if (Buffer.byteLength(u, "utf8") > caps.maxUriBytes) {
+      return _verdict("refuse", "URI '" + _trunc(u) + "' exceeds maxUriBytes=" + caps.maxUriBytes,
+        { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: false });
+    }
+    var schemeMatch = u.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:)/);                                             // allow:regex-no-length-cap — scheme has fixed-shape repeat cap
+    var scheme = schemeMatch ? schemeMatch[1].toLowerCase() : null;
+    if (!scheme) {
+      return _verdict("refuse", "URI '" + _trunc(u) + "' has no scheme (RFC 3986 §3.1)",
+        { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: false });
+    }
+    if (DANGEROUS_SCHEMES[scheme]) {
+      return _verdict("refuse", "URI scheme '" + scheme + "' is on the always-refused list (XSS / file-read class)",
+        { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: false });
+    }
+    if (scheme === "http:" && caps.refuseHttp) {
+      return _verdict("refuse", "plain http:// refused in List-Unsubscribe (one-click requires HTTPS per RFC 8058 §2 + Gmail/Yahoo bulk-sender policy)",
+        { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: false });
+    }
+    if (scheme === "https:") {
+      try {
+        safeUrl.parse(u, { allowedProtocols: safeUrl.ALLOW_HTTPS });
+      } catch (e) {
+        return _verdict("refuse", "HTTPS URI '" + _trunc(u) + "' failed safeUrl parse: " + (e && e.message || String(e)),
+          { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: false });
+      }
+      hasHttpsUri = true;
+    } else if (scheme === "mailto:") {
+      hasMailtoUri = true;
+    }
+    classified.push({
+      scheme:             scheme,
+      raw:                u,
+      oneClickEligible:   scheme === "https:",
+    });
+  }
+
+  // RFC 8058 §2 — Post header value MUST be the canonical token.
+  var postHeader = headers.listUnsubscribePost;
+  var postHeaderOk = typeof postHeader === "string" && postHeader.trim() === ONE_CLICK_POST_VALUE;
+
+  if (caps.requireHttpsUri && !hasHttpsUri) {
+    return _verdict("refuse", "List-Unsubscribe has no https:// URI (RFC 8058 + Gmail/Yahoo bulk-sender 2024 requirement)",
+      { uris: classified, hasHttpsUri: false, hasMailtoUri: hasMailtoUri, postHeaderOk: postHeaderOk });
+  }
+  if (caps.requirePostHeader && hasHttpsUri && !postHeaderOk) {
+    var got = postHeader === undefined ? "(absent)" :
+              typeof postHeader !== "string" ? "(non-string)" : postHeader;
+    return _verdict("refuse",
+      "List-Unsubscribe-Post header must be exactly '" + ONE_CLICK_POST_VALUE + "' (RFC 8058 §2); got " + got,
+      { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: false });
+  }
+
+  return _verdict("accept", "headers compliant with RFC 2369 + RFC 8058",
+    { uris: classified, hasHttpsUri: hasHttpsUri, hasMailtoUri: hasMailtoUri, postHeaderOk: postHeaderOk });
+}
+
+/**
+ * @primitive b.guardListUnsubscribe.compliancePosture
+ * @signature b.guardListUnsubscribe.compliancePosture(posture)
+ * @since     0.9.39
+ * @status    stable
+ *
+ * Return the effective profile name for a compliance posture, or
+ * `null` for unknown posture names.
+ *
+ * @example
+ *   b.guardListUnsubscribe.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _extractUris(raw, maxUris) {
+  // RFC 2369 §3.1 — comma-separated `<URI>` items. Walk angle-
+  // bracket pairs directly via String.matchAll so URIs containing
+  // commas (legitimate, e.g. `<https://x/u?tags=a,b>`) parse
+  // correctly. Earlier split(",")-based scan misclassified such
+  // URIs as "no <URI> elements" and refused legitimate mail
+  // (Codex P1 on PR #63).
+  var matches = raw.matchAll(/<([^<>]*)>/g);                                                             // allow:regex-no-length-cap — input length-bounded by maxBytes check upstream
+  var uris = [];
+  for (var m of matches) {
+    uris.push(m[1].trim());
+    if (uris.length > maxUris) return null;
+  }
+  return uris;
+}
+
+function _hasControlChar(s) {
+  for (var i = 0; i < s.length; i += 1) {
+    var c = s.charCodeAt(i);
+    if (c === 0x00 || c === 0x7f || (c < 0x20 && c !== 0x09)) {                                          // allow:raw-byte-literal — RFC 5322 control + TAB allow
+      return true;
+    }
+  }
+  return false;
+}
+
+function _trunc(s) {
+  if (s.length <= 64) return s;                                                                          // allow:raw-byte-literal — error-message truncation
+  return s.slice(0, 60) + "…";                                                                          // allow:raw-time-literal — char count for error-message truncation, not seconds
+}
+
+function _verdict(action, reason, extra) {
+  return {
+    action:        action,
+    reason:        reason,
+    uris:          extra.uris,
+    hasHttpsUri:   extra.hasHttpsUri,
+    hasMailtoUri:  extra.hasMailtoUri,
+    postHeaderOk:  extra.postHeaderOk,
+    oneClickReady: extra.hasHttpsUri && extra.postHeaderOk,
+  };
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardListUnsubscribeError("guard-list-unsubscribe/bad-profile",
+      "guardListUnsubscribe: unknown profile '" + p + "'");
+  }
+  return PROFILES[p];
+}
+
+module.exports = {
+  validate:                       validate,
+  compliancePosture:              compliancePosture,
+  PROFILES:                       PROFILES,
+  COMPLIANCE_POSTURES:            COMPLIANCE_POSTURES,
+  ONE_CLICK_POST_VALUE:           ONE_CLICK_POST_VALUE,
+  DANGEROUS_SCHEMES:              DANGEROUS_SCHEMES,
+  GuardListUnsubscribeError:      GuardListUnsubscribeError,
+  NAME:                           "listUnsubscribe",
+  KIND:                           "list-unsubscribe",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.38",
+  "version": "0.9.40",
   "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:6b9a6fd7-b1f8-4d51-9ad8-b6edd98b31e5",
+  "serialNumber": "urn:uuid:414de146-e066-4e4d-aa72-85cc18e385d6",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-15T09:16:43.370Z",
+    "timestamp": "2026-05-15T11:24:02.385Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.38",
+      "bom-ref": "@blamejs/core@0.9.40",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.38",
+      "version": "0.9.40",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.38",
+      "purl": "pkg:npm/%40blamejs/core@0.9.40",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.38",
+      "ref": "@blamejs/core@0.9.40",
       "dependsOn": []
     }
   ]