caracms 0.0.0-stage → 0.2.0

package/src/editor/server/media/upload.ts

@@ -0,0 +1,175 @@
+/**
+ * `POST /_caracms/media/upload` (M5b Decision 6): one image, or (M6c G4) one file, through the site's server.
+ * A security boundary: it takes bytes and a name from the browser and writes to the
+ * bucket that every place the site runs shares, append-only.
+ *
+ * 1. **The body is buffered in memory up to 40 MB and refused the moment it passes**:
+ *    a Content-Length over the cap is refused before a byte is read, and the read itself
+ *    stops at the cap whatever the header said (it's not trusted). Not streamed to the
+ *    bucket: the key comes from the file's hash, known only at the last byte.
+ * 2. **The type is the bytes'** (sniff.ts), never the name's or the Content-Type's
+ *    (save Decision 1's two narrow exceptions, a legacy Office file and a CSV, sniff.ts).
+ * 3. **At most 50 megapixels** (imgproxy's limit), counted as shown; an SVG has no pixels.
+ * 4. **The key is `uploads/<first 12 hex of SHA-256>/<the name, slugified>.<ext>`**, with
+ *    `<ext>` from the detected type (a HEIC called `photo.jpg` is `photo.heic`).
+ * 5. **If anything exists under `uploads/<hash>/`, nothing is written** and that object is
+ *    the answer, whatever it was called: the same bytes are stored once, and a key never
+ *    changes what it points at (the CDN keeps every copy for a year). Two uploads of the
+ *    same bytes in this process at once are one.
+ * 6. The metadata: `w`, `h` (an image's; a file has neither), `name` (the file name as
+ *    sent) and `by` (the signed-in address; none in local mode).
+ */
+import { createHash } from 'node:crypto';
+import { slugify } from '../../../slug.ts';
+import { MEDIA_MAX_BYTES, MEDIA_MAX_PIXELS, MEDIA_NAME_HEADER, type MediaRefusal } from '../../types.ts';
+import type { Bucket, ObjectMeta } from './bucket.ts';
+import { countsPixels, sniffUpload } from './sniff.ts';
+
+/** How many bytes are read before deciding (the cap, plus one to know it was passed). */
+export interface CappedBody {
+	ok: true;
+	bytes: Uint8Array;
+}
+export interface OverCap {
+	ok: false;
+	/** The size, when the request said it (Content-Length); null when the read was stopped without knowing. */
+	size: number | null;
+}
+
+/** Read a request's body, stopping as soon as it passes `cap` bytes. */
+export async function readCapped(request: Request, cap: number): Promise<CappedBody | OverCap> {
+	const declared = Number(request.headers.get('content-length') ?? NaN);
+	const said = Number.isFinite(declared) && declared >= 0 ? declared : null;
+	if (said !== null && said > cap) {
+		await request.body?.cancel().catch(() => {});
+		return { ok: false, size: said };
+	}
+	const reader = request.body?.getReader();
+	if (!reader) return { ok: true, bytes: new Uint8Array(0) };
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > cap) {
+			await reader.cancel().catch(() => {});
+			return { ok: false, size: said !== null && said > total ? said : null };
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let at = 0;
+	for (const c of chunks) {
+		bytes.set(c, at);
+		at += c.byteLength;
+	}
+	return { ok: true, bytes };
+}
+
+/** "52", or "40.3" when rounding would land on the cap itself (so it never reads as allowed). */
+function amount(value: number, cap: number): string {
+	const whole = Math.round(value);
+	return whole > cap ? String(whole) : (Math.ceil(value * 10 - 1e-9) / 10).toFixed(1);
+}
+
+export const tooLargeMessage = (bytes: number | null) =>
+	bytes === null
+		? `This file is over ${MEDIA_MAX_BYTES / 1e6} MB. The library takes up to ${MEDIA_MAX_BYTES / 1e6} MB.`
+		: `This file is ${amount(bytes / 1e6, MEDIA_MAX_BYTES / 1e6)} MB. The library takes up to ${MEDIA_MAX_BYTES / 1e6} MB.`;
+export const tooManyPixelsMessage = (pixels: number) => `This image is ${amount(pixels / 1e6, MEDIA_MAX_PIXELS / 1e6)} megapixels. The library takes up to ${MEDIA_MAX_PIXELS / 1e6}.`;
+
+/** An upload refused: the status and Decision 6's sentence. */
+export class UploadRefused extends Error {
+	readonly status: number;
+	readonly code: MediaRefusal['code'];
+	constructor(status: number, code: MediaRefusal['code'], message: string) {
+		super(message);
+		this.name = 'UploadRefused';
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/** The most a name may take URI-encoded: S3 holds all of an object's metadata to 2 KB, and `name` is stored encoded. */
+const NAME_ENCODED_MAX = 1024;
+
+/** The file name from the header: URI-decoded, no path, no control characters, at most 255 characters and 1 KB encoded. */
+export function uploadName(request: Request): string {
+	const raw = request.headers.get(MEDIA_NAME_HEADER) ?? '';
+	let name = raw;
+	try {
+		name = decodeURIComponent(raw);
+	} catch {
+		/* as sent */
+	}
+	name = (name.split(/[\\/]/).pop() ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim();
+	const chars = [...name].slice(0, 255);
+	while (chars.length > 0 && encodeURIComponent(chars.join('')).length > NAME_ENCODED_MAX) chars.pop();
+	return chars.join('');
+}
+
+/** The key's file part: the name without its extension, slugified (`image`, or a file's `file`, when nothing's left). */
+export function keyName(name: string, fallback = 'image'): string {
+	const dot = name.lastIndexOf('.');
+	const stem = dot > 0 ? name.slice(0, dot) : name;
+	return slugify(stem) || fallback;
+}
+
+export interface Stored {
+	key: string;
+	meta: ObjectMeta;
+	created: boolean;
+}
+
+const inFlight = new Map<string, Promise<Stored>>();
+
+/**
+ * Take an upload's bytes into the bucket by Decision 6's rules. Throws UploadRefused for
+ * anything the library doesn't take; a bucket failure throws its BucketError (a 502).
+ */
+export async function storeUpload(
+	bucket: Bucket,
+	upload: { bytes: Uint8Array; name: string; by: string | null },
+	options: { now?: () => number; head?: (key: string) => Promise<ObjectMeta | null> } = {},
+): Promise<Stored> {
+	const { bytes, name, by } = upload;
+	if (bytes.byteLength === 0) throw new UploadRefused(400, 'empty', 'That file is empty.');
+	if (bytes.byteLength > MEDIA_MAX_BYTES) throw new UploadRefused(413, 'too-large', tooLargeMessage(bytes.byteLength));
+	const sniffed = sniffUpload(bytes, name);
+	if (!sniffed.ok) throw new UploadRefused(415, sniffed.code, sniffed.message);
+	const size = sniffed.format === 'file' ? null : { w: sniffed.w, h: sniffed.h };
+	if (size && sniffed.format !== 'file' && countsPixels(sniffed.format) && size.w * size.h > MEDIA_MAX_PIXELS) throw new UploadRefused(422, 'too-many-pixels', tooManyPixelsMessage(size.w * size.h));
+	const sha256 = createHash('sha256').update(bytes).digest('hex');
+	const hash = sha256.slice(0, 12);
+	const head = options.head ?? ((key: string) => bucket.head(key));
+	const now = options.now ?? (() => Date.now());
+
+	const run = async (): Promise<Stored> => {
+		// Existence first, always: anything under the hash's folder is these bytes already.
+		// It's the answer even when its metadata can't be read: writing anyway could land on its key.
+		const existing = await bucket.first(`uploads/${hash}/`);
+		if (existing) {
+			const meta = (await head(existing)) ?? { w: size?.w ?? null, h: size?.h ?? null, name: null, by: null, contentType: sniffed.mime, lastModified: new Date(now()).toISOString(), size: bytes.byteLength };
+			return { key: existing, meta, created: false };
+		}
+		const stem = keyName(name, size ? 'image' : 'file');
+		const key = `uploads/${hash}/${stem}.${sniffed.ext}`;
+		const named = { name: name || `${stem}.${sniffed.ext}`, by };
+		await bucket.put({ key, body: bytes, contentType: sniffed.mime, sha256, meta: size ? { ...size, ...named } : named });
+		return {
+			key,
+			meta: { w: size?.w ?? null, h: size?.h ?? null, ...named, contentType: sniffed.mime, lastModified: new Date(now()).toISOString(), size: bytes.byteLength },
+			created: true,
+		};
+	};
+	let pending = inFlight.get(hash);
+	if (!pending) {
+		pending = run().finally(() => inFlight.delete(hash));
+		inFlight.set(hash, pending);
+		return pending;
+	}
+	// The same bytes, already on their way in this process: one object, so this one wrote nothing.
+	const first = await pending;
+	return { ...first, created: false };
+}

package/src/editor/server/mode.ts

@@ -0,0 +1,63 @@
+/**
+ * The editor's mode at run time (M4 Decision 1), and the drafts store it implies.
+ *
+ * - `editorMode()`: `readMode(process.env, isProductionServer())`, read once per
+ *   process. **A production server is the build**, not `NODE_ENV`: the integration
+ *   sets `__CARACMS_PRODUCTION__` (a Vite define) to `command !== 'dev'`, so the
+ *   built server is always live mode (or unconfigured), and `astro dev` is local
+ *   unless the App or `CARACMS_GITHUB=memory` is set. Phase 3's guard reads the
+ *   mode here too, so the two never disagree.
+ * - Unconfigured: the missing variables are logged once, on the first read (the
+ *   503 itself is ../middleware.ts's).
+ * - `editorStore(site)`: local mode's disk store (M3, unchanged), or live mode's
+ *   (../../live/drafts-store.ts). `liveEditorOf(site)`: live mode's handlers, or null.
+ */
+import type { ResolvedSite } from '../../config.ts';
+import { liveEditor, type LiveEditor } from '../../live/editor.ts';
+import { readMode, unconfiguredMessage, type Mode } from '../../live/mode.ts';
+import { localDraftsStore, type DraftsStore } from './drafts-store.ts';
+
+declare const __CARACMS_PRODUCTION__: boolean | undefined;
+
+/** True in the built server (`astro build`), false under `astro dev` and in plain Node (tests). */
+export function isProductionServer(): boolean {
+	return typeof __CARACMS_PRODUCTION__ === 'boolean' ? __CARACMS_PRODUCTION__ : false;
+}
+
+const SHARED = Symbol.for('caracms.editorMode');
+type Shared = { [SHARED]?: Mode };
+
+/** The mode, read once per process. Sync, no arguments. */
+export function editorMode(): Mode {
+	const g = globalThis as Shared;
+	if (!g[SHARED]) {
+		const mode = readMode(process.env, isProductionServer());
+		if (mode.kind === 'unconfigured') console.error(`[caracms] ${unconfiguredMessage(mode)} The public site is served; /admin answers 503.`);
+		g[SHARED] = mode;
+	}
+	return g[SHARED];
+}
+
+/** Forget the mode read (tests that change the environment). */
+export function resetEditorMode(): void {
+	delete (globalThis as Shared)[SHARED];
+}
+
+/** Live mode's editor server, or null in local mode. Unconfigured never gets here (the middleware's 503). */
+export async function liveEditorOf(site: ResolvedSite): Promise<LiveEditor | null> {
+	const mode = editorMode();
+	if (mode.kind === 'local') return null;
+	if (mode.kind === 'unconfigured') throw new Error(`caracms: ${unconfiguredMessage(mode)}`);
+	return liveEditor(site, mode.settings);
+}
+
+const local = new WeakMap<object, DraftsStore>();
+
+/** The drafts store for the mode: disk (local) or Redis over the `drafts` copy (live). */
+export async function editorStore(site: ResolvedSite): Promise<DraftsStore> {
+	const live = await liveEditorOf(site);
+	if (live) return live.store;
+	let store = local.get(site);
+	if (!store) local.set(site, (store = localDraftsStore(site)));
+	return store;
+}

package/src/editor/server/move.ts

@@ -0,0 +1,295 @@
+/**
+ * Changing a document's address (pre-M7 item 8): the rules both stores apply, what
+ * the move changes in every file, the disk half (local mode), and the route.
+ *
+ * **A security boundary, as create and delete are** (create.ts): the paths come from
+ * the browser, so the route is the same POST-JSON-same-origin handler, both paths go
+ * through create.ts → `target`, and on disk the new file is made by `createOnDisk` and
+ * the old one removed by `deleteOnDisk`, with their symlink checks.
+ *
+ * The rules (`planMove`), over the store's own listing:
+ *
+ * - **Only documents with an address move**: a page, a case study, a journal entry.
+ *   Shared blocks and Site Settings have none. The top of a nested collection (Home,
+ *   or a collection's own page at its `urlBase`) is its collection's address, so it
+ *   stays.
+ * - **The new address follows a new document's rules** (create.ts): its parts are
+ *   slugs (a folder that already holds documents keeps its name), none is `index`, and
+ *   it's free in every collection (the document's own address aside), not under
+ *   `/admin` or `/_caracms`, not strictly below another collection's `urlBase`. The
+ *   same address is refused (`same`): there's nothing to change.
+ * - **Pages under it stay where they are** (as on a delete, M5a Decision 12): moving
+ *   Services moves Services' own page, and its pages keep their addresses, as a group.
+ *
+ * What a move changes (`moveChanges`), worked out from the store's own texts:
+ *
+ * - the document, at its new path, with its own links to itself rewritten;
+ * - **every other document that links to it or references it** (relink.ts), Site
+ *   Settings included, each changed only where it points at the old address;
+ * - **Site Settings' redirects** (redirects.ts): entries to the old address go to the
+ *   new one (chains collapse), an entry from the new address goes (a page is there
+ *   now), and `old → new` is added, unless the document was never live (`addRedirect`
+ *   false: live mode's document made since the last Publish).
+ *
+ * On disk the order is: the new file (an exclusive create), the rewritten files, Site
+ * Settings, then the old file goes. A failure part way leaves the old document where
+ * it was, never no document.
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SITE_SETTINGS_FILE, type ResolvedCollection, type ResolvedSite } from '../../config.ts';
+import { documentUrl, type DocumentEntry } from '../../content.ts';
+import { own, parseAnyDocument, type SettingsDocument } from '../../document.ts';
+import type { Person } from '../../live/messages.ts';
+import { redirectsAfterMove, type Redirect } from '../../redirects.ts';
+import { relinkText, type AddressMove } from '../../relink.ts';
+import { schemaRef, stampSchema } from '../../schema-key.ts';
+import { applyKeyedEdits } from '../../serialize.ts';
+import { addressProblem, INDEX_MESSAGE, isSlug, NO_ADDRESS_MESSAGE, RESERVED_SLUG, slugify } from '../../slug.ts';
+import { RELEASE_HEADER, type MoveRequest, type MoveResponse } from '../types.ts';
+import { confineOnDisk, createOnDisk, deleteOnDisk, MAX_CREATE_BODY_BYTES, refused, target, type Target } from './create.ts';
+import { checkOrigin, seqOf, tabOf, WriteRefused, writeAtomic, type WriteContext } from './write.ts';
+
+type Site = Pick<ResolvedSite, 'root' | 'collections' | 'blocks' | 'codeRoutes'>;
+
+const MOVE_SHAPE = '{ collection, path, to }';
+
+/** A path for a message: control characters shown escaped, long ones cut. */
+const printable = (value: string) => {
+	const shown = JSON.stringify(value).slice(1, -1);
+	return shown.length > 120 ? `${shown.slice(0, 117)}...` : shown;
+};
+
+/** Validate a move body's shape. Throws WriteRefused 400. */
+export function parseMoveBody(body: unknown): MoveRequest {
+	if (!body || typeof body !== 'object' || Array.isArray(body)) throw refused(400, 'bad-request', `Malformed body: it must be a JSON object. Send ${MOVE_SHAPE}.`);
+	const b = body as Record<string, unknown>;
+	const extra = Object.keys(b).filter((k) => !['collection', 'path', 'to'].includes(k));
+	if (extra.length) throw refused(400, 'bad-request', `Malformed body: unexpected ${extra.map((k) => `"${printable(k)}"`).join(', ')}. Send ${MOVE_SHAPE}.`);
+	if (typeof b.collection !== 'string' || b.collection === '') throw refused(400, 'bad-request', `Malformed body: "collection" must be a collection's name. Send ${MOVE_SHAPE}.`);
+	if (typeof b.path !== 'string' || b.path === '') throw refused(400, 'bad-request', `Malformed body: "path" must be the document's path in its collection. Send ${MOVE_SHAPE}.`);
+	if (typeof b.to !== 'string') throw refused(400, 'bad-request', `Malformed body: "to" must be the document's new path in its collection. Send ${MOVE_SHAPE}.`);
+	if (b.path.length > 512 || b.to.length > 512) throw refused(400, 'bad-path', 'That path is too long.');
+	return { collection: b.collection, path: b.path, to: b.to };
+}
+
+export interface MovePlan {
+	from: Target & { entry: DocumentEntry; url: string };
+	to: Target & { url: string };
+	move: AddressMove;
+	title: string;
+}
+
+/** Check a move against the rules and the store's listing (every document, every collection). Throws WriteRefused. */
+export function planMove(site: Site, request: MoveRequest, documents: readonly DocumentEntry[]): MovePlan {
+	const collection = own(site.collections, request.collection);
+	if (!collection) throw refused(400, 'bad-path', `No collection "${printable(request.collection)}" is declared.`);
+	if (collection.urlBase === null) {
+		const what = collection.kind === 'shared' ? 'A shared block' : collection.kind === 'settings' ? 'Site Settings' : `${collection.label} has no pages of its own, so a document there`;
+		throw refused(400, 'not-allowed', `${what} has no address to change.`);
+	}
+	const from = target(site, collection.name, request.path);
+	const entry = documents.find((d) => d.file === from.file);
+	if (!entry) throw refused(404, 'not-found', `${collection.label}: no document "${printable(from.path)}".`);
+	const fromUrl = documentUrl(collection, from.path);
+	if (collection.nested && from.path === 'index') {
+		throw refused(400, 'not-allowed', collection.urlBase === '/' ? 'Home is always at /, so its address can\'t change.' : `${entry.label} is the top of ${collection.label}, at ${collection.urlBase}, so its address can't change.`);
+	}
+	if (fromUrl === null || entry.warning) throw refused(400, 'not-allowed', `${entry.label} can't be opened, so its address can't change.`);
+
+	if (request.to === '') throw refused(400, 'bad-name', NO_ADDRESS_MESSAGE);
+	if (request.to.split('/').includes(RESERVED_SLUG)) throw refused(400, 'index', INDEX_MESSAGE);
+	if (request.to === from.path) throw refused(400, 'same', `${fromUrl} is its address already.`);
+	const to = target(site, collection.name, request.to);
+	const parts = to.path.split('/');
+	parts.forEach((part, i) => {
+		// As on a create: a folder that already has documents in it keeps its name, whatever it is.
+		const prefix = parts.slice(0, i + 1).join('/');
+		const existing = i < parts.length - 1 && documents.some((d) => d.collection === collection.name && d.path.startsWith(`${prefix}/`));
+		if (existing || isSlug(part)) return;
+		const better = slugify(part);
+		throw refused(400, 'bad-name', better ? `"${printable(part)}" can't be part of an address; "${better}" can.` : NO_ADDRESS_MESSAGE);
+	});
+	const toUrl = documentUrl(collection, to.path)!;
+	if (documents.some((d) => d.file === to.file)) throw refused(409, 'address-taken', `There's already a page at ${toUrl}.`);
+	const others = documents.filter((d) => d.file !== from.file);
+	const collections = Object.values(site.collections).map(({ name, label, urlBase }) => ({ name, label, urlBase }));
+	const problem = addressProblem(toUrl, collection.name, collections, others, site.codeRoutes);
+	if (problem) throw refused(problem.code === 'address-taken' ? 409 : 400, problem.code, problem.message);
+	return {
+		from: { ...from, entry, url: fromUrl },
+		to: { ...to, url: toUrl },
+		move: { collection: collection.name, fromPath: from.path, toPath: to.path, fromUrl, toUrl },
+		title: entry.label,
+	};
+}
+
+export interface MoveChanges {
+	/** The document's text at its new path. */
+	moved: string;
+	/** Every other document whose text changes (links or references to it), Site Settings aside. */
+	relinked: { file: string; collection: string; path: string; title: string; text: string }[];
+	/** Site Settings' text after (null: no change), and before (null: the file isn't there yet). */
+	settings: { before: string | null; after: string } | null;
+	redirect: Redirect | null;
+}
+
+const settingsCollection = (site: Site): ResolvedCollection | undefined => Object.values(site.collections).find((c) => c.kind === 'settings');
+
+/**
+ * Site Settings' text once its redirects follow the move (and its own links are
+ * rewritten), or null when nothing changes. `text` null: there's no Site Settings file yet.
+ */
+export function settingsAfterMove(site: Site, text: string | null, move: AddressMove, addRedirect: boolean): string | null {
+	const collection = settingsCollection(site);
+	if (!collection) return null;
+	const relinked = text === null ? null : relinkText(text, move, site, collection).text;
+	let raw: unknown = {};
+	if (relinked !== null) {
+		try {
+			raw = JSON.parse(relinked);
+		} catch {
+			return null; // a Site Settings that isn't JSON is left as it is (the editor warns about it)
+		}
+	}
+	const doc = parseAnyDocument(raw, site, collection) as SettingsDocument;
+	const redirects = redirectsAfterMove(doc.data.redirects ?? [], move.fromUrl, move.toUrl, addRedirect);
+	const title = relinked === null ? 'Site Settings' : doc.title;
+	const after = applyKeyedEdits(relinked, { title, data: { ...doc.data, redirects } }, collection);
+	return after === text ? null : after;
+}
+
+/**
+ * Site Settings' text without its redirect from `url`, or null when it has none: a new
+ * document made at an address that redirected (a page is there again). Both stores'
+ * create call it; the server also lets a real page win over a redirect.
+ */
+export function settingsWithoutRedirectFrom(site: Site, text: string | null, url: string | null): string | null {
+	const collection = settingsCollection(site);
+	if (!collection || text === null || url === null) return null;
+	let doc: SettingsDocument;
+	try {
+		doc = parseAnyDocument(JSON.parse(text), site, collection) as SettingsDocument;
+	} catch {
+		return null;
+	}
+	const list = doc.data.redirects ?? [];
+	const kept = list.filter((r) => r.from.toLowerCase() !== url.replace(/\/+$/, '').toLowerCase());
+	if (kept.length === list.length) return null;
+	return applyKeyedEdits(text, { title: doc.title, data: { ...doc.data, redirects: kept } }, collection);
+}
+
+/**
+ * What the move changes, from the store's own texts (`readText` by site-relative file;
+ * live mode's has the autosaves on top). `addRedirect`: whether `old → new` is added.
+ */
+export async function moveChanges(
+	site: Site,
+	plan: MovePlan,
+	documents: readonly DocumentEntry[],
+	readText: (file: string) => Promise<string | null>,
+	addRedirect: boolean,
+): Promise<MoveChanges> {
+	const text = await readText(plan.from.file);
+	if (text === null) throw refused(404, 'not-found', `${site.collections[plan.from.collection]!.label}: no document "${plan.from.path}".`);
+	const collectionOf = (name: string) => site.collections[name]!;
+	// M8 Decision 14: its `$schema` path follows the file to its new folder.
+	const moved = stampSchema(relinkText(text, plan.move, site, collectionOf(plan.from.collection)).text, schemaRef(collectionOf(plan.to.collection), plan.to.file), { add: false });
+	const relinked: MoveChanges['relinked'] = [];
+	for (const d of documents) {
+		if (d.file === plan.from.file || d.file === SITE_SETTINGS_FILE) continue;
+		const text = await readText(d.file);
+		if (text === null) continue;
+		const after = relinkText(text, plan.move, site, collectionOf(d.collection));
+		if (after.links) relinked.push({ file: d.file, collection: d.collection, path: d.path, title: d.label, text: after.text });
+	}
+	const before = await readText(SITE_SETTINGS_FILE);
+	const after = settingsAfterMove(site, before, plan.move, addRedirect);
+	return {
+		moved,
+		relinked,
+		settings: after === null ? null : { before, after },
+		redirect: addRedirect ? { from: plan.move.fromUrl, to: plan.move.toUrl } : null,
+	};
+}
+
+/** The route's answer for a move done. */
+export function moveResponse(site: Site, plan: MovePlan, changes: MoveChanges): MoveResponse {
+	const relinked = changes.relinked.map(({ collection, path, title }) => ({ collection, path, title }));
+	if (changes.settings && relinkTouched(site, changes.settings, plan.move)) relinked.push({ collection: 'settings', path: 'site-settings', title: 'Site Settings' });
+	return {
+		ok: true,
+		collection: plan.to.collection,
+		path: plan.to.path,
+		file: plan.to.file,
+		url: plan.to.url,
+		from: { path: plan.from.path, file: plan.from.file, url: plan.from.url },
+		relinked,
+		redirect: changes.redirect,
+	};
+}
+
+/** Whether Site Settings changed for its own links (not only its redirects). */
+function relinkTouched(site: Site, settings: { before: string | null }, move: AddressMove): boolean {
+	const collection = settingsCollection(site);
+	return !!collection && settings.before !== null && relinkText(settings.before, move, site, collection).links > 0;
+}
+
+// ── The disk (local mode) ──────────────────────────────────────────────────
+
+/** Move on disk: the new file (exclusive), the rewritten files, Site Settings, then the old file goes. */
+export async function moveOnDisk(site: Site, plan: MovePlan, changes: MoveChanges): Promise<void> {
+	const collection = site.collections[plan.to.collection]!;
+	const document = parseAnyDocument(JSON.parse(changes.moved), site, collection);
+	await createOnDisk(site, { ...plan.to, title: plan.title, text: changes.moved, document });
+	for (const r of changes.relinked) {
+		const confined = await confineOnDisk(site, r.file);
+		await writeAtomic(confined.absolute, r.text);
+	}
+	if (changes.settings) {
+		const file = join(site.root, SITE_SETTINGS_FILE);
+		if (changes.settings.before === null) {
+			await writeFile(file, changes.settings.after, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+		} else await writeAtomic(file, changes.settings.after);
+	}
+	await deleteOnDisk(site, { ...plan.from, entry: plan.from.entry });
+}
+
+// ── The route ──────────────────────────────────────────────────────────────
+
+const json = (status: number, body: unknown, headers: Record<string, string> = {}) =>
+	new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers },
+	});
+
+/** What the route needs of the drafts store. */
+export interface Moves {
+	move(request: MoveRequest, context?: WriteContext): Promise<MoveResponse>;
+}
+
+/** POST /_caracms/move: a Request in, a Response out, through the mode's store (create.ts's handling, the same checks). */
+export async function handleMove(request: Request, store: Moves, who: { person?: Person | null } = {}): Promise<Response> {
+	try {
+		if (request.method !== 'POST') throw new WriteRefused(405, 'The move route only takes POST.');
+		checkOrigin(request);
+		const type = request.headers.get('content-type') ?? '';
+		if (!/^application\/json\s*(;|$)/i.test(type)) throw new WriteRefused(415, 'Send JSON (Content-Type: application/json).');
+		const length = Number(request.headers.get('content-length') ?? 0);
+		if (length > MAX_CREATE_BODY_BYTES) throw new WriteRefused(413, 'That body is too large.');
+		const raw = await request.text();
+		if (Buffer.byteLength(raw) > MAX_CREATE_BODY_BYTES) throw new WriteRefused(413, 'That body is too large.');
+		let body: unknown;
+		try {
+			body = JSON.parse(raw);
+		} catch {
+			throw refused(400, 'bad-request', 'Malformed body: it isn\'t valid JSON.');
+		}
+		const context: WriteContext = { person: who.person ?? null, tab: tabOf(request), release: request.headers.get(RELEASE_HEADER) === '1', seq: seqOf(request) };
+		return json(200, await store.move(parseMoveBody(body), context));
+	} catch (error) {
+		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body }, error.status === 405 ? { Allow: 'POST' } : {});
+		console.error('[caracms] move failed:', error);
+		return json(500, { error: `That didn't work (${error instanceof Error ? error.message : String(error)}).` });
+	}
+}

package/src/editor/server/render.tsx

@@ -0,0 +1,9 @@
+/** The shell's server render (Decision 2): the chrome is in the HTML before any script runs. */
+import { renderToString } from 'react-dom/server';
+import { createEditor } from '../client/editor.ts';
+import { EditorApp } from '../client/shell/App.tsx';
+import type { AdminProps } from '../types.ts';
+
+export function renderEditor(props: AdminProps): string {
+	return renderToString(<EditorApp editor={createEditor(props, { client: false })} />);
+}

package/src/editor/server/replace.ts

@@ -0,0 +1,72 @@
+/**
+ * Replace… on a file in the library (M6c G4, Decision 9;
+ * notes/2026-10-17-m6c-downloads-grid.md): every link to the old file, in every document
+ * the store lists (Site Settings and shared blocks included), points at the new one,
+ * `?download` and a fragment kept. The rules both stores apply, and what changes.
+ *
+ * - **Links are found by schema** (relink.ts → `refileText`, the walk a page move uses):
+ *   a link field's or a button's `href`, and rich text's links. A plain-text mention of
+ *   the address is never changed.
+ * - **Both keys are a file's** (caracms/files → `isFileKey`), and not the same key: the
+ *   same bytes are the same key (content-addressed), so there's nothing to replace. The
+ *   new file must be in the bucket already (uploaded first, through the upload route):
+ *   the media route checks that before the store is asked (media/handler.ts).
+ * - **Nothing is deleted**: the old file stays in the bucket at its address.
+ *
+ * The stores apply the changes as a move's relinked files are applied: local mode writes
+ * each file (atomic, confined; no rollback, as a local move has none), live mode stores
+ * each as an autosave under this tab's locks and lands whole or rolls back
+ * (live/drafts-store.ts → `replaceFile`).
+ */
+import type { ResolvedSite } from '../../config.ts';
+import type { DocumentEntry } from '../../content.ts';
+import { isFileKey } from '../../files.ts';
+import { refileText } from '../../relink.ts';
+import type { ReplaceFileRequest, ReplaceFileResponse } from '../types.ts';
+import { refused } from './create.ts';
+
+type Site = Pick<ResolvedSite, 'collections' | 'blocks'>;
+
+const SHAPE = '{ from, to }';
+
+/** Validate a replace body's shape and keys. Throws WriteRefused 400. */
+export function parseReplaceBody(body: unknown): ReplaceFileRequest {
+	if (!body || typeof body !== 'object' || Array.isArray(body)) throw refused(400, 'bad-request', `Malformed body: it must be a JSON object. Send ${SHAPE}.`);
+	const b = body as Record<string, unknown>;
+	const extra = Object.keys(b).filter((k) => k !== 'from' && k !== 'to');
+	if (extra.length) throw refused(400, 'bad-request', `Malformed body: unexpected keys. Send ${SHAPE}.`);
+	if (!isFileKey(b.from)) throw refused(400, 'bad-request', '"from" must be a file\'s key in the library (uploads/<hash>/<name>.<ext>).');
+	if (!isFileKey(b.to)) throw refused(400, 'bad-request', '"to" must be a file\'s key in the library (uploads/<hash>/<name>.<ext>).');
+	if (b.from === b.to) throw refused(400, 'same', "That's the same file.");
+	return { from: b.from, to: b.to };
+}
+
+export interface Refiled {
+	file: string;
+	collection: string;
+	path: string;
+	title: string;
+	text: string;
+	links: number;
+}
+
+/** Every document whose text changes, from the store's own texts (`readText` by site-relative file; live mode's has the autosaves on top). */
+export async function replaceChanges(site: Site, request: ReplaceFileRequest, documents: readonly DocumentEntry[], readText: (file: string) => Promise<string | null>): Promise<Refiled[]> {
+	const out: Refiled[] = [];
+	for (const d of documents) {
+		const collection = site.collections[d.collection];
+		if (!collection) continue;
+		const text = await readText(d.file);
+		if (text === null) continue;
+		const after = refileText(text, request.from, request.to, site, collection);
+		if (after.links) out.push({ file: d.file, collection: d.collection, path: d.path, title: d.label, text: after.text, links: after.links });
+	}
+	return out;
+}
+
+export const replaceResponse = (request: ReplaceFileRequest, changes: readonly Refiled[]): ReplaceFileResponse => ({
+	ok: true,
+	from: request.from,
+	to: request.to,
+	relinked: changes.map(({ collection, path, title, links }) => ({ collection, path, title, links })),
+});

package/src/editor/server/settings.ts

@@ -0,0 +1,35 @@
+/**
+ * Site Settings as they apply to the running site (M5a Decision 10): `editors` and
+ * `brand` are read from the **committed** copy, never an autosave, so a half-typed
+ * value is never site-wide.
+ *
+ * - Live mode: the `drafts` copy (`git.read`), as M4's whitelist reads `editors`
+ *   (live/auth/allow.ts). Site Settings' autosave is swept at once (live/sweep.ts →
+ *   `ready`), so a kept change applies on the sweep's next tick.
+ * - Local mode: the file on disk, read on every call, so it applies on the next request.
+ *
+ * The brand: Site Settings' `brand.name` (else "Site") and `brand.accent` (else the
+ * editor's neutral accent, `--accent` in tokens.css), and its `brand.logo` and
+ * `brand.icon` as signed URLs (M5b Decision 11).
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SITE_SETTINGS_FILE, type Brand, type ResolvedSite } from '../../config.ts';
+import { brandFrom } from '../brand.ts';
+import { editorMode, liveEditorOf } from './mode.ts';
+
+export { brandFrom, DEFAULT_BRAND_NAME, editorBrand } from '../brand.ts';
+
+/** Site Settings' committed text for the mode: the `drafts` copy (live) or the disk (local); null when there's none. */
+export async function committedSettingsText(site: ResolvedSite): Promise<string | null> {
+	if (editorMode().kind === 'live') {
+		const live = await liveEditorOf(site);
+		return live!.runtime.git.read(SITE_SETTINGS_FILE);
+	}
+	return readFile(join(site.root, SITE_SETTINGS_FILE), 'utf8').catch(() => null);
+}
+
+/** The brand as it applies now (Decision 10). */
+export async function currentBrand(site: ResolvedSite): Promise<Brand> {
+	return brandFrom(await committedSettingsText(site), site);
+}