@bobfrankston/mailx-types 0.1.59 → 0.1.61

package/index.d.ts

@@ -4,6 +4,8 @@
  * This is the contract between client and server.
  */
 export { CONTACT_RULES } from "./contact-rules.js";
+export { assessMessageTrust } from "./trust.js";
+export type { TrustFinding, TrustInput } 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,6 +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 } from "./trust.js";
 // Shared contacts.jsonc mutations — one implementation for desktop + Android.
 export { addContactsDenylistEntry, addContactsPreferredEntry, } from "./contacts-config.js";
 // Group-name expansion for recipient fields. Lets users type a group name
@@ -105,6 +106,23 @@ export function sanitizeHtml(html) {
     clean = clean.replace(/<select\b[^>]*>[\s\S]*?<\/select>/gi, "[blocked: select]");
     clean = clean.replace(/<button\b[^>]*>([\s\S]*?)<\/button>/gi, "$1");
     clean = clean.replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, "");
+    // Disarm image maps. An <area> hotspot makes part of an image a link with
+    // no underlined text, no visible URL, and nothing to hover — and a forger
+    // sizes it to cover the whole picture, so there is no safe pixel to click.
+    // Two phishes on 2026-08-25 used exactly that: a "shared document" card
+    // whose every pixel was <area coords="0,0,10000,10000"> pointing at an
+    // open redirector. This sanitizer stripped their forms and inputs and left
+    // that armed.
+    //
+    // Image maps have no legitimate use in mail, so this is unconditional
+    // rather than a size threshold — nothing to tune and nothing to slip past
+    // by picking a smaller rectangle. The image still renders; only its hidden
+    // clickability goes. The reader is told rather than left to wonder why the
+    // picture stopped responding: assessMessageTrust (trust.ts) raises
+    // hidden-link-overlay from the RAW html and the viewer explains it.
+    // (Claude Code 2026-08-25)
+    clean = clean.replace(/<map\b[^>]*>[\s\S]*?<\/map>/gi, "");
+    clean = clean.replace(/\s+usemap\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "");
     return { html: clean, hasRemoteContent };
 }
 /**

package/package.json

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

package/trust.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function assessMessageTrust(input: TrustInput): TrustFinding[];
+//# sourceMappingURL=trust.d.ts.map

package/trust.js

@@ -0,0 +1,228 @@
+/**
+ * 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.
+ */
+/** First value of a header, case-insensitive. */
+function header(lines, name) {
+    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, name) {
+    const want = name.toLowerCase();
+    const out = [];
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    for (const m of bodyHtml.matchAll(/href\s*=\s*["']([^"']+)["']/gi)) {
+        let url;
+        try {
+            url = new URL(m[1]);
+        }
+        catch {
+            continue;
+        }
+        if (!/^https?:$/.test(url.protocol))
+            continue;
+        for (const [, value] of url.searchParams) {
+            let target;
+            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) {
+    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]);
+}
+//# sourceMappingURL=trust.js.map