pi-roundtable-webchat 0.8.0

package/src/connections.ts

@@ -0,0 +1,99 @@
+import type { Logger, RouteSocket, Speaker } from "pi-roundtable";
+import type { WebIdentity } from "./oidc.ts";
+import type { ServerFrame } from "./protocol.ts";
+
+/** One authenticated WebSocket: who it is, at which tier, until when its token holds. */
+export interface Connection {
+	identity: WebIdentity;
+	speaker: Speaker;
+	socket?: RouteSocket<Connection>;
+	/** Asks for a fresh token, then closes the socket when the token expires. */
+	timers: ReturnType<typeof setTimeout>[];
+	/** Releases the place a refused or never-opened upgrade held. */
+	pending?: ReturnType<typeof setTimeout>;
+	/** Whether the connection holds one of its person's places. */
+	holding?: boolean;
+}
+
+/** How long an accepted upgrade may take to open before its place is released. */
+const OPEN_WITHIN_MS = 10_000;
+
+/**
+ * The open WebSocket connections, by person. Each person holds at most `perPrincipal` at once,
+ * counting the upgrades still opening, so one account cannot take every place of the route.
+ */
+export class Connections {
+	readonly #byPrincipal = new Map<string, Set<Connection>>();
+	readonly #held = new Map<string, number>();
+	readonly #perPrincipal: number;
+	readonly #logger: Logger;
+
+	constructor(options: { perPrincipal: number; logger: Logger }) {
+		this.#perPrincipal = options.perPrincipal;
+		this.#logger = options.logger;
+	}
+
+	/** Takes a place for an upgrade that is about to open; false when the person holds every place. */
+	reserve(connection: Connection): boolean {
+		const id = connection.identity.id;
+		const held = this.#held.get(id) ?? 0;
+		if (held >= this.#perPrincipal) return false;
+		this.#held.set(id, held + 1);
+		connection.holding = true;
+		connection.pending = setTimeout(
+			() => this.#release(connection),
+			OPEN_WITHIN_MS,
+		);
+		return true;
+	}
+
+	/** Counts an open socket; false when its upgrade took so long that its place was released. */
+	opened(connection: Connection, socket: RouteSocket<Connection>): boolean {
+		if (!connection.holding) return false;
+		clearTimeout(connection.pending);
+		connection.pending = undefined;
+		connection.socket = socket;
+		const id = connection.identity.id;
+		const set = this.#byPrincipal.get(id) ?? new Set();
+		set.add(connection);
+		this.#byPrincipal.set(id, set);
+		return true;
+	}
+
+	closed(connection: Connection): void {
+		for (const timer of connection.timers) clearTimeout(timer);
+		connection.timers = [];
+		const id = connection.identity.id;
+		const set = this.#byPrincipal.get(id);
+		set?.delete(connection);
+		if (set?.size === 0) this.#byPrincipal.delete(id);
+		this.#release(connection);
+	}
+
+	#release(connection: Connection): void {
+		clearTimeout(connection.pending);
+		connection.pending = undefined;
+		if (!connection.holding) return;
+		connection.holding = false;
+		const id = connection.identity.id;
+		const held = (this.#held.get(id) ?? 1) - 1;
+		if (held > 0) this.#held.set(id, held);
+		else this.#held.delete(id);
+	}
+
+	/** Sends a frame on one connection; a dropped send is logged, never thrown. */
+	send(connection: Connection, frame: ServerFrame): void {
+		const result = connection.socket?.send(JSON.stringify(frame));
+		if (result === "dropped")
+			this.#logger.warn(
+				{ frame: frame.type },
+				"a web chat frame was dropped; the connection is closed",
+			);
+	}
+
+	/** Sends a frame to every connection of a person; none open is not an error. */
+	sendTo(principal: string, frame: ServerFrame): void {
+		for (const connection of this.#byPrincipal.get(principal) ?? [])
+			this.send(connection, frame);
+	}
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export type { WebAccess, WebAccessMap, WebTierMembers } from "./access.ts";
+export { webAccess } from "./access.ts";
+export type { WebChatLimits, WebPersona } from "./chat.ts";
+export type {
+	OidcJwtVerifierOptions,
+	TokenVerifier,
+	WebIdentity,
+} from "./oidc.ts";
+export {
+	oidcJwtVerifier,
+	oidcSpeakerId,
+	parseOidcSpeakerId,
+	TokenRefused,
+} from "./oidc.ts";
+export type { WebChatOptions, WebChatRouteLimits } from "./plugin.ts";
+export { webChat } from "./plugin.ts";
+export type {
+	ClientFrame,
+	ErrorCode,
+	PersonaSummary,
+	PromptFrame,
+	PromptOutcome,
+	ReplyFileFrame,
+	ServerFrame,
+} from "./protocol.ts";
+export {
+	CLOSE_CODES,
+	parseClientFrame,
+	TICKET_PROTOCOL_PREFIX,
+	WEBCHAT_PROTOCOL,
+	WEBCHAT_PROTOCOL_VERSION,
+} from "./protocol.ts";

package/src/oidc.ts

@@ -0,0 +1,237 @@
+import {
+	createRemoteJWKSet,
+	type JWSAlgorithm,
+	type JWTPayload,
+	type JWTVerifyGetKey,
+	jwtVerify,
+} from "jose";
+
+/** Who a verified token names, and until when it may be trusted. */
+export interface WebIdentity {
+	/** The speaker id: reversible and unique across issuers, such as `oidc:<base64url(issuer)>:<sub>`. */
+	id: string;
+	/** How the person is shown, from the token's name claim. */
+	name: string;
+	/** The token's role or group claim; the access policy maps these to a tier. */
+	roles: readonly string[];
+	/** When the token expires; a connection asks for a fresh one before then. */
+	expiresAt: Date;
+}
+
+/**
+ * Checks one bearer token and names who it vouches for, or throws `TokenRefused`. The webchat
+ * calls it for every REST request, every WebSocket upgrade, and every `auth` frame.
+ */
+export type TokenVerifier = (token: string) => Promise<WebIdentity>;
+
+/** A token was refused; `reason` is for the operator's log, never sent to the client, and never holds the token. */
+export class TokenRefused extends Error {
+	override name = "TokenRefused";
+	readonly reason: string;
+
+	constructor(reason: string) {
+		super(`token refused: ${reason}`);
+		this.reason = reason;
+	}
+}
+
+const PREFIX = "oidc";
+
+/**
+ * The speaker id of an OpenID subject: `oidc:<base64url(issuer)>:<subject>`. The issuer is
+ * encoded so its own colons stay apart from the subject's, and the id can be turned back into the
+ * pair with `parseOidcSpeakerId`. It never looks like a Discord id.
+ */
+export function oidcSpeakerId(issuer: string, subject: string): string {
+	return `${PREFIX}:${Buffer.from(issuer).toString("base64url")}:${subject}`;
+}
+
+/** The issuer and subject of an id `oidcSpeakerId` made; undefined for any other id. */
+export function parseOidcSpeakerId(
+	id: string,
+): { issuer: string; subject: string } | undefined {
+	const match = /^oidc:([A-Za-z0-9_-]+):(.+)$/.exec(id);
+	if (!match) return undefined;
+	const [, encoded = "", subject = ""] = match;
+	const issuer = Buffer.from(encoded, "base64url").toString("utf8");
+	// A round trip that does not give the same text back was not base64url of an issuer.
+	if (Buffer.from(issuer).toString("base64url") !== encoded) return undefined;
+	return { issuer, subject };
+}
+
+export interface OidcJwtVerifierOptions {
+	/** The provider's published signing keys (`jwks_uri`): https, or http on a loopback address. */
+	jwksUrl: string;
+	/** The `iss` values accepted, exactly as the provider writes them. */
+	issuers: readonly string[];
+	/** The `aud` values accepted: the client id or application id URI of this API. */
+	audiences: readonly string[];
+	/**
+	 * The issuer speaker ids are made from. Required when `issuers` lists several issuers of one
+	 * provider (such as two token versions), so one person keeps one id whichever issued the token.
+	 */
+	speakerIssuer?: string;
+	/** The claim naming the person; default `sub`. A provider's stable object id claim may suit better. */
+	subjectClaim?: string;
+	/** The claim to show the person by; default `name`, then `preferred_username`, then the subject. */
+	nameClaim?: string;
+	/** The claim holding their roles or groups, an array of strings; default `roles`. */
+	rolesClaim?: string;
+	/** Accepted signature algorithms; default RS256 and ES256. Symmetric algorithms and `none` are refused. */
+	algorithms?: readonly string[];
+	/** How far `exp` and `nbf` may be off the local clock; default 60 seconds. */
+	clockSkewSeconds?: number;
+	/** A further check on the verified claims, such as a tenant claim; false refuses the token. */
+	check?(claims: Readonly<JWTPayload & Record<string, unknown>>): boolean;
+	/**
+	 * Refuses a token without a scope (`scp` or `scope`) or app roles (`roles`), the marks of an
+	 * access token; default true. An ID token carries no scope, so one whose `aud` happens to be
+	 * this API's client id cannot pass for an access token. Set false only for a provider whose
+	 * access tokens carry neither.
+	 */
+	requireScopeOrRoles?: boolean;
+	/**
+	 * Refuses an app-only token, one a service got for itself with no person behind it
+	 * (`idtyp: "app"`, as Microsoft Entra ID writes it); default true.
+	 */
+	rejectAppOnly?: boolean;
+	/** Replaces the JWKS fetch, for a test or a host that already holds the keys. */
+	keys?: JWTVerifyGetKey;
+	/** How long the fetched key set is reused before it is fetched again; default 10 minutes. */
+	cacheMaxAgeMs?: number;
+	/**
+	 * The least time between two fetches for a key id the cached set lacks, such as after the
+	 * provider rotated its keys; default 30 seconds, so unknown key ids cannot flood the provider.
+	 */
+	refetchCooldownMs?: number;
+}
+
+const DEFAULT_ALGORITHMS = ["RS256", "ES256"] as const;
+/** The JWS algorithms with a public key, the only kind a published key set can verify. */
+const ASYMMETRIC =
+	/^(RS(256|384|512)|PS(256|384|512)|ES(256|384|512)|ES256K|EdDSA|Ed25519)$/;
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+
+function configError(message: string): Error {
+	return new Error(`oidcJwtVerifier: ${message}`);
+}
+
+function keySource(options: OidcJwtVerifierOptions): JWTVerifyGetKey {
+	if (options.keys) return options.keys;
+	const url = URL.parse(options.jwksUrl);
+	if (!url) throw configError(`jwksUrl ${options.jwksUrl} is not a URL`);
+	if (
+		url.protocol !== "https:" &&
+		!(url.protocol === "http:" && LOOPBACK.has(url.hostname))
+	)
+		throw configError(
+			"jwksUrl must use https (http only on a loopback address), so the keys cannot be swapped in transit",
+		);
+	return createRemoteJWKSet(url, {
+		cacheMaxAge: options.cacheMaxAgeMs ?? 10 * 60_000,
+		cooldownDuration: options.refetchCooldownMs ?? 30_000,
+		timeoutDuration: 5_000,
+	});
+}
+
+function algorithmsOf(options: OidcJwtVerifierOptions): JWSAlgorithm[] {
+	const algorithms = options.algorithms ?? DEFAULT_ALGORITHMS;
+	if (algorithms.length === 0)
+		throw configError("algorithms is empty; leave it out for RS256 and ES256");
+	for (const alg of algorithms)
+		if (!ASYMMETRIC.test(alg))
+			throw configError(
+				`algorithm ${alg} cannot be verified with a published key; use an asymmetric one such as RS256 or ES256`,
+			);
+	return [...algorithms];
+}
+
+function speakerIssuerOf(options: OidcJwtVerifierOptions): string | undefined {
+	const { issuers, speakerIssuer } = options;
+	if (speakerIssuer !== undefined && !issuers.includes(speakerIssuer))
+		throw configError(
+			`speakerIssuer ${speakerIssuer} is not one of the accepted issuers`,
+		);
+	if (issuers.length > 1 && speakerIssuer === undefined)
+		throw configError(
+			"issuers lists several issuers: set speakerIssuer to the one speaker ids are made from, so one person keeps one id",
+		);
+	return speakerIssuer;
+}
+
+const text = (value: unknown): string | undefined =>
+	typeof value === "string" && value.trim() !== "" ? value : undefined;
+
+/** A claim with something in it: non-blank text, or a list with a non-blank text. */
+const filled = (value: unknown): boolean =>
+	text(value) !== undefined ||
+	(Array.isArray(value) && value.some((item) => text(item) !== undefined));
+
+/**
+ * Verifies OpenID Connect access tokens against a provider's published keys: the signature
+ * with an allowed asymmetric algorithm, `iss`, `aud`, `exp` (required), and `nbf`, within the
+ * clock skew; by default a scope or app roles (`requireScopeOrRoles`) and no app-only token
+ * (`rejectAppOnly`); then `sub` (or `subjectClaim`) and the optional `check`. The key set is fetched when
+ * first needed, cached, and fetched again for a key id it does not hold, at most every `refetchCooldownMs`.
+ * Configuration mistakes throw at construction, so a host with a broken verifier does not start.
+ */
+export function oidcJwtVerifier(
+	options: OidcJwtVerifierOptions,
+): TokenVerifier {
+	if (options.issuers.length === 0 || options.issuers.some((i) => !text(i)))
+		throw configError("issuers is empty; list the provider's iss values");
+	if (options.audiences.length === 0 || options.audiences.some((a) => !text(a)))
+		throw configError("audiences is empty; list this API's aud values");
+	const keys = keySource(options);
+	const algorithms = algorithmsOf(options);
+	const speakerIssuer = speakerIssuerOf(options);
+	const subjectClaim = options.subjectClaim ?? "sub";
+	const rolesClaim = options.rolesClaim ?? "roles";
+	const clockTolerance = options.clockSkewSeconds ?? 60;
+	return async (token) => {
+		if (!token) throw new TokenRefused("no token");
+		let claims: JWTPayload & Record<string, unknown>;
+		try {
+			({ payload: claims } = await jwtVerify(token, keys, {
+				issuer: [...options.issuers],
+				audience: [...options.audiences],
+				algorithms,
+				clockTolerance,
+				requiredClaims: ["exp", "iss", "aud"],
+			}));
+		} catch (error) {
+			throw new TokenRefused(
+				error instanceof Error ? error.message : "invalid token",
+			);
+		}
+		if (
+			options.requireScopeOrRoles !== false &&
+			!filled(claims.scp) &&
+			!filled(claims.scope) &&
+			!filled(claims.roles)
+		)
+			throw new TokenRefused(
+				"the token carries no scope or roles, so it is not an access token for this API",
+			);
+		if (options.rejectAppOnly !== false && claims.idtyp === "app")
+			throw new TokenRefused("an app-only token names no person");
+		const subject = text(claims[subjectClaim]);
+		if (!subject)
+			throw new TokenRefused(`the "${subjectClaim}" claim is missing`);
+		if (options.check && !options.check(claims))
+			throw new TokenRefused("the configured check refused the claims");
+		const roles = claims[rolesClaim];
+		const name =
+			text(options.nameClaim ? claims[options.nameClaim] : claims.name) ??
+			text(claims.preferred_username) ??
+			subject;
+		return {
+			id: oidcSpeakerId(speakerIssuer ?? (claims.iss as string), subject),
+			name,
+			roles: Array.isArray(roles)
+				? roles.filter((role): role is string => typeof role === "string")
+				: [],
+			expiresAt: new Date((claims.exp as number) * 1000),
+		};
+	};
+}

package/src/plugin.ts

@@ -0,0 +1,224 @@
+import {
+	CONVERSATIONS,
+	definePlugin,
+	type HttpRoute,
+	type PluginContext,
+	type RoundtablePlugin,
+	RUNTIME,
+	type WebSocketAccept,
+	type WebSocketRoute,
+} from "pi-roundtable";
+import { type WebAccess, type WebAccessMap, webAccess } from "./access.ts";
+import {
+	type Admitted,
+	checkPersonas,
+	Refusal,
+	WebChat,
+	type WebChatLimits,
+	type WebPersona,
+} from "./chat.ts";
+import type { Connection } from "./connections.ts";
+import { TokenRefused, type TokenVerifier } from "./oidc.ts";
+import { TICKET_PROTOCOL_PREFIX, WEBCHAT_PROTOCOL } from "./protocol.ts";
+import { restHandler } from "./rest.ts";
+import { TicketBook } from "./tickets.ts";
+
+/** Limits of the WebSocket route, besides the chat's own. */
+export interface WebChatRouteLimits {
+	/** Sockets the route holds open at once, for everyone together; default 256. */
+	maxConnections: number;
+	/** The largest client frame in bytes; default 64 KiB. */
+	maxMessageBytes: number;
+	/** Frames one socket may send per window; default 60 a minute. */
+	rate: { messages: number; perMs: number };
+	/** Bytes one socket may have waiting for a slow client before it is cut; default 4 MiB, room for a reply with files. */
+	maxBufferedBytes: number;
+	/** How long a WebSocket ticket may wait before it is spent; default 30 seconds. */
+	ticketTtlMs: number;
+}
+
+export interface WebChatOptions {
+	/** Checks each bearer token, such as `oidcJwtVerifier({ ... })`. */
+	verifier: TokenVerifier;
+	/** Who may chat and at which tier: an access map, or `webAccess(map)`. */
+	access: WebAccessMap | WebAccess;
+	/** The conversation kinds a person may open. */
+	personas: readonly WebPersona[];
+	/**
+	 * The browser origins allowed to open the WebSocket and call the API, each exactly
+	 * `scheme://host[:port]` as the browser sends it, such as `https://chat.example.com` or
+	 * `chrome-extension://<id>`. Required: `"any"` admits every origin, for clients that are not
+	 * browsers, and must never be used where a browser holds the token.
+	 */
+	origins: readonly string[] | "any";
+	/** The configured listener the route attaches to; default `public`. */
+	listener?: string;
+	/** Where the API and the socket live; default `/chat` (`/chat/socket`, `/chat/conversations`, …). */
+	path?: string;
+	/** The key prefix of the conversations; default `web`. Two web chats on one host need two. */
+	surface?: string;
+	limits?: Partial<WebChatLimits & WebChatRouteLimits>;
+}
+
+const DEFAULT_LIMITS: WebChatLimits & WebChatRouteLimits = {
+	connectionsPerPrincipal: 5,
+	unusedConversationsPerPrincipal: 20,
+	newConversationsPerHour: 60,
+	turnsPerPrincipal: 2,
+	messageChars: 32_000,
+	promptTimeoutMs: 30 * 60_000,
+	reauthLeadMs: 60_000,
+	maxConnections: 256,
+	maxMessageBytes: 64 * 1024,
+	rate: { messages: 60, perMs: 60_000 },
+	maxBufferedBytes: 4 * 1024 * 1024,
+	ticketTtlMs: 30_000,
+};
+
+const isAccess = (access: WebAccessMap | WebAccess): access is WebAccess =>
+	typeof (access as WebAccess).tierOf === "function";
+
+function checkOptions(options: WebChatOptions): {
+	path: string;
+	surface: string;
+} {
+	const path = options.path ?? "/chat";
+	if (!/^\/[A-Za-z0-9._~/-]*[A-Za-z0-9._~-]$/.test(path))
+		throw new Error(
+			`webChat: path ${JSON.stringify(path)} must start with / and not end with one, such as /chat`,
+		);
+	const surface = options.surface ?? "web";
+	if (!/^[a-z][a-z0-9-]*$/.test(surface))
+		throw new Error(
+			`webChat: surface ${JSON.stringify(surface)} must be a lowercase word, such as web`,
+		);
+	if (options.origins !== "any" && options.origins.length === 0)
+		throw new Error(
+			'webChat: origins is empty; list the origins your web pages are served from, or write "any" for clients that are not browsers',
+		);
+	return { path, surface };
+}
+
+/** The subprotocols a WebSocket upgrade offers. */
+function offered(request: Request): string[] {
+	return (request.headers.get("sec-websocket-protocol") ?? "")
+		.split(",")
+		.map((value) => value.trim())
+		.filter(Boolean);
+}
+
+/**
+ * A chat on the host's HTTP listener for people an OpenID Connect provider signs in: a REST API
+ * and a WebSocket under `path`, a `web:` chat surface, and the claim that runs each message as a
+ * turn of its conversation's persona through `context.turns`. Every conversation is private to the
+ * person who opened it. A browser opens the socket with a one-time ticket from `POST <path>/tickets`
+ * in the `ticket.<ticket>` subprotocol beside `roundtable.webchat.v1`; another client may send
+ * `Authorization: Bearer <token>` on the upgrade instead. The token is never read from a URL.
+ * Configuration mistakes throw here, before the host starts.
+ */
+export function webChat(options: WebChatOptions): RoundtablePlugin {
+	const { path, surface } = checkOptions(options);
+	const limits = { ...DEFAULT_LIMITS, ...options.limits };
+	const access = isAccess(options.access)
+		? options.access
+		: webAccess(options.access);
+	// The personas are checked now, so a broken list stops the configuration rather than the boot.
+	checkPersonas(options.personas);
+	return definePlugin({
+		name: surface === "web" ? "webchat" : `webchat-${surface}`,
+		requires: [CONVERSATIONS, RUNTIME],
+		setup: (context: PluginContext) => {
+			const chat = new WebChat({
+				surface,
+				verifier: options.verifier,
+				access,
+				personas: options.personas,
+				limits,
+				logger: context.logger,
+				registry: () => context.services.get(CONVERSATIONS),
+				conversations: () => context.conversations,
+				turns: () => context.turns,
+				runtime: () => context.services.get(RUNTIME),
+			});
+			// A person needs no more tickets waiting than the sockets they may open.
+			const tickets = new TicketBook({
+				ttlMs: limits.ticketTtlMs,
+				perPrincipal: limits.connectionsPerPrincipal,
+			});
+			const rest = restHandler({
+				chat,
+				tickets,
+				path,
+				origins: options.origins,
+				logger: context.logger,
+			});
+			const refuse = (status: number, text: string) =>
+				new Response(text, { status });
+			const accept = async (
+				request: Request,
+			): Promise<WebSocketAccept<Connection>> => {
+				if (URL.parse(request.url)?.pathname !== `${path}/socket`)
+					return refuse(404, "Not Found");
+				const protocols = offered(request);
+				if (!protocols.includes(WEBCHAT_PROTOCOL))
+					return refuse(400, `Offer the ${WEBCHAT_PROTOCOL} subprotocol`);
+				const ticket = protocols
+					.find((p) => p.startsWith(TICKET_PROTOCOL_PREFIX))
+					?.slice(TICKET_PROTOCOL_PREFIX.length);
+				const token = /^Bearer\s+(\S+)$/i.exec(
+					request.headers.get("authorization") ?? "",
+				)?.[1];
+				let admitted: Admitted;
+				try {
+					if (token) admitted = await chat.admit(token);
+					else if (ticket) {
+						const identity = tickets.redeem(ticket);
+						if (!identity) return refuse(401, "Unauthorized");
+						admitted = chat.admitIdentity(identity);
+					} else return refuse(401, "Unauthorized");
+				} catch (error) {
+					if (error instanceof TokenRefused) {
+						context.logger.info(
+							{ reason: error.reason },
+							"a web chat upgrade was refused",
+						);
+						return refuse(401, "Unauthorized");
+					}
+					if (error instanceof Refusal) return refuse(403, "Forbidden");
+					throw error;
+				}
+				const connection: Connection = { ...admitted, timers: [] };
+				if (!chat.connections.reserve(connection))
+					return refuse(429, "Too Many Connections");
+				return {
+					data: connection,
+					headers: { "Sec-WebSocket-Protocol": WEBCHAT_PROTOCOL },
+				};
+			};
+			const websocket: WebSocketRoute<Connection> = {
+				origins: options.origins,
+				maxConnections: limits.maxConnections,
+				maxMessageBytes: limits.maxMessageBytes,
+				maxBufferedBytes: limits.maxBufferedBytes,
+				rate: limits.rate,
+				accept,
+				open: (socket) => chat.opened(socket),
+				message: (socket, message) => chat.message(socket, message),
+				close: (socket) => chat.closed(socket),
+			};
+			const route: HttpRoute = {
+				name: `${surface}-chat`,
+				listener: options.listener ?? "public",
+				path: { prefix: `${path}/` },
+				handle: rest,
+				websocket,
+			};
+			return {
+				surfaces: [chat.surface],
+				channels: [chat.claim()],
+				personas: chat.contributedPersonas,
+				http: [route],
+			};
+		},
+	});
+}