pi-roundtable-web 0.22.4 → 0.23.0

package/src/push/channel.ts

@@ -0,0 +1,50 @@
+import {
+	type ChannelKey,
+	type DirectChannelProvider,
+	type IdentityService,
+	PluginError,
+} from "pi-roundtable";
+import type { PushService } from "./triggers.ts";
+
+export interface WebPushChannelOptions {
+	/** The key prefix of the app's rooms, which names the provider. */
+	surface: string;
+	identity: Pick<IdentityService, "tierOf">;
+	/** The room a notice to a person lands in: the home room; undefined when the team has none. */
+	home(): ChannelKey | undefined;
+	/** Writes a line the person will find in the room. */
+	post(room: ChannelKey, text: string): Promise<void>;
+	push: Pick<PushService, "notice">;
+}
+
+/**
+ * The owner app as a way to reach an owner. A notice to them is written as a line in the home
+ * room and pushed to their devices; one that another channel (such as a Discord direct message)
+ * delivered is only pushed, so the phone hears it too.
+ */
+export function webPushChannel(
+	options: WebPushChannelOptions,
+): DirectChannelProvider {
+	const { identity, home, post, push } = options;
+	const isOwner = async (principalId: string) =>
+		(await identity.tierOf(principalId)) === "owner";
+	return {
+		name: `web:${options.surface}`,
+		label: "a notice in the web app",
+		knows: async (principalId) =>
+			(await isOwner(principalId)) && home() !== undefined,
+		reaches: async (principalId) =>
+			(await isOwner(principalId)) ? home() : undefined,
+		deliver: async (principalId, text) => {
+			const room = home();
+			if (!room || !(await isOwner(principalId)))
+				throw new PluginError("the web app has no room to post this notice in");
+			await post(room, text);
+			await push.notice(principalId, text, room);
+		},
+		mirror: async (principalId, text) => {
+			const room = home();
+			await push.notice(principalId, text, room);
+		},
+	};
+}

package/src/push/encrypt.ts

@@ -0,0 +1,136 @@
+/** The size of the one record a message is sealed in (RFC 8188 `rs`). */
+const RECORD_SIZE = 4096;
+/** The header before the ciphertext: salt (16), record size (4), key id length (1), server key (65). */
+const HEADER_BYTES = 86;
+/** The AES-GCM tag and the padding delimiter. */
+const OVERHEAD = 16 + 1;
+/** The most plaintext bytes one record holds. */
+const MAX_PAYLOAD_BYTES = RECORD_SIZE - HEADER_BYTES - OVERHEAD;
+
+const ECDH = { name: "ECDH", namedCurve: "P-256" } as const;
+const text = new TextEncoder();
+
+/** A byte array WebCrypto accepts. */
+export type Bytes = Uint8Array<ArrayBuffer>;
+
+/** The keys of a receiver's push subscription, decoded. */
+export interface ReceiverKeys {
+	/** The browser's public key: an uncompressed P-256 point, 65 bytes. */
+	p256dh: Bytes;
+	/** The browser's 16-byte authentication secret. */
+	auth: Bytes;
+}
+
+/** The sender's ephemeral key pair for one message. */
+export interface ServerKey {
+	privateKey: CryptoKey;
+	/** The uncompressed point, 65 bytes. */
+	publicKey: Bytes;
+}
+
+export interface SealInput {
+	payload: Bytes;
+	userPublic: Bytes;
+	authSecret: Bytes;
+	salt: Bytes;
+	server: ServerKey;
+}
+
+async function hkdf(
+	secret: ArrayBuffer | Bytes,
+	salt: Bytes,
+	info: Bytes,
+	bits: number,
+): Promise<Bytes> {
+	const key = await crypto.subtle.importKey("raw", secret, "HKDF", false, [
+		"deriveBits",
+	]);
+	return new Uint8Array(
+		await crypto.subtle.deriveBits(
+			{ name: "HKDF", hash: "SHA-256", salt, info },
+			key,
+			bits,
+		),
+	);
+}
+
+/**
+ * Seals a payload as RFC 8291 describes for Web Push: ECDH with the browser's key, the
+ * authentication secret and the two public keys combined into the input keying material, then one
+ * `aes128gcm` record (RFC 8188) whose header carries the salt and the sender's public key.
+ */
+export async function aes128gcm(input: SealInput): Promise<Bytes> {
+	const { payload, userPublic, authSecret, salt, server } = input;
+	if (payload.byteLength > MAX_PAYLOAD_BYTES)
+		throw new RangeError(
+			`the push payload is too large: ${payload.byteLength} bytes, at most ${MAX_PAYLOAD_BYTES}`,
+		);
+	const receiver = await crypto.subtle.importKey(
+		"raw",
+		userPublic,
+		ECDH,
+		false,
+		[],
+	);
+	const shared = await crypto.subtle.deriveBits(
+		{ name: "ECDH", public: receiver },
+		server.privateKey,
+		256,
+	);
+	const keyInfo = new Uint8Array([
+		...text.encode("WebPush: info\0"),
+		...userPublic,
+		...server.publicKey,
+	]);
+	const ikm = await hkdf(shared, authSecret, keyInfo, 256);
+	const cek = await hkdf(
+		ikm,
+		salt,
+		text.encode("Content-Encoding: aes128gcm\0"),
+		128,
+	);
+	const nonce = await hkdf(
+		ikm,
+		salt,
+		text.encode("Content-Encoding: nonce\0"),
+		96,
+	);
+	// The last (here only) record ends with the delimiter 0x02.
+	const record = new Uint8Array(payload.byteLength + 1);
+	record.set(payload);
+	record[payload.byteLength] = 2;
+	const sealed = new Uint8Array(
+		await crypto.subtle.encrypt(
+			{ name: "AES-GCM", iv: nonce },
+			await crypto.subtle.importKey("raw", cek, "AES-GCM", false, ["encrypt"]),
+			record,
+		),
+	);
+	const body = new Uint8Array(HEADER_BYTES + sealed.byteLength);
+	body.set(salt, 0);
+	new DataView(body.buffer).setUint32(16, RECORD_SIZE);
+	body[20] = server.publicKey.byteLength;
+	body.set(server.publicKey, 21);
+	body.set(sealed, HEADER_BYTES);
+	return body;
+}
+
+/** Seals a payload for a subscription with a random salt and a key pair made for this message alone. */
+export async function encryptPayload(
+	payload: Bytes,
+	receiver: ReceiverKeys,
+): Promise<Bytes> {
+	const pair = await crypto.subtle.generateKey(ECDH, false, ["deriveBits"]);
+	return aes128gcm({
+		payload,
+		userPublic: receiver.p256dh,
+		authSecret: receiver.auth,
+		salt: crypto.getRandomValues(new Uint8Array(16)),
+		server: {
+			privateKey: pair.privateKey,
+			publicKey: new Uint8Array(
+				await crypto.subtle.exportKey("raw", pair.publicKey),
+			),
+		},
+	});
+}

package/src/push/endpoint.ts

@@ -0,0 +1,54 @@
+/** The push services of the browsers that support Web Push; `push.endpointHosts` adds to them. */
+const PUSH_HOSTS: readonly string[] = [
+	"fcm.googleapis.com",
+	"updates.push.services.mozilla.com",
+	"*.push.apple.com",
+	"*.notify.windows.com",
+];
+
+/** A host name as `push.endpointHosts` writes it: lower-case labels, with `*.` first to mean any subdomain. */
+const HOST_PATTERN = /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+
+export function isHostPattern(value: string): boolean {
+	return HOST_PATTERN.test(value);
+}
+
+/**
+ * Which push-service endpoints the server posts to. A subscription's endpoint is a URL the
+ * browser hands over, so without this check any owner session could make the host fetch any
+ * address: the endpoint must be `https` on the default port, with no credentials, and its host
+ * must be one of the allowed.
+ */
+export class EndpointPolicy {
+	readonly #exact = new Set<string>();
+	readonly #suffixes: string[] = [];
+
+	constructor(extra: readonly string[] = []) {
+		for (const host of [...PUSH_HOSTS, ...extra]) {
+			if (host.startsWith("*.")) this.#suffixes.push(host.slice(1));
+			else this.#exact.add(host);
+		}
+	}
+
+	/** The endpoint as a URL, or why it is refused. */
+	check(endpoint: unknown): { url: URL } | { refusal: string } {
+		if (typeof endpoint !== "string" || endpoint.length > 2048)
+			return { refusal: "The push endpoint is not a URL." };
+		const url = URL.parse(endpoint);
+		if (!url) return { refusal: "The push endpoint is not a URL." };
+		if (url.protocol !== "https:")
+			return { refusal: "The push endpoint must be https." };
+		if (url.username || url.password || url.port || url.hash)
+			return {
+				refusal:
+					"The push endpoint must have no credentials, port or fragment.",
+			};
+		const host = url.hostname;
+		if (
+			!this.#exact.has(host) &&
+			!this.#suffixes.some((suffix) => host.endsWith(suffix))
+		)
+			return { refusal: "That push service is not allowed." };
+		return { url };
+	}
+}

package/src/push/sender.ts

@@ -0,0 +1,109 @@
+import type { Logger } from "pi-roundtable";
+import { encryptPayload } from "./encrypt.ts";
+import type { EndpointPolicy } from "./endpoint.ts";
+import { type Vapid, vapidAuthorization } from "./vapid.ts";
+
+/** How long a push service keeps a message for a device that is off: a day. */
+const TTL_SECONDS = 86_400;
+/** How long one post may take. */
+const SEND_TIMEOUT_MS = 10_000;
+
+/** What a notification carries. Everything here is sealed; the push service sees only its size. */
+export interface PushPayload {
+	title: string;
+	body?: string;
+	/** The room the notification is about, which a tap opens. */
+	room?: string;
+	/** Where a tap goes when no page of the app is open: a path under the origin. */
+	url?: string;
+	/** Notifications with one tag replace each other on the device. */
+	tag: string;
+	kind: "card" | "cap" | "reply" | "notice";
+}
+
+/** The part of a stored subscription the sender needs. */
+export interface Target {
+	endpoint: string;
+	p256dh: string;
+	auth: string;
+}
+
+/** How a post ended: `sent`, `gone` (the service says the device unsubscribed), or `failed`. */
+export type SendResult = "sent" | "gone" | "failed";
+
+export interface PushSenderOptions {
+	vapid: Vapid;
+	/**
+	 * The `sub` of the VAPID token: a `mailto:` or `https:` contact for the push service. Without
+	 * one nothing is posted.
+	 */
+	subject: string | undefined;
+	policy: EndpointPolicy;
+	/** The HTTP client; default `fetch`. */
+	fetch?: typeof fetch;
+	logger: Logger;
+}
+
+/** Posts sealed notifications to the push services (RFC 8030) under the server's VAPID identity (RFC 8292). */
+export class PushSender {
+	readonly #options: PushSenderOptions;
+
+	constructor(options: PushSenderOptions) {
+		this.#options = options;
+	}
+
+	async send(target: Target, payload: PushPayload): Promise<SendResult> {
+		const { vapid, subject, policy, logger } = this.#options;
+		if (subject === undefined) return "failed";
+		// Checked again at the post: the allowlist may have changed since the device subscribed.
+		const checked = policy.check(target.endpoint);
+		if ("refusal" in checked) {
+			logger.warn(
+				{ reason: checked.refusal },
+				"a stored push endpoint is not allowed",
+			);
+			return "gone";
+		}
+		try {
+			const body = await encryptPayload(
+				new TextEncoder().encode(JSON.stringify(payload)),
+				{
+					p256dh: Buffer.from(target.p256dh, "base64url"),
+					auth: Buffer.from(target.auth, "base64url"),
+				},
+			);
+			const response = await (this.#options.fetch ?? fetch)(checked.url, {
+				method: "POST",
+				headers: {
+					authorization: await vapidAuthorization(
+						vapid,
+						target.endpoint,
+						subject,
+					),
+					"content-encoding": "aes128gcm",
+					"content-type": "application/octet-stream",
+					ttl: String(TTL_SECONDS),
+					urgency: payload.kind === "reply" ? "normal" : "high",
+				},
+				body,
+				// A push service never redirects; a redirect would walk past the allowlist.
+				redirect: "manual",
+				signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+			});
+			await response.body?.cancel();
+			if (response.status >= 200 && response.status < 300) return "sent";
+			if (response.status === 404 || response.status === 410) return "gone";
+			logger.warn(
+				{ status: response.status, host: checked.url.host },
+				"a push service refused a message",
+			);
+			return "failed";
+		} catch (error) {
+			logger.warn(
+				{ err: error, host: checked.url.host },
+				"a push could not be sent",
+			);
+			return "failed";
+		}
+	}
+}

package/src/push/subscriptions.ts

@@ -0,0 +1,140 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+
+/** A device's push subscription: where to post and the keys to seal the message with. */
+export interface Subscription {
+	endpoint: string;
+	principalId: string;
+	/** The browser's public key, base64url. */
+	p256dh: string;
+	/** The browser's authentication secret, base64url. */
+	auth: string;
+	label?: string;
+	createdAt: Date;
+	lastOkAt?: Date;
+}
+
+interface Row {
+	endpoint: string;
+	principal_id: string;
+	p256dh: string;
+	auth: string;
+	label: string | null;
+	created_at: Date;
+	last_ok_at: Date | null;
+}
+
+/** Failures in a row after which a subscription is dropped. */
+export const MAX_FAILURES = 5;
+
+const subscriptionOf = (row: Row): Subscription => ({
+	endpoint: row.endpoint,
+	principalId: row.principal_id,
+	p256dh: row.p256dh,
+	auth: row.auth,
+	...(row.label === null ? {} : { label: row.label }),
+	createdAt: row.created_at,
+	...(row.last_ok_at === null ? {} : { lastOkAt: row.last_ok_at }),
+});
+
+/** The devices that asked for push, one row per browser endpoint, in `web_push_subscriptions`. */
+export class PushSubscriptions {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	static readonly migration: Migration = {
+		name: "web-push-subscriptions",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_push_subscriptions (
+					endpoint text PRIMARY KEY,
+					principal_id text NOT NULL,
+					p256dh text NOT NULL,
+					auth text NOT NULL,
+					label text,
+					created_at timestamptz NOT NULL DEFAULT now(),
+					last_ok_at timestamptz,
+					failures integer NOT NULL DEFAULT 0
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_push_subscriptions_principal ON web_push_subscriptions (principal_id)`;
+		},
+	};
+
+	/**
+	 * Stores a device's subscription; a browser that subscribes again replaces its row and starts
+	 * clean. An endpoint that is another person's is refused (`"taken"`), and a person who already
+	 * has `cap` other devices is refused (`"full"`); the count and the insert share one lock.
+	 */
+	async save(
+		subscription: Omit<Subscription, "createdAt" | "lastOkAt">,
+		cap = Number.POSITIVE_INFINITY,
+	): Promise<"saved" | "taken" | "full"> {
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${`web-push:${subscription.principalId}`}, 0))`;
+			const [counted]: { n: number }[] = await tx`
+				SELECT count(*)::int AS n FROM web_push_subscriptions
+				WHERE principal_id = ${subscription.principalId} AND endpoint <> ${subscription.endpoint}`;
+			if ((counted?.n ?? 0) >= cap) return "full";
+			const rows: unknown[] = await tx`
+				INSERT INTO web_push_subscriptions (endpoint, principal_id, p256dh, auth, label)
+				VALUES (${subscription.endpoint}, ${subscription.principalId}, ${subscription.p256dh},
+					${subscription.auth}, ${subscription.label ?? null})
+				ON CONFLICT (endpoint) DO UPDATE SET
+					p256dh = EXCLUDED.p256dh, auth = EXCLUDED.auth,
+					label = EXCLUDED.label, failures = 0
+				WHERE web_push_subscriptions.principal_id = EXCLUDED.principal_id
+				RETURNING endpoint`;
+			return rows.length > 0 ? "saved" : "taken";
+		});
+	}
+
+	/** Every device, oldest first. */
+	async all(): Promise<Subscription[]> {
+		const rows: Row[] = await this
+			.#sql`SELECT * FROM web_push_subscriptions ORDER BY created_at, endpoint`;
+		return rows.map(subscriptionOf);
+	}
+
+	/** One person's devices, oldest first. */
+	async of(principalId: string): Promise<Subscription[]> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM web_push_subscriptions WHERE principal_id = ${principalId}
+			ORDER BY created_at, endpoint`;
+		return rows.map(subscriptionOf);
+	}
+
+	/** Drops a person's device; false when they have no such one. */
+	async remove(endpoint: string, principalId: string): Promise<boolean> {
+		const rows: unknown[] = await this.#sql`
+			DELETE FROM web_push_subscriptions
+			WHERE endpoint = ${endpoint} AND principal_id = ${principalId} RETURNING endpoint`;
+		return rows.length > 0;
+	}
+
+	/** Drops a device the push service says is gone. */
+	async forget(endpoint: string): Promise<void> {
+		await this
+			.#sql`DELETE FROM web_push_subscriptions WHERE endpoint = ${endpoint}`;
+	}
+
+	/** Notes that a push was accepted. */
+	async delivered(endpoint: string): Promise<void> {
+		await this
+			.#sql`UPDATE web_push_subscriptions SET failures = 0, last_ok_at = now() WHERE endpoint = ${endpoint}`;
+	}
+
+	/** Notes a failed push; the fifth failure in a row drops the device. Returns whether it was dropped. */
+	async failed(endpoint: string): Promise<boolean> {
+		const rows: unknown[] = await this.#sql`
+			DELETE FROM web_push_subscriptions
+			WHERE endpoint = ${endpoint}
+				AND failures + 1 >= ${MAX_FAILURES} RETURNING endpoint`;
+		if (rows.length > 0) return true;
+		await this
+			.#sql`UPDATE web_push_subscriptions SET failures = failures + 1 WHERE endpoint = ${endpoint}`;
+		return false;
+	}
+}

package/src/push/test-fetch.ts

@@ -0,0 +1,17 @@
+/**
+ * The HTTP client the push posts go through, set per options object by tests only: it is kept out
+ * of the public options so a deployment cannot send pushes anywhere but through `fetch`.
+ */
+const fetches = new WeakMap<object, typeof fetch>();
+
+/** Makes the options post through `fetch`; returns the same object. */
+export function withPushFetch<T extends object>(
+	options: T,
+	client: typeof fetch,
+): T {
+	fetches.set(options, client);
+	return options;
+}
+
+export const pushFetchOf = (options: object): typeof fetch | undefined =>
+	fetches.get(options);

package/src/push/triggers.ts

@@ -0,0 +1,155 @@
+import type { IdentityService, Logger } from "pi-roundtable";
+import type { PushPayload, PushSender, SendResult } from "./sender.ts";
+import type { PushSubscriptions, Subscription } from "./subscriptions.ts";
+
+/** The most characters of a message a notification shows. */
+export const PREVIEW_CHARS = 120;
+/** Replies in one room closer together than this share a notification. */
+const REPLY_QUIET_MS = 15_000;
+
+export interface PushServiceOptions {
+	subscriptions: Pick<
+		PushSubscriptions,
+		"all" | "delivered" | "forget" | "failed"
+	>;
+	sender: Pick<PushSender, "send">;
+	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;
+	/** Whether a notification shows the start of the message; false sends titles only. */
+	preview: boolean;
+	/** The path a tap on a room's notification opens, under the origin. */
+	urlOf(room: string): string;
+	logger: Logger;
+	/** The clock, in milliseconds; default `Date.now`. */
+	now?: () => number;
+}
+
+/** What a trigger says; the service shapes it into a notification. */
+interface Event {
+	kind: PushPayload["kind"];
+	title: string;
+	/** The text a notification shows when previews are on. */
+	text?: string;
+	room?: string;
+	tag: string;
+	/** Only this person's devices; default every owner's. */
+	principalId?: string;
+}
+
+/** The start of a message, on one line and cut at `PREVIEW_CHARS`. */
+export function previewOf(text: string): string {
+	const flat = text.replaceAll(/\s+/g, " ").trim();
+	const letters = Array.from(flat);
+	return letters.length > PREVIEW_CHARS
+		? `${letters.slice(0, PREVIEW_CHARS).join("")}…`
+		: flat;
+}
+
+/**
+ * Decides when an owner's devices are pushed and what is said. Each trigger pushes only while no
+ * page of an owner is in view, and only to owners: a device whose person is no owner any more is
+ * skipped. Delivery never throws into the code that raised the trigger.
+ */
+export class PushService {
+	readonly #options: PushServiceOptions;
+	readonly #repliedAt = new Map<string, number>();
+
+	constructor(options: PushServiceOptions) {
+		this.#options = options;
+	}
+
+	/** A card opened in a room: an approval or a question waits for an owner. */
+	card(room: string, title: string, longRunningCap: boolean): Promise<void> {
+		return this.#push({
+			kind: longRunningCap ? "cap" : "card",
+			title: longRunningCap ? "Long-running cap reached" : "Card waiting",
+			text: title,
+			room,
+			tag: room,
+		});
+	}
+
+	/** An agent posted in a room, such as a finished job's report or an answer nobody was watching for. */
+	reply(room: string, author: string, text: string): Promise<void> {
+		const now = (this.#options.now ?? Date.now)();
+		const last = this.#repliedAt.get(room);
+		if (last !== undefined && now - last < REPLY_QUIET_MS)
+			return Promise.resolve();
+		this.#repliedAt.set(room, now);
+		return this.#push({
+			kind: "reply",
+			title: this.#options.preview ? author : "New reply",
+			text,
+			room,
+			tag: room,
+		});
+	}
+
+	/** A notice for one person, from the `notify` tool. */
+	notice(principalId: string, text: string, room?: string): Promise<void> {
+		return this.#push({
+			kind: "notice",
+			title: "Notice",
+			text,
+			...(room ? { room } : {}),
+			tag: room ?? "notice",
+			principalId,
+		});
+	}
+
+	async #push(event: Event): Promise<void> {
+		const { logger, preview } = this.#options;
+		try {
+			const payload: PushPayload = {
+				kind: event.kind,
+				title: event.title,
+				tag: event.tag,
+				...(event.room
+					? { room: event.room, url: this.#options.urlOf(event.room) }
+					: {}),
+				...(preview && event.text ? { body: previewOf(event.text) } : {}),
+			};
+			const targets = await this.#targets(event.principalId);
+			await Promise.all(
+				targets.map(async (target) =>
+					this.#settle(
+						target,
+						await this.#options.sender.send(target, payload),
+					),
+				),
+			);
+		} catch (error) {
+			logger.warn({ err: error, kind: event.kind }, "a push was not sent");
+		}
+	}
+
+	async #targets(principalId?: string): Promise<Subscription[]> {
+		const owners = new Map<string, boolean>();
+		const isOwner = async (id: string): Promise<boolean> => {
+			const known = owners.get(id);
+			if (known !== undefined) return known;
+			const owner = (await this.#options.identity.tierOf(id)) === "owner";
+			owners.set(id, owner);
+			return owner;
+		};
+		const all = await this.#options.subscriptions.all();
+		const chosen: Subscription[] = [];
+		for (const subscription of all)
+			if (
+				(principalId === undefined ||
+					subscription.principalId === principalId) &&
+				!this.#options.visible(subscription.principalId) &&
+				(await isOwner(subscription.principalId))
+			)
+				chosen.push(subscription);
+		return chosen;
+	}
+
+	async #settle(target: Subscription, result: SendResult): Promise<void> {
+		const { subscriptions } = this.#options;
+		if (result === "sent") await subscriptions.delivered(target.endpoint);
+		else if (result === "gone") await subscriptions.forget(target.endpoint);
+		else await subscriptions.failed(target.endpoint);
+	}
+}