@remit/backend 0.0.26 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

package/src/handlers/index.ts

@@ -16,6 +16,7 @@ import { OrganizeJobDetailOperations, OrganizeOperations } from "./organize.js";
 import { OutboxDetailOperations, OutboxOperations } from "./outbox.js";
 import { SemanticSearchOperations } from "./search.js";
 import { SyncOperations } from "./sync.js";
+import { SystemOperations } from "./system-update.js";
 import { ThreadDetailOperations, ThreadOperations } from "./thread.js";
 import { UnifiedThreadOperations } from "./unified-threads.js";
 
@@ -23,6 +24,7 @@ import { UnifiedThreadOperations } from "./unified-threads.js";
 export const handlers: Record<OperationIds, OperationHandler<any>> = {
 	...MeOperations,
 	...ConfigOperations,
+	...SystemOperations,
 	...AccountOperations,
 	...AccountDetailOperations,
 	...MicrosoftOAuthOperations,

package/src/handlers/system-update.test.ts

@@ -0,0 +1,348 @@
+import assert from "node:assert/strict";
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { createInstanceOwnerStore } from "@remit/auth-service";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import Database from "better-sqlite3";
+import type { Context } from "openapi-backend";
+import { SystemOperations } from "./system-update.js";
+
+const tmpRoot = join(
+	fileURLToPath(new URL(".", import.meta.url)),
+	"..",
+	"..",
+	".tmp",
+	"system-update",
+);
+
+const readMigrationSql = (relativePath: string): string =>
+	readFileSync(fileURLToPath(new URL(relativePath, import.meta.url)), "utf8");
+
+const authMigrationSql = readMigrationSql(
+	"../../../../deploy/vps/migrations-sqlite/auth/0000_rainy_iron_monger.sql",
+);
+const metaMigrationSql = readMigrationSql(
+	"../../../../deploy/vps/migrations-sqlite/meta/0000_demonic_lilith.sql",
+);
+
+const OWNER = "the-owner";
+const MANIFEST_URL = "https://updates.example.com/stable.json";
+
+let dbPath: string;
+let controlDir: string;
+
+const okState = {
+	currentVersion: "v1.4.1",
+	check: {
+		status: "ok",
+		lastCheckedAt: "2026-07-20T08:00:00Z",
+		latestVersion: "v1.5.0",
+		publishedAt: "2026-07-18T09:00:00Z",
+		summary: "Faster search.",
+		releaseNotesUrl: "https://example.com/notes",
+		updateAvailable: true,
+	},
+	run: null,
+};
+
+const writeState = (state: unknown): void => {
+	writeFileSync(join(controlDir, "state.json"), JSON.stringify(state));
+};
+
+before(async () => {
+	mkdirSync(tmpRoot, { recursive: true });
+	dbPath = join(mkdtempSync(join(tmpRoot, "db-")), "app.db");
+	const sqlite = new Database(dbPath);
+	for (const sql of [authMigrationSql, metaMigrationSql]) {
+		for (const statement of sql.split("--> statement-breakpoint")) {
+			sqlite.exec(statement);
+		}
+	}
+	sqlite
+		.prepare(
+			"INSERT INTO auth_user (id, name, email, email_verified, created_at, updated_at) VALUES (?, ?, ?, 0, ?, ?)",
+		)
+		.run(OWNER, OWNER, "owner@example.com", 1000, 1000);
+	sqlite.close();
+	process.env.DATA_BACKEND = "sqlite";
+	process.env.SQLITE_DB_PATH = dbPath;
+	const store = await createInstanceOwnerStore({
+		provider: "sqlite",
+		connectionString: dbPath,
+	});
+	await store.claimIfUnclaimed(OWNER);
+	await store.close();
+});
+
+after(() => {
+	rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+	controlDir = mkdtempSync(join(tmpRoot, "control-"));
+	process.env.REMIT_UPDATE_CONTROL_DIR = controlDir;
+	process.env.REMIT_UPDATE_MANIFEST_URL = MANIFEST_URL;
+	process.env.REMIT_TAG = "v1.4.1";
+});
+
+afterEach(() => {
+	delete process.env.REMIT_UPDATE_MANIFEST_URL;
+	delete process.env.REMIT_UPDATE_CONTROL_DIR;
+	delete process.env.REMIT_TAG;
+});
+
+const buildEvent = (sub?: string): APIGatewayProxyEvent =>
+	({
+		headers: {},
+		requestContext: sub ? { authorizer: { claims: { sub } } } : {},
+	}) as unknown as APIGatewayProxyEvent;
+
+const postContext = (targetVersion: string): Context =>
+	({ request: { requestBody: { targetVersion } } }) as unknown as Context;
+
+const getSystemUpdate =
+	SystemOperations.SystemOperations_getSystemUpdate as unknown as (
+		context: Context,
+		event: APIGatewayProxyEvent,
+	) => Promise<unknown>;
+
+const applySystemUpdate =
+	SystemOperations.SystemOperations_applySystemUpdate as unknown as (
+		context: Context,
+		event: APIGatewayProxyEvent,
+	) => Promise<unknown>;
+
+const getUpdate = (event: APIGatewayProxyEvent) =>
+	getSystemUpdate({} as unknown as Context, event);
+
+const applyUpdate = (targetVersion: string, event: APIGatewayProxyEvent) =>
+	applySystemUpdate(postContext(targetVersion), event);
+
+const hasStatus = (value: unknown, code: number): boolean =>
+	typeof value === "object" &&
+	value !== null &&
+	(value as { statusCode?: number }).statusCode === code;
+
+describe("GET /system/update", () => {
+	it("returns 404 when no manifest URL is configured", async () => {
+		delete process.env.REMIT_UPDATE_MANIFEST_URL;
+
+		const result = await getUpdate(buildEvent(OWNER));
+
+		assert.ok(hasStatus(result, 404));
+	});
+
+	it("returns 403 for a non-owner", async () => {
+		const result = await getUpdate(buildEvent("someone-else"));
+
+		assert.ok(hasStatus(result, 403));
+	});
+
+	it("returns 200 with the state file verbatim", async () => {
+		writeState(okState);
+
+		const result = await getUpdate(buildEvent(OWNER));
+
+		assert.deepEqual(result, okState);
+	});
+
+	it("returns a disabled, empty resource when no state file exists", async () => {
+		const result = await getUpdate(buildEvent(OWNER));
+
+		assert.deepEqual(result, {
+			currentVersion: "v1.4.1",
+			check: { status: "disabled" },
+			run: null,
+		});
+	});
+
+	it("returns 200 with the run block untouched when the check has failed", async () => {
+		const run = {
+			runId: "run-1",
+			fromVersion: "v1.3.0",
+			targetVersion: "v1.4.1",
+			phase: "committing",
+			outcome: "succeeded",
+			startedAt: "2026-07-19T08:00:00Z",
+			updatedAt: "2026-07-19T08:05:00Z",
+			message: "Update installed.",
+			logCommand: "remit logs backend",
+		};
+		writeState({
+			currentVersion: "v1.4.1",
+			check: {
+				status: "failed",
+				lastCheckedAt: "2026-07-20T08:00:00Z",
+				error: "The update manifest could not be fetched.",
+			},
+			run,
+		});
+
+		const result = (await getUpdate(buildEvent(OWNER))) as {
+			check: { status: string };
+			run: unknown;
+		};
+
+		assert.equal(result.check.status, "failed");
+		assert.deepEqual(result.run, run);
+	});
+
+	it("passes both schema-version fields through when the state file carries them", async () => {
+		writeState({
+			currentVersion: "v1.4.1",
+			currentSchemaVersion: 5,
+			check: { ...okState.check, schemaVersion: 6 },
+			run: null,
+		});
+
+		const result = (await getUpdate(buildEvent(OWNER))) as {
+			currentSchemaVersion?: number;
+			check: { schemaVersion?: number };
+		};
+
+		assert.equal(result.currentSchemaVersion, 5);
+		assert.equal(result.check.schemaVersion, 6);
+	});
+
+	it("omits both schema-version fields when the state file predates them", async () => {
+		writeState(okState);
+
+		const result = (await getUpdate(buildEvent(OWNER))) as {
+			currentSchemaVersion?: number;
+			check: { schemaVersion?: number };
+		};
+
+		assert.ok(!("currentSchemaVersion" in result));
+		assert.ok(!("schemaVersion" in result.check));
+	});
+
+	it("carries currentSchemaVersion alone when the check has no schema version", async () => {
+		writeState({
+			currentVersion: "v1.4.1",
+			currentSchemaVersion: 5,
+			check: okState.check,
+			run: null,
+		});
+
+		const result = (await getUpdate(buildEvent(OWNER))) as {
+			currentSchemaVersion?: number;
+			check: { schemaVersion?: number };
+		};
+
+		assert.equal(result.currentSchemaVersion, 5);
+		assert.ok(!("schemaVersion" in result.check));
+	});
+
+	it("carries check.schemaVersion alone when currentSchemaVersion is absent", async () => {
+		writeState({
+			currentVersion: "v1.4.1",
+			check: { ...okState.check, schemaVersion: 6 },
+			run: null,
+		});
+
+		const result = (await getUpdate(buildEvent(OWNER))) as {
+			currentSchemaVersion?: number;
+			check: { schemaVersion?: number };
+		};
+
+		assert.ok(!("currentSchemaVersion" in result));
+		assert.equal(result.check.schemaVersion, 6);
+	});
+});
+
+describe("POST /system/update", () => {
+	it("returns 404 when no manifest URL is configured", async () => {
+		delete process.env.REMIT_UPDATE_MANIFEST_URL;
+
+		const result = await applyUpdate("v1.5.0", buildEvent(OWNER));
+
+		assert.ok(hasStatus(result, 404));
+	});
+
+	it("returns 403 for a non-owner", async () => {
+		writeState(okState);
+
+		const result = await applyUpdate("v1.5.0", buildEvent("someone-else"));
+
+		assert.ok(hasStatus(result, 403));
+	});
+
+	it("returns 409 when a run is already in flight", async () => {
+		writeState({
+			...okState,
+			run: {
+				runId: "run-9",
+				fromVersion: "v1.4.1",
+				targetVersion: "v1.5.0",
+				phase: "verifying",
+				outcome: null,
+				startedAt: "2026-07-20T08:01:00Z",
+				updatedAt: "2026-07-20T08:04:00Z",
+				message: "Waiting for the new version to answer.",
+				logCommand: "remit logs backend",
+			},
+		});
+
+		await assert.rejects(applyUpdate("v1.5.0", buildEvent(OWNER)), {
+			statusCode: 409,
+		});
+	});
+
+	it("returns 422 when the target is not the checked version", async () => {
+		writeState(okState);
+
+		await assert.rejects(applyUpdate("v9.9.9", buildEvent(OWNER)), {
+			statusCode: 422,
+		});
+	});
+
+	it("returns 422 when no check has ever succeeded", async () => {
+		await assert.rejects(applyUpdate("v1.5.0", buildEvent(OWNER)), {
+			statusCode: 422,
+		});
+	});
+
+	it("returns 202 with a run block carrying a fresh runId", async () => {
+		writeState(okState);
+
+		const result = (await applyUpdate("v1.5.0", buildEvent(OWNER))) as {
+			statusCode: number;
+			body: { run: { runId: string; targetVersion: string; outcome: null } };
+		};
+
+		assert.equal(result.statusCode, 202);
+		assert.equal(result.body.run.targetVersion, "v1.5.0");
+		assert.equal(result.body.run.outcome, null);
+		assert.ok(result.body.run.runId.length > 0);
+	});
+
+	it("writes request.json with exactly the four seam fields and nothing else", async () => {
+		writeState(okState);
+
+		await applyUpdate("v1.5.0", buildEvent(OWNER));
+
+		const request = JSON.parse(
+			readFileSync(join(controlDir, "request.json"), "utf8"),
+		);
+
+		assert.deepEqual(Object.keys(request).sort(), [
+			"requestedAt",
+			"requestedBy",
+			"runId",
+			"targetVersion",
+		]);
+		assert.equal(request.targetVersion, "v1.5.0");
+		assert.equal(request.requestedBy, OWNER);
+		for (const forbidden of ["registry", "image", "digest"]) {
+			assert.ok(!(forbidden in request));
+		}
+	});
+});

package/src/handlers/system-update.ts

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+	SystemUpdateResponse,
+	SystemUpdateRun,
+} from "@remit/api-openapi-types";
+import { ConflictError, HTTPError } from "@remit/data-ports/errors";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { getSubFromEvent } from "../auth.js";
+import type { OperationHandler, SystemOperationIds } from "../types.js";
+import { requireInstanceOwner } from "./owner-guard.js";
+
+class TargetVersionMismatchError extends HTTPError {
+	name = "TargetVersionMismatchError";
+	statusCode = 422;
+}
+
+const DEFAULT_CONTROL_DIR = "/data/control";
+
+const controlDir = (): string =>
+	process.env.REMIT_UPDATE_CONTROL_DIR ?? DEFAULT_CONTROL_DIR;
+
+const manifestUrl = (): string | undefined =>
+	process.env.REMIT_UPDATE_MANIFEST_URL;
+
+const currentVersion = (): string => process.env.REMIT_TAG ?? "unknown";
+
+const notFound = (): APIGatewayProxyResult => ({
+	statusCode: 404,
+	headers: { "Content-Type": "application/json" },
+	body: JSON.stringify({ message: "Not found" }),
+});
+
+/**
+ * The self-update seam is off unless a manifest URL is configured (RFC 037 D8),
+ * which the hosted deployment leaves unset. Both endpoints answer 404 in that
+ * case — before the owner guard, so a probe cannot tell an off surface from a
+ * forbidden one.
+ */
+const guardManifestConfigured = (): APIGatewayProxyResult | null =>
+	manifestUrl() ? null : notFound();
+
+/**
+ * Read `state.json` off the control volume. A missing file is an instance that
+ * has never checked or updated (RFC 037 D8), not an error, so it reads as
+ * `null`; the caller renders the disabled/empty resource. Any other read or
+ * parse failure propagates.
+ */
+const readState = (): SystemUpdateResponse | null => {
+	let raw: string;
+	try {
+		raw = readFileSync(join(controlDir(), "state.json"), "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+	return JSON.parse(raw) as SystemUpdateResponse;
+};
+
+const emptyResource = (): SystemUpdateResponse => ({
+	currentVersion: currentVersion(),
+	check: { status: "disabled" },
+	run: null,
+});
+
+const isRunInFlight = (run: SystemUpdateRun | null | undefined): boolean =>
+	run != null && run.outcome === null;
+
+/**
+ * The version the caller may install is the one the last check reported. It
+ * exists only on a successful check; a disabled or failed check offers nothing
+ * to match, so any target is a mismatch.
+ */
+const checkedVersion = (
+	state: SystemUpdateResponse | null,
+): string | undefined =>
+	state?.check.status === "ok" ? state.check.latestVersion : undefined;
+
+/**
+ * Write `request.json` atomically with exactly the four fields the seam accepts
+ * (#133). The updater resolves the registry and every image reference from the
+ * manifest it fetches itself; a request naming any of those is rejected whole,
+ * so the backend never writes one. The temp file sits in the same directory as
+ * the target for the rename to be atomic on one filesystem.
+ */
+const writeRequest = (request: {
+	runId: string;
+	targetVersion: string;
+	requestedAt: string;
+	requestedBy: string;
+}): void => {
+	const dir = controlDir();
+	const tmp = join(dir, `.request.json.${request.runId}.tmp`);
+	writeFileSync(tmp, JSON.stringify(request), { mode: 0o644 });
+	renameSync(tmp, join(dir, "request.json"));
+};
+
+/**
+ * The resource returned by the POST. The updater has not yet written the
+ * authoritative run — it polls the seam — so this bootstraps the run block with
+ * the id just requested and the first phase, giving the client a `runId` to
+ * persist and poll (RFC 037 D9). The updater's own `state.json` supersedes it on
+ * the next read.
+ */
+const requestedResource = (
+	state: SystemUpdateResponse | null,
+	runId: string,
+	targetVersion: string,
+	requestedAt: string,
+): SystemUpdateResponse => {
+	const from = state?.currentVersion ?? currentVersion();
+	return {
+		currentVersion: from,
+		check: state?.check ?? { status: "disabled" },
+		run: {
+			runId,
+			fromVersion: from,
+			targetVersion,
+			phase: "checking",
+			outcome: null,
+			startedAt: requestedAt,
+			updatedAt: requestedAt,
+			message: "The update has been requested.",
+			logCommand: "remit logs updater",
+		},
+	};
+};
+
+export const SystemOperations: Record<
+	SystemOperationIds,
+	OperationHandler<SystemOperationIds>
+> = {
+	SystemOperations_getSystemUpdate: async (
+		_context: Context,
+		...args: unknown[]
+	): Promise<SystemUpdateResponse | APIGatewayProxyResult> => {
+		const offSurface = guardManifestConfigured();
+		if (offSurface) return offSurface;
+
+		const event = args[0] as APIGatewayProxyEvent;
+		const forbidden = await requireInstanceOwner(event);
+		if (forbidden) return forbidden;
+
+		return readState() ?? emptyResource();
+	},
+
+	SystemOperations_applySystemUpdate: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<SystemUpdateResponse | APIGatewayProxyResult> => {
+		const offSurface = guardManifestConfigured();
+		if (offSurface) return offSurface;
+
+		const event = args[0] as APIGatewayProxyEvent;
+		const forbidden = await requireInstanceOwner(event);
+		if (forbidden) return forbidden;
+
+		const { targetVersion } = context.request.requestBody as {
+			targetVersion: string;
+		};
+		const state = readState();
+
+		if (isRunInFlight(state?.run)) {
+			throw new ConflictError("An update is already in progress.");
+		}
+
+		if (targetVersion !== checkedVersion(state)) {
+			throw new TargetVersionMismatchError(
+				"targetVersion does not match the latest checked release.",
+			);
+		}
+
+		const runId = randomUUID();
+		const requestedAt = new Date().toISOString();
+		writeRequest({
+			runId,
+			targetVersion,
+			requestedAt,
+			requestedBy: getSubFromEvent(event) ?? "",
+		});
+
+		return {
+			statusCode: 202,
+			body: requestedResource(state, runId, targetVersion, requestedAt),
+		} as unknown as APIGatewayProxyResult;
+	},
+};

package/src/types.ts

@@ -12,6 +12,8 @@ export type OperationIds =
 	| "MeOperations_getExport"
 	| "MeOperations_listQuarantine"
 	| "ConfigOperations_getConfig"
+	| "SystemOperations_getSystemUpdate"
+	| "SystemOperations_applySystemUpdate"
 	| "AccountOperations_createAccount"
 	| "AccountOperations_testConnection"
 	| "AccountDetailOperations_updateAccount"
@@ -60,6 +62,8 @@ export type MeOperationIds = MatchPrefix<"MeOperations_", OperationIds>;
 
 export type ConfigOperationIds = MatchPrefix<"ConfigOperations_", OperationIds>;
 
+export type SystemOperationIds = MatchPrefix<"SystemOperations_", OperationIds>;
+
 export type AccountOperationIds = MatchPrefix<
 	"AccountOperations_",
 	OperationIds