@bobfrankston/mailx-settings 0.1.62 → 0.1.63

package/docs/spam-false-positives.md

@@ -0,0 +1,208 @@
+# Spam false positives — why the trust banner fires on mail Bob asked for
+
+*Session note, 2026-08-27 (Claude Code), at v1.2.285. State: **first cut shipped
+2026-08-27** — ideas (1) and (2) below are implemented in `packages/mailx-types/trust.ts`
+with tests over all four samples in `tests/trust.test.ts`; sender trust (7) is still open.
+See "What shipped" at the end.*
+
+Bob 2026-08-27: *"better ideas for detecting false positives for spam"*, then
+*"Trusting senders may be a route."*
+
+## The four sample messages
+
+All still on disk under `C:\Users\Bob\.rmfmail\mailxstore\bobma\`:
+
+| file | sender | SA score | why it scored | Bayes | DMARC | Delivered-To |
+|---|---|---|---|---|---|---|
+| `f1/f1e6c04745e2403b89afa56de88af993.eml` | Blue Orchestra via Constant Contact | **10.9 YES** | `SH_DBL_HEADERS` 8.0 (blueorchestra.org in Spamhaus DBL) + `DCC_CHECK` 3.0 | BAYES_00 | pass, aligned, **p=reject** | actblue@bob.ma |
+| `cc/ccdf707f078b451697c68681f1dc0a2f.eml` | Adobe MAX | 3.9 no | 100% bulk rules: DCC_CHECK, DCC_REPUT_90_94, PYZOR_CHECK, MAILING_LIST_MULTI, HTML_FONT_SIZE_HUGE, HTML_IMAGE_RATIO_04, WORD_INVIS | BAYES_00 | pass, aligned, p=reject | adobe@bob.ma |
+| `9c/9c5a0904f8974558ac714d139ec8a235.eml` | Mokin via Shopify/SendGrid | **4.9 YES** | `URIBL_SBL` 6.0 | BAYES_00 | pass, aligned, p=quarantine | mokin@bob.ma |
+| `01/01fe446185024fd8beb851f8c29a87c2.eml` | Josh Shapiro via ActionKit | 2.2 (quiet — correct) | DCC_REPUT_70_89, KAM_TRACKIMAGE, URIBL_CSS_A, HTML_FONT_SIZE_LARGE | BAYES_00 | pass, aligned, p=reject | actblue@bob.ma |
+
+Two of the four raise the red banner ("This message is not what it says it is" /
+"Links and attachments here should not be opened"). Adobe raises the amber
+`spam score 3.9 of 4.5` chip. Shapiro is quiet.
+
+## What the sample proves
+
+**1. Shapiro is quiet by luck, not by discrimination.** The chip floor in
+`client/components/message-viewer.ts` is `spam.score >= spam.threshold / 2` = 2.25.
+Shapiro scored 2.2. It is the *same kind of mail* as Adobe — ESP-sent political/marketing
+bulk, same rule families. Landing 0.05 on the right side of an arbitrary line is not a
+classifier. **Do not respond by nudging that constant** — raising it to 0.75×threshold
+silences Adobe at 3.9 and still fires on the next legitimate newsletter at 4.0.
+
+**2. The big rules that flagged these are guilt by association, at third and fourth order.**
+Mokin's `X-Spam-Report` reads verbatim:
+
+```
+*  6.0 URIBL_SBL Contains an URL's NS IP listed in the Spamhaus SBL blocklist
+*      [URI: ns12.xincache.com/112.80.181.111]
+```
+
+link → its domain → that domain's nameserver → the nameserver's IP → SBL. Fourth order,
+worth more than the entire 4.5 threshold on its own. Blue Orchestra is the same shape:
+`SH_DBL_HEADERS` 8.0 because blueorchestra.org (a real advocacy org) sits in the DBL.
+Neither rule says anything about whether *this message* is forged.
+
+**3. Every one of the four carries `BAYES_00` (score 0.0000).** That is Bob's own
+SpamAssassin at gal.iecc.com, trained on years of Bob's own mail, saying 0–1% spam
+probability. Everything that pushed these over the line is a *network* rule about a third
+party, not a statement about the content.
+
+**4. Every one of the four passes DMARC, aligned, on a published reject/quarantine policy.**
+The domain owner staked their policy on it and the signature verified. The From line is
+*proved*. On such a message the headline "This message is not what it says it is" is
+**factually false**.
+
+**5. Every one arrived at a Bob-minted tag address**, and in two cases the tag names the
+sender's own domain: `mokin@bob.ma` → mokintech.com, `adobe@bob.ma` → adobe.com.
+
+## Root cause
+
+`serverSpamVerdict()` in `packages/mailx-types/trust.ts` consumes SpamAssassin's **bottom
+line** — a number tuned to answer "should this be delivered" — and reuses it to answer a
+different question, "is this forged", then prints the strongest banner in the app. The
+`tests=` list that would distinguish the two questions is in the same header and is never
+parsed. `spamScoreOf()` reads `score=` and `required=` out of `X-Spam-Status` and drops
+everything else.
+
+This is the same mistake trust.ts's own header warns against — its doctrine is
+*"Everything here is EVIDENCE… Each finding names what was found and what it means, so
+the reader can check it rather than trust a score."* The score finding is the one item in
+the file that is a bare number with no named evidence.
+
+## Ideas, ranked by leverage
+
+**1. A DMARC-aligned pass vetoes the danger headline.** ~10 lines, no tuning, kills the
+worst FP class outright. Does not make mail *wanted* — makes "not what it says it is"
+unsayable. Parse the existing `Authentication-Results` (already read by `selfSpoof`).
+
+**2. Classify `tests=` instead of summing it.** Three disjoint classes:
+
+- *bulk* — `DCC_*`, `PYZOR_*`, `RAZOR2_*`, `MAILING_LIST_MULTI`, `KAM_UNSUB1`,
+  `KAM_*MARKETINGBL*`, `KAM_TRACKIMAGE`, `KAM_REALLYHUGEIMGSRC`, `HTML_FONT_SIZE_*`,
+  `HTML_IMAGE_RATIO_*`, `MIME_HTML_ONLY`, `WORD_INVIS`, `HTML_TAG_BALANCE_*`,
+  `URIBL_GREY`, `URIBL_CSS_A`, `SH_BODYURI_REVERSE_CSS`
+- *forgery* — `SPF_FAIL`/`SOFTFAIL`, DKIM invalid **with** DMARC fail, `FORGED_*`, `SPOOF_*`
+- *guilt by association* — `URIBL_SBL`, `SH_DBL_HEADERS`, `URIBL_BLACK`
+
+A score composed entirely of the bulk class is a **bulk verdict**, however high. Adobe's
+3.9 is 100% bulk. Say "your server rates this bulk marketing" in the neutral register of
+the remote-content banner, or say nothing. Red is reserved for the forgery class.
+
+**3. `BAYES_00` is a demotion signal.** Flagged + BAYES_00 + DMARC-aligned means "network
+lists dislike a third party this message mentions", not "this resembles spam Bob receives".
+
+**4. The Delivered-To tag is a record of consent, and it is free.** Bob minted
+`mokin@bob.ma` and gave it to exactly one correspondent. When the tag's local part matches
+the authenticated sending domain, that is documented subscription. Needs no maintenance,
+unlike the allowlist. `deliveredTo` is already parsed at `packages/mailx-store/store.ts:543`
+and already flows to the viewer — nothing reads it for trust purposes.
+
+**5. Bob's own store is a better ham oracle than any RBL.** Prior messages from the same
+registrable domain that he read, replied to, or kept (not Junk, not deleted) — 50k+ rows of
+ground truth about his actual correspondents. A domain with 40 kept messages does not become
+a forger today because its nameserver landed in SBL.
+
+**6. Name the evidence for the score, as every other finding does.** `spam score 4.9 of 4.5`
+is unactionable; *"6.0 URIBL_SBL — the nameserver of a linked host is in Spamhaus SBL"* is
+judged in one second. Caveat found in the sample: `X-Spam-Report` appears only on flagged
+messages (present on Blue Orchestra + Mokin, absent on Adobe + Shapiro); `tests=` is always
+present, so degrade to rule names when the report is missing.
+
+**7. Extinguishable, not tuned** — see next section, this is the direction Bob picked.
+
+## Trusting senders — the direction Bob chose
+
+Bob 2026-08-27: *"Trusting senders may be a route."* Consistent with the standing rule that
+heuristic warnings should be **user-extinguishable rather than threshold-tuned**
+(memory: `allowlist_is_the_approved_sender_store`).
+
+What exists already and should be reused, not reinvented:
+
+- `allowlist.jsonc` **is** the approved-sender store; `getAllowlist()` at
+  `packages/mailx-service/index.ts:1980` returns
+  `{senders, domains, recipients, flaggedSenders, flaggedDomains}`, exposed over IPC at
+  `jsonrpc.ts:404` and bridged for Android at `mailx-store-web/android-bootstrap.ts:1794`.
+  Design doc: `docs/allowlist.md`.
+- The viewer already offers `✓ Trust all senders at <domain>` in the address context menu
+  (`client/components/message-viewer.ts:1371`), calling `approve("domain", dom)`.
+- `store.ts:570` already re-checks the recipient allowlist **with Delivered-To in hand** to
+  decide `allowRemote`. That is exactly the shape the trust suppression wants, one decision
+  earlier in the same function.
+
+What is missing:
+
+- Nothing consults the allowlist when computing `trust` / `spamScore` — an approved sender
+  still gets the red banner. `assessMessageTrust` is called at `store.ts:586` with no
+  allowlist input.
+- The trust banner has no inline action. A reader who has to find a context menu on an
+  address to say "this is mail I asked for" will not do it.
+
+Open design questions for next session:
+
+- **Trust key granularity**: envelope domain, From registrable domain, DKIM `d=` domain, or
+  the Delivered-To tag? Blue Orchestra argues against the From domain here —
+  `shared1.ccsend.com` is shared by every Constant Contact customer, so trusting it would
+  trust all of them; `blueorchestra.org` (Reply-To, and the domain in the DKIM-signed
+  `List-Unsubscribe`) is the real identity. Mokin argues the **tag** is the cleanest key —
+  `mokin@bob.ma` is single-purpose by construction.
+- Does trusting a sender suppress the *whole* banner, or only the bulk/association findings,
+  leaving genuine forgery evidence visible? Leaning: suppress the score chip and the
+  association findings, **never** the forgery class — a trusted domain can still be spoofed,
+  and that is precisely the case the banner exists for.
+- Auto-trust on a positive act (reply / move out of Junk / add to contacts) vs explicit only.
+
+## Recommended minimum first cut
+
+(1) + (2): DMARC-alignment veto plus rule classification. Together they silence all three
+false positives here and leave the 2026-08-25 sextortion/phish cases that motivated
+trust.ts untouched — those had spf=none/fail, no DKIM, no DMARC pass, and Bayes did not say
+0%. Sender-trust (7) then layers on top as the user-driven escape hatch rather than as the
+primary mechanism.
+
+## Files involved
+
+- `packages/mailx-types/trust.ts` — `serverSpamVerdict()`, `spamScoreOf()`, `assessMessageTrust()`
+- `packages/mailx-store/store.ts:586` — the single call site; has `deliveredTo`, `recipients`, raw `headerLines`
+- `client/components/message-viewer.ts:1655-1697` — the score chip (`threshold/2` floor) and the trust banner
+- `docs/allowlist.md` + `getAllowlist()` — the approved-sender store
+
+## What shipped, 2026-08-27
+
+Ideas (1) and (2), as the "recommended minimum first cut" below says. In
+`serverSpamVerdict()` / the new `analyzeServerSpam()` in
+`packages/mailx-types/trust.ts`:
+
+- `tests=` is parsed and every rule classified as **forgery**, **association**,
+  **bulk**, **neutral**, or **other** (`FORGERY_RULES` / `ASSOCIATION_RULES` /
+  `BULK_RULES` / `NEUTRAL_RULES`). A rule that scored zero or less cannot be the
+  reason a message is over the line, so it is not counted.
+- `X-Spam-Report` gives each rule its score and description, so findings name their
+  evidence — "8.0 SH_DBL_HEADERS (A domain found in headers … is listed in DBL)" —
+  and degrade to bare rule names when the report is absent (idea 6).
+- The **topmost** `Authentication-Results` is read for a DMARC-aligned pass, and its
+  `header.from=` is checked against the real From line. Only the topmost, because
+  headers are prepended: anything below it travelled with the message, and a forger
+  who could add `dmarc=pass` further down would have a switch for turning the banner
+  off.
+- Severity comes from the rules, never the number:
+  **danger** when a forgery rule fired or the server recorded an SPF/DKIM/DMARC
+  failure (phishing and malware URL listings count — a lookalike domain can get its
+  own valid DKIM); **info**, a new neutral severity with no headline and no
+  "do not open anything" footer, when the sender is proved and every rule that scored
+  is one the classifier can name, or the whole score is bulk; **caution** otherwise —
+  including a proved sender whose score came from unclassified rules, because unknown
+  is never a reason to go quiet. That last distinction is 326 messages in Bob's store.
+- `spamScoreOf()` returns `kind`, `proved` and `reasons` from the same analysis, so the
+  chip and the banner cannot disagree. The chip is grey when the sender is proved or
+  the score is all bulk, red only when the banner is. **The `threshold/2` floor is
+  unchanged.**
+
+Measured over 20,291 messages in the store: 1,131 were flagged spam, and every one of
+them used to get the red banner. Now 294 do (forgery), 672 are caution, 165 are quiet
+notes. All four samples above are quiet or neutral; the 2026-08-25 phishes stay red.
+
+Still open (C165): sender trust via `allowlist.jsonc`, the inline trust action on the
+banner, and the three design questions in the section above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-settings",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -17,7 +17,7 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/mailx-types": "^0.1.62",
+    "@bobfrankston/mailx-types": "^0.1.64",
     "jsonc-parser": "^3.3.1"
   },
   "repository": {
@@ -33,7 +33,7 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/mailx-types": "^0.1.62",
+      "@bobfrankston/mailx-types": "^0.1.64",
       "jsonc-parser": "^3.3.1"
     }
   }