pi-roundtable-webchat 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-16
+
+### Added
+
+- `entraV2Check({ tenant, scope, guests? })` (and the type `EntraV2CheckOptions`): the `check` of `oidcJwtVerifier` for Microsoft Entra ID v2 access tokens of one tenant. It requires `tid` to be the tenant, `ver` to be `"2.0"`, `scp` to list the scope, and `acct` to be `0` or `"0"` (a member); `guests: true` also admits `1` or `"1"`. A token without `acct` is refused either way.
+- The subpath `pi-roundtable-webchat/testing` with `testIssuer` (and the types `TestIssuer`, `TokenSpec`): a self-made OpenID provider on a local port, for tests of a host that verifies tokens. The package now ships `src/testing`; test files stay out.
+- Release in lockstep with pi-roundtable 0.17.0. The core peer range moves to `>=0.17.0 <0.18.0`.
+
 ## [0.16.0] - 2026-10-16
 
 - Release in lockstep with pi-roundtable 0.16.0; no package-specific behavior changes. The core peer range moves to `>=0.16.0 <0.17.0`.

package/README.md

@@ -78,6 +78,7 @@ Every mistake in these options throws when the configuration loads, so `roundtab
 | `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. |
+| `formatting` | What the model is told about how a reply shows, appended to the system prompt of every turn that replies here, after the persona. The default says full Markdown renders, tables included; a text replaces it, for a client that renders less, and `false` tells the model nothing. |
 | `limits` | Overrides of the limits below. |
 
 ### Personas
@@ -143,22 +144,43 @@ Microsoft Entra ID is the example below, and the same questions apply to any pro
 
 - **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.
+- **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` (`entraV2Check` does, or test `claims.scp` yourself); 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: ["<surface>"]` admits every person the verifier accepts on that surface, guest accounts of your tenant included; core `everyone: true` also admits people on every other surface. 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.
 
+`entraV2Check` does the tenant, version, scope and guest checks for Entra ID v2 access tokens:
+
 ```ts
+import { entraV2Check, oidcJwtVerifier } from "pi-roundtable-webchat";
+
 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",
+	check: entraV2Check({ tenant, scope: "access_as_user" }),
 });
 ```
 
+It requires `tid` to equal `tenant`, `ver` to be `"2.0"`, `scp` to list `scope`, and `acct` to be `0` or `"0"`, so a guest or a token without `acct` is refused; `guests: true` also admits `acct` `1`.
+
+### Testing a host that verifies tokens
+
+`pi-roundtable-webchat/testing` exports `testIssuer`, a self-made OpenID provider on a local port with RS256 and ES256 keys:
+
+```ts
+import { testIssuer } from "pi-roundtable-webchat/testing";
+
+const idp = await testIssuer();
+const token = await idp.sign({ claims: { scp: "access_as_user" } });
+// idp.jwksUrl, idp.issuer and idp.audience go into oidcJwtVerifier.
+await idp.close();
+```
+
+`sign({ claims, omit, alg, unknownKey })` signs over the issuer's defaults, and `rotate()` publishes a fresh key set.
+
 ## Connecting
 
 The token is never read from a URL.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-webchat",
-	"version": "0.16.0",
+	"version": "0.17.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",
@@ -8,12 +8,14 @@
 		"bun": ">=1.3.0"
 	},
 	"exports": {
-		".": "./src/index.ts"
+		".": "./src/index.ts",
+		"./testing": "./src/testing/index.ts"
 	},
 	"files": [
 		"src",
 		"!src/**/*.test.ts",
-		"!src/testing",
+		"!src/testing/fakes.ts",
+		"!src/testing/memory-attachments.ts",
 		"LICENSE",
 		"README.md",
 		"CHANGELOG.md"
@@ -36,14 +38,14 @@
 		"jose": "6.2.12"
 	},
 	"peerDependencies": {
-		"pi-roundtable": ">=0.16.0 <0.17.0"
+		"pi-roundtable": ">=0.17.0 <0.18.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.16.0",
+		"pi-roundtable": "0.17.0",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/chat.ts

@@ -97,6 +97,8 @@ export interface WebChatDeps {
 	attachments(): AttachmentPort;
 	turns(): ConversationTurns;
 	runtime(): AgentRuntime;
+	/** What the model is told about how replies render; see `WebChatOptions.formatting`. */
+	formatting?: string | false;
 	/** The clock, in milliseconds; default `Date.now`. */
 	now?(): number;
 }
@@ -250,6 +252,7 @@ export class WebChat {
 			principalOf: (conversation) => this.#owners.get(conversation),
 			send,
 			prompts: this.desk,
+			...(deps.formatting === undefined ? {} : { formatting: deps.formatting }),
 		});
 	}
 

package/src/index.ts

@@ -2,11 +2,13 @@ export type { WebChatLimits, WebPersona } from "./chat.ts";
 export type { ClientCallLimits } from "./client-calls.ts";
 export type { Notice } from "./notices.ts";
 export type {
+	EntraV2CheckOptions,
 	OidcJwtVerifierOptions,
 	TokenVerifier,
 	WebIdentity,
 } from "./oidc.ts";
 export {
+	entraV2Check,
 	identityActor,
 	oidcJwtVerifier,
 	oidcSpeakerId,

package/src/oidc.ts

@@ -278,3 +278,31 @@ export function oidcJwtVerifier(
 		};
 	};
 }
+
+export interface EntraV2CheckOptions {
+	/** The tenant id `tid` must equal. */
+	tenant: string;
+	/** A delegated scope `scp` must list. */
+	scope: string;
+	/** Admit guest accounts (`acct` 1); default false, members only. */
+	guests?: boolean;
+}
+
+/**
+ * The `check` of `oidcJwtVerifier` for Microsoft Entra ID v2 access tokens of one tenant: `tid` is
+ * the tenant, `ver` is "2.0", `scp` lists the scope, and `acct` is 0 (a member) unless guests are
+ * admitted, which also admits 1. Entra writes `acct` as a number or a string; both are read. A
+ * token without `acct` is refused.
+ */
+export function entraV2Check(
+	options: EntraV2CheckOptions,
+): NonNullable<OidcJwtVerifierOptions["check"]> {
+	const { tenant, scope, guests = false } = options;
+	const accounts = guests ? [0, "0", 1, "1"] : [0, "0"];
+	return (claims) =>
+		claims.tid === tenant &&
+		claims.ver === "2.0" &&
+		accounts.includes(claims.acct as string | number) &&
+		typeof claims.scp === "string" &&
+		claims.scp.split(" ").includes(scope);
+}

package/src/plugin.ts

@@ -60,6 +60,13 @@ export interface WebChatOptions {
 	path?: string;
 	/** The key prefix of the conversations; default `web`. Two web chats on one host need two. */
 	surface?: string;
+	/**
+	 * What the model is told, English, about how a reply shows in this chat, appended to the system
+	 * prompt of every turn that replies here, after the persona. The default says full Markdown
+	 * renders, tables included. A text replaces it, for a client that renders less; `false` tells
+	 * the model nothing.
+	 */
+	formatting?: string | false;
 	limits?: Partial<Omit<WebChatLimits & WebChatRouteLimits, "clientCalls">> & {
 		clientCalls?: Partial<ClientCallLimits>;
 	};
@@ -117,6 +124,13 @@ function checkOptions(options: WebChatOptions): {
 		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',
 		);
+	if (
+		typeof options.formatting === "string" &&
+		options.formatting.trim() === ""
+	)
+		throw new Error(
+			"webChat: formatting is empty; write the guidance, or false to give the model none",
+		);
 	return { path, surface };
 }
 
@@ -248,6 +262,9 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 				);
 			const chat = new WebChat({
 				surface,
+				...(options.formatting === undefined
+					? {}
+					: { formatting: options.formatting }),
 				verifier: options.verifier,
 				identity: () => context.services.get(IDENTITY),
 				personas: options.personas,

package/src/surface.ts

@@ -20,8 +20,17 @@ export interface WebSurfaceOptions {
 	/** Sends a frame to every connection of a person. */
 	send(principal: string, frame: ServerFrame): void;
 	prompts: PromptDesk;
+	/** What the model is told about how replies render; `false` tells it nothing. Default: full Markdown. */
+	formatting?: string | false;
 }
 
+/**
+ * What the model is told about the web chat's rendering, as the surface's `formatting`. English:
+ * it is model-facing text, not a message-catalog string.
+ */
+const WEB_FORMATTING =
+	"Reply formatting (web chat): full Markdown renders, including tables, headings, lists, quotes, links, inline code and fenced code blocks.";
+
 /**
  * The web conversations as a chat surface: what the host shows in a conversation goes to every
  * open connection of its person, as JSON frames. A reply is sent whole, in markdown, with its
@@ -30,11 +39,16 @@ export interface WebSurfaceOptions {
 export class WebSurface implements ChatSurface {
 	readonly surface: string;
 	readonly supportsFiles = true;
+	readonly formatting: string | undefined;
 	readonly #options: WebSurfaceOptions;
 	#deliver: ((message: InboundMessage) => void) | undefined;
 
 	constructor(options: WebSurfaceOptions) {
 		this.surface = options.surface;
+		this.formatting =
+			options.formatting === false
+				? undefined
+				: (options.formatting ?? WEB_FORMATTING);
 		this.#options = options;
 	}
 

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export type { TestIssuer, TokenSpec } from "./issuer.ts";
+export { testIssuer } from "./issuer.ts";

package/src/testing/issuer.ts

@@ -0,0 +1,112 @@
+import {
+	type CryptoKey,
+	exportJWK,
+	generateKeyPair,
+	type JWK,
+	type JWTPayload,
+	SignJWT,
+} from "jose";
+
+/** A token to sign: the claims, and how to sign them. */
+export interface TokenSpec {
+	/** Claims over the issuer's defaults (iss, aud, sub, name, roles, iat, exp an hour ahead). */
+	claims?: JWTPayload & Record<string, unknown>;
+	/** Claims to leave out of the defaults. */
+	omit?: readonly string[];
+	/** Default RS256, the issuer's main key. */
+	alg?: "RS256" | "ES256";
+	/** Signs with a key the JWKS does not publish. */
+	unknownKey?: boolean;
+}
+
+/** A self-made OpenID provider: signing keys and a JWKS served on a local port. */
+export interface TestIssuer {
+	readonly issuer: string;
+	readonly audience: string;
+	readonly jwksUrl: string;
+	/** How many times the JWKS was fetched. */
+	readonly fetches: number;
+	sign(spec?: TokenSpec): Promise<string>;
+	/** Publishes a fresh key set without the old keys, as a provider rotating its keys. */
+	rotate(): Promise<void>;
+	close(): Promise<void>;
+}
+
+interface KeyPair {
+	kid: string;
+	alg: "RS256" | "ES256";
+	privateKey: CryptoKey;
+	jwk: JWK;
+}
+
+async function keyPair(alg: "RS256" | "ES256", kid: string): Promise<KeyPair> {
+	const { privateKey, publicKey } = await generateKeyPair(alg, {
+		extractable: true,
+	});
+	return {
+		kid,
+		alg,
+		privateKey,
+		jwk: { ...(await exportJWK(publicKey)), kid, alg, use: "sig" },
+	};
+}
+
+let generation = 0;
+
+/** Starts a provider on 127.0.0.1 with an RS256 and an ES256 key. */
+export async function testIssuer(
+	options: { issuer?: string; audience?: string } = {},
+): Promise<TestIssuer> {
+	let keys = [
+		await keyPair("RS256", `rs-${++generation}`),
+		await keyPair("ES256", `es-${generation}`),
+	];
+	const stray = await keyPair("RS256", "stray");
+	let fetches = 0;
+	const server = Bun.serve({
+		hostname: "127.0.0.1",
+		port: 0,
+		fetch: () => {
+			fetches += 1;
+			return Response.json({ keys: keys.map((key) => key.jwk) });
+		},
+	});
+	const issuer = options.issuer ?? "https://login.example.test/tenant/v2.0";
+	const audience = options.audience ?? "api://webchat-test";
+	return {
+		issuer,
+		audience,
+		jwksUrl: `http://127.0.0.1:${server.port}/keys`,
+		get fetches() {
+			return fetches;
+		},
+		async sign(spec = {}) {
+			const alg = spec.alg ?? "RS256";
+			const key = spec.unknownKey
+				? stray
+				: (keys.find((k) => k.alg === alg) as KeyPair);
+			const now = Math.floor(Date.now() / 1000);
+			const claims: Record<string, unknown> = {
+				iss: issuer,
+				aud: audience,
+				sub: "subject-1",
+				name: "Ada",
+				roles: ["Chat.User"],
+				iat: now,
+				exp: now + 3600,
+				...spec.claims,
+			};
+			for (const name of spec.omit ?? []) delete claims[name];
+			return new SignJWT(claims)
+				.setProtectedHeader({ alg, kid: key.kid, typ: "JWT" })
+				.sign(key.privateKey);
+		},
+		async rotate() {
+			keys = [
+				await keyPair("RS256", `rs-${++generation}`),
+				await keyPair("ES256", `es-${generation}`),
+			];
+		},
+		close: () => server.stop(true),
+	};
+}