@staix/agent-hub 0.20.0 → 0.21.0

package/src/adapters/registry-types.ts

@@ -72,6 +72,8 @@ export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
   instance: string;
   projectRoot: string;
   stateDir: string;
+  /** Host-derived private external-instance state namespace; stateDir remains the canonical daemon control directory. */
+  instanceStateDir?: string;
   kindConfig: unknown;
   permission: PermissionMode | "read-only";
   mcpServers: NonNullable<AcpOptions["mcpServers"]>;
@@ -207,6 +209,8 @@ export interface AdapterDefinition {
     conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
   };
   identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin"; currentChild?: true };
+  /** External module data-only opt-in. The verified loader derives the internal instances policy from it (#754). */
+  headlessInstances?: { form: "headless"; roles: readonly ("implementer" | "verifier" | "reviewer")[] };
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
   instances?: { mode: "external" | "headless"; roles?: readonly string[];
     /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */

package/src/broker/protocol.ts

@@ -0,0 +1,203 @@
+/** Broker v1 control protocol. The broker verifies public signatures and never opens room ciphertext. */
+import {
+  decodeBase64url, encodeBase64url, signBytes, verifyBytes,
+  type HubIdentity,
+} from "../rooms/crypto.ts";
+import {
+  brokerUrl, canonicalBytes, decodeRoster, publicRosterWire, verifyPublicRoster,
+  type OwnerPin, type VerifiedPublicRoster,
+} from "../rooms/wire.ts";
+
+export const BROKER_CONTROL_LIMITS = Object.freeze({ control: 1_048_576, challenge: 8192, nonceBytes: 32 });
+export type BrokerProtocolCode = "invalid_wire" | "limit" | "untrusted" | "expired" | "authentication_failed";
+export class BrokerProtocolError extends Error {
+  constructor(readonly code: BrokerProtocolCode) { super(`Broker protocol: ${code}`); this.name = "BrokerProtocolError"; }
+}
+function fail(code: BrokerProtocolCode = "invalid_wire"): never { throw new BrokerProtocolError(code); }
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const FP = /^[0-9a-f]{64}$/;
+const DIGEST = /^[A-Za-z0-9_-]{43}$/;
+const B64URL = /^[A-Za-z0-9_-]+$/;
+
+export interface BrokerChallenge {
+  v: 1;
+  type: "challenge";
+  room: string;
+  broker: string;
+  nonce: string;
+  expiresAt: number;
+  rosterDigest: string | null;
+}
+export interface BrokerAuth {
+  v: 1;
+  type: "auth";
+  member: string;
+  roster: string | null;
+  signature: string;
+}
+export interface BrokerRosterReady { v: 1; type: "roster_ready"; digest: string }
+export interface BrokerReceived { v: 1; type: "received"; digest: string }
+export type BrokerControl = BrokerAuth | BrokerRosterReady | BrokerReceived;
+
+function record(x: unknown, keys: string[]): Record<string, unknown> {
+  if (typeof x !== "object" || x === null || Array.isArray(x) || Object.getPrototypeOf(x) !== Object.prototype) fail();
+  const value = x as Record<string, unknown>;
+  if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key))) fail();
+  return value;
+}
+function canonicalDecode<T>(input: Uint8Array, max: number, parse: (value: unknown) => T): T {
+  if (!(input instanceof Uint8Array) || input.length === 0 || input.length > max) fail("limit");
+  let raw: unknown;
+  try { raw = JSON.parse(decoder.decode(input)); } catch { fail(); }
+  const value = parse(raw), bytes = canonicalBytes(value);
+  if (bytes.length !== input.length || bytes.some((byte, i) => input[i] !== byte)) fail();
+  return value;
+}
+function exactText(x: unknown, pattern: RegExp): string {
+  if (typeof x !== "string" || !pattern.test(x)) fail();
+  return x;
+}
+function roomId(x: unknown): string {
+  if (typeof x !== "string" || x.length !== 43 || !B64URL.test(x)) fail();
+  try { decodeBase64url(x, 32); } catch { fail(); }
+  return x;
+}
+function digestText(x: unknown): string {
+  const value = exactText(x, DIGEST);
+  try { decodeBase64url(value, 32); } catch { fail(); }
+  return value;
+}
+function timestamp(x: unknown): number {
+  if (typeof x !== "number" || !Number.isSafeInteger(x) || x <= 0) fail();
+  return x;
+}
+function nullableDigest(x: unknown): string | null { return x === null ? null : digestText(x); }
+function brokerAudience(value: unknown): string {
+  try {
+    const normalized = brokerUrl(value), url = new URL(normalized);
+    if (url.pathname !== "/" || url.search) fail();
+    return normalized;
+  } catch { return fail(); }
+}
+function parseChallenge(x: unknown): BrokerChallenge {
+  const o = record(x, ["v", "type", "room", "broker", "nonce", "expiresAt", "rosterDigest"]);
+  if (o.v !== 1 || o.type !== "challenge") fail();
+  const nonce = exactText(o.nonce, B64URL);
+  try { decodeBase64url(nonce, BROKER_CONTROL_LIMITS.nonceBytes); } catch { fail(); }
+  return { v: 1, type: "challenge", room: roomId(o.room), broker: brokerAudience(o.broker), nonce,
+    expiresAt: timestamp(o.expiresAt), rosterDigest: nullableDigest(o.rosterDigest) };
+}
+function parseAuth(x: unknown): BrokerAuth {
+  const o = record(x, ["v", "type", "member", "roster", "signature"]);
+  if (o.v !== 1 || o.type !== "auth") fail();
+  let roster: string | null = null;
+  if (o.roster !== null) {
+    roster = exactText(o.roster, B64URL);
+    if (roster.length > Math.ceil(524288 * 4 / 3)) fail("limit");
+    let wire: Uint8Array;
+    try { wire = decodeBase64url(roster); } catch { fail(); }
+    decodeRoster(wire);
+  }
+  const signature = exactText(o.signature, B64URL);
+  try { decodeBase64url(signature, 64); } catch { fail(); }
+  return { v: 1, type: "auth", member: exactText(o.member, FP), roster, signature };
+}
+function parseControl(x: unknown): BrokerControl {
+  if (typeof x !== "object" || x === null || Array.isArray(x)) fail();
+  const type = (x as Record<string, unknown>).type;
+  if (type === "auth") return parseAuth(x);
+  if (type === "roster_ready" || type === "received") {
+    const o = record(x, ["v", "type", "digest"]);
+    if (o.v !== 1 || o.type !== type) fail();
+    return { v: 1, type: type as "roster_ready" | "received", digest: digestText(o.digest) };
+  }
+  fail();
+}
+function challengeBytes(challenge: BrokerChallenge, member: string, initialRosterDigest: string | null): Uint8Array {
+  return canonicalBytes(["agent-hub.rooms.broker.v1", "auth", challenge, member, initialRosterDigest]);
+}
+function validateChallenge(challenge: BrokerChallenge): BrokerChallenge {
+  return parseChallenge(challenge);
+}
+
+export function decodeBrokerChallenge(input: Uint8Array): BrokerChallenge {
+  return canonicalDecode(input, BROKER_CONTROL_LIMITS.challenge, parseChallenge);
+}
+export function encodeBrokerChallenge(challenge: BrokerChallenge): Uint8Array {
+  return canonicalBytes(validateChallenge(challenge));
+}
+export function decodeBrokerControl(input: Uint8Array): BrokerControl {
+  return canonicalDecode(input, BROKER_CONTROL_LIMITS.control, parseControl);
+}
+export function encodeBrokerControl(control: BrokerControl): Uint8Array {
+  return canonicalBytes(parseControl(control));
+}
+
+export async function createBrokerAuth(input: {
+  challenge: BrokerChallenge;
+  identity: HubIdentity;
+  broker: string;
+  room: string;
+  initialRoster?: Uint8Array;
+}): Promise<Uint8Array> {
+  const challenge = validateChallenge(input.challenge);
+  if (brokerAudience(input.broker) !== challenge.broker || roomId(input.room) !== challenge.room) fail("untrusted");
+  const member = input.identity.public.fingerprint;
+  if (!FP.test(member)) fail("untrusted");
+  let rosterWire: string | null = null;
+  let rosterDigest: string | null = null;
+  if (input.initialRoster !== undefined) {
+    if (challenge.rosterDigest !== null) fail("untrusted");
+    if (!(input.initialRoster instanceof Uint8Array)) fail();
+    const initialRoster = Uint8Array.from(input.initialRoster);
+    const decoded = decodeRoster(initialRoster);
+    const pin: OwnerPin = { room: decoded.room, owner: decoded.owner, minEpoch: "0" };
+    const proof = await verifyPublicRoster({ wire: initialRoster, pin });
+    if (proof.room !== challenge.room || proof.owner !== member || !proof.members.some(m => m.fingerprint === member)) fail("untrusted");
+    rosterWire = encodeBase64url(initialRoster);
+    rosterDigest = proof.digest;
+  } else {
+    if (challenge.rosterDigest === null) fail("untrusted");
+    rosterDigest = null;
+  }
+  const body = { v: 1 as const, type: "auth" as const, member, roster: rosterWire };
+  const auth = { ...body, signature: encodeBase64url(await signBytes(input.identity, challengeBytes(challenge, member, rosterDigest))) };
+  const wire = canonicalBytes(auth);
+  parseAuth(auth);
+  return wire;
+}
+
+/** Verify the challenge signature and resolve the public roster used for membership. */
+export async function verifyBrokerAuth(input: {
+  wire: Uint8Array;
+  challenge: BrokerChallenge;
+  roster?: VerifiedPublicRoster;
+}): Promise<{ member: string; roster: VerifiedPublicRoster; initial: boolean }> {
+  const challenge = validateChallenge(input.challenge);
+  const auth = canonicalDecode(input.wire, BROKER_CONTROL_LIMITS.control, parseAuth);
+  let roster: VerifiedPublicRoster;
+  let signedRosterDigest: string | null;
+  let initial: boolean;
+  if (challenge.rosterDigest === null) {
+    if (auth.roster === null || input.roster !== undefined) fail("untrusted");
+    let rosterWire: Uint8Array;
+    try { rosterWire = decodeBase64url(auth.roster); } catch { fail(); }
+    const decoded = decodeRoster(rosterWire);
+    roster = await verifyPublicRoster({ wire: rosterWire, pin: { room: decoded.room, owner: decoded.owner, minEpoch: "0" } });
+    if (roster.room !== challenge.room || roster.owner !== auth.member) fail("untrusted");
+    signedRosterDigest = roster.digest;
+    initial = true;
+  } else {
+    if (auth.roster !== null || !input.roster) fail("untrusted");
+    roster = input.roster;
+    publicRosterWire(roster);
+    if (roster.room !== challenge.room || roster.digest !== challenge.rosterDigest) fail("untrusted");
+    signedRosterDigest = null;
+    initial = false;
+  }
+  const member = roster.members.find(candidate => candidate.fingerprint === auth.member);
+  if (!member) fail("untrusted");
+  const signature = decodeBase64url(auth.signature, 64);
+  if (!await verifyBytes(member, challengeBytes(challenge, auth.member, signedRosterDigest), signature)) fail("authentication_failed");
+  return { member: auth.member, roster, initial };
+}

package/src/broker/server.ts

@@ -0,0 +1,314 @@
+/** Standalone blind relay. Only public proofs and sealed wire bytes cross this boundary. */
+import type { ServerWebSocket } from "bun";
+import { assertRoomCryptoReady, decodeBase64url, encodeBase64url, randomBytes } from "../rooms/crypto.ts";
+import { brokerUrl, canonicalBytes, decodeFrame, decodeRoster, publicRosterWire, verifyPublicFrame, verifyPublicRoster, type VerifiedPublicRoster } from "../rooms/wire.ts";
+import { BROKER_CONTROL_LIMITS, decodeBrokerControl, encodeBrokerChallenge, verifyBrokerAuth, type BrokerChallenge } from "./protocol.ts";
+import { BrokerStore, BrokerStoreError, type BrokerLimits } from "./store.ts";
+
+export const BROKER_SOCKET_LIMITS = Object.freeze({ connections: 128, verifications: 16, authMs: 10_000, rosterAckMs: 30_000, backpressureBytes: 1_048_576, queuedMessages: 8, queuedBytes: 2_097_152, globalQueuedBytes: 33_554_432 });
+export type BrokerEvent = "started" | "stopped" | "connected" | "buffered" | "disconnected" | "refused" | "roster_installed";
+export interface BrokerPorts {
+  clock?: () => number;
+  log?: (event: BrokerEvent, ids: Readonly<{ room?: string; member?: string; code?: string }>) => void;
+  /** Trusted test/host seam: wrappers must return real X1-minted proofs. Never read from config. */
+  verifyFrame?: typeof verifyPublicFrame;
+}
+export interface BrokerOptions {
+  stateDir: string;
+  hostname?: string;
+  port?: number;
+  publicUrl?: string;
+  /** Controls first-roster admission only; existing roster membership remains authoritative. */
+  owners?: readonly string[];
+  limits?: Partial<BrokerLimits>;
+}
+interface Client {
+  ws?: ServerWebSocket<Client>;
+  room: string;
+  challenge: BrokerChallenge;
+  phase: "challenge" | "authenticating" | "roster" | "ready" | "closed";
+  busy: boolean;
+  inbox: Uint8Array[];
+  inboxBytes: number;
+  member?: string;
+  key?: string;
+  rosterDigest?: string;
+  rosterDeadline?: number;
+  inFlight?: string;
+}
+export interface BrokerRuntime {
+  readonly port: number;
+  readonly hostname: string;
+  readonly publicUrl: string;
+  readonly closed: Promise<void>;
+  stats(): ReturnType<BrokerStore["stats"]> & { connections: number; authenticated: number; verifications: number };
+  sweep(): void;
+  stop(): Promise<void>;
+}
+export class BrokerServerError extends Error {
+  constructor(readonly code: string) { super(`Broker: ${code}`); this.name = "BrokerServerError"; }
+}
+function roomId(value: string): string {
+  if (!/^[A-Za-z0-9_-]{43}$/.test(value)) throw new BrokerServerError("invalid_room");
+  try { decodeBase64url(value, 32); } catch { throw new BrokerServerError("invalid_room"); }
+  return value;
+}
+function audience(value: string): string {
+  let parsed: URL;
+  try { parsed = new URL(brokerUrl(value)); } catch { throw new BrokerServerError("invalid_public_url"); }
+  if (parsed.pathname !== "/" || parsed.search) throw new BrokerServerError("invalid_public_url");
+  return parsed.href;
+}
+const identityKey = (member: { signingKey: string; agreementKey: string }) => `${member.signingKey}:${member.agreementKey}`;
+function errorCode(error: unknown): string {
+  if (error instanceof BrokerStoreError) {
+    if (error.code === "full" || error.code === "limit") return "queue_full";
+    if (error.code === "conflict") return "replay_refused";
+    if (error.code === "untrusted" || error.code === "expired") return error.code;
+    return "storage_error";
+  }
+  if (error instanceof BrokerServerError) return error.code;
+  const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  return typeof code === "string" && ["invalid_wire", "limit", "untrusted", "wrong_epoch", "authentication_failed", "expired"].includes(code) ? code : "invalid_wire";
+}
+
+export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {}): Promise<BrokerRuntime> {
+  // This must precede filesystem, database and listener effects.
+  await assertRoomCryptoReady();
+  const hostname = options.hostname ?? "127.0.0.1", requestedPort = options.port ?? 8788;
+  if (!/^[A-Za-z0-9.:%-]+$/.test(hostname) || !Number.isSafeInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) throw new BrokerServerError("invalid_listen");
+  const loopback = hostname === "127.0.0.1" || hostname === "::1";
+  if (!loopback && options.publicUrl === undefined) throw new BrokerServerError("public_url_required");
+  const configuredAudience = options.publicUrl === undefined ? undefined : audience(options.publicUrl);
+  if (!loopback && configuredAudience && new URL(configuredAudience).protocol !== "wss:") throw new BrokerServerError("public_url_required");
+  let owners: ReadonlySet<string> | undefined;
+  if (options.owners !== undefined) {
+    if (!Array.isArray(options.owners) || options.owners.length > 64 || options.owners.some(owner => typeof owner !== "string" || !/^[0-9a-f]{64}$/.test(owner))) throw new BrokerServerError("invalid_owner");
+    owners = new Set(options.owners);
+  }
+  if ((!loopback || configuredAudience?.startsWith("wss:")) && !owners?.size) throw new BrokerServerError("owner_allowlist_required");
+  const now = () => {
+    const value = (ports.clock ?? Date.now)();
+    if (!Number.isSafeInteger(value) || value < 0) throw new BrokerServerError("invalid_clock");
+    return value;
+  };
+  const store = await BrokerStore.open({ stateDir: options.stateDir, ...(options.limits ? { limits: options.limits } : {}), clock: now });
+  const clients = new Set<Client>(), members = new Map<string, Client>();
+  const memberKey = (client: Client) => `${client.room}|${client.member}`;
+  let stopping = false, verifications = 0, queuedBytes = 0, publicUrl = configuredAudience ?? "";
+  let resolveClosed!: () => void;
+  const closed = new Promise<void>(resolve => { resolveClosed = resolve; });
+  const emit = (event: BrokerEvent, client?: Client, code?: string) => {
+    try { ports.log?.(event, { ...(client ? { room: client.room, ...(client.member ? { member: client.member } : {}) } : {}), ...(code ? { code } : {}) }); } catch { /* diagnostics never change admission or delivery */ }
+  };
+  function close(client: Client, code: string): void {
+    if (client.phase === "closed") return;
+    client.phase = "closed";
+    queuedBytes -= client.inboxBytes; client.inboxBytes = 0; client.inbox.length = 0;
+    if (client.member && members.get(memberKey(client)) === client) members.delete(memberKey(client));
+    if (client.ws) { try { client.ws.close(4403, code); } catch { /* already closed */ } }
+    else clients.delete(client);
+  }
+  function send(client: Client, wire: Uint8Array): boolean {
+    if (stopping || client.phase === "closed" || !client.ws) return false;
+    try {
+      if (client.ws.send(wire) !== 0) return true; // -1 is queued; never resend on drain.
+    } catch { /* a closed transport cannot receive */ }
+    close(client, "backpressure"); return false;
+  }
+  const control = (client: Client, value: unknown) => send(client, canonicalBytes(value));
+  function refused(client: Client, code: string, terminal = true): void {
+    emit("refused", client, code);
+    control(client, { v: 1, type: "error", code });
+    if (terminal) close(client, code);
+  }
+  function active(client: Client): VerifiedPublicRoster {
+    if (stopping || client.phase === "closed" || !client.member || members.get(memberKey(client)) !== client) throw new BrokerServerError("state_changed");
+    const roster = store.current(client.room)?.current;
+    const member = roster?.members.find(row => row.fingerprint === client.member);
+    if (!roster || !member || identityKey(member) !== client.key) throw new BrokerServerError("untrusted");
+    return roster;
+  }
+  function sendRoster(client: Client): void {
+    const roster = active(client);
+    client.phase = "roster"; client.rosterDigest = roster.digest;
+    client.rosterDeadline = now() + BROKER_SOCKET_LIMITS.rosterAckMs;
+    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest });
+  }
+  function pump(client: Client): void {
+    if (stopping || client.phase === "closed" || !client.member) return;
+    active(client);
+    const next = store.next(client.room, client.member);
+    if (client.inFlight && next?.digest === client.inFlight) return;
+    client.inFlight = undefined; // the previous packet may have expired or been purged.
+    if (client.phase !== "ready" || !next) return;
+    if (send(client, next.wire)) client.inFlight = next.digest;
+  }
+  function safePump(client: Client): void {
+    try { pump(client); } catch (error) { refused(client, errorCode(error)); }
+  }
+  function announce(room: string): void {
+    for (const client of clients) if (client.room === room && client.member && client.phase !== "closed") {
+      try { sendRoster(client); } catch (error) { refused(client, errorCode(error)); }
+    }
+  }
+  async function authenticate(client: Client, bytes: Uint8Array): Promise<void> {
+    if (client.phase !== "challenge" || now() >= client.challenge.expiresAt) throw new BrokerServerError("expired");
+    client.phase = "authenticating"; // consume this socket's one-use challenge before any await.
+    const before = store.current(client.room)?.current;
+    const auth = await verifyBrokerAuth({ wire: bytes, challenge: client.challenge, ...(before ? { roster: before } : {}) });
+    if (stopping || client.phase !== "authenticating" || now() >= client.challenge.expiresAt) throw new BrokerServerError("expired");
+    if (auth.initial) {
+      if (owners && !owners.has(auth.member)) throw new BrokerServerError("owner_not_allowed");
+      store.install(auth.roster, auth.member);
+    }
+    else if (store.current(client.room)?.current.digest !== auth.roster.digest) throw new BrokerServerError("state_changed");
+    const current = store.current(client.room)?.current;
+    const member = current?.members.find(row => row.fingerprint === auth.member);
+    if (!current || !member || current.digest !== auth.roster.digest) throw new BrokerServerError("untrusted");
+    client.member = auth.member; client.key = identityKey(member);
+    const previous = members.get(memberKey(client));
+    if (previous && previous !== client) close(previous, "replaced");
+    members.set(memberKey(client), client);
+    client.phase = "roster";
+    sendRoster(client);
+    emit("connected", client);
+  }
+  async function message(client: Client, bytes: Uint8Array): Promise<void> {
+    if (client.phase === "challenge") return authenticate(client, bytes);
+    const current = active(client);
+    let type: unknown;
+    try { type = (JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as { type?: unknown }).type; } catch { throw new BrokerServerError("invalid_wire"); }
+    if (type === "roster") {
+      if (client.member !== current.owner) throw new BrokerServerError("not_owner");
+      const decoded = decodeRoster(bytes);
+      const proof = await verifyPublicRoster({ wire: bytes, pin: { room: current.room, owner: current.owner, minEpoch: current.epoch, digest: current.digest } });
+      active(client); // revocation/replacement/shutdown may have happened during verification.
+      if (decoded.room !== client.room) throw new BrokerServerError("untrusted");
+      const installed = store.install(proof, client.member!);
+      if (installed.changed) { announce(client.room); emit("roster_installed", client); }
+      control(client, { v: 1, type: "roster_installed", epoch: proof.epoch, digest: proof.digest, changed: installed.changed });
+      return;
+    }
+    if (type === "frame") {
+      const header = decodeFrame(bytes), state = store.current(client.room);
+      const selected = state && (header.epoch === state.current.epoch ? state.current : state.previous?.roster);
+      if (!selected) throw new BrokerServerError("wrong_epoch");
+      const proof = await (ports.verifyFrame ?? verifyPublicFrame)({ wire: bytes, roster: selected });
+      active(client);
+      const result = store.enqueue(proof, client.member!); // latest membership/grace/caps checked transactionally.
+      control(client, { v: 1, type: "stored", digest: result.digest, seq: proof.seq, duplicate: result.duplicate });
+      for (const recipient of proof.recipients) {
+        const target = members.get(`${client.room}|${recipient}`);
+        if (target) safePump(target);
+      }
+      return;
+    }
+    const packet = decodeBrokerControl(bytes);
+    if (packet.type === "auth") throw new BrokerServerError("challenge_used");
+    if (packet.type === "roster_ready") {
+      const latest = active(client);
+      if (packet.digest !== client.rosterDigest || packet.digest !== latest.digest) { sendRoster(client); return; }
+      client.phase = "ready"; client.rosterDeadline = undefined;
+      safePump(client); return;
+    }
+    if (packet.digest !== client.inFlight) { refused(client, "unexpected_ack", false); return; }
+    active(client);
+    store.ack(client.room, client.member!, packet.digest);
+    client.inFlight = undefined;
+    control(client, { v: 1, type: "queue_ack", digest: packet.digest });
+    safePump(client);
+  }
+  function schedule(client: Client): void {
+    if (stopping || client.phase === "closed" || client.busy || !client.inbox.length || verifications >= BROKER_SOCKET_LIMITS.verifications) return;
+    const bytes = client.inbox.shift()!;
+    client.inboxBytes -= bytes.length; queuedBytes -= bytes.length;
+    client.busy = true; verifications++;
+    void message(client, bytes).catch(error => {
+      if (!stopping && client.phase !== "closed") {
+        const code = errorCode(error);
+        refused(client, code, !["queue_full", "replay_refused"].includes(code));
+      }
+    }).finally(() => {
+      client.busy = false; verifications--;
+      // Bounded per-socket FIFO allows transport ACKs during an awaited outgoing
+      // signature check, without concurrent mutation of a socket's auth state.
+      for (const waiting of clients) schedule(waiting);
+    });
+  }
+  function receive(client: Client, data: string | Buffer): void {
+    if (stopping || client.phase === "closed") return;
+    if (typeof data === "string") { refused(client, "binary_required"); return; }
+    if (data.byteLength > BROKER_CONTROL_LIMITS.control) { refused(client, "limit"); return; }
+    if (client.inbox.length >= BROKER_SOCKET_LIMITS.queuedMessages || client.inboxBytes + data.byteLength > BROKER_SOCKET_LIMITS.queuedBytes || queuedBytes + data.byteLength > BROKER_SOCKET_LIMITS.globalQueuedBytes) { refused(client, "busy"); return; }
+    const bytes = Uint8Array.from(data);
+    client.inbox.push(bytes); client.inboxBytes += bytes.length; queuedBytes += bytes.length;
+    if (client.busy) emit("buffered", client);
+    schedule(client);
+  }
+  let server: ReturnType<typeof Bun.serve<Client>>;
+  try {
+    server = Bun.serve<Client>({
+      hostname, port: requestedPort, maxRequestBodySize: 8192,
+      fetch(req, host) {
+        try {
+          if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
+          const url = new URL(req.url);
+          if (req.method === "GET" && url.pathname === "/health" && !url.search) return Response.json({ v: 1, status: "ok" });
+          if (stopping || req.method !== "GET" || url.search || !url.pathname.startsWith("/v1/rooms/")) return new Response("not found", { status: 404 });
+          const room = roomId(url.pathname.slice("/v1/rooms/".length));
+          if (clients.size >= BROKER_SOCKET_LIMITS.connections) return new Response("busy", { status: 503 });
+          const current = store.current(room)?.current;
+          const client: Client = { room, challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
+          clients.add(client);
+          if (host.upgrade(req, { data: client })) return;
+          clients.delete(client); return new Response("websocket required", { status: 400 });
+        } catch { return new Response("invalid request", { status: 400 }); }
+      },
+      error() { return new Response("broker error", { status: 500 }); },
+      websocket: {
+        maxPayloadLength: BROKER_CONTROL_LIMITS.control,
+        backpressureLimit: BROKER_SOCKET_LIMITS.backpressureBytes,
+        closeOnBackpressureLimit: true, perMessageDeflate: false, idleTimeout: 60, sendPings: true,
+        open(ws) { const client = ws.data; client.ws = ws; if (client.phase === "closed") { ws.close(4403, "expired"); return; } send(client, encodeBrokerChallenge(client.challenge)); },
+        message(ws, data) { receive(ws.data, data); },
+        drain(ws) { if (!stopping && ws.data.phase !== "closed") safePump(ws.data); },
+        close(ws) {
+          const client = ws.data;
+          close(client, "disconnected"); clients.delete(client); emit("disconnected", client);
+        },
+      },
+    });
+  } catch { store.close(); throw new BrokerServerError("listen_failed"); }
+  publicUrl ||= audience(`ws://${hostname === "::1" ? "[::1]" : hostname}:${server.port}/`);
+  let cachedStats = store.stats();
+  const stats = () => {
+    if (!stopping) cachedStats = store.stats();
+    return { ...cachedStats, connections: clients.size, authenticated: members.size, verifications };
+  };
+  function sweep(): void {
+    if (stopping) return;
+    try { store.sweep(); } catch { for (const client of clients) close(client, "storage_error"); return; }
+    for (const client of clients) {
+      if (client.phase === "closed") continue;
+      if ((client.phase === "challenge" || client.phase === "authenticating") && now() >= client.challenge.expiresAt) close(client, "expired");
+      else if (client.rosterDeadline !== undefined && now() >= client.rosterDeadline) close(client, "roster_timeout");
+      else if (client.member) safePump(client);
+    }
+  }
+  const timer = setInterval(sweep, 1000);
+  let stoppingPromise: Promise<void> | undefined;
+  const stop = () => stoppingPromise ??= (async () => {
+    if (stopping) return;
+    try { cachedStats = store.stats(); } catch { /* still close a failed store */ }
+    stopping = true; clearInterval(timer);
+    for (const client of clients) close(client, "stopped");
+    try { await server.stop(true); }
+    finally {
+      try { store.close(); }
+      finally { emit("stopped"); resolveClosed(); }
+    }
+  })();
+  emit("started");
+  return Object.freeze({ port: server.port!, hostname, publicUrl, closed, stats, sweep, stop });
+}