cursedbelt-server 1.0.0

package/src/server/incidents/notifier.ts

@@ -0,0 +1,215 @@
+/**
+ * Turning a state TRANSITION into a message, and sending it exactly once.
+ *
+ * Everything that decides "does the owner hear about this?" is here, and there
+ * is very little of it, because the hard part was done in `store.ts`: this
+ * module only ever sees `opened`, `escalated` and `resolved`. There is no
+ * de-duplication logic in this file and there must never be — a second dedupe,
+ * on a timer, is how a system ends up with two disagreeing answers to "have I
+ * already said this?".
+ *
+ * ── The message the owner actually gets ─────────────────────────────────────
+ * The owner's standing complaint about agent hand-offs is that they name a
+ * symptom, a command and a credential without saying what any of them are. So
+ * an incident message is three sentences with fixed jobs, in this order:
+ *
+ *   WHAT BROKE      — in words, naming the app. Assume he does not know what
+ *                     your daemon, flag, tab or port is.
+ *   WHAT IT BLOCKS  — what he cannot do until it is fixed. This is the sentence
+ *                     that earns a text message at 2am; if you cannot write it,
+ *                     the incident is a `warning`.
+ *   WHAT TO DO      — a next step. A command carries its own `cd`, because he
+ *                     opens terminals anywhere (`fleet/rules/
+ *                     commands-must-run-from-anywhere.md`).
+ *
+ * ── 🔴 What is deliberately NOT in a message ────────────────────────────────
+ * File names, note titles, vault keys, e-mail addresses, anything a person
+ * typed. `subject` is an identifier and `facts` are numbers, both enforced at
+ * the store (`assertNoContent`). A text message is the least private surface
+ * this fleet has and several of its apps are private by construction.
+ */
+import type { ChannelMessage, ChannelResult, IncidentChannel } from "./channels";
+import type { IncidentStore } from "./store";
+import type { Incident, IncidentTransitions } from "./types";
+
+export interface IncidentNotifier {
+	/** Send for every transition in `t`. Returns one result per message sent. */
+	announce: (t: IncidentTransitions) => Promise<AnnounceResult[]>;
+	/** The channels registered on this host, for the console's health row. */
+	readonly channels: readonly IncidentChannel[];
+}
+
+export interface AnnounceResult {
+	fingerprint: string;
+	transition: "opened" | "escalated" | "resolved";
+	results: ChannelResult[];
+}
+
+/**
+ * How long to wait before trying a BLOCKING incident again when no channel
+ * managed to deliver it.
+ *
+ * 🔴 This exists because of a real hole found on the first live sweep: `roms`'
+ * overdue backup opened as blocking while the email channel was still
+ * misconfigured, both channels failed, and — because `notifiedAt` was stamped —
+ * nothing would ever have tried again. The owner would have had a blocking
+ * incident on a board he had no reason to open. The dedupe promise is "you are
+ * told ONCE", not "we attempt once": an attempt that reached nobody has not told
+ * him anything.
+ *
+ * It retries at most hourly, and it STOPS the moment any channel reports
+ * `delivered` — so a permanently broken channel costs one send an hour, and a
+ * working one costs exactly one message, which is the guarantee.
+ */
+export const UNDELIVERED_RETRY_MS = 60 * 60 * 1000;
+
+/** Did any channel actually get it out? `skipped` is not delivery. */
+const wasDelivered = (notifyResult: string | null): boolean =>
+	Boolean(notifyResult?.includes("=delivered"));
+
+const factLine = (incident: Incident): string => {
+	const facts = Object.entries(incident.facts ?? {});
+	if (facts.length === 0) return "";
+	return `\n${facts.map(([k, v]) => `${k}: ${v}`).join(" · ")}`;
+};
+
+/** The message for a newly-open (or newly-blocking) incident. */
+export function composeOpened(incident: Incident): ChannelMessage {
+	const tag = incident.severity === "blocking" ? "BLOCKED" : "Heads up";
+	return {
+		severity: incident.severity,
+		subject: `[${tag}] ${incident.title}`,
+		text: [
+			`What broke: ${incident.whatBroke}`,
+			`What it blocks: ${incident.whatItBlocks}`,
+			`What to do: ${incident.whatToDo}`,
+			`(${incident.source} · ${incident.kind} · ${incident.subject})${factLine(incident)}`,
+		].join("\n\n"),
+	};
+}
+
+/**
+ * The message for a resolve. It exists so "is it fixed?" is answered without
+ * him having to go and look — the same reason the open message exists.
+ */
+export function composeResolved(incident: Incident): ChannelMessage {
+	const minutes = Math.max(1, Math.round(((incident.resolvedAt ?? 0) - incident.firstSeen) / 60000));
+	return {
+		severity: incident.severity,
+		subject: `[cleared] ${incident.title}`,
+		text: [
+			`This is no longer happening. It was open for about ${minutes} minute${minutes === 1 ? "" : "s"}.`,
+			`It was: ${incident.whatBroke}`,
+			`(${incident.source} · ${incident.kind} · ${incident.subject})`,
+		].join("\n\n"),
+	};
+}
+
+export interface CreateNotifierOptions {
+	store: IncidentStore;
+	channels: readonly IncidentChannel[];
+	/**
+	 * Called with every channel result, so a host can record channel health.
+	 * `detectChannelHealth` in `detectors.ts` turns a run of failures into its
+	 * own incident — which is why `ChannelMessage.avoid` exists.
+	 */
+	onChannelResult?: (fingerprint: string, result: ChannelResult) => void;
+}
+
+export function createIncidentNotifier(options: CreateNotifierOptions): IncidentNotifier {
+	const { store, channels } = options;
+
+	const dispatch = async (
+		incident: Incident,
+		message: ChannelMessage,
+		transition: AnnounceResult["transition"],
+	): Promise<AnnounceResult> => {
+		// An incident that IS a channel failure must not be announced down the
+		// channel it is about. Without this the first SES outage produces an
+		// endless retry loop against SES.
+		const avoid =
+			incident.kind === "notification-channel-failing" ? [incident.subject] : undefined;
+		const withAvoid: ChannelMessage = avoid ? { ...message, avoid } : message;
+
+		const results: ChannelResult[] = [];
+		for (const channel of channels) {
+			// 🔴 The `avoid` guard lives HERE, not in each channel. It was in every
+			// channel first and a spy channel in the spec walked straight past it —
+			// which is the same hole any channel added later would have had. One
+			// enforcement point, and a new channel inherits it by existing.
+			if (withAvoid.avoid?.includes(channel.key)) {
+				results.push({
+					channel: channel.key,
+					outcome: "skipped",
+					detail: "this message is ABOUT this channel — not sent down it",
+				});
+				continue;
+			}
+			// Channels are awaited in series on purpose: there are at most three,
+			// they are all fast, and a serial loop means the text channel's
+			// delivery-proof read cannot race the email channel's for the same
+			// laptop resources.
+			const result = await channel.send(withAvoid).catch(
+				(err): ChannelResult => ({
+					channel: channel.key,
+					outcome: "failed",
+					detail: err instanceof Error ? err.message.slice(0, 200) : String(err),
+				}),
+			);
+			results.push(result);
+			options.onChannelResult?.(incident.fingerprint, result);
+		}
+		return { fingerprint: incident.fingerprint, transition, results };
+	};
+
+	const summarise = (results: ChannelResult[]): string =>
+		results.map((r) => `${r.channel}=${r.outcome}`).join(" ");
+
+	return {
+		channels,
+		async announce(t) {
+			const out: AnnounceResult[] = [];
+
+			for (const incident of [...t.opened, ...t.escalated]) {
+				const transition = t.opened.includes(incident) ? "opened" : "escalated";
+				const result = await dispatch(incident, composeOpened(incident), transition);
+				// 🔴 Only stamp `notifiedAt` when there was actually a channel to try.
+				// A host with none (a prod deployment that only stores what the Mac
+				// pushes it) has not told him anything, and stamping it there is what
+				// made the resolve message below fire for an open he never saw.
+				if (result.results.length > 0) {
+					store.markNotified([incident.fingerprint], summarise(result.results));
+				}
+				out.push(result);
+			}
+
+			// A blocking incident nobody could be told about is retried, hourly,
+			// until one channel lands it. See `UNDELIVERED_RETRY_MS`.
+			for (const incident of t.unchanged) {
+				if (incident.severity !== "blocking") continue;
+				if (incident.notifiedAt === null) continue;
+				if (wasDelivered(incident.notifyResult)) continue;
+				if (Date.now() - incident.notifiedAt < UNDELIVERED_RETRY_MS) continue;
+				const result = await dispatch(incident, composeOpened(incident), "opened");
+				if (result.results.length > 0) {
+					store.markNotified([incident.fingerprint], summarise(result.results));
+				}
+				out.push(result);
+			}
+
+			for (const incident of t.resolved) {
+				// Never announce a resolve for something whose OPEN was never
+				// announced — the owner would get "cleared: X" for an X he has never
+				// heard of, which reads as a bug in the alerting rather than as good
+				// news. This happens for real: an incident opened, acknowledged and
+				// resolved between two sweeps of a host that had no channels.
+				if (incident.notifiedAt === null) continue;
+				const result = await dispatch(incident, composeResolved(incident), "resolved");
+				store.markResolvedNotified([incident.fingerprint]);
+				out.push(result);
+			}
+
+			return out;
+		},
+	};
+}

package/src/server/incidents/reporter.ts

@@ -0,0 +1,110 @@
+/**
+ * The other side of `POST /incidents/report` — how a service that is NOT the
+ * console tells the console what it can see.
+ *
+ * ── Why a service reports rather than being polled ──────────────────────────
+ * The console can measure a service's disk, its port and its HTTP status from
+ * outside. It cannot measure the things that actually go wrong inside one: an
+ * ingest run where every item failed, a queue whose worker is looping on the
+ * same error, a store that is refusing writes for a reason of its own. Those
+ * facts exist for a few milliseconds inside the process that has them, and the
+ * only place they can be turned into an incident is there.
+ *
+ * ── 🔴 Reporting is a HEARTBEAT, not an event ───────────────────────────────
+ * A reporter sends the complete set of conditions that are true right now — the
+ * same contract a local check has — and sends it on a schedule whether or not
+ * anything is wrong. That is what lets the console clear an incident when the
+ * service recovers. A reporter that only posts on failure can open an incident
+ * and can never close one, and the owner ends up with a permanently red board,
+ * which is the same uselessness as a permanently green one.
+ *
+ * The dedupe is entirely the console's: post the same thing every five minutes
+ * for a week and he is told once. So a reporter needs no state, no "have I said
+ * this?" flag, and no backoff — which is why this file is forty lines and not
+ * four hundred.
+ *
+ * ── It never throws, and never blocks the service ───────────────────────────
+ * A service whose real work fails because its ALERTING is unreachable is worse
+ * than one with no alerting. Every failure here is logged and swallowed, and the
+ * console notices the silence by other means (the service's own health probe).
+ */
+import type { IncidentReport } from "./types";
+
+export interface IncidentReporterOptions {
+	/** e.g. `http://127.0.0.1:3024/api/station/incidents/report`. */
+	url: string;
+	/** The shared bearer the console's `reporterToken` compares against. */
+	token: string;
+	/** This service's name — the `source` of everything it reports. */
+	source: string;
+	/** A stable key for this reporter, owning the incidents it opens. */
+	checkKey: string;
+	/**
+	 * Every `kind` this reporter can produce. Required, not optional: without it
+	 * the console cannot tell "nothing is wrong" from "nothing was said", so a
+	 * recovered service would stay red for ever. See `ReconcileOptions`.
+	 */
+	kinds: readonly string[];
+	/** Produce the current set of true conditions. Called on every beat. */
+	collect: () => Promise<IncidentReport[]> | IncidentReport[];
+	/** Default 5 minutes. The console dedupes, so this is chosen for the network. */
+	intervalMs?: number;
+	fetchImpl?: typeof fetch;
+	log?: (message: string) => void;
+}
+
+export interface IncidentReporter {
+	/** Send one beat now. Resolves `false` on any failure — it never throws. */
+	beat: () => Promise<boolean>;
+	start: () => void;
+	stop: () => void;
+}
+
+export function createIncidentReporter(options: IncidentReporterOptions): IncidentReporter {
+	const doFetch = options.fetchImpl ?? fetch;
+	const log = options.log ?? ((m: string) => console.warn(`[incidents] ${m}`));
+	const intervalMs = options.intervalMs ?? 5 * 60_000;
+	let timer: ReturnType<typeof setInterval> | null = null;
+
+	const beat = async (): Promise<boolean> => {
+		try {
+			const reports = await options.collect();
+			const res = await doFetch(options.url, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${options.token}`,
+				},
+				body: JSON.stringify({
+					checkKey: options.checkKey,
+					source: options.source,
+					kinds: options.kinds,
+					reports,
+				}),
+				signal: AbortSignal.timeout(10_000),
+			});
+			if (!res.ok) {
+				log(`the console answered ${res.status} — ${reports.length} finding(s) not filed`);
+				return false;
+			}
+			return true;
+		} catch (err) {
+			log(`could not reach the console: ${err instanceof Error ? err.message : String(err)}`);
+			return false;
+		}
+	};
+
+	return {
+		beat,
+		start() {
+			if (timer) return;
+			timer = setInterval(() => void beat(), intervalMs);
+			// Never hold the process open for the sake of its own alerting.
+			timer.unref?.();
+		},
+		stop() {
+			if (timer) clearInterval(timer);
+			timer = null;
+		},
+	};
+}

package/src/server/incidents/routes.ts

@@ -0,0 +1,314 @@
+/**
+ * The mountable half — ordinary Hono routes, so any app can expose its incidents
+ * without adopting another app's rpc layer (the same reasoning, and the same
+ * shape, as `server/notifications/routes.ts`).
+ *
+ * ```ts
+ * // BEFORE the session gate — the machine doors carry their own bearer:
+ * mountIncidentMachineRoutes(app, { store, notifier, reporterToken });
+ * // INSIDE it — the owner's own surface:
+ * mountIncidentOwnerRoutes(app, { store, notifier, sweep, authorize: isOwner });
+ * ```
+ *
+ * ── 🔴 Two doors, two MOUNTS, and that is the whole point ───────────────────
+ * `authorize` is the OWNER's session — it guards the list, the acks, the manual
+ * sweep and the channel test. `reporterToken` is a shared bearer and guards the
+ * two routes a DAEMON uses. They answer different questions ("is this the
+ * owner's browser?" and "is this one of my own processes?"), so a reporter can
+ * never read the incident list and a browser session can never forge an
+ * incident.
+ *
+ * They were one function first, and the console mounted it inside its session
+ * gate. Every beat from binary-server and orch came back
+ * `{"error":"unauthorized"}` — from the GATE, so nothing in this module logged
+ * anything and the console showed a perfectly calm, empty board. A reporter
+ * cannot report that it could not reach the reporting door. Two functions make
+ * the mount order a thing you have to get right rather than a thing you can
+ * forget, and they stop the opposite mistake too: registering the owner's
+ * `GET /incidents` outside the gate, where Hono's first-match would shadow the
+ * real one for ever.
+ *
+ * 🔴 `POST /report` is the ONE route that accepts incident text from off-box, so
+ * it is also the one that has to be paranoid about it: every field is length-
+ * capped and `facts` is re-validated through the store's `assertNoContent`
+ * before anything is written. A reporter is trusted to be honest, not to be
+ * correct.
+ */
+import type { Hono } from "hono";
+import type { IncidentChannel } from "./channels";
+import type { IncidentNotifier } from "./notifier";
+import { assertNoContent, type IncidentStore } from "./store";
+import type { IncidentReport, IncidentSeverity } from "./types";
+import type { SweepResult } from "./checks";
+
+const noStore = { "cache-control": "no-store" } as const;
+
+/** Long enough for three real sentences, short enough that nobody pastes a log in. */
+const MAX_FIELD = 600;
+const MAX_REPORTS = 100;
+
+export interface IncidentRoutesOptions {
+	store: IncidentStore;
+	/** Owner-only gate for the read + write surface. Return false to 403. */
+	authorize: (c: unknown) => boolean | Promise<boolean>;
+	/** Run the checks now. Omitted on a host that runs no detectors (prod). */
+	sweep?: () => Promise<SweepResult>;
+	/** Used to announce anything a remote report opens, and to list channel health. */
+	notifier?: IncidentNotifier;
+	/** Shared bearer for `POST /report`. Omitted, the route is not mounted. */
+	reporterToken?: string;
+	/**
+	 * Deliver one message as this host. Mounted as `POST /relay-email` and used
+	 * by the local console, which cannot reach SES — see `channels.ts`.
+	 */
+	relayEmail?: (msg: {
+		subject: string;
+		text: string;
+		html?: string;
+	}) => Promise<{ sent: boolean; reason?: string }>;
+	/** The last sweep, for the health route. */
+	lastSweep?: () => SweepResult | null;
+	/** Send a test message down one channel, so the owner can prove it works. */
+	channelsOf?: () => readonly IncidentChannel[];
+}
+
+const str = (v: unknown, fallback = ""): string =>
+	typeof v === "string" ? v.slice(0, MAX_FIELD) : fallback;
+
+/** Parse one posted report defensively. Throws with a usable message. */
+function parseReport(raw: unknown): IncidentReport {
+	if (!raw || typeof raw !== "object") throw new Error("each report must be an object");
+	const r = raw as Record<string, unknown>;
+	const severity: IncidentSeverity = r.severity === "blocking" ? "blocking" : "warning";
+	const report: IncidentReport = {
+		source: str(r.source),
+		kind: str(r.kind),
+		subject: str(r.subject),
+		severity,
+		title: str(r.title),
+		whatBroke: str(r.whatBroke),
+		whatItBlocks: str(r.whatItBlocks),
+		whatToDo: str(r.whatToDo),
+		...(r.facts && typeof r.facts === "object"
+			? { facts: r.facts as IncidentReport["facts"] }
+			: {}),
+	};
+	for (const field of ["source", "kind", "subject", "title", "whatBroke"] as const) {
+		if (!report[field]) throw new Error(`report is missing "${field}"`);
+	}
+	// The privacy gate, applied to off-box input before it can reach a phone.
+	assertNoContent(report);
+	return report;
+}
+
+/**
+ * The OWNER's surface: the list, the acks, the health strip, the manual sweep,
+ * the channel test. Mount it INSIDE the app's session gate.
+ */
+export function mountIncidentOwnerRoutes(
+	app: Hono,
+	options: IncidentRoutesOptions,
+	basePath = "/incidents",
+): void {
+	const { store } = options;
+
+	const guard = async (c: { json: (b: unknown, s?: number) => Response }): Promise<Response | null> =>
+		(await options.authorize(c)) ? null : c.json({ error: "forbidden" }, 403);
+
+	app.get(`${basePath}`, async (c) => {
+		const denied = await guard(c);
+		if (denied) return denied;
+		const state = c.req.query("state");
+		const incidents = store.list({
+			state:
+				state === "all"
+					? undefined
+					: state === "resolved"
+						? "resolved"
+						: state === "open"
+							? "open"
+							: "active",
+			limit: Number(c.req.query("limit") ?? 200),
+		});
+		return c.json({ incidents }, 200, noStore);
+	});
+
+	app.post(`${basePath}/:fingerprint/ack`, async (c) => {
+		const denied = await guard(c);
+		if (denied) return denied;
+		const ok = store.acknowledge(decodeURIComponent(c.req.param("fingerprint")));
+		return c.json({ ok }, ok ? 200 : 404, noStore);
+	});
+
+	app.get(`${basePath}/health`, async (c) => {
+		const denied = await guard(c);
+		if (denied) return denied;
+		return c.json(
+			{
+				channels: (options.channelsOf?.() ?? options.notifier?.channels ?? []).map((ch) => ({
+					key: ch.key,
+					label: ch.label,
+				})),
+				lastSweep: options.lastSweep?.() ?? null,
+				sweepable: Boolean(options.sweep),
+			},
+			200,
+			noStore,
+		);
+	});
+
+	if (options.sweep) {
+		app.post(`${basePath}/sweep`, async (c) => {
+			const denied = await guard(c);
+			if (denied) return denied;
+			const result = await options.sweep?.();
+			if (!result) return c.json({ error: "no detectors on this host" }, 400, noStore);
+			const announced = options.notifier ? await options.notifier.announce(result.transitions) : [];
+			return c.json({ result, announced }, 200, noStore);
+		});
+	}
+
+	if (options.channelsOf) {
+		app.post(`${basePath}/test/:channel`, async (c) => {
+			const denied = await guard(c);
+			if (denied) return denied;
+			const key = c.req.param("channel");
+			const channel = options.channelsOf?.().find((ch) => ch.key === key);
+			if (!channel) return c.json({ error: `no channel "${key}" on this host` }, 404, noStore);
+			// Sent at `blocking` because that is the severity whose delivery matters —
+			// a test that exercises the in-app path and skips the phone proves nothing.
+			const result = await channel.send({
+				severity: "blocking",
+				subject: "[test] fleet incident alerts",
+				text: "This is the console proving the channel works. Nothing is wrong. No action needed.",
+			});
+			return c.json({ result }, 200, noStore);
+		});
+	}
+}
+
+/**
+ * The MACHINE doors: `POST /report`, which another service beats its findings
+ * into, and `POST /relay-email`, which a host that cannot send mail hands a
+ * message to. Both carry a shared bearer.
+ *
+ * 🔴 **Mount this BEFORE the session gate, and never call it with `authorize`
+ * expecting it to matter — it registers no route a browser should reach.**
+ * Mounting the two together inside a cookie gate is the trap this split exists
+ * to make impossible: every beat from binary-server and orch came back
+ * `{"error":"unauthorized"}` from the gate, so no log line in this module said
+ * anything was wrong and the console rendered a perfectly calm, empty board.
+ * A reporter cannot report the failure to reach the reporting door.
+ *
+ * Keeping them in one function also risked the opposite mistake — registering
+ * the owner's `GET /incidents` outside the gate, where Hono's first-match would
+ * have shadowed the real one for ever.
+ */
+export function mountIncidentMachineRoutes(
+	app: Hono,
+	options: Pick<IncidentRoutesOptions, "store" | "notifier" | "reporterToken" | "relayEmail">,
+	basePath = "/incidents",
+): void {
+	const { store } = options;
+	if (options.reporterToken) {
+		app.post(`${basePath}/report`, async (c) => {
+			const header = c.req.header("authorization") ?? "";
+			const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+			// Length-first compare then constant-time-ish equality; the token is a
+			// shared secret between our own daemons, not a user credential.
+			if (
+				presented.length !== options.reporterToken?.length ||
+				presented !== options.reporterToken
+			) {
+				return c.json({ error: "forbidden" }, 403, noStore);
+			}
+			const body = (await c.req.json().catch(() => null)) as {
+				checkKey?: unknown;
+				source?: unknown;
+				kinds?: unknown;
+				reports?: unknown;
+			} | null;
+			const checkKey = str(body?.checkKey);
+			const source = str(body?.source);
+			const rawReports = Array.isArray(body?.reports) ? body.reports : null;
+			if (!checkKey || !source || !rawReports) {
+				return c.json(
+					{ error: "checkKey, source and reports[] are required" },
+					400,
+					noStore,
+				);
+			}
+			if (rawReports.length > MAX_REPORTS) {
+				return c.json({ error: `at most ${MAX_REPORTS} reports per call` }, 400, noStore);
+			}
+			let reports: IncidentReport[];
+			try {
+				reports = rawReports.map(parseReport);
+			} catch (err) {
+				return c.json(
+					{ error: err instanceof Error ? err.message : "bad report" },
+					400,
+					noStore,
+				);
+			}
+			// A reporter declares the kinds it is authoritative for, exactly as a
+			// local check does — without them a remote service could never clear its
+			// own incidents, and every transient blip would stay red forever.
+			const kinds = Array.isArray(body?.kinds)
+				? (body.kinds as unknown[]).filter((k): k is string => typeof k === "string")
+				: [...new Set(reports.map((r) => r.kind))];
+			const transitions = store.reconcile(checkKey, reports, {
+				namespaces: kinds.map((k) => `${source}:${k}:`),
+			});
+			const announced = options.notifier ? await options.notifier.announce(transitions) : [];
+			return c.json(
+				{
+					opened: transitions.opened.length,
+					escalated: transitions.escalated.length,
+					resolved: transitions.resolved.length,
+					unchanged: transitions.unchanged.length,
+					announced,
+				},
+				200,
+				noStore,
+			);
+		});
+	}
+
+	if (options.relayEmail) {
+		app.post(`${basePath}/relay-email`, async (c) => {
+			const header = c.req.header("authorization") ?? "";
+			const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+			if (
+				!options.reporterToken ||
+				presented.length !== options.reporterToken.length ||
+				presented !== options.reporterToken
+			) {
+				return c.json({ error: "forbidden" }, 403, noStore);
+			}
+			const body = (await c.req.json().catch(() => null)) as {
+				subject?: unknown;
+				text?: unknown;
+				html?: unknown;
+			} | null;
+			const subject = str(body?.subject);
+			const text = typeof body?.text === "string" ? body.text.slice(0, 4000) : "";
+			if (!subject || !text) return c.json({ error: "subject and text required" }, 400, noStore);
+			// 🔴 The REASON crosses the wire, not just the boolean. `{sent:false}`
+			// alone made the local console report "the prod console accepted the
+			// request but its mailer declined" — true, useless, and indistinguishable
+			// between "mail is off on that host" and "SES refused the address". The
+			// relay is the only place that knows.
+			const outcome = await options.relayEmail?.({
+				subject,
+				text,
+				...(typeof body?.html === "string" ? { html: body.html.slice(0, 20_000) } : {}),
+			});
+			return c.json(
+				{ sent: Boolean(outcome?.sent), ...(outcome?.reason ? { reason: outcome.reason } : {}) },
+				200,
+				noStore,
+			);
+		});
+	}
+}