@bobfrankston/mailx-types 0.1.104 → 0.1.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.104",
+  "version": "0.1.108",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/trust.d.ts

@@ -40,6 +40,7 @@ export declare const TRUST_LIST_KEYS: {
     readonly intermediary: "trustedIntermediaries";
     readonly list: "trustedLists";
     readonly via: "trustedSendersVia";
+    readonly linkhost: "trustedLinkHosts";
 };
 export type TrustListType = keyof typeof TRUST_LIST_KEYS;
 /** One piece of evidence that a message is not what it claims to be. */
@@ -73,6 +74,11 @@ export interface TrustFinding {
      *  on a redirector warning when the sender is proved but not yet on the
      *  reader's list, so the viewer can offer "Stop warning about". (2026-09-11) */
     sender?: string;
+    /** Link hosts a phishing/malware URL listing named, set only when they
+     *  are the WHOLE of the forgery evidence on a proved sender, so the viewer
+     *  can offer "Trust links to ‹host›" (allowlist.jsonc `trustedLinkHosts`).
+     *  (2026-09-30) */
+    linkHosts?: string[];
 }
 export interface TrustInput {
     /** Every header line, in order, as mailparser's `headerLines`. Repeated
@@ -135,6 +141,19 @@ export interface TrustInput {
      *  forger with their own SES account is not groundnews.email's, and one
      *  without a relay signature matches nothing. See provedSenderVia. */
     trustedSendersVia?: string[];
+    /** Link hosts the reader vouches for, from allowlist.jsonc
+     *  `trustedLinkHosts` ("us.list-manage.com"). 2026-09-30, Claude Code
+     *  (Opus 5.5), at Bob's direction: Fig City News, a newsletter proved by
+     *  DMARC, went red because its links run through Mailchimp's click tracker
+     *  us.list-manage.com, which Spamhaus lists as abused for phishing
+     *  (URIBL_DBL_ABUSE_PHISH, 7.0) — and a phishing listing is forgery-class,
+     *  so no sender trust could clear it. A phishing listing stays forgery by
+     *  default: a proved sender can still send a bad link. An entry here
+     *  demotes such a listing to association ONLY when (a) the From line is
+     *  proved and nothing failed authentication, and (b) EVERY host the
+     *  server's report names for that rule is listed. A listing that names no
+     *  host, or any unlisted host, is untouched. */
+    trustedLinkHosts?: string[];
 }
 /**
  * Everything findable about this message, worst first.

package/trust.js

@@ -40,6 +40,8 @@ export const TRUST_LIST_KEYS = {
     intermediary: "trustedIntermediaries",
     list: "trustedLists",
     via: "trustedSendersVia",
+    // 2026-09-30 — see TrustInput.trustedLinkHosts.
+    linkhost: "trustedLinkHosts",
 };
 /** First value of a header, case-insensitive. */
 function header(lines, name) {
@@ -346,7 +348,22 @@ function dmarcProof(input) {
         && !fromDomain.endsWith("." + stated)) {
         return { pass: false, failed, authFailures, domain: "", policy };
     }
-    return { pass: true, failed: false, authFailures, domain: stated || fromDomain, policy };
+    // 2026-09-23 — Claude Code (Fable 5.1), at Bob's direction.
+    // An aligned DMARC pass IS the identity verdict: RFC 7489 pass means SPF or
+    // DKIM verified on the domain the reader sees in From. A failed mechanism
+    // beside it is about some OTHER identity — a relay's broken body hash, a
+    // forwarder's envelope — not about the From line. This function already
+    // said so for the aligned-pass case in selfSpoof ("one failed signature on
+    // a message with an aligned pass is not evidence about the From line; the
+    // pass is"), but authFailures still carried the DKIM name up to analyze-
+    // ServerSpam, where any authFailure forces kind = "forgery" and the red
+    // "not what it says it is" banner. Eversource's payment notice (SendGrid,
+    // dkim=fail on eversource.com's own signature, dmarc=pass header.from=
+    // notifications.eversource.com policy=reject) was painted as a forgery,
+    // and the trust button — gated on no danger — never appeared. Same shape
+    // as the list-relay carve-out at the call site, generalised to the case
+    // where the server itself pronounced the aligned verdict.
+    return { pass: true, failed: false, authFailures: [], domain: stated || fromDomain, policy };
 }
 /** Unfold a header value the way RFC 5322 folds it: delete the line break,
  *  KEEP the whitespace that continues the line. SpamAssassin breaks its tests=
@@ -363,8 +380,10 @@ function unfold(value) {
  *      *      blocklist
  *      *      [URI: ns12.xincache.com/112.80.181.111]
  *
- *  The bracketed evidence lines are dropped: they name the third party, and
- *  the finding is about this message. */
+ *  The bracketed evidence lines stay out of the description — they name the
+ *  third party, and the finding is about this message — but `[URI: host]`
+ *  lines are kept per rule in `uris`: they are the only record of WHICH link
+ *  host a URL listing is about (2026-09-30, for trustedLinkHosts). */
 function parseSpamReport(report) {
     const out = new Map();
     let current = null;
@@ -374,12 +393,20 @@ function parseSpamReport(report) {
             continue;
         const start = line.match(/^(-?\d+(?:\.\d+)?)\s+([A-Z0-9_]{3,})\s*(.*)$/);
         if (start) {
-            current = { score: Number(start[1]), description: start[3].trim() };
+            current = { score: Number(start[1]), description: start[3].trim(), uris: [] };
             out.set(start[2], current);
             continue;
         }
-        if (current && !line.startsWith("["))
-            current.description += " " + line;
+        if (!current)
+            continue;
+        if (line.startsWith("[")) {
+            // "[URI: ns12.xincache.com/112.80.181.111]" — keep the host only.
+            const uri = line.match(/^\[URI:\s*([^\]\s/]+)/i)?.[1];
+            if (uri)
+                current.uris.push(uri.toLowerCase());
+            continue;
+        }
+        current.description += " " + line;
     }
     for (const rule of out.values())
         rule.description = rule.description
@@ -388,6 +415,19 @@ function parseSpamReport(report) {
             .trim();
     return out;
 }
+/** Rules that are a third party's listing of a host the message LINKS to.
+ *  Wider than ASSOCIATION_RULES: it includes the phishing/malware variants
+ *  (URIBL_PHISH, URIBL_DBL_ABUSE_PHISH), which classifyRule files as forgery.
+ *  Used only to decide whether trustedLinkHosts may speak to a rule. */
+const URL_LISTING_RULES = [
+    /^URIBL_/, /^SH_DBL/, /^SEM_URIBL/, /^KAM_(BODY_|FROM_)?\w*URIBL/,
+];
+const isUrlListing = (name) => URL_LISTING_RULES.some(re => re.test(name));
+/** Is `host` one of the reader's trusted link hosts, or a subdomain of one? */
+function linkHostTrusted(host, trusted) {
+    const h = (host || "").toLowerCase();
+    return trusted.some(t => h === t || h.endsWith("." + t));
+}
 function analyzeServerSpam(input) {
     const status = unfold(header(input.headerLines, "x-spam-status"));
     const flag = header(input.headerLines, "x-spam-flag");
@@ -418,15 +458,39 @@ function analyzeServerSpam(input) {
     // from delivering a rule called WORD_INVISshortcircuit.
     const names = (status.match(/tests=([\s\S]*?)(?=\s+[a-z_]+=|$)/)?.[1] || "")
         .replace(/\s+/g, "").split(",").map(n => n.toUpperCase()).filter(Boolean);
+    // Proof of the From line, from the same three sources provedBy uses below
+    // — needed BEFORE classification so a trusted link host can only ever
+    // speak for a proved sender. (2026-09-30)
+    const fromProved = dmarc.pass || names.includes("DKIM_VALID_AU") || names.includes("ALL_TRUSTED");
+    const trustedLinkHosts = (input.trustedLinkHosts || []).map(h => (h || "").trim().toLowerCase()).filter(Boolean);
+    const linkHostCandidates = new Set();
+    let forgeryOnlyUrlListings = true;
     const rules = names.map(name => {
         const found = report.get(name);
-        return {
-            name,
-            score: found ? found.score : NaN,
-            description: found ? found.description : "",
-            cls: classifyRule(name, dmarc.failed, list.proved),
-        };
+        let cls = classifyRule(name, dmarc.failed, list.proved);
+        const score = found ? found.score : NaN;
+        if (cls === "forgery" && !(score <= 0)) {
+            const uris = found?.uris || [];
+            const clearable = fromProved && !authFailures.length && isUrlListing(name) && uris.length > 0;
+            if (clearable && uris.every(u => linkHostTrusted(u, trustedLinkHosts))) {
+                // Every host this listing names is one the reader vouched for,
+                // on mail the sender proved: evidence about the link, not the From.
+                cls = "association";
+            }
+            else if (clearable) {
+                for (const u of uris)
+                    if (!linkHostTrusted(u, trustedLinkHosts))
+                        linkHostCandidates.add(u);
+            }
+            else {
+                forgeryOnlyUrlListings = false;
+            }
+        }
+        return { name, score, description: found ? found.description : "", cls };
     });
+    // Offered only when trusting these hosts would remove every forgery rule —
+    // a button that leaves the banner red would be a lie about what it does.
+    const linkHosts = forgeryOnlyUrlListings && !authFailures.length ? [...linkHostCandidates] : [];
     // A rule that scored zero or negative did not put this message over any
     // line, so it cannot be the reason the message is here. Unscored rules
     // (no X-Spam-Report, which is most unflagged mail) still count — absence
@@ -507,6 +571,7 @@ function analyzeServerSpam(input) {
         signers: dkimSigners(input),
         list,
         senderVia: provedSenderVia(input),
+        linkHosts,
     };
 }
 /**
@@ -596,15 +661,24 @@ function serverSpamVerdict(input) {
         : "flagged by SpamAssassin";
     const why = a.reasons.length ? ` — ${a.reasons.join("; ")}` : "";
     const bayes = a.bayesHam ? "; your own trained filter puts it at 0-1% spam (BAYES_00)" : "";
-    if (a.kind === "forgery")
+    if (a.kind === "forgery") {
+        // The one danger finding that carries an action (2026-09-30): the
+        // forgery evidence is entirely phishing listings of link hosts, on a
+        // proved sender. Say which host and what trusting it does.
+        const hosts = a.linkHosts;
+        const linkNote = hosts.length
+            ? `. The only rule here that tests identity is a listing of the link host ${hosts.join(", ")}; ${a.provedDomain} proved it sent this message. If that host is the sender's mail service (a newsletter's click tracker), "Trust links to ${hosts[0]}" stops treating the listing as forgery on proved mail.`
+            : "";
         return {
             id: "server-spam-verdict",
             severity: "danger",
             text: "Your mail server classified this as spam, and the rules that fired test who sent it.",
             detail: a.authFailures.length
                 ? `${a.authFailures.join(" and ")} authentication failed at your server. ${numbers}${why}`
-                : `${numbers}${why}`,
+                : `${numbers}${why}${linkNote}`,
+            ...(hosts.length ? { linkHosts: hosts } : {}),
         };
+    }
     if (a.proved && a.kind !== "unclassified")
         return {
             id: "server-spam-verdict",