pi-roundtable-web 0.22.5 → 0.23.0

package/src/options.ts

@@ -2,7 +2,13 @@ import { join } from "node:path";
 import type { ChannelKey, RoundtablePlugin } from "pi-roundtable";
 import { PluginError } from "pi-roundtable";
 import { PANES, type PaneName } from "./api-types.ts";
+import {
+	DEFAULT_UPLOAD_MAX_BYTES,
+	UPLOAD_FRAMING_BYTES,
+} from "./app/uploads.ts";
 import type { ConsoleFeatures, ConsolePresentation } from "./features.ts";
+import { isHostPattern } from "./push/endpoint.ts";
+import { pushFetchOf } from "./push/test-fetch.ts";
 import type { RequestVerifier } from "./verifier.ts";
 
 /**
@@ -12,14 +18,78 @@ import type { RequestVerifier } from "./verifier.ts";
 export const DEFAULT_RELAY_NOTE =
 	"(The owner wrote this in a personal agent that relays it over MCP, not on Discord. Answer the owner directly, just as you would on Discord; the agent passes your reply back.)";
 
+/** The default environment variable `auth: { mode: "password" }` reads the password from. */
+const DEFAULT_PASSWORD_ENV = "ROUNDTABLE_WEB_PASSWORD";
+/** How many days a password session lasts by default. */
+const DEFAULT_SESSION_DAYS = 30;
+/** The shortest password the console accepts, in characters. */
+export const MIN_PASSWORD_LENGTH = 12;
+/** The key prefix of the app's rooms by default. */
+const DEFAULT_SURFACE = "app";
+/** How many seconds a turn waits on its card before it goes on without the answer, by default. */
+const DEFAULT_CARD_GRACE_SECONDS = 120;
+
+/**
+ * How the console knows who is asking. Every mode but `verifier` speaks for one principal through
+ * the plugin identity `token:web-console`, which the plugin declares; read "Authentication" and
+ * "Threat model" in the README before choosing `none` or `password`.
+ */
+export type WebAuthOptions =
+	| {
+			/**
+			 * No authentication: whoever reaches the listener is the owner. Written explicitly, never
+			 * a default, and only for a listener a person cannot reach but the owner: a unix socket,
+			 * or TCP on `127.0.0.1`, `::1` or `localhost`.
+			 */
+			mode: "none";
+			/** Allows `none` on a TCP listener that reaches beyond this machine, when a network in front of it keeps everyone else out. */
+			trustNetwork?: boolean;
+			/** The principal it speaks for; default the primary owner (the first of `access.owners`). */
+			principal?: string;
+	  }
+	| {
+			/**
+			 * A password from the environment, asked on a login page, then a signed session cookie.
+			 * It resists the network, not an agent whose shell runs as the same user.
+			 */
+			mode: "password";
+			/** The environment variable that holds the password, at least 12 characters; default `ROUNDTABLE_WEB_PASSWORD`. */
+			passwordEnv?: string;
+			/** How long a login lasts, 1 to 365 days; default 30. */
+			sessionDays?: number;
+			/** The principal it speaks for; default the primary owner. */
+			principal?: string;
+	  }
+	| {
+			/** A request verifier, such as `cloudflareAccess(...)`; the same as the `verifier` option. */
+			mode: "verifier";
+			verifier: RequestVerifier;
+	  };
+
+/** `auth` checked and filled in. */
+export type ResolvedAuth =
+	| { mode: "none"; trustNetwork: boolean; principal?: string }
+	| {
+			mode: "password";
+			passwordEnv: string;
+			sessionDays: number;
+			principal?: string;
+	  }
+	| { mode: "verifier"; verifier: RequestVerifier };
+
 export interface WebConsoleOptions {
+	/**
+	 * How requests are authenticated; one of `auth` or `verifier` is required, and without either
+	 * the plugin refuses to start rather than serve without authentication. Only a person whose
+	 * principal holds the owner role gets in.
+	 */
+	auth?: WebAuthOptions;
 	/**
 	 * Decides whether a request comes from someone the operator's proxy authenticated, and reports
-	 * who; required. `cloudflareAccess(...)` is the built-in one. Without it the plugin refuses to
-	 * start rather than serve without authentication. Only a person whose principal holds the owner
-	 * role gets in.
+	 * who; the same as `auth: { mode: "verifier", verifier }`, and giving both throws.
+	 * `cloudflareAccess(...)` is the built-in one.
 	 */
-	verifier: RequestVerifier;
+	verifier?: RequestVerifier;
 	/** Host-specific data and actions, resolved against public plugin setup context. */
 	features?:
 		| ConsoleFeatures
@@ -47,10 +117,65 @@ export interface WebConsoleOptions {
 	listener?: string;
 	/** Hash routes by default; path routes retain links such as /console/skills. */
 	routing?: "hash" | "path";
-	/** The panes to serve, in the order the page lists them; default all of `overview`, `conversations`, `notes`. */
+	/**
+	 * The panes to serve, in the order the page lists them; default `rooms`, `table`, `overview`,
+	 * `schedules`, `conversations`, `notes`. `rooms` is the owner app: the same agent team as on
+	 * Discord, in rooms of its own; `table` seats its agents at the round table and needs `rooms`.
+	 * An explicit list is kept as written, so a host that listed the panes before 0.23 adds
+	 * `rooms`, `table` and `schedules` by hand.
+	 */
 	panes?: readonly PaneName[];
+	/**
+	 * The key prefix of the app's rooms: `<surface>:agent.<name>` and `<surface>:group.<name>`.
+	 * A lower-case word that is not `discord`; default `app`. Rooms keep their conversations under
+	 * it, so changing it starts every room over.
+	 */
+	surface?: string;
+	/**
+	 * How long a turn waits on its approval or question card before it goes on without the answer,
+	 * in seconds; default 120, as on Discord. The card stays open for a day, and an answer given
+	 * then starts a new turn in the room.
+	 */
+	cardGraceSeconds?: number;
+	/**
+	 * The most bytes of one file a person may upload in the app, 100 MiB by default. The upload
+	 * route raises the listener's request body limit to this plus the form's framing, and the
+	 * agent reads files up to it. At most 4 GiB. The listener has one body limit, so this raises
+	 * it for every route on the listener, not only the upload route. A reverse proxy in front has a limit of its own, and
+	 * Cloudflare's free plan caps request bodies at 100 MB. Files are streamed to disk, not held
+	 * in memory.
+	 */
+	uploadMaxBytes?: number;
+	/**
+	 * Web Push to the owner's devices, sent when a card waits, a long-running cap is reached, an
+	 * agent replies on its own, or a notice is sent, and no page of the owner is in view. The
+	 * payload is encrypted for the device. Only the `rooms` pane has push.
+	 */
+	push?: {
+		/**
+		 * Whether a notification shows the start of the message (the first 120 characters); default
+		 * true. With `false` it says only that something is waiting and where.
+		 */
+		preview?: boolean;
+		/**
+		 * Push services the server may post to besides the browsers' own (Google, Mozilla, Apple,
+		 * Microsoft), as host names; a leading `*.` allows every subdomain. Their endpoints must
+		 * still be `https`.
+		 */
+		endpointHosts?: readonly string[];
+		/**
+		 * Who a push service may contact about this server (the VAPID `sub`): a `mailto:` or
+		 * `https:` URL. Default `origin` when that is `https`; with an `http` origin push stays off
+		 * until this is set.
+		 */
+		subject?: string;
+	};
 	/** The page's title and heading; default `Roundtable`. */
 	title?: string;
+	/** Where the install icons come from; default the ones this package ships. */
+	icons?: { dir: string };
+	/** How the page looks: `modern` (default) or `camelot`. The page's owner can switch it in the app. */
+	appearance?: { look?: "modern" | "camelot" };
 	/** Text a relayed message begins with, taken off the owner's words; default the remote MCP note. */
 	relayNotes?: readonly string[];
 	/** Conversations the console neither lists nor reads. */
@@ -61,15 +186,28 @@ export interface WebConsoleOptions {
 
 /** Options checked and filled in. */
 export interface ResolvedOptions {
-	verifier: RequestVerifier;
+	auth: ResolvedAuth;
 	origin: string;
 	ownerId: string | undefined;
+	dataDir: string;
 	sessionsDir: string;
 	mount: string;
 	listener: string;
 	routing: "hash" | "path";
 	panes: PaneName[];
+	surface: string;
+	cardGraceSeconds: number;
+	uploadMaxBytes: number;
+	push: {
+		preview: boolean;
+		endpointHosts: readonly string[];
+		/** The VAPID contact; undefined = push is off. */
+		subject: string | undefined;
+		fetch: typeof fetch | undefined;
+	};
 	title: string;
+	iconsDir: string | undefined;
+	look: "modern" | "camelot";
 	relayNotes: readonly string[];
 	exclude: ((key: ChannelKey) => boolean) | undefined;
 	assetDir: string | undefined;
@@ -119,7 +257,15 @@ function checkOrigin(origin: string): string {
 }
 
 function checkPanes(panes: readonly PaneName[] | undefined): PaneName[] {
-	if (panes === undefined) return ["overview", "conversations", "notes"];
+	if (panes === undefined)
+		return [
+			"rooms",
+			"table",
+			"overview",
+			"schedules",
+			"conversations",
+			"notes",
+		];
 	if (panes.length === 0) fail("panes is empty; serve at least one pane");
 	for (const pane of panes)
 		if (!PANES.includes(pane))
@@ -127,15 +273,155 @@ function checkPanes(panes: readonly PaneName[] | undefined): PaneName[] {
 				`unknown pane ${JSON.stringify(pane)}; the panes are ${PANES.join(", ")}`,
 			);
 	if (new Set(panes).size !== panes.length) fail("panes lists a pane twice");
+	if (panes.includes("schedules") && !panes.includes("rooms"))
+		fail("the schedules pane needs the rooms pane, which serves its API");
+	if (panes.includes("table") && !panes.includes("rooms"))
+		fail("the table pane needs the rooms pane, whose agents it seats");
 	return [...panes];
 }
 
-/** Checks the options at the point the plugin is created, so a bad setting stops the host before anything starts. */
-export function resolveOptions(options: WebConsoleOptions): ResolvedOptions {
-	if (typeof options.verifier !== "function")
+function checkAuth(options: WebConsoleOptions): ResolvedAuth {
+	const { auth, verifier } = options;
+	if (auth !== undefined && verifier !== undefined)
+		fail(
+			'both auth and verifier are given. `verifier` is shorthand for `auth: { mode: "verifier", verifier }`; pass one',
+		);
+	if (auth === undefined) {
+		if (typeof verifier !== "function")
+			fail(
+				'no verifier or auth. The console serves the owner\'s conversations and notes, so it will not start without a way to authenticate every request; pass `auth: { mode: "password" }`, `auth: { mode: "none" }` for a listener only the owner reaches, or `verifier: cloudflareAccess({...})` or your own',
+			);
+		return { mode: "verifier", verifier };
+	}
+	const mode = (auth as { mode?: unknown } | null)?.mode;
+	const principal = (auth as { principal?: unknown }).principal;
+	if (
+		principal !== undefined &&
+		(typeof principal !== "string" || !principal.trim())
+	)
+		fail(
+			"auth.principal is empty. Leave it out to speak for the primary owner",
+		);
+	const named =
+		typeof principal === "string" ? { principal: principal.trim() } : {};
+	switch (mode) {
+		case "none": {
+			const { trustNetwork } = auth as { trustNetwork?: unknown };
+			if (trustNetwork !== undefined && typeof trustNetwork !== "boolean")
+				fail("auth.trustNetwork must be true or false");
+			return { mode, trustNetwork: trustNetwork === true, ...named };
+		}
+		case "password": {
+			const {
+				passwordEnv = DEFAULT_PASSWORD_ENV,
+				sessionDays = DEFAULT_SESSION_DAYS,
+			} = auth as { passwordEnv?: unknown; sessionDays?: unknown };
+			if (typeof passwordEnv !== "string" || !passwordEnv.trim())
+				fail("auth.passwordEnv is empty");
+			if (
+				typeof sessionDays !== "number" ||
+				!Number.isInteger(sessionDays) ||
+				sessionDays < 1 ||
+				sessionDays > 365
+			)
+				fail("auth.sessionDays must be a whole number of days from 1 to 365");
+			return {
+				mode,
+				passwordEnv: passwordEnv.trim(),
+				sessionDays,
+				...named,
+			};
+		}
+		case "verifier": {
+			const given = (auth as { verifier?: unknown }).verifier;
+			if (typeof given !== "function")
+				fail(
+					"auth.verifier is not a function; pass `cloudflareAccess({...})` or your own",
+				);
+			return { mode, verifier: given as RequestVerifier };
+		}
+		default:
+			fail(
+				`auth.mode ${JSON.stringify(mode)} is unknown; the modes are none, password and verifier`,
+			);
+	}
+}
+
+function checkSurface(surface: string | undefined): string {
+	if (surface === undefined) return DEFAULT_SURFACE;
+	if (typeof surface !== "string" || !/^[a-z][a-z0-9-]*$/.test(surface))
+		fail(
+			`surface ${JSON.stringify(surface)} must be a lower-case word such as app`,
+		);
+	if (surface === "discord")
+		fail("surface cannot be discord, whose channels the Discord plugin serves");
+	return surface;
+}
+
+function checkGrace(seconds: number | undefined): number {
+	if (seconds === undefined) return DEFAULT_CARD_GRACE_SECONDS;
+	if (typeof seconds !== "number" || !(seconds > 0) || seconds > 3600)
+		fail(
+			"cardGraceSeconds must be a number of seconds above 0 and at most 3600",
+		);
+	return seconds;
+}
+
+function checkPush(
+	options: WebConsoleOptions,
+	origin: string,
+): ResolvedOptions["push"] {
+	const push = options.push;
+	if (push?.preview !== undefined && typeof push.preview !== "boolean")
+		fail("push.preview must be true or false");
+	const hosts = push?.endpointHosts ?? [];
+	if (!Array.isArray(hosts))
+		fail("push.endpointHosts must be a list of host names");
+	for (const host of hosts)
+		if (typeof host !== "string" || !isHostPattern(host))
+			fail(
+				`push.endpointHosts has ${JSON.stringify(host)}, which is not a host name such as push.example.com or *.push.example.com`,
+			);
+	const given = push?.subject;
+	if (
+		given !== undefined &&
+		!(
+			typeof given === "string" &&
+			(/^mailto:[^\s@]+@[^\s@]+$/.test(given) ||
+				(URL.parse(given)?.protocol === "https:" && !/\s/.test(given)))
+		)
+	)
+		fail(
+			"push.subject must be a mailto: address or an https: URL, such as mailto:ops@example.com",
+		);
+	return {
+		preview: push?.preview ?? true,
+		endpointHosts: [...hosts],
+		subject: given ?? (origin.startsWith("https:") ? origin : undefined),
+		fetch: pushFetchOf(options),
+	};
+}
+
+/** The largest `uploadMaxBytes`: the limit is also the listener's body limit. */
+const MAX_UPLOAD_MAX_BYTES = 4 * 1024 ** 3;
+
+function checkUploadMax(bytes: number | undefined): number {
+	if (bytes === undefined) return DEFAULT_UPLOAD_MAX_BYTES;
+	if (
+		typeof bytes !== "number" ||
+		!Number.isSafeInteger(bytes + UPLOAD_FRAMING_BYTES) ||
+		bytes < 1 ||
+		bytes > MAX_UPLOAD_MAX_BYTES
+	)
 		fail(
-			"no verifier. The console serves the owner's conversations and notes, so it will not start without one that authenticates every request; pass `verifier: cloudflareAccess({...})` or your own",
+			"uploadMaxBytes must be a whole number of bytes, from 1 to 4 GiB, that the upload route can ask the listener to take with the form's framing added",
 		);
+	return bytes;
+}
+
+/** Checks the options at the point the plugin is created, so a bad setting stops the host before anything starts. */
+export function resolveOptions(options: WebConsoleOptions): ResolvedOptions {
+	const auth = checkAuth(options);
 	if (
 		options.routing !== undefined &&
 		options.routing !== "path" &&
@@ -155,18 +441,28 @@ export function resolveOptions(options: WebConsoleOptions): ResolvedOptions {
 		fail(
 			"ownerId is empty. Leave it out: the console finds each visitor's principal, and a verifier that reports no actor speaks for the primary owner",
 		);
+	const look = options.appearance?.look ?? "modern";
+	if (look !== "modern" && look !== "camelot")
+		fail("appearance.look must be modern or camelot");
 	const title = options.title?.trim() ?? "Roundtable";
 	if (!title) fail("title is empty");
 	return {
-		verifier: options.verifier,
+		auth,
 		origin: checkOrigin(options.origin),
 		ownerId,
+		dataDir: options.dataDir ?? "data",
 		sessionsDir: join(options.dataDir ?? "data", "sessions"),
 		mount: checkMount(options.mountPath ?? "/console"),
 		listener: options.listener ?? "public",
 		routing: options.routing ?? "hash",
 		panes,
+		surface: checkSurface(options.surface),
+		cardGraceSeconds: checkGrace(options.cardGraceSeconds),
+		uploadMaxBytes: checkUploadMax(options.uploadMaxBytes),
+		push: checkPush(options, checkOrigin(options.origin)),
 		title,
+		iconsDir: options.icons?.dir,
+		look,
 		relayNotes: options.relayNotes ?? [DEFAULT_RELAY_NOTE],
 		exclude: options.exclude,
 		assetDir: options.assetDir,

package/src/page-colors.ts

@@ -0,0 +1,9 @@
+/**
+ * The page's background in each look and scheme, which the browser's toolbar takes (`--bg` in
+ * tokens.css and in styles/camelot.css). Pure data: the server writes it into the page, and the
+ * page itself reads it when the look or the scheme changes.
+ */
+export const PAGE_COLORS = {
+	modern: { light: "#f5f6f8", dark: "#0f1115" },
+	camelot: { light: "#f4ead5", dark: "#0f1726" },
+} as const;

package/src/page-presentation.ts

@@ -1,30 +1,35 @@
 import type { ConsolePresentation } from "./features.ts";
+import { escapeHtml } from "./http.ts";
+import { PAGE_COLORS } from "./page-colors.ts";
 
-const attribute = (value: string): string =>
-	value
-		.replaceAll("&", "&")
-		.replaceAll('"', """)
-		.replaceAll("<", "&lt;")
-		.replaceAll(">", "&gt;")
-		.replaceAll("'", "&#39;");
+/** The tags that make the page installable; the URLs resolve against the page, so the mount does not matter. */
+const pwaTags = (look: "modern" | "camelot"): string =>
+	'<link rel="manifest" href="./manifest.webmanifest" crossorigin="use-credentials">' +
+	`<meta name="theme-color" content="${PAGE_COLORS[look].light}" media="(prefers-color-scheme: light)">` +
+	`<meta name="theme-color" content="${PAGE_COLORS[look].dark}" media="(prefers-color-scheme: dark)">` +
+	'<link rel="apple-touch-icon" href="./icons/apple-180.png">' +
+	'<meta name="apple-mobile-web-app-capable" content="yes">';
 
 /** Authenticated, inert bootstrap data localizes even a failed first API request without inline scripts. */
 export function presentPage(
 	body: Uint8Array,
 	mount: string | undefined,
 	presentation: ConsolePresentation | undefined,
+	look: "modern" | "camelot" = "modern",
 ): Uint8Array<ArrayBuffer> | string {
-	if (!mount && !presentation) return new Uint8Array(body);
-	let head = "<head>";
-	if (mount) head += `<base href="${attribute(`${mount}/`)}">`;
+	// Not in web/index.html: the bundler would try to resolve and rewrite these URLs.
+	let head = `<head>${pwaTags(look)}`;
+	if (mount) head += `<base href="${escapeHtml(`${mount}/`)}">`;
 	if (presentation)
-		head += `<meta name="roundtable-console-presentation" content="${attribute(JSON.stringify(presentation))}">`;
+		head += `<meta name="roundtable-console-presentation" content="${escapeHtml(JSON.stringify(presentation))}">`;
+	// After the base, so it resolves under the mount; a script of the page's own origin, which its policy allows.
+	head += '<script src="./theme-init.js"></script>';
 	let html = new TextDecoder().decode(body).replace("<head>", () => head);
 	if (presentation?.locale)
 		html = html.replace(
 			/(<html[^>]*lang=")[^"]*(")/,
 			(_all, prefix: string, suffix: string) =>
-				`${prefix}${attribute(presentation.locale ?? "en")}${suffix}`,
+				`${prefix}${escapeHtml(presentation.locale ?? "en")}${suffix}`,
 		);
 	return html;
 }

package/src/push/api.ts

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import type { IdentityService } from "pi-roundtable";
+import type {
+	PushDevicesView,
+	PushDeviceView,
+	PushKeyView,
+} from "../api-types.ts";
+import type { Authenticated } from "../auth/authenticator.ts";
+import { ConsoleHttpError as HttpError, json } from "../http.ts";
+import { readLimited } from "../request-body.ts";
+import type { EndpointPolicy } from "./endpoint.ts";
+import type { PushSubscriptions } from "./subscriptions.ts";
+import type { Vapid } from "./vapid.ts";
+
+/** The most devices one person may have subscribed. */
+export const MAX_DEVICES = 20;
+/** The largest JSON body a subscription is sent in. */
+const MAX_BODY_BYTES = 8 * 1024;
+const MAX_LABEL_CHARS = 80;
+/** An uncompressed P-256 point. */
+const P256DH_BYTES = 65;
+const AUTH_BYTES = 16;
+
+export interface PushApiOptions {
+	vapid: Pick<Vapid, "publicKey">;
+	policy: EndpointPolicy;
+	subscriptions: Pick<PushSubscriptions, "of" | "save" | "remove">;
+	identity: Pick<IdentityService, "tierOf">;
+	/** False when the server has no VAPID contact: devices cannot be added, since nothing would reach them. */
+	enabled: boolean;
+}
+
+/** What identifies a device in a list without handing its endpoint around: the endpoint's SHA-256, hex. */
+const deviceId = (endpoint: string): string =>
+	createHash("sha256").update(endpoint).digest("hex");
+
+const decode = (value: unknown, bytes: number, name: string): string => {
+	if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value))
+		throw new HttpError(400, `${name} must be base64url.`);
+	const raw = Buffer.from(value, "base64url");
+	if (raw.byteLength !== bytes || (bytes === P256DH_BYTES && raw[0] !== 4))
+		throw new HttpError(400, `${name} is not a valid key.`);
+	return value;
+};
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+	const raw = await readLimited(request, MAX_BODY_BYTES);
+	if (!raw) throw new HttpError(413, "The body is too large.");
+	let value: unknown;
+	try {
+		value = JSON.parse(raw.toString("utf8"));
+	} catch {
+		throw new HttpError(400, "The body is not JSON.");
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw new HttpError(400, "The body is not an object.");
+	return value as Record<string, unknown>;
+}
+
+/**
+ * The push routes under `<mount>/api/push/`: the key a browser subscribes against, and the
+ * signed-in owner's own devices: list, add, remove. A device is only ever read or removed by the
+ * person who added it, and an endpoint is accepted only on a push service the policy allows.
+ */
+export class PushApi {
+	readonly #options: PushApiOptions;
+
+	constructor(options: PushApiOptions) {
+		this.#options = options;
+	}
+
+	/** Answers `api/push/...`; undefined for any other path. */
+	async handle(
+		request: Request,
+		parts: readonly string[],
+		admission: Authenticated,
+	): Promise<Response | undefined> {
+		const [head, area, name, id] = parts;
+		if (head !== "api" || area !== "push") return undefined;
+		try {
+			const principalId = await this.#owner(admission);
+			const { method } = request;
+			if (name === "key" && !id && method === "GET")
+				return json({
+					key: this.#options.vapid.publicKey,
+				} satisfies PushKeyView);
+			if (name !== "subscriptions")
+				throw new HttpError(404, "There is no such API.");
+			if (!id && method === "GET")
+				return json(await this.#devices(principalId));
+			if (!id && method === "POST")
+				return await this.#add(request, principalId);
+			if (!id && method === "DELETE")
+				return await this.#removeEndpoint(request, principalId);
+			if (id && method === "DELETE")
+				return await this.#removeId(id, principalId);
+			throw new HttpError(405, "Method not allowed.");
+		} catch (error) {
+			if (error instanceof HttpError)
+				return json({ error: error.message }, error.status);
+			throw error;
+		}
+	}
+
+	async #owner(admission: Authenticated): Promise<string> {
+		const { principal } = admission.visitor;
+		if ((await this.#options.identity.tierOf(principal.id)) !== "owner")
+			throw new HttpError(403, "Only an owner may do this.");
+		return principal.id;
+	}
+
+	async #devices(principalId: string): Promise<PushDevicesView> {
+		const devices = await this.#options.subscriptions.of(principalId);
+		return {
+			devices: devices.map(
+				(device): PushDeviceView => ({
+					id: deviceId(device.endpoint),
+					...(device.label ? { label: device.label } : {}),
+					createdAt: device.createdAt.toISOString(),
+					...(device.lastOkAt
+						? { lastOkAt: device.lastOkAt.toISOString() }
+						: {}),
+				}),
+			),
+		};
+	}
+
+	async #add(request: Request, principalId: string): Promise<Response> {
+		if (!this.#options.enabled)
+			throw new HttpError(
+				503,
+				"Push is not set up: set push.subject on the server.",
+			);
+		const body = await bodyOf(request);
+		const checked = this.#options.policy.check(body.endpoint);
+		if ("refusal" in checked) throw new HttpError(400, checked.refusal);
+		const keys = body.keys;
+		if (typeof keys !== "object" || keys === null)
+			throw new HttpError(400, "keys must hold p256dh and auth.");
+		const { p256dh, auth } = keys as Record<string, unknown>;
+		const label = body.label;
+		if (label !== undefined && typeof label !== "string")
+			throw new HttpError(400, "label must be text.");
+		const endpoint = checked.url.href;
+		const saved = await this.#options.subscriptions.save(
+			{
+				endpoint,
+				principalId,
+				p256dh: decode(p256dh, P256DH_BYTES, "p256dh"),
+				auth: decode(auth, AUTH_BYTES, "auth"),
+				...(label?.trim()
+					? { label: label.trim().slice(0, MAX_LABEL_CHARS) }
+					: {}),
+			},
+			MAX_DEVICES,
+		);
+		if (saved === "taken")
+			throw new HttpError(
+				409,
+				"That device is already subscribed by someone else.",
+			);
+		if (saved === "full")
+			throw new HttpError(
+				400,
+				"Too many devices. Remove one in the settings first.",
+			);
+		return json({ id: deviceId(endpoint) });
+	}
+
+	async #removeEndpoint(
+		request: Request,
+		principalId: string,
+	): Promise<Response> {
+		const body = await bodyOf(request);
+		const checked = this.#options.policy.check(body.endpoint);
+		if ("refusal" in checked) throw new HttpError(400, checked.refusal);
+		// Removing a device that is already gone is as good as removing it.
+		await this.#options.subscriptions.remove(checked.url.href, principalId);
+		return json({ ok: true });
+	}
+
+	async #removeId(id: string, principalId: string): Promise<Response> {
+		const device = (await this.#options.subscriptions.of(principalId)).find(
+			(candidate) => deviceId(candidate.endpoint) === id,
+		);
+		if (!device) throw new HttpError(404, "There is no such device.");
+		await this.#options.subscriptions.remove(device.endpoint, principalId);
+		return json({ ok: true });
+	}
+}