@bobfrankston/mailx-types 0.1.82 → 0.1.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.82",
+  "version": "0.1.86",
   "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.

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)
@@ -334,6 +367,8 @@ function analyzeServerSpam(input) {
         bayesHam: rules.some(r => r.name === "BAYES_00" || r.name === "BAYES_01"),
         authFailures: dmarc.authFailures,
         reasons,
+        intermediary: provedIntermediary(input),
+        signers: dkimSigners(input),
     };
 }
 /**
@@ -385,9 +420,25 @@ 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 } : {};
+    // Say WHICH party and HOW, in the finding itself (Bob 2026-09-08: "the
+    // banner should tell which and how"). The action's label is quoted so
+    // the reader can match it to the button — and to the allowlist.jsonc
+    // entry it writes, `trustedIntermediaries`.
+    const relayNote = relay && !a.proved
+        ? `. Sent on the author's behalf by ${relay}, which signed it; "Trust ${relay} as an intermediary" stops this note for mail ${relay} signs.`
+        : "";
     const numbers = Number.isFinite(a.score) && Number.isFinite(a.threshold)
         ? `SpamAssassin score ${a.score} of ${a.threshold}`
         : "flagged by SpamAssassin";
@@ -438,7 +489,8 @@ function serverSpamVerdict(input) {
         id: "server-spam-verdict",
         severity: "caution",
         text: "Your mail server classified this as spam before delivering it.",
-        detail: `${proof}${numbers}${why}${bayes}`,
+        detail: `${proof}${numbers}${why}${bayes}${relayNote}`,
+        ...via,
     };
 }
 /**
@@ -596,6 +648,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 {
@@ -608,6 +668,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 {
@@ -620,11 +682,21 @@ 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));
+            // Which party, and how — or why there is no party (Bob 2026-09-08).
+            const how = signer
+                ? ` ${signer} signed this message; "Trust ${signer} as an intermediary" stops this warning for links through ${signer} in mail it signs.`
+                : ` Nobody signed this message for ${url.hostname}, so there is no intermediary to trust; only the sender could vouch for the link.`;
             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}`,
+                detail: `${url.hostname} -> ${target.hostname}.${how}`,
+                ...(signer ? { via: signer } : {}),
             };
         }
     }
@@ -747,7 +819,7 @@ export function spamScoreOf(input) {
         proved: a.proved,
         provedBy: a.provedBy,
         bulkOnly: a.bulkOnly,
-        trusted: !!input.senderTrusted && a.proved && a.kind !== "forgery" && !a.authFailures.length,
+        trusted: ((!!input.senderTrusted && a.proved) || !!a.intermediary) && a.kind !== "forgery" && !a.authFailures.length,
         reasons: a.reasons,
     };
 }