caracms 0.0.0-stage → 0.2.0

package/src/forms/endpoint.ts

@@ -0,0 +1,347 @@
+/**
+ * `POST /_caracms/form`: every form's destination (M6 Decisions 5 and 6; the template's
+ * `server/forms.mjs`, `forms.md` → The endpoint and Files: the wire contract).
+ *
+ * **Public.** The guard lets it through exactly (live/auth/guard.ts → `isLetThrough`)
+ * and the unconfigured server's 503 exempts it (editor/middleware.ts), so it works in
+ * local mode, live mode, and on a production server whose editor isn't set up. No
+ * session, no same-origin check.
+ *
+ * In order, and **nothing is written until every check has passed**:
+ *
+ * 1. **The rate limit's peek** for a body that can be large (multipart on a site with a
+ *    files field, or a declared length over 256 KB): an IP already at the limit gets the
+ *    429 and the body is never read.
+ * 2. **The body**, read up to its cap: 256 KB for any body without files; 25 MiB +
+ *    256 KB for multipart only when some form has a files field (the config decides,
+ *    not the client). A declared `Content-Length` over the cap is refused before a byte
+ *    is read, and reading stops at the chunk that passes it: 413, which says which limit.
+ * 3. **The return page** (`return`), accepted only as `^/[a-z0-9/-]*$` not starting
+ *    `//`, else `/`. **A known form** (`form`), else 400: a bad id is a broken page.
+ * 4. **The honeypot** (`fax`, rules.ts): filled → the success reply, nothing stored.
+ * 5. **Each field**, in the form's order: required unless optional, an email's shape, a
+ *    select's options, the files (up to 5, the extension list, the declared type fits
+ *    the extension). Every problem comes back in one 400.
+ * 6. **The rate limit's hit** (rate-limit.ts): 5 per IP per 10 minutes, 429 past it.
+ *    A hit is counted here, so a stored submission and a Turnstile refusal both count;
+ *    a small body that fails 4 or 5 doesn't (a body over 256 KB does).
+ * 7. **Turnstile**, when `TURNSTILE_SECRET_KEY` is set: no token or a refused one is a
+ *    403; Cloudflare unreachable fails open, logged. Unset: accepted, with a warning.
+ * 8. **Store** (store.ts), then **email** (email.ts), then **record** the email's outcome
+ *    on the submission, then reply. A storage failure is a 502; an email failure never
+ *    fails the visitor.
+ *
+ * Replies: `Accept: application/json` gets `{ ok: true }` or `{ error }`; a no-JS post
+ * gets a 303 to `<return>?sent=1`, or the error as plain text. Nothing about the visitor
+ * (IP, user agent) is stored.
+ */
+import type { ResolvedSite } from '../config.ts';
+import { publicOrigin } from '../live/auth/index.ts';
+import { clientIp } from '../live/auth/request.ts';
+import { readCapped } from '../editor/server/media/upload.ts';
+import { readFormSettings, sendNotification, type FormSettings } from './email.ts';
+import { formLimiter, type FormRateLimiter } from './rate-limit.ts';
+import { cleanReturn, FILE_KINDS, FILE_TYPES, formsAcceptFiles, HONEYPOT, looksLikeEmail, MAX_FILE_BYTES, MAX_FILES, type ResolvedForm } from './rules.ts';
+import { cleanFileName, fileExtension, readSubmissionsConfig, submissionStore, type NewFile, type SubmissionStore } from './store.ts';
+import { shownFileName } from './rules.ts';
+
+type Env = Record<string, string | undefined>;
+
+export const FORM_ROUTE = '/_caracms/form';
+
+/** The cap for every body without files, and for the fields of one with them. */
+export const BODY_LIMIT = 256 * 1024;
+/** The cap on a multipart body when the site takes files: the files' 25 MiB plus the fields' 256 KB. */
+export const UPLOAD_BODY_LIMIT = BODY_LIMIT + MAX_FILE_BYTES;
+
+export const TOO_LARGE_MESSAGE = `That's too much to send: attachments can come to ${MAX_FILE_BYTES / 1024 / 1024} MB in all. Send fewer or smaller files, or email them to us.`;
+export const TOO_LONG_MESSAGE = "That's too much to send in one message. Shorten it, or email us.";
+export const RATE_LIMITED_MESSAGE = "You've sent a few messages in a row. Please wait a few minutes and try again, or email us directly.";
+export const TURNSTILE_MESSAGE = "We couldn't confirm you're a person. Please try again, or email us directly.";
+export const STORE_FAILED_MESSAGE = 'Could not send your message.';
+export const UNKNOWN_FORM_MESSAGE = "This form isn't on the site any more. Reload the page and try again.";
+export const BAD_EMAIL_MESSAGE = "That email address doesn't look right.";
+
+export const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+const TURNSTILE_TIMEOUT_MS = 5_000;
+
+/** `SITE_URL` as an address (an http(s) origin), or undefined when it's unset or isn't one. */
+function siteUrlFromEnv(env: Env): URL | undefined {
+	const raw = env['SITE_URL']?.trim();
+	if (!raw) return undefined;
+	try {
+		const url = new URL(raw);
+		return url.protocol === 'https:' || url.protocol === 'http:' ? url : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export { cleanReturn };
+
+export interface FormContext {
+	site: Pick<ResolvedSite, 'root' | 'forms' | 'timeZone'>;
+	/** The socket's address (Astro's `clientAddress`), read after `X-Real-IP`. */
+	clientAddress?: () => string | undefined;
+	env?: Env;
+	/** Astro's `site` (the route passes `context.site`): the public origin for the email's editor link. */
+	astroSite?: URL;
+	/** Cloudflare's and Resend's `fetch`, and the bucket's (tests). */
+	fetch?: typeof fetch;
+	now?: () => Date;
+	log?: (line: string) => void;
+	limiter?: FormRateLimiter;
+	/** Tests: the store, the settings reader. */
+	store?: SubmissionStore;
+	readSettings?: () => Promise<FormSettings>;
+}
+
+/** A body's values as one `get(name)`, plus its files by name (multipart read with files on). */
+interface FormBody {
+	get(name: string): string;
+	files(name: string): File[];
+	/** The raw body's size. */
+	bytes: number;
+}
+
+class BodyTooLarge extends Error {
+	readonly upload: boolean;
+	constructor(upload: boolean) {
+		super('body over its cap');
+		this.upload = upload;
+	}
+}
+
+async function readFormBody(request: Request, takesFiles: boolean): Promise<FormBody> {
+	const type = (request.headers.get('content-type') ?? '').toLowerCase();
+	const multipart = type.includes('multipart/form-data');
+	const upload = takesFiles && multipart;
+	const read = await readCapped(request, upload ? UPLOAD_BODY_LIMIT : BODY_LIMIT);
+	if (!read.ok) throw new BodyTooLarge(upload);
+	const raw = read.bytes;
+	const text = () => new TextDecoder().decode(raw);
+	if (type.includes('application/x-www-form-urlencoded')) {
+		const params = new URLSearchParams(text());
+		return { get: (name) => (params.get(name) ?? '').trim(), files: () => [], bytes: raw.byteLength };
+	}
+	if (type.includes('application/json')) {
+		const parsed = JSON.parse(text() || '{}') as unknown;
+		if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('a JSON body must be an object');
+		const o = parsed as Record<string, unknown>;
+		const get = (name: string) => {
+			const v = Object.hasOwn(o, name) ? o[name] : undefined;
+			if (typeof v === 'string') return v.trim();
+			if (typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v))) return String(v);
+			return '';
+		};
+		return { get, files: () => [], bytes: raw.byteLength };
+	}
+	if (multipart) {
+		// Node's own multipart parser, through the fetch API's FormData.
+		const data = await new Response(raw as BodyInit, { headers: { 'content-type': request.headers.get('content-type') ?? '' } }).formData();
+		let fileBytes = 0;
+		for (const [, value] of data) if (typeof value !== 'string') fileBytes += value.size;
+		if (upload && fileBytes > MAX_FILE_BYTES) throw new BodyTooLarge(true);
+		if (upload && raw.byteLength - fileBytes > BODY_LIMIT) throw new BodyTooLarge(false);
+		const get = (name: string) => {
+			const v = data.get(name);
+			return typeof v === 'string' ? v.trim() : '';
+		};
+		// A browser's empty file input (no name, no bytes) is no file. On a site that takes no files, no part is one.
+		const files = (name: string) => (upload ? data.getAll(name).filter((v): v is File => typeof v !== 'string' && (v.name !== '' || v.size > 0)) : []);
+		return { get, files, bytes: raw.byteLength };
+	}
+	throw new Error(`unsupported content type: ${type || '(none)'}`);
+}
+
+/** The declared type, bare: lower case, no parameters. */
+const bareType = (type: string) => type.split(';')[0]!.trim().toLowerCase();
+
+/** The posted files of a files field: what to store, or the problems, each naming the file. */
+export function checkFiles(posted: readonly File[]): { files: { name: string; type: string; blob: File }[]; problems: string[] } {
+	if (posted.length > MAX_FILES) return { files: [], problems: [`Attach up to ${MAX_FILES} files (you chose ${posted.length}).`] };
+	const files: { name: string; type: string; blob: File }[] = [];
+	const problems: string[] = [];
+	for (const file of posted) {
+		const name = cleanFileName(file.name);
+		const shown = shownFileName(name) || 'A file';
+		const ext = fileExtension(name);
+		const allowed = Object.hasOwn(FILE_TYPES, ext) ? FILE_TYPES[ext] : undefined;
+		const type = bareType(file.type ?? '');
+		if (!allowed) problems.push(`${shown}: we can't take that kind of file. Send ${FILE_KINDS} files.`);
+		else if (type && type !== 'application/octet-stream' && !allowed.includes(type)) {
+			problems.push(`${shown}: the file isn't what its name says (a .${ext} file). Save it again as a .${ext}, or send another.`);
+		} else files.push({ name, type, blob: file });
+	}
+	return { files, problems };
+}
+
+/** One submission against its form: what to store, or the 400's sentence (every problem in it). */
+export function vetFields(form: ResolvedForm, body: Pick<FormBody, 'get' | 'files'>): { error: string } | { fields: Record<string, string>; files: { name: string; type: string; blob: File }[] } {
+	const fields: Record<string, string> = {};
+	const missing: string[] = [];
+	const problems: string[] = [];
+	let files: { name: string; type: string; blob: File }[] = [];
+	for (const field of form.fields) {
+		if (field.type === 'files') {
+			const posted = body.files(field.name);
+			if (posted.length === 0 && !field.optional) missing.push(field.label);
+			const checked = checkFiles(posted);
+			problems.push(...checked.problems);
+			files = checked.files;
+			continue;
+		}
+		const value = body.get(field.name);
+		fields[field.name] = value;
+		if (!value) {
+			if (!field.optional) missing.push(field.label);
+			continue;
+		}
+		if (field.type === 'email' && !looksLikeEmail(value)) problems.push(BAD_EMAIL_MESSAGE);
+		if (field.type === 'select' && !field.options?.some((o) => o.value === value)) problems.push(`${field.label}: choose one of the options.`);
+	}
+	const sentences = [...(missing.length ? [`Missing: ${missing.join(', ')}.`] : []), ...problems];
+	return sentences.length ? { error: sentences.join(' ') } : { fields, files };
+}
+
+/** Cloudflare's check of the widget's token. Unreachable → true (fail open, logged). */
+export async function verifyTurnstile(input: { token: string; secret: string; ip: string; fetch: typeof fetch; log: (line: string) => void }): Promise<boolean> {
+	try {
+		const res = await input.fetch(TURNSTILE_VERIFY_URL, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ secret: input.secret, response: input.token, remoteip: input.ip }),
+			signal: AbortSignal.timeout(TURNSTILE_TIMEOUT_MS),
+		});
+		const data = (await res.json()) as { success?: boolean; 'error-codes'?: string[] };
+		if (data.success !== true) input.log(`[caracms] forms: Turnstile refused a token (${(data['error-codes'] ?? []).join(', ') || 'no reason given'}).`);
+		return data.success === true;
+	} catch (error) {
+		input.log(`[caracms] forms: couldn't reach Turnstile's check, so the submission was let through: ${error instanceof Error ? error.message : String(error)}`);
+		return true;
+	}
+}
+
+/** Answer one request to `/_caracms/form`. */
+export async function handleForm(request: Request, ctx: FormContext): Promise<Response> {
+	const env = ctx.env ?? process.env;
+	const log = ctx.log ?? ((line: string) => console.error(line));
+	const now = ctx.now ?? (() => new Date());
+	const doFetch = ctx.fetch ?? ((...args: Parameters<typeof fetch>) => globalThis.fetch(...args));
+	const limiter = ctx.limiter ?? formLimiter(env);
+	const wantsJson = (request.headers.get('accept') ?? '').includes('application/json');
+	let back = '/';
+
+	const reply = (status: number, body: { ok: true } | { error: string }, extra: Record<string, string> = {}): Response => {
+		const headers: Record<string, string> = { 'Cache-Control': 'private, no-store', ...extra };
+		if (wantsJson) return new Response(JSON.stringify(body), { status, headers: { ...headers, 'Content-Type': 'application/json; charset=utf-8' } });
+		if (status < 400) return new Response(null, { status: 303, headers: { ...headers, Location: `${back}?sent=1` } });
+		return new Response('error' in body ? body.error : 'Bad request.', { status, headers: { ...headers, 'Content-Type': 'text/plain; charset=utf-8' } });
+	};
+
+	if (request.method !== 'POST') {
+		await request.body?.cancel().catch(() => {});
+		return reply(405, { error: 'This address takes a form post.' }, { Allow: 'POST' });
+	}
+
+	const ip = clientIp(request, ctx.clientAddress ?? (() => undefined));
+	const takesFiles = formsAcceptFiles(ctx.site.forms);
+	const declared = Number(request.headers.get('content-length') ?? NaN);
+	const multipart = (request.headers.get('content-type') ?? '').toLowerCase().includes('multipart/form-data');
+	const canBeLarge = (takesFiles && multipart) || (Number.isFinite(declared) && declared > BODY_LIMIT);
+	if (canBeLarge && (await limiter.peek(ip))) {
+		await request.body?.cancel().catch(() => {});
+		return reply(429, { error: RATE_LIMITED_MESSAGE });
+	}
+
+	let body: FormBody;
+	try {
+		body = await readFormBody(request, takesFiles);
+	} catch (error) {
+		if (error instanceof BodyTooLarge) {
+			log(`[caracms] forms: refused a body over its cap (${error.upload ? 'attachments' : 'fields'}).`);
+			return reply(413, { error: error.upload ? TOO_LARGE_MESSAGE : TOO_LONG_MESSAGE });
+		}
+		log(`[caracms] forms: an unreadable body (${error instanceof Error ? error.message : String(error)}).`);
+		return reply(400, { error: 'Expected form data.' });
+	}
+	back = cleanReturn(body.get('return'));
+	// A large body that ends in a refusal or the honeypot still counts, so repeated large posts trip the limit.
+	const large = body.bytes > BODY_LIMIT;
+	const countIfLarge = async () => {
+		if (large) await limiter.hit(ip);
+	};
+
+	const formId = body.get('form');
+	const form = Object.hasOwn(ctx.site.forms, formId) ? ctx.site.forms[formId]! : null;
+	if (!form) {
+		await countIfLarge();
+		log(`[caracms] forms: a post for an unknown form (${JSON.stringify(formId.slice(0, 64))}).`);
+		return reply(400, { error: UNKNOWN_FORM_MESSAGE });
+	}
+
+	// The honeypot: answer as if it worked (telling a bot it failed teaches it to retry); nothing is stored, its files included.
+	if (body.get(HONEYPOT)) {
+		await countIfLarge();
+		return reply(200, { ok: true });
+	}
+
+	const vetted = vetFields(form, body);
+	if ('error' in vetted) {
+		await countIfLarge();
+		return reply(400, { error: vetted.error });
+	}
+
+	// Looked at here, counted once the submission is stored (below) or Turnstile refuses it: a try the server
+	// failed to store (a 502) isn't the visitor's to pay for (Decision 5 counts a stored submission).
+	if (await limiter.peek(ip)) return reply(429, { error: RATE_LIMITED_MESSAGE });
+
+	const secret = env['TURNSTILE_SECRET_KEY']?.trim() ?? '';
+	if (secret) {
+		const token = body.get('cf-turnstile-response');
+		if (!token || !(await verifyTurnstile({ token, secret, ip, fetch: doFetch, log }))) {
+			await limiter.hit(ip);
+			return reply(403, { error: TURNSTILE_MESSAGE });
+		}
+	} else {
+		log('[caracms] forms: TURNSTILE_SECRET_KEY is not set, so this submission was accepted without a bot check.');
+	}
+
+	// STORE: what makes it received. The store writes the files, then the JSON, and removes what it wrote on a failure.
+	let store: SubmissionStore;
+	if (ctx.store) store = ctx.store;
+	else {
+		const chosen = submissionStore(readSubmissionsConfig(ctx.site.root, env), ctx.fetch);
+		if ('kind' in chosen) {
+			log(`[caracms] forms: a ${form.id} submission couldn't be stored. ${chosen.message}`);
+			return reply(502, { error: STORE_FAILED_MESSAGE });
+		}
+		store = chosen;
+	}
+	let submission;
+	try {
+		const files: NewFile[] = await Promise.all(vetted.files.map(async (f) => ({ name: f.name, type: f.type, data: new Uint8Array(await f.blob.arrayBuffer()) })));
+		submission = await store.create({ form: form.id, receivedAt: now().toISOString(), fields: vetted.fields, ...(files.length ? { files } : {}) });
+	} catch (error) {
+		log(`[caracms] forms: couldn't store a ${form.id} submission: ${error instanceof Error ? error.message : String(error)}`);
+		return reply(502, { error: STORE_FAILED_MESSAGE });
+	}
+	await limiter.hit(ip);
+
+	// EMAIL, then RECORD its outcome. Neither changes the visitor's reply.
+	let email;
+	try {
+		const settings = await (ctx.readSettings ?? (() => readFormSettings(ctx.site.root)))();
+		const siteUrl = publicOrigin(ctx.astroSite ?? siteUrlFromEnv(env), env);
+		email = await sendNotification({ submission, form, settings, siteUrl, timeZone: ctx.site.timeZone, env, fetch: ctx.fetch, now, log });
+	} catch (error) {
+		email = { status: 'failed' as const, at: now().toISOString(), to: [], error: `Could not read Site Settings: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (email.status === 'failed') log(`[caracms] forms: ${form.id} submission ${submission.id}: the email failed: ${email.error}`);
+	try {
+		await store.update(submission.id, { email });
+	} catch (error) {
+		log(`[caracms] forms: couldn't record the email's outcome on ${submission.id}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return reply(200, { ok: true });
+}

package/src/forms/inbox.ts

@@ -0,0 +1,273 @@
+/**
+ * The inbox's routes (M6 Decision 9; Contracts → Routes), one handler behind
+ * `/_caracms/submissions/[...path]` (routes/submissions.ts):
+ *
+ * | Route | Does |
+ * |---|---|
+ * | `GET /_caracms/submissions[?before=<id>]` | `{ items: SubmissionRow[], older, unread }`, newest first, 50 a page |
+ * | `GET /_caracms/submissions/<id>` | `{ submission, form: { label, fields } \| null, unread }`. Changes nothing |
+ * | `POST …/<id>/read` · `/unread` · `/delete` | 204, the unread count in `X-Caracms-Unread`. `delete` needs `{ "confirm": true }` |
+ * | `GET …/<id>/files/<n>` | The file, always as an attachment |
+ *
+ * - **A session in live mode** (the guard's prefix rule, checked again here), and for a
+ *   POST the same origin. **No lock**: there are no roles, and nothing here is content.
+ * - **Every reply is `Cache-Control: private, no-store`** and `X-Robots-Tag: noindex, nofollow`.
+ * - **Ids and file numbers are checked before the store is asked**: an id that isn't one
+ *   the store mints, or an `n` that isn't 1–999, is a 404 with no read. The stored key is
+ *   checked again by the store (`isFileKey`), so a tampered JSON can't reach another file.
+ * - **A download's type comes from the stored key's extension**, never the visitor's
+ *   declared type; `Content-Disposition: attachment` with the name escaped (`filename*`
+ *   in UTF-8), `nosniff`.
+ * - **The production server without its bucket**: 503 `{ error, code: 'submissions-unset', missing }`.
+ * - **Delete removes the files, then the JSON** (store.ts), so a failure part-way leaves it listed.
+ */
+import type { ResolvedSite } from '../config.ts';
+import { checkOrigin, WriteRefused } from '../editor/server/write.ts';
+import { FILE_TYPES, isSubmissionId, senderName, shownFileName, submissionSnippet, type ResolvedFormField } from './rules.ts';
+import { fileExtension, readSubmissionsConfig, submissionStore, type StoredSubmission, type SubmissionStore } from './store.ts';
+
+type Env = Record<string, string | undefined>;
+
+export const SUBMISSIONS_PREFIX = '/_caracms/submissions';
+/** The unread count on a 204 (read, unread, delete): Decision 9's "with every submissions response". */
+export const UNREAD_HEADER = 'X-Caracms-Unread';
+
+/** One row of the inbox's list. */
+export interface SubmissionRow {
+	id: string;
+	form: string;
+	/** The form's label, or its id when the form is no longer in the config. */
+	formLabel: string;
+	/** `senderName`: the name fields, else the address. */
+	name: string;
+	/** The visitor's address as sent. */
+	email: string;
+	/** The first textarea's text, one line. */
+	snippet: string;
+	receivedAt: string;
+	readAt: string | null;
+	/** How many files came with it. */
+	files: number;
+	/** The email's outcome, or null when it's unknown (the server died between storing and recording). */
+	emailStatus: 'sent' | 'failed' | 'skipped' | null;
+}
+
+export interface SubmissionsListResponse {
+	items: SubmissionRow[];
+	/** The cursor for "Older" (`?before=`), or null on the last page. */
+	older: string | null;
+	unread: number;
+}
+
+export interface SubmissionResponse {
+	submission: StoredSubmission;
+	/** The form as the config has it now, or null when it's gone (show the stored fields by name). */
+	form: { label: string; fields: ResolvedFormField[] } | null;
+	unread: number;
+}
+
+export interface SubmissionsUnset {
+	error: string;
+	code: 'submissions-unset';
+	missing: string[];
+}
+
+export interface InboxContext {
+	site: Pick<ResolvedSite, 'root' | 'forms'>;
+	mode: 'local' | 'live';
+	/** The signed-in person's address (live mode), or null. */
+	person: string | null;
+	env?: Env;
+	log?: (line: string) => void;
+	/** Tests: the store itself. */
+	store?: SubmissionStore;
+	fetch?: typeof fetch;
+}
+
+const HEADERS = { 'Cache-Control': 'private, no-store', 'X-Robots-Tag': 'noindex, nofollow' };
+const json = (status: number, body: unknown, extra: Record<string, string> = {}) =>
+	new Response(JSON.stringify(body), { status, headers: { ...HEADERS, 'Content-Type': 'application/json; charset=utf-8', ...extra } });
+const notFound = () => json(404, { error: "There's no such submission." });
+
+export function rowOf(site: Pick<ResolvedSite, 'forms'>, s: StoredSubmission): SubmissionRow {
+	const form = Object.hasOwn(site.forms, s.form) ? site.forms[s.form]! : null;
+	const fields = s.fields ?? {};
+	return {
+		id: s.id,
+		form: s.form,
+		formLabel: form?.label ?? s.form,
+		name: senderName(form, fields),
+		email: typeof fields.email === 'string' ? fields.email : '',
+		snippet: submissionSnippet(form, fields),
+		receivedAt: s.receivedAt,
+		readAt: s.readAt ?? null,
+		files: s.files?.length ?? 0,
+		emailStatus: s.email?.status ?? null,
+	};
+}
+
+/** The store for the environment, or the 503 to answer with. */
+export function inboxStore(ctx: Pick<InboxContext, 'site' | 'env' | 'store' | 'fetch'>): SubmissionStore | SubmissionsUnset {
+	if (ctx.store) return ctx.store;
+	const chosen = submissionStore(readSubmissionsConfig(ctx.site.root, ctx.env ?? process.env), ctx.fetch);
+	return 'kind' in chosen ? { error: chosen.message, code: 'submissions-unset', missing: chosen.missing } : chosen;
+}
+
+/** `Content-Disposition` for a visitor's file name: an ASCII fallback, and `filename*` in UTF-8 when it isn't plain ASCII. */
+export function attachmentHeader(name: string): string {
+	const base = shownFileName(name) || 'file';
+	const ascii = base.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
+	const plain = ascii === base;
+	return plain ? `attachment; filename="${ascii}"` : `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(base).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+}
+
+/** A download's type, from the stored key's extension. */
+export const downloadType = (key: string): string => FILE_TYPES[fileExtension(key)]?.[0] ?? 'application/octet-stream';
+
+async function readJsonBody(request: Request): Promise<Record<string, unknown>> {
+	const text = await request.text().catch(() => '');
+	if (text.length > 4096) return {};
+	try {
+		const value = JSON.parse(text || '{}') as unknown;
+		return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+	} catch {
+		return {};
+	}
+}
+
+/** Answer one request under `/_caracms/submissions`. */
+export async function handleSubmissions(request: Request, ctx: InboxContext): Promise<Response> {
+	const log = ctx.log ?? ((line: string) => console.error(line));
+	const url = new URL(request.url);
+	const method = request.method.toUpperCase();
+	if (url.pathname !== SUBMISSIONS_PREFIX && !url.pathname.startsWith(`${SUBMISSIONS_PREFIX}/`)) return notFound();
+	const parts = url.pathname.slice(SUBMISSIONS_PREFIX.length).split('/').filter(Boolean);
+	const only = (allowed: string) => (method === allowed ? null : json(405, { error: `This route takes ${allowed}.` }, { Allow: allowed }));
+	try {
+		// Defence in depth: the guard did both in live mode.
+		if (ctx.mode === 'live' && !ctx.person) return json(401, { error: 'signed-out', code: 'signed-out' });
+		if (method !== 'GET' && method !== 'HEAD') checkOrigin(request);
+
+		const [id, action, n, extra] = parts;
+		// Checked before the store is asked: an id it never minted, or a route that isn't one, is a 404.
+		if (id !== undefined && !isSubmissionId(id)) return notFound();
+		const shapeOk =
+			id === undefined || action === undefined || ((action === 'read' || action === 'unread' || action === 'delete') && n === undefined) || (action === 'files' && n !== undefined && /^[1-9]\d{0,2}$/.test(n) && extra === undefined);
+		if (!shapeOk) return notFound();
+
+		const store = inboxStore(ctx);
+		if ('code' in store) return json(503, store);
+
+		if (id === undefined) {
+			const refused = only('GET');
+			if (refused) return refused;
+			const before = url.searchParams.get('before');
+			if (before !== null && !isSubmissionId(before)) return json(400, { error: '`before` must be a submission id.' });
+			const page = await store.list(before ? { before } : {});
+			return json(200, { items: page.items.map((s) => rowOf(ctx.site, s)), older: page.older, unread: await store.unreadCount() } satisfies SubmissionsListResponse);
+		}
+
+		if (action === undefined) {
+			const refused = only('GET');
+			if (refused) return refused;
+			const submission = await store.get(id);
+			if (!submission) return notFound();
+			const form = Object.hasOwn(ctx.site.forms, submission.form) ? ctx.site.forms[submission.form]! : null;
+			return json(200, { submission, form: form ? { label: form.label, fields: form.fields } : null, unread: await store.unreadCount() } satisfies SubmissionResponse);
+		}
+
+		if (action === 'files') {
+			const refused = only('GET');
+			if (refused) return refused;
+			const found = await store.getFile(id, Number(n));
+			if (!found) return notFound();
+			return new Response(found.body as BodyInit, {
+				status: 200,
+				headers: {
+					...HEADERS,
+					'Content-Type': downloadType(found.file.key),
+					'Content-Disposition': attachmentHeader(found.file.name || found.file.key),
+					'Content-Length': String(found.body.byteLength),
+					'X-Content-Type-Options': 'nosniff',
+					'Content-Security-Policy': "default-src 'none'; sandbox",
+				},
+			});
+		}
+
+		const refused = only('POST');
+		if (refused) return refused;
+		if (action === 'delete') {
+			const body = await readJsonBody(request);
+			if (body.confirm !== true) return json(400, { error: 'Deleting a submission is permanent: send { "confirm": true }.' });
+			if (!(await store.delete(id))) return notFound();
+		} else {
+			const updated = await store.update(id, { readAt: action === 'read' ? new Date().toISOString() : null });
+			if (!updated) return notFound();
+		}
+		return new Response(null, { status: 204, headers: { ...HEADERS, [UNREAD_HEADER]: String(await store.unreadCount()) } });
+	} catch (error) {
+		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body });
+		log(`[caracms] ${url.pathname} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+		return json(502, { error: "The submissions couldn't be read just now. Try again in a moment." });
+	}
+}
+
+/** The inbox's state for /admin's first paint and the documents list (Decision 9): the unread count, or why there's none. */
+export type SubmissionsSetup = { unread: number } | { unread: null; error: string; code: 'submissions-unset' | 'submissions-unreadable'; missing: string[] };
+
+export async function submissionsSetup(ctx: Pick<InboxContext, 'site' | 'env' | 'store' | 'fetch' | 'log'>): Promise<SubmissionsSetup> {
+	const store = inboxStore(ctx);
+	if ('code' in store) return { unread: null, error: store.error, code: store.code, missing: store.missing };
+	try {
+		return { unread: await store.unreadCount() };
+	} catch (error) {
+		(ctx.log ?? ((line: string) => console.error(line)))(`[caracms] couldn't count the unread submissions: ${error instanceof Error ? error.message : String(error)}`);
+		return { unread: null, error: "The submissions couldn't be read just now.", code: 'submissions-unreadable', missing: [] };
+	}
+}
+
+/** How long the editor's own pages wait for the unread count before going on without it. */
+const SETUP_WAIT_MS = 1500;
+/** How long a count that failed or timed out is not asked for again by those pages. */
+const SETUP_RETRY_MS = 30_000;
+/** Per store: when the last count failed or timed out (the editor pages' memory of it). */
+const setupFailures = new WeakMap<SubmissionStore, number>();
+
+/**
+ * `submissionsSetup` for the editor's own pages (/admin's first paint, the documents list):
+ * the count is raced against ~1.5 s, so a bucket that is slow or down can't stall the editor.
+ * On a timeout or an error the answer is the `submissions-unreadable` shape, and for ~30 s
+ * after, that is answered at once without asking again. A count that was still running when
+ * the wait ended keeps going, and clears the memory if it lands. The inbox's own routes
+ * don't use this.
+ */
+export async function submissionsSetupQuick(
+	ctx: Pick<InboxContext, 'site' | 'env' | 'store' | 'fetch' | 'log'>,
+	timing: { waitMs?: number; retryMs?: number; now?: () => number } = {},
+): Promise<SubmissionsSetup> {
+	const store = inboxStore(ctx);
+	if ('code' in store) return { unread: null, error: store.error, code: store.code, missing: store.missing };
+	const { waitMs = SETUP_WAIT_MS, retryMs = SETUP_RETRY_MS, now = Date.now } = timing;
+	const unreadable: SubmissionsSetup = { unread: null, error: "The submissions couldn't be read just now.", code: 'submissions-unreadable', missing: [] };
+	const failedAt = setupFailures.get(store);
+	if (failedAt !== undefined && now() - failedAt < retryMs) return unreadable;
+
+	const counting = submissionsSetup({ ...ctx, store });
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timedOut = new Promise<'timeout'>((resolve) => {
+		timer = setTimeout(() => resolve('timeout'), waitMs);
+	});
+	const result = await Promise.race([counting, timedOut]);
+	clearTimeout(timer);
+	if (result === 'timeout') {
+		setupFailures.set(store, now());
+		(ctx.log ?? ((line: string) => console.error(line)))(`[caracms] counting the unread submissions took over ${waitMs} ms; going on without it.`);
+		void counting.then((late) => {
+			if (late.unread !== null) setupFailures.delete(store);
+		});
+		return unreadable;
+	}
+	if (result.unread === null) setupFailures.set(store, now());
+	else setupFailures.delete(store);
+	return result;
+}