@remit/backend 0.0.88 → 0.0.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.88",
+  "version": "0.0.90",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",
@@ -19,6 +19,10 @@
       "types": "./src/service/create-remit-client.ts",
       "default": "./src/service/create-remit-client.ts"
     },
+    "./folder-role-appointments": {
+      "types": "./src/handlers/folder-role-appointments.ts",
+      "default": "./src/handlers/folder-role-appointments.ts"
+    },
     "./organize": {
       "types": "./src/service/organize.ts",
       "default": "./src/service/organize.ts"
@@ -52,6 +56,8 @@
     "tsx": "*"
   },
   "dependencies": {
+    "@remit/config-format": "*",
+    "@remit/config-transfer": "*",
     "@remit/data-ports": "*",
     "@remit/domain-enums": "*",
     "@remit/api-openapi-types": "*",

package/scripts/config-save.ts

@@ -0,0 +1,128 @@
+import { readConfigForExport } from "@remit/config-transfer";
+import { env } from "expect-env";
+// Reached by module path rather than through either package's entry point, the
+// same way the migrate entrypoint reaches its repairs: this file is bundled by
+// esbuild, and a barrel import would drag every repository and the native
+// driver behind it into a script that reads one table.
+import { auth_user } from "../../auth-service/src/schema/auth-schema-sqlite.js";
+import { createSqliteDatabase } from "../../drizzle-service/src/sqlite-client.js";
+import { deriveAccountConfigId } from "../src/auth.js";
+import { getClient } from "../src/service/data-client.js";
+import { exportIdentity } from "../src/service/export-identity.js";
+
+/**
+ * `remit config save` (issue #1021). Writes one configuration out as a
+ * versioned JSON document on stdout, over the same reader the export endpoint
+ * uses. Ships as an alternate entrypoint in the backend image — "the backend
+ * image with a command", the shape `migrate.mjs` and `backfill-list-id.mjs`
+ * already use — because the operator runs it before a migration drops the
+ * database, with no browser and no session to authenticate.
+ *
+ * The document goes to stdout and never to a path inside the container: the
+ * wrapper redirects it to a host file, so the file lands where the operator can
+ * see it and with their ownership, rather than root-owned inside a volume.
+ */
+
+const USAGE = `Usage: node config-save.mjs [--user <email>]
+
+Writes the configuration as a versioned JSON document to stdout. Contains no
+credential: each account records which one it will need back instead.
+
+  --user <email>  Which sign-in to export. Optional on an instance that holds
+                  exactly one configuration.
+`;
+
+interface Options {
+	user: string | undefined;
+}
+
+const parseArguments = (argv: readonly string[]): Options => {
+	const options: Options = { user: undefined };
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--user") {
+			const value = argv[index + 1];
+			if (value === undefined || value.startsWith("--")) {
+				throw new Error("--user needs an email address");
+			}
+			options.user = value;
+			index += 1;
+			continue;
+		}
+		throw new Error(`unknown option '${argument}'`);
+	}
+	return options;
+};
+
+/**
+ * The configuration behind a sign-in. Identity lives in better-auth's own
+ * tables in the same database file, and the configuration id derives from the
+ * user id, so the email on the sign-in screen is the one thing an operator can
+ * be expected to know.
+ */
+const accountConfigIdForUser = async (email: string): Promise<string> => {
+	const { db, close } = await createSqliteDatabase(
+		{ auth_user },
+		{ filename: env.SQLITE_DB_PATH },
+	);
+	try {
+		const users = await db
+			.select({ id: auth_user.id, email: auth_user.email })
+			.from(auth_user);
+		// Matched in JS rather than in the query: an address is
+		// case-insensitive on the part that matters, and which collation the
+		// column happens to carry is not something an operator should have to
+		// know before their own email matches.
+		const wanted = email.toLowerCase();
+		const user = users.find((row) => row.email.toLowerCase() === wanted);
+		if (!user) throw new Error(`no user signs in as ${email}`);
+		return deriveAccountConfigId(user.id);
+	} finally {
+		await close();
+	}
+};
+
+const soleAccountConfigId = async (
+	listAll: () => Promise<Array<{ accountConfigId: string }>>,
+): Promise<string> => {
+	const configs = await listAll();
+	const only = configs[0];
+	if (!only) throw new Error("this instance holds no configuration to export");
+	if (configs.length > 1) {
+		throw new Error(
+			`this instance holds ${configs.length} configurations — name one with --user <email>`,
+		);
+	}
+	return only.accountConfigId;
+};
+
+const run = async (): Promise<void> => {
+	const argv = process.argv.slice(2);
+	if (argv.includes("--help") || argv.includes("-h")) {
+		process.stdout.write(USAGE);
+		return;
+	}
+
+	const options = parseArguments(argv);
+	const client = await getClient();
+	const accountConfigId = options.user
+		? await accountConfigIdForUser(options.user)
+		: await soleAccountConfigId(() => client.accountConfig.listAll());
+
+	const document = await readConfigForExport(
+		client,
+		accountConfigId,
+		exportIdentity(),
+	);
+	process.stdout.write(`${JSON.stringify(document, null, "\t")}\n`);
+};
+
+// No `process.exit` on the way out: the document is written to stdout, and
+// stdout is a pipe under `compose run`, so exiting drops whatever write is
+// still pending. Setting the code and letting the process end delivers it.
+await run().catch((error: unknown) => {
+	process.stderr.write(
+		`config save: ${error instanceof Error ? error.message : String(error)}\n`,
+	);
+	process.exitCode = 1;
+});

package/src/handlers/config.ts

@@ -2,15 +2,25 @@ import type { SQSClient } from "@aws-sdk/client-sqs";
 import type {
 	AccountConfigResponse,
 	ConfigDescriptionResponse,
+	ConfigImportReport,
 } from "@remit/api-openapi-types";
+import type { ReaderConfigDocument } from "@remit/config-format";
+import {
+	importConfig,
+	pendingImportOf,
+	readConfigForExport,
+} from "@remit/config-transfer";
 import type { AccountConfigItem, MailboxItem } from "@remit/data-ports";
-import { NotFoundError } from "@remit/data-ports/errors";
+import { ConfigNotEmptyError, NotFoundError } from "@remit/data-ports/errors";
+import type { CanonicalMailboxRoleValue } from "@remit/data-ports/folder-role";
 import { logger } from "@remit/logger-lambda";
 import type { APIGatewayProxyEvent } from "aws-lambda";
 import { env } from "expect-env";
 import type { Context } from "openapi-backend";
 import { getAccountConfigIdFromEvent, getSubFromEvent } from "../auth.js";
+import { embedAnchorText } from "../service/config-import.js";
 import { getClient } from "../service/data-client.js";
+import { exportIdentity } from "../service/export-identity.js";
 import { fireAndForget } from "../service/fire-and-forget.js";
 import { sqsClient } from "../service/sqs.js";
 import { triggerAccountSync } from "../service/trigger-sync.js";
@@ -27,6 +37,7 @@ import {
 import {
 	groupFolderAppointmentsByAccount,
 	resolveFolderAppointments,
+	writeFolderRoleAppointment,
 } from "./folder-role-appointments.js";
 
 type StructuredLog = (fields: Record<string, unknown>, message: string) => void;
@@ -201,8 +212,15 @@ export const ConfigOperations: Record<
 			activeAccounts.map((acc) => acc.accountId),
 		);
 
+		// An import that named folders IMAP had not produced yet rides the config
+		// read rather than a route of its own, so nothing has to poll for it.
+		const pendingImport = pendingImportOf(
+			await client.configImport.listByAccountConfig(accountConfigId),
+		);
+
 		return {
 			accountConfig: toAccountConfigResponse(accountConfig),
+			...(pendingImport ? { pendingImport } : {}),
 			accounts: activeAccounts.map((acc) =>
 				toAccountResponse(
 					acc,
@@ -216,4 +234,74 @@ export const ConfigOperations: Record<
 			),
 		};
 	},
+
+	ConfigOperations_exportConfig: async (
+		_context: Context,
+		...args: unknown[]
+	): Promise<{ schemaVersion: number; document: ReaderConfigDocument }> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const client = await getClient();
+		const document = await readConfigForExport(
+			client,
+			accountConfigId,
+			exportIdentity(),
+		);
+		return { schemaVersion: document.schemaVersion, document };
+	},
+
+	ConfigOperations_importConfig: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<ConfigImportReport> => {
+		const event = args[0] as APIGatewayProxyEvent;
+		const accountConfigId = getAccountConfigIdFromEvent(event);
+		const body = (context.request.requestBody ?? {}) as {
+			mode?: "validate" | "apply";
+			onExisting?: "abort" | "merge";
+			document?: unknown;
+		};
+		const client = await getClient();
+
+		const outcome = await importConfig(
+			{
+				repositories: client,
+				// Passed through as-is, undefined included: a backend with no
+				// cross-entity transaction writes without one, and the report words
+				// what survived a failure from whether this is here.
+				transaction: client.writeSet,
+				appointFolderRole: (
+					configId,
+					accountId,
+					role,
+					mailboxId,
+					lastKnownPath,
+				) =>
+					writeFolderRoleAppointment(
+						client.accountSetting,
+						configId,
+						accountId,
+						role as CanonicalMailboxRoleValue,
+						mailboxId,
+						lastKnownPath,
+					),
+				embedAnchor: embedAnchorText,
+			},
+			{
+				accountConfigId,
+				userId: getSubFromEvent(event) ?? accountConfigId,
+				document: body.document,
+				mode: body.mode ?? "validate",
+				onExisting: body.onExisting ?? "abort",
+			},
+		);
+
+		if (outcome.outcome === "conflict") {
+			throw new ConfigNotEmptyError(
+				outcome.conflict.message,
+				outcome.conflict.details,
+			);
+		}
+		return outcome.report;
+	},
 };

package/src/handlers/filter.ts

@@ -3,10 +3,11 @@ import type {
 	FilterResponse,
 	UpdateFilterInput as UpdateFilterRequestBody,
 } from "@remit/api-openapi-types";
-import type {
-	FilterItem,
-	IFilterAnchorTransaction,
-	UpdateFilterInput,
+import {
+	deriveFilterTtl,
+	type FilterItem,
+	type IFilterAnchorTransaction,
+	type UpdateFilterInput,
 } from "@remit/data-ports";
 import { BadRequestError } from "@remit/data-ports/errors";
 import { FilterScope, FilterState } from "@remit/domain-enums";
@@ -41,24 +42,6 @@ export interface FilterCrudDeps {
 	): Promise<AnchorPayload | null>;
 }
 
-/**
- * Epoch-seconds `ttl` derived from `expiresAt`, set only for a `Temporary`
- * filter (RFC 034 Decision 1.3). A `Standing` filter never carries `ttl` — the
- * reserved table-wide TTL attribute must stay absent, or the row would be swept
- * (Decision 1.4).
- */
-export const deriveFilterTtl = (
-	scope: string,
-	expiresAt: string | undefined,
-): number | undefined => {
-	if (scope !== FilterScope.Temporary || !expiresAt) return undefined;
-	const ms = new Date(expiresAt).getTime();
-	if (Number.isNaN(ms)) {
-		throw new BadRequestError(`Invalid expiresAt: ${expiresAt}`);
-	}
-	return Math.floor(ms / 1000);
-};
-
 /**
  * Reduce a PATCH body to the fields a filter update may set (RFC 034, reader
  * #266). Preserves absence: a key not present in the body is not present in

package/src/service/compose-sqlite.ts

@@ -4,6 +4,7 @@ import {
 	AccountRepo,
 	AccountSettingRepo,
 	AddressRepo,
+	ConfigImportRepo,
 	createSqliteDatabase,
 	DrizzleEnvelopeRepository,
 	DrizzleFilterAnchorTransaction,
@@ -25,6 +26,7 @@ import {
 	OutboxAttachmentRepo,
 	OutboxMessageRepo,
 	QuarantineRepo,
+	runInTransaction,
 	SenderSignerStandingRepo,
 } from "@remit/drizzle-service";
 import { env } from "expect-env";
@@ -65,6 +67,7 @@ export const buildSqliteClient = async (): Promise<RemitClient> => {
 		threadMessage: new DrizzleThreadMessageRepository(genericDb),
 		envelope: new DrizzleEnvelopeRepository(messageDataDb),
 		accountExportRequest: new AccountExportRequestRepo(genericDb),
+		configImport: new ConfigImportRepo(genericDb),
 		quarantine: new QuarantineRepo(genericDb),
 		organizeJobRequest: new OrganizeJobRequestRepo(genericDb),
 		placementMove: new MessagePlacementMoveRepo(genericDb),
@@ -76,6 +79,7 @@ export const buildSqliteClient = async (): Promise<RemitClient> => {
 		messageLabel: new MessageLabelRepo(genericDb),
 		senderSignerStanding: new SenderSignerStandingRepo(genericDb),
 		unitOfWork: new DrizzleUnitOfWork(messageDataDb),
+		writeSet: (run) => runInTransaction(genericDb, () => run()),
 	};
 
 	return createRemitClient({ repositories, ...buildSharedDeps() });

package/src/service/config-import.ts

@@ -0,0 +1,39 @@
+import type { EmbedAnchor } from "@remit/config-transfer";
+import { logger } from "@remit/logger-lambda";
+import { buildEmbeddingServiceFromEnv } from "@remit/search-service/from-env";
+import { isSemanticCapabilityAbsence } from "./semantic-capability.js";
+
+type Embedder = {
+	embed: (texts: string[]) => Promise<number[][]>;
+	readonly embeddingId: string;
+};
+
+let cached: Embedder | null = null;
+
+/**
+ * Re-embed a filter's anchor from the source text its file carries. The vector
+ * never travels — it is a function of the model that produced it — so this is
+ * the one thing an import computes rather than copies.
+ *
+ * A deployment that ships no vector pipeline answers `undefined` rather than
+ * failing the import: the anchor then lands stamped as un-embedded, and the
+ * same lazy repair that handles a model migration builds its vector the first
+ * time the filter is matched. A configuration file has to be importable on the
+ * instance a person is recovering onto, whatever that instance can run.
+ */
+export const embedAnchorText: EmbedAnchor = async (sourceText) => {
+	try {
+		if (!cached) cached = buildEmbeddingServiceFromEnv();
+		const [embedding] = await cached.embed([sourceText]);
+		return embedding
+			? { embedding, embeddingId: cached.embeddingId }
+			: undefined;
+	} catch (error) {
+		if (!isSemanticCapabilityAbsence(error)) throw error;
+		logger.warn(
+			{ error: error instanceof Error ? error.message : String(error) },
+			"No embedding pipeline in this deployment; an imported filter anchor is stored as text and embedded on first use",
+		);
+		return undefined;
+	}
+};

package/src/service/create-remit-client.ts

@@ -4,6 +4,7 @@ import type {
 	IAccountRepository,
 	IAccountSettingRepository,
 	IAddressRepository,
+	IConfigImportRepository,
 	IEnvelopeRepository,
 	IFilterAnchorRepository,
 	IFilterAnchorTransaction,
@@ -78,6 +79,11 @@ export interface RemitClient {
 	envelope: IEnvelopeRepository;
 	accountExportRequest: IAccountExportRequestRepository;
 
+	// Applied configuration imports (#1021), and the folder references each is
+	// still waiting for. Read by GET /config to surface what a file named but
+	// IMAP has not produced yet, and written by the binder when it does.
+	configImport: IConfigImportRepository;
+
 	// Messages the sync path could not read (issue #72). Read-only from the API
 	// process: the sync worker writes the rows, settings lists them.
 	quarantine: IQuarantineRepository;
@@ -163,6 +169,13 @@ export interface RemitClient {
 
 	// Helper to create IMAP connection scope from accountId
 	createConnectionScope: (accountId: string) => Promise<ConnectionScope>;
+
+	// Runs an arbitrary set of repository writes as one transaction. Absent on a
+	// backend with no cross-entity transaction, where the caller's contract is
+	// instead: validate before the first write, fail fast, and report what
+	// landed. The message-save write set has its own bound repositories and uses
+	// `unitOfWork`; this one takes the repos as they are.
+	writeSet?: <T>(run: () => Promise<T>) => Promise<T>;
 }
 
 export interface RemitClientRepositories {
@@ -180,6 +193,7 @@ export interface RemitClientRepositories {
 	threadMessage: IThreadMessageRepository;
 	envelope: IEnvelopeRepository;
 	accountExportRequest: IAccountExportRequestRepository;
+	configImport: IConfigImportRepository;
 	quarantine: IQuarantineRepository;
 	organizeJobRequest: IOrganizeJobRequestRepository;
 	placementMove: IMessagePlacementMoveRepository;
@@ -191,6 +205,7 @@ export interface RemitClientRepositories {
 	messageLabel: IMessageLabelRepository;
 	senderSignerStanding: ISenderSignerStandingRepository;
 	unitOfWork?: IUnitOfWork;
+	writeSet?: <T>(run: () => Promise<T>) => Promise<T>;
 }
 
 export interface RemitClientSharedDeps {
@@ -407,6 +422,7 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		threadMessage: repositories.threadMessage,
 		envelope: repositories.envelope,
 		accountExportRequest: repositories.accountExportRequest,
+		configImport: repositories.configImport,
 		quarantine: repositories.quarantine,
 		organizeJobRequest: repositories.organizeJobRequest,
 		filter: repositories.filter,
@@ -416,6 +432,7 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		messageLabel: repositories.messageLabel,
 		senderSignerStanding: repositories.senderSignerStanding,
 		unitOfWork: repositories.unitOfWork,
+		writeSet: repositories.writeSet,
 
 		storage,
 		search,

package/src/service/export-identity.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ConfigExportIdentity } from "@remit/config-transfer";
+
+const DEFAULT_CONTROL_DIR = "/data/control";
+
+/**
+ * The version a file says it was written by. The updater owns this fact: it
+ * reads the tag from `.env` and writes it into `state.json`, which is the only
+ * honest source across an update that rewrites that tag underneath a
+ * long-lived process. With no state file there is nothing authoritative to
+ * stamp, and an export says so rather than inventing a version an importing
+ * reader would then trust.
+ */
+const runningVersion = (): string => {
+	const dir = process.env.REMIT_UPDATE_CONTROL_DIR ?? DEFAULT_CONTROL_DIR;
+	let raw: string;
+	try {
+		raw = readFileSync(join(dir, "state.json"), "utf8");
+	} catch {
+		return "unknown";
+	}
+	const state: unknown = JSON.parse(raw);
+	if (typeof state !== "object" || state === null) return "unknown";
+	const version = (state as { currentVersion?: unknown }).currentVersion;
+	return typeof version === "string" && version.length > 0
+		? version
+		: "unknown";
+};
+
+/** Who wrote a configuration file, and from where. Provenance only. */
+export const exportIdentity = (
+	now: Date = new Date(),
+): ConfigExportIdentity => ({
+	app: "reader",
+	version: runningVersion(),
+	exportedAt: now.toISOString(),
+	instance: process.env.PUBLIC_ORIGIN ?? "",
+});

package/src/types.ts

@@ -12,6 +12,8 @@ export type OperationIds =
 	| "MeOperations_getExport"
 	| "MeOperations_listQuarantine"
 	| "ConfigOperations_getConfig"
+	| "ConfigOperations_exportConfig"
+	| "ConfigOperations_importConfig"
 	| "SystemOperations_getSystemUpdate"
 	| "SystemOperations_applySystemUpdate"
 	| "AccountOperations_createAccount"