pi-roundtable-web 0.25.0 → 0.26.0

package/src/app/sockets.ts

@@ -1,32 +1,79 @@
-import type { ActorFacts, Logger, RouteSocket } from "pi-roundtable";
+import type { ActorFacts, Logger, RouteSocket, Tier } from "pi-roundtable";
 import type { ServerFrame } from "../api-types.ts";
 
-/** One open WebSocket of an owner: who, what the page shows, and when its credential lapses. */
+/** One open WebSocket: who, what the page shows, and when its credential lapses. */
 export interface AppSocket {
 	principal: { id: string; name: string };
 	/** The actor the credential vouched for, which the person's messages are written as. */
 	actor: ActorFacts | undefined;
 	expiresAt: Date | undefined;
+	/** The tier they hold, as of the upgrade or the latest frame or recheck. */
+	tier: Tier;
+	/** The identity they spoke as; the principal's id when the credential names none. */
+	speakerId: string;
+	/** The roles their sign-in carried. */
+	roles: readonly string[];
+	/** A required onboarding step stands undone: only the frames a gated socket may have reach it. */
+	gated: boolean;
+	/** The session the socket came in on, for the recheck that asks whether it still stands. */
+	session?: string | undefined;
 	/** The page is in view; a push goes out only when no socket is. */
 	visible: boolean;
 	/** The room the page shows, whose progress streams to it. */
 	focus: string | undefined;
+	/** The host rooms the socket follows. */
+	subscriptions: Set<string>;
+	/** Set once `ready` and the replay went out: until then nothing but a frame addressed to the socket reaches it. */
+	started?: boolean;
 	socket?: RouteSocket<AppSocket>;
 	/** Closes the socket when its credential lapses or the cap on its life is reached. */
 	expiry?: ReturnType<typeof setTimeout>;
-	/** Looks again at whether the person is still an owner. */
+	/** Looks again at whether the person is still admitted, and at which tier. */
 	recheck?: ReturnType<typeof setInterval>;
 }
 
-/** The open sockets. Every one belongs to an owner, so a frame for the owners goes to them all. */
+/**
+ * Who a frame is for. There is no unaddressed send: every frame names its audience, and the
+ * open-time replay goes through the same filter as a live frame.
+ */
+export type Audience =
+	/** Sockets whose tier is owner now; with `focus`, those showing that room. */
+	| { owners: true; focus?: string }
+	/** Every socket of one person. */
+	| { principal: string }
+	/** The sockets that follow a host room and may read it now; with `focus`, those also showing it. */
+	| { room: string; focus?: true }
+	/** One socket; with `audience`, only if it is also in that audience (the replay on open). */
+	| { connection: AppSocket; audience?: Audience };
+
+/** The frames a gated socket still gets: the gate itself, the person's notices and badge, and refusals. */
+const GATED_FRAMES: ReadonlySet<ServerFrame["type"]> = new Set([
+	"ready",
+	"refused",
+	"gate",
+	"notice",
+	"notice_resolved",
+	"badge",
+]);
+
+/** Whether a socket may read a host room now; answered from a memo, so it costs no lookup. */
+export type RoomReader = (connection: AppSocket, room: string) => boolean;
+
+/** The open sockets, and the one way to put a frame on them. */
 export class Sockets {
 	readonly #open = new Set<AppSocket>();
 	readonly #logger: Logger;
+	#reader: RoomReader = () => false;
 
 	constructor(logger: Logger) {
 		this.#logger = logger;
 	}
 
+	/** Sets who may read which host room; until it is set, no host room frame reaches anyone. */
+	setRoomReader(reader: RoomReader): void {
+		this.#reader = reader;
+	}
+
 	add(connection: AppSocket, socket: RouteSocket<AppSocket>): void {
 		connection.socket = socket;
 		this.#open.add(connection);
@@ -40,8 +87,42 @@ export class Sockets {
 		this.#open.delete(connection);
 	}
 
-	/** Sends a frame on one socket; a dropped send is logged, never thrown. */
-	send(connection: AppSocket, frame: ServerFrame): void {
+	/** Whether the connection is in the audience now. */
+	reaches(connection: AppSocket, audience: Audience): boolean {
+		if ("connection" in audience)
+			return (
+				audience.connection === connection &&
+				(!audience.audience || this.reaches(connection, audience.audience))
+			);
+		if (!connection.started) return false;
+		if ("owners" in audience)
+			return (
+				connection.tier === "owner" &&
+				(audience.focus === undefined || connection.focus === audience.focus)
+			);
+		if ("principal" in audience)
+			return connection.principal.id === audience.principal;
+		return (
+			connection.subscriptions.has(audience.room) &&
+			this.#reader(connection, audience.room) &&
+			(!audience.focus || connection.focus === audience.room)
+		);
+	}
+
+	/**
+	 * Puts a frame on the sockets in `audience`, except `except`. A gated socket gets only what the
+	 * gate lets through. A dropped send is logged, never thrown.
+	 */
+	deliver(frame: ServerFrame, audience: Audience, except?: AppSocket): void {
+		for (const connection of this.#open) {
+			if (connection === except || !this.reaches(connection, audience))
+				continue;
+			if (connection.gated && !GATED_FRAMES.has(frame.type)) continue;
+			this.#send(connection, frame);
+		}
+	}
+
+	#send(connection: AppSocket, frame: ServerFrame): void {
 		const result = connection.socket?.send(JSON.stringify(frame));
 		if (result === "dropped")
 			this.#logger.warn(
@@ -50,18 +131,7 @@ export class Sockets {
 			);
 	}
 
-	/** Sends a frame to every open socket, or those `where` accepts, except `except`. */
-	broadcast(
-		frame: ServerFrame,
-		where?: (connection: AppSocket) => boolean,
-		except?: AppSocket,
-	): void {
-		for (const connection of this.#open)
-			if (connection !== except && (!where || where(connection)))
-				this.send(connection, frame);
-	}
-
-	/** Whether a page of this person is in view now; of any owner when no one is named. */
+	/** Whether a page of this person is in view now; of any person when none is named. */
 	anyVisible(principalId?: string): boolean {
 		for (const connection of this.#open)
 			if (
@@ -72,10 +142,28 @@ export class Sockets {
 		return false;
 	}
 
+	/** Calls `visit` on each open socket `where` accepts. */
+	each(
+		where: (connection: AppSocket) => boolean,
+		visit: (connection: AppSocket) => void,
+	): void {
+		for (const connection of [...this.#open])
+			if (where(connection)) visit(connection);
+	}
+
+	/** Closes the sockets `where` accepts, such as those of a session that ended. */
+	closeWhere(
+		where: (connection: AppSocket) => boolean,
+		code: number,
+		reason: string,
+	): void {
+		for (const connection of [...this.#open])
+			if (where(connection)) connection.socket?.close(code, reason);
+	}
+
 	/** Closes every socket, when the app stops. */
 	closeAll(code: number, reason: string): void {
-		for (const connection of [...this.#open])
-			connection.socket?.close(code, reason);
+		this.closeWhere(() => true, code, reason);
 	}
 
 	get size(): number {

package/src/app/surface.ts

@@ -16,9 +16,9 @@ import {
 } from "pi-roundtable";
 import type { RoomFile, RoomMessage } from "../api-types.ts";
 import type { OwnerDesk } from "./desk.ts";
-import { type FileDir, typeByName } from "./files.ts";
+import { type FileBinding, type FileDir, typeByName } from "./files.ts";
 import type { NewRoomMessage, RoomLog } from "./room-log.ts";
-import type { AppSocket, Sockets } from "./sockets.ts";
+import type { AppSocket, Audience, Sockets } from "./sockets.ts";
 import { AppSurfaceThreads } from "./surface-threads.ts";
 import type { WebThreads } from "./threads.ts";
 import type { Uploads } from "./uploads.ts";
@@ -45,6 +45,12 @@ export interface AppSurfaceOptions {
 	threads: Pick<WebThreads, "open" | "close">;
 	/** Whether a room can host a thread: an agent's or group's room that exists. */
 	canHost(parent: ChannelKey): Promise<boolean>;
+	/** Who has a room's frames: the owners' sockets for an agent room, a host room's readers for a host room. */
+	audienceOf(room: string): Audience;
+	/** Whether the room is a host's (its frames are the `host_*` ones). */
+	isHostRoom(room: string): boolean;
+	/** What binds a file an agent attaches in a host room, so its readers are served it. */
+	fileBinding?(room: string): FileBinding | undefined;
 	/** Tells the sockets the room list differs, once changes settle. */
 	changed(): void;
 	/**
@@ -54,6 +60,8 @@ export interface AppSurfaceOptions {
 	unprompted?(room: ChannelKey, author: string, text: string): void;
 	/** Called when a room's activity changes, so the presence table can follow. */
 	activity?(): void;
+	/** What was said in a host room since the assistant last posted; the host rooms' reader. */
+	channelContext?: ChatSurface["channelContext"];
 	/** The clock, in milliseconds; default `Date.now`. */
 	now?: () => number;
 	logger: Logger;
@@ -88,8 +96,8 @@ export interface RoomActivity {
 }
 
 /**
- * The owner app's rooms as a chat surface: what the host shows in a room reaches every socket of
- * every owner as a frame, and what a room says is stored in the room log. The agent team runs
+ * The owner app's rooms as a chat surface: what the host shows in a room reaches the sockets that
+ * may have it (the owners' for an agent room) as a frame, and what a room says is stored in the room log. The agent team runs
  * in the rooms (`agentRooms`) as it runs in its Discord channels, but each room is a
  * conversation of its own. A reply arrives whole, in Markdown, with its files stored, and an
  * agent's interim text is shown live until the final reply replaces it.
@@ -101,6 +109,8 @@ export class AppSurface implements ChatSurface {
 	readonly formatting = APP_FORMATTING;
 	/** The turn takes an upload up to the most the app lets a person upload. */
 	readonly maxAttachmentBytes: number;
+	/** Present on a surface with host rooms: what was said in one since the assistant last posted. */
+	channelContext?: ChatSurface["channelContext"];
 	readonly threads: AppSurfaceThreads;
 	readonly #options: AppSurfaceOptions;
 	readonly #activity = new Map<ChannelKey, Activity>();
@@ -114,6 +124,7 @@ export class AppSurface implements ChatSurface {
 		this.surface = options.surface;
 		this.maxAttachmentBytes = options.uploads.maxBytes;
 		this.#options = options;
+		if (options.channelContext) this.channelContext = options.channelContext;
 		this.threads = new AppSurfaceThreads({
 			surface: options.surface,
 			threads: options.threads,
@@ -147,26 +158,29 @@ export class AppSurface implements ChatSurface {
 		return this.#deliver !== undefined;
 	}
 
-	/** Stores a message of a room and shows it to every open socket, except `except`. */
+	/** Stores a message of a room and shows it to the sockets that may have the room, except `except`. */
 	async publish(row: NewRoomMessage, except?: AppSocket): Promise<RoomMessage> {
 		const message = await this.#options.log.append(row);
-		this.#options.sockets.broadcast(
-			{ type: "message", room: row.room, message },
-			undefined,
+		this.#options.sockets.deliver(
+			this.#options.isHostRoom(row.room)
+				? { type: "host_message", room: row.room, message }
+				: { type: "message", room: row.room, message },
+			this.#options.audienceOf(row.room),
 			except,
 		);
 		return message;
 	}
 
-	/** Changes the text of a stored message and shows the change to every open socket. */
+	/** Changes the text of a stored message and shows the change to the sockets that may have the room. */
 	async edit(room: ChannelKey, id: number, text: string): Promise<void> {
 		const message = await this.#options.log.edit(room, id, text);
 		if (!message) return;
-		this.#options.sockets.broadcast({
-			type: "edited",
-			room: message.room,
-			message,
-		});
+		this.#options.sockets.deliver(
+			this.#options.isHostRoom(room)
+				? { type: "host_edited", room: message.room, message }
+				: { type: "edited", room: message.room, message },
+			this.#options.audienceOf(room),
+		);
 	}
 
 	/** Whether a turn works in the room and whether Stop applies, as `activity` frames say. */
@@ -225,12 +239,15 @@ export class AppSurface implements ChatSurface {
 	}
 
 	#announce(room: ChannelKey, outcome?: "done" | "failed"): void {
-		this.#options.sockets.broadcast({
-			type: "activity",
-			room,
-			...this.activityOf(room),
-			...(outcome ? { outcome } : {}),
-		});
+		this.#options.sockets.deliver(
+			{
+				type: "activity",
+				room,
+				...this.activityOf(room),
+				...(outcome ? { outcome } : {}),
+			},
+			this.#options.audienceOf(room),
+		);
 		this.#options.activity?.();
 	}
 
@@ -283,7 +300,15 @@ export class AppSurface implements ChatSurface {
 		const entry = this.#activity.get(channel);
 		if (entry) entry.outcome = reply.failed ? "failed" : "done";
 		const files: RoomFile[] = (reply.files ?? []).map((file) =>
-			this.#options.files.put(file.name, typeByName(file.name), file.data),
+			this.#options.files.put(
+				file.name,
+				typeByName(file.name),
+				file.data,
+				undefined,
+				this.#options.isHostRoom(channel)
+					? this.#options.fileBinding?.(channel)
+					: undefined,
+			),
 		);
 		await this.publish({
 			room: channel,
@@ -328,21 +353,26 @@ export class AppSurface implements ChatSurface {
 				this.#speaks(channel, as?.agent);
 				const live = crypto.randomUUID();
 				const show = (current: string) =>
-					this.#options.sockets.broadcast({
-						type: "message",
-						room: channel,
-						message: {
-							id: 0,
+					this.#options.sockets.deliver(
+						{
+							type: this.#options.isHostRoom(channel)
+								? "host_message"
+								: "message",
 							room: channel,
-							kind: "agent",
-							...(as?.agent ? { agent: as.agent } : {}),
-							author: as?.name ?? ASSISTANT,
-							text: current,
-							files: [],
-							at: new Date().toISOString(),
-							live,
+							message: {
+								id: 0,
+								room: channel,
+								kind: "agent",
+								...(as?.agent ? { agent: as.agent } : {}),
+								author: as?.name ?? ASSISTANT,
+								text: current,
+								files: [],
+								at: new Date().toISOString(),
+								live,
+							},
 						},
-					});
+						this.#options.audienceOf(channel),
+					);
 				show(text);
 				return {
 					edit: async (edited) => {
@@ -362,9 +392,15 @@ export class AppSurface implements ChatSurface {
 
 	progress(channel: ChannelKey, event: TurnProgress): void {
 		this.#toolEvent(channel, event);
-		this.#options.sockets.broadcast(
+		// Only the sockets showing the room get its progress, and only those that may have the room.
+		const audience = this.#options.audienceOf(channel);
+		this.#options.sockets.deliver(
 			{ type: "progress", room: channel, event },
-			(connection) => connection.focus === channel,
+			"owners" in audience
+				? { owners: true, focus: channel }
+				: "room" in audience
+					? { room: audience.room, focus: true }
+					: audience,
 		);
 	}
 

package/src/app/uploads.ts

@@ -1,7 +1,12 @@
 import { extname } from "node:path";
 import type { AttachmentFile, AttachmentRef } from "pi-roundtable";
 import type { RoomFile, UploadView } from "../api-types.ts";
-import { FILE_RETENTION_MS, type FileDir, safeName } from "./files.ts";
+import {
+	FILE_RETENTION_MS,
+	type FileBinding,
+	type FileDir,
+	safeName,
+} from "./files.ts";
 import {
 	boundaryOf,
 	MultipartError,
@@ -32,7 +37,7 @@ const startsWith = (bytes: Uint8Array, signature: readonly number[], at = 0) =>
 const ascii = (text: string) => [...text].map((char) => char.charCodeAt(0));
 
 /** The image type the first bytes say, if any; these four are the ones the page shows itself. */
-function imageTypeOf(head: Uint8Array): string | undefined {
+export function imageTypeOf(head: Uint8Array): string | undefined {
 	if (startsWith(head, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
 		return "image/png";
 	if (startsWith(head, [0xff, 0xd8, 0xff])) return "image/jpeg";
@@ -153,6 +158,8 @@ export class Uploads {
 	readonly #now: () => number;
 	readonly maxBytes: number;
 	readonly #pendingBytes: number;
+	/** How long a stored file of an agent room is kept, in milliseconds. */
+	readonly #keepMs: number;
 
 	constructor(
 		waiting: FileDir,
@@ -161,6 +168,8 @@ export class Uploads {
 			maxBytes?: number;
 			/** The most bytes one person may have waiting; default 400 MiB. */
 			pendingBytes?: number;
+			/** How many days a stored file of an agent room is kept; default 30. */
+			keepDays?: number;
 			now?: () => number;
 		} = {},
 	) {
@@ -169,6 +178,10 @@ export class Uploads {
 		this.#now = options.now ?? Date.now;
 		this.maxBytes = options.maxBytes ?? DEFAULT_UPLOAD_MAX_BYTES;
 		this.#pendingBytes = options.pendingBytes ?? PENDING_BYTES_PER_PRINCIPAL;
+		this.#keepMs =
+			options.keepDays === undefined
+				? FILE_RETENTION_MS
+				: options.keepDays * 24 * 3_600_000;
 	}
 
 	#waitingOf(principalId: string): { files: number; bytes: number } {
@@ -303,11 +316,15 @@ export class Uploads {
 		return files;
 	}
 
-	/** Moves claimed uploads into the stored files, once their message is accepted. */
-	use(ids: readonly string[]): void {
+	/**
+	 * Moves claimed uploads into the stored files, once their message is accepted. `binding` ties
+	 * them to the host room the message is in, so only that room's readers are served them.
+	 */
+	use(ids: readonly string[], binding?: FileBinding): void {
 		for (const id of ids) {
 			this.#pending.delete(id);
-			this.#waiting.moveTo(id, this.#stored);
+			if (this.#waiting.moveTo(id, this.#stored) && binding)
+				this.#stored.bind(id, binding);
 		}
 	}
 
@@ -334,7 +351,11 @@ export class Uploads {
 		return { path };
 	}
 
-	/** Deletes the waiting uploads older than a day and the stored files older than 30 days; returns how many. */
+	/**
+	 * Deletes the waiting uploads older than a day and the stored files that are due; returns how
+	 * many. A file of an agent room is due after `keepDays` (default 30); a file bound to a host
+	 * room is due when its own expiry passes, and kept when it has none.
+	 */
 	sweep(): number {
 		const now = this.#now();
 		let dropped = 0;
@@ -343,7 +364,12 @@ export class Uploads {
 			this.#pending.delete(id);
 			dropped += 1;
 		}
-		for (const id of this.#stored.older(FILE_RETENTION_MS, now)) {
+		for (const id of this.#stored.ids()) {
+			const binding = this.#stored.binding(id);
+			const due = binding
+				? binding.expiresAt !== undefined && binding.expiresAt <= now
+				: (this.#stored.ageOf(id, now) ?? 0) > this.#keepMs;
+			if (!due) continue;
 			this.#stored.remove(id);
 			dropped += 1;
 		}

package/src/auth/authenticator.ts

@@ -4,8 +4,10 @@ import type { ResolvedAuth } from "../options.ts";
 import type { Verdict } from "../verifier.ts";
 import type { Identified, Visitor } from "../visitors.ts";
 import { checkNoneListener } from "./none.ts";
+import type { OidcLogin } from "./oidc.ts";
 import { checkPassword, PasswordCredential } from "./password.ts";
 import { loadSessionKey } from "./session-key.ts";
+import type { WebSessions } from "./sessions.ts";
 
 /** The plugin identity `none` and `password` speak through; `RoundtablePlugin.identities` links it to the owner. */
 export const WEB_CONSOLE_IDENTITY = "token:web-console";
@@ -22,6 +24,14 @@ export interface Authenticated {
 	visitor: Visitor;
 	actor?: ActorFacts;
 	expiresAt?: Date;
+	/** The session the credential is, when it is one: what an open socket asks about again. */
+	session?: string;
+}
+
+/** What a socket holds of the credential it came in on, to ask again whether it still stands. */
+export interface Held {
+	actor: ActorFacts | undefined;
+	session?: string | undefined;
 }
 
 /** A request that may not, with the status that says so; `login` when signing in would help. */
@@ -38,6 +48,12 @@ export interface Unauthenticated {
  */
 export interface Authenticator {
 	authenticate(request: Request): Promise<Authenticated | Unauthenticated>;
+	/**
+	 * Asks again about a credential already admitted, as an open socket does for every frame and on
+	 * a timer: does the session still stand, and who is the person now, at which tier. It reads the
+	 * same `IDENTITY` as a request does, so a person disabled or demoted since is seen at once.
+	 */
+	recheck(held: Held): Promise<{ visitor: Visitor } | Unauthenticated>;
 	/**
 	 * Answers the paths below the mount that need no session, such as the login page; undefined
 	 * for any other, and absent for a mode with none.
@@ -60,6 +76,11 @@ export interface AuthenticatorOptions {
 	dataDir: string;
 	/** The listener the console is served on and its address, for the check of `none`. */
 	listener: { id: string; address: Readonly<ListenerAddress> | undefined };
+	/** The sign-in flow and the session store, for `oidc`. */
+	oidc?: {
+		login: Pick<OidcLogin, "open" | "credential">;
+		sessions: Pick<WebSessions, "alive">;
+	};
 	/** Where the password is read from; default `process.env`. */
 	env?: Readonly<Record<string, string | undefined>>;
 	/** How long each failed login waits; default 1000 ms. Tests set it lower. */
@@ -68,8 +89,15 @@ export interface AuthenticatorOptions {
 	now?: () => number;
 }
 
+/** A credential that admits: who it vouches for, and the session it is when it is one. */
+export type Admitted = Extract<Verdict, { admitted: true }> & {
+	session?: string;
+};
+
 /** What a credential says about a request, before the person is identified. */
-type Credential = (request: Request) => Promise<Verdict | Unauthenticated>;
+export type Credential = (
+	request: Request,
+) => Promise<Verdict | Admitted | Unauthenticated>;
 
 const READ_METHODS = new Set(["GET", "HEAD"]);
 
@@ -78,6 +106,16 @@ const denied = (refusal: string): Unauthenticated => ({
 	status: 403,
 });
 
+/** A refusal in the shape identification answers with. */
+const refused = (reason: string): Identified => ({ refusal: reason });
+
+/** A session that is gone, which signing in again would fix. */
+const signedOut = (reason: string): Unauthenticated => ({
+	refusal: reason,
+	status: 401,
+	login: true,
+});
+
 /** Admits as the verifier says; one that throws or rejects admits no one. */
 function verifierCredential(
 	verifier: (request: Request) => Verdict | Promise<Verdict>,
@@ -112,6 +150,11 @@ export function createAuthenticator(
 			logger,
 		);
 		credential = async () => ({ admitted: true, actor: WEB_CONSOLE_ACTOR });
+	} else if (auth.mode === "oidc") {
+		if (!options.oidc) throw new Error("the oidc sign-in is not set up");
+		credential = options.oidc.login.credential;
+		open = (request, rest) =>
+			options.oidc?.login.open(request, rest) ?? Promise.resolve(undefined);
 	} else {
 		const password = new PasswordCredential({
 			password: checkPassword(options.env ?? process.env, auth.passwordEnv),
@@ -138,30 +181,50 @@ export function createAuthenticator(
 		};
 		open = (request, rest) => password.open(request, rest);
 	}
+	const identify = async (
+		actor: ActorFacts | undefined,
+	): Promise<Identified> => {
+		try {
+			return await options.identify(actor);
+		} catch {
+			// A lookup of who they are that fails admits no one.
+			return refused("identity failed");
+		}
+	};
 	return {
 		...(open ? { open } : {}),
 		async authenticate(request) {
 			const checked = await credential(request);
 			if ("refusal" in checked) return checked;
 			if (!checked.admitted) return denied(String(checked.reason));
-			let identified: Identified;
-			try {
-				identified = await options.identify(checked.actor);
-			} catch {
-				// A lookup of who they are that fails admits no one.
-				return denied("identity failed");
-			}
+			const identified = await identify(checked.actor);
 			if ("refusal" in identified) return denied(String(identified.refusal));
 			if (
 				!READ_METHODS.has(request.method) &&
 				request.headers.get("origin") !== options.origin
 			)
 				return denied("foreign origin");
+			const { session } = checked as Admitted;
 			return {
 				visitor: identified.visitor,
 				...(checked.actor ? { actor: checked.actor } : {}),
 				...(checked.expiresAt ? { expiresAt: checked.expiresAt } : {}),
+				...(session ? { session } : {}),
 			};
 		},
+		async recheck(held) {
+			if (held.session) {
+				try {
+					if (!(await options.oidc?.sessions.alive(held.session)))
+						return signedOut("session ended");
+				} catch {
+					return denied("session lookup failed");
+				}
+			}
+			const identified = await identify(held.actor);
+			return "refusal" in identified
+				? denied(String(identified.refusal))
+				: { visitor: identified.visitor };
+		},
 	};
 }

package/src/auth/next.ts

@@ -0,0 +1,52 @@
+/**
+ * Where a sign-in goes back to. A page link (from the host's own dashboard, a notification, or a
+ * page the server turned away) names it as `?next=`, and only these shapes are taken: anything
+ * else is dropped, so the callback never redirects to a place a link chose.
+ *
+ * - `profile`, `notices`, `settings`: a page of the app;
+ * - `room:<key>`: a room of this app's surface (`<surface>:<kind>.<id>`);
+ * - `p:<id>`: a host page, `[a-z0-9-]{1,40}`.
+ */
+export function allowedNext(
+	value: string | null | undefined,
+	surface: string,
+): string | undefined {
+	if (!value) return undefined;
+	if (value === "profile" || value === "notices" || value === "settings")
+		return value;
+	const room = /^room:(.+)$/.exec(value)?.[1];
+	if (room !== undefined)
+		return new RegExp(`^${surface}:[A-Za-z0-9._~-]{1,160}$`).test(room)
+			? value
+			: undefined;
+	const page = /^p:(.+)$/.exec(value)?.[1];
+	return page !== undefined && /^[a-z0-9-]{1,40}$/.test(page)
+		? value
+		: undefined;
+}
+
+/** The app route a `next` names, as the page's router writes it: `room/<key>`, `p/<id>` or the page's name. */
+export function routeOfNext(next: string): string {
+	if (next.startsWith("room:"))
+		return `room/${encodeURIComponent(next.slice("room:".length))}`;
+	if (next.startsWith("p:")) return `p/${next.slice("p:".length)}`;
+	return next;
+}
+
+/**
+ * The `next` a page path stands for, for a server that turns away a page navigation (path
+ * routing only: a hash route never reaches the server). Undefined for a path that names none.
+ */
+export function nextOfPath(rest: string, surface: string): string | undefined {
+	const [first, second, ...more] = rest.split("/").filter(Boolean);
+	if (more.length > 0 || first === undefined) return undefined;
+	try {
+		if (second === undefined) return allowedNext(first, surface);
+		const key = decodeURIComponent(second);
+		if (first === "room") return allowedNext(`room:${key}`, surface);
+		if (first === "p") return allowedNext(`p:${key}`, surface);
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}