@remit/mailbox-service 0.0.1

package/src/connection-factory.ts

@@ -0,0 +1,102 @@
+/**
+ * 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

@@ -0,0 +1,208 @@
+/**
+ * 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]);
+};

package/src/credentials.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Unit tests for MailCredentials union and MailConnectionError.
+ *
+ * Covers:
+ * 1. Auth object construction — imapflow auth shape for each credential kind
+ * 2. Exhaustiveness — TypeScript catches missing cases via `never`
+ * 3. Token-leak assertion — accessToken never in serialized error
+ * 4. Error classification — createImapFlowConnectionFromAccount wires password
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { inspect } from "node:util";
+import { MailConnectionError, type MailCredentials } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Helper: build the same imapflow auth object that imapflow-connection.ts uses
+// (extracted here so the test doesn't import the whole class)
+// ---------------------------------------------------------------------------
+
+type ImapAuth =
+	| { user: string; pass: string }
+	| { user: string; accessToken: string };
+
+const buildImapAuth = (
+	user: string,
+	credentials: MailCredentials,
+): ImapAuth => {
+	if (credentials.kind === "password") {
+		return { user, pass: credentials.password };
+	}
+	if (credentials.kind === "accessToken") {
+		return { user, accessToken: credentials.accessToken };
+	}
+	// Exhaustiveness check — TypeScript will error here if a new union member
+	// is added without updating this function.
+	const _exhaustive: never = credentials;
+	throw new Error(`Unknown credential kind: ${JSON.stringify(_exhaustive)}`);
+};
+
+// ---------------------------------------------------------------------------
+// Helper: build the same nodemailer auth object that smtp-client.ts uses
+// ---------------------------------------------------------------------------
+
+type SmtpAuth =
+	| { user: string; pass: string }
+	| { type: "OAuth2"; user: string; accessToken: string };
+
+const buildSmtpAuth = (
+	user: string,
+	credentials: MailCredentials,
+): SmtpAuth => {
+	if (credentials.kind === "password") {
+		return { user, pass: credentials.password };
+	}
+	if (credentials.kind === "accessToken") {
+		return {
+			type: "OAuth2" as const,
+			user,
+			accessToken: credentials.accessToken,
+		};
+	}
+	// Exhaustiveness check
+	const _exhaustive: never = credentials;
+	throw new Error(`Unknown credential kind: ${JSON.stringify(_exhaustive)}`);
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("MailCredentials — imapflow auth shape", () => {
+	it("password kind → { user, pass }", () => {
+		const creds: MailCredentials = { kind: "password", password: "s3cr3t" };
+		const auth = buildImapAuth("alice@example.com", creds);
+
+		assert.deepEqual(auth, { user: "alice@example.com", pass: "s3cr3t" });
+		assert.ok(
+			!("accessToken" in auth),
+			"no accessToken field for password auth",
+		);
+	});
+
+	it("accessToken kind → { user, accessToken }", () => {
+		const token = "ya29.super-secret-token";
+		const creds: MailCredentials = { kind: "accessToken", accessToken: token };
+		const auth = buildImapAuth("alice@example.com", creds);
+
+		assert.deepEqual(auth, {
+			user: "alice@example.com",
+			accessToken: token,
+		});
+		assert.ok(!("pass" in auth), "no pass field for accessToken auth");
+	});
+});
+
+describe("MailCredentials — nodemailer auth shape", () => {
+	it("password kind → { user, pass }", () => {
+		const creds: MailCredentials = { kind: "password", password: "s3cr3t" };
+		const auth = buildSmtpAuth("alice@example.com", creds);
+
+		assert.deepEqual(auth, { user: "alice@example.com", pass: "s3cr3t" });
+		assert.ok(!("type" in auth), "no OAuth2 type field for password auth");
+	});
+
+	it("accessToken kind → { type: 'OAuth2', user, accessToken }", () => {
+		const token = "ya29.super-secret-token";
+		const creds: MailCredentials = { kind: "accessToken", accessToken: token };
+		const auth = buildSmtpAuth("alice@example.com", creds);
+
+		assert.deepEqual(auth, {
+			type: "OAuth2",
+			user: "alice@example.com",
+			accessToken: token,
+		});
+		assert.ok(!("pass" in auth), "no pass field for OAuth2 auth");
+	});
+});
+
+describe("MailConnectionError", () => {
+	it("stores kind='auth'", () => {
+		const err = new MailConnectionError("auth", "IMAP authentication failed");
+		assert.equal(err.kind, "auth");
+		assert.equal(err.name, "MailConnectionError");
+		assert.equal(err.message, "IMAP authentication failed");
+	});
+
+	it("stores kind='network'", () => {
+		const err = new MailConnectionError(
+			"network",
+			"IMAP connection failed: ECONNREFUSED",
+		);
+		assert.equal(err.kind, "network");
+	});
+
+	it("token-leak: accessToken must NOT appear in inspected MailConnectionError", () => {
+		const secretToken = "ya29.A0ARrdaM_very_secret_access_token_12345";
+
+		// Simulate what connection code does: auth fails for an OAuth account.
+		// The error message must NOT mention the token, only "auth failed".
+		const err = new MailConnectionError(
+			"auth",
+			"IMAP authentication failed",
+			// The cause should also never include the token
+		);
+
+		// util.inspect walks the full error including the cause chain, so this
+		// proves no token leaks through name/message/stack OR cause.
+		const serialized = inspect(err, { depth: null });
+
+		assert.ok(
+			!serialized.includes(secretToken),
+			`MailConnectionError must not contain the access token — got: ${serialized.slice(0, 200)}`,
+		);
+	});
+
+	it("token-leak: accessToken in cause does NOT bubble into error.message", () => {
+		// Even if the underlying library error somehow includes the token text,
+		// our MailConnectionError message must not re-echo it.
+		const secretToken = "ya29.A0ARrdaM_very_secret_access_token_CAUSE";
+		const underlyingError = new Error(`AUTH failed token=${secretToken}`);
+
+		const err = new MailConnectionError(
+			"auth",
+			"IMAP authentication failed",
+			underlyingError,
+		);
+
+		// The message itself must be token-free
+		assert.ok(
+			!err.message.includes(secretToken),
+			"error.message must not contain the access token",
+		);
+	});
+
+	it("is instanceof Error", () => {
+		const err = new MailConnectionError("auth", "test");
+		assert.ok(err instanceof Error);
+		assert.ok(err instanceof MailConnectionError);
+	});
+});

package/src/filters/match.test.ts

@@ -0,0 +1,181 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { FilterItem } from "@remit/data-ports";
+import { FilterClauseField, FilterMatchOperator } from "@remit/domain-enums";
+import {
+	buildMatchText,
+	clauseMatches,
+	cosineSimilarity,
+	type FilterMessage,
+	literalClausesMatch,
+	selectMoveWinner,
+} from "./match.js";
+
+type FilterClause = FilterItem["literalClauses"][number];
+
+const message = (overrides: Partial<FilterMessage> = {}): FilterMessage => ({
+	from: "alice@acme.example",
+	fromName: "Alice Example",
+	subject: "Q3 invoice attached",
+	text: "Please find the invoice for the quarter attached.",
+	...overrides,
+});
+
+const clause = (field: FilterClause["field"], value: string): FilterClause => ({
+	field,
+	value,
+});
+
+describe("clauseMatches", () => {
+	it("matches From against the sender address, case-insensitively", () => {
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.From, "ACME.example"), message()),
+			true,
+		);
+	});
+
+	it("matches From against the sender display name", () => {
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.From, "alice example"), message()),
+			true,
+		);
+	});
+
+	it("matches Subject as a substring", () => {
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.Subject, "invoice"), message()),
+			true,
+		);
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.Subject, "receipt"), message()),
+			false,
+		);
+	});
+
+	it("matches HasWords against subject or body", () => {
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.HasWords, "quarter"), message()),
+			true,
+		);
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.HasWords, "Q3"), message()),
+			true,
+		);
+	});
+
+	it("never matches an empty clause value", () => {
+		assert.equal(
+			clauseMatches(clause(FilterClauseField.HasWords, "   "), message()),
+			false,
+		);
+	});
+});
+
+describe("literalClausesMatch", () => {
+	it("passes vacuously with no clauses (a purely-semantic filter)", () => {
+		assert.equal(
+			literalClausesMatch([], FilterMatchOperator.And, message()),
+			true,
+		);
+	});
+
+	it("And requires every clause to match", () => {
+		const clauses = [
+			clause(FilterClauseField.From, "acme.example"),
+			clause(FilterClauseField.Subject, "invoice"),
+		];
+		assert.equal(
+			literalClausesMatch(clauses, FilterMatchOperator.And, message()),
+			true,
+		);
+		assert.equal(
+			literalClausesMatch(
+				[...clauses, clause(FilterClauseField.Subject, "nope")],
+				FilterMatchOperator.And,
+				message(),
+			),
+			false,
+		);
+	});
+
+	it("Or requires only one clause to match", () => {
+		const clauses = [
+			clause(FilterClauseField.Subject, "nope"),
+			clause(FilterClauseField.Subject, "invoice"),
+		];
+		assert.equal(
+			literalClausesMatch(clauses, FilterMatchOperator.Or, message()),
+			true,
+		);
+		assert.equal(
+			literalClausesMatch(
+				[clause(FilterClauseField.Subject, "nope")],
+				FilterMatchOperator.Or,
+				message(),
+			),
+			false,
+		);
+	});
+});
+
+describe("cosineSimilarity", () => {
+	it("scores identical vectors as 1", () => {
+		assert.equal(cosineSimilarity([1, 2, 3], [1, 2, 3]), 1);
+	});
+
+	it("scores orthogonal vectors as 0", () => {
+		assert.equal(cosineSimilarity([1, 0], [0, 1]), 0);
+	});
+
+	it("scores a zero vector as 0 rather than dividing by zero", () => {
+		assert.equal(cosineSimilarity([0, 0], [1, 1]), 0);
+	});
+
+	it("throws on a dimension mismatch instead of scoring incomparable vectors", () => {
+		assert.throws(
+			() => cosineSimilarity([1, 2], [1, 2, 3]),
+			/dimension mismatch/,
+		);
+	});
+});
+
+describe("selectMoveWinner", () => {
+	const filter = (filterId: string, ruleChangedAt: number): FilterItem =>
+		({ filterId, ruleChangedAt }) as FilterItem;
+
+	it("returns undefined with no candidates", () => {
+		assert.equal(selectMoveWinner([]), undefined);
+	});
+
+	it("picks the most-recently-changed filter", () => {
+		const winner = selectMoveWinner([
+			filter("a", 100),
+			filter("b", 300),
+			filter("c", 200),
+		]);
+		assert.equal(winner?.filterId, "b");
+	});
+
+	it("tie-breaks on filterId when ruleChangedAt is identical", () => {
+		const winner = selectMoveWinner([
+			filter("a", 100),
+			filter("c", 100),
+			filter("b", 100),
+		]);
+		assert.equal(winner?.filterId, "c");
+	});
+});
+
+describe("buildMatchText", () => {
+	it("joins subject and body and bounds the length", () => {
+		const text = buildMatchText(message({ subject: "hello", text: "world" }));
+		assert.equal(text, "hello\nworld");
+	});
+
+	it("caps at 512 characters", () => {
+		const text = buildMatchText(
+			message({ subject: "", text: "x".repeat(1000) }),
+		);
+		assert.equal(text.length, 512);
+	});
+});