@remit/mailbox-service 0.0.111 → 0.0.113

package/{src/heuristics/machineSenders.ts → dist/heuristics/machineSenders.js}

@@ -7,7 +7,6 @@
  * signature, so before issue #45 it reached the `personal` fallback and sat
  * alongside actual human correspondence.
  */
-
 /**
  * From local-parts that mean "this mailbox is not read by a person". Matched
  * case-insensitively against whole separator-delimited words, so `no-reply`,
@@ -18,36 +17,34 @@
  * wrong entry here silently buries real mail in `automated`.
  */
 const MACHINE_LOCAL_PARTS = new Set([
-	"noreply",
-	"donotreply",
-	"notification",
-	"notifications",
-	"notify",
-	"automailer",
-	"automated",
-	"autoreply",
-	"mailerdaemon",
-	"postmaster",
-	"bounce",
-	"bounces",
-	"alert",
-	"alerts",
+    "noreply",
+    "donotreply",
+    "notification",
+    "notifications",
+    "notify",
+    "automailer",
+    "automated",
+    "autoreply",
+    "mailerdaemon",
+    "postmaster",
+    "bounce",
+    "bounces",
+    "alert",
+    "alerts",
 ]);
-
 /**
  * Machine mailbox names that senders spell across separators. Joined into one
  * word before the local-part is split, so `no-reply` and `mailer.daemon` reduce
  * to a single token that {@link MACHINE_LOCAL_PARTS} can match.
  */
-const SPELLED_OUT_MACHINE_NAMES: ReadonlyArray<[RegExp, string]> = [
-	[/do-not-reply/g, "donotreply"],
-	[/donot-reply/g, "donotreply"],
-	[/no-reply/g, "noreply"],
-	[/mailer-daemon/g, "mailerdaemon"],
-	[/auto-reply/g, "autoreply"],
-	[/auto-mailer/g, "automailer"],
+const SPELLED_OUT_MACHINE_NAMES = [
+    [/do-not-reply/g, "donotreply"],
+    [/donot-reply/g, "donotreply"],
+    [/no-reply/g, "noreply"],
+    [/mailer-daemon/g, "mailerdaemon"],
+    [/auto-reply/g, "autoreply"],
+    [/auto-mailer/g, "automailer"],
 ];
-
 /**
  * Headers only bulk/notification infrastructure sets. `Feedback-ID` is the
  * per-campaign identifier SES, Google and other ESPs attach to programmatic
@@ -55,20 +52,18 @@ const SPELLED_OUT_MACHINE_NAMES: ReadonlyArray<[RegExp, string]> = [
  * vacation replies back, which only a machine sender asks for.
  */
 const MACHINE_HEADERS = ["feedback-id", "x-auto-response-suppress"];
-
 /**
  * Split a local-part into its separator-delimited words, with the spelled-out
  * machine names joined back up first. The `+tag` suffix is dropped: it labels a
  * subaddress, never the mailbox.
  */
-const toWords = (localPart: string): string[] => {
-	let canonical = localPart.toLowerCase().split("+")[0].replace(/[._]/g, "-");
-	for (const [pattern, replacement] of SPELLED_OUT_MACHINE_NAMES) {
-		canonical = canonical.replace(pattern, replacement);
-	}
-	return canonical.split("-").filter(Boolean);
+const toWords = (localPart) => {
+    let canonical = localPart.toLowerCase().split("+")[0].replace(/[._]/g, "-");
+    for (const [pattern, replacement] of SPELLED_OUT_MACHINE_NAMES) {
+        canonical = canonical.replace(pattern, replacement);
+    }
+    return canonical.split("-").filter(Boolean);
 };
-
 /**
  * True when any whole word of the From local-part is a known machine mailbox.
  *
@@ -79,12 +74,11 @@ const toWords = (localPart: string): string[] => {
  * separators the sender wrote catches the qualified forms without inventing a
  * match that spans two words.
  */
-export const isMachineLocalPart = (localPart: string): boolean =>
-	toWords(localPart).some((word) => MACHINE_LOCAL_PARTS.has(word));
-
-export const hasMachineHeader = (headerKeys: readonly string[]): boolean => {
-	for (const key of headerKeys) {
-		if (MACHINE_HEADERS.includes(key.toLowerCase())) return true;
-	}
-	return false;
+export const isMachineLocalPart = (localPart) => toWords(localPart).some((word) => MACHINE_LOCAL_PARTS.has(word));
+export const hasMachineHeader = (headerKeys) => {
+    for (const key of headerKeys) {
+        if (MACHINE_HEADERS.includes(key.toLowerCase()))
+            return true;
+    }
+    return false;
 };

package/dist/heuristics/senderMismatch.d.ts

@@ -0,0 +1,81 @@
+import { DisplayNameCorrespondence } from "@remit/domain-enums";
+import type { ParsedMail } from "mailparser";
+import type { FolderPlacement } from "./classifyPlacement.js";
+type CorrespondenceValue = (typeof DisplayNameCorrespondence)[keyof typeof DisplayNameCorrespondence];
+/**
+ * The two signals that survive a passing SPF/DKIM/DMARC check: a display name
+ * that belongs to nobody at the sending domain, and body links that leave it.
+ *
+ * Both are deliberately aggressive, and both are computed only for mail the
+ * provider's own filter already called spam or that sits in the Junk folder
+ * (see {@link extractSenderMismatch}).
+ * On a shared-tenant host — a free Atlassian, Salesforce or Zendesk instance —
+ * the verified subdomain is chosen by whoever signed up, so a passing signature
+ * proves the domain and nothing about the identity the message claims.
+ */
+export interface SenderMismatchSignals {
+    displayNameCorrespondence?: CorrespondenceValue;
+    offDomainLinkDomains?: string[];
+}
+export interface SenderMismatchContext {
+    fromDomain: string;
+    providerSpamClassified: boolean;
+    placement: FolderPlacement;
+    /**
+     * List-Unsubscribe present. Bulk mail routinely shows a brand name over an
+     * ESP's sending domain, so the display-name comparison says nothing there and
+     * is not made.
+     */
+    bulkSender: boolean;
+}
+/**
+ * Whether the From display name corresponds to the From domain.
+ *
+ * Containment decides: the normalised name, or any word of it, containing an
+ * entire domain candidate. `GitHub` contains the label `github` from
+ * `notifications.github.com`; `InfoMedics` contains no label of
+ * `serviceupdatebank.atlassian.net`.
+ *
+ * Only that direction counts — a domain candidate containing the (shorter)
+ * name does not. `ING Fraudedesk` is not a match for `secure-ing-verify.tk`
+ * just because the three-letter word "ing" sits inside "secureingverify":
+ * that is a coincidental substring of a longer label the domain owner chose,
+ * not a domain that names the brand. The direction this drops is exactly the
+ * one a short, valuable brand name is deliberately embedded into a longer,
+ * unrelated-looking domain to exploit — the live Dutch-bank shape this was
+ * fixed against (`ING`). A real short brand over its own domain (`ING` /
+ * `ing.nl`) still matches: name and label are then equal, and equality
+ * satisfies containment in either direction.
+ *
+ * A bounded edit distance is the secondary test, and only reaches names that
+ * nearly match a label — `InfoMedics` against `1nfomedics.nl`. It cannot promote
+ * an unrelated name on its own.
+ *
+ * A name that spells out an address is decided before any of that. Over the
+ * sending domain it claims nothing — `billing@` shown over
+ * `serviceupdatebank.atlassian.net` names the same party the envelope does.
+ * Over any other registrable domain it is the strongest non-correspondence
+ * signal there is: the message asserts, in the one field the recipient reads,
+ * that it comes from an address that cannot have sent it.
+ */
+export declare const classifyDisplayNameCorrespondence: (displayName: string | undefined, fromDomain: string) => CorrespondenceValue;
+/**
+ * Registrable domains the body's links point at, minus the sender's own.
+ *
+ * `mailto:`, `tel:`, in-page anchors and relative hrefs carry no destination
+ * domain and are skipped; anything else is resolved public-suffix-aware through
+ * tldts, so `co.uk` and `atlassian.net` both survive the comparison a naive dot
+ * split gets wrong.
+ */
+export declare const extractOffDomainLinkDomains: (parsed: ParsedMail, fromDomain: string) => string[];
+/**
+ * Both signals, gated on a spam verdict: the provider's own, or the message
+ * sitting in the Junk folder.
+ *
+ * The gate is what lets the checks be this aggressive: ordinary mail never
+ * reaches them, so a brand name over an ESP domain or a newsletter full of
+ * tracking links can never be flagged. Returns an empty object when the gate
+ * does not open — the fields stay absent, meaning "not compared".
+ */
+export declare const extractSenderMismatch: (parsed: ParsedMail, context: SenderMismatchContext) => SenderMismatchSignals;
+export {};

package/dist/heuristics/senderMismatch.js

@@ -0,0 +1,192 @@
+import { DisplayNameCorrespondence } from "@remit/domain-enums";
+import { getDomain, parse as parseHost } from "tldts";
+const MAX_LINK_DOMAINS = 10;
+const normalize = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, "");
+/**
+ * The parts of a host a display name could honestly correspond to: the
+ * registrable name without its public suffix, every subdomain label, and the
+ * registrable domain run together. The suffix itself is dropped — `net` and
+ * `com` sit inside half the brand names in existence.
+ */
+const correspondenceCandidates = (host) => {
+    const parsed = parseHost(host);
+    const labels = (parsed.subdomain ?? "").split(".");
+    if (parsed.domainWithoutSuffix !== null) {
+        labels.push(parsed.domainWithoutSuffix);
+    }
+    else {
+        labels.push(...host.split(".").slice(0, -1));
+    }
+    if (parsed.domain !== null)
+        labels.push(parsed.domain);
+    return labels.map(normalize).filter((label) => label.length >= 3);
+};
+const words = (displayName) => displayName
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length >= 3);
+const editDistance = (a, b) => {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+};
+const ADDRESS_SHAPE = /[^\s<>@,;:"]+@([a-z0-9-]+(?:\.[a-z0-9-]+)+)/i;
+const registrableDomain = (host) => getDomain(host) ?? host.toLowerCase();
+/**
+ * The registrable domain of the address a display name spells out, or
+ * `undefined` when it holds an `@` without an address behind it — `Bob @ Acme`
+ * asserts no address and is left to the ordinary comparison.
+ */
+const claimedAddressDomain = (displayName) => {
+    const host = ADDRESS_SHAPE.exec(displayName)?.[1];
+    if (host === undefined)
+        return undefined;
+    return registrableDomain(host);
+};
+/**
+ * The distance a name of this length may be from a domain label and still be
+ * read as an imitation of it. Tight on purpose: an unrelated brand name and an
+ * ESP's domain are always far apart, so distance alone must never decide.
+ */
+const lookalikeThreshold = (length) => {
+    if (length < 5)
+        return 0;
+    if (length < 9)
+        return 1;
+    return 2;
+};
+/**
+ * Whether the From display name corresponds to the From domain.
+ *
+ * Containment decides: the normalised name, or any word of it, containing an
+ * entire domain candidate. `GitHub` contains the label `github` from
+ * `notifications.github.com`; `InfoMedics` contains no label of
+ * `serviceupdatebank.atlassian.net`.
+ *
+ * Only that direction counts — a domain candidate containing the (shorter)
+ * name does not. `ING Fraudedesk` is not a match for `secure-ing-verify.tk`
+ * just because the three-letter word "ing" sits inside "secureingverify":
+ * that is a coincidental substring of a longer label the domain owner chose,
+ * not a domain that names the brand. The direction this drops is exactly the
+ * one a short, valuable brand name is deliberately embedded into a longer,
+ * unrelated-looking domain to exploit — the live Dutch-bank shape this was
+ * fixed against (`ING`). A real short brand over its own domain (`ING` /
+ * `ing.nl`) still matches: name and label are then equal, and equality
+ * satisfies containment in either direction.
+ *
+ * A bounded edit distance is the secondary test, and only reaches names that
+ * nearly match a label — `InfoMedics` against `1nfomedics.nl`. It cannot promote
+ * an unrelated name on its own.
+ *
+ * A name that spells out an address is decided before any of that. Over the
+ * sending domain it claims nothing — `billing@` shown over
+ * `serviceupdatebank.atlassian.net` names the same party the envelope does.
+ * Over any other registrable domain it is the strongest non-correspondence
+ * signal there is: the message asserts, in the one field the recipient reads,
+ * that it comes from an address that cannot have sent it.
+ */
+export const classifyDisplayNameCorrespondence = (displayName, fromDomain) => {
+    const raw = (displayName ?? "").trim();
+    if (raw === "")
+        return DisplayNameCorrespondence.NoClaim;
+    const claimed = claimedAddressDomain(raw);
+    if (claimed !== undefined) {
+        if (claimed === registrableDomain(fromDomain)) {
+            return DisplayNameCorrespondence.NoClaim;
+        }
+        return DisplayNameCorrespondence.ForeignAddress;
+    }
+    const name = normalize(raw);
+    if (name.length < 3)
+        return DisplayNameCorrespondence.NoClaim;
+    const candidates = correspondenceCandidates(fromDomain);
+    if (candidates.length === 0)
+        return DisplayNameCorrespondence.NoClaim;
+    const terms = [name, ...words(raw)];
+    for (const term of terms) {
+        for (const candidate of candidates) {
+            if (term.includes(candidate)) {
+                return DisplayNameCorrespondence.Corresponds;
+            }
+        }
+    }
+    for (const candidate of candidates) {
+        const threshold = lookalikeThreshold(Math.min(name.length, candidate.length));
+        if (threshold === 0)
+            continue;
+        if (Math.abs(name.length - candidate.length) > threshold)
+            continue;
+        if (editDistance(name, candidate) <= threshold) {
+            return DisplayNameCorrespondence.Lookalike;
+        }
+    }
+    return DisplayNameCorrespondence.Unrelated;
+};
+const hrefsFromHtml = (html) => {
+    const out = [];
+    const pattern = /href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
+    let match = pattern.exec(html);
+    while (match !== null) {
+        out.push(match[1] ?? match[2] ?? match[3] ?? "");
+        match = pattern.exec(html);
+    }
+    return out;
+};
+const urlsFromText = (text) => text.match(/https?:\/\/[^\s<>"')\]]+/gi) ?? [];
+/**
+ * Registrable domains the body's links point at, minus the sender's own.
+ *
+ * `mailto:`, `tel:`, in-page anchors and relative hrefs carry no destination
+ * domain and are skipped; anything else is resolved public-suffix-aware through
+ * tldts, so `co.uk` and `atlassian.net` both survive the comparison a naive dot
+ * split gets wrong.
+ */
+export const extractOffDomainLinkDomains = (parsed, fromDomain) => {
+    const senderDomain = getDomain(fromDomain);
+    const html = typeof parsed.html === "string" ? parsed.html : "";
+    const text = typeof parsed.text === "string" ? parsed.text : "";
+    const seen = new Set();
+    const out = [];
+    for (const href of [...hrefsFromHtml(html), ...urlsFromText(text)]) {
+        const value = href.trim();
+        if (value === "" || !/^https?:\/\//i.test(value))
+            continue;
+        const domain = getDomain(value);
+        if (domain === null || domain === senderDomain)
+            continue;
+        if (seen.has(domain))
+            continue;
+        seen.add(domain);
+        out.push(domain);
+        if (out.length === MAX_LINK_DOMAINS)
+            break;
+    }
+    return out;
+};
+/**
+ * Both signals, gated on a spam verdict: the provider's own, or the message
+ * sitting in the Junk folder.
+ *
+ * The gate is what lets the checks be this aggressive: ordinary mail never
+ * reaches them, so a brand name over an ESP domain or a newsletter full of
+ * tracking links can never be flagged. Returns an empty object when the gate
+ * does not open — the fields stay absent, meaning "not compared".
+ */
+export const extractSenderMismatch = (parsed, context) => {
+    if (!context.providerSpamClassified && context.placement !== "junk") {
+        return {};
+    }
+    const offDomainLinkDomains = extractOffDomainLinkDomains(parsed, context.fromDomain);
+    if (context.bulkSender)
+        return { offDomainLinkDomains };
+    return {
+        displayNameCorrespondence: classifyDisplayNameCorrespondence(parsed.from?.value?.[0]?.name, context.fromDomain),
+        offDomainLinkDomains,
+    };
+};

package/dist/heuristics/socialDomains.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hand-curated allow-list of domains whose mail is treated as `social`.
+ *
+ * Sources are notifications from social/communication platforms. Match is
+ * suffix-based on the From-domain (lowercase). `news.linkedin.com` matches
+ * an entry of `linkedin.com`. Add new entries lowercase, no leading dot.
+ *
+ * Note: GitHub deliberately does NOT appear here. It is in
+ * `transactionalDomains.ts` because the EDD prioritises receipts and
+ * security alerts. The transactional rule fires before the social rule, so
+ * placing GitHub in the transactional list ensures all GitHub mail surfaces
+ * as `transactional`.
+ */
+export declare const SOCIAL_DOMAINS: readonly ["linkedin.com", "x.com", "twitter.com", "facebook.com", "instagram.com", "meetup.com", "discord.com", "slack.com"];

package/{src/heuristics/socialDomains.ts → dist/heuristics/socialDomains.js}

@@ -12,12 +12,12 @@
  * as `transactional`.
  */
 export const SOCIAL_DOMAINS = [
-	"linkedin.com",
-	"x.com",
-	"twitter.com",
-	"facebook.com",
-	"instagram.com",
-	"meetup.com",
-	"discord.com",
-	"slack.com",
-] as const;
+    "linkedin.com",
+    "x.com",
+    "twitter.com",
+    "facebook.com",
+    "instagram.com",
+    "meetup.com",
+    "discord.com",
+    "slack.com",
+];

package/dist/heuristics/transactionalDomains.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hand-curated allow-list of domains whose mail is treated as `transactional`.
+ *
+ * Sources are receipts, billing, security alerts, and similar
+ * person-actionable but not promotional mail. GitHub appears here (security
+ * alerts, billing receipts) and is intentionally NOT in the social allow-list
+ * — we want a GitHub security alert to surface as `transactional`, not
+ * `social`.
+ *
+ * Match is suffix-based on the From-domain (lowercase). `news.example.com`
+ * matches an entry of `example.com`. Add new entries lowercase, no leading
+ * dot.
+ *
+ * TODO: We deliberately do NOT seed banks here — the bank landscape is too
+ * geographic, and a wrong allow-list entry causes silent mis-classification.
+ * Banks should be added per-deployment by the operator.
+ */
+export declare const TRANSACTIONAL_DOMAINS: readonly ["github.com", "stripe.com", "paypal.com", "square.com", "itunes.com", "apple.com", "google.com"];

package/{src/heuristics/transactionalDomains.ts → dist/heuristics/transactionalDomains.js}

@@ -16,11 +16,11 @@
  * Banks should be added per-deployment by the operator.
  */
 export const TRANSACTIONAL_DOMAINS = [
-	"github.com",
-	"stripe.com",
-	"paypal.com",
-	"square.com",
-	"itunes.com",
-	"apple.com",
-	"google.com",
-] as const;
+    "github.com",
+    "stripe.com",
+    "paypal.com",
+    "square.com",
+    "itunes.com",
+    "apple.com",
+    "google.com",
+];