caracms 0.1.0 → 0.3.0

package/src/live/auth/request.ts

@@ -6,20 +6,53 @@
 const first = (value: string | null) => (value ?? '').split(',')[0]!.trim();
 
 /**
- * The client's IP, which keys the per-IP rate limits (the template's `clientIp()`,
- * `docs/admin-login.md` → Rate limits and the client IP). In order:
+ * The header `caracms start`'s gate sets on every request, replacing any copy the request
+ * brought (runs-anywhere Decision 8, the spec's Contracts): the visitor's IP, decided from
+ * the one source `CARACMS_CLIENT_IP_HEADER` names.
+ */
+export const CLIENT_IP_HEADER = 'x-caracms-client-ip';
+
+/**
+ * The mark `caracms start` puts on its own process before importing the built site, which
+ * runs in that same process (`bin/gate.mjs` → `GATED_MARK`, `markProcessGated()`):
+ * `globalThis[Symbol.for('caracms.gated')] === true`. It's what makes the header above
+ * trustworthy: with the mark there, every request reached the site through the gate, which
+ * replaced any copy the visitor sent. Without it (`node dist/server/entry.mjs`), nothing
+ * replaced it, so the header is the visitor's to choose and is never read.
+ */
+export const GATED_MARK = Symbol.for('caracms.gated');
+
+/** Whether this process was started by `caracms start` (the mark above). */
+export const isGatedProcess = (): boolean => (globalThis as Record<symbol, unknown>)[GATED_MARK] === true;
+
+/** The 503 on sign-in, forms and downloads of a production server with no gate (Decision 8; acceptance check 17). */
+export const NO_GATE_MESSAGE =
+	"This site wasn't started with `caracms start`, so it can't tell its visitors apart for the limits on signing in, forms and downloads. A developer can start it with `caracms start` (the site's start script).";
+
+/**
+ * The client's IP, which keys the per-IP rate limits (sign-in, forms, downloads).
  *
- * 1. **`X-Real-IP`.** Railway's edge overwrites it with the address that connected, so
- *    behind Railway it's the one value the client can't choose.
- * 2. The socket's address as the adapter gives it (`clientAddress`).
- * 3. The first `X-Forwarded-For` hop, only when there's nothing else. Never ahead of
- *    the socket: the client writes the leftmost hop, so keyed on it an attacker could
- *    rotate past every per-IP limit.
+ * **In production, only `x-caracms-client-ip`**, which `caracms start`'s gate sets on
+ * every request from the one trusted source, and only in a process the gate marked
+ * (`GATED_MARK`). Null when the mark is missing, whatever the request carries: the server
+ * wasn't started by `caracms start`, so a header there is one the visitor sent. Null too
+ * when the header is absent. Either way the caller answers 503 with `NO_GATE_MESSAGE`.
+ * Nothing else on the request is trusted there: Astro's Node adapter reports the first
+ * `X-Forwarded-For` entry as `clientAddress` whenever the Host is trusted, which caracms
+ * always arranges for its own domain, so the adapter's address is the visitor's to choose
+ * (`node_modules/astro/dist/core/app/node.js`), and `X-Real-IP` is trustworthy only behind
+ * a proxy that overwrites it.
  *
- * Off Railway (dev, tests) nothing proxies, so a spoofed `X-Real-IP` only rate-limits
- * the spoofer's own requests: accepted, as in the template.
+ * **Under `astro dev`** (no gate, and nothing to protect), as before: `X-Real-IP`, then
+ * the socket's address as the adapter gives it, then the first `X-Forwarded-For` hop.
+ * A spoofed one only rate-limits the spoofer's own requests.
  */
-export function clientIp(request: Request, clientAddress: () => string | undefined): string {
+export function clientIp(request: Request, clientAddress: () => string | undefined, production = false): string | null {
+	if (production) {
+		if (!isGatedProcess()) return null;
+		const gated = request.headers.get(CLIENT_IP_HEADER)?.trim();
+		return gated ? gated.slice(0, 64) : null;
+	}
 	const real = first(request.headers.get('x-real-ip'));
 	if (real) return real.slice(0, 64);
 	let socket: string | undefined;
@@ -53,4 +86,52 @@ export function isSameOrigin(request: Request): boolean {
 	}
 }
 
+/**
+ * Runs-anywhere Decision 7: the sentence for a site reached at an address that isn't its
+ * own, naming SITE_URL. The likeliest setup mistake: SITE_URL at www while people use the
+ * apex (or the other way round), or set differently at build and at run time.
+ */
+export function addressMismatchMessage(reached: string, address: string | null): string {
+	return address
+		? `This site's address is set to ${address} (SITE_URL), but it was opened at ${reached}, so signing in and saving are refused here. Open it at ${address}, or set SITE_URL to ${reached} where the site is built and where it runs.`
+		: `This site's address isn't set, so signing in and saving are refused. Set SITE_URL to ${reached} where the site is built and where it runs.`;
+}
+
+/** The address the visitor typed (the proxy's forwarded host, else Host), when it isn't the one Astro read the request as. */
+export function reachedElsewhere(request: Request): string | null {
+	const host = first(request.headers.get('x-forwarded-host')) || first(request.headers.get('host'));
+	if (!host) return null;
+	const url = new URL(request.url);
+	if (host === url.host) return null;
+	const proto = first(request.headers.get('x-forwarded-proto')) || url.protocol.replace(':', '');
+	return `${proto}://${host}`;
+}
+
+/**
+ * For a write refused by `isSameOrigin`: the mismatch sentence when the browser was on
+ * this site all along (it says `Sec-Fetch-Site: same-origin`, or its `Origin` is the
+ * request's own Host) but Astro, trusting only the site's address, read the request as
+ * another host. Null for a real cross-site request.
+ */
+export function addressMismatch(request: Request, address: string | null): string | null {
+	let origin: URL;
+	try {
+		origin = new URL(request.headers.get('origin') ?? '');
+	} catch {
+		return null;
+	}
+	if (origin.host === new URL(request.url).host) return null;
+	const fetchSite = request.headers.get('sec-fetch-site');
+	const host = first(request.headers.get('x-forwarded-host')) || first(request.headers.get('host'));
+	if (fetchSite !== 'same-origin' && !(!fetchSite && origin.host === host)) return null;
+	return addressMismatchMessage(origin.origin, address);
+}
+
+/** On a page with no `Origin` (the sign-in form's GET): the sentence when the site is opened at an address that isn't its own. */
+export function addressNotice(request: Request, address: string | null): string | null {
+	const reached = reachedElsewhere(request);
+	if (!reached || (address && new URL(address).host === new URL(reached).host)) return null;
+	return addressMismatchMessage(reached, address);
+}
+
 export const isRead = (method: string) => method === 'GET' || method === 'HEAD';

package/src/live/auth/views.ts

@@ -301,9 +301,9 @@ const FINE = html`<p class="fine">Not you? Close this tab.</p>`;
 const backupLink = (next: string) => html`<p class="si-alt"><a class="linkbtn" href="${loginHref({ backup: '1' }, next)}">Use the backup account</a></p>`;
 
 /** The email form: plain, signed out, or with the malformed-address error. */
-export function emailView(input: { next: string; value?: string; invalid?: string; signedOut?: boolean; backupEnabled: boolean }): SafeHtml {
+export function emailView(input: { next: string; value?: string; invalid?: string; signedOut?: boolean; backupEnabled: boolean; notice?: string | null }): SafeHtml {
 	const bad = !!input.invalid;
-	return html`<section class="si-card">${input.signedOut ? html`<p class="notice info" role="status">${ic('check', 'i-sm')}You're signed out.</p>` : ''}<h1>Sign in</h1><p class="sub">We'll email you a sign-in link.</p><form method="post" action="${LOGIN_PATH}" novalidate><input type="hidden" name="next" value="${input.next}"><div class="field"><label class="field-label" for="si-email">Email address</label><input class="input" id="si-email" name="email" type="email" autocomplete="email" inputmode="email" spellcheck="false" autofocus value="${input.value ?? ''}"${new SafeHtml(bad ? ' aria-invalid="true" aria-describedby="si-err"' : '')}>${
+	return html`<section class="si-card">${addressNoticeHtml(input.notice)}${input.signedOut ? html`<p class="notice info" role="status">${ic('check', 'i-sm')}You're signed out.</p>` : ''}<h1>Sign in</h1><p class="sub">We'll email you a sign-in link.</p><form method="post" action="${LOGIN_PATH}" novalidate><input type="hidden" name="next" value="${input.next}"><div class="field"><label class="field-label" for="si-email">Email address</label><input class="input" id="si-email" name="email" type="email" autocomplete="email" inputmode="email" spellcheck="false" autofocus value="${input.value ?? ''}"${new SafeHtml(bad ? ' aria-invalid="true" aria-describedby="si-err"' : '')}>${
 		bad ? html`<p class="field-err" id="si-err">${ic('warn', 'i-sm')}<span>${input.invalid}</span></p>` : ''
 	}</div><button class="btn accent block" type="submit">Send sign-in link</button></form></section>${input.backupEnabled ? backupLink(input.next) : ''}`;
 }
@@ -317,9 +317,14 @@ export function sentView(input: { email: string; next: string; again: boolean; b
 	return html`<section class="si-card">${input.again ? html`<p class="notice ok" role="status">${ic('check', 'i-sm')}Sent again.</p>` : ''}<h1>Check your email</h1><p>If <strong>${input.email}</strong> can sign in, a link is on its way. It expires in 15 minutes.</p><p class="fine">Not there? Check spam, or send again.</p><div class="row-acts"><form method="post" action="${LOGIN_PATH}"><input type="hidden" name="email" value="${input.email}"><input type="hidden" name="next" value="${input.next}"><input type="hidden" name="again" value="1"><button class="btn" type="submit">Send again</button></form><a class="linkbtn" href="${loginHref({}, input.next)}">Use a different address</a></div></section>${input.backupEnabled ? backupLink(input.next) : ''}`;
 }
 
+/** Runs-anywhere Decision 7: the site was opened at an address that isn't its own (request.ts → `addressNotice`). */
+function addressNoticeHtml(notice: string | null | undefined): SafeHtml | string {
+	return notice ? html`<p class="notice fail" role="alert" data-notice="address">${ic('warn', 'i-sm')}${notice}</p>` : '';
+}
+
 /** The backup form. Posting it without script only shows it again. */
-export function backupView(input: { next: string }): SafeHtml {
-	return html`<section class="si-card"><p class="notice fail" id="signin-error" role="alert" hidden></p><h1>Backup account</h1><p class="sub">Details are in the shared password manager.</p>${NOSCRIPT}<form method="post" action="${loginHref({ backup: '1' }, input.next)}" data-signin="backup" data-next="${input.next}"><div class="field"><label class="field-label" for="si-user">Username</label><input class="input" id="si-user" name="username" autocomplete="username" autocapitalize="off" spellcheck="false" autofocus required></div><div class="field"><label class="field-label" for="si-pass">Password</label><input class="input" id="si-pass" name="password" type="password" autocomplete="current-password" required></div><button class="btn accent block" type="submit">Sign in</button></form></section><p class="si-alt"><a class="linkbtn" href="${loginHref({}, input.next)}">Use email sign-in instead</a></p>`;
+export function backupView(input: { next: string; notice?: string | null }): SafeHtml {
+	return html`<section class="si-card">${addressNoticeHtml(input.notice)}<p class="notice fail" id="signin-error" role="alert" hidden></p><h1>Backup account</h1><p class="sub">Details are in the shared password manager.</p>${NOSCRIPT}<form method="post" action="${loginHref({ backup: '1' }, input.next)}" data-signin="backup" data-next="${input.next}"><div class="field"><label class="field-label" for="si-user">Username</label><input class="input" id="si-user" name="username" autocomplete="username" autocapitalize="off" spellcheck="false" autofocus required></div><div class="field"><label class="field-label" for="si-pass">Password</label><input class="input" id="si-pass" name="password" type="password" autocomplete="current-password" required></div><button class="btn accent block" type="submit">Sign in</button></form></section><p class="si-alt"><a class="linkbtn" href="${loginHref({}, input.next)}">Use email sign-in instead</a></p>`;
 }
 
 /**

package/src/live/autosaves.ts

@@ -41,10 +41,14 @@
  * counts while its old file is gone and its new file is there (`movesIn`, git.ts).
  *
  * Paths are site-relative (`content/pages/index.json`). Values are JSON text.
+ *
+ * **The status cache** (status-cache.ts, Redis diet Decision 2): every write here of a
+ * key the status poll reads (autosaves, change records, moves) tells it what landed.
  */
 import type { AnyDocument } from '../document.ts';
 import type { Person } from './messages.ts';
 import type { RedisClient } from './redis.ts';
+import { landed, type StatusCache } from './status-cache.ts';
 import type { LiveTimings } from './timings.ts';
 
 export interface Autosave {
@@ -131,17 +135,34 @@ export class Autosaves {
 	readonly timings: LiveTimings;
 	readonly now: () => number;
 	readonly prefix: string;
+	private readonly cache: StatusCache | null;
 
-	constructor(redis: RedisClient, timings: LiveTimings, now: () => number, prefix = 'caracms:') {
+	constructor(redis: RedisClient, timings: LiveTimings, now: () => number, prefix = 'caracms:', cache: StatusCache | null = null) {
 		this.redis = redis;
 		this.timings = timings;
 		this.now = now;
 		this.prefix = prefix;
+		this.cache = cache;
 	}
 
 	key = (file: string) => `${this.prefix}autosave:${file}`;
+	/** What every autosave key starts with (the status cache scans it). */
+	get keyPrefix(): string {
+		return this.key('');
+	}
 	private committedKey = (file: string) => `${this.prefix}committed:${file}`;
-	private changedKey = (file: string) => `${this.prefix}changed:${file}`;
+	readonly changedKey = (file: string) => `${this.prefix}changed:${file}`;
+	readonly movesKey = () => movesKey(this.prefix);
+
+	/** A compare-and-swap (or delete) on an autosave key, and the status cache told what came of it. */
+	private async swap(key: string, expected: string | null, raw: string | null): Promise<boolean> {
+		const ok = await landed(this.cache, key, () =>
+			raw === null ? this.redis.compareAndDelete(key, expected!) : this.redis.compareAndSet(key, expected, raw, { px: this.timings.autosaveTtlMs }),
+		);
+		if (ok) this.cache?.string(key, raw);
+		else this.cache?.drop(key);
+		return ok;
+	}
 
 	async get(file: string): Promise<Read<Autosave> | null> {
 		const raw = await this.redis.get(this.key(file));
@@ -151,30 +172,34 @@ export class Autosaves {
 
 	/** Every autosave: one SCAN and one MGET. */
 	async all(): Promise<Read<Autosave>[]> {
-		const keys = await this.redis.scan(`${this.prefix}autosave:*`);
+		const keys = await this.redis.scan(`${this.keyPrefix}*`);
 		if (keys.length === 0) return [];
-		const raws = await this.redis.mget(keys);
+		return Autosaves.allFrom(await this.redis.mget(keys));
+	}
+
+	/** The autosaves among these values (a scan of `keyPrefix`'s, read). */
+	static allFrom(raws: Iterable<string | null>): Read<Autosave>[] {
 		const out: Read<Autosave>[] = [];
-		raws.forEach((raw) => {
+		for (const raw of raws) {
 			const value = parse<Autosave>(raw);
 			if (raw !== null && value) out.push({ raw, value });
-		});
+		}
 		return out;
 	}
 
 	/** Store it only if the autosave is still what was read (`null`: only if there's none), so a write that read an older one never replaces a newer. */
 	putIf(read: Read<Autosave> | null, autosave: Autosave): Promise<boolean> {
-		return this.redis.compareAndSet(this.key(autosave.file), read?.raw ?? null, JSON.stringify(autosave), { px: this.timings.autosaveTtlMs });
+		return this.swap(this.key(autosave.file), read?.raw ?? null, JSON.stringify(autosave));
 	}
 
 	/** Delete it only if it's still what was read (a newer write wins). */
 	removeIf(read: Read<Autosave>): Promise<boolean> {
-		return this.redis.compareAndDelete(this.key(read.value.file), read.raw);
+		return this.swap(this.key(read.value.file), read.raw, null);
 	}
 
 	/** Replace it only if it's still what was read. */
 	replaceIf(read: Read<Autosave>, next: Autosave): Promise<boolean> {
-		return this.redis.compareAndSet(this.key(next.file), read.raw, JSON.stringify(next), { px: this.timings.autosaveTtlMs });
+		return this.swap(this.key(next.file), read.raw, JSON.stringify(next));
 	}
 
 	async committed(file: string): Promise<Committed | null> {
@@ -186,7 +211,12 @@ export class Autosaves {
 	}
 
 	async changed(file: string): Promise<ChangeRecord | null> {
-		return parse<ChangeRecord>(await this.redis.get(this.changedKey(file)));
+		return Autosaves.changedFrom(await this.redis.get(this.changedKey(file)));
+	}
+
+	/** A change record from its text as read. */
+	static changedFrom(raw: string | null): ChangeRecord | null {
+		return parse<ChangeRecord>(raw);
 	}
 
 	/** Several files' records in one MGET (the documents list's "Last edited"), in the order asked; none: null. */
@@ -197,7 +227,9 @@ export class Autosaves {
 
 	/** No expiry: one small key per file, overwritten on each change, so "who changed it" is never forgotten while Redis keeps its data. */
 	async setChanged(file: string, record: ChangeRecord): Promise<void> {
-		await this.redis.set(this.changedKey(file), JSON.stringify(record));
+		const raw = JSON.stringify(record);
+		await landed(this.cache, this.changedKey(file), () => this.redis.set(this.changedKey(file), raw));
+		this.cache?.string(this.changedKey(file), raw);
 	}
 
 	/**
@@ -205,7 +237,8 @@ export class Autosaves {
 	 * from `main` leaves `{ by: null }` ("only merges"), and never overwrites an editor's.
 	 */
 	async setChangedIfAbsent(file: string, record: Omit<ChangeRecord, 'by'> & { by: Person | null }): Promise<void> {
-		await this.redis.set(this.changedKey(file), JSON.stringify(record), { nx: true });
+		const raw = JSON.stringify(record);
+		if (await landed(this.cache, this.changedKey(file), () => this.redis.set(this.changedKey(file), raw, { nx: true }))) this.cache?.string(this.changedKey(file), raw);
 	}
 
 	/** Pre-M7 item 8: the moves waiting to publish, old file → new file. */
@@ -213,6 +246,16 @@ export class Autosaves {
 		return new Map(Object.entries(await this.redis.hgetall(movesKey(this.prefix))));
 	}
 
+	private async setMove(from: string, to: string): Promise<void> {
+		await landed(this.cache, movesKey(this.prefix), () => this.redis.hset(movesKey(this.prefix), { [from]: to }));
+		this.cache?.hash(movesKey(this.prefix), { [from]: to });
+	}
+
+	private async dropMoves(...from: string[]): Promise<void> {
+		await landed(this.cache, movesKey(this.prefix), () => this.redis.hdel(movesKey(this.prefix), ...from));
+		this.cache?.hash(movesKey(this.prefix), {}, from);
+	}
+
 	/**
 	 * A document moved from `from` to `to`. Moved since the last Publish already (a record
 	 * ends at `from`): that record now ends at `to`, or goes when `to` is where it started
@@ -223,16 +266,16 @@ export class Autosaves {
 		const moves = await this.moves();
 		const earlier = [...moves].find(([, t]) => t === from)?.[0];
 		if (earlier !== undefined) {
-			if (earlier === to) await this.redis.hdel(movesKey(this.prefix), earlier);
-			else await this.redis.hset(movesKey(this.prefix), { [earlier]: to });
-		} else if (wasLive) await this.redis.hset(movesKey(this.prefix), { [from]: to });
+			if (earlier === to) await this.dropMoves(earlier);
+			else await this.setMove(earlier, to);
+		} else if (wasLive) await this.setMove(from, to);
 	}
 
 	/** A deleted document's move, if it was moved, is no move any more: it's a deletion. */
 	async forgetMoveTo(file: string): Promise<void> {
 		const moves = await this.moves();
 		const olds = [...moves].filter(([, t]) => t === file).map(([o]) => o);
-		if (olds.length) await this.redis.hdel(movesKey(this.prefix), ...olds);
+		if (olds.length) await this.dropMoves(...olds);
 	}
 
 	/** The merge's ancestor for an autosave (Decision 6). See `ancestorFor`. */

package/src/live/backend.ts

@@ -15,7 +15,7 @@
  */
 import { createHash } from 'node:crypto';
 import { gunzipSync } from 'node:zlib';
-import { GitHubClient, GraphQLError, HttpError, Tracker } from './github.ts';
+import { GitHubClient, GraphQLError, HttpError, Tracker, type GitHubAccessProblem } from './github.ts';
 
 export interface Head {
 	commit: string;
@@ -26,7 +26,10 @@ export interface Heads {
 	drafts: Head;
 }
 
-export type Branch = 'main' | 'drafts';
+import type { Branch, BranchNames } from './branches.ts';
+import { DEFAULT_BRANCHES } from './branches.ts';
+
+export { DEFAULT_BRANCHES, type Branch, type BranchNames };
 
 export interface CommitSummary {
 	sha: string;
@@ -111,6 +114,8 @@ export class MissingBranchError extends Error {
 export interface GitBackend {
 	readonly tracker: Tracker;
 	readonly name: 'github' | 'memory';
+	/** The ref name behind each role. */
+	readonly branches: Readonly<BranchNames>;
 	/** Both heads, in one request. Throws MissingBranchError. */
 	readHeads(): Promise<Heads>;
 	createBranch(branch: Branch, sha: string): Promise<void>;
@@ -134,6 +139,8 @@ export interface GitBackend {
 	listDeployments(count: number): Promise<Deployment[]>;
 	/** A deployment's newest status, or null when it has none yet. */
 	deploymentStatus(id: number): Promise<DeploymentStatus | null>;
+	/** What's wrong with GitHub access now, from the responses so far (runs-anywhere Decision 5); null when nothing is. */
+	accessProblem(): GitHubAccessProblem | null;
 }
 
 /** Is this GraphQL error a stale head (someone moved the ref)? M1 → G6 (a): often it can't tell. */
@@ -144,11 +151,11 @@ export function isStaleGraphQL(errors: { type?: string; message?: string }[]): b
 
 // ── GitHub ────────────────────────────────────────────────────────────────────
 
-const HEADS_QUERY = `query($owner: String!, $name: String!) {
+const HEADS_QUERY = `query($owner: String!, $name: String!, $main: String!, $drafts: String!) {
   repository(owner: $owner, name: $name) {
     id
-    main: ref(qualifiedName: "refs/heads/main") { target { oid ... on Commit { tree { oid } } } }
-    drafts: ref(qualifiedName: "refs/heads/drafts") { target { oid ... on Commit { tree { oid } } } }
+    main: ref(qualifiedName: $main) { target { oid ... on Commit { tree { oid } } } }
+    drafts: ref(qualifiedName: $drafts) { target { oid ... on Commit { tree { oid } } } }
   }
 }`;
 
@@ -168,19 +175,29 @@ const COMPARE_FILE_CAP = 300;
 export class GitHubBackend implements GitBackend {
 	readonly name = 'github';
 	readonly gh: GitHubClient;
+	readonly branches: Readonly<BranchNames>;
 	private repoId = '';
 
-	constructor(gh: GitHubClient) {
+	constructor(gh: GitHubClient, branches: Readonly<BranchNames> = DEFAULT_BRANCHES) {
 		this.gh = gh;
+		this.branches = branches;
+	}
+	/** `refs/heads/<name>` for a role. */
+	private qualified(branch: Branch) {
+		return `refs/heads/${this.branches[branch]}`;
 	}
 	get tracker() {
 		return this.gh.tracker;
 	}
 
+	accessProblem(): GitHubAccessProblem | null {
+		return this.gh.accessProblem();
+	}
+
 	async readHeads(): Promise<Heads> {
 		const d = await this.gh.graphql<{ repository: { id: string; main: RefNode; drafts: RefNode } }>(
 			HEADS_QUERY,
-			{ owner: this.gh.owner, name: this.gh.repo },
+			{ owner: this.gh.owner, name: this.gh.repo, main: this.qualified('main'), drafts: this.qualified('drafts') },
 			'readHeads',
 		);
 		this.repoId = d.repository.id;
@@ -192,7 +209,7 @@ export class GitHubBackend implements GitBackend {
 	}
 
 	async createBranch(branch: Branch, sha: string) {
-		await this.gh.rest('POST', this.gh.repoPath('/git/refs'), { ref: `refs/heads/${branch}`, sha });
+		await this.gh.rest('POST', this.gh.repoPath('/git/refs'), { ref: this.qualified(branch), sha });
 	}
 
 	async readArchive(commit: string, keep: (path: string) => boolean) {
@@ -253,7 +270,7 @@ export class GitHubBackend implements GitBackend {
 				COMMIT_ON_BRANCH,
 				{
 					input: {
-						branch: { repositoryNameWithOwner: this.gh.nameWithOwner, branchName: branch },
+						branch: { repositoryNameWithOwner: this.gh.nameWithOwner, branchName: this.branches[branch] },
 						expectedHeadOid: expectedHead,
 						message: { headline, body },
 						fileChanges: {
@@ -295,7 +312,7 @@ export class GitHubBackend implements GitBackend {
 				{
 					input: {
 						repositoryId: this.repoId,
-						refUpdates: updates.map((u) => ({ name: `refs/heads/${u.branch}`, beforeOid: u.before, afterOid: u.after, force: u.force })),
+						refUpdates: updates.map((u) => ({ name: this.qualified(u.branch), beforeOid: u.before, afterOid: u.after, force: u.force })),
 					},
 				},
 				'updateRefs',
@@ -309,7 +326,7 @@ export class GitHubBackend implements GitBackend {
 	async listCommits(branch: Branch, count: number) {
 		const list = await this.gh.rest<{ sha: string; parents: { sha: string }[]; commit: { message: string; committer: { date: string } } }[]>(
 			'GET',
-			this.gh.repoPath(`/commits?sha=${branch}&per_page=${Math.min(100, count)}`),
+			this.gh.repoPath(`/commits?sha=${encodeURIComponent(this.branches[branch])}&per_page=${Math.min(100, count)}`),
 		);
 		return list.map((k) => ({ sha: k.sha, parents: k.parents.map((p) => p.sha), message: k.commit.message, date: k.commit.committer.date }));
 	}
@@ -395,21 +412,30 @@ export const blobSha = (contents: string) => {
 export class MemoryBackend implements GitBackend {
 	readonly name = 'memory';
 	readonly tracker: Tracker;
+	readonly branches: Readonly<BranchNames>;
 	/** Deployments, newest last; tests push to it. */
 	deployments: MemoryDeployment[] = [];
 	/** Called before each recorded request, with its endpoint: tests inject races here. */
 	beforeRequest: ((endpoint: string) => Promise<void> | void) | null = null;
+	/** The GitHub access problem the status reports; tests set it (the GitHub client's own is tested with faked responses). */
+	access: GitHubAccessProblem | null = null;
 	private readonly now: () => number;
 	private inHook = false;
 	private blobs = new Map<string, string>();
 	private trees = new Map<string, MemTree>();
 	private commits = new Map<string, MemCommit>();
-	refs = new Map<Branch, string>();
+	/** Every ref, by its name (not its role): a test can seed a branch caracms mustn't touch. */
+	refs = new Map<string, string>();
 	private n = 0;
 
-	constructor(tracker = new Tracker(), options: { now?: () => number } = {}) {
+	constructor(tracker = new Tracker(), options: { now?: () => number; branches?: Readonly<BranchNames> } = {}) {
 		this.tracker = tracker;
 		this.now = options.now ?? Date.now;
+		this.branches = options.branches ?? DEFAULT_BRANCHES;
+	}
+	/** The ref name behind a role. */
+	private ref(branch: Branch) {
+		return this.branches[branch];
 	}
 
 	private async rec(endpoint: string, creating: boolean, status = 200) {
@@ -464,7 +490,7 @@ export class MemoryBackend implements GitBackend {
 		return c;
 	}
 	private head(branch: Branch): Head {
-		const c = this.refs.get(branch);
+		const c = this.refs.get(this.ref(branch));
 		if (!c) throw new MissingBranchError(branch);
 		return { commit: c, tree: this.commit(c).tree };
 	}
@@ -479,12 +505,12 @@ export class MemoryBackend implements GitBackend {
 
 	// Test helpers (not part of GitBackend; record no requests).
 
-	/** Start the repo: one parentless commit with these files on `main` (and `drafts`, if asked). */
+	/** Start the repo: one parentless commit with these files on the main branch (and the drafts branch, if asked). */
 	seed(files: FileWrite[], options: { drafts?: boolean } = {}): string {
 		const tree = this.putTree(new Map(files.map((f) => [f.path, { sha: this.blob(f.contents), mode: '100644' }])));
 		const seed = this.putCommit(tree, [], 'Seed');
-		this.refs.set('main', seed);
-		if (options.drafts) this.refs.set('drafts', seed);
+		this.refs.set(this.ref('main'), seed);
+		if (options.drafts) this.refs.set(this.ref('drafts'), seed);
 		return seed;
 	}
 
@@ -497,7 +523,7 @@ export class MemoryBackend implements GitBackend {
 			else t.set(path, { sha: this.blob(contents), mode: '100644' });
 		}
 		const c = this.putCommit(this.putTree(t), [head.commit], message);
-		this.refs.set(branch, c);
+		this.refs.set(this.ref(branch), c);
 		return c;
 	}
 
@@ -523,6 +549,10 @@ export class MemoryBackend implements GitBackend {
 
 	// GitBackend.
 
+	accessProblem(): GitHubAccessProblem | null {
+		return this.access;
+	}
+
 	async readHeads() {
 		await this.rec('graphql readHeads', false);
 		return { main: this.head('main'), drafts: this.head('drafts') };
@@ -530,9 +560,9 @@ export class MemoryBackend implements GitBackend {
 
 	async createBranch(branch: Branch, sha: string) {
 		await this.rec('POST /git/refs', true);
-		if (this.refs.has(branch)) throw new HttpError(422, 'Reference already exists', null);
+		if (this.refs.has(this.ref(branch))) throw new HttpError(422, 'Reference already exists', null);
 		this.commit(sha);
-		this.refs.set(branch, sha);
+		this.refs.set(this.ref(branch), sha);
 	}
 
 	async readArchive(commit: string, keep: (path: string) => boolean) {
@@ -574,14 +604,14 @@ export class MemoryBackend implements GitBackend {
 
 	async commitOnBranch(branch: Branch, expectedHead: string, additions: FileWrite[], deletions: string[], headline: string, body: string) {
 		await this.rec('graphql createCommitOnBranch', true);
-		const cur = this.refs.get(branch);
+		const cur = this.refs.get(this.ref(branch));
 		if (cur !== expectedHead) throw new StaleHeadError(`Expected branch to point to "${expectedHead}" but it did not. Pull and try again.`);
 		const t = new Map(this.trees.get(this.commit(cur).tree)!);
 		for (const f of additions) t.set(f.path, { sha: this.blob(f.contents), mode: '100644' });
 		for (const p of deletions) t.delete(p);
 		const tree = this.putTree(t);
 		const c = this.putCommit(tree, [cur], body ? `${headline}\n\n${body}` : headline);
-		this.refs.set(branch, c);
+		this.refs.set(this.ref(branch), c);
 		return { commit: c, tree };
 	}
 
@@ -606,10 +636,10 @@ export class MemoryBackend implements GitBackend {
 		await this.rec('graphql updateRefs', true);
 		for (const u of updates) {
 			// GitHub's answer here is a generic error, not a typed one (M1 → G6 (a)).
-			if (this.refs.get(u.branch) !== u.before) throw new GraphQLError([{ message: 'Something went wrong while executing your query.' }]);
+			if (this.refs.get(this.ref(u.branch)) !== u.before) throw new GraphQLError([{ message: 'Something went wrong while executing your query.' }]);
 			if (!u.force && !this.isAncestor(u.before, u.after)) throw new GraphQLError([{ message: 'Something went wrong while executing your query.' }]);
 		}
-		for (const u of updates) this.refs.set(u.branch, u.after); // all or nothing
+		for (const u of updates) this.refs.set(this.ref(u.branch), u.after); // all or nothing
 	}
 
 	async listCommits(branch: Branch, count: number) {

package/src/live/branches.ts

@@ -0,0 +1,19 @@
+/**
+ * The ref names behind each branch role (M9 Decision 6). `main` is what's published
+ * (and deployed); `drafts` is where autosaves land. `CARACMS_MAIN_BRANCH` and
+ * `CARACMS_DRAFTS_BRANCH` name them (mode.ts), defaulting to `main` and `drafts`.
+ * With both named, a branch called `main` is never read or moved.
+ *
+ * Only the backends (backend.ts) turn a role into a name; everything above them speaks
+ * in roles. No imports here, so mode.ts can read it without the backends.
+ */
+
+/** A branch's role, not its name. */
+export type Branch = 'main' | 'drafts';
+
+export interface BranchNames {
+	main: string;
+	drafts: string;
+}
+
+export const DEFAULT_BRANCHES: Readonly<BranchNames> = Object.freeze({ main: 'main', drafts: 'drafts' });

package/src/live/drafts-store.ts

@@ -41,7 +41,7 @@ import { parseAnyDocument } from '../document.ts';
 import type { DraftsStore } from '../editor/server/drafts-store.ts';
 import { confinePath, fileVersion, WriteRefused, writeText, type WriteContext, type WriteRequest, type WriteResponse } from '../editor/server/write.ts';
 import type { CreateResponse, DeleteResponse, LastChange, LockRefusal, MoveResponse, ReplaceFileResponse } from '../editor/types.ts';
-import type { Autosave, Autosaves, Read } from './autosaves.ts';
+import type { Autosave, Autosaves, ChangeRecord, Read } from './autosaves.ts';
 import { titleOf, type LiveGit } from './git.ts';
 import type { LockRecord, Locks } from './locks.ts';
 import { displayName, type Person } from './messages.ts';
@@ -79,8 +79,9 @@ export function unavailable(error: unknown): WriteRefused {
  * expire, so a file with none was never changed in the editor or Redis lost its data, and
  * the server can't tell which: the keeper holds edits on unknown rather than re-send them.
  */
-export async function lastChangeOf(parts: Pick<LiveStoreParts, 'git' | 'autosaves'>, file: string): Promise<LastChange> {
-	const record = await parts.autosaves.changed(file);
+/** `known`: the file's change record as the caller already read it (the status poll's cache); otherwise read here. */
+export async function lastChangeOf(parts: Pick<LiveStoreParts, 'git' | 'autosaves'>, file: string, known?: ChangeRecord | null): Promise<LastChange> {
+	const record = known !== undefined ? known : await parts.autosaves.changed(file);
 	if (record) return { by: record.by, version: record.version, at: record.at };
 	const editor = parts.git.waiting().find((w) => w.file === file)?.editors[0];
 	return editor ? { by: editor.person, version: null, at: editor.at } : { by: null, version: null, at: null, known: false };