@remit/mailbox-service 0.0.100 → 0.0.102

package/package.json

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

package/src/heuristics/authenticationResults.test.ts

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type AuthenticationResults,
+	parseAuthenticationResults,
+} from "./authenticationResults.js";
+
+const parse = (value: string): AuthenticationResults => {
+	const parsed = parseAuthenticationResults(value);
+	assert.ok(parsed, `expected ${JSON.stringify(value)} to parse`);
+	return parsed;
+};
+
+const summary = (value: string): string[] =>
+	parse(value).results.map((r) =>
+		[`${r.method}=${r.result}`, ...r.properties].flat().join(" "),
+	);
+
+describe("parseAuthenticationResults", () => {
+	it("reads the authserv-id and every resinfo", () => {
+		const parsed = parse(
+			"mx.example.com; dkim=pass header.d=acme.example; spf=pass smtp.mailfrom=acme.example; dmarc=pass header.from=acme.example",
+		);
+		assert.equal(parsed.authservId, "mx.example.com");
+		assert.deepEqual(summary("mx.example.com; dkim=pass header.d=a.example"), [
+			"dkim=pass header.d a.example",
+		]);
+		assert.deepEqual(
+			parsed.results.map((r) => r.method),
+			["dkim", "spf", "dmarc"],
+		);
+	});
+
+	it("keeps a semicolon inside a comment within its own resinfo", () => {
+		assert.deepEqual(
+			summary(
+				"gw.example; dkim=fail (1024-bit key; unprotected) header.d=acme.example; dkim=fail header.d=relay.example; dmarc=fail (p=REJECT) header.from=acme.example",
+			),
+			[
+				"dkim=fail header.d acme.example",
+				"dkim=fail header.d relay.example",
+				"dmarc=fail header.from acme.example",
+			],
+		);
+	});
+
+	it("never reads a result out of another method's comment", () => {
+		assert.deepEqual(
+			summary(
+				"mx.example.net; arc=fail (i=1 spf=pass; dkim=fail\r\n  header.d=arcsigner.example; dmarc=fail); spf=pass smtp.mailfrom=acme.example;\r\n  dmarc=fail header.from=acme.example",
+			),
+			[
+				"arc=fail",
+				"spf=pass smtp.mailfrom acme.example",
+				"dmarc=fail header.from acme.example",
+			],
+		);
+	});
+
+	it("strips nested comments and escaped parentheses", () => {
+		assert.deepEqual(
+			summary(
+				"mx.example (outer (inner; dkim=pass) \\) still; comment); dkim=fail (a (b; c) d) header.d=acme.example",
+			),
+			["dkim=fail header.d acme.example"],
+		);
+	});
+
+	it("keeps a semicolon inside a quoted reason", () => {
+		assert.deepEqual(
+			summary(
+				'gw.example; dkim=fail reason="verification failed; body hash mismatch" header.d=acme.example; dmarc=fail header.from=acme.example',
+			),
+			[
+				"dkim=fail reason verification failed; body hash mismatch header.d acme.example",
+				"dmarc=fail header.from acme.example",
+			],
+		);
+	});
+
+	it("lower-cases methods, results and property names", () => {
+		const parsed = parse(
+			"GW.EXAMPLE; DKIM=FAIL HEADER.D=EVIL.EXAMPLE; DMARC=FAIL",
+		);
+		assert.equal(parsed.authservId, "gw.example");
+		assert.deepEqual(
+			summary("GW.EXAMPLE; DKIM=FAIL HEADER.D=EVIL.EXAMPLE; DMARC=FAIL"),
+			["dkim=fail header.d EVIL.EXAMPLE", "dmarc=fail"],
+		);
+	});
+
+	it("accepts a comment before the method name", () => {
+		assert.deepEqual(
+			summary(
+				"mx.example.com; (a comment) dkim=pass header.d=acme.example; dmarc=fail",
+			),
+			["dkim=pass header.d acme.example", "dmarc=fail"],
+		);
+	});
+
+	it("accepts whitespace around = and .", () => {
+		assert.deepEqual(
+			summary(
+				"mx.example.com; dkim = fail header . d = evil.example; dmarc=fail",
+			),
+			["dkim=fail header.d evil.example", "dmarc=fail"],
+		);
+	});
+
+	it("reads folded continuation lines", () => {
+		assert.deepEqual(
+			summary(
+				"mx.example.com;\r\n\tdkim=pass header.d=acme.example;\r\n\tdmarc=fail header.from=acme.example",
+			),
+			[
+				"dkim=pass header.d acme.example",
+				"dmarc=fail header.from acme.example",
+			],
+		);
+	});
+
+	it("finds a result after hundreds of filler properties", () => {
+		const filler = Array.from(
+			{ length: 400 },
+			(_, n) => `x-filler.p${n}=v${n}`,
+		).join(" ");
+		const parsed = parse(
+			`mx.example.com; spf=none ${filler}; dkim=fail header.d=acme.example`,
+		);
+		assert.equal(parsed.results[0].properties.size, 400);
+		assert.equal(parsed.results[1].properties.get("header.d"), "acme.example");
+	});
+
+	it("reads a result that carries no properties", () => {
+		assert.deepEqual(summary("gw.example; dkim=fail; dmarc=fail"), [
+			"dkim=fail",
+			"dmarc=fail",
+		]);
+	});
+
+	it("reads method versions, an authres-version and a trailing semicolon", () => {
+		const parsed = parse("mx.example 1; dkim/1=pass header.d=acme.example;");
+		assert.equal(parsed.authservId, "mx.example");
+		assert.deepEqual(
+			summary("mx.example 1; dkim/1=pass header.d=acme.example;"),
+			["dkim=pass header.d acme.example"],
+		);
+	});
+
+	it("reads the explicit no-result form", () => {
+		assert.deepEqual(parse("mx.example.com; none"), {
+			authservId: "mx.example.com",
+			results: [],
+		});
+	});
+
+	it("reads a header that omits the authserv-id", () => {
+		const parsed = parse(
+			"spf=pass (sender IP is 192.0.2.1) smtp.mailfrom=acme.example; dkim=pass (signature was verified) header.d=acme.example;dmarc=pass action=none header.from=acme.example;compauth=pass reason=100",
+		);
+		assert.equal(parsed.authservId, "");
+		assert.deepEqual(
+			parsed.results.map((r) => `${r.method}=${r.result}`),
+			["spf=pass", "dkim=pass", "dmarc=pass", "compauth=pass"],
+		);
+	});
+
+	for (const [label, value] of [
+		["an empty header", "   "],
+		["an authserv-id alone", "mx.example.com"],
+		["an authserv-id with an empty resinfo", "mx.example.com;"],
+		["an unterminated comment", "mx.example; dmarc=pass (oops"],
+		["an unbalanced closing parenthesis", "mx.example; dmarc=pass oops)"],
+		["an unterminated quoted string", 'mx.example; dkim=fail reason="oops'],
+		["a word with no value", "mx.example; dmarc=pass stray"],
+		["a key with no value", "mx.example; dmarc=pass header.from="],
+		["a resinfo with no method", "mx.example; header.d=acme.example"],
+		["a quoted result", 'mx.example; dmarc="pass"'],
+		[
+			"two words where a key belongs",
+			"mx.example; dmarc=pass extra header.from=a.example",
+		],
+		["no-result mixed with a result", "mx.example; none; dmarc=pass"],
+	] as const) {
+		it(`yields no result for ${label}`, () => {
+			assert.equal(parseAuthenticationResults(value), null);
+		});
+	}
+});

package/src/heuristics/authenticationResults.ts

@@ -0,0 +1,212 @@
+export interface AuthenticationResult {
+	method: string;
+	result: string;
+	properties: ReadonlyMap<string, string>;
+}
+
+export interface AuthenticationResults {
+	authservId: string;
+	results: AuthenticationResult[];
+}
+
+type Token =
+	| { kind: "word"; text: string }
+	| { kind: "quoted"; text: string }
+	| { kind: "semicolon" }
+	| { kind: "equals" };
+
+type ValueToken = Extract<Token, { kind: "word" | "quoted" }>;
+
+const DELIMITERS = new Set([";", "=", "(", ")", '"']);
+const KEYWORD = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const METHOD = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[0-9]+)?$/;
+const PROPERTY_KEY =
+	/^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$/;
+const VERSION = /^[0-9]+$/;
+
+const isWhitespace = (c: string): boolean =>
+	c === " " || c === "\t" || c === "\r" || c === "\n";
+
+const skipComment = (input: string, start: number): number | null => {
+	let depth = 0;
+	for (let i = start; i < input.length; i++) {
+		const c = input[i];
+		if (c === "\\") {
+			i++;
+			continue;
+		}
+		if (c === "(") depth++;
+		if (c === ")") depth--;
+		if (depth === 0) return i + 1;
+	}
+	return null;
+};
+
+const readQuoted = (
+	input: string,
+	start: number,
+): { text: string; end: number } | null => {
+	let text = "";
+	for (let i = start + 1; i < input.length; i++) {
+		const c = input[i];
+		if (c === "\\") {
+			if (i + 1 >= input.length) return null;
+			text += input[i + 1];
+			i++;
+			continue;
+		}
+		if (c === '"') return { text, end: i + 1 };
+		text += c;
+	}
+	return null;
+};
+
+const tokenize = (input: string): Token[] | null => {
+	const tokens: Token[] = [];
+	let i = 0;
+	while (i < input.length) {
+		const c = input[i];
+		if (isWhitespace(c)) {
+			i++;
+			continue;
+		}
+		if (c === "(") {
+			const end = skipComment(input, i);
+			if (end === null) return null;
+			i = end;
+			continue;
+		}
+		if (c === ")") return null;
+		if (c === ";") {
+			tokens.push({ kind: "semicolon" });
+			i++;
+			continue;
+		}
+		if (c === "=") {
+			tokens.push({ kind: "equals" });
+			i++;
+			continue;
+		}
+		if (c === '"') {
+			const quoted = readQuoted(input, i);
+			if (!quoted) return null;
+			tokens.push({ kind: "quoted", text: quoted.text });
+			i = quoted.end;
+			continue;
+		}
+		let end = i;
+		while (
+			end < input.length &&
+			!isWhitespace(input[end]) &&
+			!DELIMITERS.has(input[end])
+		) {
+			end++;
+		}
+		tokens.push({ kind: "word", text: input.slice(i, end) });
+		i = end;
+	}
+	return tokens;
+};
+
+const splitStatements = (tokens: Token[]): Token[][] => {
+	const statements: Token[][] = [[]];
+	for (const token of tokens) {
+		if (token.kind === "semicolon") {
+			statements.push([]);
+			continue;
+		}
+		statements[statements.length - 1].push(token);
+	}
+	return statements;
+};
+
+const isValue = (token: Token | undefined): token is ValueToken =>
+	token !== undefined && (token.kind === "word" || token.kind === "quoted");
+
+const joinsKey = (previous: string, next: string): boolean =>
+	previous.endsWith(".") ||
+	previous.endsWith("/") ||
+	next.startsWith(".") ||
+	next.startsWith("/");
+
+const readPairs = (statement: Token[]): [string, ValueToken][] | null => {
+	const pairs: [string, ValueToken][] = [];
+	let key: string[] = [];
+	for (let i = 0; i < statement.length; i++) {
+		const token = statement[i];
+		if (token.kind === "equals") {
+			const value = statement[i + 1];
+			if (key.length === 0 || !isValue(value)) return null;
+			pairs.push([key.join("").toLowerCase(), value]);
+			key = [];
+			i++;
+			continue;
+		}
+		if (token.kind !== "word") return null;
+		const previous = key[key.length - 1];
+		if (previous !== undefined && !joinsKey(previous, token.text)) return null;
+		key.push(token.text);
+	}
+	if (key.length > 0) return null;
+	return pairs;
+};
+
+const parseResult = (statement: Token[]): AuthenticationResult | null => {
+	const pairs = readPairs(statement);
+	if (!pairs || pairs.length === 0) return null;
+	const [[methodKey, resultToken], ...rest] = pairs;
+	if (!METHOD.test(methodKey)) return null;
+	if (resultToken.kind !== "word") return null;
+	const result = resultToken.text.toLowerCase();
+	if (!KEYWORD.test(result)) return null;
+
+	const properties = new Map<string, string>();
+	for (const [key, value] of rest) {
+		if (!PROPERTY_KEY.test(key)) return null;
+		if (!properties.has(key)) properties.set(key, value.text);
+	}
+	return { method: methodKey.split("/")[0], result, properties };
+};
+
+const parseAuthservId = (statement: Token[]): string | null => {
+	const [id, version, ...extra] = statement;
+	if (!isValue(id) || extra.length > 0) return null;
+	if (version !== undefined) {
+		if (version.kind !== "word" || !VERSION.test(version.text)) return null;
+	}
+	const authservId = id.text.toLowerCase();
+	return authservId.length > 0 ? authservId : null;
+};
+
+const isNoResult = (statement: Token[]): boolean =>
+	statement.length === 1 &&
+	statement[0].kind === "word" &&
+	statement[0].text.toLowerCase() === "none";
+
+export const parseAuthenticationResults = (
+	value: string,
+): AuthenticationResults | null => {
+	const tokens = tokenize(value);
+	if (!tokens) return null;
+
+	const [head, ...tail] = splitStatements(tokens);
+	const headIsResult = head.some((token) => token.kind === "equals");
+	const authservId = headIsResult ? "" : parseAuthservId(head);
+	if (authservId === null) return null;
+
+	const statements = (headIsResult ? [head, ...tail] : tail).filter(
+		(statement) => statement.length > 0,
+	);
+	if (statements.length === 0) return null;
+	if (statements.length === 1 && isNoResult(statements[0])) {
+		return { authservId, results: [] };
+	}
+
+	const results: AuthenticationResult[] = [];
+	for (const statement of statements) {
+		const result = parseResult(statement);
+		if (!result) return null;
+		results.push(result);
+	}
+	return { authservId, results };
+};

package/src/heuristics/classifyByHeaders.test.ts

@@ -1,7 +1,12 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { MessageCategory } from "@remit/domain-enums";
-import { simpleParser } from "mailparser";
+import type { MessageItem } from "@remit/data-ports";
+import {
+	MessageCategory,
+	SenderOverride,
+	SenderTrust,
+} from "@remit/domain-enums";
+import { type ParsedMail, simpleParser } from "mailparser";
 import {
 	classifyByHeaders,
 	extractAuthenticity,
@@ -9,6 +14,7 @@ import {
 	extractHasListUnsubscribe,
 	extractProviderSpam,
 } from "./classifyByHeaders.js";
+import { classifyPlacement } from "./classifyPlacement.js";
 
 const buildEml = (lines: string[]): Buffer => Buffer.from(lines.join("\r\n"));
 
@@ -576,3 +582,308 @@ describe("extractHasListUnsubscribe", () => {
 		assert.equal(extractHasListUnsubscribe(parsed), true);
 	});
 });
+
+const messageFrom = (parsed: ParsedMail): MessageItem => ({
+	messageId: "m-1",
+	mailboxId: "mb-1",
+	uid: 1,
+	sequenceNumber: 1,
+	rfc822Size: 1,
+	internalDate: 1,
+	envelopeId: "e-1",
+	rootBodyPartId: "bp-1",
+	status: "active",
+	syncStatus: "synced",
+	abandonedMutation: "none",
+	category: "uncategorized",
+	classificationState: "NotExamined",
+	authenticityVerdict: "NotEvaluated",
+	hasListUnsubscribe: false,
+	movedByRemit: false,
+	createdAt: 1,
+	updatedAt: 1,
+	providerSpam: extractProviderSpam(parsed) ?? undefined,
+	authResult: extractAuthResult(parsed) ?? undefined,
+	authenticity: extractAuthenticity(parsed) ?? undefined,
+});
+
+const inboxVerdict = (parsed: ParsedMail) =>
+	classifyPlacement(
+		messageFrom(parsed),
+		"inbox",
+		SenderTrust.Unknown,
+		SenderOverride.None,
+	);
+
+const withBody = (lines: string[]): string[] => [...lines, "", "body"];
+
+describe("Authentication-Results adversarial findings (#657)", () => {
+	it("keeps the aligned dkim result when a comment carries a semicolon", async () => {
+		const parsed = await parse(
+			withBody([
+				"From: Alice <alice@acme.example>",
+				"Authentication-Results: gw.example; dkim=fail (1024-bit key; unprotected) header.d=acme.example; dkim=pass header.d=relay.example; dmarc=fail (p=REJECT) header.from=acme.example",
+				"X-Spam-Status: No, score=0.1",
+			]),
+		);
+		assert.deepEqual(extractAuthResult(parsed), {
+			dmarc: "Fail",
+			spf: undefined,
+			dkim: "Fail",
+		});
+	});
+
+	it("checks alignment even when an unrelated dkim=pass is present", async () => {
+		const header = (extra: string) =>
+			parse(
+				withBody([
+					"From: Alice <alice@acme.example>",
+					`Authentication-Results: gw.corp.example; ${extra}dkim=fail (body hash did not verify) header.d=acme.example; dmarc=fail (p=REJECT) header.from=acme.example`,
+					"X-Spam-Status: No, score=0.1",
+				]),
+			);
+		const without = await header("");
+		const withEsp = await header("dkim=pass header.d=esp-mailer.example; ");
+		assert.deepEqual(extractAuthResult(withEsp), extractAuthResult(without));
+		assert.deepEqual(inboxVerdict(withEsp), inboxVerdict(without));
+		assert.equal(inboxVerdict(withEsp).action, "leave");
+	});
+
+	it("never junks list mail whose relay stripped the original signature", async () => {
+		const parsed = await parse(
+			withBody([
+				"From: Alice <alice@acme.example>",
+				"To: list@googlegroups.example",
+				"Authentication-Results: mx.google.example; dkim=pass header.d=googlegroups.example; spf=pass smtp.mailfrom=googlegroups.example; dmarc=fail (p=REJECT) header.from=acme.example",
+				"List-Id: <list.googlegroups.example>",
+				"X-Spam-Status: No, score=0.2",
+			]),
+		);
+		assert.equal(extractAuthenticity(parsed), null);
+		assert.equal(inboxVerdict(parsed).action, "leave");
+	});
+
+	it("never lets a prepended header override the raw signing domain", async () => {
+		const parsed = await parse(
+			withBody([
+				"Authentication-Results: anything-i-like; dkim=pass header.d=bank.example",
+				"From: Security <security@bank.example>",
+				"To: victim@example.com",
+				"Subject: Verify your account",
+				"DKIM-Signature: v=1; a=rsa-sha256; d=phish-host.example; s=sel; b=xxx",
+				"X-Spam-Status: No, score=0.1",
+			]),
+		);
+		assert.deepEqual(extractAuthenticity(parsed), {
+			fromDomain: "bank.example",
+			dkimDomain: "phish-host.example",
+			dkimMismatch: true,
+		});
+	});
+
+	it("never lets a prepended header hide the receiving MTA's dmarc=fail", async () => {
+		const lines = (order: "forged-first" | "real-first") => {
+			const forged =
+				"Authentication-Results: whatever; dkim=pass header.d=evil-mimic.example; dmarc=pass header.from=evil-mimic.example";
+			const real = "Authentication-Results: mx.example.com; dmarc=fail";
+			return withBody([
+				...(order === "forged-first" ? [forged, real] : [real, forged]),
+				"From: Support <support@evil-mimic.example>",
+				"To: me@example.com",
+				"Subject: Verify your account",
+				"DKIM-Signature: v=1; a=rsa-sha256; d=relay.example.net; s=sel; b=xxx",
+				"X-Spam-Status: No, score=0.1",
+			]);
+		};
+		for (const order of ["forged-first", "real-first"] as const) {
+			const parsed = await parse(lines(order));
+			assert.equal(extractAuthResult(parsed)?.dmarc, "Fail", order);
+			assert.equal(inboxVerdict(parsed).action, "move-to-junk", order);
+		}
+	});
+
+	it("never lets a sender-added aligned dkim=pass override the receiver's verdict", async () => {
+		const receivers = [
+			"Authentication-Results: mx.me.example; dkim=fail header.d=phish.example; dmarc=fail header.from=bank.example",
+			"Authentication-Results: mx.me.example; dkim=none; dmarc=fail header.from=bank.example",
+		];
+		const forged = "Authentication-Results: x; dkim=pass header.d=bank.example";
+		for (const [receiver, expected] of [
+			[receivers[0], "Fail"],
+			[receivers[1], "None"],
+		] as const) {
+			for (const headers of [
+				[receiver, forged],
+				[forged, receiver],
+			]) {
+				const parsed = await parse(
+					withBody([...headers, "From: B <s@bank.example>"]),
+				);
+				assert.equal(
+					extractAuthResult(parsed)?.dkim,
+					expected,
+					headers.join(" | "),
+				);
+			}
+		}
+	});
+
+	it("never reads dkim=fail out of another method's comment", async () => {
+		const parsed = await parse(
+			withBody([
+				"From: Alice <alice@acme.example>",
+				"Authentication-Results: mx.example.net; arc=fail (i=1 spf=fail; dkim=fail",
+				"  header.d=arcsigner.example; dmarc=fail); spf=pass smtp.mailfrom=acme.example;",
+				"  dmarc=pass header.from=acme.example",
+			]),
+		);
+		assert.deepEqual(extractAuthResult(parsed), {
+			dmarc: "Pass",
+			spf: "Pass",
+			dkim: undefined,
+		});
+	});
+
+	it("reads dmarc from its own resinfo, not from an arc comment", async () => {
+		const parsed = await parse(
+			withBody([
+				"From: Alice <alice@acme.example>",
+				"Authentication-Results: gw.example; arc=pass (i=1 dmarc=fail fromdomain=acme.example); dmarc=pass header.from=acme.example",
+			]),
+		);
+		assert.equal(extractAuthResult(parsed)?.dmarc, "Pass");
+	});
+
+	describe("grammar edge cases", () => {
+		const dkimFor = async (value: string) =>
+			extractAuthResult(
+				await parse(
+					withBody([
+						"From: Alice <alice@acme.example>",
+						`Authentication-Results: ${value}`,
+					]),
+				),
+			)?.dkim;
+
+		it("aligns a signing domain written with a trailing root dot", async () => {
+			assert.equal(
+				await dkimFor(
+					"gw.example; dkim=fail header.d=esp.example; dkim=pass header.d=acme.example.",
+				),
+				"Pass",
+			);
+		});
+
+		it("never aligns a header.i without an @", async () => {
+			assert.equal(
+				await dkimFor(
+					"gw.example; dkim=fail header.d=esp.example; dkim=pass header.i=acme.example",
+				),
+				"Fail",
+			);
+		});
+
+		it("never aligns a result whose header.i falls outside header.d", async () => {
+			assert.equal(
+				await dkimFor(
+					"gw.example; dkim=fail header.d=esp.example; dkim=pass header.d=acme.example header.i=@evil.example",
+				),
+				"Fail",
+			);
+		});
+
+		it("aligns through header.i when header.d is absent", async () => {
+			assert.equal(
+				await dkimFor(
+					"gw.example; dkim=fail header.d=esp.example; dkim=pass header.i=alice@mail.acme.example",
+				),
+				"Pass",
+			);
+		});
+
+		it("reads upper-case tokens", async () => {
+			const parsed = await parse(
+				withBody([
+					"From: Alice <alice@acme.example>",
+					"Authentication-Results: GW.EXAMPLE; DKIM=FAIL HEADER.D=EVIL.EXAMPLE; DMARC=FAIL",
+				]),
+			);
+			assert.deepEqual(extractAuthResult(parsed), {
+				dmarc: "Fail",
+				spf: undefined,
+				dkim: "Fail",
+			});
+		});
+
+		it("reads a folded header whose continuation starts with dkim=", async () => {
+			const parsed = await parse(
+				withBody([
+					"From: Alice <alice@acme.example>",
+					"Authentication-Results: mx.example.com;",
+					"\tdkim=pass header.d=acme.example;",
+					"\tdmarc=fail header.from=acme.example",
+				]),
+			);
+			assert.deepEqual(extractAuthResult(parsed), {
+				dmarc: "Fail",
+				spf: undefined,
+				dkim: "Pass",
+			});
+		});
+
+		it("prefers the aligned result wherever it is listed", async () => {
+			assert.equal(
+				await dkimFor(
+					"gw.example; dkim=fail header.d=esp-mailer.example; dkim=pass header.d=acme.example; dmarc=fail",
+				),
+				"Pass",
+			);
+		});
+
+		it("reads dkim=fail with no domain", async () => {
+			assert.equal(await dkimFor("gw.example; dkim=fail; dmarc=fail"), "Fail");
+		});
+
+		it("never reads an unrecognised result as a pass", async () => {
+			assert.equal(
+				await dkimFor(
+					"gw.example; dkim=pass header.d=acme.example; dkim=permerror header.d=acme.example",
+				),
+				undefined,
+			);
+		});
+	});
+
+	describe("fail closed", () => {
+		it("yields no result for an empty header", async () => {
+			const parsed = await parse(
+				withBody([
+					"From: Alice <alice@acme.example>",
+					"Authentication-Results:    ",
+				]),
+			);
+			assert.equal(extractAuthResult(parsed), null);
+		});
+
+		it("yields no result for a header that does not parse", async () => {
+			const parsed = await parse(
+				withBody([
+					"From: Alice <alice@acme.example>",
+					"Authentication-Results: mx.example; dmarc=pass (unterminated",
+				]),
+			);
+			assert.equal(extractAuthResult(parsed), null);
+		});
+
+		it("ignores an unparseable header beside one that parses", async () => {
+			const parsed = await parse(
+				withBody([
+					"Authentication-Results: forged; dmarc=pass )",
+					"From: Alice <alice@acme.example>",
+					"Authentication-Results: mx.example.com; dmarc=fail header.from=acme.example",
+				]),
+			);
+			assert.equal(extractAuthResult(parsed)?.dmarc, "Fail");
+		});
+	});
+});

package/src/heuristics/classifyByHeaders.ts

@@ -6,6 +6,11 @@ import type {
 	ParsedMail,
 	StructuredHeader,
 } from "mailparser";
+import {
+	type AuthenticationResult,
+	type AuthenticationResults,
+	parseAuthenticationResults,
+} from "./authenticationResults.js";
 import { hasMachineHeader, isMachineLocalPart } from "./machineSenders.js";
 import { SOCIAL_DOMAINS } from "./socialDomains.js";
 import { TRANSACTIONAL_DOMAINS } from "./transactionalDomains.js";
@@ -139,41 +144,104 @@ export const extractAuthenticity = (
 	};
 };
 
-const extractVerdict = (
-	text: string,
-	mechanism: string,
+const RESULTS_BY_FAVOURABILITY = [
+	"fail",
+	"softfail",
+	"neutral",
+	"none",
+	"unrecognised",
+	"pass",
+] as const;
+
+type RankedResult = (typeof RESULTS_BY_FAVOURABILITY)[number];
+
+const VERDICT_BY_RESULT: ReadonlyMap<RankedResult, AuthVerdictValue> = new Map([
+	["fail", AuthResultVerdict.Fail],
+	["softfail", AuthResultVerdict.Softfail],
+	["neutral", AuthResultVerdict.Neutral],
+	["none", AuthResultVerdict.None],
+	["pass", AuthResultVerdict.Pass],
+]);
+
+const isRankedResult = (result: string): result is RankedResult =>
+	(RESULTS_BY_FAVOURABILITY as readonly string[]).includes(result);
+
+const rankOf = (result: string): number =>
+	RESULTS_BY_FAVOURABILITY.indexOf(
+		isRankedResult(result) ? result : "unrecognised",
+	);
+
+const leastFavourableVerdict = (
+	results: AuthenticationResult[],
 ): AuthVerdictValue | undefined => {
-	const match = text.match(new RegExp(`${mechanism}=(\\w+)`, "i"));
-	if (!match) return undefined;
-	const raw = match[1].toLowerCase();
-	const map: Record<string, AuthVerdictValue> = {
-		pass: AuthResultVerdict.Pass,
-		fail: AuthResultVerdict.Fail,
-		none: AuthResultVerdict.None,
-		neutral: AuthResultVerdict.Neutral,
-		softfail: AuthResultVerdict.Softfail,
-	};
-	return map[raw];
+	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: string | undefined): string | null => {
+	if (value === undefined) return null;
+	const domain = value.trim().toLowerCase().replace(/\.$/, "");
+	return domain.length > 0 ? domain : null;
+};
+
+const identityDomain = (value: string | undefined): string | null => {
+	if (value === undefined) return null;
+	const at = value.lastIndexOf("@");
+	if (at < 0) return null;
+	return normaliseDomain(value.slice(at + 1));
+};
+
+const dkimSigningDomain = (result: AuthenticationResult): string | null => {
+	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: AuthenticationResult[],
+	fromDomain: string | null,
+): AuthenticationResult[] => {
+	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;
 };
 
-/**
- * Extract provider authentication-results verdict from the Authentication-Results header.
- * Returns null when the header is absent.
- */
 export const extractAuthResult = (
 	parsed: ParsedMail,
 ): MessageAuthResult | null => {
-	const line = parsed.headerLines.find(
-		(l) => l.key.toLowerCase() === "authentication-results",
-	);
-	if (!line) return null;
+	const headers = parsed.headerLines
+		.filter((l) => l.key.toLowerCase() === "authentication-results")
+		.map((l) => parseAuthenticationResults(stripHeaderName(l.line)))
+		.filter((h): h is AuthenticationResults => h !== null);
+	if (headers.length === 0) return null;
 
-	const text = stripHeaderName(line.line);
-	const dmarc = extractVerdict(text, "dmarc");
-	const spf = extractVerdict(text, "spf");
-	const dkim = extractVerdict(text, "dkim");
+	const fromDomain = getFromDomain(parsed);
+	const byMethod = (
+		results: AuthenticationResult[],
+		method: string,
+	): AuthenticationResult[] => results.filter((r) => r.method === method);
+	const acrossHeaders = (method: string): AuthenticationResult[] =>
+		headers.flatMap((h) => byMethod(h.results, method));
 
-	return { dmarc, spf, dkim };
+	return {
+		dmarc: leastFavourableVerdict(acrossHeaders("dmarc")),
+		spf: leastFavourableVerdict(acrossHeaders("spf")),
+		dkim: leastFavourableVerdict(
+			headers.flatMap((h) =>
+				dkimResultsForFrom(byMethod(h.results, "dkim"), fromDomain),
+			),
+		),
+	};
 };
 
 /**

package/src/mailbox-management.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert";
 import { describe, it } from "node:test";
 import type {
 	IMailboxRepository,
+	MailboxItem,
 	MailboxTransitionIntent,
 } from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
@@ -99,7 +100,10 @@ const boxStatus = (path: string): ImapBoxStatus => ({
 	newKeywords: false,
 });
 
-const recordingRepo = () => {
+const recordingRepo = (
+	held: Pick<MailboxItem, "mailboxId" | "fullPath">[] = [],
+) => {
+	const removed: string[] = [];
 	const updates: Array<{ mailboxId: string; patch: Record<string, unknown> }> =
 		[];
 	const settles: Array<{
@@ -108,7 +112,11 @@ const recordingRepo = () => {
 	}> = [];
 	const repo: Pick<
 		IMailboxRepository,
-		"update" | "transition" | "findByPathPrefix"
+		| "update"
+		| "transition"
+		| "findByPathPrefix"
+		| "findByPath"
+		| "deleteMailboxWithMail"
 	> = {
 		update: async (
 			_accountId: string,
@@ -127,8 +135,13 @@ const recordingRepo = () => {
 			return {} as never;
 		},
 		findByPathPrefix: async () => [],
+		findByPath: async (_accountId: string, fullPath: string) =>
+			(held.find((row) => row.fullPath === fullPath) as MailboxItem) ?? null,
+		deleteMailboxWithMail: async (_accountId: string, mailboxId: string) => {
+			removed.push(mailboxId);
+		},
 	};
-	return { repo: repo as IMailboxRepository, updates, settles };
+	return { repo: repo as IMailboxRepository, updates, settles, removed };
 };
 
 const stubConnection = (
@@ -185,6 +198,38 @@ describe("MailboxManagementService.syncCreate — server path normalization", ()
 		assert.strictEqual(settles[0].intent.to, MailboxSyncStatus.synced);
 	});
 
+	it("drops the pending row when the prefixed path already has a folder (#318)", async () => {
+		const { repo, settles, updates, removed } = recordingRepo([
+			{ mailboxId: "mbx-existing", fullPath: "INBOX/Notifications" },
+		]);
+		const connection = {
+			createMailbox: async (_path: string) => ({
+				path: "INBOX/Notifications",
+				created: false,
+			}),
+			subscribeMailbox: async () => undefined,
+			listMailboxes: async (): Promise<FlatMailboxInfo[]> => [],
+			openBox: async (path: string) => boxStatus(path),
+			closeBox: async () => undefined,
+		} as unknown as IImapConnection;
+		const service = new MailboxManagementService(repo);
+
+		const result = await service.syncCreate(
+			"acc-1",
+			"mbx-recreated",
+			"Notifications",
+			async () => connection,
+		);
+
+		assert.deepStrictEqual(result, {
+			success: true,
+			existing: { mailboxId: "mbx-existing", fullPath: "INBOX/Notifications" },
+		});
+		assert.deepStrictEqual(removed, ["mbx-recreated"]);
+		assert.deepStrictEqual(settles, []);
+		assert.deepStrictEqual(updates, []);
+	});
+
 	it("leaves the path untouched when the server keeps it as requested", async () => {
 		const { repo, settles } = recordingRepo();
 		const { connection } = stubConnection("Work", ["Work"]);

package/src/mailbox-management.ts

@@ -48,6 +48,7 @@ export interface MailboxManagementSyncResult {
 	 * which is how a caller tells the two apart without a second read.
 	 */
 	renamed?: { oldPath: string; newPath: string; delimiter: string };
+	existing?: { mailboxId: string; fullPath: string };
 }
 
 /**
@@ -304,6 +305,30 @@ export class MailboxManagementService {
 			this.log.info({ mailboxId, path: serverPath }, "Subscribed to mailbox");
 		}
 
+		const holder =
+			confirmedPath === undefined
+				? null
+				: await this.mailboxService.findByPath(accountId, confirmedPath);
+		if (holder && holder.mailboxId !== mailboxId) {
+			await this.mailboxService.deleteMailboxWithMail(accountId, mailboxId);
+			this.log.info(
+				{
+					accountId,
+					mailboxId,
+					intent: "create",
+					path,
+					serverPath,
+					existingMailboxId: holder.mailboxId,
+					outcome: "already-exists",
+				},
+				"Folder already exists at the path the server resolved",
+			);
+			return {
+				success: true,
+				existing: { mailboxId: holder.mailboxId, fullPath: holder.fullPath },
+			};
+		}
+
 		// Refresh mailbox list to get UIDVALIDITY and other attributes
 		const mailboxes = await connection.listMailboxes();
 		const mailboxInfo = mailboxes.find((m) => m.fullPath === serverPath);

package/src/mailbox-queue.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
 import type {
 	CreateMailboxInput,
+	CreateMailboxResult,
 	IMailboxRepository,
 	MailboxItem,
 } from "@remit/data-ports";
@@ -120,18 +121,19 @@ export class MailboxQueueService {
 	 * @param input - The mailbox creation input (without syncStatus)
 	 * @param accountId - The account ID for the IMAP sync event
 	 * @param subscribe - Whether to subscribe to the mailbox after creation
-	 * @returns The created mailbox
+	 * @returns The created mailbox, or `PathTaken` when the account already has a folder at that path
 	 */
 	createMailbox = async (
 		input: CreateMailboxQueueInput,
 		accountId: string,
 		subscribe?: boolean,
-	): Promise<MailboxItem> => {
-		// Create local mailbox with pending status
-		const mailbox = await this.mailboxService.create({
+	): Promise<CreateMailboxResult> => {
+		const created = await this.mailboxService.create({
 			...input,
 			syncStatus: MailboxSyncStatus.pending,
 		});
+		if (created.outcome === "PathTaken") return created;
+		const { mailbox } = created;
 
 		this.log.info(
 			{ mailboxId: mailbox.mailboxId, path: mailbox.fullPath },
@@ -149,7 +151,7 @@ export class MailboxQueueService {
 			subscribe,
 		});
 
-		return mailbox;
+		return created;
 	};
 
 	/**

package/src/mailbox-sync.test.ts

@@ -13,7 +13,11 @@ import {
 import { parseImapAttributes } from "./attribute-mapper.js";
 import { type MailboxSyncLogger, MailboxSyncService } from "./mailbox-sync.js";
 
-const silentLogger: MailboxSyncLogger = { info: () => {}, debug: () => {} };
+const silentLogger: MailboxSyncLogger = {
+	info: () => {},
+	debug: () => {},
+	error: () => {},
+};
 
 import type { IImapConnection, ImapNamespaces } from "./types.js";
 
@@ -110,7 +114,10 @@ describe("MailboxSyncService.syncMailboxes — UIDVALIDITY cursor detection (#12
 				return {};
 			},
 			delete: async () => undefined,
-			create: async () => ({}),
+			create: async () => ({
+				outcome: "Created",
+				mailbox: { mailboxId: "new" },
+			}),
 		} as unknown as IMailboxRepository;
 
 		const specialUseService = {
@@ -257,6 +264,7 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 			syncStatus?: string;
 			pendingPath?: string;
 		}>,
+		createOutcome: "Created" | "PathTaken" = "Created",
 	) => {
 		const deleted: string[] = [];
 		const created: Array<Record<string, unknown>> = [];
@@ -283,7 +291,11 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 			},
 			create: async (input: Record<string, unknown>) => {
 				created.push(input);
-				return { ...input, mailboxId: `new-${created.length}` };
+				if (createOutcome === "PathTaken") return { outcome: "PathTaken" };
+				return {
+					outcome: "Created",
+					mailbox: { ...input, mailboxId: `new-${created.length}` },
+				};
 			},
 		} as unknown as IMailboxRepository;
 
@@ -401,6 +413,35 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 		assert.deepEqual(deleted, []);
 	});
 
+	it("counts no insert and keeps the account sweep going when the path is already taken", async () => {
+		const { mailboxService, specialUseService, created } = buildServices(
+			[
+				{
+					mailboxId: "inbox",
+					fullPath: "INBOX",
+					syncStatus: MailboxSyncStatus.synced,
+				},
+			],
+			"PathTaken",
+		);
+		const errors: Array<Record<string, unknown>> = [];
+		const service = new MailboxSyncService(mailboxService, specialUseService, {
+			...silentLogger,
+			error: (obj) => {
+				errors.push(obj);
+			},
+		});
+
+		const result = await service.syncMailboxes(
+			{ accountId: "acc-1" },
+			serverConnection([{ fullPath: "INBOX" }, { fullPath: "Projects" }]),
+		);
+
+		assert.equal(created.length, 1);
+		assert.equal(result.created, 0);
+		assert.deepEqual(errors, [{ accountId: "acc-1", fullPath: "Projects" }]);
+	});
+
 	it("lets a failed rename's target be discovered as a folder of its own", async () => {
 		// A failed rename keeps its target so the UI can name what it was aiming
 		// at (T6), and nothing clears it until the user retries or dismisses. If
@@ -539,7 +580,10 @@ describe("MailboxSyncService.syncMailboxes — a lookalike is not a folder the u
 			delete: async (_accountId: string, mailboxId: string) => {
 				deleted.push(mailboxId);
 			},
-			create: async () => ({}),
+			create: async () => ({
+				outcome: "Created",
+				mailbox: { mailboxId: "new" },
+			}),
 		} as unknown as IMailboxRepository;
 
 		const specialUseService = {
@@ -717,7 +761,10 @@ describe("MailboxSyncService.syncMailboxes — a folder leaving mid-sweep (#339)
 				return {};
 			},
 			delete: async () => undefined,
-			create: async () => ({}),
+			create: async () => ({
+				outcome: "Created",
+				mailbox: { mailboxId: "new" },
+			}),
 		} as unknown as IMailboxRepository;
 
 		const specialUseService = {

package/src/mailbox-sync.ts

@@ -82,6 +82,7 @@ export interface SyncAccountInfo {
 export interface MailboxSyncLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
 	debug(obj: Record<string, unknown>, msg: string): void;
+	error(obj: Record<string, unknown>, msg: string): void;
 }
 
 /**
@@ -263,13 +264,13 @@ export class MailboxSyncService {
 						result.updated++;
 					}
 				} else if (!claimedByPendingRename.has(mailboxInfo.fullPath)) {
-					await this.createMailbox(
+					const created = await this.createMailbox(
 						account.accountId,
 						mailboxInfo,
 						namespaces,
 						connection,
 					);
-					result.created++;
+					if (created) result.created++;
 				}
 			},
 			{ concurrency: 3 },
@@ -432,7 +433,7 @@ export class MailboxSyncService {
 		},
 		_namespaces: ImapNamespaces,
 		connection: IImapConnection,
-	): Promise<MailboxItem> => {
+	): Promise<MailboxItem | null> => {
 		// Fetch mailbox status using STATUS command (doesn't require SELECT/EXAMINE)
 		// This gets us message counts including unseen without opening the mailbox
 		const status = await connection.getMailboxStatus(mailboxInfo.fullPath);
@@ -472,7 +473,15 @@ export class MailboxSyncService {
 			// parentMailboxId would need to be resolved from parentPath
 		};
 
-		const mailbox = await this.mailboxService.create(input);
+		const created = await this.mailboxService.create(input);
+		if (created.outcome === "PathTaken") {
+			this.log.error(
+				{ accountId, fullPath: mailboxInfo.fullPath },
+				"Sweep found no row for a folder path the account already holds",
+			);
+			return null;
+		}
+		const { mailbox } = created;
 
 		// Keep the MailboxSpecialUseEntry table in sync — every backend and worker
 		// special-folder lookup reads it through MailboxSpecialUseRepo. Denormalized