@remit/account-worker 0.0.1

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@remit/account-worker",
+	"version": "0.0.1",
+	"type": "module",
+	"main": "dist/index.js",
+	"scripts": {
+		"bundle": "esbuild src/index.ts --sourcemap --bundle --platform=node --format=esm --outfile=dist/index.js",
+		"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"
+	},
+	"devDependencies": {
+		"@aws-sdk/client-cloudfront": "*",
+		"@aws-sdk/client-cognito-identity-provider": "*",
+		"@aws-sdk/client-dynamodb": "*",
+		"@aws-sdk/client-s3": "*",
+		"@aws-sdk/client-sqs": "*",
+		"@aws-sdk/core": "*",
+		"@aws-sdk/lib-dynamodb": "*",
+		"@aws-sdk/lib-storage": "*",
+		"@aws-sdk/s3-request-presigner": "*",
+		"@remit/backend": "*",
+		"@remit/data-ports": "*",
+		"@remit/electrodb-entities": "*",
+		"@remit/drizzle-service": "*",
+		"@remit/domain-enums": "*",
+		"@remit/logger-lambda": "*",
+		"@remit/search-index-worker": "*",
+		"@remit/search-service": "*",
+		"@remit/sqs-client": "*",
+		"@remit/storage-service": "*",
+		"@types/archiver": "*",
+		"@types/aws-lambda": "*",
+		"archiver": "*",
+		"aws-sdk-client-mock": "*",
+		"electrodb": "*",
+		"esbuild": "^0.27.7",
+		"expect-env": "*",
+		"p-map": "*"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/remit-mail/remit.git",
+		"directory": "packages/account-worker"
+	}
+}

package/src/cascade.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, it } from "node:test";
+import { COVERED_ENTITY_TYPES } from "./cascade.js";
+
+// The snapshot enumerates electrodb-service's models; that package is stripped
+// from the open-core tree, so the check skips there and runs where it ships.
+const modelsDir = resolve(
+	import.meta.dirname,
+	"../../remit-electrodb-service/src/models",
+);
+
+describe("cascade entity coverage snapshot", () => {
+	it(
+		"covers every entity model in remit-electrodb-service",
+		{ skip: !existsSync(modelsDir) },
+		() => {
+			const modelFiles = readdirSync(modelsDir)
+				.filter(
+					(f) =>
+						f.endsWith(".ts") && !f.endsWith(".test.ts") && f !== "index.ts",
+				)
+				.map((f) => f.replace(".ts", ""));
+
+			// Map model file names to the entity types they contain
+			const entityTypesByFile: Record<string, string[]> = {
+				"account-config": ["AccountConfig"],
+				"account-export-request": [],
+				"account-setting": ["AccountSetting"],
+				"account-setting-registry": [],
+				account: ["Account"],
+				address: ["Address", "EnvelopeAddress"],
+				envelope: [
+					"Envelope",
+					"MessageReference",
+					"BodyPart",
+					"BodyPartParameter",
+					"RawMessageStorage",
+					"BodyPartStorage",
+					"BodyPartContent",
+				],
+				filter: ["Filter"],
+				"filter-anchor": ["FilterAnchor"],
+				label: ["Label"],
+				mailbox: ["Mailbox"],
+				"mailbox-lock": ["MailboxLock"],
+				"mailbox-special-use": [],
+				message: ["Message"],
+				"message-flag": ["MessageFlag"],
+				"message-flag-push": ["MessageFlagPush"],
+				"message-label": ["MessageLabel"],
+				"message-placement-move": ["MessagePlacementMove"],
+				"organize-job-request": [],
+				"outbox-message": ["OutboxMessage"],
+				"thread-message": ["ThreadMessage"],
+				"wellknown-rule": [],
+			};
+
+			const allEntityTypes = Object.values(entityTypesByFile).flat().sort();
+			const coveredSorted = [...COVERED_ENTITY_TYPES].sort();
+
+			assert.deepStrictEqual(
+				coveredSorted,
+				allEntityTypes,
+				`Cascade does not cover all entity types.\n` +
+					`Missing: ${allEntityTypes.filter((t) => !(coveredSorted as readonly string[]).includes(t)).join(", ")}\n` +
+					`Extra: ${(coveredSorted as readonly string[]).filter((t) => !allEntityTypes.includes(t)).join(", ")}`,
+			);
+
+			// Verify all model files are accounted for
+			const unmappedFiles = modelFiles.filter((f) => !(f in entityTypesByFile));
+			assert.deepStrictEqual(
+				unmappedFiles,
+				[],
+				`Model files not mapped to entity types: ${unmappedFiles.join(", ")}`,
+			);
+		},
+	);
+});

package/src/cascade.ts

@@ -0,0 +1,383 @@
+import type {
+	IAccountConfigRepository,
+	IAccountExportRequestRepository,
+	IAccountRepository,
+	IAccountSettingRepository,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IFilterAnchorRepository,
+	IFilterRepository,
+	ILabelRepository,
+	IMailboxLockRepository,
+	IMailboxRepository,
+	IMessageFlagPushRepository,
+	IMessageFlagRepository,
+	IMessageLabelRepository,
+	IMessagePlacementMoveRepository,
+	IMessageRepository,
+	IOutboxMessageRepository,
+	IThreadMessageRepository,
+	MessageDescription,
+} from "@remit/data-ports";
+import type { Logger } from "@remit/logger-lambda";
+
+export interface CascadeEntity {
+	entityType: string;
+	key: Record<string, string>;
+}
+
+export interface CascadeServices {
+	accountConfigService: IAccountConfigRepository;
+	accountService: IAccountRepository;
+	addressService: IAddressRepository;
+	mailboxService: IMailboxRepository;
+	messageService: IMessageRepository;
+	messageFlagService: IMessageFlagRepository;
+	envelopeService: IEnvelopeRepository;
+	outboxMessageService: IOutboxMessageRepository;
+	threadMessageService: IThreadMessageRepository;
+	mailboxLockService: IMailboxLockRepository;
+	messagePlacementMoveService: IMessagePlacementMoveRepository;
+	messageFlagPushService: IMessageFlagPushRepository;
+	accountExportRequestService: IAccountExportRequestRepository;
+	accountSettingService: IAccountSettingRepository;
+	filterService: IFilterRepository;
+	filterAnchorService: IFilterAnchorRepository;
+	labelService: ILabelRepository;
+	messageLabelService: IMessageLabelRepository;
+}
+
+export interface CascadeResult {
+	entities: CascadeEntity[];
+	messageIds: string[];
+}
+
+/**
+ * Expand one message's 9 child entities (flags, envelope, addresses, body
+ * parts, references, raw/body storage) into the cascade plan. The Message row
+ * itself is pushed by the caller — this only collects the children that a
+ * `describe()` reveals. Shared by the tenant cascade enumerator and the
+ * per-account purge worker.
+ */
+export const collectMessageChildEntities = (
+	entities: CascadeEntity[],
+	messageData: MessageDescription,
+): void => {
+	for (const flag of messageData.messageFlag) {
+		entities.push({
+			entityType: "MessageFlag",
+			key: { messageFlagId: flag.messageFlagId },
+		});
+	}
+	for (const envelope of messageData.envelope) {
+		entities.push({
+			entityType: "Envelope",
+			key: { envelopeId: envelope.envelopeId },
+		});
+	}
+	for (const ref of messageData.messageReference) {
+		entities.push({
+			entityType: "MessageReference",
+			key: { messageReferenceId: ref.messageReferenceId },
+		});
+	}
+	for (const addr of messageData.envelopeAddress) {
+		entities.push({
+			entityType: "EnvelopeAddress",
+			key: { envelopeAddressId: addr.envelopeAddressId },
+		});
+	}
+	for (const bp of messageData.bodyPart) {
+		entities.push({
+			entityType: "BodyPart",
+			key: { bodyPartId: bp.bodyPartId },
+		});
+	}
+	for (const bpp of messageData.bodyPartParameter) {
+		entities.push({
+			entityType: "BodyPartParameter",
+			key: { bodyPartParameterId: bpp.bodyPartParameterId },
+		});
+	}
+	for (const rms of messageData.rawMessageStorage) {
+		entities.push({
+			entityType: "RawMessageStorage",
+			key: { rawStorageId: rms.rawStorageId },
+		});
+	}
+	for (const bps of messageData.bodyPartStorage) {
+		entities.push({
+			entityType: "BodyPartStorage",
+			key: { bodyPartStorageId: bps.bodyPartStorageId },
+		});
+	}
+	for (const bpc of messageData.bodyPartContent) {
+		entities.push({
+			entityType: "BodyPartContent",
+			key: { bodyPartContentId: bpc.bodyPartContentId },
+		});
+	}
+};
+
+export const enumerateCascadeEntities = async (
+	accountConfigId: string,
+	services: CascadeServices,
+	log: Logger,
+): Promise<CascadeResult> => {
+	const entities: CascadeEntity[] = [];
+	const messageIds: string[] = [];
+
+	const {
+		accountConfigService,
+		accountService,
+		messageService,
+		outboxMessageService,
+		threadMessageService,
+		mailboxLockService,
+		messagePlacementMoveService,
+		messageFlagPushService,
+		accountSettingService,
+		filterService,
+		filterAnchorService,
+		labelService,
+		messageLabelService,
+	} = services;
+
+	const description = await accountConfigService.describe(accountConfigId);
+
+	for (const account of description.account) {
+		entities.push({
+			entityType: "Account",
+			key: { accountId: account.accountId },
+		});
+
+		const accountDescription = await accountService.describe(account.accountId);
+
+		for (const mailbox of accountDescription.mailbox) {
+			entities.push({
+				entityType: "Mailbox",
+				key: { mailboxId: mailbox.mailboxId },
+			});
+
+			const messages = await messageService.listAllByMailbox(mailbox.mailboxId);
+
+			for (const message of messages) {
+				messageIds.push(message.messageId);
+				entities.push({
+					entityType: "Message",
+					key: { messageId: message.messageId },
+				});
+
+				const messageData = await messageService.describe(message.messageId);
+
+				for (const flag of messageData.messageFlag) {
+					entities.push({
+						entityType: "MessageFlag",
+						key: { messageFlagId: flag.messageFlagId },
+					});
+				}
+
+				for (const envelope of messageData.envelope) {
+					entities.push({
+						entityType: "Envelope",
+						key: { envelopeId: envelope.envelopeId },
+					});
+				}
+
+				for (const ref of messageData.messageReference) {
+					entities.push({
+						entityType: "MessageReference",
+						key: { messageReferenceId: ref.messageReferenceId },
+					});
+				}
+
+				for (const addr of messageData.envelopeAddress) {
+					entities.push({
+						entityType: "EnvelopeAddress",
+						key: { envelopeAddressId: addr.envelopeAddressId },
+					});
+				}
+
+				for (const bp of messageData.bodyPart) {
+					entities.push({
+						entityType: "BodyPart",
+						key: { bodyPartId: bp.bodyPartId },
+					});
+				}
+
+				for (const bpp of messageData.bodyPartParameter) {
+					entities.push({
+						entityType: "BodyPartParameter",
+						key: { bodyPartParameterId: bpp.bodyPartParameterId },
+					});
+				}
+
+				for (const rms of messageData.rawMessageStorage) {
+					entities.push({
+						entityType: "RawMessageStorage",
+						key: { rawStorageId: rms.rawStorageId },
+					});
+				}
+
+				for (const bps of messageData.bodyPartStorage) {
+					entities.push({
+						entityType: "BodyPartStorage",
+						key: { bodyPartStorageId: bps.bodyPartStorageId },
+					});
+				}
+
+				for (const bpc of messageData.bodyPartContent) {
+					entities.push({
+						entityType: "BodyPartContent",
+						key: { bodyPartContentId: bpc.bodyPartContentId },
+					});
+				}
+			}
+		}
+
+		const outboxMessages = await outboxMessageService.listByAccount(
+			account.accountId,
+		);
+		for (const outbox of outboxMessages.items) {
+			entities.push({
+				entityType: "OutboxMessage",
+				key: { outboxMessageId: outbox.outboxMessageId },
+			});
+		}
+
+		const locks = await mailboxLockService.listByAccount(account.accountId);
+		for (const lock of locks) {
+			entities.push({
+				entityType: "MailboxLock",
+				key: { mailboxId: lock.mailboxId, eventName: lock.eventName },
+			});
+		}
+
+		const placementMoves = await messagePlacementMoveService.listByAccountId(
+			account.accountId,
+		);
+		for (const move of placementMoves) {
+			entities.push({
+				entityType: "MessagePlacementMove",
+				key: { messageId: move.messageId },
+			});
+		}
+
+		const flagPushes = await messageFlagPushService.listByAccountId(
+			account.accountId,
+		);
+		for (const push of flagPushes) {
+			entities.push({
+				entityType: "MessageFlagPush",
+				key: { messageId: push.messageId, flagName: push.flagName },
+			});
+		}
+	}
+
+	const threadMessages =
+		await threadMessageService.listAllByAccount(accountConfigId);
+	for (const tm of threadMessages) {
+		entities.push({
+			entityType: "ThreadMessage",
+			key: { accountConfigId, threadMessageId: tm.threadMessageId },
+		});
+	}
+
+	const accountSettings =
+		await accountSettingService.listByAccountConfig(accountConfigId);
+	for (const setting of accountSettings) {
+		entities.push({
+			entityType: "AccountSetting",
+			key: { accountSettingId: setting.accountSettingId },
+		});
+	}
+
+	// Filter/FilterAnchor/Label/MessageLabel are accountConfig-scoped (RFC 034),
+	// not per sub-account, so — like AccountSetting and ThreadMessage above —
+	// they are enumerated once here rather than inside the per-account loop.
+	const filters = await filterService.listByAccountConfig(accountConfigId);
+	for (const filter of filters) {
+		entities.push({
+			entityType: "Filter",
+			key: { accountConfigId, filterId: filter.filterId },
+		});
+		if (!filter.hasAnchor) continue;
+		const anchor = await filterAnchorService.get(
+			accountConfigId,
+			filter.filterId,
+		);
+		if (!anchor) continue;
+		entities.push({
+			entityType: "FilterAnchor",
+			key: { accountConfigId, filterId: filter.filterId },
+		});
+	}
+
+	const labels = await labelService.listByAccountConfig(accountConfigId);
+	for (const label of labels) {
+		entities.push({
+			entityType: "Label",
+			key: { accountConfigId, labelId: label.labelId },
+		});
+		const messageLabels = await messageLabelService.listByLabelId(
+			accountConfigId,
+			label.labelId,
+		);
+		for (const messageLabel of messageLabels) {
+			entities.push({
+				entityType: "MessageLabel",
+				key: { messageLabelId: messageLabel.messageLabelId },
+			});
+		}
+	}
+
+	for (const address of description.address) {
+		entities.push({
+			entityType: "Address",
+			key: { addressId: address.addressId },
+		});
+	}
+
+	entities.push({
+		entityType: "AccountConfig",
+		key: { accountConfigId },
+	});
+
+	log.info(
+		{
+			accountConfigId,
+			entityCount: entities.length,
+			messageCount: messageIds.length,
+		},
+		"Cascade enumeration complete",
+	);
+
+	return { entities, messageIds };
+};
+
+export const COVERED_ENTITY_TYPES = [
+	"Account",
+	"AccountConfig",
+	"AccountSetting",
+	"Address",
+	"BodyPart",
+	"BodyPartContent",
+	"BodyPartParameter",
+	"BodyPartStorage",
+	"Envelope",
+	"EnvelopeAddress",
+	"Filter",
+	"FilterAnchor",
+	"Label",
+	"Mailbox",
+	"MailboxLock",
+	"Message",
+	"MessageFlag",
+	"MessageFlagPush",
+	"MessageLabel",
+	"MessagePlacementMove",
+	"MessageReference",
+	"OutboxMessage",
+	"RawMessageStorage",
+	"ThreadMessage",
+] as const;

package/src/compose-relational.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import type { Logger } from "@remit/logger-lambda";
+import { buildRelationalDeletionCapabilities } from "./compose-relational.js";
+
+const noopLog = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	fatal: () => {},
+	trace: () => {},
+	child: () => noopLog,
+} as unknown as Logger;
+
+const exists = (path: string): Promise<boolean> =>
+	stat(path)
+		.then(() => true)
+		.catch(() => false);
+
+const writeUnder = async (base: string, key: string): Promise<string> => {
+	const full = join(base, key);
+	await mkdir(dirname(full), { recursive: true });
+	await writeFile(full, "x");
+	return full;
+};
+
+describe("relational deletion capabilities — filesystem storage cleanup", () => {
+	let base: string;
+	const prevStoragePath = process.env.STORAGE_LOCAL_PATH;
+
+	beforeEach(async () => {
+		base = await mkdtemp(join(tmpdir(), "remit-relational-storage-"));
+		process.env.STORAGE_LOCAL_PATH = base;
+	});
+
+	afterEach(() => {
+		if (prevStoragePath === undefined) delete process.env.STORAGE_LOCAL_PATH;
+		else process.env.STORAGE_LOCAL_PATH = prevStoragePath;
+	});
+
+	it("removes every object under the account prefix, leaving siblings intact", async () => {
+		const caps = buildRelationalDeletionCapabilities();
+
+		const deleted = [
+			await writeUnder(base, "accounts/cfg-1/acc-1/messages/m1/body.eml"),
+			await writeUnder(base, "accounts/cfg-1/acc-2/messages/m2/parts/1"),
+		];
+		const kept = await writeUnder(
+			base,
+			"accounts/cfg-2/acc-9/messages/m9/body.eml",
+		);
+
+		await caps.deleteStoragePrefix("accounts/cfg-1/", noopLog);
+
+		for (const path of deleted) {
+			assert.equal(await exists(path), false, `${path} must be deleted`);
+		}
+		assert.equal(await exists(kept), true, "a different tenant must survive");
+	});
+
+	it("scopes deletion to a single account when the prefix names one", async () => {
+		const caps = buildRelationalDeletionCapabilities();
+
+		const deleted = await writeUnder(
+			base,
+			"accounts/cfg-1/acc-1/messages/m1/body.eml",
+		);
+		const keptSibling = await writeUnder(
+			base,
+			"accounts/cfg-1/acc-2/messages/m2/body.eml",
+		);
+
+		await caps.deleteStoragePrefix("accounts/cfg-1/acc-1/", noopLog);
+
+		assert.equal(await exists(deleted), false);
+		assert.equal(
+			await exists(keptSibling),
+			true,
+			"a sibling account under the same tenant must survive",
+		);
+	});
+
+	it("is replay-safe — deleting a missing prefix does not throw", async () => {
+		const caps = buildRelationalDeletionCapabilities();
+		await caps.deleteStoragePrefix("accounts/never-existed/", noopLog);
+	});
+});
+
+describe("relational deletion capabilities — CDN and sign-out are no-ops", () => {
+	it("invalidateContent resolves without a CDN", async () => {
+		const caps = buildRelationalDeletionCapabilities();
+		await caps.invalidateContent("cfg-1", noopLog);
+		await caps.invalidateContent("cfg-1/acc-1", noopLog);
+	});
+
+	it("signOut resolves without a federated session store", async () => {
+		const caps = buildRelationalDeletionCapabilities();
+		await caps.signOut("user-123", noopLog);
+	});
+});

package/src/compose-relational.ts

@@ -0,0 +1,87 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import {
+	type CascadeDeleter,
+	createCascadeDeleter,
+	createSqliteCascadeDeleter,
+} from "@remit/drizzle-service";
+import type { Logger } from "@remit/logger-lambda";
+import { env } from "expect-env";
+import type { DeletionCapabilities } from "./deletion-capabilities.js";
+
+// Mirrors `@remit/storage-service`'s filesystem-backend default: bodies
+// live under `STORAGE_LOCAL_PATH` (`.remit/storage` when unset). The cascade
+// deletes the same `accounts/{accountConfigId}/…` key prefixes the S3 backend
+// would, translated to a recursive directory removal.
+const storageBasePath = (): string =>
+	process.env.STORAGE_LOCAL_PATH ?? ".remit/storage";
+
+/**
+ * Recursively remove every stored object under a key prefix. Replay-safe:
+ * `force: true` swallows a missing directory (ENOENT), matching the S3 backend's
+ * "delete on missing keys is a 200" idempotency.
+ */
+const deleteStoragePrefix = async (
+	keyPrefix: string,
+	log: Logger,
+): Promise<void> => {
+	const target = join(storageBasePath(), keyPrefix);
+	await rm(target, { recursive: true, force: true });
+	log.info({ keyPrefix, target }, "Filesystem storage prefix cleanup complete");
+};
+
+// The Drizzle cascade deleter is opened once, on first use, and reused. On
+// Postgres it binds to `PG_CONNECTION_URL`; on SQLite it opens the shared file
+// at `SQLITE_DB_PATH` (the native binding loads there, hence async). Built
+// lazily so the fanout worker — which signs out but never cascade-deletes —
+// does not open a database handle it will not use.
+let deleterPromise: Promise<CascadeDeleter> | undefined;
+
+const buildDeleter = async (): Promise<CascadeDeleter> => {
+	if (process.env.DATA_BACKEND === "sqlite") {
+		return createSqliteCascadeDeleter(env.SQLITE_DB_PATH);
+	}
+	return createCascadeDeleter(env.PG_CONNECTION_URL);
+};
+
+const getDeleter = (): Promise<CascadeDeleter> => {
+	if (!deleterPromise) deleterPromise = buildDeleter();
+	return deleterPromise;
+};
+
+/**
+ * The self-host stack's deletion capabilities (RFC 035/036).
+ *
+ * - `signOut`: no-op. Deleting the AccountConfig row severs the session's
+ *   account→data resolution, and there is no federated session store to sign
+ *   out of; better-auth session rows are owned by the auth service, outside this
+ *   worker's data seam.
+ * - `invalidateContent`: no-op. Caddy proxies `/content/*` straight to the
+ *   backend with no response cache (`deploy/vps/caddy/routes.caddy`), so there
+ *   is nothing to invalidate.
+ * - `deleteStoragePrefix`: recursive filesystem removal.
+ * - `cascadeDelete`: the Drizzle cascade over Postgres or SQLite. Message
+ *   subtrees emit `message.removed` outbox rows the search-index worker relays.
+ */
+export const buildRelationalDeletionCapabilities =
+	(): DeletionCapabilities => ({
+		assertReady: async () => {},
+		signOut: async (userId, log) => {
+			log.info(
+				{ userId },
+				"Sign-out is a no-op on the relational backend; AccountConfig removal severs session data access",
+			);
+		},
+		invalidateContent: async (contentPrefix, log) => {
+			log.info(
+				{ contentPrefix },
+				"Content invalidation is a no-op on the relational backend; no CDN cache fronts /content",
+			);
+		},
+		deleteStoragePrefix: (keyPrefix, log) =>
+			deleteStoragePrefix(keyPrefix, log),
+		cascadeDelete: async (entities, log) => {
+			const deleter = await getDeleter();
+			await deleter(entities, log);
+		},
+	});