pi-roundtable-webchat 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.8.0] - 2026-10-07
+
+- First release. `webChat(options)` adds a WebSocket chat to a host's HTTP listener for people an OpenID Connect provider signs in: a `web:` chat surface, the claim that runs each message as a turn of its conversation's persona through `context.turns`, and a REST API (`POST tickets`, `GET`/`POST conversations`, `GET conversations/<id>/messages`) under one path. Every conversation is private to the person who opened it: the claim checks the host's conversation registry inside the conversation's queue before each turn.
+- Protocol version 1 (`roundtable.webchat.v1`): client frames `send`, `stop`, `approval`, `answer`, and `auth`; server frames `ready`, `accepted`, `typing`, `stoppable`, `progress`, `reply`, `failed` (also when the host refuses a turn before it runs, such as when its conversation cannot be recorded), `prompt`, `prompt_closed`, `reauth`, and `error`; close codes 4401 and 4403. A browser connects with a one-time ticket in the `ticket.<ticket>` subprotocol, another client with a bearer header; the token is never read from a URL.
+- `oidcJwtVerifier(options)`: JWKS fetched and cached, `iss`, `aud`, `exp`, `nbf` with clock skew, an asymmetric algorithm allowlist, configurable subject, name, and roles claims, and a further `check`. By default it refuses a token with no scope (`scp` or `scope`) or app roles, so an ID token cannot pass for an access token (`requireScopeOrRoles`), and an app-only token (`idtyp: "app"`, `rejectAppOnly`). The README's provider settings cover a stable subject claim, pinning the tenant, merging issuers of one tenant only, and who `everyone` admits. Speaker ids are `oidc:<base64url(issuer)>:<subject>` (`oidcSpeakerId`, `parseOidcSpeakerId`).
+- `webAccess(map)`: tiers from the token's roles or speaker ids; owners only by speaker id; a person with no tier is not admitted.
+- Secure defaults: `origins` required, connections per person and per route, frame size and rate limits, prompts that only the conversation's person answers at the tier the call needs.
+- Turn and conversation limits per person: `turnsPerPrincipal` (default 2) turns running or queued at once across their conversations, and at most one turn queued behind a conversation's running one; a message over either is refused with the `busy` error and never queued. `newConversationsPerHour` (default 60) bounds the conversations a person opens an hour, over the socket or `POST conversations`, past which they get `too_many_conversations` (429 over REST).
+- Tickets per person: a person holds at most `connectionsPerPrincipal` unspent WebSocket tickets, and asking for one more drops their own oldest, so one person cannot push out everyone else's tickets (`TicketBookOptions.perPrincipal`, default 5).
+- Configuration checked at load, for JavaScript configurations too: an access map whose `owners`, `users`, or `roles` is not a list of strings, or whose `everyone` is not a boolean, and a persona whose `kind` is not a non-empty string or whose `minTier` is not a tier, throw. A string where a list belongs would have matched its substrings, and an unknown `minTier` would have let every tier open the persona.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wayne930242
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# pi-roundtable-webchat
+
+A WebSocket chat adapter for [pi-roundtable][roundtable].
+People an OpenID Connect provider signs in chat with the assistant from a web page or a browser extension, each in private conversations of their own.
+A turn's text and tools show as it runs, and a held tool call asks the person on an approval card.
+Source lives in [`packages/webchat`][source] in the pi-roundtable repository and releases in lockstep with the core.
+
+[roundtable]: https://www.npmjs.com/package/pi-roundtable
+[source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/webchat
+
+The plugin adds three things to a host:
+
+- a chat surface whose conversations have keys `web:<conversation>`;
+- the claim that runs each message as a turn of its conversation's persona, through `context.turns` and the host's runtime;
+- a REST API and a WebSocket under one path of the host's HTTP listener.
+
+It needs no Discord: a host whose `roundtable.config.ts` has no `discord` key and lists this plugin is a web-only assistant.
+`roundtable init --adapter web` creates such a project.
+
+## Requirements
+
+- Bun 1.3 or later, and pi-roundtable `>=0.8.0 <0.9.0` as a peer dependency.
+- An HTTP listener on the host (`http` in the configuration), behind a reverse proxy that serves it over HTTPS.
+- An OpenID Connect provider that issues access tokens for this API, with signing keys published as a JWKS.
+
+## Install
+
+```sh
+bun add pi-roundtable-webchat
+```
+
+```ts
+import { readFileSync } from "node:fs";
+import type { RoundtableConfig } from "pi-roundtable";
+import { oidcJwtVerifier, webChat } from "pi-roundtable-webchat";
+
+export default {
+	owner: { id: "operator", name: "Ada" },
+	database: { url: process.env.DATABASE_URL ?? "" },
+	dataDir: "./data",
+	model: "anthropic/claude-sonnet-5-5",
+	http: { port: 3000, hostname: "127.0.0.1" },
+	plugins: [
+		webChat({
+			verifier: oidcJwtVerifier({
+				jwksUrl: "https://login.example.com/keys",
+				issuers: ["https://login.example.com/"],
+				audiences: ["api://helpdesk"],
+			}),
+			access: {
+				admins: { roles: ["Helpdesk.Admin"] },
+				members: { roles: ["Helpdesk.User"] },
+			},
+			origins: ["https://chat.example.com"],
+			personas: [
+				{
+					kind: "helpdesk",
+					label: "Helpdesk",
+					prompt: () => readFileSync("./persona/helpdesk.md", "utf8"),
+				},
+			],
+		}),
+	],
+} satisfies RoundtableConfig;
+```
+
+Every mistake in these options throws when the configuration loads, so `roundtable doctor` names it before the host starts.
+
+## Options
+
+| Option | What it sets |
+|---|---|
+| `verifier` | Checks each bearer token and names the person: `oidcJwtVerifier({ ... })`, or your own `TokenVerifier`. |
+| `access` | Who may chat, and at which tier: a `WebAccessMap`, or `webAccess(map)`. |
+| `personas` | The conversation kinds a person may open (`WebPersona`). |
+| `origins` | Required. The browser origins allowed to open the socket and call the API, each exactly `scheme://host[:port]`, such as `https://chat.example.com` or `chrome-extension://<id>`. `"any"` admits every origin, for clients that are not browsers; never use it where a browser holds the token. |
+| `listener` | The configured listener the route attaches to; default `public`, the one `http` names. |
+| `path` | Where the API and the socket live; default `/chat`. |
+| `surface` | The key prefix of the conversations; default `web`. Two web chats on one host need two prefixes, and two paths. |
+| `limits` | Overrides of the limits below. |
+
+### Personas
+
+A `WebPersona` is `{ kind, label?, prompt?, minTier?, selection? }`.
+`prompt()` is the system prompt of its conversations, contributed by this plugin; leave it out when another plugin contributes the persona of that kind.
+`minTier` (default `member`) is the lowest tier that may see and open it; a person whose tier falls below it later can no longer write in its conversations.
+`selection` (`{ tools, groups }`) names the tools its turns get; without it a turn gets the plugins' `agentSelection`, which grows with every plugin you add, so name the tools.
+Leave out `schedule_*` and `delegate_task` (see [what it does not do yet](#what-it-does-not-do-yet)), and `web_search` and `fetch_content` unless people may make the server fetch any address, internal ones included: they are member-tier tools, and a plugin that loads pi-web-access, such as one `roundtable add package pi-web-access` writes, adds them to `agentSelection`.
+The kinds `owner` and `agent` belong to the host and are refused.
+
+### Access
+
+A `WebAccessMap` is `{ owners?, admins?, members? }`.
+`admins` and `members` name people by `users` (speaker ids), by `roles` (the names in the token's roles claim), or `everyone` the verifier accepts, guest accounts included; the highest tier a person qualifies for wins.
+`owners` is a list of speaker ids only: no claim a provider issues can make anyone the owner.
+A person the map gives no tier is not admitted: no ticket, no socket, no conversation, no turn.
+A map that admits no one throws.
+
+### `oidcJwtVerifier`
+
+| Option | What it sets |
+|---|---|
+| `jwksUrl` | The provider's signing keys (`jwks_uri`): https, or http on a loopback address. Fetched when first needed, cached for `cacheMaxAgeMs` (10 minutes), and fetched again for a key id it lacks at most every `refetchCooldownMs` (30 seconds). |
+| `issuers` | The accepted `iss` values. |
+| `audiences` | The accepted `aud` values. |
+| `speakerIssuer` | The issuer speaker ids are made from; required when `issuers` lists several issuers of one provider, so one person keeps one id. |
+| `subjectClaim` | The claim naming the person; default `sub`. Use a claim that stays the same across your app registrations, such as Entra's `oid`; see [provider settings](#provider-settings). |
+| `nameClaim` | The claim to show them by; default `name`, then `preferred_username`, then the subject. |
+| `rolesClaim` | The claim holding their roles or groups, an array of strings; default `roles`. |
+| `algorithms` | Accepted signature algorithms; default `RS256` and `ES256`. Symmetric algorithms and `none` are refused. |
+| `clockSkewSeconds` | How far `exp` and `nbf` may be off the local clock; default 60. |
+| `check` | A further check on the verified claims, such as a tenant claim; `false` refuses the token. |
+| `requireScopeOrRoles` | Refuse a token without a scope (`scp` or `scope`) or app roles (`roles`), the marks of an access token; default `true`, so an ID token cannot pass for an access token. Set `false` only for a provider whose access tokens carry neither. |
+| `rejectAppOnly` | Refuse an app-only token, which names a service rather than a person (`idtyp: "app"`); default `true`. |
+
+It checks the signature, `iss`, `aud`, `exp` (required), and `nbf`, then a scope or roles and no app-only token, then the subject claim and `check`.
+A refused token throws `TokenRefused`, whose `reason` goes to the host's log and never to the client.
+The speaker id of a person is `oidc:<base64url(issuer)>:<subject>`: `oidcSpeakerId(issuer, subject)` makes it, and `parseOidcSpeakerId(id)` turns it back into the pair.
+Use it to name owners in the access map.
+
+### Provider settings
+
+The verifier is generic; what makes it safe is how you point it at your provider.
+Microsoft Entra ID is the example below, and the same questions apply to any provider.
+
+- **Name people by a claim that is stable across app registrations.** Many providers make `sub` pairwise: it differs for each application, so a web page and a browser extension registered as two apps would give one person two speaker ids, and two memories. Entra's `oid` is the same for a person in every app of the tenant: set `subjectClaim: "oid"`.
+- **Pin the tenant in `check`.** An object id is unique only within its tenant, and a multi-tenant app takes tokens from every tenant. With Entra, check `claims.tid` against your tenant id.
+- **Accept access tokens only.** `requireScopeOrRoles` refuses a token with no scope or app roles, as an ID token is. An Entra ID token may still carry `roles` when you assign app roles, so also require the delegated scope in `check` (`typeof claims.scp === "string"`); where you can, register the API apart from the web page's sign-in app, so a page's ID token never has the API's audience.
+- **Refuse app-only tokens.** `rejectAppOnly` refuses `idtyp: "app"`. Entra writes `idtyp` only when the app asks for that optional claim; requiring `scp` refuses app-only tokens either way, since they carry roles and no scope.
+- **Merge issuers of one tenant only.** `speakerIssuer` makes one person's id the same whichever listed issuer signed the token, such as Entra's v1 `https://sts.windows.net/<tenant>/` and v2 `https://login.microsoftonline.com/<tenant>/v2.0`. Never list issuers of different tenants or providers together: their subjects are separate namespaces, and two people could get one id.
+- **Mind who `everyone` admits.** `everyone: true` admits every person the verifier accepts, guest accounts of your tenant included. Prefer roles assigned to the users and groups who should chat; with Entra, the optional `acct` claim (`0` for a member of the tenant, `1` for a guest) lets `check` refuse guests.
+
+```ts
+const tenant = process.env.ENTRA_TENANT_ID ?? "";
+const verifier = oidcJwtVerifier({
+	jwksUrl: `https://login.microsoftonline.com/${tenant}/discovery/v2.0/keys`,
+	issuers: [`https://login.microsoftonline.com/${tenant}/v2.0`],
+	audiences: [process.env.ENTRA_API_CLIENT_ID ?? ""],
+	subjectClaim: "oid",
+	check: (claims) => claims.tid === tenant && typeof claims.scp === "string",
+});
+```
+
+## Connecting
+
+The token is never read from a URL.
+
+- **A browser** asks for a one-time ticket with `POST <path>/tickets` and `Authorization: Bearer <token>`, then opens `<path>/socket` offering two subprotocols: `roundtable.webchat.v1` and `ticket.<ticket>`.
+  A ticket is spent by the first upgrade, lasts 30 seconds, and never outlives its token.
+  A person holds at most `connectionsPerPrincipal` unspent tickets; asking for one more drops their own oldest, never anyone else's.
+- **Another client**, such as a service, sends `Authorization: Bearer <token>` on the upgrade and offers `roundtable.webchat.v1`.
+
+The server echoes `roundtable.webchat.v1`.
+An upgrade from an origin not in `origins`, or without one, is refused with 403; without a valid ticket or token with 401; for a person the access map does not admit with 403; past the person's connection limit with 429.
+
+```js
+const { ticket } = await (
+	await fetch("/chat/tickets", { method: "POST", headers: { authorization: `Bearer ${token}` } })
+).json();
+const socket = new WebSocket("wss://chat.example.com/chat/socket", [
+	"roundtable.webchat.v1",
+	`ticket.${ticket}`,
+]);
+socket.onmessage = (event) => console.log(JSON.parse(event.data));
+socket.onopen = () =>
+	socket.send(JSON.stringify({ type: "send", id: "1", persona: "helpdesk", text: "Hello" }));
+```
+
+## Protocol, version 1
+
+Each WebSocket message is one JSON object with a `type`.
+`WEBCHAT_PROTOCOL` and `WEBCHAT_PROTOCOL_VERSION` name the version; an incompatible change gets a new subprotocol name.
+The TypeScript types are `ClientFrame` and `ServerFrame`.
+
+### Client frames
+
+| Frame | Meaning |
+|---|---|
+| `{ type: "send", id, persona, text }` | Opens a new conversation of `persona` with this message. `id` is your reference, echoed by `accepted` or `error`. |
+| `{ type: "send", id, conversation, text }` | A message in one of your conversations. |
+| `{ type: "stop", conversation }` | Stops the conversation's running turn. |
+| `{ type: "approval", prompt, approved }` | Approves or declines an approval prompt. |
+| `{ type: "answer", prompt, choices, text? }` | Answers a question prompt: the chosen options' labels, and your own text where the question allows it. |
+| `{ type: "auth", token }` | A fresh token for the same person, sent after `reauth`. |
+
+### Server frames
+
+| Frame | Meaning |
+|---|---|
+| `{ type: "ready", protocol, speaker, personas, expiresAt }` | Sent first, and again after a fresh token: who you are (`{ id, name, tier }`), the personas you may open (`{ kind, label }`), and when the token expires. Open prompts follow it. |
+| `{ type: "accepted", id, conversation }` | Your message `id` was taken into `conversation`, a new one when you named none. |
+| `{ type: "typing", conversation, on }` | The assistant is, or is no longer, working in the conversation. |
+| `{ type: "stoppable", conversation, on }` | A stop applies, or no longer applies. |
+| `{ type: "progress", conversation, event }` | What the running turn writes and which tools it runs: `{ type: "text", delta }`, `{ type: "tool_start", id, tool, preview? }`, or `{ type: "tool_end", id, tool, ok }`. Never the thinking, never a tool's full arguments. |
+| `{ type: "reply", conversation, text, thinking?, files? }` | The turn's answer in full markdown, with its files inline as `{ name, data }` (base64). |
+| `{ type: "failed", conversation, stopped }` | The turn ended without an answer: it failed, the host refused it before it ran (for example when its conversation could not be recorded), or it was stopped. The cause stays in the host's log. |
+| `{ type: "prompt", conversation, prompt }` | The turn asks you: `{ id, kind: "approval", title, message }`, or `{ id, kind: "ask", title, question, options, multi, allowOther }`. |
+| `{ type: "prompt_closed", conversation, prompt, outcome }` | The prompt closed: `approved`, `declined`, `answered`, `expired`, or `cancelled` (the turn stopped). |
+| `{ type: "reauth", expiresAt }` | Your token expires soon: send `auth` with a fresh one. |
+| `{ type: "error", code, ref? }` | A frame was refused. `ref` is the `send` id or prompt id it was about. |
+
+Error codes: `bad_frame` (it does not parse, its text is blank or too long, or an answer the question does not allow), `unknown_conversation`, `forbidden` (someone else's conversation or prompt, or an approval above your tier), `unknown_persona` (none of that kind you may open), `unknown_prompt`, `too_many_conversations` (you hold `unusedConversationsPerPrincipal` conversations you have not written in, or opened `newConversationsPerHour` in the last hour), and `busy` (you have `turnsPerPrincipal` turns running or queued, or the conversation already has a turn queued behind its running one; the message was not taken, so send it again once a turn ends).
+
+Close codes: `4401` when the token expired without a fresh `auth`, or a fresh one was refused; `4403` when the person is no longer admitted, or a fresh token names someone else.
+The host's own limits close with `1008` (too many frames), `1009` (a frame too big), and `1006` (a client that stopped reading).
+
+## REST API
+
+Every call sends `Authorization: Bearer <token>`; a missing or refused token gets 401 with `WWW-Authenticate: Bearer`, and a person the access map does not admit 403.
+A request from a browser origin not in `origins` gets 403; an allowed origin gets CORS headers and its preflight is answered.
+
+| Call | Answer |
+|---|---|
+| `POST <path>/tickets` | 201 `{ ticket, expiresAt }`. |
+| `GET <path>/conversations` | `{ conversations: [{ conversation, persona, title?, createdAt, lastActiveAt }] }`: your own, the most recently active first. |
+| `POST <path>/conversations` with `{ persona, title? }` | 201 `{ conversation, persona }`: a new conversation to write in. 429 `too_many_conversations` past either conversation limit. |
+| `GET <path>/conversations/<conversation>/messages?limit=50` | `{ messages: [{ role, text }] }`: its last messages, at most 500. Someone else's conversation is 403. |
+
+## Security model
+
+- **Private conversations.** A conversation belongs to the person who opened it.
+  The host's conversation registry records its person at its first turn, and the claim checks that record inside the conversation's queue before every turn; only that person may list it, read it, write in it, stop it, or answer its prompts.
+  Conversation ids are random UUIDs, and the claim runs only messages this plugin accepted from a verified socket.
+  The owner can still read every conversation through the owner console, pi-roundtable-web, and the operator through the database and the data directory.
+- **Tokens.** Tokens are checked on every REST call, every upgrade, and every `auth` frame, and never read from a URL.
+  By default only a person's access token passes: one without a scope or app roles, or an app-only one, is refused.
+  A socket is closed when its token expires.
+- **Origins.** `origins` is required and checked on every upgrade and every browser request, so another site cannot open a socket or call the API with a browser's credentials.
+- **Limits.** Each person holds at most `connectionsPerPrincipal` sockets, and the route at most `maxConnections`; frames are limited in size and rate.
+  Each person has at most `turnsPerPrincipal` turns running or queued at once, however many conversations or sockets they use, and a conversation at most its running turn and one queued behind it, so one account cannot spend a shared model subscription on many turns at once; a message over either limit is refused with `busy` and never queued.
+  Each person opens at most `newConversationsPerHour` conversations an hour, over the socket or the REST API alike.
+- **Approvals.** A held call's card goes to the conversation's person only, and needs the tier the call needs.
+  A card whose tier the person lacks is never shown, so the call stays held.
+- **Owner.** Nobody becomes the owner through a token's claims; list owners by speaker id.
+  Owner-tier tools stay out of web turns unless an owner is chatting.
+
+## Limits
+
+| Limit | Default |
+|---|---|
+| `connectionsPerPrincipal` | 5 sockets per person |
+| `unusedConversationsPerPrincipal` | 20 conversations opened but not written in |
+| `newConversationsPerHour` | 60 conversations opened per person in any hour |
+| `turnsPerPrincipal` | 2 turns running or queued per person, across conversations; a conversation holds its running turn and one queued |
+| `messageChars` | 32 000 characters per message |
+| `promptTimeoutMs` | 30 minutes before a prompt expires |
+| `reauthLeadMs` | `reauth` 60 seconds before the token expires |
+| `maxConnections` | 256 sockets on the route |
+| `maxMessageBytes` | 64 KiB per client frame |
+| `rate` | 60 frames a minute per socket |
+| `maxBufferedBytes` | 4 MiB waiting for a slow client |
+| `ticketTtlMs` | 30 seconds |
+
+## What it does not do yet
+
+- Attachments: messages carry text only.
+- Schedules and delegated reports: the claim takes no background turns, so a schedule or a report aimed at a web conversation is skipped. Leave the `schedule_*` and `delegate_task` tools out of a web persona's `selection`.
+- Error reports: `ops: { conversation: "web:<id>" }` stops the host at startup with a `config ops.conversation` error, since the surface posts only to a conversation a signed-in person opened and the claim takes no background turns. Report errors to another surface's conversation, or to an agent with Discord.
+- Agent teams: the web chat has no agent rooms.
+- A person signed in on two providers, or on Discord and the web, has two speaker ids, and so two memories, until principals arrive in pi-roundtable 0.9.
+
+## Testing
+
+`pi-roundtable/testing`'s `describeSurfaceContract` runs the chat surface contract on this surface in this package's tests, and the end-to-end test runs a host with a self-made JWKS and a scripted model.

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "pi-roundtable-webchat",
+	"version": "0.8.0",
+	"description": "A WebSocket chat adapter for pi-roundtable: private web conversations for people an OpenID Connect provider signs in, with live progress and approval cards",
+	"type": "module",
+	"license": "MIT",
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/testing",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git",
+		"directory": "packages/webchat"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"jose": "6.2.12"
+	},
+	"peerDependencies": {
+		"pi-roundtable": ">=0.8.0 <0.9.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@earendil-works/pi-ai": ">=1.0.0 <2",
+		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
+		"@types/bun": "1.4.2",
+		"pi-roundtable": "0.8.0",
+		"typebox": "1.3.34",
+		"typescript": "7.0.2"
+	}
+}

package/src/access.ts

@@ -0,0 +1,99 @@
+import type { Tier } from "pi-roundtable";
+import type { WebIdentity } from "./oidc.ts";
+
+/** Who holds a tier: speaker ids, role or group names from the token, or everyone the provider signs in. */
+export interface WebTierMembers {
+	users?: readonly string[];
+	roles?: readonly string[];
+	everyone?: boolean;
+}
+
+/**
+ * Who may chat, and at which tier. Owners are named only by speaker id, so no claim a provider
+ * issues can make someone the owner; admins and members may be named by role as well. A person
+ * the map gives no tier is not admitted: no connection, no conversation, no turn.
+ */
+export interface WebAccessMap {
+	/** Speaker ids, such as `oidcSpeakerId(issuer, subject)`; never roles. */
+	owners?: readonly string[];
+	admins?: WebTierMembers;
+	members?: WebTierMembers;
+}
+
+/** The tier a verified person chats at, or undefined when they are not admitted. */
+export interface WebAccess {
+	tierOf(identity: WebIdentity): Tier | undefined;
+}
+
+const isStrings = (value: unknown): value is readonly string[] =>
+	Array.isArray(value) && value.every((item) => typeof item === "string");
+
+/**
+ * Throws unless `tier` is a `WebTierMembers` whose `users` and `roles` are lists of strings and
+ * whose `everyone` is a boolean: a JavaScript configuration is not type-checked, and a string
+ * where a list belongs would match its substrings.
+ */
+function checkTier(name: string, tier: unknown): void {
+	if (tier === undefined) return;
+	if (typeof tier !== "object" || tier === null || Array.isArray(tier))
+		throw new Error(
+			`webAccess: ${name} is { users?, roles?, everyone? }; got ${JSON.stringify(tier)}`,
+		);
+	const { users, roles, everyone } = tier as Record<string, unknown>;
+	for (const [field, value] of [
+		["users", users],
+		["roles", roles],
+	] as const)
+		if (value !== undefined && !isStrings(value))
+			throw new Error(
+				`webAccess: ${name}.${field} must be a list of strings; got ${JSON.stringify(value)}`,
+			);
+	if (everyone !== undefined && typeof everyone !== "boolean")
+		throw new Error(
+			`webAccess: ${name}.everyone must be true or false; got ${JSON.stringify(everyone)}`,
+		);
+}
+
+function admitsSomeone(tier: WebTierMembers | undefined): boolean {
+	return (
+		tier !== undefined &&
+		(tier.everyone === true ||
+			(tier.users?.length ?? 0) > 0 ||
+			(tier.roles?.length ?? 0) > 0)
+	);
+}
+
+/**
+ * The policy of an access map: the highest tier a person qualifies for wins. A map that admits
+ * no one is a configuration mistake and throws.
+ */
+export function webAccess(map: WebAccessMap): WebAccess {
+	if (map.owners !== undefined && !isStrings(map.owners))
+		throw new Error(
+			"webAccess: owners is a list of speaker ids; a provider's roles cannot name an owner",
+		);
+	checkTier("admins", map.admins);
+	checkTier("members", map.members);
+	const owners = new Set(map.owners ?? []);
+	if (
+		owners.size === 0 &&
+		!admitsSomeone(map.admins) &&
+		!admitsSomeone(map.members)
+	)
+		throw new Error(
+			"webAccess: the map admits no one; name owners, or admins or members by user, role, or everyone",
+		);
+	const holds = (tier: WebTierMembers | undefined, identity: WebIdentity) =>
+		tier !== undefined &&
+		(tier.everyone === true ||
+			tier.users?.includes(identity.id) === true ||
+			identity.roles.some((role) => tier.roles?.includes(role)));
+	return {
+		tierOf(identity) {
+			if (owners.has(identity.id)) return "owner";
+			if (holds(map.admins, identity)) return "admin";
+			if (holds(map.members, identity)) return "member";
+			return undefined;
+		},
+	};
+}

package/src/budget.ts

@@ -0,0 +1,74 @@
+/** Turns one conversation may hold at once: the running one and one queued behind it. */
+export const TURNS_PER_CONVERSATION = 2;
+
+/**
+ * The turns each person has running or queued, by conversation. A person holds at most
+ * `perPrincipal` across their conversations, and a conversation at most `TURNS_PER_CONVERSATION`,
+ * so one person cannot keep the shared model busy with many turns at once.
+ */
+export class TurnBudget {
+	readonly #perPrincipal: number;
+	readonly #held = new Map<string, Map<string, number>>();
+
+	constructor(perPrincipal: number) {
+		this.#perPrincipal = perPrincipal;
+	}
+
+	/** Whether the person may start one more turn, in `conversation` when it is named. */
+	allows(principal: string, conversation?: string): boolean {
+		const mine = this.#held.get(principal);
+		let total = 0;
+		for (const count of mine?.values() ?? []) total += count;
+		if (total >= this.#perPrincipal) return false;
+		return (
+			conversation === undefined ||
+			(mine?.get(conversation) ?? 0) < TURNS_PER_CONVERSATION
+		);
+	}
+
+	/** Takes a place for one turn: a function that frees it, once, or undefined over a limit. */
+	take(principal: string, conversation: string): (() => void) | undefined {
+		if (!this.allows(principal, conversation)) return undefined;
+		const mine = this.#held.get(principal) ?? new Map<string, number>();
+		mine.set(conversation, (mine.get(conversation) ?? 0) + 1);
+		this.#held.set(principal, mine);
+		let held = true;
+		return () => {
+			if (!held) return;
+			held = false;
+			const left = (mine.get(conversation) ?? 1) - 1;
+			if (left > 0) mine.set(conversation, left);
+			else mine.delete(conversation);
+			if (mine.size === 0) this.#held.delete(principal);
+		};
+	}
+}
+
+/** At most `limit` events per key in any `perMs` window, as a log of each key's recent events. */
+export class RateWindow {
+	readonly #limit: number;
+	readonly #perMs: number;
+	readonly #now: () => number;
+	readonly #events = new Map<string, number[]>();
+
+	constructor(limit: number, perMs: number, now: () => number) {
+		this.#limit = limit;
+		this.#perMs = perMs;
+		this.#now = now;
+	}
+
+	/** Records one event for `key`; false, recording nothing, when the window is full. */
+	take(key: string): boolean {
+		const now = this.#now();
+		const recent = (this.#events.get(key) ?? []).filter(
+			(at) => at > now - this.#perMs,
+		);
+		if (recent.length >= this.#limit) {
+			this.#events.set(key, recent);
+			return false;
+		}
+		recent.push(now);
+		this.#events.set(key, recent);
+		return true;
+	}
+}