@remit/data-ports 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -31,7 +31,8 @@
     }
   },
   "scripts": {
-    "test:typecheck": "tsgo --noEmit"
+    "test:typecheck": "tsgo --noEmit",
+    "test:run": "node --import tsx --test 'src/**/*.test.ts'"
   },
   "dependencies": {
     "@remit/domain-enums": "*",

package/src/id.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { deriveQuarantineId, quarantineMessageIdHash } from "./id.js";
+
+const ACCOUNT = "acct-1";
+const MAILBOX = "mbx-1";
+
+describe("deriveQuarantineId", () => {
+	it("is stable for the same message", () => {
+		assert.equal(
+			deriveQuarantineId(ACCOUNT, MAILBOX, 1_700_000_000, 40217),
+			deriveQuarantineId(ACCOUNT, MAILBOX, 1_700_000_000, 40217),
+		);
+	});
+
+	it("separates the same uid across a UIDVALIDITY bump", () => {
+		// A mailbox keeps its mailboxId when the server bumps UIDVALIDITY, so
+		// without this the stale entry would name the new message and suppress
+		// it from a sync round — losing mail rather than a diagnostic.
+		assert.notEqual(
+			deriveQuarantineId(ACCOUNT, MAILBOX, 1_700_000_000, 40217),
+			deriveQuarantineId(ACCOUNT, MAILBOX, 1_700_000_001, 40217),
+		);
+	});
+
+	it("separates mailboxes and accounts", () => {
+		const base = deriveQuarantineId(ACCOUNT, MAILBOX, 1, 40217);
+		assert.notEqual(base, deriveQuarantineId(ACCOUNT, "mbx-2", 1, 40217));
+		assert.notEqual(base, deriveQuarantineId("acct-2", MAILBOX, 1, 40217));
+	});
+});
+
+describe("quarantineMessageIdHash", () => {
+	it("hashes a real Message-ID to a pinned sha256 value", () => {
+		const hash = quarantineMessageIdHash("<abc@example.com>");
+		assert.match(hash ?? "", /^sha256:[0-9a-f]{64}$/);
+		assert.equal(hash, quarantineMessageIdHash("<abc@example.com>"));
+	});
+
+	it("distinguishes different Message-IDs", () => {
+		assert.notEqual(
+			quarantineMessageIdHash("<a@example.com>"),
+			quarantineMessageIdHash("<b@example.com>"),
+		);
+	});
+
+	it("refuses to hash a Message-ID the sync path never had", () => {
+		// The sync path coerces a missing Message-ID to "". Hashing that would
+		// give every such message one shared hash and correlate unrelated
+		// reports — the opposite of what the field is for.
+		for (const absent of [undefined, "", "   ", "<>"]) {
+			assert.equal(quarantineMessageIdHash(absent), undefined);
+		}
+	});
+});

package/src/id.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import shortUuid from "short-uuid";
 import { v5 as uuidv5 } from "uuid";
 import type { MessageIdSource } from "./types.js";
@@ -103,3 +104,45 @@ export const deriveBodyPartParameterId = (
 		`bodypartparam:${messageId}:${partPath}:${parameterName.toLowerCase()}`,
 		REMIT_NAMESPACE,
 	);
+
+/**
+ * Identity of a quarantined message (issue #72). Derived rather than generated
+ * so re-quarantining the same message rewrites its own row: the sync path can
+ * write without first checking whether an entry already exists.
+ *
+ * `uidValidity` is part of the name because a uid alone does not identify a
+ * message — only uidValidity + uid does, forever (RFC 9051 2.3.1.1). A mailbox
+ * keeps its `mailboxId` across a UIDVALIDITY bump (the sync path updates the
+ * same row), so without this a stale entry would derive the same id as a later,
+ * unrelated message and suppress it from a sync round.
+ */
+export const deriveQuarantineId = (
+	accountId: string,
+	mailboxId: string,
+	uidValidity: number,
+	uid: number,
+): string =>
+	base36uuidv5(
+		`quarantine:${accountId}:${mailboxId}:${uidValidity}:${uid}`,
+		REMIT_NAMESPACE,
+	);
+
+/**
+ * The `sha256:`-prefixed Message-ID hash a quarantine record carries, or
+ * undefined when the message declared no usable Message-ID.
+ *
+ * The sync path coerces a missing Message-ID to `""`, and hashing that would
+ * give every Message-ID-less message the same hash — so the one field whose
+ * purpose is correlating reports of the same message would silently correlate
+ * unrelated ones. Absent is the honest value, and this is the only way the
+ * value is produced, so the empty hash cannot be written by accident.
+ */
+export const quarantineMessageIdHash = (
+	messageIdHeader: string | undefined,
+): string | undefined => {
+	if (!messageIdHeader || !isValidMessageId(messageIdHeader)) return undefined;
+	const digest = createHash("sha256")
+		.update(messageIdHeader.trim())
+		.digest("hex");
+	return `sha256:${digest}`;
+};

package/src/index.ts

@@ -17,6 +17,7 @@ export type { IMessageLabelRepository } from "./interfaces/message-label.js";
 export type { IMessagePlacementMoveRepository } from "./interfaces/message-placement-move.js";
 export type { IOrganizeJobRequestRepository } from "./interfaces/organize-job-request.js";
 export type { IOutboxMessageRepository } from "./interfaces/outbox-message.js";
+export type { IQuarantineRepository } from "./interfaces/quarantine.js";
 export type { IThreadMessageRepository } from "./interfaces/thread-message.js";
 export type {
 	IUnitOfWork,
@@ -80,6 +81,8 @@ export type {
 	OutboxMessageItem,
 	PutMessageFlagPushInput,
 	PutMessagePlacementMoveInput,
+	QuarantineItem,
+	QuarantineMimeNodeItem,
 	RawMessageStorageItem,
 	ResultList,
 	SearchOptions,

package/src/interfaces/quarantine.ts

@@ -0,0 +1,10 @@
+import type { QuarantineItem } from "../types.js";
+
+export interface IQuarantineRepository {
+	/**
+	 * Every quarantined message for one user, newest first. Unpaginated: the
+	 * list is small by design, and it is read whole both by the settings
+	 * surface and by a sync round that keeps it in memory.
+	 */
+	listByAccountConfigId(accountConfigId: string): Promise<QuarantineItem[]>;
+}

package/src/types.ts

@@ -22,6 +22,7 @@ import type {
 	MessageSchema,
 	OrganizeJobRequestSchema,
 	OutboxMessageSchema,
+	QuarantineSchema,
 	RawMessageStorageSchema,
 	ThreadMessageSchema,
 } from "@remit/api-zod-schemas";
@@ -85,6 +86,8 @@ export type MessagePlacementMoveItem = z.infer<
 	typeof MessagePlacementMoveSchema
 >;
 export type MessageFlagPushItem = z.infer<typeof MessageFlagPushSchema>;
+export type QuarantineItem = z.infer<typeof QuarantineSchema>;
+export type QuarantineMimeNodeItem = QuarantineItem["structure"][number];
 
 export type MailboxSpecialUseValue = z.infer<typeof MailboxSpecialUseSchema>;