@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/heuristics/classifyByHeaders.js

@@ -0,0 +1,365 @@
+import { AuthResultVerdict, MessageCategory } from "@remit/domain-enums";
+import { parseAuthenticationResults, } from "./authenticationResults.js";
+import { hasMachineHeader, isMachineLocalPart } from "./machineSenders.js";
+import { SOCIAL_DOMAINS } from "./socialDomains.js";
+import { TRANSACTIONAL_DOMAINS } from "./transactionalDomains.js";
+/**
+ * Header-only classification. Pure function. First match wins. Falls through
+ * to `personal` so misclassification stays in the safest bucket.
+ *
+ * Rules are ordered most-specific-signal first. Two properties drive the
+ * order, and both were violated by the original table (issue #45):
+ *
+ * - A signal that identifies WHO sent the mail (calendar part, allow-listed
+ *   domain) outranks a signal that only says the mail was sent in bulk.
+ * - `Precedence` and `Auto-Submitted` say "a machine sent this", which is true
+ *   of nearly every newsletter, marketing blast, and platform notification.
+ *   Ranking them first collapsed `newsletter`, `marketing`, `social` and
+ *   `transactional` into `automated`, leaving those buckets empty.
+ *
+ * 1. `Content-Type: text/calendar` part anywhere → `transactional`
+ * 2. From-domain in TRANSACTIONAL_DOMAINS → `transactional`
+ * 3. From-domain in SOCIAL_DOMAINS → `social`
+ * 4. `List-Unsubscribe` AND `List-Id` → `newsletter`
+ * 5. `List-Unsubscribe` only → `marketing`
+ * 6. `Auto-Submitted: auto-generated|auto-replied` → `automated`
+ * 7. `Precedence: bulk|list|junk` → `automated`
+ * 8. Machine sender (no-reply local-part, `Feedback-ID`,
+ *    `X-Auto-Response-Suppress`) → `automated`
+ * 9. DKIM `d=` differs from From domain → `automated`
+ * 10. fallback → `personal`
+ */
+export const classifyByHeaders = (parsed) => {
+    const headers = parsed.headers;
+    const lines = parsed.headerLines;
+    if (hasCalendarPart(parsed.attachments))
+        return MessageCategory.transactional;
+    const fromDomain = getFromDomain(parsed);
+    if (fromDomain && domainMatches(fromDomain, TRANSACTIONAL_DOMAINS)) {
+        return MessageCategory.transactional;
+    }
+    if (fromDomain && domainMatches(fromDomain, SOCIAL_DOMAINS)) {
+        return MessageCategory.social;
+    }
+    const hasListUnsubscribe = hasHeaderLine(lines, "list-unsubscribe");
+    const hasListId = hasHeaderLine(lines, "list-id");
+    if (hasListUnsubscribe && hasListId)
+        return MessageCategory.newsletter;
+    if (hasListUnsubscribe)
+        return MessageCategory.marketing;
+    if (matchesAutoSubmitted(headers))
+        return MessageCategory.automated;
+    if (matchesPrecedence(headers))
+        return MessageCategory.automated;
+    if (isMachineSender(parsed, lines))
+        return MessageCategory.automated;
+    if (fromDomain &&
+        pickAlignedOrFirstMismatch(extractDkimDomains(headers, lines), fromDomain)
+            .mismatch) {
+        return MessageCategory.automated;
+    }
+    return MessageCategory.personal;
+};
+/**
+ * Extract the structured authenticity signal from parsed headers.
+ *
+ * Returns a `MessageAuthenticity` when at least one DKIM-Signature header
+ * is present (a comparison was possible). Returns `null` when there are no
+ * DKIM-Signature headers so callers can omit the field entirely — absence
+ * means "no signal", not "mismatch: false".
+ *
+ * The alignment rule exactly mirrors the category heuristic (rule 7) so the
+ * structured `dkimMismatch` boolean and the `automated` category can never
+ * disagree.
+ */
+export const extractAuthenticity = (parsed) => {
+    const headers = parsed.headers;
+    const lines = parsed.headerLines;
+    const fromDomain = getFromDomain(parsed);
+    if (!fromDomain)
+        return null;
+    const dkimDomains = extractDkimDomains(headers, lines);
+    if (dkimDomains.length === 0)
+        return null;
+    const picked = pickAlignedOrFirstMismatch(dkimDomains, fromDomain);
+    return {
+        fromDomain,
+        dkimDomain: picked.domain ?? undefined,
+        dkimMismatch: picked.mismatch,
+    };
+};
+const RESULTS_BY_FAVOURABILITY = [
+    "fail",
+    "softfail",
+    "neutral",
+    "none",
+    "unrecognised",
+    "pass",
+];
+const VERDICT_BY_RESULT = new Map([
+    ["fail", AuthResultVerdict.Fail],
+    ["softfail", AuthResultVerdict.Softfail],
+    ["neutral", AuthResultVerdict.Neutral],
+    ["none", AuthResultVerdict.None],
+    ["pass", AuthResultVerdict.Pass],
+]);
+const isRankedResult = (result) => RESULTS_BY_FAVOURABILITY.includes(result);
+const rankOf = (result) => RESULTS_BY_FAVOURABILITY.indexOf(isRankedResult(result) ? result : "unrecognised");
+const leastFavourableVerdict = (results) => {
+    if (results.length === 0)
+        return undefined;
+    const worst = Math.min(...results.map((r) => rankOf(r.result)));
+    return VERDICT_BY_RESULT.get(RESULTS_BY_FAVOURABILITY[worst]);
+};
+const normaliseDomain = (value) => {
+    if (value === undefined)
+        return null;
+    const domain = value.trim().toLowerCase().replace(/\.$/, "");
+    return domain.length > 0 ? domain : null;
+};
+const identityDomain = (value) => {
+    if (value === undefined)
+        return null;
+    const at = value.lastIndexOf("@");
+    if (at < 0)
+        return null;
+    return normaliseDomain(value.slice(at + 1));
+};
+const dkimSigningDomain = (result) => {
+    const signing = normaliseDomain(result.properties.get("header.d"));
+    const hasIdentity = result.properties.has("header.i");
+    const identity = identityDomain(result.properties.get("header.i"));
+    if (hasIdentity && identity === null)
+        return null;
+    if (signing === null)
+        return identity;
+    if (identity === null)
+        return signing;
+    const identityWithinSigning = identity === signing || identity.endsWith(`.${signing}`);
+    return identityWithinSigning ? signing : null;
+};
+const dkimResultsForFrom = (results, fromDomain) => {
+    if (!fromDomain)
+        return results;
+    const aligned = results.filter((r) => {
+        const domain = dkimSigningDomain(r);
+        return domain !== null && domainsAligned(domain, fromDomain);
+    });
+    return aligned.length > 0 ? aligned : results;
+};
+export const extractAuthResult = (parsed) => {
+    const headers = parsed.headerLines
+        .filter((l) => l.key.toLowerCase() === "authentication-results")
+        .map((l) => parseAuthenticationResults(stripHeaderName(l.line)))
+        .filter((h) => h !== null);
+    if (headers.length === 0)
+        return null;
+    const fromDomain = getFromDomain(parsed);
+    const byMethod = (results, method) => results.filter((r) => r.method === method);
+    const acrossHeaders = (method) => headers.flatMap((h) => byMethod(h.results, method));
+    return {
+        dmarc: leastFavourableVerdict(acrossHeaders("dmarc")),
+        spf: leastFavourableVerdict(acrossHeaders("spf")),
+        dkim: leastFavourableVerdict(headers.flatMap((h) => dkimResultsForFrom(byMethod(h.results, "dkim"), fromDomain))),
+    };
+};
+/**
+ * Extract provider spam-filter signal from X-SpamExperts-Class, X-Spam-Status,
+ * or X-HalOne-Spam-Probability headers. Returns null when none are present.
+ */
+export const extractProviderSpam = (parsed) => {
+    const lines = parsed.headerLines;
+    const spamExperts = lines.find((l) => l.key.toLowerCase() === "x-spamexperts-class");
+    if (spamExperts) {
+        const value = stripHeaderName(spamExperts.line).trim().toLowerCase();
+        return {
+            classified: value === "spam",
+            source: "x-spamexperts-class",
+        };
+    }
+    const spamStatus = lines.find((l) => l.key.toLowerCase() === "x-spam-status");
+    if (spamStatus) {
+        const text = stripHeaderName(spamStatus.line).trim();
+        const classified = text.toLowerCase().startsWith("yes");
+        const scoreMatch = text.match(/score=([\d.+-]+)/i);
+        return {
+            classified,
+            score: scoreMatch ? scoreMatch[1] : undefined,
+            source: "x-spam-status",
+        };
+    }
+    const halOne = lines.find((l) => l.key.toLowerCase() === "x-halone-spam-probability");
+    if (halOne) {
+        const value = stripHeaderName(halOne.line).trim();
+        return {
+            classified: parseFloat(value) > 0.5,
+            score: value,
+            source: "x-halone-spam-probability",
+        };
+    }
+    return null;
+};
+/**
+ * Returns true when a List-Unsubscribe header is present, indicating a
+ * bulk/mailing-list sender.
+ */
+export const extractHasListUnsubscribe = (parsed) => parsed.headerLines.some((l) => l.key.toLowerCase() === "list-unsubscribe");
+const matchesAutoSubmitted = (headers) => {
+    const value = readStringHeader(headers, "auto-submitted");
+    if (!value)
+        return false;
+    const normalized = value.split(";")[0].trim().toLowerCase();
+    return normalized === "auto-generated" || normalized === "auto-replied";
+};
+const matchesPrecedence = (headers) => {
+    const value = readStringHeader(headers, "precedence");
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return (normalized === "bulk" || normalized === "list" || normalized === "junk");
+};
+const hasCalendarPart = (attachments) => {
+    if (!attachments)
+        return false;
+    for (const att of attachments) {
+        if ((att.contentType ?? "").toLowerCase().startsWith("text/calendar")) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * Whether the sender is a machine that does not read replies — a no-reply
+ * local-part, or a header only bulk/notification infrastructure sets. This is
+ * what routes platform notifications (npm, CI, password resets) to `automated`
+ * instead of the `personal` fallback; they carry no list or bulk headers.
+ */
+const isMachineSender = (parsed, lines) => {
+    if (hasMachineHeader(lines.map((line) => line.key)))
+        return true;
+    const localPart = getFromLocalPart(parsed);
+    return localPart !== null && isMachineLocalPart(localPart);
+};
+const getFromLocalPart = (parsed) => {
+    const address = parsed.from?.value?.[0]?.address;
+    if (!address)
+        return null;
+    const at = address.lastIndexOf("@");
+    if (at <= 0)
+        return null;
+    return address.slice(0, at);
+};
+const getFromDomain = (parsed) => {
+    const from = parsed.from;
+    if (!from || !from.value || from.value.length === 0)
+        return null;
+    const address = from.value[0]?.address;
+    if (!address)
+        return null;
+    const at = address.lastIndexOf("@");
+    if (at < 0 || at === address.length - 1)
+        return null;
+    return address.slice(at + 1).toLowerCase();
+};
+const domainMatches = (domain, allowList) => {
+    for (const entry of allowList) {
+        if (domain === entry || domain.endsWith(`.${entry}`))
+            return true;
+    }
+    return false;
+};
+/**
+ * Whether a signing domain aligns with the From domain: equal, or one is a
+ * subdomain of the other (parent/child). A legitimate re-mailer signing under
+ * a subdomain is not suspicious, so either direction counts as aligned.
+ */
+const domainsAligned = (signingDomain, fromDomain) => signingDomain === fromDomain ||
+    fromDomain.endsWith(`.${signingDomain}`) ||
+    signingDomain.endsWith(`.${fromDomain}`);
+/**
+ * Pick the domain to report out of a list of candidate signing domains: the
+ * first one aligned with the From domain, so a legitimate signature is never
+ * shadowed by an earlier unrelated one. When none align, the first is
+ * reported as the mismatching evidence — the UI can then show "signed by
+ * relay.example.net, claims example.com". Shared by the category heuristic
+ * (rule 9, which reads only `.mismatch`) and the authenticity extractor
+ * (which also reads `.domain`), so the two can never disagree.
+ */
+const pickAlignedOrFirstMismatch = (domains, fromDomain) => {
+    let firstMismatching = null;
+    for (const d of domains) {
+        if (domainsAligned(d, fromDomain))
+            return { mismatch: false, domain: d };
+        if (!firstMismatching)
+            firstMismatching = d;
+    }
+    return { mismatch: firstMismatching !== null, domain: firstMismatching };
+};
+const extractDkimDomains = (headers, lines) => {
+    const domains = [];
+    const raw = headers.get("dkim-signature");
+    const structured = collectStructured(raw);
+    for (const s of structured) {
+        const d = s.params?.d;
+        if (typeof d === "string")
+            domains.push(d.trim().toLowerCase());
+    }
+    for (const line of lines) {
+        if (line.key.toLowerCase() !== "dkim-signature")
+            continue;
+        const value = stripHeaderName(line.line);
+        const match = value.match(/(?:^|;)\s*d\s*=\s*([^;\s]+)/i);
+        if (match) {
+            const candidate = match[1].trim().toLowerCase();
+            if (!domains.includes(candidate))
+                domains.push(candidate);
+        }
+    }
+    return domains;
+};
+const collectStructured = (value) => {
+    if (!value)
+        return [];
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const v of value) {
+            if (isStructuredHeader(v))
+                out.push(v);
+        }
+        return out;
+    }
+    if (isStructuredHeader(value))
+        return [value];
+    return [];
+};
+const isStructuredHeader = (v) => {
+    if (!v || typeof v !== "object")
+        return false;
+    return ("value" in v &&
+        typeof v.value === "string" &&
+        "params" in v &&
+        typeof v.params === "object");
+};
+const stripHeaderName = (line) => {
+    const idx = line.indexOf(":");
+    return idx >= 0 ? line.slice(idx + 1).trim() : line;
+};
+const hasHeaderLine = (lines, name) => {
+    const lc = name.toLowerCase();
+    for (const line of lines) {
+        if (line.key.toLowerCase() === lc)
+            return true;
+    }
+    return false;
+};
+const readStringHeader = (headers, key) => {
+    const value = headers.get(key);
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        const first = value[0];
+        if (typeof first === "string")
+            return first;
+    }
+    return undefined;
+};

package/dist/heuristics/classifyPlacement.d.ts

@@ -0,0 +1,67 @@
+import type { MessageItem } from "@remit/data-ports";
+import { SenderOverride, SenderTrust } from "@remit/domain-enums";
+type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
+type SenderOverrideValue = (typeof SenderOverride)[keyof typeof SenderOverride];
+export type FolderPlacement = "inbox" | "junk" | "other";
+export type PlacementAction = "move-to-inbox" | "move-to-junk" | "leave";
+export interface PlacementVerdict {
+    action: PlacementAction;
+    confidence: "confident" | "unsure";
+    reasons: string[];
+}
+/** The trust signal plus the `setAt` of whichever flag (`vip`/`wellknown`) produced it, `undefined` when the sender is `Unknown`. */
+export interface SenderTrustSignal {
+    trust: SenderTrustValue;
+    setAt?: number;
+}
+/** The sender's `blocked` flag value plus its `setAt`. */
+export interface SenderBlockedSignal {
+    blocked: boolean;
+    setAt?: number;
+}
+/**
+ * Resolve the two axes {@link classifyPlacement} takes: the trust signal, and
+ * the user's standing instruction about placement.
+ *
+ * `blocked` and `neverSpam` are two directly contradictory instructions and
+ * cannot both stand — `AddressRepository.mergeFlags` drops the loser at write
+ * time. Reading a row that carries both anyway (written before that invariant)
+ * resolves to `Blocked`, the same direction the `blocked`/`vip` same-second tie
+ * already breaks in: the demote is the recoverable mistake.
+ */
+export declare const resolveSenderPlacement: (trust: SenderTrustSignal, blocked: SenderBlockedSignal, neverSpam: boolean) => {
+    senderTrust: SenderTrustValue;
+    senderOverride: SenderOverrideValue;
+};
+/**
+ * Tier 0 deterministic placement verdict (RFC 031, "Confident moves").
+ *
+ * Pure: the caller resolves the message's current folder placement and the
+ * sender trust; this function does no DB lookups and produces no side effects.
+ * It generalizes `shouldRescueFromJunk` into a two-directional verdict and is
+ * recall-biased — a confident move only fires when cheap, deterministic signals
+ * agree; everything else is left in place for a later LLM tier.
+ *
+ * `senderOverride` (RFC 039 Decision 3, issue #605) is the user's standing
+ * instruction about this sender's placement, and it outranks every
+ * DKIM/DMARC/provider signal below — an explicit block or never-spam grant is
+ * not a heuristic. Already-tie-broken against `vip`/`wellknown` by
+ * {@link resolveSenderPlacement} in the caller; this function itself does not
+ * compare `setAt`.
+ *
+ * `NeverSpam` is checked above the `missing-signals` return and above the
+ * `providerSpam.classified` gate on purpose: the senders who need the grant are
+ * the ones the provider rated clean and whose domain publishes no DMARC record,
+ * so a check inside the rescue branch below would never fire for them. It
+ * rescues only from `junk` — a message a standing filter put in a user folder
+ * is not a spam question.
+ *
+ * It refuses outright on a `dmarc === "Fail"` or a DKIM mismatch. The demote
+ * branch below is reached only from `inbox`, so a spoof already sitting in Junk
+ * would never meet it: without this guard the grant would launder mail out of
+ * Junk on exactly the two signals that identify someone impersonating the
+ * address the user granted. A domain that publishes no DMARC record never
+ * scores `Fail`, so the case the grant exists for is untouched.
+ */
+export declare const classifyPlacement: (message: MessageItem, placement: FolderPlacement, senderTrust: SenderTrustValue, senderOverride: SenderOverrideValue) => PlacementVerdict;
+export {};

package/dist/heuristics/classifyPlacement.js

@@ -0,0 +1,153 @@
+import { SenderOverride, SenderTrust } from "@remit/domain-enums";
+const isTrusted = (senderTrust) => senderTrust === SenderTrust.Vip || senderTrust === SenderTrust.Wellknown;
+/**
+ * RFC 039 Decision 3a: when a sender's `blocked` flag and their `vip`/
+ * `wellknown` flag disagree on placement, the one set most recently wins.
+ * Scoped to {@link classifyPlacement}'s own verdict only — it never touches
+ * `deriveSenderTrust` or the trust badge, which stay a plain `vip → wellknown
+ * → unknown` read with no `blocked` case.
+ *
+ * A same-second tie (both `setAt` floor to the same second) breaks in a
+ * fixed, arbitrary order: `blocked` before `vip` before `wellknown` — a
+ * determinism backstop, not a meaningful signal.
+ */
+const resolveBlockedVsTrust = (trust, blocked) => {
+    if (!blocked.blocked) {
+        return { senderTrust: trust.trust, senderBlocked: false };
+    }
+    if (trust.trust === SenderTrust.Unknown || trust.setAt === undefined) {
+        return { senderTrust: SenderTrust.Unknown, senderBlocked: true };
+    }
+    const blockedSecond = Math.floor((blocked.setAt ?? 0) / 1000);
+    const trustSecond = Math.floor(trust.setAt / 1000);
+    // Newer (or a same-second tie, which `blocked` wins) — blocked wins.
+    if (blockedSecond >= trustSecond) {
+        return { senderTrust: SenderTrust.Unknown, senderBlocked: true };
+    }
+    return { senderTrust: trust.trust, senderBlocked: false };
+};
+/**
+ * Resolve the two axes {@link classifyPlacement} takes: the trust signal, and
+ * the user's standing instruction about placement.
+ *
+ * `blocked` and `neverSpam` are two directly contradictory instructions and
+ * cannot both stand — `AddressRepository.mergeFlags` drops the loser at write
+ * time. Reading a row that carries both anyway (written before that invariant)
+ * resolves to `Blocked`, the same direction the `blocked`/`vip` same-second tie
+ * already breaks in: the demote is the recoverable mistake.
+ */
+export const resolveSenderPlacement = (trust, blocked, neverSpam) => {
+    const { senderTrust, senderBlocked } = resolveBlockedVsTrust(trust, blocked);
+    if (senderBlocked)
+        return { senderTrust, senderOverride: SenderOverride.Blocked };
+    if (neverSpam)
+        return { senderTrust, senderOverride: SenderOverride.NeverSpam };
+    return { senderTrust, senderOverride: SenderOverride.None };
+};
+/**
+ * Tier 0 deterministic placement verdict (RFC 031, "Confident moves").
+ *
+ * Pure: the caller resolves the message's current folder placement and the
+ * sender trust; this function does no DB lookups and produces no side effects.
+ * It generalizes `shouldRescueFromJunk` into a two-directional verdict and is
+ * recall-biased — a confident move only fires when cheap, deterministic signals
+ * agree; everything else is left in place for a later LLM tier.
+ *
+ * `senderOverride` (RFC 039 Decision 3, issue #605) is the user's standing
+ * instruction about this sender's placement, and it outranks every
+ * DKIM/DMARC/provider signal below — an explicit block or never-spam grant is
+ * not a heuristic. Already-tie-broken against `vip`/`wellknown` by
+ * {@link resolveSenderPlacement} in the caller; this function itself does not
+ * compare `setAt`.
+ *
+ * `NeverSpam` is checked above the `missing-signals` return and above the
+ * `providerSpam.classified` gate on purpose: the senders who need the grant are
+ * the ones the provider rated clean and whose domain publishes no DMARC record,
+ * so a check inside the rescue branch below would never fire for them. It
+ * rescues only from `junk` — a message a standing filter put in a user folder
+ * is not a spam question.
+ *
+ * It refuses outright on a `dmarc === "Fail"` or a DKIM mismatch. The demote
+ * branch below is reached only from `inbox`, so a spoof already sitting in Junk
+ * would never meet it: without this guard the grant would launder mail out of
+ * Junk on exactly the two signals that identify someone impersonating the
+ * address the user granted. A domain that publishes no DMARC record never
+ * scores `Fail`, so the case the grant exists for is untouched.
+ */
+export const classifyPlacement = (message, placement, senderTrust, senderOverride) => {
+    if (message.movedByRemit === true) {
+        return {
+            action: "leave",
+            confidence: "confident",
+            reasons: ["already-moved-by-remit"],
+        };
+    }
+    if (senderOverride === SenderOverride.Blocked && placement !== "junk") {
+        return {
+            action: "move-to-junk",
+            confidence: "confident",
+            reasons: ["sender=blocked"],
+        };
+    }
+    if (senderOverride === SenderOverride.NeverSpam &&
+        placement === "junk" &&
+        message.authResult?.dmarc !== "Fail" &&
+        message.authenticity?.dkimMismatch !== true) {
+        return {
+            action: "move-to-inbox",
+            confidence: "confident",
+            reasons: ["sender=never-spam"],
+        };
+    }
+    if (!message.providerSpam || !message.authResult) {
+        return {
+            action: "leave",
+            confidence: "unsure",
+            reasons: ["missing-signals"],
+        };
+    }
+    const providerSpam = message.providerSpam.classified === true;
+    const dmarc = message.authResult.dmarc;
+    const dkimMismatch = message.authenticity?.dkimMismatch === true;
+    const trusted = isTrusted(senderTrust);
+    // Rescue (junk → inbox), LOW bar. Mirrors shouldRescueFromJunk's gate.
+    if (placement === "junk" && providerSpam && dmarc === "Pass") {
+        if (trusted) {
+            return {
+                action: "move-to-inbox",
+                confidence: "confident",
+                reasons: ["provider=spam", "dmarc=pass", `sender=${senderTrust}`],
+            };
+        }
+        // Anti-spoof guard: an unknown sender is never auto-rescued.
+        return {
+            action: "leave",
+            confidence: "unsure",
+            reasons: ["provider=spam", "dmarc=pass", "sender=untrusted"],
+        };
+    }
+    // Demote (inbox → junk), HIGH bar.
+    if (placement === "inbox" && dkimMismatch) {
+        if (dmarc === "Fail" && !trusted) {
+            return {
+                action: "move-to-junk",
+                confidence: "confident",
+                reasons: ["dkim-mismatch", "dmarc=fail", "sender=untrusted"],
+            };
+        }
+        // DMARC-pass phishing: dkimMismatch but DMARC did not fail. Deferred to a
+        // later LLM tier — must never auto-demote here.
+        if (dmarc === "Pass") {
+            return {
+                action: "leave",
+                confidence: "unsure",
+                reasons: ["dkim-mismatch", "dmarc=pass", "deferred-to-llm"],
+            };
+        }
+    }
+    return {
+        action: "leave",
+        confidence: "unsure",
+        reasons: ["no-confident-signal"],
+    };
+};

package/dist/heuristics/machineSenders.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Signals that a message was sent by a machine that does not read replies.
+ *
+ * Distinct from the bulk signals (`Precedence`, `List-Unsubscribe`): a platform
+ * notification — an npm publish or 2FA mail, a CI result, a password reset —
+ * carries none of those. It is a one-to-one message with an aligned DKIM
+ * signature, so before issue #45 it reached the `personal` fallback and sat
+ * alongside actual human correspondence.
+ */
+/**
+ * True when any whole word of the From local-part is a known machine mailbox.
+ *
+ * Word-boundary, not substring: platforms qualify the mailbox on either side
+ * (`noreply-github`, `messages-noreply`, `jobalerts-noreply`), so a bare prefix
+ * test misses half of them — but a substring test reads `bruno.reply` as
+ * "bru|noreply" and files a real person as `automated`. Splitting on the
+ * separators the sender wrote catches the qualified forms without inventing a
+ * match that spans two words.
+ */
+export declare const isMachineLocalPart: (localPart: string) => boolean;
+export declare const hasMachineHeader: (headerKeys: readonly string[]) => boolean;