@bobfrankston/mailx-types 0.1.80 → 0.1.84

package/package.json

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

package/trust.d.ts

@@ -40,6 +40,12 @@ export interface TrustFinding {
     text: string;
     /** The specific evidence — a header value, a host, a score. */
     detail: string;
+    /** A party that provably handled this message and could be vouched for
+     *  as an intermediary (allowlist.jsonc `trustedIntermediaries`) — the
+     *  DKIM signer behind a redirector, or the Sender: domain that signed on
+     *  the author's behalf. Set only when such a party exists and is not yet
+     *  trusted, so the viewer can offer the action by name. (2026-09-08) */
+    via?: string;
 }
 export interface TrustInput {
     /** Every header line, in order, as mailparser's `headerLines`. Repeated
@@ -68,6 +74,17 @@ export interface TrustInput {
      *  because markup legitimately contains things prose does not, and the
      *  zero-width test would trip over an entity or an attribute value. */
     bodyText?: string;
+    /** Domains the reader trusts to carry mail on OTHER people's behalf —
+     *  Google Calendar, Zoom, DocuSign — from allowlist.jsonc
+     *  `trustedIntermediaries`. Bob 2026-09-08, on a Google Calendar
+     *  invitation whose every link is wrapped in google.com/url?q=…: "how do
+     *  I mark zoom and sites like that as trusted intermediaries?" An entry
+     *  counts only on a message the intermediary PROVABLY handled (a
+     *  dkim=pass for its domain, or a DMARC pass when it is the From) — an
+     *  open redirector on google.com is the classic laundering hop, and a
+     *  list that cleared it on sight would be a switch any forger could
+     *  flip by pasting the link. See provedIntermediary. */
+    trustedIntermediaries?: string[];
 }
 /**
  * Everything findable about this message, worst first.
@@ -109,6 +126,10 @@ export interface SpamScore {
      *  may not exist (Bob's own mail carries no Authentication-Results at
      *  all). */
     provedBy: "dmarc" | "dkim" | "trusted" | "";
+    /** Every rule that scored is a bulk-mail or blocklist test. The chip's
+     *  tooltip may say so ONLY when this is true — it is a claim about all of
+     *  the rules, and the reader can read them underneath it. */
+    bulkOnly: 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. */

package/trust.js

@@ -166,6 +166,39 @@ function classifyRule(name, dmarcFailed) {
  * against the actual From line anyway, because an Authentication-Results about
  * some other message proves nothing about this one.
  */
+/** Domains whose DKIM signature the receiving server verified, from the
+ *  topmost Authentication-Results — the one the sender cannot write. A
+ *  signer is a party that provably handled the message: it need not be the
+ *  author (Google Calendar signs d=google.com on an invitation From the
+ *  organizer), which is exactly what makes it an intermediary. */
+function dkimSigners(input) {
+    const auth = headerAll(input.headerLines, "authentication-results")[0] || "";
+    const out = [];
+    for (const part of auth.split(";")) {
+        if (!/\bdkim=pass\b/i.test(part))
+            continue;
+        const d = (part.match(/header\.d=([^\s;,]+)/i)?.[1] || "").toLowerCase();
+        if (d && !out.includes(d))
+            out.push(d);
+    }
+    return out;
+}
+/** The entry in `trustedIntermediaries` that provably handled this message,
+ *  or "" — proof being a verified signature from its domain, or a DMARC pass
+ *  when it is the author. The list alone proves nothing. (2026-09-08) */
+function provedIntermediary(input) {
+    const list = (input.trustedIntermediaries || []).map(d => (d || "").trim().toLowerCase()).filter(Boolean);
+    if (!list.length)
+        return "";
+    const proved = dkimSigners(input);
+    const dmarc = dmarcProof(input);
+    if (dmarc.pass && dmarc.domain)
+        proved.push(dmarc.domain);
+    for (const entry of list)
+        if (proved.some(p => sameOrg(p, entry)))
+            return entry;
+    return "";
+}
 function dmarcProof(input) {
     const auth = headerAll(input.headerLines, "authentication-results")[0] || "";
     if (!auth)
@@ -282,6 +315,16 @@ function analyzeServerSpam(input) {
     const unknownCouldFlagAlone = !unknown.length ? false
         : !Number.isFinite(unknownWeight) || !Number.isFinite(threshold) ? true
             : unknownWeight >= threshold;
+    // What the chip may claim about the rule set. "Every rule that scored is a
+    // bulk-mail test" is a statement about ALL of them, so it has to be
+    // checked against all of them — deriving it from `proved` (which says
+    // nothing about the rules) or from `kind` (the worst class, which says
+    // nothing about the rest) asserts something the code never looked at.
+    // The Altis Hotels welcome mail, 2026-09-03 (Bob: "marked as spam but is
+    // valid"): DMARC-proved, so the chip said "scored by bulk-mail or
+    // blocklist rules" — with 3.2 of its 8.3 coming from KAM_ACCOUNTPHISH,
+    // which is neither, listed directly underneath.
+    const bulkOnly = rules.every(r => !scored(r) || r.cls === "bulk" || r.cls === "neutral");
     const kind = (dmarc.authFailures.length || present("forgery")) ? "forgery"
         : present("association") ? "association"
             : unknownCouldFlagAlone ? "unclassified"
@@ -319,11 +362,13 @@ function analyzeServerSpam(input) {
     });
     return {
         score, threshold, flagged, rules, kind,
-        proved: !!provedBy, provedBy,
+        proved: !!provedBy, provedBy, bulkOnly,
         provedDomain: dmarc.domain || fromDomain, provedPolicy: dmarc.policy,
         bayesHam: rules.some(r => r.name === "BAYES_00" || r.name === "BAYES_01"),
         authFailures: dmarc.authFailures,
         reasons,
+        intermediary: provedIntermediary(input),
+        signers: dkimSigners(input),
     };
 }
 /**
@@ -375,9 +420,18 @@ function serverSpamVerdict(input) {
     // into furniture. (Bob 2026-08-28, having just clicked "Always:
     // *@icecer.com" on a conference announcement: "I accepted the server so
     // shouldn't this be considered safe?")
-    const trustedAndProved = input.senderTrusted && a.proved;
+    // A trusted INTERMEDIARY that provably handled the message answers the
+    // same question the same way — Google Calendar's invitation on Aaron's
+    // behalf is wanted because the reader said google.com is (2026-09-08).
+    const trustedAndProved = (input.senderTrusted && a.proved) || !!a.intermediary;
     if (trustedAndProved && a.kind !== "forgery" && !a.authFailures.length)
         return null;
+    // The party that sent this on the author's behalf, when it signed: the
+    // Sender: header names it and a verified signature backs the claim. That
+    // is the one the reader can sensibly vouch for as an intermediary.
+    const senderDomain = (bare(header(input.headerLines, "sender")).split("@")[1] || "").toLowerCase();
+    const relay = senderDomain ? a.signers.find(s => sameOrg(s, senderDomain)) : "";
+    const via = relay && !a.proved ? { via: relay } : {};
     const numbers = Number.isFinite(a.score) && Number.isFinite(a.threshold)
         ? `SpamAssassin score ${a.score} of ${a.threshold}`
         : "flagged by SpamAssassin";
@@ -401,11 +455,19 @@ function serverSpamVerdict(input) {
                 : `Your mail server scored this as spam, but ${a.provedDomain} proved it sent this.`,
             detail: `${provedNote(a)} ${numbers}${why}${bayes}`,
         };
+    // Same discipline as the chip: "nothing that scored tests who sent it" is
+    // a claim about every rule, so it is made only when every rule was
+    // actually looked at and classified. `kind === "bulk"` does not establish
+    // that — an unclassified rule that could not have flagged the message on
+    // its own leaves the kind at bulk while remaining, by definition, a rule
+    // this file cannot say anything about.
     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.",
+            text: a.bulkOnly
+                ? "Your mail server rates this bulk mail — nothing that scored tests who sent it."
+                : "Your mail server rates this bulk mail.",
             detail: `${numbers}${why}${bayes}`,
         };
     const proof = a.proved ? `${provedNote(a)} ` : "";
@@ -421,6 +483,7 @@ function serverSpamVerdict(input) {
         severity: "caution",
         text: "Your mail server classified this as spam before delivering it.",
         detail: `${proof}${numbers}${why}${bayes}`,
+        ...via,
     };
 }
 /**
@@ -578,6 +641,14 @@ function provedSenderDomain(input) {
 function redirectorLink(input) {
     const bodyHtml = input.bodyHtml || "";
     const senderDomain = provedSenderDomain(input);
+    // 3. (2026-09-08) The redirector belongs to a reader-listed intermediary
+    //    that provably handled the message. Google Calendar wraps every link
+    //    in an invitation as google.com/url?q=…, signs the mail d=google.com,
+    //    and is not the From — rule 2 cannot save it, and the reader's answer
+    //    is "I trust google.com to do that". Same second-party logic: the
+    //    host spending its reputation is the host that signed.
+    const intermediary = provedIntermediary(input);
+    const signers = dkimSigners(input);
     for (const m of bodyHtml.matchAll(/href\s*=\s*["']([^"']+)["']/gi)) {
         let url;
         try {
@@ -590,6 +661,8 @@ function redirectorLink(input) {
             continue;
         if (senderDomain && sameOrg(url.hostname, senderDomain))
             continue; // the sender's own host
+        if (intermediary && sameOrg(url.hostname, intermediary))
+            continue; // a trusted relay's own host
         for (const [, value] of url.searchParams) {
             let target;
             try {
@@ -602,11 +675,17 @@ function redirectorLink(input) {
                 continue;
             if (sameOrg(target.hostname, url.hostname))
                 continue; // same site, not laundering
+            // Name the signer behind this redirector, if there is one, so the
+            // viewer can offer "trust google.com as an intermediary" — and
+            // only then: a redirector nobody signed for has no party to vouch
+            // for, and a list entry could not clear it anyway.
+            const signer = signers.find(s => sameOrg(s, url.hostname));
             return {
                 id: "redirector-link",
                 severity: "caution",
                 text: `A link hides where it goes: it passes through ${url.hostname} and ends at ${target.hostname}.`,
                 detail: `${url.hostname} -> ${target.hostname}`,
+                ...(signer ? { via: signer } : {}),
             };
         }
     }
@@ -728,7 +807,8 @@ export function spamScoreOf(input) {
         kind: a.kind,
         proved: a.proved,
         provedBy: a.provedBy,
-        trusted: !!input.senderTrusted && a.proved && a.kind !== "forgery" && !a.authFailures.length,
+        bulkOnly: a.bulkOnly,
+        trusted: ((!!input.senderTrusted && a.proved) || !!a.intermediary) && a.kind !== "forgery" && !a.authFailures.length,
         reasons: a.reasons,
     };
 }