@remit/mailbox-service 0.0.111 → 0.0.113

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]);
-};

package/src/credentials.test.ts

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