serverless-ircd 0.8.0 → 0.10.0

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

@@ -33,20 +33,21 @@ import { randomUUID } from 'node:crypto';
 import { type Server, type Socket, createServer } from 'node:net';
 import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
 import {
-  type AccountStore,
   type AdmissionConfig,
   type ChanName,
   type ConnectionState,
   ConsoleLogger,
-  InMemoryAccountStore,
   InMemoryMessageStore,
   InMemoryNickHistoryStore,
+  InMemoryServicesStore,
   LogLevel,
   type Logger,
   type MessageStore,
   type NickHistoryStore,
   type RawLine,
   type ServerConfig,
+  type ServicesStore,
+  SystemClock,
   WS_SUBPROTO_BINARY,
   WS_SUBPROTO_TEXT,
   type WsFrameMode,
@@ -77,6 +78,7 @@ type ResolvedServerConfig = Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'operCreds'
 > &
   Pick<
     LocalServerConfig,
@@ -86,6 +88,7 @@ type ResolvedServerConfig = Omit<
     | 'maxConnectionsPerUser'
     | 'perIpConnectionRate'
     | 'saslAccounts'
+    | 'operCreds'
   >;
 
 /**
@@ -107,6 +110,7 @@ function serverConfigFromResolved(cfg: ResolvedServerConfig): ServerConfig {
     quitMessage: cfg.quitMessage,
     ...(cfg.serverPassword !== undefined ? { serverPassword: cfg.serverPassword } : {}),
     ...(cfg.cloaking !== undefined ? { cloaking: cfg.cloaking } : {}),
+    ...(cfg.operCreds !== undefined ? { operCreds: cfg.operCreds } : {}),
   };
 }
 
@@ -165,12 +169,21 @@ export interface LocalServerConfig {
    */
   historyMaxPerChannel?: number;
   /**
-   * SASL PLAIN account credentials. When non-empty the server seeds an
-   * in-memory {@link AccountStore} so `AUTHENTICATE PLAIN` succeeds for the
-   * listed accounts. When omitted/empty, SASL account verification is
-   * disabled (`ctx.accounts` undefined → `904 ERR_SASLFAIL`).
+   * SASL PLAIN account credentials. Seeded into the in-memory
+   * {@link ServicesStore} at boot so `AUTHENTICATE PLAIN`, `PASS
+   * <nick>:<password>`, and NickServ `IDENTIFY` all verify against the
+   * listed accounts. Empty array (the default) still binds a services
+   * store — NickServ REGISTER creates accounts at runtime.
    */
   saslAccounts?: Array<{ username: string; password: string }>;
+  /**
+   * IRC operator credentials consulted by the `OPER` reducer. When omitted
+   * (or empty) `OPER` receives `491 ERR_NOOPERHOST` and oper-only commands
+   * like `REHASH` are unreachable; supply a non-empty list to let a client
+   * oper up. Threaded straight through to the reducer-facing
+   * {@link ServerConfig} via the shared schema.
+   */
+  readonly operCreds?: Array<{ user: string; password: string }>;
 }
 
 export interface StartServerOptions extends LocalServerConfig {
@@ -235,6 +248,7 @@ const DEFAULT_CONFIG: Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'operCreds'
   | 'serverName'
   | 'networkName'
 > = {
@@ -303,6 +317,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ...(opts.quitMessage !== undefined ? { quitMessage: opts.quitMessage } : {}),
       ...(opts.saslAccounts !== undefined ? { saslAccounts: opts.saslAccounts } : {}),
       ...(opts.serverPassword !== undefined ? { serverPassword: opts.serverPassword } : {}),
+      ...(opts.operCreds !== undefined ? { operCreds: opts.operCreds } : {}),
     });
   } catch (err) {
     return Promise.reject(err);
@@ -332,6 +347,9 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     ...(opts.saslAccounts !== undefined && opts.saslAccounts.length > 0
       ? { saslAccounts: opts.saslAccounts }
       : {}),
+    ...(opts.operCreds !== undefined && opts.operCreds.length > 0
+      ? { operCreds: opts.operCreds }
+      : {}),
   };
   const hostname = opts.hostname ?? '127.0.0.1';
 
@@ -369,13 +387,15 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   // matches wall time.
   const history = new InMemoryNickHistoryStore({ now: () => Date.now() });
 
-  // SASL account store: seeded from config so `AUTHENTICATE PLAIN` works
-  // end-to-end. `undefined` (no accounts configured) leaves the actor's
-  // `ctx.accounts` unset, preserving the no-store behaviour.
-  const accounts =
-    cfg.saslAccounts !== undefined && cfg.saslAccounts.length > 0
-      ? new InMemoryAccountStore(cfg.saslAccounts)
-      : undefined;
+  // Services store: the single credential home for NickServ, SASL PLAIN,
+  // SASL EXTERNAL, and PASS-auth. Seeded from `saslAccounts` config so the
+  // listed accounts verify end-to-end via `services.verifyNick`. Always
+  // bound (never `undefined`) so NickServ REGISTER / IDENTIFY work
+  // out-of-the-box for local development.
+  const services = new InMemoryServicesStore({ clock: SystemClock });
+  for (const acct of cfg.saslAccounts ?? []) {
+    services.registerNick(acct.username, acct.password, '');
+  }
 
   const wss = new WebSocketServer({
     port: opts.port,
@@ -399,7 +419,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     // Admission gate: refuse the connection BEFORE we attach an actor / emit
     // any IRC state. Keeps per-IP / per-user counters authoritative and
     // avoids burning a nick or runtime slot on a denied client.
-    const ip = req.socket.remoteAddress ?? 'unknown';
+    const ip = peerHost(req.socket.remoteAddress);
     const decision = runtime.admitConnection(ip, undefined);
     if (!decision.ok) {
       ws.send(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
@@ -418,7 +438,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     wsModes.set(ws, subproto);
     const frameMode = wsFrameModeFor(subproto ?? undefined);
 
-    const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
+    const { state, actor } = attachConnection(runtime, cfg, messages, services, history, {
       sendText: (text) => {
         if (ws.readyState !== WebSocket.OPEN) return;
         // binary.ircv3.net connections exchange binary WebSocket frames;
@@ -485,12 +505,15 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     const onWsListening = (): void => {
       wss.removeListener('error', onWsError);
       const addr = wss.address();
-      // c8 ignore next 1 - defensive fallback for non-IP transports; with a
-      // TCP port `wss.address()` always returns an AddressInfo object.
-      const wsPort = typeof addr === 'object' && addr !== null ? addr.port : opts.port;
+      const wsPort = listenerPort(addr, opts.port);
+
+      // Capture the requested TCP port as a `const` so TS narrows it to
+      // `number` past the `undefined` early-return below (a property access
+      // like `opts.tcpPort` is not narrowed across the closure).
+      const requestedTcpPort = opts.tcpPort;
 
       // If no TCP listener was requested, resolve immediately with just WS.
-      if (opts.tcpPort === undefined) {
+      if (requestedTcpPort === undefined) {
         finishResolve({ wsPort, tcpPort: undefined, tcpServer: undefined });
         return;
       }
@@ -506,12 +529,13 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
 
         // Admission gate — same policy as the WS path: refuse before the
         // actor is attached so per-IP / per-user counters stay authoritative.
-        const ip = socket.remoteAddress ?? 'unknown';
+        const ip = peerHost(socket.remoteAddress);
         const decision = runtime.admitConnection(ip, undefined);
         if (!decision.ok) {
-          if (socket.writable) {
-            socket.write(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
-          }
+          safeSocketWrite(
+            socket,
+            `ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`,
+          );
           socket.destroy();
           tcpSockets.delete(socket);
           return;
@@ -519,9 +543,9 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
         const admissionRecordId = decision.recordId;
         runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-        const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
+        const { state, actor } = attachConnection(runtime, cfg, messages, services, history, {
           sendText: (text) => {
-            if (socket.writable) socket.write(text);
+            safeSocketWrite(socket, text);
           },
           closeTransport: () => {
             // `destroy()` over `end()` so a half-closed peer can't hold the
@@ -562,12 +586,10 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       });
       tcpServer.once('listening', () => {
         const tcpAddr = tcpServer.address();
-        // c8 ignore next 1 - defensive: a TCP listener always yields AddressInfo.
-        const tcpPort =
-          typeof tcpAddr === 'object' && tcpAddr !== null ? tcpAddr.port : opts.tcpPort;
+        const tcpPort = listenerPort(tcpAddr, requestedTcpPort);
         finishResolve({ wsPort, tcpPort, tcpServer, tcpConnections, tcpSockets });
       });
-      tcpServer.listen(opts.tcpPort, hostname);
+      tcpServer.listen(requestedTcpPort, hostname);
     };
 
     const finishResolve = (args: {
@@ -612,13 +634,18 @@ function attachConnection(
   runtime: InMemoryRuntime,
   cfg: ResolvedServerConfig,
   messages: MessageStore,
-  accounts: AccountStore | undefined,
+  services: ServicesStore,
   history: NickHistoryStore,
   transport: {
     sendText: (text: string) => void;
     closeTransport: () => void;
     admissionRecordId?: string;
-    sourceHost?: string;
+    /**
+     * Transport-visible source host recorded on the connection state (cloak
+     * input / visible host). Both transports always supply the peer IP, so
+     * this is required rather than optional.
+     */
+    sourceHost: string;
     /**
      * Negotiated IRCv3 WebSocket frame mode for this connection. Spec modes
      * (`spec-text` / `spec-binary`) switch outbound delivery to one WS
@@ -639,9 +666,7 @@ function attachConnection(
   const state = createConnection({ id, connectedSince: Date.now() });
   // Record the transport-visible source host up front. Used as the cloak
   // input when cloaking is enabled, and as the visible host otherwise.
-  if (transport.sourceHost !== undefined) {
-    state.host = transport.sourceHost;
-  }
+  state.host = transport.sourceHost;
 
   // Per-connection logger: every record the actor emits
   // carries this connection's id so the local-cli log stream can be
@@ -659,7 +684,7 @@ function attachConnection(
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
     messages,
-    ...(accounts !== undefined ? { accounts } : {}),
+    ...(services !== undefined ? { services } : {}),
     history,
     logger,
     ...(transport.actorTransport !== undefined ? { transport: transport.actorTransport } : {}),
@@ -731,29 +756,71 @@ function closeEverything(args: {
   // Tear down WS connections + server first.
   const wsClosed = teardownWss(wss, wsConnections);
 
-  // Tear down TCP connections + server in parallel (if enabled).
+  // Tear down TCP connections + server in parallel (if enabled). Both are
+  // captured together (a TCP-disabled server has neither), so the guard is a
+  // single expression covering both the disabled and enabled cases.
   const tcpClosed =
-    tcpServer === undefined
+    tcpServer === undefined || tcpConnections === undefined
       ? Promise.resolve()
       : new Promise<void>((res) => {
-          if (tcpConnections !== undefined) {
-            for (const socket of tcpConnections.keys()) {
-              // Defensive: reachable only if a socket was already destroyed
-              // (e.g. via a reducer-driven disconnect racing the close sweep)
-              // but hasn't yet been removed from `tcpConnections`. The cleanup
-              // handler always removes on 'close'/'error', so this branch is a
-              // no-op in steady state.
-              // c8 ignore next 1
-              if (!socket.destroyed) socket.destroy();
-            }
-            tcpConnections.clear();
+          for (const socket of tcpConnections.keys()) {
+            // Idempotent: a socket already torn down by a reducer-driven
+            // disconnect racing the close sweep is skipped.
+            safeDestroy(socket);
           }
+          tcpConnections.clear();
           tcpServer.close(() => res());
         });
 
   return Promise.all([wsClosed, tcpClosed]).then(() => undefined);
 }
 
+/**
+ * Resolves the visible peer IP for a freshly-accepted socket, falling back to
+ * `'unknown'` when the transport exposes no remote address (e.g. a socket
+ * already torn down at upgrade time). Extracted as a pure helper so the
+ * fallback arm is unit-testable in isolation — the live WS/TCP paths always
+ * observe a concrete `remoteAddress`, so the `'unknown'` arm is unreachable
+ * through the integration suite.
+ */
+export function peerHost(remoteAddress: string | undefined): string {
+  return remoteAddress ?? 'unknown';
+}
+
+/**
+ * Reads the bound port from a listener's `address()` result, falling back to
+ * the requested port for non-IP transports (named-pipe / unix-socket) which
+ * local-cli never binds but the `node:net` typing permits. Pure helper so the
+ * fallback arm is unit-testable; the live listeners always bind IP.
+ */
+export function listenerPort(addr: { port: number } | string | null, fallback: number): number {
+  return typeof addr === 'object' && addr !== null ? addr.port : fallback;
+}
+
+/**
+ * Writes `data` to `socket` only while it is still writable, silently
+ * skipping a destroyed / non-writable socket. Extracted so the non-writable
+ * arm is unit-testable with a fake — the live WS/TCP send paths always
+ * observe a writable transport, and the TCP admission-deny write races a
+ * socket that a peer RST may already have torn down.
+ */
+export function safeSocketWrite(
+  socket: { writable: boolean; write: (data: string) => void },
+  data: string,
+): void {
+  if (socket.writable) socket.write(data);
+}
+
+/**
+ * Destroys `socket` unless it is already destroyed (idempotent teardown).
+ * Extracted so the already-destroyed arm is unit-testable with a fake — the
+ * race that produces an already-destroyed socket still present in the
+ * connection map is not deterministically reproducible in the suite.
+ */
+export function safeDestroy(socket: { destroyed: boolean; destroy(): void }): void {
+  if (!socket.destroyed) socket.destroy();
+}
+
 function logError(msg: string, err: unknown): void {
   // Structured JSON per acceptance criteria.
   const payload = { ts: new Date().toISOString(), level: 'error', msg, err: stringifyErr(err) };

package/apps/local-cli/tests/config-resolution.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Coverage for `startLocalServer`'s config-resolution branches:
+ *   - the conditional spreads that pass optional CLI knobs through to the
+ *     shared schema (each knob's "defined" arm — exercised only when the
+ *     caller explicitly supplies the value);
+ *   - the admission-config `?? DEFAULT_*` fallbacks (exercised only when
+ *     admission is enabled without the corresponding cap/rate).
+ *
+ * Starting a server (and closing it) is enough to drive the resolution — no
+ * client connection is required.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { startLocalServer } from '../src/server';
+
+describe('startLocalServer — threads explicit config knobs to the schema', () => {
+  it('accepts every optional limit/knob override and starts cleanly', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'cfg.example.com',
+      networkName: 'CfgNet',
+      motdLines: ['explicit motd line'],
+      maxChannelsPerUser: 7,
+      maxTargetsPerCommand: 3,
+      maxListEntries: 11,
+      nickLen: 20,
+      channelLen: 40,
+      topicLen: 200,
+      quitMessage: 'explicit quit',
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    await srv.close();
+  });
+});
+
+describe('startLocalServer — admission defaults', () => {
+  it('falls back to the per-IP / per-user defaults when only the rate limit is set', async () => {
+    // Admission enabled, but maxConnectionsPerIp / maxConnectionsPerUser are
+    // left undefined → the `?? DEFAULT_*` arms apply.
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'rate.example.com',
+      networkName: 'RateNet',
+      perIpConnectionRate: { max: 5, windowMs: 60_000 },
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    await srv.close();
+  });
+
+  it('falls back to the per-IP cap and rate defaults when only per-user cap is set', async () => {
+    // Admission enabled, but maxConnectionsPerIp / perIpConnectionRate are
+    // left undefined → both `?? DEFAULT_*` arms apply.
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'user.example.com',
+      networkName: 'UserNet',
+      maxConnectionsPerUser: 3,
+    });
+    expect(srv.port).toBeGreaterThan(0);
+    await srv.close();
+  });
+});

package/apps/local-cli/tests/motd-file-non-error.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Isolated coverage for {@link loadMotdFile}'s non-Error throw wrap
+ * (motd-file.ts:41 — the `String(err)` branch). The rest of the motd-file
+ * suite exercises real `node:fs` I/O against a temp dir; this file
+ * `vi.mock`s `node:fs` so `readFileSync` rejects with a value that is NOT
+ * an `Error`, driving the `err instanceof Error ? ... : String(err)` ternary
+ * down its non-Error path. Lives in its own file so the mock never leaks
+ * into the real-I/O tests.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('node:fs', () => ({
+  // Throw a non-Error value so the catch wraps it via `String(err)`.
+  readFileSync: () => {
+    throw 'boom-non-error';
+  },
+}));
+
+// Imported AFTER `vi.mock` is established (vitest hoists the mock).
+import { loadMotdFile } from '../src/motd-file';
+
+describe('loadMotdFile — wraps a non-Error throw via String()', () => {
+  it('rethrows a descriptive Error whose detail is String(<thrown value>)', () => {
+    expect(() => loadMotdFile('/irrelevant/motd.txt')).toThrowError(
+      /motd: cannot read --motd-file at .*: boom-non-error/u,
+    );
+  });
+});

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

@@ -0,0 +1,147 @@
+/**
+ * oper `REHASH` end-to-end through the local CLI.
+ *
+ * Drives the `configLoader` closure bound at server.ts:358 — the REHASH
+ * reload source. An oper's `REHASH` re-invokes that closure (via the runtime's
+ * `reloadConfig`) and swaps the live ServerConfig; the actor emits
+ * `382 RPL_REHASHING` on success. A non-oper receives `481 ERR_NOPRIVILEGES`
+ * and no reload is attempted.
+ *
+ * Oper credentials are threaded through the local CLI's `operCreds` option
+ * (the shared schema already accepted them; `startLocalServer` now wires them
+ * to the reducer-facing ServerConfig).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+class IrcClient {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string) {
+    this.ws = new WebSocket(url);
+    this.ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws.readyState === WebSocket.OPEN) resolve();
+      else {
+        this.ws.once('open', () => resolve());
+        this.ws.once('error', reject);
+      }
+    });
+  }
+
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1_000): Promise<string> {
+    const check = (line: string): boolean => predicate(line);
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`)),
+        timeoutMs,
+      );
+      const onLine = (line: string): void => {
+        if (check(line)) {
+          clearTimeout(timeout);
+          this.ws.off('message', onMessage);
+          resolve(line);
+        }
+      };
+      const onMessage = (data: { toString: (enc: string) => string }): void => {
+        for (const line of data.toString('utf8').split(/\r?\n/u)) {
+          if (line.length > 0) onLine(line);
+        }
+      };
+      for (const line of this.received) {
+        if (check(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.ws.on('message', onMessage);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+describe('local-cli e2e — oper REHASH re-invokes the bound configLoader', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'rehash.example.com',
+      networkName: 'RehashNet',
+      operCreds: [{ user: 'admin', password: 's3cret' }],
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('grants oper then reloads config on REHASH (382 RPL_REHASHING, no error)', async () => {
+    const client = new IrcClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK oper1');
+    await client.send('USER oper1 0 * :Oper');
+    await client.waitFor((l) => l.startsWith(':rehash.example.com 001 '));
+
+    // Oper up so the REHASH oper gate passes.
+    await client.send('OPER admin s3cret');
+    const operUp = await client.waitFor((l) => l.includes(' 381 '));
+    expect(operUp).toContain('You are now an IRC operator');
+
+    // REHASH — the actor re-invokes the runtime's reloadConfig, which calls
+    // the configLoader closure (server.ts:358). A clean `382` (no `failed`)
+    // proves the reload succeeded.
+    await client.send('REHASH');
+    const rehashLine = await client.waitFor((l) => l.includes(' 382 '), 2_000);
+    expect(rehashLine).toContain('Rehashing from');
+    expect(rehashLine).not.toContain('failed');
+
+    await client.close();
+  });
+
+  it('rejects REHASH from a non-oper with 481 ERR_NOPRIVILEGES (no reload)', async () => {
+    const client = new IrcClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK peon');
+    await client.send('USER peon 0 * :Peon');
+    await client.waitFor((l) => l.startsWith(':rehash.example.com 001 '));
+
+    await client.send('REHASH');
+    const denied = await client.waitFor((l) => l.includes(' 481 '));
+    expect(denied).toContain('Permission Denied');
+    await client.close();
+  });
+
+  it('directly exercises the configLoader closure via runtime.reloadConfig()', async () => {
+    // Independent of the actor path: the closure bound at server.ts:358 must
+    // return the live ServerConfig the actor was bootstrapped with.
+    const reloaded = await server.runtime.reloadConfig();
+    expect(reloaded.serverName).toBe('rehash.example.com');
+    expect(reloaded.networkName).toBe('RehashNet');
+  });
+});

package/apps/local-cli/tests/server-helpers.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Unit tests for the small transport/adapter helpers extracted from
+ * `server.ts` as test seams. These wrap the genuinely-unreachable defensive
+ * branches (peer-IP fallback, listener-port fallback, write-to-unwritable,
+ * destroy-already-destroyed) so each branch is deterministically exercisable
+ * with a fake — the live WS/TCP integration paths only ever observe the
+ * non-defensive arm.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { listenerPort, peerHost, safeDestroy, safeSocketWrite } from '../src/server';
+
+describe('peerHost', () => {
+  it('returns the remote address when present', () => {
+    expect(peerHost('203.0.113.7')).toBe('203.0.113.7');
+  });
+
+  it("falls back to 'unknown' when no remote address is exposed", () => {
+    expect(peerHost(undefined)).toBe('unknown');
+  });
+});
+
+describe('listenerPort', () => {
+  it('reads the port from an AddressInfo-shaped object', () => {
+    expect(listenerPort({ port: 6667 }, 0)).toBe(6667);
+  });
+
+  it('falls back when the address is a non-IP transport (string)', () => {
+    expect(listenerPort('/run/irc.sock', 7000)).toBe(7000);
+  });
+
+  it('falls back when the address is null', () => {
+    expect(listenerPort(null, 7000)).toBe(7000);
+  });
+});
+
+describe('safeSocketWrite', () => {
+  it('writes when the socket is writable', () => {
+    const write = vi.fn();
+    safeSocketWrite({ writable: true, write }, 'PONG :tok');
+    expect(write).toHaveBeenCalledWith('PONG :tok');
+  });
+
+  it('is a silent no-op when the socket is no longer writable', () => {
+    const write = vi.fn();
+    safeSocketWrite({ writable: false, write }, 'PONG :tok');
+    expect(write).not.toHaveBeenCalled();
+  });
+});
+
+describe('safeDestroy', () => {
+  it('destroys a live socket', () => {
+    const destroy = vi.fn();
+    safeDestroy({ destroyed: false, destroy });
+    expect(destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('is idempotent — skips a socket that is already destroyed', () => {
+    const destroy = vi.fn();
+    safeDestroy({ destroyed: true, destroy });
+    expect(destroy).not.toHaveBeenCalled();
+  });
+});