@remit/drizzle-service 0.0.45 → 0.0.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/drizzle-service",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "description": "Drizzle ORM service over SQLite",
   "type": "module",
   "main": "src/index.ts",

package/src/repair/address-display-name.sqlite.test.ts

@@ -0,0 +1,280 @@
+/**
+ * The repair against the shape a deployment actually runs: the committed
+ * `CREATE TABLE` blocks, not a schema pushed from the drizzle table objects.
+ *
+ * What this has to hold, on a live database with no second copy of the data:
+ * every name the harvest guard would keep survives, a name that says something
+ * besides the address keeps that something, no row is removed, and a second run
+ * writes nothing.
+ */
+
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { storedDisplayName } from "@remit/data-ports/display-name";
+import Database from "better-sqlite3";
+import { shippedTableDdl } from "../test-shipped-sqlite-schema.js";
+import {
+	type DisplayNameRepairClient,
+	EMBEDDED_ADDRESS_LIKE,
+	sweepDisplayNames,
+} from "./address-display-name.js";
+
+const SPOOF = "aramirez@secresaludguaviare.gov.co";
+
+const clientOver = (sqlite: Database.Database): DisplayNameRepairClient => ({
+	all: async (sql, params) => sqlite.prepare(sql).all(...params),
+	run: async (sql, params) => sqlite.prepare(sql).run(...params).changes,
+});
+
+const seed = (sqlite: Database.Database): void => {
+	sqlite.exec(shippedTableDdl("0000_happy_roland_deschain", "address"));
+	sqlite.exec(
+		shippedTableDdl("0000_happy_roland_deschain", "envelope_address"),
+	);
+	sqlite.exec(shippedTableDdl("0000_happy_roland_deschain", "thread_message"));
+
+	const address = sqlite.prepare(
+		`INSERT INTO address (
+			address_id, account_config_id, display_name, local_part, domain,
+			normalized_email, normalized_compound, flags, inbound_count,
+			outbound_count, reply_count, last_inbound_at, last_outbound_at,
+			last_reply_at, created_at, updated_at
+		) VALUES (?, 'cfg-1', ?, 'x', 'y', ?, ?, '{}', 0, 0, 0, 0, NULL, 0, 0, 0)`,
+	);
+	const addressRow = (id: string, name: string | null, email: string): void => {
+		address.run(
+			id,
+			name,
+			email,
+			`${(name ?? "").toLowerCase()} ${email}`.trim(),
+		);
+	};
+
+	addressRow("spoof", "matthijs@ischen.nl", SPOOF);
+	addressRow("embedded", "Matthijs <matthijs@ischen.nl>", SPOOF);
+	addressRow("tabbed", "Support\tmatthijs@ischen.nl", SPOOF);
+	addressRow("parenthesised", "Support (support@acme.com)", "noreply@acme.com");
+	addressRow("comma", "matthijs@ischen.nl, team", SPOOF);
+	addressRow("semicolon", "Team; matthijs@ischen.nl", SPOOF);
+	addressRow("self", "ing@ing-nl-mailing.nl", "ing@ing-nl-mailing.nl");
+	addressRow("self-cased", "Matthijs@Ischen.nl", "matthijs@ischen.nl");
+	addressRow("self-diacritic", "Özcan@example.com", "özcan@example.com");
+	addressRow("self-in-name", "Özcan <Özcan@example.com>", "özcan@example.com");
+	addressRow("human", "Matthijs van Henten", "matthijs@ischen.nl");
+	addressRow("absent", null, "quiet@example.com");
+	addressRow("blank", "", "blank@example.com");
+
+	const envelope = sqlite.prepare(
+		`INSERT INTO envelope_address (
+			envelope_address_id, message_id, address_id, display_name,
+			normalized_email, address_role, address_order, created_at, updated_at
+		) VALUES (?, 'msg-1', 'addr-1', ?, ?, 'From', 0, 0, 0)`,
+	);
+	envelope.run("env-spoof", "matthijs@ischen.nl", SPOOF);
+	envelope.run("env-self", "Özcan@example.com", "özcan@example.com");
+	envelope.run("env-human", "Matthijs van Henten", "matthijs@ischen.nl");
+
+	const thread = sqlite.prepare(
+		`INSERT INTO thread_message (
+			thread_message_id, thread_id, message_id, account_config_id, mailbox_id,
+			uid, reference_order, from_email, from_name, subject, internal_date,
+			sent_date, is_read, has_attachment, has_stars, is_deleted,
+			created_at, updated_at
+		) VALUES (?, 'thr-1', 'msg-1', 'cfg-1', 'mbx-1', 1, 0, ?, ?, 's', 0, 0, 0, 0, 0, 0, 0, 0)`,
+	);
+	thread.run("thr-spoof", SPOOF, "matthijs@ischen.nl");
+	thread.run("thr-named", SPOOF, "Support <matthijs@ischen.nl>");
+	thread.run("thr-unparseable", null, "matthijs@ischen.nl");
+	thread.run("thr-human", SPOOF, "Alejandro Ramirez");
+};
+
+describe("rewriting display names that claim another address", () => {
+	let sqlite: Database.Database;
+	let client: DisplayNameRepairClient;
+
+	before(() => {
+		sqlite = new Database(":memory:");
+		seed(sqlite);
+		client = clientOver(sqlite);
+	});
+
+	after(() => {
+		sqlite.close();
+	});
+
+	const nameOf = (id: string): string | null =>
+		(
+			sqlite
+				.prepare("SELECT display_name AS n FROM address WHERE address_id = ?")
+				.get(id) as { n: string | null }
+		).n;
+
+	test("check writes nothing and counts what repair would rewrite", async () => {
+		const report = await sweepDisplayNames(client, "check");
+
+		assert.equal(report.claiming, 10);
+		assert.deepEqual(
+			report.sites.map((site) => [site.table, site.claiming, site.rewritten]),
+			[
+				["address", 6, 0],
+				["envelope_address", 1, 0],
+				["thread_message", 3, 0],
+			],
+		);
+		assert.equal(nameOf("spoof"), "matthijs@ischen.nl");
+	});
+
+	test("repair rewrites exactly those rows", async () => {
+		const report = await sweepDisplayNames(client, "repair");
+
+		assert.deepEqual(
+			report.sites.map((site) => [site.table, site.rewritten]),
+			[
+				["address", 6],
+				["envelope_address", 1],
+				["thread_message", 3],
+			],
+		);
+	});
+
+	test("empties a name that is nothing but another address", () => {
+		assert.equal(nameOf("spoof"), "");
+	});
+
+	test("keeps the text a name carries besides the address", () => {
+		const kept: ReadonlyArray<readonly [string, string]> = [
+			["embedded", "Matthijs"],
+			["tabbed", "Support"],
+			["parenthesised", "Support"],
+			["comma", "team"],
+			["semicolon", "Team"],
+		];
+		for (const [id, remainder] of kept) {
+			assert.equal(nameOf(id), remainder, id);
+		}
+	});
+
+	test("rebuilds the search compound the way the app writes it", () => {
+		const rows = sqlite
+			.prepare(
+				"SELECT address_id AS id, normalized_compound AS c FROM address WHERE address_id IN ('spoof', 'embedded') ORDER BY address_id",
+			)
+			.all() as Array<{ id: string; c: string }>;
+		assert.deepEqual(
+			rows.map((row) => [row.id, row.c]),
+			[
+				["embedded", `matthijs ${SPOOF}`],
+				["spoof", SPOOF],
+			],
+		);
+	});
+
+	test("keeps every name the harvest guard keeps", () => {
+		const kept: ReadonlyArray<readonly [string, string | null]> = [
+			["self", "ing@ing-nl-mailing.nl"],
+			["self-cased", "Matthijs@Ischen.nl"],
+			["self-diacritic", "Özcan@example.com"],
+			["self-in-name", "Özcan <Özcan@example.com>"],
+			["human", "Matthijs van Henten"],
+			["absent", null],
+			["blank", ""],
+		];
+		for (const [id, name] of kept) {
+			assert.equal(nameOf(id), name, id);
+		}
+	});
+
+	test("clears the From line the message header renders", () => {
+		const rows = sqlite
+			.prepare(
+				"SELECT envelope_address_id AS id, display_name AS n FROM envelope_address ORDER BY envelope_address_id",
+			)
+			.all() as Array<{ id: string; n: string | null }>;
+		assert.deepEqual(rows, [
+			{ id: "env-human", n: "Matthijs van Henten" },
+			{ id: "env-self", n: "Özcan@example.com" },
+			{ id: "env-spoof", n: "" },
+		]);
+	});
+
+	test("clears the sender label in the message list", () => {
+		const rows = sqlite
+			.prepare(
+				"SELECT thread_message_id AS id, from_name AS n FROM thread_message ORDER BY thread_message_id",
+			)
+			.all() as Array<{ id: string; n: string | null }>;
+		assert.deepEqual(rows, [
+			{ id: "thr-human", n: "Alejandro Ramirez" },
+			{ id: "thr-named", n: "Support" },
+			{ id: "thr-spoof", n: null },
+			{ id: "thr-unparseable", n: null },
+		]);
+	});
+
+	test("removes no row", () => {
+		for (const [table, count] of [
+			["address", 13],
+			["envelope_address", 3],
+			["thread_message", 4],
+		] as const) {
+			const row = sqlite
+				.prepare(`SELECT count(*) AS n FROM ${table}`)
+				.get() as {
+				n: number;
+			};
+			assert.equal(row.n, count, table);
+		}
+	});
+
+	test("a second run writes nothing", async () => {
+		const report = await sweepDisplayNames(client, "repair");
+		assert.equal(report.claiming, 0);
+	});
+});
+
+/**
+ * The SQL in this repair narrows; it never decides. That only holds if no name
+ * the rule rewrites can slip past the narrowing — the case where a planted name
+ * would survive the sweep unseen.
+ */
+describe("the SQL narrowing is a superset of the rule", () => {
+	test("selects every name the rule rewrites", () => {
+		const sqlite = new Database(":memory:");
+		sqlite.exec("CREATE TABLE probe (name text)");
+		const insert = sqlite.prepare("INSERT INTO probe VALUES (?)");
+		const names = [
+			"matthijs@ischen.nl",
+			"Matthijs <matthijs@ischen.nl>",
+			"Support (support@acme.com)",
+			"Support\tmatthijs@ischen.nl",
+			"Support matthijs@ischen.nl",
+			"Support​matthijs@ischen.nl",
+			"prvs=0068b51f37=matthijs@ischen.nl",
+			'"matthijs@ischen.nl"',
+			"matthijs@ischen.nl, team",
+			"Team; matthijs@ischen.nl",
+			"Özcan@example.com",
+			"MATTHIJS@ISCHEN.NL",
+			"matthijs@mail.ischen.nl",
+			"Matthijs van Henten",
+			"me @ home",
+			"a@b.c",
+			"",
+		];
+		for (const name of names) insert.run(name);
+
+		const selected = new Set(
+			(
+				sqlite
+					.prepare("SELECT name FROM probe WHERE name LIKE ?")
+					.all(EMBEDDED_ADDRESS_LIKE) as Array<{ name: string }>
+			).map((row) => row.name),
+		);
+		sqlite.close();
+
+		for (const name of names) {
+			if (storedDisplayName(name, "nobody@example.org") === name) continue;
+			assert.equal(selected.has(name), true, name);
+		}
+	});
+});

package/src/repair/address-display-name.ts

@@ -0,0 +1,200 @@
+import { storedDisplayName } from "@remit/data-ports/display-name";
+
+/**
+ * Rewriting the display names a spoofing sender already planted (issue #826).
+ *
+ * The harvest guard only decides what is stored from now on. Every name already
+ * written stays live, and none of the three write paths repairs one on a
+ * re-sync: `upsertAddress` refuses to overwrite a name with an empty one,
+ * `upsertEnvelopeAddress` is `onConflictDoNothing`, and a ThreadMessage is
+ * created once. On the instance that was hit there were 150 email-shaped
+ * display names in `address` alone, 30 of them naming a different address.
+ *
+ * The decision is `storedDisplayName` and nothing else. Expressing it a second
+ * time in SQL is what makes this dangerous: SQLite's `lower()` folds ASCII
+ * where JS folds all of Unicode, and its `trim()` and a literal space in a GLOB
+ * know only U+0020, so a SQL twin rewrites `Özcan@example.com` on
+ * `özcan@example.com` and `foo\tbar@baz.com` on anything — names the guard
+ * keeps, destroyed on a database holding the only copy. SQL narrows the scan
+ * and never decides.
+ *
+ * This is a repair rather than a migration because a migration is SQL, and SQL
+ * is exactly what must not hold the rule. It is convergent: a name the guard
+ * would keep is never rewritten twice, so re-running it, or resuming it after a
+ * crash part-way through, writes only what is left to write.
+ */
+
+export interface DisplayNameRepairClient {
+	all(sql: string, params: readonly unknown[]): Promise<unknown[]>;
+	run(sql: string, params: readonly unknown[]): Promise<number>;
+}
+
+export type DisplayNameRepairMode = "check" | "repair";
+
+/**
+ * The scan narrows to names that could carry an address at all: everything
+ * `storedDisplayName` rewrites contains `x@y.zz`, so a row this misses cannot
+ * be claiming anything. It is a filter, never the decision — the pairing is
+ * pinned by a test that runs both halves over the same strings.
+ */
+export const EMBEDDED_ADDRESS_LIKE = "%_@_%.__%";
+
+interface RepairSite {
+	readonly table: string;
+	readonly key: string;
+	readonly name: string;
+	readonly email: string;
+	/** The compound the search path reads, where the table keeps one. */
+	readonly compound?: string;
+	/** What the write path stores for an absent name on this table. */
+	readonly absent: "" | null;
+}
+
+/**
+ * Every column an attacker-chosen name lands in. `address.display_name` is the
+ * one autocomplete reads; `envelope_address.display_name` is the From line the
+ * message header renders; `thread_message.from_name` is the sender label in the
+ * message list and the text the search index tokenizes.
+ */
+const SITES: readonly RepairSite[] = [
+	{
+		table: "address",
+		key: "address_id",
+		name: "display_name",
+		email: "normalized_email",
+		compound: "normalized_compound",
+		absent: "",
+	},
+	{
+		table: "envelope_address",
+		key: "envelope_address_id",
+		name: "display_name",
+		email: "normalized_email",
+		absent: "",
+	},
+	{
+		table: "thread_message",
+		key: "thread_message_id",
+		name: "from_name",
+		email: "from_email",
+		absent: null,
+	},
+];
+
+export interface SiteResult {
+	readonly table: string;
+	readonly scanned: number;
+	readonly claiming: number;
+	readonly rewritten: number;
+}
+
+export interface DisplayNameReport {
+	readonly mode: DisplayNameRepairMode;
+	readonly sites: readonly SiteResult[];
+	readonly claiming: number;
+}
+
+interface CandidateRow {
+	id: string;
+	name: string | null;
+	email: string | null;
+}
+
+const isCandidateRow = (row: unknown): row is CandidateRow =>
+	typeof row === "object" &&
+	row !== null &&
+	typeof (row as { id: unknown }).id === "string";
+
+const candidates = async (
+	client: DisplayNameRepairClient,
+	site: RepairSite,
+): Promise<CandidateRow[]> => {
+	const rows = await client.all(
+		`SELECT ${site.key} AS id, ${site.name} AS name, ${site.email} AS email
+		 FROM ${site.table}
+		 WHERE ${site.name} LIKE ?`,
+		[EMBEDDED_ADDRESS_LIKE],
+	);
+	return rows.filter(isCandidateRow);
+};
+
+/**
+ * One row at a time, because each row keeps a different remainder. The set is
+ * what a spoofing sender planted, not the table.
+ */
+const rewrite = async (
+	client: DisplayNameRepairClient,
+	site: RepairSite,
+	row: CandidateRow,
+	stored: string,
+): Promise<number> => {
+	const columns = [`${site.name} = ?`];
+	const params: unknown[] = [stored === "" ? site.absent : stored];
+
+	if (site.compound) {
+		columns.push(`${site.compound} = ?`);
+		params.push(`${stored.toLowerCase()} ${row.email ?? ""}`.trim());
+	}
+	params.push(row.id);
+
+	return client.run(
+		`UPDATE ${site.table} SET ${columns.join(", ")} WHERE ${site.key} = ?`,
+		params,
+	);
+};
+
+/**
+ * `check` writes nothing, so it can be pointed at a live instance; `repair`
+ * runs the same scan and rewrites what it finds. One code path, so the report
+ * can never describe a decision the repair does not make.
+ */
+export const sweepDisplayNames = async (
+	client: DisplayNameRepairClient,
+	mode: DisplayNameRepairMode,
+): Promise<DisplayNameReport> => {
+	const sites: SiteResult[] = [];
+
+	for (const site of SITES) {
+		const rows = await candidates(client, site);
+		let claiming = 0;
+		let rewritten = 0;
+
+		for (const row of rows) {
+			const name = row.name ?? "";
+			const stored = storedDisplayName(name, row.email ?? undefined);
+			if (stored === name) continue;
+			claiming += 1;
+			if (mode === "repair") {
+				rewritten += await rewrite(client, site, row, stored);
+			}
+		}
+
+		sites.push({
+			table: site.table,
+			scanned: rows.length,
+			claiming,
+			rewritten,
+		});
+	}
+
+	return {
+		mode,
+		sites,
+		claiming: sites.reduce((sum, site) => sum + site.claiming, 0),
+	};
+};
+
+export const formatDisplayNameReport = (
+	report: DisplayNameReport,
+): string[] => {
+	if (report.claiming === 0) {
+		return ["no display name claims another address"];
+	}
+	return report.sites
+		.filter((site) => site.claiming > 0)
+		.map(
+			(site) =>
+				`${site.table}: ${site.claiming} of ${site.scanned} scanned name(s) claim another address` +
+				(report.mode === "repair" ? `, ${site.rewritten} rewritten` : ""),
+		);
+};

package/src/repair/stranded-sent-outbox.sqlite.test.ts

@@ -0,0 +1,117 @@
+/**
+ * The repair against the shape a deployment actually runs: the committed
+ * `CREATE TABLE` block, not a schema pushed from the drizzle table objects.
+ *
+ * What it has to hold on a live database: a message whose filing is still in
+ * flight is left alone, a stranded one becomes visible, no row is removed, and
+ * a second run writes nothing.
+ */
+
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import Database from "better-sqlite3";
+import { shippedTableDdl } from "../test-shipped-sqlite-schema.js";
+import {
+	STRANDED_AFTER_MILLIS,
+	type StrandedSentRepairClient,
+	sweepStrandedSentOutbox,
+} from "./stranded-sent-outbox.js";
+
+const clientOver = (sqlite: Database.Database): StrandedSentRepairClient => ({
+	all: async (sql, params) => sqlite.prepare(sql).all(...params),
+	run: async (sql, params) => sqlite.prepare(sql).run(...params).changes,
+});
+
+interface Row {
+	status: string;
+	last_error: string | null;
+}
+
+describe("outbox rows stranded at sent", () => {
+	let sqlite: Database.Database;
+
+	const insert = (
+		outboxMessageId: string,
+		status: string,
+		sentAt: number,
+	): void => {
+		sqlite
+			.prepare(
+				`INSERT INTO outbox_message (
+					outbox_message_id, account_id, account_config_id, from_address,
+					to_addresses, cc_addresses, bcc_addresses, "references",
+					message_id_value, status, sent_at, created_at, updated_at
+				) VALUES (?, 'acc', 'cfg', 'me@example.com', '["you@example.com"]',
+					'[]', '[]', '[]', 'mid@example.com', ?, ?, ?, ?)`,
+			)
+			.run(outboxMessageId, status, sentAt, sentAt, sentAt);
+	};
+
+	const read = (outboxMessageId: string): Row =>
+		sqlite
+			.prepare(
+				"SELECT status, last_error FROM outbox_message WHERE outbox_message_id = ?",
+			)
+			.get(outboxMessageId) as Row;
+
+	before(() => {
+		sqlite = new Database(":memory:");
+		sqlite.exec(
+			shippedTableDdl("0000_happy_roland_deschain", "outbox_message"),
+		);
+	});
+
+	after(() => {
+		sqlite.close();
+	});
+
+	test("makes a stranded sent message visible again", async () => {
+		const stranded = Date.now() - STRANDED_AFTER_MILLIS - 1000;
+		insert("stranded", "sent", stranded);
+
+		const report = await sweepStrandedSentOutbox(clientOver(sqlite), "repair");
+
+		assert.equal(report.stranded, 1);
+		assert.equal(report.settled, 1);
+		const row = read("stranded");
+		assert.equal(row.status, "unfiled");
+		assert.match(String(row.last_error), /not filed/);
+	});
+
+	test("a second run writes nothing", async () => {
+		const report = await sweepStrandedSentOutbox(clientOver(sqlite), "repair");
+
+		assert.equal(report.stranded, 0);
+		assert.equal(report.settled, 0);
+	});
+
+	test("leaves a filing that is still in flight alone", async () => {
+		insert("in-flight", "sent", Date.now());
+
+		const report = await sweepStrandedSentOutbox(clientOver(sqlite), "repair");
+
+		assert.equal(report.stranded, 0);
+		assert.equal(read("in-flight").status, "sent");
+	});
+
+	test("touches no other status", async () => {
+		const old = Date.now() - STRANDED_AFTER_MILLIS - 1000;
+		insert("a-draft", "draft", old);
+		insert("a-failure", "failed", old);
+
+		await sweepStrandedSentOutbox(clientOver(sqlite), "repair");
+
+		assert.equal(read("a-draft").status, "draft");
+		assert.equal(read("a-failure").status, "failed");
+	});
+
+	test("check mode reports what it would do and writes nothing", async () => {
+		insert("also-stranded", "sent", Date.now() - STRANDED_AFTER_MILLIS - 1000);
+
+		const report = await sweepStrandedSentOutbox(clientOver(sqlite), "check");
+
+		assert.equal(report.stranded, 1);
+		assert.equal(report.settled, 0);
+		assert.equal(read("also-stranded").status, "sent");
+	});
+});

package/src/repair/stranded-sent-outbox.ts

@@ -0,0 +1,109 @@
+/**
+ * The repair for outbox rows stranded at `sent` (issue #824).
+ *
+ * A row holds `sent` only between SMTP accepting the message and the IMAP
+ * APPEND that files a copy in Sent, whose last act is to delete the row. Every
+ * way that APPEND could fail used to end in a silent return, so the row stayed
+ * at `sent` forever — and `sent` is the one non-draft status the Outbox list
+ * hides, on the assumption that the APPEND deletes it. The message was
+ * delivered, exists in no server folder, and appears in no view.
+ *
+ * The handler now settles those failures as `unfiled`. That reaches nothing
+ * already stranded: the events are long gone, and the rows are on instances
+ * that only an image update reaches. So the same settlement is applied here,
+ * once, at boot — the migrate one-shot is the only step every self-host
+ * instance runs before its app containers start (#281).
+ *
+ * The age bound is what separates a stranded row from an ordinary one. A
+ * message sent seconds before a restart has its APPEND event still queued, and
+ * that event settles the row itself once the workers come back; rewriting it
+ * here would take a filing that was about to succeed. An hour is far past any
+ * redrive budget, so a row older than that has no event coming.
+ *
+ * It is a status flip and an error string, on rows whose only other outcome is
+ * to stay invisible. Nothing is deleted and no message content is touched.
+ */
+
+/**
+ * The smallest surface this needs, so the module imports no schema and no
+ * driver and can be driven by the migrator's `better-sqlite3` handle or a test.
+ */
+export interface StrandedSentRepairClient {
+	all(sql: string, params: unknown[]): Promise<unknown[]>;
+	run(sql: string, params: unknown[]): Promise<number>;
+}
+
+export type StrandedSentRepairMode = "check" | "repair";
+
+export type StrandedSentReport = {
+	readonly mode: StrandedSentRepairMode;
+	readonly stranded: number;
+	readonly settled: number;
+};
+
+/**
+ * One hour. A row younger than this may still have its APPEND event in the
+ * queue, and that event settles the row correctly on its own.
+ */
+export const STRANDED_AFTER_MILLIS = 60 * 60 * 1000;
+
+const STRANDED_SENT_REASON =
+	"Sent, but not filed: filing a copy in the Sent folder never completed. The message was delivered.";
+
+const NOW_MILLIS = "CAST(unixepoch('subsec') * 1000 AS INTEGER)";
+
+const AGE = `coalesce(sent_at, updated_at) < ${NOW_MILLIS} - ?`;
+
+const COUNT_SQL = `SELECT count(*) AS row_count
+FROM outbox_message
+WHERE status = 'sent' AND ${AGE}`;
+
+const SETTLE_SQL = `UPDATE outbox_message
+SET status = 'unfiled', last_error = ?
+WHERE status = 'sent' AND ${AGE}`;
+
+const countStranded = async (
+	client: StrandedSentRepairClient,
+): Promise<number> => {
+	const [row] = (await client.all(COUNT_SQL, [STRANDED_AFTER_MILLIS])) as {
+		row_count: number;
+	}[];
+	return row?.row_count ?? 0;
+};
+
+/**
+ * The UPDATE runs only when the count found rows. SQLite takes its exclusive
+ * write lock the moment an UPDATE begins, before it can know the WHERE matches
+ * nothing, and a lock the migrator cannot get inside its `busy_timeout` fails
+ * the migration and holds every gated service down. Zero is the steady state.
+ */
+export const sweepStrandedSentOutbox = async (
+	client: StrandedSentRepairClient,
+	mode: StrandedSentRepairMode,
+): Promise<StrandedSentReport> => {
+	const stranded = await countStranded(client);
+	if (mode === "check" || stranded === 0) {
+		return { mode, stranded, settled: 0 };
+	}
+	const settled = await client.run(SETTLE_SQL, [
+		STRANDED_SENT_REASON,
+		STRANDED_AFTER_MILLIS,
+	]);
+	return { mode, stranded, settled };
+};
+
+export const formatStrandedSentReport = (
+	report: StrandedSentReport,
+): string[] => {
+	if (report.stranded === 0) {
+		return ["No sent message is stranded in the outbox"];
+	}
+	if (report.mode === "check") {
+		return [
+			`${report.stranded} sent message(s) stranded in the outbox, would be marked unfiled`,
+		];
+	}
+	return [
+		`${report.settled} of ${report.stranded} stranded sent message(s) marked unfiled`,
+	];
+};