caracms 0.0.0-stage → 0.2.0

package/src/live/github.ts

@@ -0,0 +1,271 @@
+/**
+ * GitHub as the site's App (M4 Phase 1; lifted from M1's spike, `spikes/git/src/github.ts`).
+ *
+ * - **The App's JWT**: RS256, signed with the App's private key, `iat` backdated a
+ *   minute for clock drift, nine minutes long (GitHub's limit is ten).
+ * - **An installation token scoped to the one repo**: the installation is found with
+ *   `GET /repos/{owner}/{repo}/installation`, and the token is minted for that repo
+ *   only. It's refreshed five minutes before it expires (they last an hour).
+ * - Every response is recorded by a Tracker, tagged with the operation it belongs to,
+ *   so a run can be checked against the content-creating cap (80 a minute, 500 an
+ *   hour; M1 → G4).
+ *
+ * - **Every request times out** after `timeoutMs` (20 s), its body included: a GitHub
+ *   that stops answering fails the operation instead of holding it (and Publish's or
+ *   the check's callers) forever.
+ *
+ * The private key is never logged.
+ */
+import { createSign } from 'node:crypto';
+
+const API = 'https://api.github.com';
+
+export interface AppConnection {
+	appId: string;
+	/** The PEM. Railway variables often carry it with literal `\n`s; those are turned back into newlines. */
+	privateKey: string;
+	owner: string;
+	repo: string;
+	/** For tests. Default: global fetch. */
+	fetch?: typeof fetch;
+	/** Default: Date.now. */
+	now?: () => number;
+	/** How long one request may take, response body included, before it fails (default 20 s). */
+	timeoutMs?: number;
+}
+
+/** A GitHub request that takes longer than this fails (its caller treats it as any failure). */
+export const GITHUB_TIMEOUT_MS = 20_000;
+
+const b64url = (b: Buffer | string) => Buffer.from(b).toString('base64url');
+
+/** The App's JWT. */
+export function appJwt(appId: string, key: string, nowSeconds = Math.floor(Date.now() / 1000)): string {
+	const header = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+	const payload = b64url(JSON.stringify({ iat: nowSeconds - 60, exp: nowSeconds + 540, iss: appId }));
+	const signer = createSign('RSA-SHA256');
+	signer.update(`${header}.${payload}`);
+	return `${header}.${payload}.${b64url(signer.sign(key))}`;
+}
+
+export class HttpError extends Error {
+	readonly status: number;
+	readonly body: unknown;
+	constructor(status: number, message: string, body: unknown) {
+		super(message);
+		this.name = 'HttpError';
+		this.status = status;
+		this.body = body;
+	}
+}
+
+export class GraphQLError extends Error {
+	readonly errors: { type?: string; message?: string }[];
+	constructor(errors: { type?: string; message?: string }[]) {
+		super(`GraphQL: ${errors.map((e) => `${e.type ?? '?'}: ${e.message}`).join(' | ')}`);
+		this.name = 'GraphQLError';
+		this.errors = errors;
+	}
+}
+
+/** One request, as the Tracker keeps it. */
+export interface RequestRecord {
+	/** The operation instance: `draft #2`, `publish #1`. */
+	op: string;
+	/** Its kind: `draft`, `publish`, `merge`, `start`, `check`, `status`… */
+	kind: string;
+	/** `POST /git/commits`, `graphql createCommitOnBranch`. */
+	endpoint: string;
+	status: number;
+	/** Counts against GitHub's content-creating cap. */
+	creating: boolean;
+	at: number;
+}
+
+/** Is this request content-creating in GitHub's sense? */
+export function isContentCreating(method: string, path: string, graphqlMutation: boolean): boolean {
+	if (graphqlMutation) return true;
+	if (method === 'GET' || method === 'HEAD') return false;
+	return /\/git\/(blobs|trees|commits|refs)|\/contents\/|\/merges$|\/deployments/.test(path);
+}
+
+/** Records every request against the operation running at the time. */
+export class Tracker {
+	records: RequestRecord[] = [];
+	private op = 'other';
+	private kind = 'other';
+	private counters = new Map<string, number>();
+	private readonly now: () => number;
+
+	constructor(now: () => number = Date.now) {
+		this.now = now;
+	}
+
+	/** Run `fn` with its requests tagged as one instance of `kind` (`draft` → `draft #2`). */
+	async within<T>(kind: string, fn: () => Promise<T>): Promise<T> {
+		const prev = [this.op, this.kind] as const;
+		const n = (this.counters.get(kind) ?? 0) + 1;
+		this.counters.set(kind, n);
+		this.op = `${kind} #${n}`;
+		this.kind = kind;
+		try {
+			return await fn();
+		} finally {
+			[this.op, this.kind] = prev;
+		}
+	}
+
+	record(r: { endpoint: string; status: number; creating: boolean }) {
+		this.records.push({ ...r, op: this.op, kind: this.kind, at: this.now() });
+		if (this.records.length > 2000) this.records.splice(0, this.records.length - 2000);
+	}
+
+	/** Content-creating requests in the last `ms` (the cap is 80 a minute, 500 an hour). */
+	creatingWithin(ms: number): number {
+		const since = this.now() - ms;
+		return this.records.filter((r) => r.creating && r.at >= since).length;
+	}
+}
+
+/** `/git/commits/abc…` → `/git/commits/:sha`, so a table groups by endpoint. */
+function shorten(p: string): string {
+	return p
+		.replace(/\b[0-9a-f]{40}\b/g, ':sha')
+		.replace(/\/compare\/.*$/, '/compare/:range')
+		.replace(/\/git\/refs\/heads\/.*$/, '/git/refs/heads/:branch')
+		.replace(/\/git\/ref\/heads\/.*$/, '/git/ref/heads/:branch')
+		.replace(/\/tarball\/.*$/, '/tarball/:ref')
+		.replace(/\/deployments\/\d+/, '/deployments/:id')
+		.replace(/\/contents\/.*$/, '/contents/:path');
+}
+
+export class GitHubClient {
+	readonly tracker: Tracker;
+	readonly owner: string;
+	readonly repo: string;
+	private readonly appId: string;
+	private readonly key: string;
+	private readonly fetcher: typeof fetch;
+	private readonly now: () => number;
+	private readonly timeoutMs: number;
+	private token = '';
+	private tokenExpires = 0;
+	private signingIn: Promise<void> | null = null;
+
+	constructor(connection: AppConnection, tracker: Tracker) {
+		this.appId = connection.appId;
+		this.key = connection.privateKey.includes('\\n') ? connection.privateKey.replace(/\\n/g, '\n') : connection.privateKey;
+		this.owner = connection.owner;
+		this.repo = connection.repo;
+		this.fetcher = connection.fetch ?? fetch;
+		this.now = connection.now ?? Date.now;
+		this.timeoutMs = connection.timeoutMs ?? GITHUB_TIMEOUT_MS;
+		this.tracker = tracker;
+	}
+
+	get nameWithOwner() {
+		return `${this.owner}/${this.repo}`;
+	}
+
+	repoPath(p = ''): string {
+		return `/repos/${this.owner}/${this.repo}${p}`;
+	}
+
+	/** Find the App's installation on the repo and mint a token for that repo only. */
+	private async signIn(): Promise<void> {
+		const jwt = appJwt(this.appId, this.key, Math.floor(this.now() / 1000));
+		const install = (await this.request('GET', this.repoPath('/installation'), undefined, jwt).catch((error: unknown) => {
+			if (error instanceof HttpError && error.status === 404) {
+				throw new Error(`The GitHub App (id ${this.appId}) isn't installed on ${this.nameWithOwner}. Install it on that repo.`);
+			}
+			throw error;
+		})) as { id: number };
+		const tok = (await this.request('POST', `/app/installations/${install.id}/access_tokens`, { repositories: [this.repo] }, jwt, true)) as {
+			token: string;
+			expires_at: string;
+		};
+		this.token = tok.token;
+		this.tokenExpires = Date.parse(tok.expires_at);
+	}
+
+	/** The installation token, refreshed five minutes before it expires. */
+	private async auth(): Promise<string> {
+		if (!this.token || this.now() > this.tokenExpires - 5 * 60_000) {
+			this.signingIn ??= this.signIn().finally(() => {
+				this.signingIn = null;
+			});
+			await this.signingIn;
+		}
+		return this.token;
+	}
+
+	async rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T> {
+		return (await this.request(method, path, body, await this.auth())) as T;
+	}
+
+	/** A GET whose body is bytes (the tarball). Follows GitHub's redirect to codeload. */
+	async bytes(path: string): Promise<Buffer> {
+		const res = await this.fetcher(`${API}${path}`, { headers: this.headers(await this.auth()), redirect: 'follow', signal: this.signal() });
+		this.tracker.record({ endpoint: `GET ${shorten(path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, ''))}`, status: res.status, creating: false });
+		if (!res.ok) throw new HttpError(res.status, `GET ${path} -> ${res.status}`, await res.text().catch(() => ''));
+		return Buffer.from(await res.arrayBuffer());
+	}
+
+	/** Aborts the request (and the reading of its body) after `timeoutMs`. */
+	private signal(): AbortSignal {
+		return AbortSignal.timeout(this.timeoutMs);
+	}
+
+	private headers(bearer: string, json = false): Record<string, string> {
+		return {
+			authorization: `Bearer ${bearer}`,
+			accept: 'application/vnd.github+json',
+			'x-github-api-version': '2022-11-28',
+			'user-agent': 'caracms',
+			...(json ? { 'content-type': 'application/json' } : {}),
+		};
+	}
+
+	private async request(method: string, path: string, body: unknown, bearer: string, notCreating = false): Promise<unknown> {
+		const res = await this.fetcher(`${API}${path}`, {
+			method,
+			headers: this.headers(bearer, body !== undefined),
+			body: body !== undefined ? JSON.stringify(body) : undefined,
+			signal: this.signal(),
+		});
+		const endpointPath = path.replace(/^\/repos\/[^/]+\/[^/]+/, '').replace(/\?.*$/, '');
+		this.tracker.record({ endpoint: `${method} ${shorten(endpointPath)}`, status: res.status, creating: !notCreating && isContentCreating(method, path, false) });
+		const text = await res.text();
+		let json: unknown = null;
+		try {
+			json = text ? JSON.parse(text) : null;
+		} catch {
+			json = text;
+		}
+		if (!res.ok) {
+			const message = (json as { message?: string } | null)?.message ?? text.slice(0, 200);
+			throw new HttpError(res.status, `${method} ${endpointPath} -> ${res.status}: ${message}`, json);
+		}
+		return json;
+	}
+
+	/** GraphQL as the installation. Throws GraphQLError when the answer has `errors`. */
+	async graphql<T = unknown>(query: string, variables: Record<string, unknown>, name: string): Promise<T> {
+		const isMutation = /^\s*mutation\b/.test(query);
+		const res = await this.fetcher(`${API}/graphql`, {
+			method: 'POST',
+			// updateRefs worked with this preview header in M1 (G2); whether it still needs it is untested (G6 (f)).
+			headers: { ...this.headers(await this.auth(), true), accept: 'application/vnd.github.update-refs-preview+json, application/json' },
+			body: JSON.stringify({ query, variables }),
+			signal: this.signal(),
+		});
+		this.tracker.record({ endpoint: `graphql ${name}`, status: res.status, creating: isMutation });
+		const json = (await res.json().catch((error: unknown) => {
+			if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) throw error; // timed out mid-body
+			return {};
+		})) as { data?: T; errors?: { type?: string; message?: string }[] };
+		if (!res.ok && !json.errors) throw new HttpError(res.status, `graphql ${name} -> ${res.status}`, json);
+		if (json.errors?.length) throw new GraphQLError(json.errors);
+		return json.data as T;
+	}
+}

package/src/live/locals.ts

@@ -0,0 +1,24 @@
+/**
+ * The signed-in person, handed from the sign-in guard to the editor's routes
+ * (M4 Phases 2 and 3). The guard (Phase 3's middleware) checks the session on every
+ * `/admin` and `/_caracms/` request in live mode and, when it passes, records the
+ * person here; a route reads it back. In local mode nothing is recorded: there's no
+ * sign-in (Decision 1).
+ *
+ * It rides on Astro's `context.locals`, under one key, so the package needs no
+ * global `App.Locals` declaration in the site.
+ */
+import type { Person } from './messages.ts';
+
+const KEY = '__caracms_person';
+
+type Locals = object;
+
+export function setPerson(locals: Locals, person: Person): void {
+	(locals as Record<string, unknown>)[KEY] = person;
+}
+
+/** The person the guard let through, or null (local mode, or no guard ran). */
+export function personOf(locals: Locals): Person | null {
+	return ((locals as Record<string, unknown>)[KEY] as Person | undefined) ?? null;
+}

package/src/live/locks.ts

@@ -0,0 +1,273 @@
+/**
+ * Locks and presence (M4 Decision 9).
+ *
+ * **A lock belongs to a tab**, held for a person: `caracms:lock:<file>` →
+ * `{ tab, person, since, beat, releasing }`. Every change to it is a compare-and-swap
+ * on the text read, so two servers (a deploy) and two tabs can't both win.
+ *
+ * - **The first write takes it, atomically** (`acquire`); browsing never locks. A write
+ *   from a tab that doesn't hold it is refused (the route's 409).
+ * - **The heartbeat** rides on the status poll (`beat`), and on every write. A tab back
+ *   from hidden re-takes its own lapsed lock on its first poll, if nobody took it.
+ * - **The lapse comes only after the autosave is committed**: a lock whose heartbeat
+ *   is older than `lockLapseMs` is still held while its document has an autosave.
+ *   The sweep commits first; the lock is then free.
+ * - **Releasing** (`X-Caracms-Release: 1` on the last write, or a lone release): the lock
+ *   still accepts that tab's writes, and drops once the document has no autosave. A
+ *   short grace keeps it while no autosave has arrived yet, because a closing tab's
+ *   two keepalive requests come in no set order (a release can overtake the last write).
+ * - **Edit here** (`take`) moves your own lock to this tab at once.
+ * - **Take over** (`takeOver`) moves anyone's lock to this tab at once. The route then
+ *   commits the old holder's autosave under their name; their tab goes read-only.
+ * - **Idle** tabs stop renewing: the status route beats only for a tab someone typed,
+ *   clicked or scrolled in within `lockIdleMs`, so a forgotten tab lapses by itself.
+ *
+ * Nothing here drops a lock key on a timer: whether a lock still holds is worked out
+ * when it's read (`holds`), so no process has to be running for a lock to lapse,
+ * and Redis gets no traffic for it. The sweep deletes the keys it can.
+ *
+ * **Presence** (`caracms:presence`, a hash by tab): each poll records the person and the
+ * document their tab has open; someone is "on" a document while a tab of theirs
+ * polled with it in the last `presenceMs`.
+ */
+import type { LockState, LockView, PresenceView } from '../editor/types.ts';
+import type { Person } from './messages.ts';
+import type { RedisClient } from './redis.ts';
+import type { LiveTimings } from './timings.ts';
+
+export interface LockRecord {
+	tab: string;
+	person: Person;
+	/** ms: when it was taken. */
+	since: number;
+	/** ms: the last heartbeat (a poll or a write). */
+	beat: number;
+	/** ms: when the tab said it was closing; null while it isn't. */
+	releasing: number | null;
+	/** The document was deleted (M5a): the tab's own polls don't clear `releasing`, so the lock drops once the removal is committed. */
+	deleted?: true;
+}
+
+interface ReadLock {
+	raw: string;
+	lock: LockRecord;
+}
+
+interface PresenceRecord {
+	person: Person;
+	file: string | null;
+	at: number;
+}
+
+/** How long a releasing lock with no autosave yet waits for the tab's last write. */
+export const RELEASE_GRACE_MS = 5_000;
+
+const sameEmail = (a: Person, b: Person) => a.email.toLowerCase() === b.email.toLowerCase();
+
+export type AcquireResult = { ok: true; lock: LockRecord } | { ok: false; lock: LockRecord };
+
+export class Locks {
+	readonly redis: RedisClient;
+	readonly timings: LiveTimings;
+	readonly now: () => number;
+	readonly prefix: string;
+	/** Whether the document has an autosave not yet committed. */
+	private readonly pending: (file: string) => Promise<boolean>;
+
+	constructor(redis: RedisClient, timings: LiveTimings, now: () => number, pending: (file: string) => Promise<boolean>, prefix = 'caracms:') {
+		this.redis = redis;
+		this.timings = timings;
+		this.now = now;
+		this.pending = pending;
+		this.prefix = prefix;
+	}
+
+	key = (file: string) => `${this.prefix}lock:${file}`;
+	private presenceKey = () => `${this.prefix}presence`;
+
+	private parse(raw: string | null): ReadLock | null {
+		if (raw === null) return null;
+		try {
+			const lock = JSON.parse(raw) as LockRecord;
+			return lock && typeof lock.tab === 'string' && lock.person ? { raw, lock } : null;
+		} catch {
+			return null;
+		}
+	}
+
+	async read(file: string): Promise<ReadLock | null> {
+		return this.parse(await this.redis.get(this.key(file)));
+	}
+
+	/** Every lock key: one SCAN and one MGET. */
+	async all(): Promise<Map<string, ReadLock>> {
+		const keys = await this.redis.scan(`${this.prefix}lock:*`);
+		const out = new Map<string, ReadLock>();
+		if (keys.length === 0) return out;
+		const raws = await this.redis.mget(keys);
+		keys.forEach((k, i) => {
+			const read = this.parse(raws[i] ?? null);
+			if (read) out.set(k.slice(this.key('').length), read);
+		});
+		return out;
+	}
+
+	/** Does this lock still hold? `pending`: the document has an uncommitted autosave. */
+	holds(lock: LockRecord, pending: boolean): boolean {
+		if (pending) return true; // commit first, then release
+		const now = this.now();
+		if (lock.releasing !== null) return now - lock.releasing < Math.min(RELEASE_GRACE_MS, this.timings.lockLapseMs);
+		return now - lock.beat < this.timings.lockLapseMs;
+	}
+
+	private async live(read: ReadLock | null, file: string): Promise<boolean> {
+		return read !== null && this.holds(read.lock, await this.pending(file));
+	}
+
+	private put(file: string, expected: string | null, lock: LockRecord): Promise<boolean> {
+		return this.redis.compareAndSet(this.key(file), expected, JSON.stringify(lock), { px: this.timings.autosaveTtlMs });
+	}
+
+	private static mine(lock: LockRecord, tab: string, person: Person) {
+		return lock.tab === tab && sameEmail(lock.person, person);
+	}
+
+	/**
+	 * A write's lock (Decision 9): the tab's own lock is renewed (a releasing one stays
+	 * releasing); a free or lapsed one is taken, atomically; anyone else's refuses.
+	 */
+	async acquire(file: string, tab: string, person: Person): Promise<AcquireResult> {
+		for (let attempt = 0; attempt < 5; attempt++) {
+			const cur = await this.read(file);
+			const now = this.now();
+			if (cur && Locks.mine(cur.lock, tab, person)) {
+				// A tab that deleted the document and now writes to it again (a re-create) is back: no longer releasing.
+				const { deleted: _deleted, ...kept } = cur.lock;
+				const next: LockRecord = { ...kept, person, beat: now, ...(cur.lock.deleted ? { releasing: null } : {}) };
+				if (await this.put(file, cur.raw, next)) return { ok: true, lock: next };
+				continue;
+			}
+			if (cur && (await this.live(cur, file))) return { ok: false, lock: cur.lock };
+			const next: LockRecord = { tab, person, since: now, beat: now, releasing: null };
+			if (await this.put(file, cur?.raw ?? null, next)) return { ok: true, lock: next };
+		}
+		const cur = await this.read(file);
+		if (cur) return { ok: false, lock: cur.lock };
+		throw new Error('caracms: the lock kept changing under the write.');
+	}
+
+	/**
+	 * The status poll's heartbeat: renew the tab's own lock and clear "releasing" (the tab
+	 * is still here), except for a lock the tab's own delete released. A lapsed lock that still names this tab is re-taken (a tab back
+	 * from hidden). Nothing is taken that the tab never held.
+	 */
+	async beat(file: string, tab: string, person: Person): Promise<ReadLock | null> {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const cur = await this.read(file);
+			if (!cur || !Locks.mine(cur.lock, tab, person)) return cur;
+			// A poll in flight when the tab deleted the document must not un-release its lock (M5a).
+			const next = { ...cur.lock, beat: this.now(), releasing: cur.lock.deleted ? cur.lock.releasing : null };
+			const raw = JSON.stringify(next);
+			if (await this.redis.compareAndSet(this.key(file), cur.raw, raw, { px: this.timings.autosaveTtlMs })) return { raw, lock: next };
+		}
+		return this.read(file);
+	}
+
+	/** Edit here: move your own lock to this tab at once, or take a free one. Someone else's refuses. */
+	async take(file: string, tab: string, person: Person): Promise<AcquireResult> {
+		for (let attempt = 0; attempt < 5; attempt++) {
+			const cur = await this.read(file);
+			if (cur && !sameEmail(cur.lock.person, person) && (await this.live(cur, file))) return { ok: false, lock: cur.lock };
+			const now = this.now();
+			const next: LockRecord = { tab, person, since: cur && Locks.mine(cur.lock, tab, person) ? cur.lock.since : now, beat: now, releasing: null };
+			if (await this.put(file, cur?.raw ?? null, next)) return { ok: true, lock: next };
+		}
+		throw new Error('caracms: the lock kept changing under Edit here.');
+	}
+
+	/**
+	 * Take over: move the lock to this tab whoever holds it, at once. Returns the lock
+	 * it replaced (null if it was free or lapsed), so the route can commit their autosave.
+	 */
+	async takeOver(file: string, tab: string, person: Person): Promise<{ lock: LockRecord; from: LockRecord | null }> {
+		for (let attempt = 0; attempt < 5; attempt++) {
+			const cur = await this.read(file);
+			const now = this.now();
+			const next: LockRecord = { tab, person, since: now, beat: now, releasing: null };
+			if (await this.put(file, cur?.raw ?? null, next)) return { lock: next, from: cur && (await this.live(cur, file)) ? cur.lock : null };
+		}
+		throw new Error('caracms: the lock kept changing under Take over.');
+	}
+
+	/**
+	 * The tab is closing: mark its lock releasing. Another tab's lock is left alone.
+	 * `deleted`: the tab deleted the document, so its later polls leave the lock releasing (`beat`).
+	 */
+	async release(file: string, tab: string, person: Person, options: { deleted?: boolean } = {}): Promise<ReadLock | null> {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const cur = await this.read(file);
+			if (!cur || !Locks.mine(cur.lock, tab, person)) return cur;
+			if (cur.lock.releasing !== null && (!options.deleted || cur.lock.deleted)) return cur;
+			const next: LockRecord = { ...cur.lock, releasing: cur.lock.releasing ?? this.now(), ...(options.deleted ? { deleted: true as const } : {}) };
+			const raw = JSON.stringify(next);
+			if (await this.put(file, cur.raw, next)) return { raw, lock: next };
+		}
+		return this.read(file);
+	}
+
+	/** Delete a lock that no longer holds (the sweep, after a commit). */
+	async dropIfFree(file: string): Promise<void> {
+		const cur = await this.read(file);
+		if (cur && !(await this.live(cur, file))) await this.redis.compareAndDelete(this.key(file), cur.raw);
+	}
+
+	view(file: string, lock: LockRecord, tab: string | null, person: Person): LockView {
+		return {
+			file,
+			person: lock.person,
+			since: new Date(lock.since).toISOString(),
+			releasing: lock.releasing !== null,
+			mine: !sameEmail(lock.person, person) ? null : lock.tab === tab ? 'this-tab' : 'other-tab',
+		};
+	}
+
+	static state(view: LockView | null): LockState {
+		if (!view) return 'free';
+		return view.mine === 'this-tab' ? 'yours' : view.mine === 'other-tab' ? 'yours-elsewhere' : 'theirs';
+	}
+
+	// ── Presence ────────────────────────────────────────────────────────────────
+
+	/** Record a poll: this tab, this person, this document (or none). */
+	async present(tab: string, person: Person, file: string | null): Promise<void> {
+		const record: PresenceRecord = { person, file, at: this.now() };
+		await this.redis.hset(this.presenceKey(), { [tab]: JSON.stringify(record) });
+	}
+
+	/** Who is on which document now (polled with it in the last `presenceMs`). Long-gone tabs are pruned. */
+	async presence(): Promise<PresenceView[]> {
+		const all = await this.redis.hgetall(this.presenceKey());
+		const now = this.now();
+		const byFile = new Map<string, Person[]>();
+		const gone: string[] = [];
+		for (const [tab, raw] of Object.entries(all)) {
+			let r: PresenceRecord;
+			try {
+				r = JSON.parse(raw) as PresenceRecord;
+			} catch {
+				gone.push(tab);
+				continue;
+			}
+			if (now - r.at > this.timings.presenceMs) {
+				if (now - r.at > this.timings.lockLapseMs) gone.push(tab);
+				continue;
+			}
+			if (!r.file) continue;
+			const people = byFile.get(r.file) ?? [];
+			if (!people.some((p) => sameEmail(p, r.person))) people.push(r.person);
+			byFile.set(r.file, people);
+		}
+		if (gone.length) await this.redis.hdel(this.presenceKey(), ...gone);
+		return [...byFile].map(([file, people]) => ({ file, people }));
+	}
+}