@bobfrankston/mailx-types 0.1.61 → 0.1.63

package/index.d.ts

@@ -4,8 +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 { 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,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 } from "./trust.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

package/package.json

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

package/trust.d.ts

@@ -31,7 +31,7 @@
 /** 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";
+    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". */
@@ -54,6 +54,10 @@ export interface TrustInput {
     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.
@@ -63,4 +67,25 @@ export interface TrustInput {
  * 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

@@ -96,9 +96,21 @@ function serverSpamVerdict(lines) {
  * 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.
+ * 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);
@@ -108,13 +120,27 @@ function selfSpoof(input) {
     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);
-    if (!failed.length)
-        return null;
+    // 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"));
@@ -219,10 +245,110 @@ 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