@bobfrankston/mailx-types 0.1.63 → 0.1.67

package/package.json

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

package/trust.d.ts

@@ -32,8 +32,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. */
@@ -86,6 +88,17 @@ 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 declare function spamScoreOf(headerLines: TrustInput["headerLines"]): SpamScore;
+export declare function spamScoreOf(input: TrustInput): SpamScore;
 //# sourceMappingURL=trust.d.ts.map

package/trust.js

@@ -56,8 +56,233 @@ function bare(addr) {
     const m = (addr || "").match(/[^\s<>,;]+@[^\s<>,;]+/);
     return (m ? m[0] : addr || "").toLowerCase().replace(/[.,;]+$/, "");
 }
+/** 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 = [
+    /^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 = [
+    /^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 = [
+    /^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 = [
+    /^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, dmarcFailed) {
+    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's spam filter already say yes?
+ * 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) {
+    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 };
+}
+/** 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) {
+    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) {
+    const out = new Map();
+    let current = 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;
+}
+function analyzeServerSpam(input) {
+    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 = 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) => !(r.score <= 0);
+    const present = (cls) => 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";
+    // Two proofs SpamAssassin states in its own rule list, which mail that
+    // never crossed a trust boundary carries INSTEAD of an Authentication-Results
+    // header — Bob's own message to John Levine about spam handling, 2026-08-27,
+    // had neither AR nor DMARC and got a caution banner reading "links and
+    // attachments here should not be opened" on prose he had just written:
+    //
+    //   ALL_TRUSTED    Passed through trusted hosts only via SMTP
+    //   DKIM_VALID_AU  Message has a valid DKIM or DK signature from author's domain
+    //
+    // DKIM_VALID_AU is the same evidence DMARC alignment rests on — the author
+    // domain signed it and the signature verified — so it proves the From line on
+    // its own. ALL_TRUSTED says the message reached the mailbox without passing
+    // through a host the server distrusts, which is Bob's own authenticated
+    // submission; nothing could have injected it in transit. (What flagged his
+    // message was URIBL_DBL_SPAM 8.0 on blueorchestra.org — the domain he was
+    // quoting IN a discussion about spam. Guilt by association at its purest.)
+    const has = (name) => rules.some(r => r.name === name);
+    const provedBy = dmarc.pass ? "dmarc"
+        : has("DKIM_VALID_AU") ? "dkim"
+            : has("ALL_TRUSTED") ? "trusted"
+                : "";
+    const fromDomain = (bare(input.fromAddress).split("@")[1] || "").toLowerCase();
+    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: !!provedBy, provedBy,
+        provedDomain: dmarc.domain || fromDomain, 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.
@@ -67,23 +292,73 @@ function bare(addr) {
  * `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) {
-    const flag = header(lines, "x-spam-flag");
-    const status = header(lines, "x-spam-status");
-    if (!/^yes/i.test(flag) && !/^yes/i.test(status))
+/** How the From line was proved, in the reader's terms — named so it can be
+ *  checked against the headers rather than believed. */
+function provedNote(a) {
+    switch (a.provedBy) {
+        case "dmarc":
+            return `DMARC pass, aligned${a.provedPolicy ? `, policy ${a.provedPolicy}` : ""}.`;
+        case "dkim":
+            return `Valid signature from ${a.provedDomain}, the sending domain itself (DKIM_VALID_AU).`;
+        case "trusted":
+            return "It passed through trusted hosts only (ALL_TRUSTED) — nothing untrusted handled it.";
+        default:
+            return "";
+    }
+}
+function serverSpamVerdict(input) {
+    const a = analyzeServerSpam(input);
+    if (!a || !a.flagged)
         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];
+    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: a.provedBy === "trusted"
+                ? "Your mail server scored this as spam, but it reached you without leaving your own systems."
+                : `Your mail server scored this as spam, but ${a.provedDomain} proved it sent this.`,
+            detail: `${provedNote(a)} ${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 ? `${provedNote(a)} ` : "";
     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}`,
     };
 }
 /**
@@ -243,14 +518,14 @@ function redirectorLink(bodyHtml) {
  */
 export function assessMessageTrust(input) {
     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]);
 }
 /**
@@ -341,14 +616,17 @@ function zeroWidthObfuscation(bodyText) {
         detail: `${count} zero-width characters hidden inside words — legitimate mail has no reason to do this`,
     };
 }
-export function spamScoreOf(headerLines) {
-    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))
+export function spamScoreOf(input) {
+    const a = analyzeServerSpam(input);
+    if (!a || !Number.isFinite(a.score) || !Number.isFinite(a.threshold))
         return null;
-    return { score, threshold, flagged: /^yes/i.test(status) };
+    return {
+        score: a.score,
+        threshold: a.threshold,
+        flagged: a.flagged,
+        kind: a.kind,
+        proved: a.proved,
+        reasons: a.reasons,
+    };
 }
 //# sourceMappingURL=trust.js.map