@bobfrankston/mailx-types 0.1.88 → 0.1.92

package/index.d.ts

@@ -4,9 +4,9 @@
  * This is the contract between client and server.
  */
 export { CONTACT_RULES } from "./contact-rules.js";
-export { assessMessageTrust, spamScoreOf } from "./trust.js";
+export { assessMessageTrust, spamScoreOf, TRUST_LIST_KEYS } from "./trust.js";
 export { logIfChanged, clearLogState } from "./log-changes.js";
-export type { TrustFinding, TrustInput, SpamScore } from "./trust.js";
+export type { TrustFinding, TrustInput, SpamScore, TrustListType } from "./trust.js";
 export type { MailxApi } from "./mailx-api.js";
 export { addContactsDenylistEntry, addContactsPreferredEntry, type PreferredContactEntry, type CloudReadFn, type CloudWriteFn, } from "./contacts-config.js";
 export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } from "./groups.js";

package/index.js

@@ -7,7 +7,7 @@
 // this barrel so a single source-of-truth (contact-rules.jsonc) drives
 // junk-contact filtering on every platform.
 export { CONTACT_RULES } from "./contact-rules.js";
-export { assessMessageTrust, spamScoreOf } from "./trust.js";
+export { assessMessageTrust, spamScoreOf, TRUST_LIST_KEYS } from "./trust.js";
 export { logIfChanged, clearLogState } from "./log-changes.js";
 // Shared contacts.jsonc mutations — one implementation for desktop + Android.
 export { addContactsDenylistEntry, addContactsPreferredEntry, } from "./contacts-config.js";

package/package.json

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

package/trust.d.ts

@@ -28,6 +28,19 @@
  * be you. Forwarded mail fails SPF constantly, and flagging that would be
  * exactly the cry-wolf banner this is trying not to be.
  */
+/** What the reader can vouch for, and the allowlist.jsonc key each one is
+ *  written to. One table, shared by the desktop service and the Android
+ *  web-service, so "trust X" cannot land in different keys on the two
+ *  platforms — the merge is by key. (Claude Code 2026-09-09; the two
+ *  services each carried their own ternary before, and adding `list` to one
+ *  and not the other is exactly the drift this prevents.) */
+export declare const TRUST_LIST_KEYS: {
+    readonly sender: "trustedSenders";
+    readonly domain: "trustedDomains";
+    readonly intermediary: "trustedIntermediaries";
+    readonly list: "trustedLists";
+};
+export type TrustListType = keyof typeof TRUST_LIST_KEYS;
 /** One piece of evidence that a message is not what it claims to be. */
 export interface TrustFinding {
     /** Stable identifier — for tests, logs, and any future suppression UI. */
@@ -46,6 +59,10 @@ export interface TrustFinding {
      *  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;
+    /** The mailing list that provably delivered this message (its List-Id),
+     *  when the list is not yet in allowlist.jsonc `trustedLists`, so the
+     *  viewer can offer "Trust the ‹list› list". (2026-09-09) */
+    list?: string;
 }
 export interface TrustInput {
     /** Every header line, in order, as mailparser's `headerLines`. Repeated
@@ -85,6 +102,17 @@ export interface TrustInput {
      *  list that cleared it on sight would be a switch any forger could
      *  flip by pasting the link. See provedIntermediary. */
     trustedIntermediaries?: string[];
+    /** Mailing lists the reader subscribes to, by List-Id ("ieee-cs.mit.edu"),
+     *  from allowlist.jsonc `trustedLists`. Bob 2026-09-09: "how do I say
+     *  that this is a valid mailing list message". A list that does not
+     *  rewrite From (Mailman only does so when the author's domain publishes
+     *  a DMARC policy; gmail.com does not) delivers the poster's own address,
+     *  and its subject tag and footer break every signature on the way — so
+     *  the author can never be proved, and per-sender trust has nothing to
+     *  hold on to. The LIST can be proved: the receiving server records
+     *  spf=pass for the list's bounce address, or dkim=pass for its domain.
+     *  An entry counts only on such a message. See listProof. */
+    trustedLists?: string[];
 }
 /**
  * Everything findable about this message, worst first.
@@ -137,6 +165,13 @@ export interface SpamScore {
     /** The reader approved this sender AND the sender is proved: the score is
      *  still true, and no longer worth showing. The viewer hides the chip. */
     trusted: boolean;
+    /** The mailing list that delivered this (List-Id), or "". With
+     *  `listProved` — the receiving server recorded the list's host sending
+     *  it — the viewer can offer "Trust the ‹list› list"; `listTrusted` says
+     *  the reader already has. (2026-09-09) */
+    listId: string;
+    listProved: boolean;
+    listTrusted: boolean;
 }
 export declare function spamScoreOf(input: TrustInput): SpamScore;
 //# sourceMappingURL=trust.d.ts.map

package/trust.js

@@ -28,6 +28,18 @@
  * be you. Forwarded mail fails SPF constantly, and flagging that would be
  * exactly the cry-wolf banner this is trying not to be.
  */
+/** What the reader can vouch for, and the allowlist.jsonc key each one is
+ *  written to. One table, shared by the desktop service and the Android
+ *  web-service, so "trust X" cannot land in different keys on the two
+ *  platforms — the merge is by key. (Claude Code 2026-09-09; the two
+ *  services each carried their own ternary before, and adding `list` to one
+ *  and not the other is exactly the drift this prevents.) */
+export const TRUST_LIST_KEYS = {
+    sender: "trustedSenders",
+    domain: "trustedDomains",
+    intermediary: "trustedIntermediaries",
+    list: "trustedLists",
+};
 /** First value of a header, case-insensitive. */
 function header(lines, name) {
     const want = name.toLowerCase();
@@ -135,7 +147,28 @@ const NEUTRAL_RULES = [
     /^DKIMWL_/, /^RCVD_IN_(DNSWL|MSPIKE_H|IADB)/,
     /^SHORTCIRCUIT$/, /^AWL$/, /^NO_RELAYS$/, /^ALL_TRUSTED$/,
 ];
-function classifyRule(name, dmarcFailed) {
+/** Rules that test whether the From domain matches the path the message took
+ *  — which a mailing list breaks BY DESIGN. Mailman re-sends the poster's
+ *  message from its own host with its own bounce address, so a Gmail From
+ *  arrives without a Google hop or a Google envelope, and the author's
+ *  signature no longer verifies over the tagged subject and appended footer.
+ *  Every one of these fired on an ordinary IEEE-CS meeting announcement
+ *  (Bob 2026-09-09) and together they painted it as a phish. They are
+ *  evidence of forgery only when nothing else explains the mismatch; on a
+ *  message a list PROVABLY delivered (see listProof) the list is the
+ *  explanation, and they are set to neutral. URL and phishing listings are
+ *  not in this set: a list member can post a bad link like anyone else. */
+const LIST_RELAY_RULES = [
+    /^POSSIBLE_GMAIL_PHISHER$/, // From gmail.com, not sent through Google
+    /^FREEMAIL_FORGED_FROMDOMAIN$/, // From and envelope are different freemail domains
+    /^(NML_|DKIM_)ADSP_/, // author domain did not sign what arrived
+    /^FORGED_[A-Z]+_RCVD$/, // From ‹provider› without ‹provider›'s Received
+];
+function classifyRule(name, dmarcFailed, listRelayed = false) {
+    if (listRelayed)
+        for (const re of LIST_RELAY_RULES)
+            if (re.test(name))
+                return "neutral";
     if (dmarcFailed && name === "DKIM_INVALID")
         return "forgery";
     for (const re of FORGERY_RULES)
@@ -183,6 +216,30 @@ function dkimSigners(input) {
     }
     return out;
 }
+/** Did the From domain's OWN organisation pass authentication at the
+ *  receiving server — a verified signature for the From domain, or an SPF
+ *  pass for an envelope at the From domain? This is DMARC's relaxed
+ *  alignment computed locally, for domains that publish no DMARC policy and
+ *  so never get a dmarc= verdict. Only the From domain's own servers can pass
+ *  SPF as that domain or sign as it, so a forger's pass for their own domain
+ *  does not count. Returns which proof, or "". (2026-09-09) */
+function alignedPass(input) {
+    const fromDomain = (bare(input.fromAddress).split("@")[1] || "").toLowerCase();
+    if (!fromDomain)
+        return "";
+    if (dkimSigners(input).some(d => sameOrg(d, fromDomain)))
+        return "dkim";
+    const auth = headerAll(input.headerLines, "authentication-results")[0] || "";
+    for (const part of auth.split(";")) {
+        if (!/\bspf=pass\b/i.test(part))
+            continue;
+        const mailfrom = (part.match(/(?:spf|smtp)\.mailfrom=([^\s;,]+)/i)?.[1] || "").toLowerCase();
+        const domain = mailfrom.includes("@") ? mailfrom.split("@")[1] : mailfrom;
+        if (domain && sameOrg(domain, fromDomain))
+            return "spf";
+    }
+    return "";
+}
 /** 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) */
@@ -199,6 +256,49 @@ function provedIntermediary(input) {
             return entry;
     return "";
 }
+/** The mailing list this message came through, and whether the receiving
+ *  server proved the list sent it. (2026-09-09)
+ *
+ *  Identity is the List-Id (RFC 2919), the one header that is the same on
+ *  every post to the list whoever wrote it — `<ieee-cs.mit.edu>` — so it is
+ *  what `trustedLists` is keyed on. The list's HOST is the Sender: domain
+ *  (Mailman sets `Sender: list-bounces@host`) or the List-Id's own domain.
+ *
+ *  Proof is the topmost Authentication-Results, which the sender cannot
+ *  write: `spf=pass` for a bounce address at the list's host — SPF is checked
+ *  against the envelope, and a list's envelope IS the list — or `dkim=pass`
+ *  for the list's domain, which Mailman 3 and Sympa add. A List-Id alone is
+ *  a header anyone can type; without the server's pass it proves nothing,
+ *  and `trustedLists` never counts on such a message. */
+function listProof(input) {
+    const none = { id: "", proved: false, host: "" };
+    const raw = header(input.headerLines, "list-id");
+    if (!raw)
+        return none;
+    // `Meeting Announcements <ieee-cs.mit.edu>` or bare `<ieee-cs.mit.edu>`;
+    // the angle-bracketed token is the identifier, the rest is a comment.
+    const id = (raw.match(/<([^>]+)>/)?.[1] || raw).trim().toLowerCase();
+    if (!id)
+        return none;
+    const senderDomain = (bare(header(input.headerLines, "sender")).split("@")[1] || "").toLowerCase();
+    const hosts = [senderDomain, id].filter(Boolean);
+    const auth = headerAll(input.headerLines, "authentication-results")[0] || "";
+    for (const part of auth.split(";")) {
+        if (/\bspf=pass\b/i.test(part)) {
+            // iecc writes `spf.mailfrom=user@host`, Microsoft `smtp.mailfrom=host`.
+            const mailfrom = (part.match(/(?:spf|smtp)\.mailfrom=([^\s;,]+)/i)?.[1] || "").toLowerCase();
+            const domain = mailfrom.includes("@") ? mailfrom.split("@")[1] : mailfrom;
+            if (domain && hosts.some(h => sameOrg(domain, h)))
+                return { id, proved: true, host: domain };
+        }
+        if (/\bdkim=pass\b/i.test(part)) {
+            const d = (part.match(/header\.d=([^\s;,]+)/i)?.[1] || "").toLowerCase();
+            if (d && hosts.some(h => sameOrg(d, h)))
+                return { id, proved: true, host: d };
+        }
+    }
+    return { id, proved: false, host: "" };
+}
 function dmarcProof(input) {
     const auth = headerAll(input.headerLines, "authentication-results")[0] || "";
     if (!auth)
@@ -275,6 +375,20 @@ function analyzeServerSpam(input) {
     const threshold = Number(status.match(/required=(-?[\d.]+)/)?.[1]);
     const flagged = /^yes/i.test(status) || /^yes/i.test(flag);
     const dmarc = dmarcProof(input);
+    // A list the server proved delivered this message explains two things
+    // that otherwise read as forgery: the author's signature no longer
+    // verifying (the list tagged the subject and appended a footer), and the
+    // From domain not matching the path (the list re-sent it from its own
+    // host). Both are removed from the evidence on a PROVED list whether or
+    // not the reader trusts it — the explanation is a fact about the
+    // headers, and the trust is a separate question answered below. SPF and
+    // DMARC failures stay: SPF is checked against the list's own envelope,
+    // and a list that lets a DMARC failure through is not one to be quiet
+    // about. (2026-09-09)
+    const listFound = listProof(input);
+    const trustedLists = (input.trustedLists || []).map(l => (l || "").trim().toLowerCase());
+    const list = { ...listFound, trusted: listFound.proved && trustedLists.includes(listFound.id) };
+    const authFailures = list.proved && !dmarc.failed ? dmarc.authFailures.filter(f => f !== "DKIM") : dmarc.authFailures;
     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"
@@ -288,7 +402,7 @@ function analyzeServerSpam(input) {
             name,
             score: found ? found.score : NaN,
             description: found ? found.description : "",
-            cls: classifyRule(name, dmarc.failed),
+            cls: classifyRule(name, dmarc.failed, list.proved),
         };
     });
     // A rule that scored zero or negative did not put this message over any
@@ -325,7 +439,7 @@ function analyzeServerSpam(input) {
     // 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"
+    const kind = (authFailures.length || present("forgery")) ? "forgery"
         : present("association") ? "association"
             : unknownCouldFlagAlone ? "unclassified"
                 : rules.length ? "bulk"
@@ -365,10 +479,11 @@ function analyzeServerSpam(input) {
         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,
+        authFailures,
         reasons,
         intermediary: provedIntermediary(input),
         signers: dkimSigners(input),
+        list,
     };
 }
 /**
@@ -423,7 +538,10 @@ function serverSpamVerdict(input) {
     // 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;
+    // A trusted mailing LIST answers it for every post the list provably
+    // delivered, whoever wrote it — the From line is the list's word, not
+    // the author's, and the reader subscribed to the list (2026-09-09).
+    const trustedAndProved = (input.senderTrusted && a.proved) || !!a.intermediary || a.list.trusted;
     if (trustedAndProved && a.kind !== "forgery" && !a.authFailures.length)
         return null;
     // The party that sent this on the author's behalf, when it signed: the
@@ -439,6 +557,14 @@ function serverSpamVerdict(input) {
     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.`
         : "";
+    // The list that provably delivered this, named the same way, with the
+    // action that writes `trustedLists`. Offered only while the author is
+    // unproved and the list is not yet trusted: a proved author needs no
+    // list, and a trusted list returned above.
+    const listNote = a.list.proved && !a.list.trusted && !a.proved
+        ? `. Delivered by the ${a.list.id} mailing list — ${a.list.host} proved it sent this — which re-sent the author's message from its own host, so nothing proves the From line; "Trust the ${a.list.id} list" stops this note for mail the list delivers.`
+        : "";
+    const viaList = listNote ? { list: a.list.id } : {};
     const numbers = Number.isFinite(a.score) && Number.isFinite(a.threshold)
         ? `SpamAssassin score ${a.score} of ${a.threshold}`
         : "flagged by SpamAssassin";
@@ -483,14 +609,16 @@ function serverSpamVerdict(input) {
             id: "server-spam-verdict",
             severity: "caution",
             text: "This claims to be a sender you trust, but nothing proves it is.",
-            detail: `No DMARC pass, no valid signature from the sending domain, and it passed through hosts your server does not trust. ${numbers}${why}`,
+            detail: `No DMARC pass, no valid signature from the sending domain, and it passed through hosts your server does not trust. ${numbers}${why}${listNote}`,
+            ...viaList,
         };
     return {
         id: "server-spam-verdict",
         severity: "caution",
         text: "Your mail server classified this as spam before delivering it.",
-        detail: `${proof}${numbers}${why}${bayes}${relayNote}`,
+        detail: `${proof}${numbers}${why}${bayes}${relayNote}${listNote}`,
         ...via,
+        ...viaList,
     };
 }
 /**
@@ -529,6 +657,27 @@ function selfSpoof(input) {
     const auth = headerAll(input.headerLines, "authentication-results").join(" ; ");
     if (!auth)
         return null;
+    // The From domain passed DMARC, aligned, at the receiving server: the
+    // message provably came from that domain, which is the opposite of a
+    // spoof. Checked BEFORE the failure scan because the scan reads every
+    // Authentication-Results and every signature — an ISOC list post
+    // (2026-09-09) carried dkim=pass d=elists.isoc.org, dmarc=pass
+    // header.from=elists.isoc.org, AND dkim=fail for the original author's
+    // standardstrack.com signature the list had broken, and that one fail
+    // painted the whole message red as "did not come from your account"
+    // (the list address was the Delivered-To, so it counted as Bob's own).
+    // One failed signature on a message with an aligned pass is not
+    // evidence about the From line; the pass is.
+    //
+    // The same proof without the dmarc= verdict: a From domain that publishes
+    // no DMARC policy gets no dmarc=pass, but its own SPF pass or its own
+    // verified signature is the very evidence DMARC would have aligned on.
+    // The AMW list (berglist.com, 2026-09-09): spf=pass for
+    // amw-bounces@berglist.com, dkim=pass d=berglist.com, and dkim=fail for
+    // the gmail.com author signature the list broke — flagged as a spoof of
+    // the list's own address.
+    if (dmarcProof(input).pass || alignedPass(input))
+        return null;
     const failed = [
         /\bspf=(fail|softfail)\b/i.test(auth) ? "SPF" : "",
         /\bdkim=(fail|permerror)\b/i.test(auth) ? "DKIM" : "",
@@ -833,8 +982,11 @@ export function spamScoreOf(input) {
         proved: a.proved,
         provedBy: a.provedBy,
         bulkOnly: a.bulkOnly,
-        trusted: ((!!input.senderTrusted && a.proved) || !!a.intermediary) && a.kind !== "forgery" && !a.authFailures.length,
+        trusted: ((!!input.senderTrusted && a.proved) || !!a.intermediary || a.list.trusted) && a.kind !== "forgery" && !a.authFailures.length,
         reasons: a.reasons,
+        listId: a.list.id,
+        listProved: a.list.proved,
+        listTrusted: a.list.trusted,
     };
 }
 //# sourceMappingURL=trust.js.map