@schlessera/brain-ui-server 0.34.0 → 0.35.0

package/src/ws/bridge.ts

@@ -114,8 +114,20 @@ export function makeBridge(
         // The decision stamps the wait/execution boundary on the tool span
         // (grant) or lands the denied outcome (deny) before the backend's
         // own error tool_result can mislabel it — write-once protects it.
-        const recorded = (decision: PermissionDecision) => {
-          recorder?.onApprovalDecision(req.toolUseId, decision.behavior === "allow");
+        const recorded = (
+          decision: PermissionDecision,
+          response?: { principalId: string; always?: boolean }
+        ) => {
+          recorder?.onApprovalDecision(
+            req.toolUseId,
+            decision.behavior === "deny"
+              ? "deny"
+              : response?.always
+                ? "always_allow"
+                : "allow",
+            req.kind ?? "tool",
+            response?.principalId
+          );
           resolve(decision);
         };
         coordinator.pendingApprovals.set(req.toolUseId, {

package/src/ws/clients.ts

@@ -12,6 +12,12 @@ export type WSContext = {
   raw?: unknown;
 };
 
+interface AttachedClient {
+  ws: WSContext;
+  principalId: string;
+  onRemove?: () => void;
+}
+
 function canSendRaw(raw: unknown): raw is { send: (data: string) => unknown } {
   return (
     typeof raw === "object" && raw !== null && "send" in raw && typeof raw.send === "function"
@@ -34,19 +40,27 @@ export class ClientSet {
   // Hono creates a new WSContext for every Bun open/message/close callback.
   // The raw socket remains stable across those wrappers, so it is the identity
   // that admission and removal must share.
-  private readonly clients = new Map<unknown, WSContext>();
+  private readonly clients = new Map<unknown, AttachedClient>();
 
-  constructor(readonly maxConnections = 32) {}
+  constructor(
+    readonly maxConnections = 32,
+    private readonly invalidateAuthorizations: (
+      principalIds: ReadonlySet<string>
+    ) => void = () => {}
+  ) {}
 
-  add(ws: WSContext): boolean {
+  add(ws: WSContext, principalId: string, options?: { onRemove?: () => void }): boolean {
     const identity = ws.raw ?? ws;
     if (!this.clients.has(identity) && this.clients.size >= this.maxConnections) return false;
-    this.clients.set(identity, ws);
+    this.clients.set(identity, { ws, principalId, ...options });
     return true;
   }
 
   remove(ws: WSContext): void {
-    this.clients.delete(ws.raw ?? ws);
+    const identity = ws.raw ?? ws;
+    const client = this.clients.get(identity);
+    this.clients.delete(identity);
+    client?.onRemove?.();
   }
 
   count(): number {
@@ -62,6 +76,32 @@ export class ClientSet {
     return this.clients.size > 0;
   }
 
+  /**
+   * Close and forget only sockets admitted for one principal.
+   */
+  closeFor(principalId: string, code: number, reason: string): void {
+    const closing: AttachedClient[] = [];
+    // Same boundary as closeAll: invalidate through the coordinator FIRST,
+    // while the socket-owned references still make every pending dispatch
+    // discoverable. Releasing them first would let a frame parsed before this
+    // call start a turn after it — measured as 0 starts before this became a
+    // registry, 1 after.
+    this.invalidateAuthorizations(new Set([principalId]));
+    for (const [identity, client] of this.clients) {
+      if (client.principalId !== principalId) continue;
+      this.clients.delete(identity);
+      client.onRemove?.();
+      closing.push(client);
+    }
+    for (const { ws } of closing) {
+      try {
+        ws.close?.(code, reason);
+      } catch {
+        // Best effort per socket; revocation of sibling sockets must continue.
+      }
+    }
+  }
+
   /**
    * Close and forget every attached socket. The set is cleared before close
    * callbacks can run, and one broken socket cannot prevent the others from
@@ -69,8 +109,13 @@ export class ClientSet {
    */
   closeAll(code: number, reason: string): void {
     const clients = [...this.clients.values()];
+    // Forced closure is also an authorization boundary. Invalidate through
+    // the coordinator while socket-owned references still keep every pending
+    // dispatch discoverable; the loop below remains transport cleanup only.
+    this.invalidateAuthorizations(new Set(clients.map((client) => client.principalId)));
     this.clients.clear();
-    for (const ws of clients) {
+    for (const client of clients) client.onRemove?.();
+    for (const { ws } of clients) {
       try {
         ws.close?.(code, reason);
       } catch {
@@ -88,7 +133,7 @@ export class ClientSet {
   broadcast(msg: ServerMessage, onSendError?: (err: unknown) => void): void {
     if (this.clients.size === 0) return;
     const payload = JSON.stringify(shrinkForReplication(msg));
-    for (const ws of this.clients.values()) {
+    for (const { ws } of this.clients.values()) {
       try {
         // Bun's ServerWebSocket reports a dropped write by RETURNING 0 (closed
         // connection) rather than throwing, and hono's WSContext.send discards

package/src/ws/connection.ts

@@ -1,8 +1,11 @@
 import { upgradeWebSocket, websocket } from "hono/bun";
+import type { MiddlewareHandler } from "hono";
 import { PROTOCOL_REV } from "@schlessera/brain-ui-sdk/protocol";
 import { parseClientMessage } from "@schlessera/brain-ui-sdk/schemas";
 import { withTurnScope } from "./frames.js";
 import type { WSContext as WSContextType } from "./clients.js";
+import type { Principal } from "../db/principals.js";
+import type { AppEnv } from "../app-env.js";
 
 /**
  * Re-send every pending approval and ask-user card to a client that just
@@ -51,6 +54,8 @@ export { websocket };
 
 const CONNECTION_LIMIT_CLOSE_CODE = 4008;
 const CONNECTION_LIMIT_CLOSE_REASON = "Connection limit reached";
+const REVOKED_BEFORE_ADMISSION_CLOSE_CODE = 1008;
+const REVOKED_BEFORE_ADMISSION_CLOSE_REASON = "Sessions invalidated";
 
 /**
  * The socket lifecycle handlers for one host, separate from the Hono upgrade
@@ -61,17 +66,35 @@ const CONNECTION_LIMIT_CLOSE_REASON = "Connection limit reached";
  * production runs, which is what makes an assertion about a dropped frame an
  * assertion about the shipped code rather than about a re-implementation.
  */
-export function createWsHandlers(host: WsHost) {
+export function createWsHandlers(host: WsHost, principal: Principal) {
   // One bucket per connection, created here so it lives and dies with the
   // socket rather than in a map keyed by something a peer controls.
   const limiter = host.newRateLimiter();
+  // Authentication can await before it reaches this handler. Re-read durable
+  // validity as the coordinator constructs and synchronously registers the
+  // context, so there is no unregistered authorization state to lose.
+  const authorization = host.coordinator.openAuthorization({
+    principalId: principal.id,
+    expiresAt: principal.expiresAt,
+    valid: host.isPrincipalValid(principal),
+  });
   // Per-connection negotiation state: what revision this client declared.
   // Lives with the socket, like the limiter.
-  const connection: ConnectionState = {};
-
+  const connection: ConnectionState = {
+    principal,
+    authorization,
+  };
   return {
     async onOpen(_evt: Event, ws: WSContext) {
-      if (!host.clients.add(ws)) {
+      if (!connection.authorization.valid) {
+        connection.authorization.release();
+        ws.close!(REVOKED_BEFORE_ADMISSION_CLOSE_CODE, REVOKED_BEFORE_ADMISSION_CLOSE_REASON);
+        return;
+      }
+      if (
+        !host.clients.add(ws, principal.id, { onRemove: connection.authorization.release })
+      ) {
+        connection.authorization.release();
         host.reportRefusedConnection();
         // Hono's WSContext always exposes close(); the local structural socket
         // type keeps it optional because send-only test/dispatch fakes never
@@ -121,12 +144,17 @@ export function createWsHandlers(host: WsHost) {
             turn
           )
         );
+        // Snapshot-on-connect owns a lease separate from the socket: a close
+        // while history loads must not make this work invisible to revocation.
+        const releaseAuthorization = connection.authorization.retain();
         try {
           const backend = await host.registry.getBackendForSession(
             catalog.getStoredBackendId(sid) ?? turn.backend.id
           );
           const history = await backend.getHistory(sid);
-          if (history.length > 0) sendSessionHistory(ws, sid, history);
+          if (connection.authorization.valid && history.length > 0) {
+            sendSessionHistory(ws, sid, history);
+          }
         } catch (err) {
           host.log.emit({
             severityText: "ERROR",
@@ -134,19 +162,22 @@ export function createWsHandlers(host: WsHost) {
             attributes: { error: err instanceof Error ? err.message : String(err) },
           });
         } finally {
-          host.sendMessage(
-            ws,
-            withTurnScope(
-              {
-                type: "status",
-                status: "thinking",
-                detail: "Session in progress",
-                sessionId: sid,
-              },
-              turn
-            )
-          );
-          resendPendingInteractive(host, ws);
+          releaseAuthorization();
+          if (connection.authorization.valid) {
+            host.sendMessage(
+              ws,
+              withTurnScope(
+                {
+                  type: "status",
+                  status: "thinking",
+                  detail: "Session in progress",
+                  sessionId: sid,
+                },
+                turn
+              )
+            );
+            resendPendingInteractive(host, ws);
+          }
         }
         return;
       }
@@ -160,6 +191,16 @@ export function createWsHandlers(host: WsHost) {
     },
 
     onMessage(evt: MessageEvent, ws: WSContext) {
+      if (
+        connection.authorization.valid &&
+        connection.authorization.expiresAt <= Date.now()
+      ) {
+        host.expireAuthorizationContexts();
+      }
+      if (!connection.authorization.valid) {
+        host.reportDroppedFrame("revoked_principal");
+        return;
+      }
       // Boundary validation (rev 2): byte cap + JSON decode + schema, in one
       // place. No more casting client JSON to ClientMessage.
       //
@@ -197,6 +238,12 @@ export function createWsHandlers(host: WsHost) {
         host.sendMessage(ws, { type: "error", code: "PARSE_ERROR", message: parsed.error });
         return;
       }
+      // Parsing is synchronous, but dispatch deliberately starts on a
+      // microtask. Keep this shared authority discoverable across that gap —
+      // including after an ordinary disconnect removes the admitted client.
+      // runSession adds its own reference before this one is released, so a
+      // chat startup remains continuously revocable through routing/billing.
+      const releaseAuthorization = connection.authorization.retain();
       // handleClientMessage is async — a rejection must not escape as an
       // unhandled rejection with no frame sent.
       void Promise.resolve()
@@ -217,10 +264,19 @@ export function createWsHandlers(host: WsHost) {
             code: "INTERNAL_ERROR",
             message: "Failed to handle message",
           });
+        })
+        .finally(() => {
+          releaseAuthorization();
         });
     },
 
     onClose(evt: CloseEvent, ws: WSContext) {
+      // Closure is not authorization: a frame parsed before this callback can
+      // still be mid-dispatch, and an activity_subscribe landing after the
+      // cleanup below would re-register the dead socket and keep the activity
+      // poller awake. Authorization stays whatever it is; this says the
+      // transport is gone.
+      connection.closed = true;
       host.log.emit({ severityText: "INFO", body: "client disconnected" });
       // No onError here on purpose: hono's Bun adapter never dispatches it
       // (only open/message/close reach these handlers), so a transport failure
@@ -232,6 +288,7 @@ export function createWsHandlers(host: WsHost) {
         host.reportAbnormalClose(code);
       }
       host.clients.remove(ws);
+      connection.authorization.release();
       host.activity?.stream.dropConnection(ws);
       // Turns keep running in the background. Once the LAST client leaves,
       // reject only the requests that need a live client RIGHT NOW (location,
@@ -244,10 +301,31 @@ export function createWsHandlers(host: WsHost) {
         host.coordinator.drainClientBoundForTurn(turn, "Client disconnected");
       }
     },
+
+    /** The HTTP upgrade failed, so no socket lifecycle callback will clean up. */
+    onUpgradeFailed() {
+      connection.authorization.release();
+    },
   };
 }
 
 /** Build the Hono WebSocket upgrade handler bound to one host. */
-export function createWsUpgrade(host: WsHost) {
-  return upgradeWebSocket(() => createWsHandlers(host));
+export function createWsUpgrade(host: WsHost): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const principal = c.get("principal");
+    if (!principal) {
+      return c.json({ error: "Authentication required" }, 401);
+    }
+    const handlers = createWsHandlers(host, principal);
+    const upgrade = upgradeWebSocket(() => handlers);
+    try {
+      return await upgrade(c, async () => {
+        handlers.onUpgradeFailed();
+        await next();
+      });
+    } catch (err) {
+      handlers.onUpgradeFailed();
+      throw err;
+    }
+  };
 }

package/src/ws/dispatch.ts

@@ -1,6 +1,7 @@
 import { PROTOCOL_REV_CLIENT_ECHO } from "@schlessera/brain-ui-sdk/protocol";
 import type { ClientMessage } from "@schlessera/brain-ui-sdk/protocol";
 import type { WSContext } from "./clients.js";
+import type { AuthorizationContext } from "./turns.js";
 import { locationErrorText } from "./frames.js";
 import { sendSessionHistory } from "./history.js";
 import { validateAttachments } from "./attachments.js";
@@ -9,6 +10,16 @@ import type { WsHost } from "./host.js";
 
 /** Per-connection negotiation state, owned by the socket handler. */
 export interface ConnectionState {
+  /**
+   * The transport is gone. Set by onClose, and separate from `authorization`
+   * because a disconnect is not a revocation: work already underway keeps its
+   * authority, but nothing may register new per-connection state afterwards.
+   */
+  closed?: boolean;
+  /** Principal resolved once at the WebSocket upgrade boundary. */
+  principal: import("../db/principals.js").Principal;
+  /** Mutable in-memory decision invalidated synchronously by revocation. */
+  authorization: AuthorizationContext;
   /** Revision the client declared via `client_hello`; absent means rev 2. */
   protocolRev?: number;
 }
@@ -39,8 +50,21 @@ export async function handleClientMessage(
   host: WsHost,
   ws: WSContext,
   msg: ClientMessage,
-  connection: ConnectionState = {}
+  connection: ConnectionState
 ): Promise<void> {
+  // The socket callback schedules dispatch on a microtask. Revocation may land
+  // after parsing but before this function begins, so repeat the in-memory
+  // check at the actual dispatch boundary.
+  if (
+    connection.authorization.valid &&
+    connection.authorization.expiresAt <= Date.now()
+  ) {
+    host.expireAuthorizationContexts();
+  }
+  if (!connection.authorization.valid) {
+    host.reportDroppedFrame("revoked_principal");
+    return;
+  }
   const { coordinator, catalog } = host;
   const requireEcho = (connection.protocolRev ?? 2) >= PROTOCOL_REV_CLIENT_ECHO;
   switch (msg.type) {
@@ -64,11 +88,13 @@ export async function handleClientMessage(
         return;
       }
       await handleChatMessage(host, ws, {
+        authorization: connection.authorization,
         text: msg.text,
         sessionId: msg.sessionId,
         attachments: attachmentResult.attachments,
         providerId: msg.providerId,
         client: msg.client,
+        draftId: msg.draftId,
       });
       break;
     }
@@ -77,6 +103,9 @@ export async function handleClientMessage(
       const pending = coordinator.pendingAskUser.get(msg.requestId);
       if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
         coordinator.pendingAskUser.delete(msg.requestId);
+        pending.turn.recorder?.recordAskUserResponse(
+          connection.authorization.principalId
+        );
         pending.resolve({ answers: msg.answers, annotations: msg.annotations });
       }
       break;
@@ -86,6 +115,10 @@ export async function handleClientMessage(
       const pending = coordinator.pendingAskUser.get(msg.requestId);
       if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
         coordinator.pendingAskUser.delete(msg.requestId);
+        pending.turn.recorder?.recordCancellation(
+          connection.authorization.principalId,
+          "ask_user"
+        );
         pending.reject(new Error(msg.reason || "User cancelled the question"));
       }
       break;
@@ -147,7 +180,11 @@ export async function handleClientMessage(
         pending.resolve(
           msg.updatedInput
             ? { behavior: "allow", updatedInput: msg.updatedInput }
-            : { behavior: "allow" }
+            : { behavior: "allow" },
+          {
+            principalId: connection.authorization.principalId,
+            ...(msg.always && pending.request.kind !== "command" ? { always: true } : {}),
+          }
         );
       }
       break;
@@ -157,7 +194,10 @@ export async function handleClientMessage(
       const pending = coordinator.pendingApprovals.get(msg.toolUseId);
       if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
         coordinator.pendingApprovals.delete(msg.toolUseId);
-        pending.resolve({ behavior: "deny", message: msg.message });
+        pending.resolve(
+          { behavior: "deny", message: msg.message },
+          { principalId: connection.authorization.principalId }
+        );
       }
       break;
     }
@@ -165,7 +205,18 @@ export async function handleClientMessage(
     case "cancel": {
       if (msg.sessionId) {
         const turn = coordinator.bySession.get(msg.sessionId);
-        if (turn) coordinator.cancelTurn(turn, "Cancelled by user");
+        if (turn) {
+          coordinator.recordCancellation(turn, connection.authorization.principalId);
+          coordinator.cancelTurn(turn, "Cancelled by user");
+        }
+        const starting = coordinator.startingBySession.get(msg.sessionId);
+        if (starting) {
+          starting.cancelled = true;
+          // Releasing here, not in runSession: a start cancelled before it
+          // becomes a turn never reaches the loop that would drain its queue.
+          for (const entry of starting.queue.splice(0)) entry.releaseAuthorization();
+          host.sendToClients({ type: "status", status: "idle", sessionId: msg.sessionId, detail: "Cancelled before starting" });
+        }
         return;
       }
       // No sessionId: cancel the sole running session; ambiguous if several run.
@@ -178,7 +229,9 @@ export async function handleClientMessage(
         });
         return;
       }
-      coordinator.cancelTurn([...coordinator.running][0], "Cancelled by user");
+      const turn = [...coordinator.running][0]!;
+      coordinator.recordCancellation(turn, connection.authorization.principalId);
+      coordinator.cancelTurn(turn, "Cancelled by user");
       break;
     }
 
@@ -186,7 +239,13 @@ export async function handleClientMessage(
       // View-scoped opt-in: without a subscription this connection never
       // receives an activity frame. No turn correlation — subscriptions are
       // connection state, not turn state.
-      host.activity?.stream.handleSubscribe(ws, msg);
+      //
+      // Dispatch starts on a microtask, so this can run after onClose already
+      // dropped the connection's subscriptions. Registering here would resurrect
+      // a dead socket in the registry and keep the activity poller alive for the
+      // life of the process.
+      if (connection.closed) break;
+      host.activity?.stream.handleSubscribe(ws, msg, connection.authorization.principalId);
       break;
     }
 
@@ -207,6 +266,7 @@ export async function handleClientMessage(
       try {
         const backend = await host.registry.getBackendForSession(catalog.getStoredBackendId(msg.sessionId));
         const messages = await backend.getHistory(msg.sessionId);
+        if (!connection.authorization.valid) return;
         sendSessionHistory(ws, msg.sessionId, messages);
         // A resume of a RUNNING session (reattach) must not report idle: idle
         // would clear the client's running badge and finish its streaming

package/src/ws/history.ts

@@ -1,6 +1,6 @@
 import type { SessionHistoryMessage } from "@schlessera/brain-ui-sdk/protocol";
 import { type WSContext, sendTo } from "./clients.js";
-import { HISTORY_CHUNK_BYTES, shrinkForReplication } from "./shrink.js";
+import { HISTORY_CHUNK_BYTES, jsonBytes, shrinkForReplication } from "./shrink.js";
 
 /**
  * Send a structured history to one socket as one or more `session_history`
@@ -20,8 +20,7 @@ export function sendSessionHistory(
   sessionId: string,
   messages: SessionHistoryMessage[]
 ): void {
-  const bounded = messages.map((m) => shrinkForReplication(m));
-  if (bounded.length === 0) {
+  if (messages.length === 0) {
     sendTo(ws, { type: "session_history", sessionId, messages: [] });
     return;
   }
@@ -41,8 +40,11 @@ export function sendSessionHistory(
     batchBytes = 0;
   };
 
-  for (const message of bounded) {
-    const size = JSON.stringify(message).length;
+  for (const original of messages) {
+    // Reserve the frame wrapper separately: bounding a message to the entire
+    // frame cap caused sendTo to shrink its parent history array a second time.
+    const message = shrinkForReplication(original, HISTORY_CHUNK_BYTES);
+    const size = jsonBytes(message) + 1; // comma between messages
     if (batch.length > 0 && batchBytes + size > HISTORY_CHUNK_BYTES) flush();
     batch.push(message);
     batchBytes += size;

package/src/ws/host.ts

@@ -7,11 +7,15 @@ import { createSilentObservability, type Observability } from "../observability/
 import { FrameRateLimiter } from "./rate-limit.js";
 import type { ActivityStore } from "../activity/store.js";
 import type { ActivityStream } from "../activity/stream.js";
+import type { PushSender } from "../activity/push-sender.js";
+import type { Principal } from "../db/principals.js";
 
 /** The activity record and its live stream, when the host records activity. */
 export interface ActivityRuntime {
   store: ActivityStore;
   stream: ActivityStream;
+  /** Push bindings invalidated through the same principal-revocation boundary. */
+  pushSender?: Pick<PushSender, "unbindPrincipal">;
   /** Read seam for the agent-facing query tool (bridge.queryActivity). */
   query?: (query: import("@schlessera/brain-ui-sdk/server").ActivityQuery) => Record<string, unknown>;
 }
@@ -21,6 +25,9 @@ const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 
 /** Default cap on concurrently RUNNING sessions (MAX_CONCURRENT_SESSIONS). */
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 3;
+const AUTHORIZATION_EXPIRY_SWEEP_MS = 1_000;
+const SESSION_EXPIRED_CLOSE_CODE = 1008;
+const SESSION_EXPIRED_CLOSE_REASON = "Session expired";
 
 /**
  * Budget for the host-side follow-up queue of ONE session (backends without a
@@ -77,6 +84,13 @@ export interface WsHostOptions {
   wsRate?: { ratePerSecond: number; burst: number };
   /** Maximum WebSocket connections accepted by this host (default 32). */
   wsMaxConnections?: number;
+  /**
+   * Final synchronous check before a resolved principal becomes discoverable
+   * to in-memory revocation. Production re-reads the principal row here; a
+   * host without durable authentication (including focused tests) accepts the
+   * already-resolved principal.
+   */
+  isPrincipalValid?: (principal: Principal) => boolean;
   /**
    * Activity recording (span store + live stream). Optional: a host without
    * one records nothing and never sends activity frames — which is also what
@@ -134,6 +148,7 @@ export class WsHost {
   maxConcurrentSessions: () => number;
   readonly observability: Observability;
   readonly wsRate: { ratePerSecond: number; burst: number } | null;
+  readonly isPrincipalValid: (principal: Principal) => boolean;
   readonly activity: ActivityRuntime | null;
   readonly toolPermissions: ToolPermissions | null;
   /** Scoped instruments, resolved once — `[ws]` is the existing log prefix. */
@@ -156,9 +171,12 @@ export class WsHost {
   private readonly connectionsRefused: ReturnType<
     ReturnType<Observability["meter"]>["createCounter"]
   >;
+  private readonly authorizationExpiryTimer: ReturnType<typeof setInterval>;
 
   constructor(options: WsHostOptions) {
-    this.clients = new ClientSet(options.wsMaxConnections);
+    this.clients = new ClientSet(options.wsMaxConnections, (principalIds) => {
+      this.coordinator.invalidateAuthorizations(principalIds);
+    });
     this.registry = options.registry;
     this.catalog = options.catalog;
     this.appName = options.appName ?? "Brain UI";
@@ -168,6 +186,7 @@ export class WsHost {
     this.observability = options.observability ?? createSilentObservability();
     this.wsRate =
       options.wsRate && options.wsRate.ratePerSecond > 0 ? options.wsRate : null;
+    this.isPrincipalValid = options.isPrincipalValid ?? (() => true);
     this.activity = options.activity ?? null;
     this.toolPermissions = options.toolPermissions ?? null;
     this.log = this.observability.logger("ws");
@@ -191,6 +210,11 @@ export class WsHost {
       description: "WebSocket connections refused before admission",
     });
     this.coordinator.log = this.log;
+    this.authorizationExpiryTimer = setInterval(
+      () => this.expireAuthorizationContexts(),
+      AUTHORIZATION_EXPIRY_SWEEP_MS
+    );
+    this.authorizationExpiryTimer.unref?.();
   }
 
   /** A metering bucket for one new connection, or null when metering is off. */
@@ -300,6 +324,40 @@ export class WsHost {
     });
   }
 
+  /**
+   * Apply principal-store revocation to every in-memory authority boundary.
+   * Running turns are marked but deliberately not aborted.
+   */
+  revokePrincipals(principalIds: readonly string[], code: number, reason: string): void {
+    const revoked = new Set(principalIds);
+    if (revoked.size === 0) return;
+    const affectedRunning = this.coordinator.revokePrincipals(revoked);
+    for (const principalId of revoked) {
+      this.clients.closeFor(principalId, code, reason);
+      this.activity?.stream.dropFor(principalId);
+      this.activity?.pushSender?.unbindPrincipal(principalId);
+    }
+    for (const turn of affectedRunning) {
+      turn.recorder?.recordPrincipalRevocation(turn.principalId);
+    }
+  }
+
+  /** Route expiry through the same full boundary as explicit revocation. */
+  expireAuthorizationContexts(now = Date.now()): void {
+    const expired = new Set<string>();
+    this.coordinator.collectExpiredPrincipalIds(now, expired);
+    this.revokePrincipals(
+      [...expired],
+      SESSION_EXPIRED_CLOSE_CODE,
+      SESSION_EXPIRED_CLOSE_REASON
+    );
+  }
+
+  /** Stop host-owned timers during application/test teardown. */
+  close(): void {
+    clearInterval(this.authorizationExpiryTimer);
+  }
+
   /** Send a frame to one specific socket (size-bounded). */
   sendMessage(ws: WSContext, msg: ServerMessage): void {
     sendTo(ws, msg);