@bobfrankston/rmfmail 1.2.280 → 1.2.281

package/packages/mailx-types/trust.ts

@@ -0,0 +1,239 @@
+/**
+ * Why a message looks forged.
+ *
+ * Not a spam filter — a spam filter guesses, and a guess that fires on real
+ * mail teaches you to click past it. Everything here is EVIDENCE: a verdict
+ * your own mail server already reached, or a construct in the message that
+ * legitimate mail does not contain. Each finding names what was found and what
+ * it means, so the reader can check it rather than trust a score.
+ *
+ * Written 2026-08-25 after two phishes landed looking clean in the reader
+ * (Bob: "this is an attack — could you do a better job of identifying it as
+ * bogus?"). Both carried all of the following, and mailx surfaced NONE of it:
+ *
+ *   X-Spam-Flag: YES                        <- his own server, score 6.7/4.5
+ *   Authentication-Results: ... spf=fail
+ *   From: bobip@bobf.frankston.com          <- his own address, forged
+ *   To:   bobip@bobf.frankston.com
+ *   Return-Path: <3EDTkWNvbY@visionsurveysqld.com.au>
+ *   <area coords="0,0,10000,10000" href="http://.../redirect.php?newurl=...">
+ *
+ * No header in that list was read anywhere in the codebase, and the one
+ * impersonation check that existed (displayNameClaimsOtherAddress) needs a
+ * display name, which these messages did not have. The whole visible card was
+ * one hidden link through an open redirector, with the victim's own address
+ * base64'd into the fragment so the landing page could prefill it.
+ *
+ * Deliberately NOT included: bare SPF failure on mail that isn't claiming to
+ * be you. Forwarded mail fails SPF constantly, and flagging that would be
+ * exactly the cry-wolf banner this is trying not to be.
+ */
+
+/** 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. */
+    id: "server-spam-verdict" | "self-spoof" | "hidden-link-overlay" | "redirector-link";
+    /** `danger`: near-certain forgery. `caution`: worth a second look. */
+    severity: "danger" | "caution";
+    /** One line, naming what was found. Never "this message is suspicious". */
+    text: string;
+    /** The specific evidence — a header value, a host, a score. */
+    detail: string;
+}
+
+export interface TrustInput {
+    /** Every header line, in order, as mailparser's `headerLines`. Repeated
+     *  headers matter: Authentication-Results and Received both appear more
+     *  than once and the interesting one is not always the first. */
+    headerLines: { key: string; line: string }[];
+    /** Envelope From address. */
+    fromAddress: string;
+    /** Addresses belonging to the reader — their own aliases. Used only to
+     *  recognise a message claiming to BE them. */
+    ownAddresses: string[];
+    /** Sanitized HTML body, for the link-construct checks. */
+    bodyHtml: string;
+}
+
+/** First value of a header, case-insensitive. */
+function header(lines: TrustInput["headerLines"], name: string): string {
+    const want = name.toLowerCase();
+    for (const h of lines) {
+        if ((h.key || "").toLowerCase() !== want) continue;
+        const colon = h.line.indexOf(":");
+        return colon < 0 ? "" : h.line.slice(colon + 1).trim();
+    }
+    return "";
+}
+
+/** All values of a repeated header. */
+function headerAll(lines: TrustInput["headerLines"], name: string): string[] {
+    const want = name.toLowerCase();
+    const out: string[] = [];
+    for (const h of lines) {
+        if ((h.key || "").toLowerCase() !== want) continue;
+        const colon = h.line.indexOf(":");
+        if (colon >= 0) out.push(h.line.slice(colon + 1).trim());
+    }
+    return out;
+}
+
+function bare(addr: string): string {
+    const m = (addr || "").match(/[^\s<>,;]+@[^\s<>,;]+/);
+    return (m ? m[0] : addr || "").toLowerCase().replace(/[.,;]+$/, "");
+}
+
+/**
+ * Did the receiving server's spam filter already say yes?
+ *
+ * The highest-value signal available, and it costs nothing: the mail server
+ * ran SpamAssassin before delivery and wrote the answer into the message.
+ * mailx was throwing it away.
+ *
+ * Only a POSITIVE verdict is trusted, never a negative one. Anyone can inject
+ * `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.
+ */
+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];
+    return {
+        id: "server-spam-verdict",
+        severity: "danger",
+        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"),
+    };
+}
+
+/**
+ * Does the message claim to come from the reader themselves, while failing the
+ * authentication that would prove it?
+ *
+ * Either half alone is ordinary — people really do mail themselves notes, and
+ * forwarded mail really does fail SPF. Together they are not: mail genuinely
+ * from your own account authenticates as your own account. This is the most
+ * common shape of targeted phish, because a From line showing your own address
+ * defeats every visual check a reader makes.
+ *
+ * Requires an EXPLICIT failure. A message with no Authentication-Results at
+ * all (internal mail that never crossed a trust boundary) is not evidence of
+ * anything and must not fire this.
+ */
+function selfSpoof(input: TrustInput): TrustFinding {
+    const from = bare(input.fromAddress);
+    if (!from) return null;
+    const own = new Set(input.ownAddresses.map(bare).filter(Boolean));
+    if (!own.has(from)) return null;
+
+    const auth = headerAll(input.headerLines, "authentication-results").join(" ; ");
+    const failed = [
+        /\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);
+    if (!failed.length) return null;
+
+    // Name the envelope sender when it disagrees — that is the address that
+    // actually sent this, and seeing it beside the claim is the whole story.
+    const envelope = bare(header(input.headerLines, "return-path"));
+    const envelopeNote = envelope && envelope !== from ? `; actually sent by ${envelope}` : "";
+    return {
+        id: "self-spoof",
+        severity: "danger",
+        text: `This claims to be from your own address, ${from}, but it did not come from your account.`,
+        detail: `${failed.join(" and ")} authentication failed${envelopeNote}`,
+    };
+}
+
+/** Bigger than any real image. An honest layout never needs a hotspot this
+ *  large; a forger picks an absurd number so they don't have to know the
+ *  rendered size. Not a tuned threshold — a sanity bound. */
+const OVERLAY_MIN_EDGE_PX = 2000;
+
+/**
+ * Is an entire image covered by one invisible link?
+ *
+ * `<area coords="0,0,10000,10000">` turns every pixel of an image into a link
+ * with no underlined text, no visible URL, and no safe area to click. Real
+ * mail uses image maps almost never, and never at that size.
+ */
+function hiddenLinkOverlay(bodyHtml: string): TrustFinding {
+    for (const m of bodyHtml.matchAll(/<area\b[^>]*>/gi)) {
+        const tag = m[0];
+        const href = tag.match(/href\s*=\s*["']([^"']+)["']/i)?.[1];
+        if (!href) continue;
+        const coords = (tag.match(/coords\s*=\s*["']([^"']+)["']/i)?.[1] || "")
+            .split(/[,\s]+/).map(Number).filter(n => Number.isFinite(n));
+        if (coords.length < 4) continue;
+        const width = Math.abs(coords[2] - coords[0]);
+        const height = Math.abs(coords[3] - coords[1]);
+        if (width < OVERLAY_MIN_EDGE_PX || height < OVERLAY_MIN_EDGE_PX) continue;
+        let host = href;
+        try { host = new URL(href).hostname; } catch { /* keep the raw href */ }
+        return {
+            id: "hidden-link-overlay",
+            severity: "danger",
+            text: "The picture in this message is one large hidden link — clicking anywhere on it goes to the same place.",
+            detail: `${width}x${height} clickable area over the image, pointing at ${host}`,
+        };
+    }
+    return null;
+}
+
+/**
+ * Does a link route through a redirector carrying its real destination in the
+ * query string?
+ *
+ * `castanet-sa.fr/modules/babel/redirect.php?newurl=https%3A%2F%2Fevil.example`
+ * borrows a real site's reputation: the visible host is a legitimate business
+ * whose redirect script was left open, and the destination appears only
+ * percent-encoded inside a parameter. Reporting the ENDPOINT is the point — a
+ * reader cannot be expected to URL-decode a query string.
+ */
+function redirectorLink(bodyHtml: string): TrustFinding {
+    for (const m of bodyHtml.matchAll(/href\s*=\s*["']([^"']+)["']/gi)) {
+        let url: URL;
+        try { url = new URL(m[1]); } catch { continue; }
+        if (!/^https?:$/.test(url.protocol)) continue;
+        for (const [, value] of url.searchParams) {
+            let target: URL;
+            try { target = new URL(value); } catch { continue; }
+            if (!/^https?:$/.test(target.protocol)) continue;
+            if (target.hostname === url.hostname) continue;   // same-site, not laundering
+            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}`,
+            };
+        }
+    }
+    return null;
+}
+
+/**
+ * Everything findable about this message, worst first.
+ *
+ * Returns an empty array for ordinary mail — the caller then shows nothing,
+ * rather than a reassuring "looks fine" this cannot support. Absence of
+ * evidence is not a clean bill of health.
+ */
+export function assessMessageTrust(input: TrustInput): TrustFinding[] {
+    const findings = [
+        serverSpamVerdict(input.headerLines),
+        selfSpoof(input),
+        hiddenLinkOverlay(input.bodyHtml || ""),
+        redirectorLink(input.bodyHtml || ""),
+    ].filter(Boolean);
+    const rank = { danger: 0, caution: 1 };
+    return findings.sort((a, b) => rank[a.severity] - rank[b.severity]);
+}