caracms 0.2.0 → 0.3.1

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;
@@ -139,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. */
@@ -188,6 +190,10 @@ export class GitHubBackend implements GitBackend {
 		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,
@@ -411,6 +417,8 @@ export class MemoryBackend implements GitBackend {
 	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>();
@@ -541,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') };

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 };