pi-roundtable-web 0.24.2 → 0.26.0

package/src/push/triggers.ts

@@ -1,4 +1,5 @@
 import type { IdentityService, Logger } from "pi-roundtable";
+import type { NewOutboxRow, PushOutbox } from "./outbox.ts";
 import type { PushPayload, PushSender, SendResult } from "./sender.ts";
 import type { PushSubscriptions, Subscription } from "./subscriptions.ts";
 
@@ -7,12 +8,26 @@ export const PREVIEW_CHARS = 120;
 /** Replies in one room closer together than this share a notification. */
 const REPLY_QUIET_MS = 15_000;
 
+/**
+ * Where the push goes when the app does not sign it: the outbox an external sender empties. The
+ * app then holds no VAPID key and a row carries a title and a preview only with `content: "full"`.
+ */
+export interface OutboxRoute {
+	outbox: Pick<PushOutbox, "enqueue">;
+	content: "full" | "none";
+	/** The count the app icon shows for the person: their notices not handled. */
+	badge(principalId: string): Promise<number>;
+}
+
 export interface PushServiceOptions {
 	subscriptions: Pick<
 		PushSubscriptions,
 		"all" | "delivered" | "forget" | "failed"
 	>;
-	sender: Pick<PushSender, "send">;
+	/** Signs and sends in this process; absent when `route` queues the pushes for an external sender. */
+	sender?: Pick<PushSender, "send">;
+	/** Queue the pushes instead of signing them here; absent = sign and send in this process. */
+	route?: OutboxRoute;
 	identity: Pick<IdentityService, "tierOf">;
 	/** Whether a page of this person is in view now; their devices are not pushed while one is. */
 	visible(principalId: string): boolean;
@@ -33,6 +48,8 @@ export interface PushServiceOptions {
 	 * card is. Default never.
 	 */
 	muted?: (room: string) => Promise<boolean>;
+	/** Whether a room is a host's: those reach phones only through notices, never through a card or reply push. */
+	hostRoom?: (room: string) => boolean;
 }
 
 /** What a trigger says; the service shapes it into a notification. */
@@ -72,6 +89,7 @@ export class PushService {
 
 	/** A card opened in a room: an approval or a question waits for an owner. */
 	card(room: string, title: string, longRunningCap: boolean): Promise<void> {
+		if (this.#options.hostRoom?.(room)) return Promise.resolve();
 		return this.#push({
 			kind: longRunningCap ? "cap" : "card",
 			title: longRunningCap ? "Long-running cap reached" : "Card waiting",
@@ -83,6 +101,7 @@ export class PushService {
 
 	/** An agent posted in a room, such as a finished job's report or an answer nobody was watching for. */
 	async reply(room: string, author: string, text: string): Promise<void> {
+		if (this.#options.hostRoom?.(room)) return;
 		const now = this.#now();
 		if (this.#options.quiet?.(now)) return;
 		if (await this.#muted(room)) return;
@@ -142,12 +161,15 @@ export class PushService {
 				...(preview && event.text ? { body: previewOf(event.text) } : {}),
 			};
 			const targets = await this.#targets(event.principalId);
+			if (this.#options.route) {
+				await this.#queue(this.#options.route, event, payload, targets);
+				return;
+			}
+			const { sender } = this.#options;
+			if (!sender) return;
 			await Promise.all(
 				targets.map(async (target) =>
-					this.#settle(
-						target,
-						await this.#options.sender.send(target, payload),
-					),
+					this.#settle(target, await sender.send(target, payload)),
 				),
 			);
 		} catch (error) {
@@ -155,6 +177,35 @@ export class PushService {
 		}
 	}
 
+	/** One outbox row for each person the push reaches; the sender finds their devices. */
+	async #queue(
+		route: OutboxRoute,
+		event: Event,
+		payload: PushPayload,
+		targets: readonly Subscription[],
+	): Promise<void> {
+		const people = [...new Set(targets.map((target) => target.principalId))];
+		await Promise.all(
+			people.map(async (principalId) => {
+				const row: NewOutboxRow = {
+					kind: payload.kind === "cap" ? "card" : payload.kind,
+					tag: payload.tag,
+					principalId,
+					open: payload.url ?? "",
+					urgency: payload.kind === "reply" ? "normal" : "high",
+					badge: await route.badge(principalId),
+					...(route.content === "full"
+						? {
+								title: event.title,
+								...(payload.body ? { body: payload.body } : {}),
+							}
+						: {}),
+				};
+				await route.outbox.enqueue(row);
+			}),
+		);
+	}
+
 	async #targets(principalId?: string): Promise<Subscription[]> {
 		const owners = new Map<string, boolean>();
 		const isOwner = async (id: string): Promise<boolean> => {

package/src/push/vapid.ts

@@ -71,6 +71,25 @@ async function importStored(stored: Stored, path: string): Promise<Vapid> {
 	return { publicKey: stored.publicKey, privateKey };
 }
 
+/**
+ * The VAPID keys in `path`, which must exist: for a sender process that holds the key the app
+ * never sees. A missing or unreadable file stops it, since a new key would not match the one the
+ * devices subscribed against.
+ */
+export async function readVapid(path: string): Promise<Vapid> {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT")
+			throw new Error(
+				`${path} does not exist; the sender needs the VAPID key file the devices subscribed against`,
+			);
+		throw error;
+	}
+	return importStored(parse(raw, path), path);
+}
+
 /**
  * The VAPID keys in `path`, made on first use with WebCrypto and kept readable by this user
  * alone. Subscriptions are bound to the public key, so the file must outlive a restart; a file

package/src/push/web-push-transport.ts

@@ -0,0 +1,106 @@
+import type { SQL } from "bun";
+import type { Logger } from "pi-roundtable";
+import type { PushTransport } from "./drain.ts";
+import { EndpointPolicy } from "./endpoint.ts";
+import { type PushPayload, PushSender } from "./sender.ts";
+import { PushSubscriptions } from "./subscriptions.ts";
+import { readVapid, type Vapid } from "./vapid.ts";
+
+/** The name of the Web Push transport, which a notice's `via` may name. */
+export const WEB_PUSH = "web-push";
+
+export interface WebPushTransportOptions {
+	/** The key the devices subscribed against. Read when the first push is sent; it must exist. */
+	vapidFile?: string;
+	/** The key itself, when the caller already holds it (the app's own sender). */
+	vapid?: Vapid;
+	/** The VAPID `sub`: a `mailto:` or `https:` contact for the push services. */
+	subject: string;
+	/** Push services besides the browsers' own, as `push.endpointHosts` writes them. */
+	endpointHosts?: readonly string[];
+	database: SQL;
+	/** The HTTP client; default `fetch`. */
+	fetch?: typeof fetch;
+	logger?: Logger;
+}
+
+/** A logger that says nothing, for a sender run without one. */
+const silent: Logger = {
+	debug: () => undefined,
+	info: () => undefined,
+	warn: () => undefined,
+	error: () => undefined,
+	fatal: () => undefined,
+	child: () => silent,
+};
+
+/** What a push says on a device, from the row and the words the sender gave it. */
+export function payloadOf(
+	row: Parameters<PushTransport["send"]>[0],
+	rendered: Parameters<PushTransport["send"]>[1],
+): PushPayload {
+	return {
+		kind: row.kind,
+		title: rendered.title,
+		...(rendered.body ? { body: rendered.body } : {}),
+		tag: row.tag,
+		url: row.open,
+		badge: row.badge,
+		urgency: row.urgency,
+	};
+}
+
+/**
+ * Web Push to all the devices a person subscribed. It reads their subscriptions, posts a sealed
+ * payload to each under the VAPID key, forgets a device the push service says is gone, and counts
+ * a failure against one that keeps failing. `sent` when at least one device took it; `gone` when
+ * every device was gone; `skipped` when the person has no device.
+ */
+export function webPushTransport(
+	options: WebPushTransportOptions,
+): PushTransport {
+	const subscriptions = new PushSubscriptions(options.database);
+	const policy = new EndpointPolicy(options.endpointHosts);
+	const logger = options.logger ?? silent;
+	let sender: Promise<PushSender> | undefined;
+	const senderOf = (): Promise<PushSender> => {
+		sender ??= (async () => {
+			const vapid =
+				options.vapid ??
+				(options.vapidFile ? await readVapid(options.vapidFile) : undefined);
+			if (!vapid) throw new Error("webPushTransport needs vapidFile or vapid");
+			return new PushSender({
+				vapid,
+				subject: options.subject,
+				policy,
+				...(options.fetch ? { fetch: options.fetch } : {}),
+				logger,
+			});
+		})();
+		return sender;
+	};
+	return {
+		name: WEB_PUSH,
+		async send(row, rendered, signal) {
+			const devices = await subscriptions.of(row.principalId);
+			if (devices.length === 0) return "skipped";
+			const push = await senderOf();
+			const payload = payloadOf(row, rendered);
+			let sent = 0;
+			let gone = 0;
+			for (const device of devices) {
+				if (signal.aborted) break;
+				const result = await push.send(device, payload);
+				if (result === "sent") {
+					sent += 1;
+					await subscriptions.delivered(device.endpoint);
+				} else if (result === "gone") {
+					gone += 1;
+					await subscriptions.forget(device.endpoint);
+				} else await subscriptions.failed(device.endpoint);
+			}
+			if (sent > 0) return "sent";
+			return gone === devices.length ? "gone" : "failed";
+		},
+	};
+}

package/src/push-sender/index.ts

@@ -0,0 +1,14 @@
+// The entry `pi-roundtable-web/push-sender`: the process that signs and sends the web app's pushes
+// when the app holds no VAPID key (`push.sender: { external }`). The app queues each push as a row
+// in `web_push_outbox`; this empties it through transports (Web Push here, a host's own beside it).
+
+export type { PushTransport } from "../push/drain.ts";
+export type { DeliveryResult, OutboxKind, OutboxRow } from "../push/outbox.ts";
+export { WEB_PUSH, webPushTransport } from "../push/web-push-transport.ts";
+export type { PushSenderOptions } from "./run.ts";
+export { runPushSender } from "./run.ts";
+export {
+	SESSION_COOKIE,
+	webSessionClaims,
+	webSessionPrincipal,
+} from "./session.ts";

package/src/push-sender/run.ts

@@ -0,0 +1,118 @@
+import type { Server, SQL } from "bun";
+import type { Logger } from "pi-roundtable";
+import { ConsoleHttpError, json } from "../http.ts";
+import { DeviceRoutes } from "../push/api.ts";
+import { OutboxSender, type PushTransport } from "../push/drain.ts";
+import { EndpointPolicy } from "../push/endpoint.ts";
+import { type OutboxRow, PushOutbox } from "../push/outbox.ts";
+import { PushSubscriptions } from "../push/subscriptions.ts";
+
+export interface PushSenderOptions {
+	/**
+	 * The sender's own database role. It needs to SELECT the outbox, subscriptions, sessions and
+	 * principals, UPDATE the outbox, and INSERT deliveries and subscriptions.
+	 */
+	database: SQL;
+	/** Tried in order for each row until one says `sent`; a row's `via` narrows them. */
+	transports: readonly PushTransport[];
+	/** Words a row; with `push.content: "none"` the row carries no text, so this is where it comes from. */
+	render(row: OutboxRow): { title: string; body?: string };
+	/** Serves the subscription routes at `path`, for `push.sender.external.subscribePath`. */
+	subscribe?: {
+		listener: { port: number; hostname?: string } | { socketPath: string };
+		/** The path the page posts devices to, such as `/push/subscriptions`. */
+		path: string;
+		/** Every request that is not a GET must carry exactly this `Origin`: the console's. */
+		origin: string;
+		/** The principal behind the request's session cookie, or undefined (use `webSessionPrincipal`). */
+		authenticate(request: Request): Promise<string | undefined>;
+		/** Push services besides the browsers' own, as `push.endpointHosts` writes them. */
+		endpointHosts?: readonly string[];
+	};
+	logger: Logger;
+	/** How often the outbox is looked at; default 1 s. */
+	intervalMs?: number;
+}
+
+/**
+ * Runs the process that signs and sends the app's pushes when the app holds no key
+ * (`push.sender.external`). It empties the outbox through the transports and, when asked, serves
+ * the subscription routes with the app's session cookie and the console's `Origin`.
+ */
+export function runPushSender(options: PushSenderOptions): {
+	stop(): Promise<void>;
+	/** Takes and sends what is queued now, for a test; returns how many rows it finished. */
+	drain(): Promise<number>;
+	/** The port the subscription routes listen on, when they are served over TCP. */
+	port?: number;
+} {
+	const sender = new OutboxSender({
+		outbox: new PushOutbox(options.database),
+		transports: options.transports,
+		render: options.render,
+		logger: options.logger,
+		...(options.intervalMs ? { intervalMs: options.intervalMs } : {}),
+	});
+	sender.start();
+	const server = options.subscribe ? serve(options) : undefined;
+	return {
+		stop: async () => {
+			await server?.stop(true);
+			await sender.stop();
+		},
+		drain: () => sender.drain(),
+		...(server?.port ? { port: server.port } : {}),
+	};
+}
+
+function serve(options: PushSenderOptions): Server<undefined> {
+	const { subscribe, logger } = options;
+	if (!subscribe) throw new Error("no subscribe options");
+	const devices = new DeviceRoutes({
+		policy: new EndpointPolicy(subscribe.endpointHosts),
+		subscriptions: new PushSubscriptions(options.database),
+		enabled: true,
+	});
+	const base = subscribe.path.replace(/\/$/, "");
+	return Bun.serve({
+		...("socketPath" in subscribe.listener
+			? { unix: subscribe.listener.socketPath }
+			: {
+					port: subscribe.listener.port,
+					hostname: subscribe.listener.hostname ?? "127.0.0.1",
+				}),
+		fetch: async (request) => {
+			const path = URL.parse(request.url)?.pathname ?? "";
+			if (path !== base && !path.startsWith(`${base}/`))
+				return new Response("Not Found", { status: 404 });
+			let id: string | undefined;
+			try {
+				id =
+					path === base
+						? undefined
+						: decodeURIComponent(path.slice(base.length + 1));
+			} catch {
+				return json({ error: "There is no such device." }, 404);
+			}
+			// A page on a sibling host of the same site carries the cookie too; the Origin is what stops it.
+			if (
+				request.method !== "GET" &&
+				request.headers.get("origin") !== subscribe.origin
+			)
+				return json({ error: "The request did not come from the app." }, 403);
+			try {
+				const principalId = await subscribe.authenticate(request);
+				if (!principalId) return json({ error: "Sign in again." }, 401);
+				return await devices.handle(request, id, principalId);
+			} catch (error) {
+				if (error instanceof ConsoleHttpError)
+					return json({ error: error.message }, error.status);
+				logger.error({ err: error }, "a subscription request failed");
+				return json(
+					{ error: "The sender could not complete the request." },
+					500,
+				);
+			}
+		},
+	});
+}

package/src/push-sender/session.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import type { SQL } from "bun";
+import { WebSessions } from "../auth/sessions.ts";
+
+/** The session cookie the app sets: `__Secure-` because the console is never served at the root. */
+export const SESSION_COOKIE = "__Secure-rt_session";
+
+const cookieValue = (
+	header: string | null,
+	name: string,
+): string | undefined => {
+	for (const part of (header ?? "").split(";")) {
+		const at = part.indexOf("=");
+		if (at > 0 && part.slice(0, at).trim() === name)
+			return part.slice(at + 1).trim();
+	}
+	return undefined;
+};
+
+/**
+ * Looks the app's session cookie up in `web_sessions` (read only) and answers the principal it
+ * belongs to, or undefined for a cookie that names no session, a session past its limit, or a
+ * principal that is disabled. The cookie holds a random id; only its SHA-256 is stored.
+ */
+export function webSessionPrincipal(options: {
+	database: SQL;
+	/** The cookie's name; default the app's own. */
+	cookieName?: string;
+}): (request: Request) => Promise<string | undefined> {
+	const name = options.cookieName ?? SESSION_COOKIE;
+	return async (request) => {
+		const token = cookieValue(request.headers.get("cookie"), name);
+		if (!token) return undefined;
+		const [found]: { principal_id: string }[] = await options.database`
+			SELECT s.principal_id FROM web_sessions s
+			JOIN principals p ON p.id = s.principal_id
+			WHERE s.id_hash = ${createHash("sha256").update(token).digest()}
+				AND s.expires_at > now() AND p.disabled_at IS NULL`;
+		return found?.principal_id;
+	};
+}
+
+/**
+ * The id_token claims `oidc.storeClaims` kept for a person, from their newest live session;
+ * undefined when they have no live session or kept no claims. For a sender that needs, say, the
+ * person's mailbox address. Claims are the host's own data: never log them.
+ */
+export function webSessionClaims(
+	database: SQL,
+	principalId: string,
+): Promise<Readonly<Record<string, unknown>> | undefined> {
+	// The idle limit only matters for creating a session; reading one does not use it.
+	return new WebSessions(database, { days: 30 }).claimsOf(principalId);
+}

package/src/visitors.ts

@@ -1,13 +1,24 @@
 import type {
 	ActorFacts,
+	ChannelKey,
 	IdentityService,
 	Logger,
 	Principal,
+	Tier,
 } from "pi-roundtable";
 
-/** Who a request the console admitted comes from: an owner's principal. */
+/**
+ * Who a request the console admitted comes from: the principal, the tier they hold on this
+ * request (read again for every request and every socket frame, never carried over from the
+ * sign-in), the identity they spoke as, and the roles their sign-in carried.
+ */
 export interface Visitor {
 	principal: Principal;
+	tier: Tier;
+	/** The identity they spoke as, `<provider>:<subject>`; the principal's id when the credential names none. */
+	speakerId: string;
+	/** The roles the sign-in carried, each `<surface>:role:<name>`. */
+	roles: readonly string[];
 }
 
 /** The visitor of a request, or why it is refused, for the operator's log. */
@@ -19,6 +30,12 @@ export type ConsoleIdentity = Pick<
 	"principalOf" | "principal" | "tierOf" | "owners"
 >;
 
+/** The reads (and the one first-contact write) of `IDENTITY` that admitting members uses. */
+export type AccessIdentity = Pick<
+	IdentityService,
+	"principalOf" | "principal" | "peek" | "resolve"
+>;
+
 export interface VisitorOptions {
 	/** Whom a request from a verifier that reports no actor stands for; default the primary owner. */
 	ownerId?: string;
@@ -50,13 +67,24 @@ export function consoleVisitors(
 		logger.warn(`web-console: ${message}`);
 	};
 
-	const owner = async (id: string): Promise<Identified> => {
+	const owner = async (
+		id: string,
+		actor: ActorFacts | undefined,
+	): Promise<Identified> => {
 		const principal = await identity.principal(id);
 		if (!principal) return { refusal: `there is no principal ${id}` };
 		if (principal.disabled) return { refusal: `principal ${id} is disabled` };
-		if ((await identity.tierOf(id)) !== "owner")
+		const tier = await identity.tierOf(id);
+		if (tier !== "owner")
 			return { refusal: `principal ${id} holds no owner role` };
-		return { visitor: { principal } };
+		return {
+			visitor: {
+				principal,
+				tier,
+				speakerId: actor ? `${actor.provider}:${actor.subject}` : id,
+				roles: actor?.roles ?? [],
+			},
+		};
 	};
 
 	return async (actor) => {
@@ -68,7 +96,7 @@ export function consoleVisitors(
 			const id = options.ownerId ?? (await identity.owners())[0]?.id;
 			return id === undefined
 				? { refusal: "the host has no owner" }
-				: owner(id);
+				: owner(id, undefined);
 		}
 		const named = `${actor.provider}:${actor.subject}`;
 		if (actor.provider === LEGACY_PROVIDER)
@@ -79,7 +107,7 @@ export function consoleVisitors(
 		} catch {
 			return { refusal: "the verifier's actor is no identity" };
 		}
-		if (id !== undefined) return owner(id);
+		if (id !== undefined) return owner(id, actor);
 		warnOnce(
 			named,
 			`${named} is linked to no principal, so the console refuses it. If it is an owner's, add "${named}" to that owner's access.owners[].identities, or run: roundtable principal link <owner's principal id> ${named}`,
@@ -87,3 +115,63 @@ export function consoleVisitors(
 		return { refusal: `${named} is linked to no principal` };
 	};
 }
+
+export interface AccessOptions {
+	/** The app's surface, such as `app`: the surface the facts name and the conversation `<surface>:session` the tier is read for. */
+	surface: string;
+	logger: Logger;
+}
+
+/**
+ * Identifies the person behind each request when the app admits everyone `IDENTITY` admits on its
+ * surface (`admission: "access"`). The credential must name a person: one shared actor names no
+ * one. The facts are the app's (`surface`, `partial`, and the roles the sign-in carried), so a
+ * sign-in shows less than a person may hold and never lowers a tier recorded elsewhere.
+ *
+ * A linked identity is only read (`peek`): a request writes nothing. An unlinked one goes through
+ * `resolve`, which admits it as a new principal where `access.provisioning` says so for the
+ * surface. A disabled principal, and a person the rules give no tier, are refused.
+ */
+export function accessVisitors(
+	identity: AccessIdentity,
+	options: AccessOptions,
+): (actor: ActorFacts | undefined) => Promise<Identified> {
+	const { surface, logger } = options;
+	const scope = { conversation: `${surface}:session` as ChannelKey };
+	return async (actor) => {
+		if (!actor) return { refusal: "the credential names no one" };
+		if (actor.provider === LEGACY_PROVIDER)
+			return { refusal: "a 0.8 id is not an identity" };
+		const named = `${actor.provider}:${actor.subject}`;
+		const facts: ActorFacts = { ...actor, surface, partial: true };
+		let linked: string | undefined;
+		try {
+			linked = await identity.principalOf(named);
+		} catch {
+			return { refusal: "the credential's actor is no identity" };
+		}
+		const speaker =
+			linked === undefined
+				? await identity.resolve(facts, scope)
+				: await identity.peek(facts, scope);
+		if (!speaker) {
+			logger.debug(
+				{ linked: linked !== undefined },
+				"web-console: the access rules serve no one by this sign-in",
+			);
+			return { refusal: `${named} holds no tier on this surface` };
+		}
+		const principal = await identity.principal(speaker.principalId);
+		if (!principal) return { refusal: "the principal is gone" };
+		if (principal.disabled)
+			return { refusal: `principal ${principal.id} is disabled` };
+		return {
+			visitor: {
+				principal,
+				tier: speaker.tier,
+				speakerId: named,
+				roles: actor.roles ?? [],
+			},
+		};
+	};
+}