@bobfrankston/mailx-types 0.1.59 → 0.1.63

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, spamScoreOf } from "./trust.js";
+export type { TrustFinding, TrustInput, SpamScore } 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, spamScoreOf } 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.63",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",

package/trust.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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" | "relay-auth-mismatch" | "zero-width-obfuscation" | "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;
+    /** Plain-text body, for the character-level checks. Separate from the HTML
+     *  because markup legitimately contains things prose does not, and the
+     *  zero-width test would trip over an entity or an attribute value. */
+    bodyText?: 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[];
+/**
+ * The receiving server's spam score, whether or not it crossed the threshold.
+ *
+ * Separate from the findings on purpose. A finding is an accusation and only
+ * fires on evidence; this is a measurement, and the reader asked to see the
+ * number itself (Bob 2026-08-25: "should we have a flag ... with the spam
+ * assassin number and a color code?"). The sextortion mail is exactly why:
+ * 2.7 against a 4.5 threshold is not "clean", it is "did not quite trip the
+ * wire", and those are very different things to a person deciding whether to
+ * trust a message.
+ *
+ * Returns null when the server left no score — most mail from providers that
+ * filter server-side and say nothing in the headers.
+ */
+export interface SpamScore {
+    score: number;
+    threshold: number;
+    /** The server's own yes/no, which is simply score >= threshold. */
+    flagged: boolean;
+}
+export declare function spamScoreOf(headerLines: TrustInput["headerLines"]): SpamScore;
+//# sourceMappingURL=trust.d.ts.map

package/trust.js

@@ -0,0 +1,354 @@
+/**
+ * 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 Authentication-Results header to exist. A message without one
+ * never crossed a trust boundary — it is your own mail, handled internally —
+ * and is not evidence of anything. That case is the overwhelming majority:
+ * 10,034 of the 10,338 self-claimed messages in a 50,000-message scan of Bob's
+ * store had no such header at all.
+ *
+ * `spf=none` counts as "not authenticated", not just `fail`. A domain with no
+ * SPF record published can never produce a failure, only a shrug — so treating
+ * `none` as neutral leaves the least-protected domain the least defended.
+ * bobf.frankston.com publishes no SPF, and that is precisely the hole the
+ * 2026-08-25 sextortion mail walked through: SpamAssassin scored it 2.7
+ * against a 4.5 threshold and delivered it. In that same 50,000-message scan
+ * `spf=none` on self-claimed mail occurred 18 times and was spam nearly every
+ * time ("Settle your debt", "AAA Final notice", "McAfee Protection Plan
+ * Ended"); legitimate self-mail was in the no-header group, untouched by 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(" ; ");
+    if (!auth)
+        return null;
+    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);
+    // Nothing failed, but did anything actually PASS? "spf=none dkim=none" is
+    // not a clean bill of health for a message claiming to be you.
+    if (!failed.length) {
+        if (/\b(spf|dkim|dmarc)=pass\b/i.test(auth))
+            return null;
+        const envelopeAddr = bare(header(input.headerLines, "return-path"));
+        const note = envelopeAddr && envelopeAddr !== from ? `; envelope sender ${envelopeAddr}` : "";
+        return {
+            id: "self-spoof",
+            severity: "danger",
+            text: `This claims to be from your own address, ${from}, and nothing proves it came from your account.`,
+            detail: `no SPF, DKIM or DMARC result to check against${note} — your domain publishes no SPF record, so forgery cannot be detected by the sending side`,
+        };
+    }
+    // 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),
+        relayAuthMismatch(input),
+        zeroWidthObfuscation(input.bodyText || ""),
+        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]);
+}
+/**
+ * Did the relay record a different account than the one the message claims?
+ *
+ * Shared hosts stamp the identity that actually authenticated to submit the
+ * message. That stamp is added by the RELAY, downstream of whoever sent it, so
+ * a forger cannot remove or edit it — which makes disagreement between the
+ * stamp and the From line about as close to proof as mail headers get.
+ *
+ * The 2026-08-25 sextortion mail (Bob: "note that the origin is different than
+ * the from domain in antiabuse and in source-auth"):
+ *
+ *   From:            universe@bobf.frankston.com
+ *   X-Source-Auth:   admin@calebjross.com
+ *   X-Source-Cap:    (base64) calebjro;calebjro;box2202.bluehost.com
+ *   Message-ID:      <...@calebjross.com>
+ *
+ * A Bluehost cPanel account belonging to an unrelated domain authenticated and
+ * sent mail wearing Bob's address. SpamAssassin scored the whole thing 2.7
+ * against a 4.5 threshold and let it through.
+ *
+ * Compared at the registrable-domain level, not the full address: a host that
+ * legitimately sends for a domain authenticates as some account AT that
+ * domain, and the local part varies for perfectly ordinary reasons.
+ */
+const RELAY_IDENTITY_HEADERS = [
+    "x-source-auth", // cPanel / Exim (Bluehost, HostGator, most shared hosts)
+    "x-authenticated-sender", // Postfix / Communigate
+    "x-auth-id",
+    "x-authenticated-user",
+];
+function relayAuthMismatch(input) {
+    const from = bare(input.fromAddress);
+    const fromDomain = from.split("@")[1] || "";
+    if (!fromDomain)
+        return null;
+    for (const name of RELAY_IDENTITY_HEADERS) {
+        const stamped = bare(header(input.headerLines, name));
+        const stampedDomain = stamped.split("@")[1] || "";
+        if (!stampedDomain || stampedDomain === fromDomain)
+            continue;
+        // Sub/parent-domain is the same organisation — mail.example.com
+        // sending for example.com is ordinary. Cross-organisation is not.
+        if (stampedDomain.endsWith("." + fromDomain) || fromDomain.endsWith("." + stampedDomain))
+            continue;
+        return {
+            id: "relay-auth-mismatch",
+            severity: "danger",
+            text: `The account that actually sent this belongs to someone else: ${stampedDomain}, not ${fromDomain}.`,
+            detail: `the sending server recorded ${stamped} as the authenticated sender, while the message claims to be from ${from}`,
+        };
+    }
+    return null;
+}
+/**
+ * Is the text stuffed with invisible characters to break word matching?
+ *
+ * Zero-width space, zero-width non-joiner, zero-width joiner and the
+ * zero-width no-break space render as nothing, so a reader sees plain prose
+ * while every filter matching on words sees gibberish. The 2026-08-25
+ * sextortion mail put one between nearly every pair of letters — "i regret to
+ * inform you" reached the parser as `i re‍gret t‌o ‌in​f‌orm​ you`. SpamAssassin
+ * spotted it (UNICODE_OBFU_ZW_MANY) and still scored the message 2.7 against a
+ * 4.5 threshold, so it was delivered.
+ *
+ * Counted only BETWEEN TWO LATIN LETTERS, which is what obfuscation looks like
+ * and what the legitimate uses do not: an emoji ZWJ sequence joins pictographs,
+ * Arabic and Indic ZWNJ sit between their own scripts' letters, and a soft
+ * hyphen marks a break opportunity rather than splitting a word mid-render.
+ *
+ * The count guards against a single stray character surviving a copy-paste out
+ * of a web page — it is a sanity bound, not a tuned dial. Prose does not
+ * accumulate dozens of these by accident; the sample message had over 900.
+ */
+const ZERO_WIDTH_MIN_OCCURRENCES = 12;
+function zeroWidthObfuscation(bodyText) {
+    if (!bodyText)
+        return null;
+    const between = bodyText.match(/[A-Za-z][​‌‍][A-Za-z]/g);
+    const count = between ? between.length : 0;
+    if (count < ZERO_WIDTH_MIN_OCCURRENCES)
+        return null;
+    return {
+        id: "zero-width-obfuscation",
+        severity: "danger",
+        text: "The words in this message are stuffed with invisible characters to get past spam filters.",
+        detail: `${count} zero-width characters hidden inside words — legitimate mail has no reason to do this`,
+    };
+}
+export function spamScoreOf(headerLines) {
+    const status = header(headerLines, "x-spam-status");
+    if (!status)
+        return null;
+    const score = Number(status.match(/score=([-\d.]+)/)?.[1]);
+    const threshold = Number(status.match(/required=([-\d.]+)/)?.[1]);
+    if (!Number.isFinite(score) || !Number.isFinite(threshold))
+        return null;
+    return { score, threshold, flagged: /^yes/i.test(status) };
+}
+//# sourceMappingURL=trust.js.map