pi-roundtable-web 0.24.2 → 0.26.0

package/src/console-server.ts

@@ -6,10 +6,16 @@ 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 { type ConsolePresentation, message } from "./features.ts";
+import type { Gate } from "./gate.ts";
+import { json } from "./http.ts";
 import { presentPage } from "./page-presentation.ts";
 import { 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 +59,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;
@@ -70,9 +80,11 @@ export interface ConsoleServerOptions {
 
 /**
  * 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;
@@ -154,6 +166,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);
@@ -206,6 +223,43 @@ export class ConsoleServer {
 		return new Response("Not found", { status: 404 });
 	}
 
+	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 +269,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,99 @@
+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)`;
+		},
+	};
+
+	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)
+			VALUES (${id}, ${room}, ${JSON.stringify(card)}::jsonb, ${card.state ?? null})
+			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}, 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`; 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} RETURNING 1`;
+		return rows.length;
+	}
+
+	async removeRoom(room: string): Promise<void> {
+		await this.#sql`DELETE FROM web_host_cards WHERE room = ${room}`;
+	}
+}

package/src/host/context.ts

@@ -0,0 +1,141 @@
+import type { InboundMessage } from "pi-roundtable";
+import type {
+	ChannelContext,
+	ChannelContextMessage,
+	ChannelContextOptions,
+} from "pi-roundtable/discord";
+import { formatChannelContext } from "pi-roundtable/discord";
+import type { HostAuthorKind, RoomMessage } from "../api-types.ts";
+import { PAGE_LIMIT } from "../app/room-log.ts";
+import type { HostContext } from "./host-context.ts";
+
+const DEFAULT_FETCH = 50;
+const DEFAULT_KEEP = 15;
+const DEFAULT_CHARS = 500;
+/** How many delivered message ids are remembered per room, and how many rooms. */
+const SEEN_PER_ROOM = 500;
+const SEEN_ROOMS = 1_000;
+
+type Source = Parameters<NonNullable<ChannelContextOptions["authors"]>>[0];
+
+const positive = (name: string, value: number, most: number): number => {
+	if (!Number.isInteger(value) || value < 1 || value > most)
+		throw new RangeError(
+			`channel context option ${name} must be a whole number from 1 to ${most}, got ${value}`,
+		);
+	return value;
+};
+
+/** Whose a stored message of a host room is; a message without a kind is read from its row's. */
+function authorKindOf(message: RoomMessage): HostAuthorKind {
+	if (message.authorKind) return message.authorKind;
+	if (message.kind === "agent") return "assistant";
+	return message.kind === "system" ? "notice" : "member";
+}
+
+/** What the channel context reads of one stored message of a host room. */
+function sourceOf(message: RoomMessage): Source {
+	const kind = authorKindOf(message);
+	return {
+		id: String(message.id),
+		authorId: message.principalId ?? kind,
+		authorName: message.author,
+		bot: false,
+		own: kind === "assistant",
+		...(kind === "external" ? { external: true as const } : {}),
+		attachments: message.files.map((file) => ({
+			name: file.name,
+			contentType: file.type,
+			size: file.size,
+			url: `api/files/${file.id}`,
+		})),
+		at: Date.parse(message.at),
+		text: message.text,
+	};
+}
+
+/**
+ * The app surface's `channelContext` for a host room: what was said in it since the assistant
+ * last posted, before the message that addressed it, as the core's block of channel messages. An
+ * outsider's words read as `external`, a notice line is not in the channel as far as the context
+ * goes, and a message already handed to the conversation is not handed again. Anything but a host
+ * room has none: an agent room is one person's.
+ */
+export function hostChannelContext(
+	ctx: Pick<HostContext, "registry" | "log">,
+): (
+	message: InboundMessage,
+	options?: ChannelContextOptions,
+) => Promise<ChannelContext | undefined> {
+	const seen = new Map<string, Set<string>>();
+	return async (message, options = {}) => {
+		const room = message.channel;
+		if (!ctx.registry.isHostRoom(room)) return undefined;
+		const fetch = positive("fetch", options.fetch ?? DEFAULT_FETCH, PAGE_LIMIT);
+		const keep = positive("keep", options.keep ?? DEFAULT_KEEP, 100);
+		const chars = positive(
+			"messageChars",
+			options.messageChars ?? DEFAULT_CHARS,
+			20_000,
+		);
+		const addressed = /^app-(\d+)$/.exec(message.messageId)?.[1];
+		const page = await ctx.log.page(
+			room,
+			addressed === undefined ? undefined : Number(addressed),
+			fetch,
+		);
+		const sources = page.messages.map((one) => ({
+			source: sourceOf(one),
+			notice: authorKindOf(one) === "notice",
+		}));
+		type Entry = (typeof sources)[number];
+		const verdict = (entry: Entry) => {
+			const given = options.authors?.(entry.source);
+			if (given === "keep" || given === "skip" || given === "end") return given;
+			if (entry.notice) return "skip";
+			return entry.source.own ? "end" : "keep";
+		};
+		const considered = sources.filter((entry) => verdict(entry) !== "skip");
+		const lastEnd = considered.findLastIndex(
+			(entry) => verdict(entry) === "end",
+		);
+		const known = seen.get(room) ?? new Set<string>();
+		const fresh = considered
+			.slice(lastEnd + 1)
+			.filter(
+				(entry) =>
+					verdict(entry) === "keep" &&
+					!known.has(entry.source.id) &&
+					entry.source.text !== "",
+			)
+			.slice(-keep);
+		// What was in the window is not handed over again, kept or not.
+		for (const entry of considered.slice(lastEnd + 1))
+			known.add(entry.source.id);
+		seen.delete(room);
+		seen.set(room, new Set([...known].slice(-SEEN_PER_ROOM)));
+		if (seen.size > SEEN_ROOMS) {
+			const oldest = seen.keys().next().value;
+			if (oldest !== undefined) seen.delete(oldest);
+		}
+		if (fresh.length === 0) return undefined;
+		const messages: ChannelContextMessage[] = fresh.map(({ source }) => ({
+			id: source.id,
+			authorId: source.authorId,
+			authorName: source.authorName,
+			bot: false,
+			owner: false,
+			...(source.external ? { external: true } : {}),
+			text:
+				source.text.length > chars
+					? `${source.text.slice(0, chars)}…`
+					: source.text,
+			at: new Date(source.at),
+			attachments: (source.attachments ?? []).map((file) => ({
+				...file,
+				messageId: source.id,
+			})),
+		}));
+		return { messages, text: formatChannelContext(messages) };
+	};
+}