@remit/mailbox-service 0.0.61 → 0.0.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.61",
+  "version": "0.0.63",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/filters/anchor-drift.ts

@@ -0,0 +1,55 @@
+import type {
+	FilterAnchorItem,
+	IFilterAnchorRepository,
+} from "@remit/data-ports";
+
+/**
+ * The half of an embedding service an anchor refresh needs: the text-to-vector
+ * call and the `<modelId>@<dimensions>` identifier of the model behind it (the
+ * same scheme `EmbeddingService.embeddingId` derives). Compared against
+ * `FilterAnchor.anchorEmbeddingId` to detect a model drift a same-dimension
+ * swap would otherwise pass through silently (RFC 039 Decision 1a, reader
+ * #295).
+ */
+export interface AnchorEmbedder {
+	embed(text: string): Promise<number[]>;
+	readonly embeddingId: string;
+}
+
+export interface AnchorDriftDeps {
+	anchorRepository: Pick<IFilterAnchorRepository, "put">;
+	/** Absent on a deployment with no embedder wired; then nothing can drift. */
+	embedder: AnchorEmbedder | undefined;
+}
+
+/**
+ * The anchor to score against, re-embedded in place when the embedding model
+ * has drifted since it was written (RFC 039 Decision 1a). No migration job
+ * walks these rows proactively, so the refresh is lazy: the first read that
+ * notices the stamp no longer matches the configured model re-embeds the
+ * already-persisted `anchorSourceText` and writes it back under the current
+ * id. A failure here is never a terminal state — the row is left as it was,
+ * so the next read that reaches this anchor retries.
+ *
+ * The single mechanism behind both index-time matching
+ * ({@link FilterPipeline}) and the back-apply pass's cross-filter precedence
+ * check, which must agree on what a filter currently matches (reader #399).
+ */
+export const refreshAnchorForEmbedder = async (
+	deps: AnchorDriftDeps,
+	anchor: FilterAnchorItem,
+): Promise<FilterAnchorItem> => {
+	const { embedder } = deps;
+	if (!embedder || anchor.anchorEmbeddingId === embedder.embeddingId) {
+		return anchor;
+	}
+	const anchorEmbedding = await embedder.embed(anchor.anchorSourceText);
+	return deps.anchorRepository.put({
+		accountConfigId: anchor.accountConfigId,
+		filterId: anchor.filterId,
+		anchorEmbedding,
+		anchorEmbeddingId: embedder.embeddingId,
+		anchorSourceText: anchor.anchorSourceText,
+		anchorMessageId: anchor.anchorMessageId,
+	});
+};

package/src/filters/pipeline.ts

@@ -7,6 +7,10 @@ import type {
 } from "@remit/data-ports";
 import { FilterState } from "@remit/domain-enums";
 import type { PlacementMoveService } from "../placement-move.js";
+import {
+	type AnchorEmbedder,
+	refreshAnchorForEmbedder,
+} from "./anchor-drift.js";
 import {
 	buildMatchText,
 	cosineSimilarity,
@@ -20,22 +24,12 @@ import {
 /**
  * Turns the candidate message's text into a single message-level vector to
  * compare against a filter's persisted `anchorEmbedding`. The anchor side is
- * never embedded here — it is read from `FilterAnchor` as a fixed fact (RFC 034
- * Decision 2.1/2.3); only the incoming message is embedded, and only once per
- * message, and only when a semantic filter is actually in play.
+ * embedded here only to repair a drifted anchor in place (see
+ * {@link refreshAnchorForEmbedder}); the match itself reads `FilterAnchor` as
+ * a fixed fact (RFC 034 Decision 2.1/2.3), and the incoming message is
+ * embedded once per message, only when a semantic filter is actually in play.
  */
-export interface MessageEmbedder {
-	embed(text: string): Promise<number[]>;
-	/**
-	 * `<modelId>@<dimensions>` identifier of the model currently configured —
-	 * the same scheme `EmbeddingService.embeddingId`
-	 * (`packages/search-service/src/embeddings.ts`) derives. Compared against
-	 * `FilterAnchor.anchorEmbeddingId` to detect a model drift a same-dimension
-	 * swap would otherwise pass through silently (RFC 039 Decision 1a, reader
-	 * #295).
-	 */
-	readonly embeddingId: string;
-}
+export type MessageEmbedder = AnchorEmbedder;
 
 export interface FilterLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -236,26 +230,16 @@ export class FilterPipeline {
 			return false;
 		}
 
-		const embedder = this.config.embedder;
-		if (embedder && anchor.anchorEmbeddingId !== embedder.embeddingId) {
-			// The embedding model has drifted since this anchor was last written
-			// (RFC 039 Decision 1a) — re-embed the already-persisted
-			// `anchorSourceText` and write it back in place, lazily, on this read.
-			// No migration job walks these rows proactively; a re-embed failure
-			// here propagates to the per-filter catch in `match()`, which logs and
-			// skips this filter for this one evaluation exactly as an unrecoverable
-			// stale anchor does today — never a terminal state, so the next
-			// message that reaches this filter retries.
-			const anchorEmbedding = await embedder.embed(anchor.anchorSourceText);
-			anchor = await this.config.filterAnchorService.put({
-				accountConfigId,
-				filterId: filter.filterId,
-				anchorEmbedding,
-				anchorEmbeddingId: embedder.embeddingId,
-				anchorSourceText: anchor.anchorSourceText,
-				anchorMessageId: anchor.anchorMessageId,
-			});
-		}
+		// A re-embed failure here propagates to the per-filter catch in
+		// `match()`, which logs and skips this filter for this one evaluation
+		// exactly as an unrecoverable stale anchor does today.
+		anchor = await refreshAnchorForEmbedder(
+			{
+				anchorRepository: this.config.filterAnchorService,
+				embedder: this.config.embedder,
+			},
+			anchor,
+		);
 
 		const vector = await embed();
 		if (!vector) {

package/src/heuristics/senderMismatch.test.ts

@@ -71,7 +71,7 @@ describe("classifyDisplayNameCorrespondence", () => {
 		);
 	});
 
-	it("claims nothing when the display name is the address itself", () => {
+	it("claims nothing when the display name is an address at the sending domain", () => {
 		assert.equal(
 			classifyDisplayNameCorrespondence(
 				"billing@serviceupdatebank.atlassian.net",
@@ -81,6 +81,60 @@ describe("classifyDisplayNameCorrespondence", () => {
 		);
 	});
 
+	it("claims nothing when the display name spells the envelope address itself", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence("matthijs@ischen.nl", "ischen.nl"),
+			DisplayNameCorrespondence.NoClaim,
+		);
+	});
+
+	it("claims nothing when the display name is an address on a sibling subdomain", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence(
+				"noreply@example.co.uk",
+				"mail.example.co.uk",
+			),
+			DisplayNameCorrespondence.NoClaim,
+		);
+	});
+
+	it("is a foreign address when the display name spells an address over another domain", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence(
+				"matthijs@ischen.nl",
+				"secresaludguaviare.gov.co",
+			),
+			DisplayNameCorrespondence.ForeignAddress,
+		);
+	});
+
+	it("is a foreign address when the spelled-out address is decorated with a name", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence(
+				"Matthijs (matthijs@ischen.nl)",
+				"secresaludguaviare.gov.co",
+			),
+			DisplayNameCorrespondence.ForeignAddress,
+		);
+	});
+
+	it("compares an at sign that spells no address as an ordinary name", () => {
+		assert.equal(
+			classifyDisplayNameCorrespondence(
+				"Support @ InfoMedics",
+				"infomedics.nl",
+			),
+			DisplayNameCorrespondence.Corresponds,
+		);
+		assert.equal(
+			classifyDisplayNameCorrespondence(
+				"Support @ InfoMedics",
+				"serviceupdatebank.atlassian.net",
+			),
+			DisplayNameCorrespondence.Unrelated,
+		);
+	});
+
 	it("does not read the public suffix as a match for a brand containing it", () => {
 		assert.equal(
 			classifyDisplayNameCorrespondence("Netflix", "mailer.example.net"),
@@ -213,6 +267,25 @@ describe("extractSenderMismatch", () => {
 		);
 	});
 
+	it("flags a display name spelling the recipient's own address over a foreign domain", async () => {
+		const parsed = await parse([
+			"From: matthijs@ischen.nl <aramirez@secresaludguaviare.gov.co>",
+			"To: matthijs@ischen.nl",
+			"Subject: Re: factura",
+			"X-HalOne-Spam-Probability: 1",
+			"",
+			"hola",
+		]);
+		assert.equal(
+			extractSenderMismatch(parsed, {
+				fromDomain: "secresaludguaviare.gov.co",
+				spamClassified: true,
+				bulkSender: false,
+			}).displayNameCorrespondence,
+			DisplayNameCorrespondence.ForeignAddress,
+		);
+	});
+
 	it("leaves the display name uncompared for a bulk sender", async () => {
 		const parsed = await parse([
 			"From: Dutch Cycling Weekly <bounce-9f2@mailer.esp.example>",

package/src/heuristics/senderMismatch.ts

@@ -76,6 +76,22 @@ const editDistance = (a: string, b: string): number => {
 	return previous[b.length];
 };
 
+const ADDRESS_SHAPE = /[^\s<>@,;:"]+@([a-z0-9-]+(?:\.[a-z0-9-]+)+)/i;
+
+const registrableDomain = (host: string): string =>
+	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: string): string | undefined => {
+	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
@@ -109,14 +125,27 @@ const lookalikeThreshold = (length: number): number => {
  * 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: string | undefined,
 	fromDomain: string,
 ): CorrespondenceValue => {
 	const raw = (displayName ?? "").trim();
-	if (raw === "" || raw.includes("@")) {
-		return DisplayNameCorrespondence.NoClaim;
+	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);

package/src/index.ts

@@ -59,6 +59,11 @@ export {
 	testImapConnection,
 	testSmtpConnection,
 } from "./connection-test.js";
+export {
+	type AnchorDriftDeps,
+	type AnchorEmbedder,
+	refreshAnchorForEmbedder,
+} from "./filters/anchor-drift.js";
 export { extractListId, normalizeListId } from "./filters/list-id.js";
 export {
 	buildMatchText,