pi-roundtable-web 0.24.2 → 0.26.0

package/src/host/forms.ts

@@ -0,0 +1,237 @@
+import { PluginError } from "pi-roundtable";
+import type {
+	FormField,
+	FormSpec,
+	FormValues,
+	HostAction,
+} from "../web-app.ts";
+
+/** The limits of what a host puts on a card, a header or a form. */
+const LIMITS = {
+	title: 200,
+	label: 120,
+	body: 20_000,
+	links: 10,
+	buttons: 10,
+	fields: 20,
+	options: 1_000,
+	textMax: 500,
+	textareaMax: 8_000,
+} as const;
+
+const ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+const FIELD_NAME = /^[A-Za-z0-9_]{1,40}$/;
+const TONES = new Set(["note", "ok", "warn", "risk"]);
+const STATES = new Set(["open", "working", "done", "superseded", "expired"]);
+
+const fail = (what: string): never => {
+	throw new PluginError(`web app: ${what}`);
+};
+
+/** Whether a link may be put on a card: `https`, or a path of this origin. */
+export function safeLink(url: string): boolean {
+	// Browsers strip tabs and newlines, so "/\t/host" reads as "//host": no control or space.
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: the check is for them
+	if (/[\u0000-\u0020\u007f]/.test(url)) return false;
+	if (url.startsWith("/")) return !url.startsWith("//") && !url.includes("\\");
+	return URL.parse(url)?.protocol === "https:";
+}
+
+function checkField(field: FormField, where: string): void {
+	if (!FIELD_NAME.test(field.name))
+		fail(
+			`${where}: field name ${JSON.stringify(field.name)} must match [A-Za-z0-9_]{1,40}`,
+		);
+	if (typeof field.label !== "string" || field.label.length > LIMITS.label)
+		fail(
+			`${where}: field ${field.name} needs a label of at most ${LIMITS.label} characters`,
+		);
+	if (field.type === "select" || field.type === "multiselect") {
+		const { options } = field;
+		if (!Array.isArray(options) || options.length > LIMITS.options)
+			fail(
+				`${where}: field ${field.name} takes at most ${LIMITS.options} options`,
+			);
+		const values = new Set(options.map((option) => option.value));
+		if (values.size !== options.length)
+			fail(`${where}: field ${field.name} lists a value twice`);
+		if (field.search !== undefined && typeof field.search !== "boolean")
+			fail(`${where}: field ${field.name}'s search is true or false`);
+		const initial =
+			field.initial === undefined
+				? []
+				: typeof field.initial === "string"
+					? [field.initial]
+					: field.initial;
+		if (field.type === "select" && initial.length > 1)
+			fail(`${where}: select ${field.name} takes one initial value`);
+		for (const value of initial)
+			if (!values.has(value))
+				fail(
+					`${where}: field ${field.name}'s initial value ${JSON.stringify(value)} is not an option`,
+				);
+	} else if (!["text", "textarea", "url"].includes(field.type))
+		fail(
+			`${where}: field ${field.name} has the unknown type ${String(field.type)}`,
+		);
+}
+
+function checkSpec(form: FormSpec, where: string): void {
+	if (typeof form.title !== "string" || typeof form.submit !== "string")
+		fail(`${where}: a form needs a title and a submit label`);
+	if (!Array.isArray(form.fields) || form.fields.length > LIMITS.fields)
+		fail(`${where}: a form takes at most ${LIMITS.fields} fields`);
+	const names = new Set<string>();
+	for (const field of form.fields) {
+		checkField(field, where);
+		if (names.has(field.name))
+			fail(`${where}: field ${field.name} is listed twice`);
+		names.add(field.name);
+	}
+}
+
+/** Throws a `PluginError` naming what is wrong with a list of actions a host offers; returns them. */
+export function checkActions(
+	actions: readonly HostAction[],
+	where: string,
+): readonly HostAction[] {
+	if (actions.length > LIMITS.buttons)
+		fail(`${where}: at most ${LIMITS.buttons} buttons`);
+	const ids = new Set<string>();
+	for (const action of actions) {
+		if (!ID.test(action.id))
+			fail(
+				`${where}: button id ${JSON.stringify(action.id)} must match [A-Za-z0-9_.:-]{1,64}`,
+			);
+		if (ids.has(action.id))
+			fail(`${where}: button ${action.id} is listed twice`);
+		ids.add(action.id);
+		if (typeof action.label !== "string" || action.label.length > LIMITS.label)
+			fail(
+				`${where}: button ${action.id} needs a label of at most ${LIMITS.label} characters`,
+			);
+		if (action.confirm !== undefined && action.confirm.length > LIMITS.body)
+			fail(`${where}: button ${action.id}'s confirmation is too long`);
+		if (action.form) checkSpec(action.form, `${where} button ${action.id}`);
+	}
+	return actions;
+}
+
+/** Throws a `PluginError` for a card a host may not put in a room. */
+export function checkCard(card: {
+	title: string;
+	body: string;
+	tone?: string | undefined;
+	state?: string | undefined;
+	links?: readonly { label: string; url: string }[] | undefined;
+	buttons?: readonly HostAction[] | undefined;
+}): void {
+	if (typeof card.title !== "string" || card.title.length > LIMITS.title)
+		fail(`a card's title is at most ${LIMITS.title} characters`);
+	if (typeof card.body !== "string" || card.body.length > LIMITS.body)
+		fail(`a card's body is at most ${LIMITS.body} characters`);
+	if (card.tone !== undefined && !TONES.has(card.tone))
+		fail(`a card's tone is note, ok, warn or risk`);
+	if (card.state !== undefined && !STATES.has(card.state))
+		fail(`a card's state is open, working, done, superseded or expired`);
+	const links = card.links ?? [];
+	if (links.length > LIMITS.links)
+		fail(`a card takes at most ${LIMITS.links} links`);
+	for (const link of links)
+		if (!safeLink(link.url))
+			fail(
+				`a card's link ${JSON.stringify(link.url)} must be https or a path of this origin`,
+			);
+	checkActions(card.buttons ?? [], "a card");
+}
+
+/** The buttons a card shows: only while it is open (or has no state), since a settled card has nothing left to press. */
+export const pressable = (card: { state?: string | undefined }): boolean =>
+	card.state === undefined || card.state === "open";
+
+/**
+ * What a form's input comes to: the values kept, or the first thing wrong with it and the field it
+ * is about. Every field of the form is checked; a name the form does not have is refused, so an
+ * action cannot be handed values it never offered.
+ */
+export function checkInput(
+	form: FormSpec | undefined,
+	input: FormValues,
+):
+	| { ok: true; values: FormValues }
+	| { ok: false; error: string; field?: string } {
+	if (!form) {
+		return Object.keys(input).length === 0
+			? { ok: true, values: {} }
+			: { ok: false, error: "This action takes no form." };
+	}
+	const known = new Set(form.fields.map((field) => field.name));
+	for (const name of Object.keys(input))
+		if (!known.has(name))
+			return { ok: false, error: "The form has no such field.", field: name };
+	const values: Record<string, string | readonly string[]> = {};
+	for (const field of form.fields) {
+		const given = input[field.name];
+		const empty =
+			given === undefined ||
+			(typeof given === "string" ? given.trim() === "" : given.length === 0);
+		if (empty) {
+			if (field.required)
+				return {
+					ok: false,
+					error: "This field is required.",
+					field: field.name,
+				};
+			continue;
+		}
+		if ("options" in field) {
+			const allowed = new Set(field.options.map((option) => option.value));
+			if (field.type === "multiselect") {
+				if (
+					typeof given === "string" ||
+					new Set(given).size !== given.length ||
+					!given.every((value) => allowed.has(value))
+				)
+					return {
+						ok: false,
+						error: "Choose from the list.",
+						field: field.name,
+					};
+				values[field.name] = [...given];
+			} else {
+				if (typeof given !== "string" || !allowed.has(given))
+					return {
+						ok: false,
+						error: "Choose from the list.",
+						field: field.name,
+					};
+				values[field.name] = given;
+			}
+			continue;
+		}
+		if (typeof given !== "string")
+			return {
+				ok: false,
+				error: "This field takes one value.",
+				field: field.name,
+			};
+		const max =
+			field.max ??
+			(field.type === "textarea" ? LIMITS.textareaMax : LIMITS.textMax);
+		if (given.length > max)
+			return {
+				ok: false,
+				error: "This field is too long.",
+				field: field.name,
+			};
+		if (field.type === "url") {
+			const protocol = URL.parse(given.trim())?.protocol;
+			if (protocol !== "https:" && protocol !== "http:")
+				return { ok: false, error: "Give a web address.", field: field.name };
+			values[field.name] = given.trim();
+			continue;
+		}
+		values[field.name] = given;
+	}
+	return { ok: true, values };
+}

package/src/host/frames.ts

@@ -0,0 +1,342 @@
+import type { ActorFacts, InboundMessage } from "pi-roundtable";
+import {
+	type ClientFrame,
+	MAX_MESSAGE_CHARS,
+	type RefusalCode,
+} from "../api-types.ts";
+import type { AppSocket, Audience } from "../app/sockets.ts";
+import type {
+	ActionResult,
+	FormSpec,
+	FrameContext,
+	HostAction,
+	Viewer,
+} from "../web-app.ts";
+import { checkInput } from "./forms.ts";
+import { asRoom, type HostContext } from "./host-context.ts";
+import { buttonsFor, type FoundRoom } from "./room-views.ts";
+
+/** The most host rooms one socket follows. */
+export const MAX_SUBSCRIPTIONS = 200;
+
+/** An id of a host room: what follows the dot of `<surface>:<kind>.<id>`. */
+const ROOM_ID = /^[A-Za-z0-9_-]{8,64}$/;
+
+/** The host room a key names, when its kind is registered and its id has the shape a room's has. */
+export function hostRoomOf(
+	ctx: Pick<HostContext, "registry">,
+	key: string,
+): FoundRoom | undefined {
+	const found = ctx.registry.hostKindOf(key);
+	return found && ROOM_ID.test(found.id) ? found : undefined;
+}
+
+/** Why an act did not reach the host. */
+export type ActRefusal = "unknown" | "forbidden";
+
+export type ActOutcome = { result: ActionResult } | { refused: ActRefusal };
+
+/**
+ * One press of a button or submit of a form in a host room: the viewer may read and act, the
+ * button is one this card offers them (or an action of the room's header), and the form's input is
+ * what the form asks for. Only then does the host hear of it, and the host decides what it means.
+ */
+export async function actInRoom(
+	ctx: HostContext,
+	viewer: Viewer,
+	room: string,
+	press: {
+		action: string;
+		card?: string;
+		input?: Readonly<Record<string, string | readonly string[]>>;
+	},
+): Promise<ActOutcome> {
+	const found = hostRoomOf(ctx, room);
+	if (!found) return { refused: "unknown" };
+	const access = await ctx.access.of(viewer, room);
+	if (!access) return { refused: "unknown" };
+	if (!access.act) return { refused: "forbidden" };
+	let offered: readonly HostAction[];
+	if (press.card !== undefined) {
+		const card = await ctx.cards.get(room, press.card);
+		if (!card) return { refused: "unknown" };
+		offered = buttonsFor(viewer, found, access, card);
+	} else {
+		const header = await found.kind
+			.header?.(viewer, found.id)
+			.catch((error: unknown) => {
+				ctx.logger.warn(
+					{ kind: found.kind.kind, err: error },
+					"a room's header could not be read",
+				);
+				return undefined;
+			});
+		offered = header?.actions ?? [];
+	}
+	const button = offered.find((one) => one.id === press.action);
+	if (!button) return { refused: "forbidden" };
+	if (!found.kind.act) return { refused: "unknown" };
+	const checked = checkInput(
+		button.form as FormSpec | undefined,
+		press.input ?? {},
+	);
+	if (!checked.ok)
+		return {
+			result: {
+				ok: false,
+				error: checked.error,
+				...(checked.field ? { field: checked.field } : {}),
+			},
+		};
+	let result: ActionResult;
+	try {
+		result = await found.kind.act(
+			viewer,
+			found.id,
+			{
+				action: press.action,
+				...(press.card === undefined ? {} : { card: press.card }),
+			},
+			checked.values,
+		);
+	} catch (error) {
+		ctx.logger.warn(
+			{ kind: found.kind.kind, err: error },
+			"a host action failed",
+		);
+		result = { ok: false, error: "The action could not be done." };
+	}
+	ctx.events?.action?.({
+		kind: "act",
+		actor: viewer.speakerId,
+		principalId: viewer.principalId,
+		channel: asRoom(room),
+		ok: result.ok,
+		at: new Date(ctx.now()),
+	});
+	return { result };
+}
+
+/** The audience a room's `read` frames go to: a host room's readers, or the owners for an agent room. */
+export const readAudience = (
+	ctx: Pick<HostContext, "registry">,
+	room: string,
+): Audience => (ctx.registry.isHostRoom(room) ? { room } : { owners: true });
+
+/** Registers the handlers of the frames host rooms take. */
+export function installFrames(ctx: HostContext): void {
+	const { registry } = ctx;
+
+	registry.onFrame(
+		"subscribe",
+		async ({ frame, viewer, connection, refuse }) => {
+			if (!hostRoomOf(ctx, frame.room)) return refuse("unknown_room");
+			if (
+				!connection.subscriptions.has(frame.room) &&
+				connection.subscriptions.size >= MAX_SUBSCRIPTIONS
+			)
+				return refuse("not_accepted");
+			if (!(await ctx.access.read(viewer, asRoom(frame.room))))
+				return refuse("unknown_room");
+			connection.subscriptions.add(frame.room);
+			// A card that opened before the reader came is theirs to see, once they may read the room.
+			for (const { room, frame: card } of ctx.desk.openFrames())
+				if (room === frame.room)
+					ctx.sockets.deliver(card, {
+						connection,
+						audience: { room: frame.room },
+					});
+		},
+	);
+
+	registry.onFrame("unsubscribe", async ({ frame, connection }) => {
+		connection.subscriptions.delete(frame.room);
+		if (connection.focus === frame.room) connection.focus = undefined;
+	});
+
+	registry.onFrame("act", async ({ frame, viewer, refuse }) => {
+		if (frame.page !== undefined) {
+			const outcome = await ctx.pages.act(viewer, frame.page, {
+				action: frame.action,
+				...(frame.input ? { input: frame.input } : {}),
+			});
+			if ("refused" in outcome) return refuse("forbidden", frame.id);
+			if (!outcome.result.ok) return refuse("not_accepted", frame.id);
+			return;
+		}
+		const outcome = await actInRoom(ctx, viewer, frame.room ?? "", {
+			action: frame.action,
+			...(frame.card === undefined ? {} : { card: frame.card }),
+			...(frame.input ? { input: frame.input } : {}),
+		});
+		if ("refused" in outcome)
+			return refuse(
+				outcome.refused === "unknown" ? "unknown_room" : "forbidden",
+				frame.id,
+			);
+		if (!outcome.result.ok) refuse("not_accepted", frame.id);
+	});
+
+	registry.onFrame("read", async ({ frame, viewer, connection, refuse }) => {
+		const audience = await readableAudience(ctx, viewer, frame.room);
+		if (!audience) return refuse("unknown_room");
+		const mark = await ctx.reads.advance(
+			frame.room,
+			viewer.principalId,
+			frame.upTo,
+		);
+		if (!mark) return;
+		ctx.sockets.deliver(
+			{
+				type: "read",
+				room: frame.room,
+				principal: viewer.principalId,
+				name: viewer.name,
+				upTo: mark.upTo,
+				at: mark.at,
+			},
+			audience,
+		);
+		void connection;
+	});
+
+	registry.onFrame("hostSend", async (context) => hostSend(ctx, context));
+
+	registry.onFrame("hostStop", async ({ frame, viewer, refuse }) => {
+		if (!hostRoomOf(ctx, frame.room)) return refuse("unknown_room");
+		const access = await ctx.access.of(viewer, frame.room);
+		if (!access) return refuse("unknown_room");
+		if (!access.send.includes("turn")) return refuse("forbidden");
+		ctx.conversations.stop(asRoom(frame.room));
+	});
+}
+
+/**
+ * Who a read frame of this room is shown to when the viewer may read it now: a host room's readers
+ * (asked of the kind), or, for an agent or thread room, the owners. Undefined when the viewer may not.
+ */
+export async function readableAudience(
+	ctx: HostContext,
+	viewer: Viewer,
+	room: string,
+): Promise<Audience | undefined> {
+	if (ctx.registry.isHostRoom(room)) {
+		if (!hostRoomOf(ctx, room)) return undefined;
+		return (await ctx.access.read(viewer, asRoom(room))) ? { room } : undefined;
+	}
+	if (viewer.tier !== "owner") return undefined;
+	return (await ctx.rooms.resolve(room)) ? { owners: true } : undefined;
+}
+
+/** A viewer's message to a host room: stored and shown, and a `turn` is also handed to the room's claim. */
+async function hostSend(
+	ctx: HostContext,
+	{
+		frame,
+		viewer,
+		connection,
+		refuse,
+	}: FrameContext<Extract<ClientFrame, { type: "send" }>>,
+): Promise<void> {
+	const reject = (code: RefusalCode) => refuse(code, frame.id);
+	const found = hostRoomOf(ctx, frame.room);
+	if (!found) return reject("unknown_room");
+	const access = await ctx.access.of(viewer, frame.room);
+	if (!access) return reject("unknown_room");
+	const mode = frame.mode ?? "turn";
+	if (!access.send.includes(mode)) return reject("forbidden");
+	const text = frame.text.trim();
+	if (text.length > MAX_MESSAGE_CHARS) return reject("too_long");
+	const ids = frame.uploads ?? [];
+	if (text === "" && ids.length === 0) return reject("empty");
+	// A turn is written as the person; without the actor their credential vouched for, it cannot be.
+	if (mode === "turn" && !connection.actor) return reject("forbidden");
+	const files = ctx.uploads.claim(ids, viewer.principalId);
+	if (!files) return reject("unknown_upload");
+	if (!ctx.app.started) return reject("not_accepted");
+	if (found.kind.send) {
+		let verdict: "accepted" | { refused: string };
+		try {
+			verdict = await found.kind.send(viewer, found.id, { mode, text, files });
+		} catch (error) {
+			ctx.logger.warn(
+				{ kind: found.kind.kind, err: error },
+				"a kind's send failed",
+			);
+			return reject("not_accepted");
+		}
+		if (verdict !== "accepted") return reject("not_accepted");
+	}
+	const expiresAt = found.kind.retention
+		? ctx.now() + found.kind.retention.fileDays * 86_400_000
+		: undefined;
+	const message = await ctx.app.publish(
+		{
+			room: asRoom(frame.room),
+			kind: "owner",
+			principalId: viewer.principalId,
+			author: viewer.name,
+			text,
+			files: [...files],
+			authorKind: "member",
+		},
+		connection,
+	);
+	ctx.uploads.use(
+		files.map((file) => file.id),
+		{ room: frame.room, ...(expiresAt === undefined ? {} : { expiresAt }) },
+	);
+	ctx.sockets.deliver(
+		{ type: "accepted", id: frame.id, room: frame.room, message },
+		{ connection },
+	);
+	// What a person sends is read by them, and the others see the room has moved.
+	const mark = await ctx.reads.advance(
+		frame.room,
+		viewer.principalId,
+		message.id,
+	);
+	if (mark)
+		ctx.sockets.deliver(
+			{
+				type: "read",
+				room: frame.room,
+				principal: viewer.principalId,
+				name: viewer.name,
+				upTo: mark.upTo,
+				at: mark.at,
+			},
+			{ room: frame.room },
+		);
+	if (mode !== "turn" || !connection.actor) return;
+	// The router never records a lower tier from these facts: the app is not the authority on roles.
+	const actor: ActorFacts = {
+		...connection.actor,
+		surface: ctx.surface,
+		partial: true,
+	};
+	const inbound: InboundMessage = {
+		channel: asRoom(frame.room),
+		messageId: `app-${message.id}`,
+		actor,
+		authorId: viewer.principalId,
+		authorName: viewer.name,
+		authorIsBot: false,
+		isDirect: false,
+		mentionsBot: false,
+		repliesToBot: false,
+		text,
+		attachments: files.map((file) => ctx.uploads.refOf(file)),
+	};
+	try {
+		ctx.app.deliver(inbound);
+	} catch (error) {
+		ctx.logger.warn(
+			{ room: frame.room, err: error },
+			"a host room turn was not delivered",
+		);
+	}
+}
+
+/** The connection of a frame, for the pieces that need its socket. */
+export type { AppSocket };