@remit/config-format 0.0.1

package/src/bin/check-schema.ts

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { serializeConfigJsonSchema } from "../json-schema.js";
+import { committedSchemaPath } from "../schema-artifact.js";
+
+const target = committedSchemaPath();
+
+if (!existsSync(target)) {
+	console.error(`Config JSON Schema is missing: ${target}`);
+	console.error("Run `npm run schema:emit -w @remit/config-format`.");
+	process.exit(1);
+}
+
+if ((await readFile(target, "utf8")) === serializeConfigJsonSchema()) {
+	console.log(`config JSON Schema is current: ${target}`);
+	process.exit(0);
+}
+
+console.error(`Config JSON Schema is stale: ${target}`);
+console.error("Run `npm run schema:emit -w @remit/config-format`.");
+process.exit(1);

package/src/bin/emit-schema.ts

@@ -0,0 +1,12 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { serializeConfigJsonSchema } from "../json-schema.js";
+import { artifactSchemaPath, committedSchemaPath } from "../schema-artifact.js";
+
+const serialized = serializeConfigJsonSchema();
+
+for (const target of [committedSchemaPath(), artifactSchemaPath()]) {
+	await mkdir(dirname(target), { recursive: true });
+	await writeFile(target, serialized, "utf8");
+	console.log(`wrote ${target}`);
+}

package/src/document.test.ts

@@ -0,0 +1,216 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	AccountAuthType,
+	CanonicalMailboxRole,
+	FilterClauseField,
+	LabelColor,
+	MessageCategory,
+} from "@remit/domain-enums";
+import {
+	AccountSchema,
+	AddressFlagsEntrySchema,
+	FilterSchema,
+	FolderOverrideSchema,
+	LabelSchema,
+	MessageDecisionsSchema,
+	ReaderConfigDocumentSchema,
+} from "./document.js";
+import { readGoldenConfigDocument } from "./fixtures.js";
+
+const goldenAccount = () =>
+	structuredClone(
+		(readGoldenConfigDocument() as { accounts: unknown[] }).accounts[0],
+	) as Record<string, unknown>;
+
+test("the account schema is strict at every level it defines", () => {
+	for (const mutate of [
+		(account: Record<string, unknown>) => {
+			account.legacyField = 1;
+		},
+		(account: Record<string, unknown>) => {
+			(account.imap as Record<string, unknown>).compress = true;
+		},
+		(account: Record<string, unknown>) => {
+			(account.signature as Record<string, unknown>).markdown = "";
+		},
+	]) {
+		const account = goldenAccount();
+		mutate(account);
+
+		assert.equal(AccountSchema.safeParse(account).success, false);
+	}
+});
+
+test("an account declares which credential it needs, and never more", () => {
+	const account = goldenAccount();
+	account.credentials = { required: "certificate" };
+
+	assert.equal(AccountSchema.safeParse(account).success, false);
+});
+
+test("enum values come from the domain, so a stale spelling is rejected", () => {
+	const account = goldenAccount();
+	account.authType = "oauthGoogle";
+	assert.equal(AccountSchema.safeParse(account).success, false);
+
+	account.authType = AccountAuthType.OauthMicrosoft;
+	assert.equal(AccountSchema.safeParse(account).success, true);
+
+	assert.equal(
+		LabelSchema.safeParse({ name: "x", color: "Chartreuse" }).success,
+		false,
+	);
+	assert.equal(
+		LabelSchema.safeParse({ name: "x", color: LabelColor.Teal }).success,
+		true,
+	);
+});
+
+test("folder roles and overrides travel by IMAP path", () => {
+	const account = goldenAccount();
+	account.folderRoles = [
+		{ role: CanonicalMailboxRole.Archive, mailboxId: "not-a-path" },
+	];
+
+	assert.equal(AccountSchema.safeParse(account).success, false);
+
+	assert.equal(
+		FolderOverrideSchema.safeParse({
+			folderPath: "INBOX.Lists",
+			displayName: "",
+			muted: null,
+		}).success,
+		true,
+	);
+});
+
+test("a filter names its label by name and its folder by account and path", () => {
+	const filter = {
+		name: "keep",
+		scope: "Standing",
+		expiresAt: null,
+		matchOperator: "And",
+		literalClauses: [{ field: FilterClauseField.ListId, value: "x.example" }],
+		actionLabelName: "Facturen",
+		actionFolder: {
+			accountId: "6f4c2c30-9a2c-4a7f-9f9f-1f2c3d4e5a6b",
+			folderPath: "INBOX.Facturen",
+		},
+		anchor: null,
+	};
+
+	assert.equal(FilterSchema.safeParse(filter).success, true);
+	assert.equal(
+		FilterSchema.safeParse({ ...filter, actionLabelId: "Facturen" }).success,
+		false,
+	);
+	assert.equal(
+		FilterSchema.safeParse({
+			...filter,
+			actionFolder: { mailboxId: "6f4c2c30-9a2c-4a7f-9f9f-1f2c3d4e5a6b" },
+		}).success,
+		false,
+	);
+});
+
+test("a filter anchor carries its source text and no vector", () => {
+	const anchored = {
+		name: "like this",
+		scope: "Standing",
+		expiresAt: null,
+		matchOperator: "And",
+		literalClauses: [],
+		actionLabelName: null,
+		actionFolder: null,
+		anchor: {
+			sourceText: "the release note we file every month",
+			embeddingId: "amazon.titan-embed-text-v2:0@1024",
+			sourceMessageId: "2c9e4b11-7d5a-4f60-9a31-5b8c0e7f2d44",
+		},
+	};
+
+	assert.equal(FilterSchema.safeParse(anchored).success, true);
+	assert.equal(
+		FilterSchema.safeParse({
+			...anchored,
+			anchor: {
+				sourceText: "x",
+				embeddingId: "m@1",
+				sourceMessageId: "2c9e4b11-7d5a-4f60-9a31-5b8c0e7f2d44",
+				anchorEmbedding: [0.1, 0.2],
+			},
+		}).success,
+		false,
+	);
+});
+
+test("an address flag keeps its whole payload", () => {
+	const entry = {
+		normalizedEmail: "post@bank.example",
+		displayName: "Bank",
+		flags: {
+			blocked: {
+				value: true,
+				setAt: 1750000000000,
+				setBy: "web-client",
+				expiresAt: 1790000000000,
+				reason: "phishing",
+			},
+			category: {
+				value: MessageCategory.transactional,
+				setAt: 1750000000000,
+			},
+		},
+	};
+
+	const parsed = AddressFlagsEntrySchema.parse(entry);
+
+	assert.deepEqual(parsed, entry);
+	assert.equal(
+		AddressFlagsEntrySchema.safeParse({
+			...entry,
+			flags: { blocked: true },
+		}).success,
+		false,
+	);
+});
+
+test("an unknown flag key is refused, so a flag is added deliberately", () => {
+	assert.equal(
+		AddressFlagsEntrySchema.safeParse({
+			normalizedEmail: "a@b.example",
+			displayName: "",
+			flags: { shouted: { value: true, setAt: 1 } },
+		}).success,
+		false,
+	);
+});
+
+test("the two derived flags have no place in the file", () => {
+	for (const flag of ["wellknown", "junkOnly"]) {
+		assert.equal(
+			AddressFlagsEntrySchema.safeParse({
+				normalizedEmail: "a@b.example",
+				displayName: "",
+				flags: { [flag]: { value: true, setAt: 1 } },
+			}).success,
+			false,
+		);
+	}
+});
+
+test("the reserved decisions slot is defined and empty", () => {
+	assert.equal(MessageDecisionsSchema.safeParse([]).success, true);
+	assert.equal(MessageDecisionsSchema.safeParse([{}]).success, false);
+});
+
+test("the document schema refuses an unknown top-level section", () => {
+	const source = readGoldenConfigDocument() as Record<string, unknown>;
+
+	assert.equal(
+		ReaderConfigDocumentSchema.safeParse({ ...source, savedSearches: [] })
+			.success,
+		false,
+	);
+});

package/src/document.ts

@@ -0,0 +1,262 @@
+import {
+	AccountAuthType,
+	CanonicalMailboxRole,
+	FilterClauseField,
+	FilterMatchOperator,
+	FilterScope,
+	LabelColor,
+	MessageCategory,
+} from "@remit/domain-enums";
+import { z } from "zod/v4";
+import { CONFIG_KIND, CURRENT_SCHEMA_VERSION } from "./version.js";
+
+const NonEmpty = z.string().min(1);
+const Uuid = z.uuid();
+const IsoDateTime = z.iso.datetime({ offset: true });
+const Port = z.int().min(1).max(65535);
+const FlagTimestamp = z.int();
+
+/**
+ * An IMAP path, as the server spells it. Folders travel by path rather than by
+ * id: the ids are local to the instance that wrote the file, the path is what
+ * the receiving instance can actually resolve against its own mailbox list.
+ */
+const ImapPath = z.string().min(1).max(512);
+
+/**
+ * Which reader wrote the file, and when. A reader that does not recognise the
+ * generator still reads the document: the envelope already said it could.
+ */
+export const GeneratorSchema = z
+	.strictObject({
+		app: NonEmpty,
+		version: NonEmpty,
+		exportedAt: IsoDateTime,
+	})
+	.describe("Which reader wrote this file, and when.");
+
+/**
+ * Where the file came from, recorded and never authoritative. A database drop
+ * can change the account config id, so the importing instance rebinds to its
+ * own; this block only lets a person tell two exports apart.
+ */
+export const ProvenanceSchema = z
+	.strictObject({
+		accountConfigId: Uuid,
+		instance: z.string(),
+	})
+	.describe("The instance this file was exported from. Never applied.");
+
+/** The audit metadata every sender-level flag and mute carries. */
+export const FlagMetadataSchema = z.strictObject({
+	value: z.boolean(),
+	setAt: FlagTimestamp,
+	setBy: z.string().optional(),
+	expiresAt: FlagTimestamp.optional(),
+	reason: z.string().optional(),
+});
+
+export const MutedFlagSchema = FlagMetadataSchema;
+
+const CategoryFlagSchema = z.strictObject({
+	value: z.enum(MessageCategory),
+	setAt: FlagTimestamp,
+	setBy: z.string().optional(),
+	expiresAt: FlagTimestamp.optional(),
+	reason: z.string().optional(),
+});
+
+/**
+ * Sender-level flags, sparse exactly as they are stored: a key's presence is
+ * the flag being set. Each entry carries its full payload — who set it, when,
+ * why, and when it lapses — because a flag stripped to a boolean arrives on the
+ * other side as an assertion nobody can date or explain.
+ *
+ * `wellknown` and `junkOnly` have no place here. The machine derives both, from
+ * engagement counters and from where mail was seen, and both come back on their
+ * own after a resync; carrying them would let a stale file overrule what the
+ * receiving instance has since worked out for itself.
+ */
+export const AddressFlagsSchema = z.strictObject({
+	trusted: FlagMetadataSchema.optional(),
+	blocked: FlagMetadataSchema.optional(),
+	muted: FlagMetadataSchema.optional(),
+	vip: FlagMetadataSchema.optional(),
+	category: CategoryFlagSchema.optional(),
+	autoArchive: FlagMetadataSchema.optional(),
+	unsubscribed: FlagMetadataSchema.optional(),
+});
+
+export const AddressFlagsEntrySchema = z.strictObject({
+	/** Lowercased address. The identity an importing instance matches on. */
+	normalizedEmail: NonEmpty,
+	/**
+	 * The personal name last seen on mail from this address. A display hint for
+	 * an import preview and nothing more: it is not authoritative, it is never
+	 * matched on, and an importing instance overwrites it from its own mail.
+	 */
+	displayName: z.string(),
+	flags: AddressFlagsSchema,
+});
+
+/**
+ * Which credential the account needs to come back to life, never the credential
+ * itself. The importing instance prompts for what this names.
+ */
+export const CredentialRequirementSchema = z.strictObject({
+	required: z.enum(["password", "oauth"]),
+	provider: z.literal("microsoft").optional(),
+});
+
+export const ImapEndpointSchema = z.strictObject({
+	host: NonEmpty,
+	port: Port,
+	tls: z.boolean(),
+	startTls: z.boolean(),
+});
+
+export const SmtpEndpointSchema = z.strictObject({
+	enabled: z.boolean(),
+	host: z.string(),
+	port: Port,
+	tls: z.boolean(),
+	startTls: z.boolean(),
+	/** Empty when sending reuses the IMAP username. */
+	username: z.string(),
+});
+
+export const SignatureSchema = z.strictObject({
+	plainText: z.string(),
+	html: z.string(),
+});
+
+/** A canonical role, bound to the folder that fills it by IMAP path. */
+export const FolderRoleSchema = z.strictObject({
+	role: z.enum(CanonicalMailboxRole),
+	folderPath: ImapPath,
+});
+
+/** Per-folder settings that survive the move, keyed by IMAP path. */
+export const FolderOverrideSchema = z.strictObject({
+	folderPath: ImapPath,
+	/** Empty when the folder keeps the name the server gives it. */
+	displayName: z.string(),
+	muted: MutedFlagSchema.nullable(),
+});
+
+export const AccountSchema = z.strictObject({
+	accountId: Uuid,
+	email: NonEmpty,
+	username: NonEmpty,
+	authType: z.enum(AccountAuthType),
+	credentials: CredentialRequirementSchema,
+	isActive: z.boolean(),
+	imap: ImapEndpointSchema,
+	smtp: SmtpEndpointSchema,
+	/** Empty when the client derives a label from the address. */
+	displayName: z.string(),
+	muted: MutedFlagSchema.nullable(),
+	composeLanguages: z.array(NonEmpty),
+	signature: SignatureSchema,
+	folderRoles: z.array(FolderRoleSchema),
+	folderOverrides: z.array(FolderOverrideSchema),
+	pinnedFolders: z.array(ImapPath),
+});
+
+export const AccountConfigSchema = z.strictObject({
+	name: z.string(),
+});
+
+export const LabelSchema = z.strictObject({
+	name: z.string().min(1).max(140),
+	color: z.enum(LabelColor),
+});
+
+export const FilterClauseSchema = z.strictObject({
+	field: z.enum(FilterClauseField),
+	value: z.string().min(1).max(256),
+});
+
+/**
+ * A semantic anchor as text, never as numbers. The vector is a function of the
+ * embedding model that produced it, so it means nothing on an instance running
+ * a different one; the source text re-embeds against whatever model the
+ * importing instance actually has.
+ */
+export const FilterAnchorSchema = z.strictObject({
+	sourceText: z.string().min(1).max(512),
+	/** `<modelId>@<dimensions>` the vector was built with, for provenance. */
+	embeddingId: NonEmpty,
+	sourceMessageId: Uuid,
+});
+
+/** A folder named the only way it can be named across instances. */
+export const FolderRefSchema = z.strictObject({
+	accountId: Uuid,
+	folderPath: ImapPath,
+});
+
+export const FilterSchema = z.strictObject({
+	name: z.string().min(1).max(256),
+	scope: z.enum(FilterScope),
+	/** ISO 8601 with offset when the scope is Temporary, otherwise null. */
+	expiresAt: IsoDateTime.nullable(),
+	matchOperator: z.enum(FilterMatchOperator),
+	literalClauses: z.array(FilterClauseSchema),
+	/** The label this filter applies, by name — ids are local to an instance. */
+	actionLabelName: z.string().min(1).max(140).nullable(),
+	actionFolder: FolderRefSchema.nullable(),
+	anchor: FilterAnchorSchema.nullable(),
+});
+
+export const SavedSearchSchema = z.strictObject({
+	name: NonEmpty,
+	query: z.string(),
+});
+
+/**
+ * Preferences the browser holds, not the server. They survive a database drop
+ * already; they ride along so they also survive a change of browser. The server
+ * ignores this block.
+ */
+export const ClientPreferencesSchema = z.strictObject({
+	theme: z.string(),
+	density: z.string(),
+	defaultComposerFormat: z.string(),
+	savedSearches: z.array(SavedSearchSchema),
+});
+
+/**
+ * Reserved. Per-message decisions — what was filed where, what was dismissed —
+ * are the one part of a mailbox's history this format does not yet describe,
+ * and the slot is named here so a later version can fill it without moving
+ * anything else. Nothing writes it and nothing reads it, so v1 requires it to
+ * be empty: accepting entries a reader would then drop is worse than refusing
+ * the file.
+ */
+export const MessageDecisionsSchema = z
+	.array(z.unknown())
+	.max(0)
+	.describe("Reserved for a later schema version; must be empty in v1.");
+
+export const ReaderConfigDocumentSchema = z.strictObject({
+	kind: z.literal(CONFIG_KIND),
+	schemaVersion: z.literal(CURRENT_SCHEMA_VERSION),
+	generator: GeneratorSchema,
+	provenance: ProvenanceSchema,
+	accountConfig: AccountConfigSchema,
+	accounts: z.array(AccountSchema),
+	labels: z.array(LabelSchema),
+	filters: z.array(FilterSchema),
+	addressFlags: z.array(AddressFlagsEntrySchema),
+	clientPreferences: ClientPreferencesSchema.optional(),
+	messageDecisions: MessageDecisionsSchema.optional(),
+});
+
+export type ReaderConfigDocument = z.infer<typeof ReaderConfigDocumentSchema>;
+export type ConfigAccount = z.infer<typeof AccountSchema>;
+export type ConfigFilter = z.infer<typeof FilterSchema>;
+export type ConfigLabel = z.infer<typeof LabelSchema>;
+export type ConfigAddressFlagsEntry = z.infer<typeof AddressFlagsEntrySchema>;
+export type ConfigAddressFlags = z.infer<typeof AddressFlagsSchema>;
+export type ConfigClientPreferences = z.infer<typeof ClientPreferencesSchema>;

package/src/envelope.ts

@@ -0,0 +1,15 @@
+import { z } from "zod/v4";
+import { CONFIG_KIND } from "./version.js";
+
+/**
+ * The first of the two passes. Deliberately tiny and deliberately not strict:
+ * it answers "what is this file, and which version of the format does it claim
+ * to be" without any opinion about the rest, so a document written by a newer
+ * reader still identifies itself instead of failing as a wall of unknown keys.
+ */
+export const ConfigEnvelopeSchema = z.object({
+	kind: z.literal(CONFIG_KIND),
+	schemaVersion: z.int().min(1),
+});
+
+export type ConfigEnvelope = z.infer<typeof ConfigEnvelopeSchema>;

package/src/errors.ts

@@ -0,0 +1,119 @@
+import type { $ZodIssue } from "zod/v4/core";
+
+/**
+ * Every way reading a configuration document can fail, as a closed set. A
+ * caller renders the failure from `code` rather than from an `instanceof`
+ * ladder; the classes exist so the throw carries the offending detail with it.
+ */
+export const ConfigReadErrorCode = {
+	NotAnObject: "NotAnObject",
+	WrongKind: "WrongKind",
+	UnsupportedVersion: "UnsupportedVersion",
+	UnknownKeys: "UnknownKeys",
+	CredentialPresent: "CredentialPresent",
+	Malformed: "Malformed",
+} as const;
+
+export type ConfigReadErrorCodeValue =
+	(typeof ConfigReadErrorCode)[keyof typeof ConfigReadErrorCode];
+
+export abstract class ConfigReadError extends Error {
+	abstract readonly code: ConfigReadErrorCodeValue;
+
+	constructor(message: string) {
+		super(message);
+		this.name = new.target.name;
+	}
+}
+
+export class ConfigNotAnObjectError extends ConfigReadError {
+	readonly code = ConfigReadErrorCode.NotAnObject;
+}
+
+export class ConfigKindError extends ConfigReadError {
+	readonly code = ConfigReadErrorCode.WrongKind;
+	readonly expected: string;
+	readonly received: unknown;
+
+	constructor(expected: string, received: unknown) {
+		super(
+			`Not a reader configuration document: expected kind "${expected}", found ${JSON.stringify(received) ?? "nothing"}.`,
+		);
+		this.expected = expected;
+		this.received = received;
+	}
+}
+
+export class ConfigVersionError extends ConfigReadError {
+	readonly code = ConfigReadErrorCode.UnsupportedVersion;
+	readonly documentVersion: number;
+	readonly supportedVersion: number;
+
+	constructor(documentVersion: number, supportedVersion: number) {
+		super(
+			documentVersion > supportedVersion
+				? `Document schemaVersion ${documentVersion} was written by a newer reader; this one reads up to ${supportedVersion}. Upgrade before importing.`
+				: `Document schemaVersion ${documentVersion} has no migration to ${supportedVersion}.`,
+		);
+		this.documentVersion = documentVersion;
+		this.supportedVersion = supportedVersion;
+	}
+}
+
+export class ConfigUnknownKeysError extends ConfigReadError {
+	readonly code = ConfigReadErrorCode.UnknownKeys;
+	readonly keys: readonly string[];
+	readonly path: string;
+
+	constructor(path: string, keys: readonly string[]) {
+		super(
+			`Unknown ${keys.length === 1 ? "key" : "keys"} at ${path}: ${keys.join(", ")}. A document this reader does not fully understand is refused rather than partly applied.`,
+		);
+		this.keys = keys;
+		this.path = path;
+	}
+}
+
+/**
+ * A configuration document is a description of accounts, never a copy of their
+ * secrets. A file carrying one is refused outright: importing it would move a
+ * credential through a channel that was never meant to hold one, and silently
+ * dropping the field would teach the exporter that writing it is harmless.
+ */
+export class ConfigCredentialError extends ConfigReadError {
+	readonly code = ConfigReadErrorCode.CredentialPresent;
+	readonly keys: readonly string[];
+	readonly path: string;
+
+	constructor(path: string, keys: readonly string[]) {
+		super(
+			`Credential ${keys.length === 1 ? "field" : "fields"} at ${path}: ${keys.join(", ")}. A configuration document declares which credential an account needs; it never carries one.`,
+		);
+		this.keys = keys;
+		this.path = path;
+	}
+}
+
+export class ConfigMalformedError extends ConfigReadError {
+	readonly code = ConfigReadErrorCode.Malformed;
+	readonly issues: readonly $ZodIssue[];
+
+	constructor(issues: readonly $ZodIssue[]) {
+		super(
+			`Configuration document does not match schema version: ${issues
+				.map((issue) => `${formatPath(issue.path)}: ${issue.message}`)
+				.join("; ")}`,
+		);
+		this.issues = issues;
+	}
+}
+
+export function formatPath(path: readonly PropertyKey[]): string {
+	if (path.length === 0) return "(document root)";
+	return path
+		.map((segment) =>
+			typeof segment === "number" ? `[${segment}]` : `.${String(segment)}`,
+		)
+		.join("")
+		.replace(/^\./, "");
+}