@bobfrankston/rmfmail 1.2.285 → 1.2.286

package/packages/mailx-types/trust.ts

@@ -34,8 +34,10 @@ export interface TrustFinding {
     /** Stable identifier — for tests, logs, and any future suppression UI. */
     id: "server-spam-verdict" | "self-spoof" | "relay-auth-mismatch"
         | "zero-width-obfuscation" | "hidden-link-overlay" | "redirector-link";
-    /** `danger`: near-certain forgery. `caution`: worth a second look. */
-    severity: "danger" | "caution";
+    /** `danger`: near-certain forgery. `caution`: worth a second look.
+     *  `info`: something the server said, in a register that is not an
+     *  accusation — a bulk-mail verdict on a sender DMARC proved. */
+    severity: "danger" | "caution" | "info";
     /** One line, naming what was found. Never "this message is suspicious". */
     text: string;
     /** The specific evidence — a header value, a host, a score. */
@@ -89,7 +91,270 @@ function bare(addr: string): string {
 }
 
 /**
- * Did the receiving server's spam filter already say yes?
+ * What SpamAssassin's rules are evidence OF — which is not what its score is.
+ *
+ * The score answers "should this be delivered". The banner asks a different
+ * question, "is this forged", and the `tests=` list that separates the two
+ * sits in the same header and was never read. Four messages Bob subscribed to
+ * (Constant Contact, Adobe MAX, Mokin, ActBlue) scored 2.2 to 10.9 and two of
+ * them raised the app's strongest banner; every rule that pushed them there
+ * was a bulk-mail test or a third-party blocklist entry about a host the
+ * message merely LINKS TO. Mokin's 6.0 — more than the whole 4.5 threshold on
+ * its own — was `URIBL_SBL` on the IP of the nameserver of a linked domain:
+ * fourth-order guilt by association, saying nothing whatever about whether
+ * Mokin sent the mail. All four passed DMARC aligned, so on all four the
+ * headline "This message is not what it says it is" was factually false.
+ * Full diagnosis: docs/spam-false-positives.md. (Claude Code 2026-08-27)
+ *
+ * Note what is NOT here: any tuning of a threshold. A rule's class follows
+ * from what it tests, never from how much it scored.
+ */
+type RuleClass = "forgery" | "association" | "bulk" | "neutral" | "other";
+
+/** Rules that say THIS message lies about who sent it. The only class that
+ *  earns the red banner. `KAM_DMARC_STATUS` is deliberately absent — it is a
+ *  0.0-scoring status marker that fired on Mokin, a message the receiving
+ *  server had just recorded as `dmarc=pass`. */
+const FORGERY_RULES: RegExp[] = [
+    /^SPF_(HELO_)?(FAIL|SOFTFAIL)$/,
+    /^(KAM_)?DMARC_(FAIL|REJECT|QUAR)/,
+    /^DKIM_ADSP_(ALL|DISCARD|NXDOMAIN)$/,
+    /^FORGED_/,
+    /SPOOF/,
+    /_PHISH/, /PHISHING/, /_MALW/, /MALWARE/,
+];
+
+/** Reputation a third party holds about some host the message mentions or
+ *  travelled through. Real evidence the mail is unwanted; no evidence at all
+ *  that the From line is false — the listed party is usually not the sender. */
+const ASSOCIATION_RULES: RegExp[] = [
+    /^URIBL_(SBL|BLACK|RED|DBL|ABUSE)/,
+    /^SH_DBL/,
+    /^SEM_URIBL/,
+    /^SPAMHAUS_/,
+    /^RCVD_IN_(SBL|XBL|PBL|BL_SPAMCOP|SORBS|BRBL|VALIDITY|MSPIKE_[LZ])/,
+];
+
+/** The shape of mass mailing: bulk-detection networks, marketing markup, list
+ *  plumbing. A score built entirely from these is a bulk verdict however high
+ *  it climbs — Adobe MAX reached 3.9 without one rule that looks at identity. */
+const BULK_RULES: RegExp[] = [
+    /^DCC_/, /^PYZOR_/, /^RAZOR2_/,
+    /^MAILING_LIST/, /^LIST_/,
+    // KAM_* by name only, never the whole family: it holds marketing and list
+    // rules alongside scam-CONTENT rules (KAM_BENEFICIARY is worth 10.0,
+    // KAM_FAKE_NORTONLOW 6.5), and calling those bulk would quiet the loudest
+    // true positives in the store.
+    /^KAM_(BODY_)?MARKETINGBL/, /^KAM_UNSUB/, /^KAM_TRACKIMAGE$/,
+    /^KAM_REALLYHUGEIMGSRC$/, /^KAM_DMARC_STATUS$/, /^KAM_COUPON/,
+    /^HTML_/, /^MIME_HTML/, /^WORD_INVIS$/,
+    /^URIBL_(GREY|CSS|BLOCKED|CT_SURBL)/, /^SH_BODYURI/,
+    /^HEADER_FROM_DIFFERENT_DOMAINS$/,          // every ESP on earth trips this
+    /^MPART_ALT_DIFF/, /^TVD_/, /^T_REMOTE_IMAGE$/, /^UNPARSEABLE_RELAY$/,
+];
+
+/** Passes, whitelistings, and Bayes' own opinion — informational, and in
+ *  BAYES_00's case exculpatory. `DKIM_INVALID` lives here rather than in the
+ *  forgery class because a broken signature is routine on relayed and
+ *  list-rewritten mail (Mokin, sent via Shopify and SendGrid, carries it while
+ *  the receiving server records dkim=pass). It is promoted to forgery only
+ *  when DMARC also failed — see classifyRule. */
+const NEUTRAL_RULES: RegExp[] = [
+    /^BAYES_/,
+    /^SPF_(PASS|NONE|HELO_(PASS|NONE|NEUTRAL))$/,
+    /^DKIM_(SIGNED|VALID|VALID_AU|VALID_EF|INVALID)$/,
+    /^DKIMWL_/, /^RCVD_IN_(DNSWL|MSPIKE_H|IADB)/,
+    /^SHORTCIRCUIT$/, /^AWL$/, /^NO_RELAYS$/, /^ALL_TRUSTED$/,
+];
+
+function classifyRule(name: string, dmarcFailed: boolean): RuleClass {
+    if (dmarcFailed && name === "DKIM_INVALID") return "forgery";
+    for (const re of FORGERY_RULES) if (re.test(name)) return "forgery";
+    for (const re of ASSOCIATION_RULES) if (re.test(name)) return "association";
+    for (const re of NEUTRAL_RULES) if (re.test(name)) return "neutral";
+    for (const re of BULK_RULES) if (re.test(name)) return "bulk";
+    return "other";
+}
+
+/**
+ * Did the receiving server prove the From domain?
+ *
+ * Only the TOPMOST Authentication-Results is read. Headers are prepended, so
+ * the first one is the one our own server wrote; every one below it travelled
+ * with the message and a forger can write whatever they like there. Same
+ * asymmetry serverSpamVerdict relies on, in the other direction: a claim that
+ * SILENCES a warning must come from a source the sender cannot control.
+ *
+ * `dmarc=pass` is aligned by definition (RFC 7489) — SPF or DKIM passed on the
+ * same domain the reader sees in From. The `header.from=` it names is checked
+ * against the actual From line anyway, because an Authentication-Results about
+ * some other message proves nothing about this one.
+ */
+function dmarcProof(input: TrustInput): { pass: boolean; failed: boolean; authFailures: string[]; domain: string; policy: string } {
+    const auth = headerAll(input.headerLines, "authentication-results")[0] || "";
+    if (!auth) return { pass: false, failed: false, authFailures: [], domain: "", policy: "" };
+
+    // What the server caught failing, by name. An outright authentication
+    // failure IS an identity test, whatever the tests= list happens to call
+    // it — this is what keeps the 2026-08-25 phishes red under the new
+    // classification, since spf=fail is the whole point of them.
+    const authFailures = [
+        /\bspf=(fail|softfail)\b/i.test(auth) ? "SPF" : "",
+        /\bdkim=(fail|permerror)\b/i.test(auth) ? "DKIM" : "",
+        /\bdmarc=(fail|permerror)\b/i.test(auth) ? "DMARC" : "",
+    ].filter(Boolean);
+    const failed = authFailures.includes("DMARC");
+    if (!/\bdmarc=pass\b/i.test(auth)) return { pass: false, failed, authFailures, domain: "", policy: "" };
+
+    const stated = (auth.match(/header\.from=([^\s;,]+)/i)?.[1] || "").toLowerCase();
+    const policy = (auth.match(/policy\.dmarc=([^\s;,]+)/i)?.[1] || "").toLowerCase();
+    const fromDomain = (bare(input.fromAddress).split("@")[1] || "").toLowerCase();
+    if (stated && fromDomain
+        && stated !== fromDomain
+        && !stated.endsWith("." + fromDomain)
+        && !fromDomain.endsWith("." + stated)) {
+        return { pass: false, failed, authFailures, domain: "", policy };
+    }
+    return { pass: true, failed: false, authFailures, domain: stated || fromDomain, policy };
+}
+
+/** One rule that fired, with its score and description when the server left a
+ *  report. `X-Spam-Report` appears only on flagged mail, so score and
+ *  description are often absent while the name always is not. */
+interface SpamRule {
+    name: string;
+    score: number;
+    description: string;
+    cls: RuleClass;
+}
+
+/** 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=
+ *  list right after a comma, so that continuation whitespace is all that
+ *  separates two rule names from being glued into one — the list is de-spaced
+ *  after it has been cut out, not here. X-Spam-Report is NOT unfolded: there
+ *  the line structure is the record structure. */
+function unfold(value: string): string {
+    return value.replace(/\r?\n/g, "");
+}
+
+/** Per-rule scores and descriptions out of X-Spam-Report, which reads:
+ *
+ *      *  6.0 URIBL_SBL Contains an URL's NS IP listed in the Spamhaus SBL
+ *      *      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. */
+function parseSpamReport(report: string): Map<string, { score: number; description: string }> {
+    const out = new Map<string, { score: number; description: string }>();
+    let current: { score: number; description: string } = null;
+    for (const raw of report.split(/\r?\n/)) {
+        const line = raw.replace(/^[ \t]*\*?[ \t]*/, "").trimEnd();
+        if (!line) continue;
+        const start = line.match(/^(-?\d+(?:\.\d+)?)\s+([A-Z0-9_]{3,})\s*(.*)$/);
+        if (start) {
+            current = { score: Number(start[1]), description: start[3].trim() };
+            out.set(start[2], current);
+            continue;
+        }
+        if (current && !line.startsWith("[")) current.description += " " + line;
+    }
+    for (const rule of out.values())
+        rule.description = rule.description
+            .replace(/\s+/g, " ")
+            .replace(/^(BODY|RAW|HEADER|URI|RBL):\s*/i, "")
+            .trim();
+    return out;
+}
+
+/**
+ * What the server said, taken apart: the rules that fired, what each one is
+ * evidence of, and whether the From line was proved independently.
+ *
+ * One mechanism, two consumers — the banner finding below and spamScoreOf's
+ * chip — so the banner and the chip can never disagree about what a message is.
+ */
+interface ServerSpamAnalysis {
+    score: number;
+    threshold: number;
+    flagged: boolean;
+    rules: SpamRule[];
+    /** Worst class that actually scored, forgery > association > other > bulk. */
+    kind: "forgery" | "association" | "bulk" | "unclassified";
+    /** DMARC-aligned pass at the receiving server: the sender is who it says. */
+    proved: boolean;
+    provedDomain: string;
+    provedPolicy: string;
+    /** The reader's own trained filter put this at 0-1% spam. */
+    bayesHam: boolean;
+    /** Authentication the receiving server saw fail, by name: "SPF", "DKIM",
+     *  "DMARC". Any of these is an identity finding on its own. */
+    authFailures: string[];
+    /** Top scoring rules, worst first, named for a human to judge in a second. */
+    reasons: string[];
+}
+
+function analyzeServerSpam(input: TrustInput): ServerSpamAnalysis {
+    const status = unfold(header(input.headerLines, "x-spam-status"));
+    const flag = header(input.headerLines, "x-spam-flag");
+    if (!status && !flag) return null;
+
+    const score = Number(status.match(/score=(-?[\d.]+)/)?.[1]);
+    const threshold = Number(status.match(/required=(-?[\d.]+)/)?.[1]);
+    const flagged = /^yes/i.test(status) || /^yes/i.test(flag);
+
+    const dmarc = dmarcProof(input);
+    const report = parseSpamReport(header(input.headerLines, "x-spam-report"));
+    // Everything up to the first lowercase key=value — SpamAssassin's trailing
+    // shortcircuit=/autolearn=/version= fields. Cutting on "not a rule name"
+    // rather than on whitespace is what keeps "...,WORD_INVIS shortcircuit=no"
+    // 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);
+
+    const rules: SpamRule[] = names.map(name => {
+        const found = report.get(name);
+        return {
+            name,
+            score: found ? found.score : NaN,
+            description: found ? found.description : "",
+            cls: classifyRule(name, dmarc.failed),
+        };
+    });
+
+    // 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
+    // of a report is not evidence the rule was free.
+    const scored = (r: SpamRule) => !(r.score <= 0);
+    const present = (cls: RuleClass) => rules.some(r => r.cls === cls && scored(r));
+    const kind = (dmarc.authFailures.length || present("forgery")) ? "forgery"
+        : present("association") ? "association"
+        : present("other") ? "unclassified"
+        : rules.length ? "bulk"
+        : "unclassified";
+
+    const reasons = rules
+        .filter(r => r.cls !== "neutral" && scored(r))
+        .sort((a, b) => (b.score || 0) - (a.score || 0))
+        .slice(0, 3)
+        .map(r => {
+            const num = Number.isFinite(r.score) ? `${r.score.toFixed(1)} ` : "";
+            return r.description ? `${num}${r.name} (${r.description})` : `${num}${r.name}`;
+        });
+
+    return {
+        score, threshold, flagged, rules, kind,
+        proved: dmarc.pass, provedDomain: dmarc.domain, provedPolicy: dmarc.policy,
+        bayesHam: rules.some(r => r.name === "BAYES_00" || r.name === "BAYES_01"),
+        authFailures: dmarc.authFailures,
+        reasons,
+    };
+}
+
+/**
+ * Did the receiving server's spam filter already say yes — and if so, to WHAT?
  *
  * The highest-value signal available, and it costs nothing: the mail server
  * ran SpamAssassin before delivery and wrote the answer into the message.
@@ -99,23 +364,61 @@ function bare(addr: string): string {
  * `X-Spam-Flag: NO` into a message they send, and treating that as a clean
  * bill of health would hand attackers a switch for turning the check off. A
  * forged YES only flags the forger's own mail, so the asymmetry is safe.
+ *
+ * The severity comes from the RULES, never from the number (Claude Code
+ * 2026-08-27):
+ *   - a forgery rule fired          -> danger. This is what red is for.
+ *   - the sender is DMARC-proved     -> info. The mail may well be unwanted,
+ *     and every rule that scored is     but "not what it says it is" is a
+ *     one this file can name, or        claim its own evidence contradicts.
+ *     the whole score is bulk rules
+ *   - anything else                  -> caution. Flagged, and the reason is
+ *                                      not identity — or is a rule this file
+ *                                      cannot classify, which is never a
+ *                                      reason to go quiet.
  */
-function serverSpamVerdict(lines: TrustInput["headerLines"]): TrustFinding {
-    const flag = header(lines, "x-spam-flag");
-    const status = header(lines, "x-spam-status");
-    if (!/^yes/i.test(flag) && !/^yes/i.test(status)) return null;
-
-    // "Yes, score=6.7 required=4.5 tests=..." — quote the numbers when they
-    // are there, so the reader sees how emphatic the verdict was.
-    const score = status.match(/score=([-\d.]+)/)?.[1];
-    const required = status.match(/required=([-\d.]+)/)?.[1];
+function serverSpamVerdict(input: TrustInput): TrustFinding {
+    const a = analyzeServerSpam(input);
+    if (!a || !a.flagged) return null;
+
+    const numbers = Number.isFinite(a.score) && Number.isFinite(a.threshold)
+        ? `SpamAssassin score ${a.score} of ${a.threshold}`
+        : "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")
+        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}`,
+        };
+
+    if (a.proved && a.kind !== "unclassified")
+        return {
+            id: "server-spam-verdict",
+            severity: "info",
+            text: `Your mail server scored this as spam, but ${a.provedDomain} proved it sent this.`,
+            detail: `DMARC pass, aligned${a.provedPolicy ? `, policy ${a.provedPolicy}` : ""}. ${numbers}${why}${bayes}`,
+        };
+
+    if (a.kind === "bulk")
+        return {
+            id: "server-spam-verdict",
+            severity: "info",
+            text: "Your mail server rates this bulk mail — nothing that scored tests who sent it.",
+            detail: `${numbers}${why}${bayes}`,
+        };
+
+    const proof = a.proved ? `${a.provedDomain} passed DMARC, so the From line is genuine. ` : "";
     return {
         id: "server-spam-verdict",
-        severity: "danger",
+        severity: "caution",
         text: "Your mail server classified this as spam before delivering it.",
-        detail: score && required
-            ? `SpamAssassin score ${score}, threshold ${required}`
-            : (status || flag || "X-Spam-Flag: YES"),
+        detail: `${proof}${numbers}${why}${bayes}`,
     };
 }
 
@@ -259,14 +562,14 @@ function redirectorLink(bodyHtml: string): TrustFinding {
  */
 export function assessMessageTrust(input: TrustInput): TrustFinding[] {
     const findings = [
-        serverSpamVerdict(input.headerLines),
+        serverSpamVerdict(input),
         selfSpoof(input),
         relayAuthMismatch(input),
         zeroWidthObfuscation(input.bodyText || ""),
         hiddenLinkOverlay(input.bodyHtml || ""),
         redirectorLink(input.bodyHtml || ""),
     ].filter(Boolean);
-    const rank = { danger: 0, caution: 1 };
+    const rank = { danger: 0, caution: 1, info: 2 };
     return findings.sort((a, b) => rank[a.severity] - rank[b.severity]);
 }
 
@@ -377,13 +680,28 @@ export interface SpamScore {
     threshold: number;
     /** The server's own yes/no, which is simply score >= threshold. */
     flagged: boolean;
+    /** What the rules that actually scored are evidence OF. `bulk` and a
+     *  `proved` sender are the two ways a high number can be honest mail —
+     *  the chip stays visible and says so, rather than going red at a number
+     *  and teaching the reader to ignore it. (Claude Code 2026-08-27) */
+    kind: "forgery" | "association" | "bulk" | "unclassified";
+    /** The From domain passed DMARC, aligned, at the receiving server. */
+    proved: boolean;
+    /** Top scoring rules, named — "6.0 URIBL_SBL (Contains an URL's NS IP
+     *  listed in the Spamhaus SBL blocklist)". A number alone is unactionable;
+     *  this can be judged in a second. */
+    reasons: string[];
 }
 
-export function spamScoreOf(headerLines: TrustInput["headerLines"]): SpamScore {
-    const status = header(headerLines, "x-spam-status");
-    if (!status) return null;
-    const score = Number(status.match(/score=([-\d.]+)/)?.[1]);
-    const threshold = Number(status.match(/required=([-\d.]+)/)?.[1]);
-    if (!Number.isFinite(score) || !Number.isFinite(threshold)) return null;
-    return { score, threshold, flagged: /^yes/i.test(status) };
+export function spamScoreOf(input: TrustInput): SpamScore {
+    const a = analyzeServerSpam(input);
+    if (!a || !Number.isFinite(a.score) || !Number.isFinite(a.threshold)) return null;
+    return {
+        score: a.score,
+        threshold: a.threshold,
+        flagged: a.flagged,
+        kind: a.kind,
+        proved: a.proved,
+        reasons: a.reasons,
+    };
 }