@remit/mailbox-service 0.0.112 → 0.0.113

package/src/classify-message.test.ts

@@ -1,142 +0,0 @@
-import assert from "node:assert/strict";
-import { after, before, describe, it } from "node:test";
-import { DisplayNameCorrespondence } from "@remit/domain-enums";
-import { parseMessageBody } from "./body-parse.js";
-import {
-	classifyParsedMessage,
-	extractPrimaryFromEmail,
-} from "./classify-message.js";
-import { openStore, type Store } from "./test-helpers/test-store.js";
-
-const PLAIN_EML = Buffer.from(
-	[
-		"From: Alice <alice@example.com>",
-		"To: me@example.com",
-		"Subject: Hi",
-		"Content-Type: text/plain",
-		"",
-		"hi",
-	].join("\r\n"),
-);
-
-const LIST_EML = Buffer.from(
-	[
-		"From: Alice <alice@example.com>",
-		"To: me@example.com",
-		"Subject: Newsletter",
-		"List-Id: <news.example.com>",
-		"List-Unsubscribe: <https://example.com/unsub>",
-		"Content-Type: text/plain",
-		"",
-		"this week in news",
-	].join("\r\n"),
-);
-
-const IMPERSONATION_EML = Buffer.from(
-	[
-		"From: InfoMedics <billing@serviceupdatebank.atlassian.net>",
-		"To: me@example.com",
-		"Subject: Openstaande factuur",
-		"DKIM-Signature: v=1; a=rsa-sha256; d=atlassian.net; s=sel; b=xxx",
-		"Content-Type: text/html",
-		"",
-		'<a href="https://betaal-vordering.example.org/pay">Betaal uw factuur</a>',
-	].join("\r\n"),
-);
-
-let store: Store;
-before(async () => {
-	store = await openStore();
-});
-after(() => store.close());
-
-describe("classifyParsedMessage", () => {
-	it("answers from the header rule table when the sender has no override", async () => {
-		const parsed = await parseMessageBody(LIST_EML);
-
-		const classification = await classifyParsedMessage(
-			store.address,
-			"acc-1",
-			parsed,
-			"inbox",
-		);
-
-		assert.equal(classification.category, "newsletter");
-		assert.equal(classification.hasListUnsubscribe, true);
-	});
-
-	it("classifies mail with no From address by headers alone", async () => {
-		const parsed = await parseMessageBody(
-			Buffer.from(
-				[
-					"To: me@example.com",
-					"Subject: Hi",
-					"Content-Type: text/plain",
-					"",
-					"hi",
-				].join("\r\n"),
-			),
-		);
-
-		const classification = await classifyParsedMessage(
-			store.address,
-			"acc-1",
-			parsed,
-			"inbox",
-		);
-
-		assert.equal(classification.category, "personal");
-	});
-});
-
-describe("classifyParsedMessage sender mismatch", () => {
-	it("compares the sender of mail in Junk the provider rated clean", async () => {
-		const parsed = await parseMessageBody(IMPERSONATION_EML);
-
-		const classification = await classifyParsedMessage(
-			store.address,
-			"acc-1",
-			parsed,
-			"junk",
-		);
-
-		assert.equal(
-			classification.authenticity?.displayNameCorrespondence,
-			DisplayNameCorrespondence.Unrelated,
-		);
-		assert.deepEqual(classification.authenticity?.offDomainLinkDomains, [
-			"example.org",
-		]);
-	});
-
-	it("compares nothing for the same mail outside Junk without a provider verdict", async () => {
-		const parsed = await parseMessageBody(IMPERSONATION_EML);
-
-		const classification = await classifyParsedMessage(
-			store.address,
-			"acc-1",
-			parsed,
-			"inbox",
-		);
-
-		assert.equal(
-			classification.authenticity?.displayNameCorrespondence,
-			undefined,
-		);
-		assert.equal(classification.authenticity?.offDomainLinkDomains, undefined);
-	});
-});
-
-describe("extractPrimaryFromEmail", () => {
-	it("reads the first From address", async () => {
-		const parsed = await parseMessageBody(PLAIN_EML);
-		assert.equal(extractPrimaryFromEmail(parsed), "alice@example.com");
-	});
-
-	it("answers null when there is no From address to read", async () => {
-		const parsed = await parseMessageBody(
-			Buffer.from(["To: me@example.com", "", "hi"].join("\r\n")),
-		);
-		assert.equal(extractPrimaryFromEmail(parsed), null);
-	});
-});

package/src/classify-message.ts

@@ -1,116 +0,0 @@
-import type {
-	IAddressRepository,
-	ThreadMessageItem,
-	UpdateMessageInput,
-} from "@remit/data-ports";
-import { NotFoundError } from "@remit/data-ports/errors";
-import { deriveAddressId } from "@remit/data-ports/id";
-import type { ParsedMail } from "mailparser";
-import {
-	classifyByHeaders,
-	extractAuthenticity,
-	extractAuthResult,
-	extractHasListUnsubscribe,
-	extractProviderSpam,
-} from "./heuristics/classifyByHeaders.js";
-import type { FolderPlacement } from "./heuristics/classifyPlacement.js";
-import { extractSenderMismatch } from "./heuristics/senderMismatch.js";
-
-type ThreadMessageCategory = ThreadMessageItem["category"];
-
-/**
- * The From address the classifier reads, when there is one to read. Shared by
- * every path that classifies or counts a sender (body-sync's classification,
- * inbound counter and placement signals, and the classification backfill) so
- * they all read the same address off the same bytes.
- */
-export const extractPrimaryFromEmail = (parsed: ParsedMail): string | null => {
-	const from = parsed.from;
-	if (!from || !from.value || from.value.length === 0) return null;
-	const address = from.value[0]?.address;
-	if (!address) return null;
-	return address.toLowerCase();
-};
-
-/**
- * The one-sided half of `Address.flags.category` (issue #299, RFC 039
- * Decision 3): a real value here overrides `classifyByHeaders` outright.
- * Only a genuinely-absent Address is "no override" — any other failure
- * (throttle, infra) propagates, because this feeds the write-once
- * `Message.category` at the moment it is decided, where a masked infra
- * failure would silently classify by headers when the user asked for
- * something else.
- */
-const resolveCategoryOverride = async (
-	addressService: Pick<IAddressRepository, "getAddress">,
-	accountConfigId: string,
-	fromEmail: string,
-): Promise<ThreadMessageCategory | undefined> => {
-	try {
-		const addressId = deriveAddressId(accountConfigId, fromEmail);
-		const address = await addressService.getAddress(accountConfigId, addressId);
-		return address.flags?.category?.value;
-	} catch (err) {
-		if (!(err instanceof NotFoundError)) throw err;
-		return undefined;
-	}
-};
-
-/**
- * Header classification, with the sender's `Address.flags.category` override
- * (issue #299, RFC 039 Decision 3) substituted for the header-derived
- * category when one is set. Returns the subset of the Message update that
- * carries the derived fields; the caller folds it into a single UpdateItem
- * alongside `bodyStorageKey` (body-sync) or `classificationState` (the
- * classification backfill, issue #1197). Optional signals are omitted when
- * absent so we never overwrite an existing value with `undefined`.
- *
- * The override wins outright rather than blending with the heuristic — RFC
- * 039 Decision 3 treats a direct reclassification as final, the same as
- * `flags.blocked`/`vip` already override placement. Every caller gates on
- * `hasDecidedCategory` before this result reaches a write, so a message that
- * already carries a real category is never re-touched regardless of what
- * this returns.
- */
-export const classifyParsedMessage = async (
-	addressService: Pick<IAddressRepository, "getAddress">,
-	accountConfigId: string,
-	parsed: ParsedMail,
-	placement: FolderPlacement,
-): Promise<UpdateMessageInput & { category: ThreadMessageCategory }> => {
-	const headerCategory = classifyByHeaders(parsed);
-	const authenticity = extractAuthenticity(parsed);
-	const authResult = extractAuthResult(parsed);
-	const providerSpam = extractProviderSpam(parsed);
-	const hasListUnsubscribe = extractHasListUnsubscribe(parsed);
-
-	// A passing SPF/DKIM/DMARC check proves the sending domain, not the
-	// identity the message claims — on a shared-tenant host the verified
-	// subdomain belongs to whoever signed up. These two comparisons say
-	// whether the claim holds, and run only over mail the provider already
-	// called spam or that sits in the Junk folder.
-	const senderMismatch =
-		authenticity === null
-			? {}
-			: extractSenderMismatch(parsed, {
-					fromDomain: authenticity.fromDomain,
-					providerSpamClassified: providerSpam?.classified === true,
-					placement,
-					bulkSender: hasListUnsubscribe,
-				});
-
-	const fromEmail = extractPrimaryFromEmail(parsed);
-	const categoryOverride = fromEmail
-		? await resolveCategoryOverride(addressService, accountConfigId, fromEmail)
-		: undefined;
-
-	return {
-		category: categoryOverride ?? headerCategory,
-		hasListUnsubscribe,
-		...(authenticity !== null
-			? { authenticity: { ...authenticity, ...senderMismatch } }
-			: {}),
-		...(authResult !== null ? { authResult } : {}),
-		...(providerSpam !== null ? { providerSpam } : {}),
-	};
-};

package/src/connection-factory.ts

@@ -1,102 +0,0 @@
-/**
- * Connection factory for IMAP implementations
- *
- * Uses ImapFlow for all IMAP connections.
- */
-
-import {
-	createImapFlowConnectionFromAccount,
-	createImapFlowConnectionWithCredentials,
-	ImapFlowConnection,
-} from "./imapflow-connection.js";
-import type {
-	IImapConnection,
-	ImapConnectionConfig,
-	MailCredentials,
-} from "./types.js";
-
-/**
- * Create an IMAP connection
- */
-export const createConnection = (
-	config: ImapConnectionConfig,
-): IImapConnection => {
-	return new ImapFlowConnection(config);
-};
-
-/**
- * Create an IMAP connection from account data using password credentials.
- */
-export const createConnectionFromAccount = (
-	account: {
-		imapHost: string;
-		imapPort: number;
-		imapTls: boolean;
-		username: string;
-	},
-	password: string,
-): IImapConnection => {
-	return createImapFlowConnectionFromAccount(account, password);
-};
-
-/**
- * Create an IMAP connection from account data using a MailCredentials union.
- * Use this instead of createConnectionFromAccount for OAuth accounts.
- */
-export const createConnectionWithCredentials = (
-	account: {
-		imapHost: string;
-		imapPort: number;
-		imapTls: boolean;
-		username: string;
-	},
-	credentials: MailCredentials,
-): IImapConnection => {
-	return createImapFlowConnectionWithCredentials(account, credentials);
-};
-
-/**
- * Managed connection factory that caches and reuses a single connection.
- *
- * The factory handles connection lifecycle - callers should not disconnect.
- * Call close() on the factory to disconnect when done.
- */
-export interface ManagedConnectionFactory {
-	/** Get the cached connection (creates on first call) */
-	getConnection(): IImapConnection;
-	/** Disconnect and cleanup */
-	close(): Promise<void>;
-}
-
-/**
- * Create a managed connection factory that caches a single connection.
- *
- * @example
- * ```typescript
- * const factory = createManagedConnectionFactory(config);
- * const conn = factory.getConnection();
- * await conn.connect();
- * // ... reuse conn via factory.getConnection() ...
- * await factory.close(); // Disconnect when done
- * ```
- */
-export const createManagedConnectionFactory = (
-	config: ImapConnectionConfig,
-): ManagedConnectionFactory => {
-	let connection: ImapFlowConnection | null = null;
-
-	return {
-		getConnection: () => {
-			if (!connection) {
-				connection = new ImapFlowConnection(config);
-			}
-			return connection;
-		},
-		close: async () => {
-			if (connection) {
-				await connection.disconnect();
-				connection = null;
-			}
-		},
-	};
-};

package/src/connection-test.ts

@@ -1,208 +0,0 @@
-/**
- * Connection testing utilities for IMAP and SMTP servers
- *
- * Used to validate credentials before saving account configuration.
- */
-
-import { createConnection as createNetConnection } from "node:net";
-import { connect as tlsConnect } from "node:tls";
-import { createTransport } from "nodemailer";
-import type { MailCredentials } from "./types.js";
-import { MailConnectionError } from "./types.js";
-
-export interface TestResult {
-	success: boolean;
-	error?: string;
-}
-
-export interface ImapTestConfig {
-	host: string;
-	port: number;
-	secure: boolean;
-	startTls?: boolean;
-	credentials: MailCredentials;
-	user: string;
-}
-
-export interface SmtpTestConfig {
-	host: string;
-	port: number;
-	secure: boolean;
-	credentials: MailCredentials;
-	user: string;
-}
-
-// TODO(#468): Wire OAuth testConnection once authType/oauthRefreshTokenHash are
-// available on Account. For OAuth accounts, mint a token via MailOAuthService
-// before calling testImapConnection / testSmtpConnection, and map
-// RefreshTokenError(reauth-required) to MailConnectionError("auth", ...).
-
-const TEST_TIMEOUT_MS = 12_000;
-
-/**
- * Build nodemailer auth object from credentials.
- */
-const buildSmtpAuth = (
-	user: string,
-	credentials: MailCredentials,
-):
-	| { user: string; pass: string }
-	| { type: "OAuth2"; user: string; accessToken: string } => {
-	if (credentials.kind === "password") {
-		return { user, pass: credentials.password };
-	}
-	return {
-		type: "OAuth2" as const,
-		user,
-		accessToken: credentials.accessToken,
-	};
-};
-
-/**
- * Test IMAP connection with provided credentials.
- *
- * Uses a raw socket to send AUTH PLAIN directly — bypasses the CAPABILITY
- * round-trip that IMAP clients typically perform first, avoiding deadlocks
- * with servers that pipeline their tagged responses.
- *
- * Supports plaintext, direct TLS (secure: true), and STARTTLS (startTls: true).
- */
-export const testImapConnection = async (
-	config: ImapTestConfig,
-): Promise<TestResult> => {
-	if (config.credentials.kind !== "password") {
-		return { success: false, error: "OAuth not supported for connection test" };
-	}
-
-	const { user, credentials } = config;
-	const authPlain = Buffer.from(
-		`\x00${user}\x00${credentials.password}`,
-	).toString("base64");
-
-	return new Promise((resolve) => {
-		let settled = false;
-		const done = (result: TestResult) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeoutId);
-			resolve(result);
-		};
-
-		const timeoutId = setTimeout(
-			() => done({ success: false, error: "Connection timed out" }),
-			TEST_TIMEOUT_MS,
-		);
-
-		let buf = "";
-		let phase: "greeting" | "starttls" | "tls-upgrade" | "auth" | "done" =
-			"greeting";
-		// biome-ignore lint/suspicious/noExplicitAny: socket type varies between net.Socket and tls.TLSSocket
-		let sock: any;
-
-		const onData = (chunk: Buffer) => {
-			buf += chunk.toString();
-			const lines = buf.split("\r\n");
-			buf = lines.pop() ?? "";
-
-			for (const line of lines) {
-				if (phase === "greeting" && /^\* OK/i.test(line)) {
-					if (config.startTls) {
-						phase = "starttls";
-						sock.write("A001 STARTTLS\r\n");
-					} else {
-						phase = "auth";
-						sock.write(`A001 AUTHENTICATE PLAIN ${authPlain}\r\n`);
-					}
-				} else if (phase === "starttls" && /^A001 OK/i.test(line)) {
-					phase = "tls-upgrade";
-					// Upgrade socket to TLS in place
-					const tlsSock = tlsConnect({
-						socket: sock,
-						host: config.host,
-						rejectUnauthorized: false,
-					});
-					tlsSock.on("data", onData);
-					tlsSock.on("error", onError);
-					tlsSock.once("secureConnect", () => {
-						phase = "auth";
-						sock = tlsSock;
-						sock.write(`A002 AUTHENTICATE PLAIN ${authPlain}\r\n`);
-					});
-				} else if (
-					phase === "auth" &&
-					(/^A00[12] OK/i.test(line) || /^A001 OK/i.test(line))
-				) {
-					phase = "done";
-					sock.write("A099 LOGOUT\r\n");
-					done({ success: true });
-				} else if (
-					phase === "auth" &&
-					(/^A00[12] NO/i.test(line) || /^A00[12] BAD/i.test(line))
-				) {
-					phase = "done";
-					sock.destroy();
-					done({ success: false, error: "Authentication failed" });
-				}
-			}
-		};
-
-		const onError = (err: Error) => {
-			done({ success: false, error: err.message });
-		};
-
-		if (config.secure) {
-			sock = tlsConnect({
-				host: config.host,
-				port: config.port,
-				rejectUnauthorized: false,
-			});
-		} else {
-			sock = createNetConnection({ host: config.host, port: config.port });
-		}
-
-		sock.on("data", onData);
-		sock.on("error", onError);
-	});
-};
-
-/**
- * Test SMTP connection with provided credentials
- *
- * Uses nodemailer's verify() method to test authentication.
- */
-export const testSmtpConnection = async (
-	config: SmtpTestConfig,
-): Promise<TestResult> => {
-	const transport = createTransport({
-		host: config.host,
-		port: config.port,
-		secure: config.secure,
-		auth: buildSmtpAuth(config.user, config.credentials),
-		connectionTimeout: TEST_TIMEOUT_MS,
-		greetingTimeout: TEST_TIMEOUT_MS,
-		socketTimeout: TEST_TIMEOUT_MS,
-	});
-
-	const attempt = transport
-		.verify()
-		.then(() => ({ success: true as const }))
-		.catch((error: unknown) => {
-			if (error instanceof MailConnectionError) {
-				return { success: false as const, error: error.message };
-			}
-			return {
-				success: false as const,
-				error: error instanceof Error ? error.message : "Connection failed",
-			};
-		})
-		.finally(() => transport.close());
-
-	const timeout = new Promise<TestResult>((resolve) =>
-		setTimeout(() => {
-			transport.close();
-			resolve({ success: false, error: "Connection timed out" });
-		}, TEST_TIMEOUT_MS),
-	);
-
-	return Promise.race([attempt, timeout]);
-};