pi-roundtable-web 0.25.0 → 0.26.1

package/src/console-server.ts

@@ -6,10 +6,20 @@ import type {
 	Authenticator,
 	Unauthenticated,
 } from "./auth/authenticator.ts";
+import { allowedNext, nextOfPath } from "./auth/next.ts";
+import { type Decision, decide } from "./authz.ts";
 import type { ConsoleApi } from "./console-api.ts";
-import type { ConsolePresentation } from "./features.ts";
-import { presentPage } from "./page-presentation.ts";
-import { servePwa } from "./pwa.ts";
+import { type ConsolePresentation, message } from "./features.ts";
+import type { Gate } from "./gate.ts";
+import { json } from "./http.ts";
+import {
+	defaultDescription,
+	type PageMeta,
+	presentPage,
+} from "./page-presentation.ts";
+import { hasMarkSvg, isPublicStatic, servePwa } from "./pwa.ts";
+import type { Visitor } from "./visitors.ts";
+import { viewerOf } from "./web-app.ts";
 
 const encoder = new TextEncoder();
 /** Changes closer together than this reach the page as one event. */
@@ -53,6 +63,10 @@ export interface ConsoleServerOptions {
 		): Promise<Response | undefined>;
 		websocket: WebSocketRoute<AppSocket>;
 	};
+	/** The onboarding gate; without it nobody is gated. */
+	gate?: Pick<Gate, "required">;
+	/** The app's surface, for the `next` a turned-away page navigation asks to come back to. */
+	surface?: string;
 	/** Registers the listener with every source whose change the console shows. */
 	subscribe(listener: () => void): void;
 	logger: Logger;
@@ -66,17 +80,24 @@ export interface ConsoleServerOptions {
 	/** Where the install icons come from; default the ones this package ships. */
 	iconsDir?: string;
 	look?: "modern" | "camelot";
+	/** The console's own origin, for the absolute `og:image` of a link preview. */
+	origin?: string;
+	/** What the page says about itself in a search result and a link preview; default derived from the title. */
+	description?: string;
 }
 
 /**
  * The console on the host's listener: `<mount>` redirects to `<mount>/`, and everything under
- * it needs the authenticator to admit the request as an owner's, apart from what it answers
- * openly, such as a login page. A request that changes data must also carry the console's own
- * `Origin`.
+ * it needs the authenticator to admit the request, apart from what it answers openly, such as a
+ * login page. An admitted request is then judged by the authorization table before any handler
+ * sees it: a route that is not listed answers 404, one for owners answers a member 403, and while
+ * the person owes a required step only the routes open to them answer. A request that changes
+ * data must also carry the console's own `Origin`.
  */
 export class ConsoleServer {
 	readonly #options: ConsoleServerOptions;
 	readonly #base: string;
+	readonly #meta: PageMeta | undefined;
 	readonly #streams = new Set<ReadableStreamDefaultController<Uint8Array>>();
 	#pending: ReturnType<typeof setTimeout> | undefined;
 	#ping: ReturnType<typeof setInterval> | undefined;
@@ -84,6 +105,16 @@ export class ConsoleServer {
 	constructor(options: ConsoleServerOptions) {
 		this.#options = options;
 		this.#base = `${options.mount}/`;
+		const title = options.title ?? "Roundtable";
+		this.#meta = options.origin
+			? {
+					title,
+					description: options.description ?? defaultDescription(title),
+					origin: options.origin,
+					mount: options.mount,
+					svg: hasMarkSvg(options.iconsDir),
+				}
+			: undefined;
 		options.subscribe(() => this.#changed());
 	}
 
@@ -145,6 +176,11 @@ export class ConsoleServer {
 		if (path !== this.#options.mount && !path.startsWith(this.#base))
 			return new Response("Not found", { status: 404 });
 		const rest = path.slice(this.#base.length);
+		// Static and the same for everyone: a sign-in page and a link preview show the icon without a session.
+		if (READ_METHODS.has(request.method) && isPublicStatic(rest)) {
+			const shown = servePwa(rest, this.#pwa());
+			if (shown) return shown;
+		}
 		const open = await this.#options.authenticator.open?.(request, rest);
 		if (open) return open;
 		const admission = await this.#options.authenticator.authenticate(request);
@@ -154,6 +190,11 @@ export class ConsoleServer {
 				status: 302,
 				headers: { location: this.#base },
 			});
+		const decision = decide(request.method, rest, {
+			tier: admission.visitor.tier,
+			gated: await this.#gated(admission.visitor),
+		});
+		if (!decision.allow) return this.#denied(decision);
 		if (rest === "api/events" && request.method === "GET")
 			return this.#events();
 		const owned = await this.#options.app?.handle(request, rest, admission);
@@ -166,10 +207,7 @@ export class ConsoleServer {
 			);
 		if (!READ_METHODS.has(request.method))
 			return new Response("Method not allowed", { status: 405 });
-		const installable = servePwa(rest, {
-			...this.#options,
-			title: this.#options.title ?? "Roundtable",
-		});
+		const installable = servePwa(rest, this.#pwa());
 		if (installable) return installable;
 		const asset = this.#options.assets.get(rest);
 		if (asset && rest !== "index.html" && rest !== "sw.js")
@@ -188,6 +226,7 @@ export class ConsoleServer {
 						this.#options.pathRouting ? this.#options.mount : undefined,
 						this.#options.presentation,
 						this.#options.look,
+						this.#meta,
 					),
 					{
 						headers: {
@@ -206,6 +245,47 @@ export class ConsoleServer {
 		return new Response("Not found", { status: 404 });
 	}
 
+	#pwa(): Parameters<typeof servePwa>[1] {
+		return { ...this.#options, title: this.#options.title ?? "Roundtable" };
+	}
+
+	async #gated(visitor: Visitor): Promise<boolean> {
+		const { gate } = this.#options;
+		if (!gate) return false;
+		try {
+			return (await gate.required(viewerOf(visitor))).length > 0;
+		} catch (error) {
+			// A gate that cannot be read stays shut.
+			this.#options.logger.warn({ err: error }, "the gate was not read");
+			return true;
+		}
+	}
+
+	/** The answer to a request the authorization table refused. */
+	#denied(decision: Extract<Decision, { allow: false }>): Response {
+		const { presentation, logger } = this.#options;
+		logger.debug({ reason: decision.reason }, "console request denied");
+		if (decision.gate)
+			return json(
+				{
+					error: message(presentation, "Finish setting up first."),
+					gate: true,
+				},
+				403,
+			);
+		return json(
+			{
+				error: message(
+					presentation,
+					decision.status === 404
+						? "There is no such API."
+						: "Only an owner may do this.",
+				),
+			},
+			decision.status,
+		);
+	}
+
 	/**
 	 * The answer to a request the authenticator refused: a page navigation that signing in would
 	 * fix goes to the login page, everything else gets the status and a fixed body.
@@ -215,14 +295,24 @@ export class ConsoleServer {
 			refusal.login &&
 			READ_METHODS.has(request.method) &&
 			!rest.startsWith("api/")
-		)
+		) {
+			// A link can name where to come back to (`?next=`), and so can a path route; a hash route's place never reaches the server.
+			const surface = this.#options.surface ?? "app";
+			const named = allowedNext(
+				URL.parse(request.url)?.searchParams.get("next"),
+				surface,
+			);
+			const next =
+				named ??
+				(this.#options.pathRouting ? nextOfPath(rest, surface) : undefined);
 			return new Response(null, {
 				status: 303,
 				headers: {
-					location: `${this.#options.mount}/login`,
+					location: `${this.#options.mount}/login${next ? `?next=${encodeURIComponent(next)}` : ""}`,
 					"cache-control": "no-store",
 				},
 			});
+		}
 		// A missing session is the normal way to meet a login page, not worth a line each time.
 		const { logger } = this.#options;
 		const fields = { refusal: refusal.refusal };

package/src/gate.ts

@@ -0,0 +1,90 @@
+import type { GateStepView } from "./api-types.ts";
+import type { Viewer, WebAppRegistry } from "./web-app.ts";
+
+/** How long a person's owed steps are remembered, so a page of requests asks each step once. */
+const MEMO_MS = 5_000;
+
+export interface GateOptions {
+	registry: Pick<WebAppRegistry, "steps" | "waived">;
+	/** The clock, in milliseconds; default `Date.now`. */
+	now?: () => number;
+}
+
+interface Memo {
+	at: number;
+	steps: GateStepView[];
+}
+
+/**
+ * The onboarding gate. A person owes a step when it applies to them and is neither done nor
+ * waived. While they owe a required step, only the routes marked G and the few frames a gated
+ * socket may have answer them; the rest answer 403 with `gate: true`. A step that cannot be read
+ * counts as undone, so a failing lookup keeps the gate shut rather than opening it.
+ */
+export class Gate {
+	readonly #options: GateOptions;
+	readonly #memo = new Map<string, Memo>();
+	readonly #listeners = new Set<(principalId: string) => void>();
+
+	constructor(options: GateOptions) {
+		this.#options = options;
+	}
+
+	#now(): number {
+		return (this.#options.now ?? Date.now)();
+	}
+
+	/** The steps this viewer still owes, required or not, in the order they were registered. */
+	async owed(viewer: Viewer): Promise<GateStepView[]> {
+		const found = this.#memo.get(viewer.principalId);
+		if (found && this.#now() - found.at < MEMO_MS) return found.steps;
+		const steps: GateStepView[] = [];
+		for (const step of this.#options.registry.steps()) {
+			try {
+				if (step.applies && !(await step.applies(viewer))) continue;
+				if (await step.done(viewer)) continue;
+				const waived = step.required
+					? await this.#options.registry.waived(viewer.principalId, step.id)
+					: false;
+				if (waived) continue;
+				steps.push({
+					id: step.id,
+					label: step.label,
+					...(step.help ? { help: step.help } : {}),
+					...(step.builtin ? { builtin: step.builtin } : {}),
+					required: step.required,
+					open: step.open,
+					...(step.required && step.waiver ? { waiver: step.waiver } : {}),
+				});
+			} catch {
+				// A step that cannot be read is undone; a required one keeps the gate shut.
+				steps.push({
+					id: step.id,
+					label: step.label,
+					...(step.builtin ? { builtin: step.builtin } : {}),
+					required: step.required,
+					open: step.open,
+				});
+			}
+		}
+		this.#memo.set(viewer.principalId, { at: this.#now(), steps });
+		return steps;
+	}
+
+	/** Whether a required step stands undone; the steps it names are those. */
+	async required(viewer: Viewer): Promise<GateStepView[]> {
+		return (await this.owed(viewer)).filter((step) => step.required);
+	}
+
+	/** A person's steps may differ now (they linked an account, waived a step): ask again. */
+	changed(principalId: string): void {
+		this.#memo.delete(principalId);
+		for (const listener of this.#listeners) listener(principalId);
+	}
+
+	/** Hears of a change to a person's steps, so their open sockets can be told. */
+	onChanged(listener: (principalId: string) => void): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+}

package/src/host/access.ts

@@ -0,0 +1,161 @@
+import type { ChannelKey, Logger } from "pi-roundtable";
+import { viewerOfSocket } from "../app/socket.ts";
+import type { AppSocket, Sockets } from "../app/sockets.ts";
+import type {
+	HostRoomAccess,
+	RoomAccess,
+	Viewer,
+	WebAppRegistry,
+} from "../web-app.ts";
+
+/** How long an answer of a kind's `access` is trusted: 10 seconds. */
+export const ACCESS_TTL_MS = 10_000;
+
+interface Entry {
+	at: number;
+	/** What the kind said then; undefined = no access. */
+	access: RoomAccess | undefined;
+}
+
+export interface HostAccessOptions {
+	registry: Pick<WebAppRegistry, "hostKindOf">;
+	sockets: Pick<Sockets, "each">;
+	logger: Logger;
+	/** The clock, in milliseconds; default `Date.now`. */
+	now?: () => number;
+	/** How long an answer is trusted; default 10 s. */
+	ttlMs?: number;
+	/** Hears that a person's reading of a room was cut off, so their page can be told. */
+	revoked?(connection: AppSocket, room: string): void;
+}
+
+/**
+ * What decides who reads a host room right now: the kind's `access`, asked again at least every
+ * ten seconds for as long as anyone follows the room, and at once when the host says access
+ * changed. A frame is delivered only to a socket whose person the memo says may read, so a revoked
+ * reader stops receiving within the TTL even if the host never says so, and an error of the
+ * kind's is a refusal, never a pass.
+ */
+export class HostAccess implements HostRoomAccess {
+	readonly #options: HostAccessOptions;
+	readonly #memo = new Map<string, Entry>();
+	readonly #inflight = new Map<string, Promise<RoomAccess | undefined>>();
+	readonly #ttl: number;
+	#timer: ReturnType<typeof setInterval> | undefined;
+
+	constructor(options: HostAccessOptions) {
+		this.#options = options;
+		this.#ttl = options.ttlMs ?? ACCESS_TTL_MS;
+	}
+
+	#now(): number {
+		return (this.#options.now ?? Date.now)();
+	}
+
+	static #key(principalId: string, room: string): string {
+		return `${principalId}\u0000${room}`;
+	}
+
+	/** Re-asks about the rooms that are followed, a few times per TTL. */
+	start(): void {
+		if (this.#timer) return;
+		this.#timer = setInterval(
+			() => this.#refresh(this.#ttl / 2),
+			Math.max(50, this.#ttl / 4),
+		);
+		this.#timer.unref?.();
+	}
+
+	stop(): void {
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+		this.#memo.clear();
+	}
+
+	/** What the kind grants the viewer in the room now, from the memo when it is fresh; undefined for no access. */
+	async of(viewer: Viewer, room: string): Promise<RoomAccess | undefined> {
+		const key = HostAccess.#key(viewer.principalId, room);
+		const found = this.#memo.get(key);
+		if (found && this.#now() - found.at <= this.#ttl) return found.access;
+		return this.#ask(viewer, room);
+	}
+
+	async read(viewer: Viewer, room: ChannelKey): Promise<boolean> {
+		return (await this.of(viewer, room)) !== undefined;
+	}
+
+	/** Whether the memo, still fresh, says this socket's person may read the room. */
+	readNow(connection: AppSocket, room: string): boolean {
+		const found = this.#memo.get(
+			HostAccess.#key(connection.principal.id, room),
+		);
+		return (
+			found !== undefined &&
+			found.access !== undefined &&
+			this.#now() - found.at <= this.#ttl
+		);
+	}
+
+	#ask(viewer: Viewer, room: string): Promise<RoomAccess | undefined> {
+		const key = HostAccess.#key(viewer.principalId, room);
+		const running = this.#inflight.get(key);
+		if (running) return running;
+		const found = this.#options.registry.hostKindOf(room);
+		const answer = (async () => {
+			let access: RoomAccess | undefined;
+			if (found) {
+				try {
+					access = await found.kind.access(viewer, found.id);
+				} catch (error) {
+					this.#options.logger.warn(
+						{ kind: found.kind.kind, err: error },
+						"a kind of room could not say who may read; the room stays closed",
+					);
+				}
+			}
+			this.#memo.set(key, { at: this.#now(), access });
+			return access;
+		})().finally(() => this.#inflight.delete(key));
+		this.#inflight.set(key, answer);
+		return answer;
+	}
+
+	/** Re-asks for every followed room whose answer is older than `olderThan`. */
+	#refresh(olderThan: number): Promise<unknown> {
+		const asks: Promise<unknown>[] = [];
+		this.#options.sockets.each(
+			(connection) => connection.subscriptions.size > 0,
+			(connection) => {
+				const viewer = viewerOfSocket(connection);
+				for (const room of [...connection.subscriptions]) {
+					const found = this.#memo.get(
+						HostAccess.#key(viewer.principalId, room),
+					);
+					if (found && this.#now() - found.at < olderThan) continue;
+					asks.push(
+						this.#ask(viewer, room).then((access) => {
+							if (access) return;
+							// The person lost the room: stop following it and tell their page.
+							connection.subscriptions.delete(room);
+							if (connection.focus === room) connection.focus = undefined;
+							this.#options.revoked?.(connection, room);
+						}),
+					);
+				}
+			},
+		);
+		return Promise.allSettled(asks);
+	}
+
+	/** Drops what is remembered of a room, of everyone's or one person's, and asks the followers again at once. */
+	forget(where: { room?: string; principalId?: string }): Promise<unknown> {
+		for (const key of [...this.#memo.keys()]) {
+			const [principalId, room] = key.split("\u0000");
+			if (where.room !== undefined && room !== where.room) continue;
+			if (where.principalId !== undefined && principalId !== where.principalId)
+				continue;
+			this.#memo.delete(key);
+		}
+		return this.#refresh(0);
+	}
+}

package/src/host/cards.ts

@@ -0,0 +1,112 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+import type { HostCard, StoredHostCard } from "../web-app.ts";
+import { storedJson } from "./stored-json.ts";
+
+interface Row {
+	id: string;
+	room: string;
+	card: HostCard | string;
+	created_at: Date;
+	updated_at: Date;
+}
+
+function cardOf(row: Row): StoredHostCard {
+	return {
+		...storedJson(row.card, "host card"),
+		id: row.id,
+		room: row.room as StoredHostCard["room"],
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	};
+}
+
+/**
+ * The cards hosts put in their rooms, kept in `web_host_cards`: a title and body, a state, links
+ * and buttons, which the host updates in place as the thing the card stands for moves on. Held-call
+ * approvals and questions are not here; they are the desk's cards.
+ */
+export class HostCardLog {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-host-cards",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_host_cards (
+					id text PRIMARY KEY,
+					room text NOT NULL,
+					card jsonb NOT NULL,
+					state text,
+					created_at timestamptz NOT NULL DEFAULT now(),
+					updated_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_host_cards_room_created ON web_host_cards (room, created_at)`;
+		},
+	};
+
+	/** The mark of a card the host keeps past its kind's retention (`HostCard.keep`). */
+	static readonly keepMigration: Migration = {
+		name: "web-host-cards-keep",
+		up: async (sql) => {
+			await sql`
+				ALTER TABLE web_host_cards ADD COLUMN IF NOT EXISTS keep boolean NOT NULL DEFAULT false`;
+		},
+	};
+
+	async create(room: string, card: HostCard): Promise<StoredHostCard> {
+		const id = crypto.randomUUID();
+		const [row]: Row[] = await this.#sql`
+			INSERT INTO web_host_cards (id, room, card, state, keep)
+			VALUES (${id}, ${room}, ${JSON.stringify(card)}::jsonb, ${card.state ?? null}, ${card.keep === true})
+			RETURNING *`;
+		if (!row) throw new Error("the card log stored nothing");
+		return cardOf(row);
+	}
+
+	/** Replaces a card of the room; undefined when the room holds no such card. */
+	async update(
+		room: string,
+		id: string,
+		card: HostCard,
+	): Promise<StoredHostCard | undefined> {
+		const [row]: Row[] = await this.#sql`
+			UPDATE web_host_cards
+			SET card = ${JSON.stringify(card)}::jsonb, state = ${card.state ?? null}, keep = ${card.keep === true}, updated_at = now()
+			WHERE id = ${id} AND room = ${room} RETURNING *`;
+		return row && cardOf(row);
+	}
+
+	async get(room: string, id: string): Promise<StoredHostCard | undefined> {
+		const [row]: Row[] = await this.#sql`
+			SELECT * FROM web_host_cards WHERE id = ${id} AND room = ${room}`;
+		return row && cardOf(row);
+	}
+
+	/** The room's cards, oldest first. */
+	async list(room: string): Promise<StoredHostCard[]> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM web_host_cards WHERE room = ${room} ORDER BY created_at, id`;
+		return rows.map(cardOf);
+	}
+
+	/**
+	 * Deletes the cards of the rooms whose key starts with `prefix` that are older than `before`,
+	 * except those the host marked `keep`; how many.
+	 */
+	async sweepKind(prefix: string, before: Date): Promise<number> {
+		const rows: unknown[] = await this.#sql`
+			DELETE FROM web_host_cards
+			WHERE starts_with(room, ${prefix}) AND created_at < ${before}
+			AND NOT keep RETURNING 1`;
+		return rows.length;
+	}
+
+	async removeRoom(room: string): Promise<void> {
+		await this.#sql`DELETE FROM web_host_cards WHERE room = ${room}`;
+	}
+}