@remit/smtp-service 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@remit/smtp-service",
+	"version": "0.0.1",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test:typecheck": "tsgo --noEmit",
+		"test:run": "node --env-file=../../localhost-test-unit.env --test 'src/**/*.test.ts'",
+		"test": "npm run test:typecheck && npm run test:run",
+		"test:integ": "RUN_INTEG_TESTS=true node --env-file=../../localhost-dev-aws.env --import tsx --test --test-force-exit 'src/**/*.integ.test.ts'"
+	},
+	"devDependencies": {
+		
+		"@remit/domain-enums": "*",
+		"@types/node": "*",
+		"@types/nodemailer": "*"
+	},
+	"dependencies": {
+		"nodemailer": "^9.0.3"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/remit.git",
+		"directory": "packages/smtp-service"
+	}
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./message-builder.js";
+export * from "./message-id.js";
+export * from "./smtp-client.js";

package/src/message-builder.ts

@@ -0,0 +1,51 @@
+import type { OutboxMessageItem } from "@remit/data-ports";
+
+export interface MailMessage {
+	from: string;
+	to: string[];
+	cc?: string[];
+	bcc?: string[];
+	replyTo?: string;
+	subject?: string;
+	text?: string;
+	html?: string;
+	messageId: string;
+	inReplyTo?: string;
+	references?: string;
+	attachments?: MailAttachment[];
+}
+
+export interface MailAttachment {
+	filename: string;
+	content: Buffer;
+	contentType: string;
+	cid?: string;
+	contentDisposition?: "attachment" | "inline";
+}
+
+/**
+ * Build Nodemailer message options from OutboxMessage entity
+ */
+export const buildMailMessage = (
+	outbox: OutboxMessageItem,
+	attachments?: MailAttachment[],
+): MailMessage => {
+	const from = outbox.fromName
+		? `"${outbox.fromName}" <${outbox.fromAddress}>`
+		: outbox.fromAddress;
+
+	return {
+		from,
+		to: outbox.toAddresses,
+		cc: outbox.ccAddresses,
+		bcc: outbox.bccAddresses,
+		replyTo: outbox.replyToAddress,
+		subject: outbox.subject,
+		text: outbox.textBody,
+		html: outbox.htmlBody,
+		messageId: `<${outbox.messageIdValue}>`,
+		inReplyTo: outbox.inReplyTo ? `<${outbox.inReplyTo}>` : undefined,
+		references: outbox.references?.map((r) => `<${r}>`).join(" "),
+		attachments,
+	};
+};

package/src/message-id.test.ts

@@ -0,0 +1,51 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { extractDomain, generateMessageId } from "./message-id.js";
+
+describe("Message-ID generation", () => {
+	it("generates unique message IDs", () => {
+		const id1 = generateMessageId("example.com");
+		const id2 = generateMessageId("example.com");
+		assert.notStrictEqual(id1, id2);
+	});
+
+	it("includes domain in message ID", () => {
+		const id = generateMessageId("test.example.com");
+		assert.ok(id.endsWith("@test.example.com"));
+	});
+
+	it("contains timestamp and random hex", () => {
+		const id = generateMessageId("example.com");
+		const parts = id.split("@")[0].split(".");
+		assert.strictEqual(parts.length, 2);
+		// First part is timestamp (numeric)
+		assert.ok(/^\d+$/.test(parts[0]));
+		// Second part is hex string
+		assert.ok(/^[0-9a-f]+$/.test(parts[1]));
+	});
+});
+
+describe("extractDomain", () => {
+	it("extracts domain from email", () => {
+		assert.strictEqual(extractDomain("user@example.com"), "example.com");
+	});
+
+	it("handles email with + alias", () => {
+		assert.strictEqual(extractDomain("user+tag@example.com"), "example.com");
+	});
+
+	it("handles subdomain", () => {
+		assert.strictEqual(
+			extractDomain("user@mail.example.com"),
+			"mail.example.com",
+		);
+	});
+
+	it("uses last @ for edge cases", () => {
+		assert.strictEqual(extractDomain("user@name@example.com"), "example.com");
+	});
+
+	it("throws on invalid email", () => {
+		assert.throws(() => extractDomain("invalid"), /Invalid email/);
+	});
+});

package/src/message-id.ts

@@ -0,0 +1,22 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Generate RFC 2822 compliant Message-ID
+ * Format: <timestamp.random@domain>
+ */
+export const generateMessageId = (domain: string): string => {
+	const timestamp = Date.now();
+	const random = randomBytes(8).toString("hex");
+	return `${timestamp}.${random}@${domain}`;
+};
+
+/**
+ * Extract domain from email address for Message-ID generation
+ */
+export const extractDomain = (email: string): string => {
+	const atIndex = email.lastIndexOf("@");
+	if (atIndex === -1) {
+		throw new Error(`Invalid email address: ${email}`);
+	}
+	return email.slice(atIndex + 1);
+};

package/src/smtp-client.integ.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Integration tests for SMTP client using mokapi.
+ *
+ * These tests require mokapi to be running:
+ *   npm run start:mokapi
+ *
+ * Run with:
+ *   npm run test:integ -w packages/smtp-service
+ *
+ * Note: mokapi SMTP server runs on port 2525 without TLS.
+ * Sent emails are delivered to the recipient's IMAP mailbox.
+ */
+
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import type { MailMessage } from "./message-builder.js";
+import { generateMessageId } from "./message-id.js";
+import { type SmtpConfig, sendMail } from "./smtp-client.js";
+
+const MOKAPI_SMTP_CONFIG: SmtpConfig = {
+	host: "localhost",
+	port: 2525,
+	secure: false,
+	user: "alice@mokapi.io",
+	credentials: { kind: "password", password: "alice123" },
+	tls: {
+		rejectUnauthorized: false, // Accept mokapi's self-signed cert
+	},
+};
+
+/**
+ * Generate a unique message ID for testing
+ */
+const createTestMessageId = (): string => {
+	return `<${generateMessageId("mokapi.io")}>`;
+};
+
+/**
+ * Create a basic test message
+ */
+const createTestMessage = (
+	overrides: Partial<MailMessage> = {},
+): MailMessage => {
+	return {
+		from: "alice@mokapi.io",
+		to: ["bob@mokapi.io"],
+		subject: `Test message ${Date.now()}`,
+		text: "This is a test message body.",
+		messageId: createTestMessageId(),
+		...overrides,
+	};
+};
+
+describe(
+	"SMTP client integration tests",
+	{
+		skip: !process.env.RUN_INTEG_TESTS,
+	},
+	() => {
+		describe("sendMail", () => {
+			test("sends a simple text message", async () => {
+				const message = createTestMessage({
+					subject: `Simple text test ${Date.now()}`,
+					text: "Hello from the SMTP integration test!",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.equal(result.isTransient, false, "Should not be transient");
+				assert.ok(result.messageId, "Should return a message ID");
+				assert.ok(result.response, "Should return an SMTP response");
+			});
+
+			test("sends an HTML message", async () => {
+				const message = createTestMessage({
+					subject: `HTML test ${Date.now()}`,
+					text: "Plain text fallback",
+					html: "<html><body><h1>Hello!</h1><p>This is an <strong>HTML</strong> message.</p></body></html>",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a message with CC recipients", async () => {
+				const message = createTestMessage({
+					subject: `CC test ${Date.now()}`,
+					to: ["bob@mokapi.io"],
+					cc: ["alice@mokapi.io"],
+					text: "Message with CC recipient",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a message with BCC recipients", async () => {
+				const message = createTestMessage({
+					subject: `BCC test ${Date.now()}`,
+					to: ["bob@mokapi.io"],
+					bcc: ["alice@mokapi.io"],
+					text: "Message with BCC recipient",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a message with multiple recipients", async () => {
+				const message = createTestMessage({
+					subject: `Multiple recipients test ${Date.now()}`,
+					to: ["bob@mokapi.io", "alice@mokapi.io"],
+					text: "Message to multiple recipients",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a reply with In-Reply-To header", async () => {
+				const originalMessageId = "<original-message-123@mokapi.io>";
+				const message = createTestMessage({
+					subject: `Re: Original subject ${Date.now()}`,
+					text: "This is a reply to your message.",
+					inReplyTo: originalMessageId,
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a reply with References header", async () => {
+				const references = [
+					"<msg-1@mokapi.io>",
+					"<msg-2@mokapi.io>",
+					"<msg-3@mokapi.io>",
+				].join(" ");
+
+				const message = createTestMessage({
+					subject: `Re: Thread subject ${Date.now()}`,
+					text: "This is a reply in a thread.",
+					inReplyTo: "<msg-3@mokapi.io>",
+					references,
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a message with Reply-To address", async () => {
+				const message = createTestMessage({
+					subject: `Reply-To test ${Date.now()}`,
+					text: "Please reply to a different address.",
+					replyTo: "noreply@mokapi.io",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("sends a message with formatted From name", async () => {
+				const message = createTestMessage({
+					from: '"Alice Test" <alice@mokapi.io>',
+					subject: `From name test ${Date.now()}`,
+					text: "Message with formatted From name",
+				});
+
+				const result = await sendMail(MOKAPI_SMTP_CONFIG, message);
+
+				assert.equal(result.success, true, "Send should succeed");
+				assert.ok(result.messageId, "Should return a message ID");
+			});
+
+			test("handles connection failure gracefully", async () => {
+				const badConfig: SmtpConfig = {
+					host: "localhost",
+					port: 9999, // Non-existent port
+					secure: false,
+					user: "alice@mokapi.io",
+					credentials: { kind: "password", password: "alice123" },
+					connectionTimeout: 1000, // Short timeout for tests
+				};
+
+				const message = createTestMessage();
+				const result = await sendMail(badConfig, message);
+
+				assert.equal(result.success, false, "Send should fail");
+				assert.ok(result.error, "Should return an error");
+				// Connection errors are typically transient
+				assert.equal(
+					result.isTransient,
+					false,
+					"Connection errors without SMTP code are not transient",
+				);
+			});
+
+			test("handles authentication failure", async () => {
+				const badAuthConfig: SmtpConfig = {
+					host: "localhost",
+					port: 2525,
+					secure: false,
+					user: "alice@mokapi.io",
+					credentials: { kind: "password", password: "wrong-password" },
+					tls: {
+						rejectUnauthorized: false,
+					},
+					connectionTimeout: 5000,
+				};
+
+				const message = createTestMessage();
+				const result = await sendMail(badAuthConfig, message);
+
+				// mokapi may or may not enforce authentication
+				// If it does, this should fail; if not, it will succeed
+				if (!result.success) {
+					assert.ok(result.error, "Should return an error");
+					// 5xx errors are permanent (not transient)
+					if (result.smtpCode && result.smtpCode >= 500) {
+						assert.equal(
+							result.isTransient,
+							false,
+							"Auth failure should be permanent",
+						);
+					}
+				}
+			});
+		});
+	},
+);

package/src/smtp-client.ts

@@ -0,0 +1,194 @@
+import nodemailer from "nodemailer";
+import type { MailMessage } from "./message-builder.js";
+
+/**
+ * Discriminated union of SMTP authentication credentials.
+ *
+ * Mirrors MailCredentials in remit-mailbox-service. Defined here to avoid a
+ * cross-package dependency — smtp-service does not depend on mailbox-service.
+ */
+export type SmtpCredentials =
+	| { kind: "password"; password: string }
+	| { kind: "accessToken"; accessToken: string };
+
+/**
+ * Classification of SMTP connection / send errors.
+ */
+export type SmtpErrorKind = "auth" | "network";
+
+/**
+ * Typed error for SMTP authentication and network failures.
+ *
+ * IMPORTANT: access tokens must NEVER appear in error messages.
+ */
+export class SmtpConnectionError extends Error {
+	readonly kind: SmtpErrorKind;
+
+	constructor(kind: SmtpErrorKind, message: string, cause?: unknown) {
+		super(message, { cause });
+		this.name = "SmtpConnectionError";
+		this.kind = kind;
+	}
+}
+
+/** Password-based SMTP auth (AUTH PLAIN/LOGIN) */
+export interface SmtpAuthPassword {
+	type?: undefined;
+	user: string;
+	pass: string;
+}
+
+/** OAuth2 SMTP auth (XOAUTH2 / OAUTHBEARER) */
+export interface SmtpAuthOAuth2 {
+	type: "OAUTH2";
+	user: string;
+	accessToken: string;
+}
+
+export type SmtpAuth = SmtpAuthPassword | SmtpAuthOAuth2;
+
+export interface SmtpConfig {
+	host: string;
+	port: number;
+	secure: boolean; // true for TLS (465), false for STARTTLS (587)
+	credentials: SmtpCredentials;
+	user: string;
+	tls?: {
+		rejectUnauthorized?: boolean; // false to accept self-signed certs (testing only)
+	};
+	connectionTimeout?: number; // milliseconds, default 30000
+}
+
+export interface SendResult {
+	success: boolean;
+	messageId?: string;
+	response?: string;
+	error?: Error;
+	smtpCode?: number;
+	isTransient: boolean;
+}
+
+/**
+ * Build nodemailer auth from SmtpCredentials.
+ * IMPORTANT: never include accessToken values in error messages.
+ */
+const buildSmtpAuth = (
+	user: string,
+	credentials: SmtpCredentials,
+):
+	| { user: string; pass: string }
+	| { type: "OAuth2"; user: string; accessToken: string } => {
+	if (credentials.kind === "password") {
+		return { user, pass: credentials.password };
+	}
+	if (credentials.kind === "accessToken") {
+		return {
+			type: "OAuth2" as const,
+			user,
+			accessToken: credentials.accessToken,
+		};
+	}
+	// Exhaustiveness check — fails to compile if a new credential kind is added
+	// without handling it here.
+	const _exhaustive: never = credentials;
+	throw new Error(`Unknown credential kind: ${JSON.stringify(_exhaustive)}`);
+};
+
+/**
+ * Send email via SMTP using Nodemailer
+ */
+export const sendMail = async (
+	config: SmtpConfig,
+	message: MailMessage,
+): Promise<SendResult> => {
+	const timeout = config.connectionTimeout ?? 30_000;
+	const transporter = nodemailer.createTransport({
+		host: config.host,
+		port: config.port,
+		secure: config.secure,
+		auth: buildSmtpAuth(config.user, config.credentials),
+		tls: config.tls,
+		connectionTimeout: timeout,
+		greetingTimeout: timeout,
+		socketTimeout: 300_000,
+	});
+
+	return transporter
+		.sendMail({
+			from: message.from,
+			to: message.to,
+			cc: message.cc,
+			bcc: message.bcc,
+			replyTo: message.replyTo,
+			subject: message.subject,
+			text: message.text,
+			html: message.html,
+			messageId: message.messageId,
+			inReplyTo: message.inReplyTo,
+			references: message.references,
+			attachments: message.attachments?.map((a) => ({
+				filename: a.filename,
+				content: a.content as Buffer,
+				contentType: a.contentType,
+				cid: a.cid,
+				contentDisposition: a.contentDisposition,
+			})),
+		})
+		.then((info) => ({
+			success: true,
+			messageId: info.messageId,
+			response: info.response,
+			isTransient: false,
+		}))
+		.catch(
+			(
+				error: Error & {
+					responseCode?: number;
+					code?: string;
+					command?: string;
+				},
+			) => {
+				const smtpCode = error.responseCode;
+
+				// Classify auth errors — EAUTH or 5xx on AUTH command
+				if (
+					error.code === "EAUTH" ||
+					(smtpCode !== undefined &&
+						smtpCode >= 500 &&
+						error.command === "AUTH")
+				) {
+					throw new SmtpConnectionError(
+						"auth",
+						"SMTP authentication failed",
+						error,
+					);
+				}
+
+				// Classify network errors
+				if (
+					error.code === "ECONNREFUSED" ||
+					error.code === "ETIMEDOUT" ||
+					error.code === "ENOTFOUND" ||
+					error.code === "ECONNRESET" ||
+					error.code === "EHOSTUNREACH"
+				) {
+					throw new SmtpConnectionError(
+						"network",
+						`SMTP connection failed: ${error.code}`,
+						error,
+					);
+				}
+
+				// 4xx = transient (retry), 5xx = permanent (no retry)
+				const isTransient =
+					smtpCode !== undefined && smtpCode >= 400 && smtpCode < 500;
+				return {
+					success: false,
+					error,
+					smtpCode,
+					isTransient,
+				};
+			},
+		)
+		.finally(() => transporter.close());
+};

package/src/smtp-credentials.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Unit tests for SmtpCredentials union and SmtpConnectionError.
+ *
+ * Covers:
+ * 1. Auth object construction — nodemailer 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 kind classification
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { inspect } from "node:util";
+import { SmtpConnectionError, type SmtpCredentials } from "./smtp-client.js";
+
+// ---------------------------------------------------------------------------
+// Helper: mirrors buildSmtpAuth in smtp-client.ts
+// ---------------------------------------------------------------------------
+
+type SmtpAuth =
+	| { user: string; pass: string }
+	| { type: "OAuth2"; user: string; accessToken: string };
+
+const buildSmtpAuth = (
+	user: string,
+	credentials: SmtpCredentials,
+): 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 — 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)}`);
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("SmtpCredentials — auth shape", () => {
+	it("password kind → { user, pass }", () => {
+		const creds: SmtpCredentials = { 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 for password auth");
+		assert.ok(!("accessToken" in auth), "no accessToken for password auth");
+	});
+
+	it("accessToken kind → { type: 'OAuth2', user, accessToken }", () => {
+		const token = "ya29.super-secret-token";
+		const creds: SmtpCredentials = { 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 for OAuth2 auth");
+	});
+});
+
+describe("SmtpConnectionError", () => {
+	it("stores kind='auth'", () => {
+		const err = new SmtpConnectionError("auth", "SMTP authentication failed");
+		assert.equal(err.kind, "auth");
+		assert.equal(err.name, "SmtpConnectionError");
+		assert.equal(err.message, "SMTP authentication failed");
+	});
+
+	it("stores kind='network'", () => {
+		const err = new SmtpConnectionError(
+			"network",
+			"SMTP connection failed: ECONNREFUSED",
+		);
+		assert.equal(err.kind, "network");
+	});
+
+	it("is instanceof Error", () => {
+		const err = new SmtpConnectionError("auth", "test");
+		assert.ok(err instanceof Error);
+		assert.ok(err instanceof SmtpConnectionError);
+	});
+
+	it("token-leak: accessToken must NOT appear in inspected SmtpConnectionError (incl. cause)", () => {
+		const secretToken = "ya29.A0ARrdaM_very_secret_smtp_token_67890";
+
+		// Reproduce what sendMail() does: classify a nodemailer EAUTH failure and
+		// attach the underlying error as `cause`. A realistic nodemailer auth
+		// error reports the failure without echoing the access token.
+		const underlyingError = Object.assign(
+			new Error("Invalid login: 535 5.7.8 Authentication credentials invalid"),
+			{ code: "EAUTH", responseCode: 535, command: "AUTH" },
+		);
+		const err = new SmtpConnectionError(
+			"auth",
+			"SMTP authentication failed",
+			underlyingError,
+		);
+
+		// 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),
+			`SmtpConnectionError must not contain the access token — got: ${serialized.slice(0, 200)}`,
+		);
+	});
+
+	it("token-leak: accessToken in cause does NOT bubble into error.message", () => {
+		const secretToken = "ya29.A0ARrdaM_very_secret_smtp_token_CAUSE";
+		const underlyingError = new Error(`AUTH PLAIN failed token=${secretToken}`);
+
+		const err = new SmtpConnectionError(
+			"auth",
+			"SMTP authentication failed",
+			underlyingError,
+		);
+
+		assert.ok(
+			!err.message.includes(secretToken),
+			"error.message must not contain the access token",
+		);
+	});
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"outDir": "dist"
+	},
+	"include": ["src/**/*"]
+}