serverless-ircd 0.4.0 → 0.6.0

package/apps/local-cli/src/server.ts

@@ -8,6 +8,11 @@
  *   • a `ws.WebSocketServer` on {@link StartServerOptions.port} — the
  *     original WebSocket transport (one IRC message per text frame, or N
  *     `\r\n`-joined messages per frame). Programmatic test clients use this.
+ *     When a client negotiates an IRCv3 subprotocol
+ *     (`text.ircv3.net` / `binary.ircv3.net`) the connection switches to
+ *     spec framing: one IRC message per WebSocket message with no trailing
+ *     CR-LF, a 510-byte inbound budget, and (for text) lone-surrogate
+ *     sanitization. Un-negotiated clients keep the legacy framing.
  *   • an optional `node:net` TCP server on {@link StartServerOptions.tcpPort}
  *     — the RFC-style byte stream that real IRC clients (WeeChat, HexChat,
  *     IRCCloud) speak. The TCP path uses {@link LineScanner} to reassemble
@@ -41,9 +46,19 @@ import {
   type MessageStore,
   type NickHistoryStore,
   type RawLine,
+  type ServerConfig,
+  WS_SUBPROTO_BINARY,
+  WS_SUBPROTO_TEXT,
+  type WsFrameMode,
+  type WsSubprotocol,
   createConnection,
+  frameToLines,
+  isWithinWsByteBudget,
+  sanitizeForTextMode,
+  selectSubprotocol,
+  wsFrameModeFor,
 } from '@serverless-ircd/irc-core';
-import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { ConnectionActor, type Transport } from '@serverless-ircd/irc-server';
 import { WebSocket, WebSocketServer } from 'ws';
 import { loadServerConfigFromCliArgs } from './config-loader.js';
 import { LineScanner } from './line-scanner.js';
@@ -73,6 +88,28 @@ type ResolvedServerConfig = Omit<
     | 'saslAccounts'
   >;
 
+/**
+ * Builds the reducer-facing {@link ServerConfig} from the resolved local-cli
+ * config. Shared by {@link attachConnection} (initial config) and the
+ * `InMemoryRuntime` reload source (REHASH) so a reload returns the same
+ * shape the actor was bootstrapped with — keeping the two paths consistent.
+ */
+function serverConfigFromResolved(cfg: ResolvedServerConfig): ServerConfig {
+  return {
+    serverName: cfg.serverName,
+    networkName: cfg.networkName,
+    maxChannelsPerUser: cfg.maxChannelsPerUser,
+    maxTargetsPerCommand: cfg.maxTargetsPerCommand,
+    maxListEntries: cfg.maxListEntries,
+    nickLen: cfg.nickLen,
+    channelLen: cfg.channelLen,
+    topicLen: cfg.topicLen,
+    quitMessage: cfg.quitMessage,
+    ...(cfg.serverPassword !== undefined ? { serverPassword: cfg.serverPassword } : {}),
+    ...(cfg.cloaking !== undefined ? { cloaking: cfg.cloaking } : {}),
+  };
+}
+
 /** Default per-IP / per-user caps used when callers don't override. */
 const DEFAULT_MAX_CONNECTIONS_PER_IP = 10;
 const DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
@@ -198,9 +235,9 @@ const DEFAULT_CONFIG: Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'serverName'
+  | 'networkName'
 > = {
-  serverName: 'irc.example.com',
-  networkName: 'ExampleNet',
   motdLines: ['Welcome to the local-cli ServerlessIRCd instance.'],
   maxChannelsPerUser: 30,
   maxTargetsPerCommand: 10,
@@ -216,7 +253,7 @@ const DEFAULT_CONFIG: Omit<
  * the three generators once at module load, not per-connection. No reducer in
  * the current codebase actually invokes `batchId` / `nonce` / `sessionId`;
  * they are forward-looking seams for SASL / BATCH / context-restoration
- * tickets and are exercised by irc-core's own unit tests via test fakes.
+ * and are exercised by irc-core's own unit tests via test fakes.
  *
  * Exported so `apps/local-cli` can ship a focused unit test asserting each
  * generator returns a fresh UUID-shaped string (defending against future
@@ -242,14 +279,16 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   // Validate the user-supplied config through the shared ServerConfigSchema
   // (sourced from `irc-core`). Both adapters consume the same schema; here
   // we discard the parsed result and only retain the side-effect of
-  // throwing on a malformed config at boot. The actor still consumes the
-  // `LocalServerConfig` projection so existing callers (and the e2e
-  // harness) keep their permissive defaults.
+  // throwing on a malformed config at boot. `serverName` and `networkName`
+  // are required by the schema — passing them through as `undefined` when
+  // the caller omits them lets the loader fail fast with a readable error
+  // pointing at the missing knob, so the server never boots advertising a
+  // placeholder identity.
   let parsed: ReturnType<typeof loadServerConfigFromCliArgs>;
   try {
     parsed = loadServerConfigFromCliArgs({
-      serverName: opts.serverName ?? DEFAULT_CONFIG.serverName,
-      networkName: opts.networkName ?? DEFAULT_CONFIG.networkName,
+      serverName: opts.serverName,
+      networkName: opts.networkName,
       ...(opts.motdLines !== undefined ? { motdLines: opts.motdLines } : {}),
       ...(opts.maxChannelsPerUser !== undefined
         ? { maxChannelsPerUser: opts.maxChannelsPerUser }
@@ -312,6 +351,10 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   const runtime = new InMemoryRuntime({
     clock: { now: () => Date.now() },
     ...(admission !== undefined ? { admission } : {}),
+    // REHASH reload source: re-derive the live ServerConfig from the
+    // resolved config so an oper's `REHASH` re-fetches the latest values
+    // (rotated oper creds, MOTD, limits) without restarting the process.
+    configLoader: async () => serverConfigFromResolved(cfg),
   });
 
   // Per-process chat-history store: one ring buffer shared by every
@@ -333,8 +376,23 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ? new InMemoryAccountStore(cfg.saslAccounts)
       : undefined;
 
-  const wss = new WebSocketServer({ port: opts.port, host: hostname });
+  const wss = new WebSocketServer({
+    port: opts.port,
+    host: hostname,
+    // IRCv3 WebSocket subprotocol negotiation: select the first supported
+    // offer in client-preference order (core selector), or fall through to
+    // legacy framing when none match. The `ws` library only invokes this
+    // when the client offered protocols; returning the selected name echoes
+    // it, returning false completes the handshake with no
+    // Sec-WebSocket-Protocol header (legacy) — it never rejects.
+    handleProtocols: (protocols: Set<string>): string | false =>
+      selectSubprotocol([...protocols]) ?? false,
+  });
   const wsConnections = new Map<WebSocket, ConnectionBindings>();
+  // Per-connection negotiated IRCv3 subprotocol registry (null = legacy
+  // framing). Mirrors the selection made in `handleProtocols`; the resolved
+  // frame mode is also captured in the per-connection handlers below.
+  const wsModes = new Map<WebSocket, WsSubprotocol | null>();
 
   wss.on('connection', (ws, req) => {
     // Admission gate: refuse the connection BEFORE we attach an actor / emit
@@ -350,18 +408,50 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     const admissionRecordId = decision.recordId;
     runtime.commitAdmission(ip, undefined, admissionRecordId);
 
+    // Resolve the negotiated IRCv3 subprotocol (echoed by handleProtocols)
+    // and derive the frame mode. `ws.protocol` is '' when none negotiated.
+    const subproto: WsSubprotocol | null =
+      ws.protocol === WS_SUBPROTO_TEXT || ws.protocol === WS_SUBPROTO_BINARY
+        ? (ws.protocol as WsSubprotocol)
+        : null;
+    wsModes.set(ws, subproto);
+    const frameMode = wsFrameModeFor(subproto ?? undefined);
+
     const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
       sendText: (text) => {
-        if (ws.readyState === WebSocket.OPEN) ws.send(text);
+        if (ws.readyState !== WebSocket.OPEN) return;
+        // binary.ircv3.net connections exchange binary WebSocket frames;
+        // text/legacy connections send UTF-8 text frames.
+        ws.send(frameMode === 'spec-binary' ? Buffer.from(text, 'utf8') : text);
       },
       closeTransport: () => ws.close(),
       admissionRecordId,
       sourceHost: ip,
+      frameMode,
+      // Spec-mode framing: one IRC message per WS message (strip a single
+      // trailing CR-LF, never split on an embedded line break). Legacy
+      // connections fall through to the actor's default WsTextFrameTransport.
+      ...(frameMode === 'legacy'
+        ? {}
+        : { actorTransport: { feed: (chunk: string) => frameToLines(chunk, frameMode) } }),
     });
     wsConnections.set(ws, { state, actor });
 
     ws.on('message', (data) => {
       const text = data.toString('utf8');
+      // Spec-mode inbound: enforce the IRCv3 510-byte message budget and
+      // sanitize lone surrogates for text frames before framing. Legacy
+      // frames pass through unchanged (the 512-byte line cap is enforced in
+      // the parser, as before).
+      if (frameMode === 'spec-text' || frameMode === 'spec-binary') {
+        if (!isWithinWsByteBudget(text)) {
+          ws.close(1009, 'Message Too Big');
+          return;
+        }
+        const inbound = frameMode === 'spec-text' ? sanitizeForTextMode(text) : text;
+        actor.receiveTextFrame(inbound).catch((err) => logError('actor failure', err));
+        return;
+      }
       // Fire-and-forget: the actor's reducer pipeline is synchronous through
       // to dispatch, and dispatch awaits each runtime call in order. Errors
       // propagate to the catch here and are logged (never crash the server).
@@ -376,6 +466,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     // admission record (if any) so per-IP / per-user counters stay accurate.
     const cleanup = (): void => {
       wsConnections.delete(ws);
+      wsModes.delete(ws);
       runtime.unregisterConnection(state.id);
     };
     ws.on('close', cleanup);
@@ -527,6 +618,20 @@ function attachConnection(
     closeTransport: () => void;
     admissionRecordId?: string;
     sourceHost?: string;
+    /**
+     * Negotiated IRCv3 WebSocket frame mode for this connection. Spec modes
+     * (`spec-text` / `spec-binary`) switch outbound delivery to one WS
+     * message per IRC line with no trailing CR-LF (and surrogate
+     * sanitization for text). `undefined` / `legacy` keeps the original
+     * `\r\n`-joined batch. TCP connections never set this.
+     */
+    frameMode?: WsFrameMode;
+    /**
+     * Inbound line-framing seam forwarded to the actor's `Transport`. Only
+     * set for spec-mode WebSocket connections (one IRC line per frame);
+     * when omitted the actor defaults to its WS-text-frame transport.
+     */
+    actorTransport?: Transport;
   },
 ): ConnectionBindings {
   const id = randomUUID();
@@ -547,19 +652,8 @@ function attachConnection(
     state,
     runtime,
     channels: runtime,
-    serverConfig: {
-      serverName: cfg.serverName,
-      networkName: cfg.networkName,
-      maxChannelsPerUser: cfg.maxChannelsPerUser,
-      maxTargetsPerCommand: cfg.maxTargetsPerCommand,
-      maxListEntries: cfg.maxListEntries,
-      nickLen: cfg.nickLen,
-      channelLen: cfg.channelLen,
-      topicLen: cfg.topicLen,
-      quitMessage: cfg.quitMessage,
-      ...(cfg.serverPassword !== undefined ? { serverPassword: cfg.serverPassword } : {}),
-      ...(cfg.cloaking !== undefined ? { cloaking: cfg.cloaking } : {}),
-    },
+    serverConfig: serverConfigFromResolved(cfg),
+    configSource: 'config file',
     clock: { now: () => Date.now() },
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
@@ -567,21 +661,37 @@ function attachConnection(
     ...(accounts !== undefined ? { accounts } : {}),
     history,
     logger,
+    ...(transport.actorTransport !== undefined ? { transport: transport.actorTransport } : {}),
   });
 
   runtime.registerConnection(
     state,
     {
       send: (lines: RawLine[]) => {
-        const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-        transport.sendText(text);
+        const fm = transport.frameMode;
+        if (fm === 'spec-text' || fm === 'spec-binary') {
+          // Spec mode: one WebSocket message per IRC line, no trailing
+          // CR-LF. Sanitize lone surrogates for text frames (they have no
+          // valid UTF-8 encoding); binary frames pass through verbatim.
+          for (const l of lines) {
+            transport.sendText(fm === 'spec-text' ? sanitizeForTextMode(l.text) : l.text);
+          }
+        } else {
+          const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
+          transport.sendText(text);
+        }
       },
       disconnect: (reason?: string) => {
         // If a reason was supplied, send the RFC-style ERROR notice before
         // closing. (QUIT does not supply one; future paths like flood
-        // control will.)
+        // control will.) In spec mode the notice is its own message with no
+        // trailing CR-LF.
         if (reason !== undefined) {
-          transport.sendText(`ERROR :Closing link: (${reason})\r\n`);
+          const line = `ERROR :Closing link: (${reason})`;
+          const fm = transport.frameMode;
+          if (fm === 'spec-text') transport.sendText(sanitizeForTextMode(line));
+          else if (fm === 'spec-binary') transport.sendText(line);
+          else transport.sendText(`${line}\r\n`);
         }
         transport.closeTransport();
       },

package/apps/local-cli/tests/e2e.test.ts

@@ -80,7 +80,12 @@ describe('local-cli e2e', () => {
   let server: LocalServer;
 
   beforeAll(async () => {
-    server = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
   });
 
   afterAll(async () => {
@@ -103,15 +108,15 @@ describe('local-cli e2e', () => {
 
     await alice.send('NICK alice');
     await alice.send('USER alice 0 * :Alice');
-    await alice.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await alice.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await bob.send('NICK bob');
     await bob.send('USER bob 0 * :Bob');
-    await bob.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await bob.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await alice.send('JOIN #e2e');
     await alice.waitFor((l) => l.includes('JOIN #e2e'));
-    await alice.waitFor((l) => l.startsWith(':irc.example.com 353 '));
+    await alice.waitFor((l) => l.startsWith(':irc.local.example.com 353 '));
 
     await bob.send('JOIN #e2e');
     // Bob sees his own JOIN + NAMES.
@@ -130,7 +135,7 @@ describe('local-cli e2e', () => {
     await client.opened();
     await client.send('NICK charlie');
     await client.send('USER charlie 0 * :Charlie');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await client.send('PING :tok-12345');
     await client.waitFor((l) => l === 'PONG :tok-12345');
@@ -143,7 +148,7 @@ describe('local-cli e2e', () => {
     await client.opened();
     await client.send('NICK dave');
     await client.send('USER dave 0 * :Dave');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await client.send('BOGUSCMD');
     await client.waitFor((l) => l.includes('421') && l.includes('BOGUSCMD'));
@@ -156,7 +161,7 @@ describe('local-cli e2e', () => {
     await client.opened();
     await client.send('NICK eve');
     await client.send('USER eve 0 * :Eve');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await client.send('QUIT :bye');
     // The disconnect effect should close the socket.
@@ -166,18 +171,42 @@ describe('local-cli e2e', () => {
     await next.opened();
     await next.send('NICK eve');
     await next.send('USER eve 0 * :Eve2');
-    await next.waitFor((l) => l.startsWith(':irc.example.com 001 '), 2000);
+    await next.waitFor((l) => l.startsWith(':irc.local.example.com 001 '), 2000);
     await next.close();
   });
 });
 
 describe('local-cli error paths', () => {
   it('rejects startLocalServer when the port is already in use', async () => {
-    const first = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
-    await expect(startLocalServer({ port: first.port, hostname: '127.0.0.1' })).rejects.toThrow();
+    const first = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
+    await expect(
+      startLocalServer({
+        port: first.port,
+        hostname: '127.0.0.1',
+        serverName: 'irc.local.example.com',
+        networkName: 'LocalNet',
+      }),
+    ).rejects.toThrow();
     await first.close();
   });
 
+  it('rejects when serverName is omitted so the placeholder never leaks', async () => {
+    await expect(startLocalServer({ port: 0, hostname: '127.0.0.1' })).rejects.toThrowError(
+      /serverName/u,
+    );
+  });
+
+  it('rejects when networkName is omitted', async () => {
+    await expect(
+      startLocalServer({ port: 0, hostname: '127.0.0.1', serverName: 'irc.local.example.com' }),
+    ).rejects.toThrowError(/networkName/u);
+  });
+
   it('validates the supplied config through the shared ServerConfigSchema at boot', async () => {
     // nickLen=0 is rejected by the schema (must be a positive integer).
     await expect(
@@ -192,7 +221,12 @@ describe('local-cli error paths', () => {
   });
 
   it('logs and recovers from a per-socket error without crashing the server', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
     await client.opened();
     // Synthesize a socket-level error on the SERVER-side ws via the
@@ -218,20 +252,22 @@ describe('local-cli error paths', () => {
     const srv = await startLocalServer({
       port: 0,
       hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
       motdLines: ['first line of motd', 'second line of motd'],
     });
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
     await client.opened();
     await client.send('NICK karl');
     await client.send('USER karl 0 * :Karl');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     // Drain registration burst so the explicit MOTD responses below aren't
     // confused with the placeholder MOTD emitted at registration.
     client.received.length = 0;
     await client.send('MOTD');
     // Wait for end-of-MOTD so all 372 lines are buffered in `received`.
-    await client.waitFor((l) => l.startsWith(':irc.example.com 376 karl'));
-    const motdBody = client.received.filter((l) => l.startsWith(':irc.example.com 372 karl'));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 376 karl'));
+    const motdBody = client.received.filter((l) => l.startsWith(':irc.local.example.com 372 karl'));
     expect(motdBody.some((l) => l.includes('first line of motd'))).toBe(true);
     expect(motdBody.some((l) => l.includes('second line of motd'))).toBe(true);
     await client.close();
@@ -239,7 +275,11 @@ describe('local-cli error paths', () => {
   });
 
   it('defaults hostname to 127.0.0.1 when omitted', async () => {
-    const srv = await startLocalServer({ port: 0 });
+    const srv = await startLocalServer({
+      port: 0,
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     expect(srv.hostname).toBe('127.0.0.1');
     // Sanity-check that the server is actually reachable on the default.
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
@@ -249,7 +289,12 @@ describe('local-cli error paths', () => {
   });
 
   it('close() forcibly closes any still-open client sockets', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
     await client.opened();
     // Close the server WITHOUT first closing the client — exercises the
@@ -260,14 +305,24 @@ describe('local-cli error paths', () => {
   });
 
   it('close() is a no-op when no connections are live', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     await srv.close();
     // Closing again should not throw (idempotent).
     await expect(srv.close()).resolves.toBeUndefined();
   });
 
   it('logs an actor failure without crashing the server (Error path)', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     // Force the runtime's `send` to throw a real Error so the actor's
     // reducer pipeline rejects with an Error instance — exercises
     // `stringifyErr`'s `instanceof Error` branch and `logError`.
@@ -291,14 +346,19 @@ describe('local-cli error paths', () => {
     await next.opened();
     await next.send('NICK grace');
     await next.send('USER grace 0 * :Grace');
-    await next.waitFor((l) => l.startsWith(':irc.example.com 001 '), 2000);
+    await next.waitFor((l) => l.startsWith(':irc.local.example.com 001 '), 2000);
     await next.close();
     await client.close();
     await srv.close();
   });
 
   it('logs a non-Error throw from the actor pipeline (defensive path)', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const original = srv.runtime.send.bind(srv.runtime);
     srv.runtime.send = async () => {
       // Throw a non-Error value to exercise stringifyErr's else branch.
@@ -316,12 +376,17 @@ describe('local-cli error paths', () => {
   });
 
   it('cleans up when a client terminates abruptly (server-side error path)', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
     await client.opened();
     await client.send('NICK ivan');
     await client.send('USER ivan 0 * :Ivan');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     const connId = await srv.runtime.lookupNick('ivan');
     expect(connId).not.toBeNull();
     expect(srv.runtime.hasConnection(connId as string)).toBe(true);
@@ -330,7 +395,7 @@ describe('local-cli error paths', () => {
     // 'error' followed by 'close', and the cleanup handler unregisters the
     // connection from the runtime. (The nick itself is released by the
     // QUIT reducer on graceful shutdown; abrupt termination leaks the nick
-    // pending a future gone-connection sweep — 041.)
+    // pending a future gone-connection sweep.)
     client.ws.terminate();
     await new Promise((r) => setTimeout(r, 100));
     expect(srv.runtime.hasConnection(connId as string)).toBe(false);
@@ -338,12 +403,17 @@ describe('local-cli error paths', () => {
   });
 
   it('delivers an ERROR notice when a reducer supplies a disconnect reason', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
     await client.opened();
     await client.send('NICK heidi');
     await client.send('USER heidi 0 * :Heidi');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     // Call the runtime's disconnect directly with a reason (simulates a
     // future flood-control / oper-kill effect). The runtime takes a ConnId;
@@ -370,12 +440,17 @@ describe('local-cli chathistory end-to-end', () => {
     client.send(`NICK ${nick}\r\n`);
     client.send(`USER ${nick} 0 * :${nick}\r\n`);
     client.send('CAP END\r\n');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     return client;
   }
 
   it('records a PRIVMSG and replays it via CHATHISTORY LATEST in a BATCH', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
     const alice = await registerWithCaps(srv, 'ch-alice');
 
     alice.send('JOIN #chathist-e2e\r\n');
@@ -395,7 +470,12 @@ describe('local-cli chathistory end-to-end', () => {
   });
 
   it('prepends a chathistory BATCH on rejoin after messages were sent', async () => {
-    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
 
     // Seed history as alice: join + send a message that bob has missed.
     const alice = await registerWithCaps(srv, 'ch-seed');
@@ -429,6 +509,8 @@ describe('local-cli SASL PLAIN end-to-end', () => {
     const srv = await startLocalServer({
       port: 0,
       hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
       saslAccounts: [{ username: 'sasl-alice', password: 's3cret' }],
     });
 
@@ -445,7 +527,7 @@ describe('local-cli SASL PLAIN end-to-end', () => {
     client.send('NICK sasl-alice\r\n');
     client.send('USER sasl-alice 0 * :Sasl Alice\r\n');
     client.send('CAP END\r\n');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     await client.close();
     await srv.close();
   });
@@ -454,6 +536,8 @@ describe('local-cli SASL PLAIN end-to-end', () => {
     const srv = await startLocalServer({
       port: 0,
       hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
       saslAccounts: [{ username: 'sasl-bob', password: 'right' }],
     });