@remit/mailbox-service 0.0.49 → 0.0.51

package/package.json

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

package/src/index.ts

@@ -197,6 +197,24 @@ export {
 	type SyncedMessage,
 	type SyncMessagesResult,
 } from "./message-sync.js";
+export {
+	type CompleteOutboxAttachmentInput,
+	type CompleteOutboxAttachmentOutcome,
+	type MintOutboxAttachmentInput,
+	type MintOutboxAttachmentOutcome,
+	OUTBOX_ATTACHMENT_MAX_COUNT,
+	OUTBOX_ATTACHMENT_MAX_TOTAL_BYTES,
+	type OutboxAttachmentConfig,
+	type OutboxAttachmentRejectionDetail,
+	type OutboxAttachmentRejectionReasonValue,
+	type OutboxAttachmentReservation,
+	OutboxAttachmentService,
+} from "./outbox-attachment.js";
+export {
+	FALLBACK_CONTENT_TYPE,
+	normalizeAttachmentContentType,
+	sanitizeAttachmentFilename,
+} from "./outbox-attachment-filename.js";
 export {
 	type CreateDraftInput,
 	type OutboxQueueConfig,

package/src/message-sync-changedsince.test.ts

@@ -14,7 +14,11 @@ import type {
 	UpdateMailboxInput,
 	UpdateThreadMessageInput,
 } from "@remit/data-ports";
-import { MailboxCursorState, MessageSystemFlag } from "@remit/domain-enums";
+import {
+	MailboxCursorState,
+	MessageKeywordFlag,
+	MessageSystemFlag,
+} from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
 import type { FlagPushService } from "./flag-push.js";
 import { FlagQueueService } from "./flag-queue.js";
@@ -112,6 +116,8 @@ interface Harness {
 	/** The canonical flag record after the round. */
 	flagStore: Set<string>;
 	messageFlagService: IMessageFlagRepository;
+	/** Method names invoked on the top-level address repository. */
+	addressCalls: string[];
 }
 
 const buildHarness = (options: HarnessOptions): Harness => {
@@ -241,12 +247,29 @@ const buildHarness = (options: HarnessOptions): Harness => {
 		},
 	} as unknown as IMessageFlagRepository;
 
+	// The existing-message path (applyChange -> applyServerFlags) never
+	// touches this repository. Recording every call, rather than leaving the
+	// stub as `{}`, is what makes "$Junk stays message state" an assertion
+	// instead of an assumption a future change could silently break.
+	const addressCalls: string[] = [];
+	const addressRepository = new Proxy(
+		{},
+		{
+			get:
+				(_target, prop: string) =>
+				(..._args: unknown[]) => {
+					addressCalls.push(prop);
+					throw new Error(`unexpected IAddressRepository.${prop} call`);
+				},
+		},
+	) as IAddressRepository;
+
 	const service = new MessageSyncService(
 		connectionFactory,
 		mailboxService,
 		{} as IMessageRepository,
 		{} as IEnvelopeRepository,
-		{} as IAddressRepository,
+		addressRepository,
 		threadMessageService,
 		logger,
 		unitOfWork,
@@ -263,6 +286,7 @@ const buildHarness = (options: HarnessOptions): Harness => {
 		errors,
 		flagStore,
 		messageFlagService,
+		addressCalls,
 	};
 };
 
@@ -603,6 +627,71 @@ describe("MessageSyncService CHANGEDSINCE path", () => {
 	});
 });
 
+// $Junk/$NotJunk mirroring (report-spam epic, message-state slice). This
+// mailbox is never remit-only — Apple Mail or another IMAP client is
+// routinely connected too — so a keyword another client set is message
+// state only. It must never become a standing rule about the sender.
+describe("MessageSyncService mirrors $Junk/$NotJunk keywords", () => {
+	it("mirrors a server-side $Junk into the canonical flag record", async () => {
+		const harness = buildHarness({
+			mailbox: mailbox(),
+			supportsCondstore: true,
+			changed: [serverMessage({ flags: [MessageKeywordFlag.Junk] })],
+			storedRows: [storedRow()],
+			storedFlags: [],
+		});
+
+		await syncOnce(harness);
+
+		assert.ok(harness.flagStore.has(MessageKeywordFlag.Junk));
+	});
+
+	it("mirrors a server-side $NotJunk into the canonical flag record", async () => {
+		const harness = buildHarness({
+			mailbox: mailbox(),
+			supportsCondstore: true,
+			changed: [serverMessage({ flags: [MessageKeywordFlag.NotJunk] })],
+			storedRows: [storedRow()],
+			storedFlags: [],
+		});
+
+		await syncOnce(harness);
+
+		assert.ok(harness.flagStore.has(MessageKeywordFlag.NotJunk));
+	});
+
+	it("leaves $Junk alone while its local flip is still owed to IMAP", async () => {
+		const harness = buildHarness({
+			mailbox: mailbox(),
+			supportsCondstore: true,
+			// Server has not seen the local flip yet.
+			changed: [serverMessage({ flags: [] })],
+			storedRows: [storedRow()],
+			storedFlags: [MessageKeywordFlag.Junk],
+			pendingFlags: new Set([MessageKeywordFlag.Junk]),
+		});
+
+		await syncOnce(harness);
+
+		assert.ok(harness.flagStore.has(MessageKeywordFlag.Junk));
+	});
+
+	it("mirroring $Junk leaves the sender's Address record completely untouched", async () => {
+		const harness = buildHarness({
+			mailbox: mailbox(),
+			supportsCondstore: true,
+			changed: [serverMessage({ flags: [MessageKeywordFlag.Junk] })],
+			storedRows: [storedRow()],
+			storedFlags: [],
+		});
+
+		await syncOnce(harness);
+
+		assert.ok(harness.flagStore.has(MessageKeywordFlag.Junk));
+		assert.deepEqual(harness.addressCalls, []);
+	});
+});
+
 describe("MessageSyncService without CONDSTORE", () => {
 	it("falls back to full enumeration and never issues CHANGEDSINCE", async () => {
 		const harness = buildHarness({

package/src/message-sync.ts

@@ -23,6 +23,7 @@ import {
 import {
 	AddressRole,
 	MailboxCursorState,
+	MessageKeywordFlag,
 	MessageSystemFlag,
 	StarColor,
 } from "@remit/domain-enums";
@@ -1025,8 +1026,9 @@ export class MessageSyncService {
 	}
 
 	/**
-	 * Bring a stored row's read and star state in line with the server's
-	 * flags.
+	 * Bring a stored row's read and star state, and the $Junk/$NotJunk
+	 * keywords on the canonical MessageFlag record, in line with the
+	 * server's flags.
 	 *
 	 * A field with a pending outbound push is left alone: the user flipped it
 	 * locally, IMAP has not been told yet, and the server's answer is
@@ -1073,6 +1075,17 @@ export class MessageSyncService {
 			}
 		}
 
+		await this.mirrorKeywordFlag(
+			existing.messageId,
+			MessageKeywordFlag.Junk,
+			flags,
+		);
+		await this.mirrorKeywordFlag(
+			existing.messageId,
+			MessageKeywordFlag.NotJunk,
+			flags,
+		);
+
 		if (Object.keys(updates).length === 0) return;
 
 		// MessageFlag is the canonical flag record — `FlagQueueService` reads it
@@ -1157,6 +1170,32 @@ export class MessageSyncService {
 		return marker !== null;
 	}
 
+	/**
+	 * Mirror one RFC 5788 keyword ($Junk / $NotJunk) from the server into the
+	 * canonical MessageFlag record, guarded the same way as the system flags:
+	 * a pending local push wins over the server's known-stale answer.
+	 *
+	 * This mailbox is never remit-only — Apple Mail or another IMAP client is
+	 * routinely connected too — so the keyword is message state, nothing
+	 * more. It never reaches the Address model: reading another client's
+	 * keyword as a standing rule about the sender is the exact fight this
+	 * mirror must not pick.
+	 */
+	private async mirrorKeywordFlag(
+		messageId: string,
+		flagName: string,
+		serverFlags: string[],
+	): Promise<void> {
+		if (!this.messageFlagService) return;
+		if (await this.hasPendingPush(messageId, flagName)) return;
+
+		const present = serverFlags.includes(flagName);
+		const hasFlag = await this.messageFlagService.hasFlag(messageId, flagName);
+		if (hasFlag === present) return;
+
+		await this.setMessageFlag(messageId, flagName, present);
+	}
+
 	/**
 	 * Fetch a batch of messages using the managed connection.
 	 * Assumes mailbox is already open from fetchUidsToSync.

package/src/outbox-attachment-filename.test.ts

@@ -0,0 +1,132 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	FALLBACK_CONTENT_TYPE,
+	normalizeAttachmentContentType,
+	sanitizeAttachmentFilename,
+} from "./outbox-attachment-filename.js";
+
+describe("sanitizeAttachmentFilename", () => {
+	it("keeps an ordinary name, accents and spaces included", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("Facture décembre 2026.pdf"),
+			"Facture décembre 2026.pdf",
+		);
+	});
+
+	it("keeps only the basename of a traversal attempt", () => {
+		assert.equal(sanitizeAttachmentFilename("../../../etc/passwd"), "passwd");
+	});
+
+	it("keeps only the basename of a windows path", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("C:\\Users\\me\\Desktop\\report.xlsx"),
+			"report.xlsx",
+		);
+	});
+
+	it("strips the bidi override that disguises an extension", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("invoice\u202Egnp.exe"),
+			"invoicegnp.exe",
+		);
+	});
+
+	it("strips control characters that would break a header", () => {
+		assert.equal(
+			sanitizeAttachmentFilename("report\r\nBcc: someone@example.com.pdf"),
+			"reportBcc: someone@example.com.pdf",
+		);
+	});
+
+	it("refuses a name that is nothing but separators and dots", () => {
+		assert.equal(sanitizeAttachmentFilename("../.."), null);
+		assert.equal(sanitizeAttachmentFilename("."), null);
+		assert.equal(sanitizeAttachmentFilename("   "), null);
+		assert.equal(sanitizeAttachmentFilename("\u202A\u202B"), null);
+	});
+
+	it("truncates an overlong name but keeps its extension", () => {
+		const sanitized = sanitizeAttachmentFilename(`${"a".repeat(500)}.pdf`);
+		assert.ok(sanitized !== null);
+		assert.ok(sanitized.length <= 200);
+		assert.ok(sanitized.endsWith(".pdf"));
+	});
+
+	it("never cuts an emoji in half when it truncates", () => {
+		const sanitized = sanitizeAttachmentFilename(
+			`${"a".repeat(195)}\u{1F600}x.pdf`,
+		);
+		assert.ok(sanitized !== null);
+		assert.equal(
+			[...sanitized].some((character) => {
+				const code = character.charCodeAt(0);
+				return code >= 0xd800 && code <= 0xdfff && character.length === 1;
+			}),
+			false,
+		);
+		assert.equal(Buffer.from(sanitized, "utf8").includes("\uFFFD"), false);
+		assert.ok(sanitized.endsWith(".pdf"));
+	});
+
+	it("truncates a name whose trailing dot-segment is not a plausible extension", () => {
+		const sanitized = sanitizeAttachmentFilename(
+			`${"a".repeat(300)}.${"b".repeat(300)}`,
+		);
+		assert.ok(sanitized !== null);
+		assert.equal(sanitized.length, 200);
+	});
+});
+
+describe("normalizeAttachmentContentType", () => {
+	it("lowercases a media type and drops its parameters", () => {
+		assert.equal(
+			normalizeAttachmentContentType("TEXT/Plain; charset=utf-8"),
+			"text/plain",
+		);
+	});
+
+	it("passes an archive through — the receiving server decides what it takes", () => {
+		assert.equal(
+			normalizeAttachmentContentType("application/zip"),
+			"application/zip",
+		);
+	});
+
+	it("falls back when the browser sent nothing", () => {
+		assert.equal(normalizeAttachmentContentType(""), FALLBACK_CONTENT_TYPE);
+	});
+
+	it("falls back on a token long enough to overflow the field it lands in", () => {
+		assert.equal(
+			normalizeAttachmentContentType(`application/${"x".repeat(300)}`),
+			FALLBACK_CONTENT_TYPE,
+		);
+	});
+
+	it("falls back on a value that is not a media type", () => {
+		assert.equal(
+			normalizeAttachmentContentType("text/html<script>"),
+			FALLBACK_CONTENT_TYPE,
+		);
+		assert.equal(
+			normalizeAttachmentContentType("not-a-media-type"),
+			FALLBACK_CONTENT_TYPE,
+		);
+	});
+});
+
+describe("a filename that hides its separators behind control characters", () => {
+	it("takes the basename after the newline, not before it", () => {
+		// `.` does not match a newline, so a basename strip that runs first stops
+		// at it and leaves every separator that follows.
+		assert.equal(
+			sanitizeAttachmentFilename("report\r\n/../../.bashrc"),
+			"bashrc",
+		);
+	});
+
+	it("leaves nothing usable when the whole name is separators and a newline", () => {
+		assert.equal(sanitizeAttachmentFilename("..\n/../x.png"), "x.png");
+	});
+});

package/src/outbox-attachment-filename.ts

@@ -0,0 +1,76 @@
+/**
+ * A filename arrives from a browser's `File.name` and reaches a
+ * `Content-Disposition` header on a message a stranger opens. Nothing in the
+ * middle re-derives it, and the storage key never contains it — the key is a
+ * generated id — so this is the one place the value is made safe.
+ */
+
+const PATH_SEPARATORS = /^.*[\\/]/;
+
+// C0/C1 controls and DEL, then the bidi and directional-isolate formatting
+// characters that let a name ending in "exe" render as if it ended in "png".
+const UNSAFE_CHARACTERS =
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point
+	/[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
+
+const MAX_FILENAME_LENGTH = 200;
+
+// By code point, never by UTF-16 unit: cutting mid-surrogate leaves a lone half
+// that a Content-Disposition encoder can only render as U+FFFD.
+const truncateCodePoints = (value: string, limit: number): string =>
+	Array.from(value).slice(0, limit).join("");
+
+const truncateKeepingExtension = (filename: string): string => {
+	const codePoints = Array.from(filename);
+	if (codePoints.length <= MAX_FILENAME_LENGTH) return filename;
+
+	const dot = filename.lastIndexOf(".");
+	const extension = dot > 0 ? Array.from(filename.slice(dot)) : [];
+	if (extension.length === 0 || extension.length > 16) {
+		return truncateCodePoints(filename, MAX_FILENAME_LENGTH);
+	}
+	return (
+		truncateCodePoints(filename, MAX_FILENAME_LENGTH - extension.length) +
+		extension.join("")
+	);
+};
+
+/**
+ * The filename to record, or null when nothing usable survives — a name made
+ * only of separators, dots or control characters is refused rather than
+ * replaced with something invented.
+ */
+export const sanitizeAttachmentFilename = (raw: string): string | null => {
+	// Strip first, then take the basename. The other order is bypassable: `.`
+	// does not match a newline, so `PATH_SEPARATORS` stops at one and leaves
+	// every separator after it — "report\r\n/../../.bashrc" survives with its
+	// slashes intact.
+	const stripped = raw.replace(UNSAFE_CHARACTERS, "");
+	const basename = stripped.replace(PATH_SEPARATORS, "").trim();
+	const trimmed = basename.replace(/^\.+/, "").trim();
+
+	if (trimmed.length === 0) return null;
+
+	return truncateKeepingExtension(trimmed);
+};
+
+// RFC 9110 token characters, on both sides of the one slash.
+const MEDIA_TYPE = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+\/[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+
+export const FALLBACK_CONTENT_TYPE = "application/octet-stream";
+
+// The longest registered media type is well under this. A token run past it is
+// a client inventing one, and it would overflow the response field it lands in.
+const MAX_CONTENT_TYPE_LENGTH = 127;
+
+/**
+ * The media type to record. Parameters (`; charset=…`) are dropped and anything
+ * that is not a bare type/subtype becomes the fallback: the value is recorded
+ * for the outgoing MIME part, never trusted for rendering.
+ */
+export const normalizeAttachmentContentType = (raw: string): string => {
+	const bare = raw.split(";")[0].trim().toLowerCase();
+	if (bare.length > MAX_CONTENT_TYPE_LENGTH) return FALLBACK_CONTENT_TYPE;
+	if (!MEDIA_TYPE.test(bare)) return FALLBACK_CONTENT_TYPE;
+	return bare;
+};