serverless-ircd 0.7.0 → 0.9.0

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

@@ -77,6 +77,7 @@ type ResolvedServerConfig = Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'operCreds'
 > &
   Pick<
     LocalServerConfig,
@@ -86,6 +87,7 @@ type ResolvedServerConfig = Omit<
     | 'maxConnectionsPerUser'
     | 'perIpConnectionRate'
     | 'saslAccounts'
+    | 'operCreds'
   >;
 
 /**
@@ -107,6 +109,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 } : {}),
   };
 }
 
@@ -171,6 +174,14 @@ export interface LocalServerConfig {
    * disabled (`ctx.accounts` undefined → `904 ERR_SASLFAIL`).
    */
   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 +246,7 @@ const DEFAULT_CONFIG: Omit<
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
   | 'saslAccounts'
+  | 'operCreds'
   | 'serverName'
   | 'networkName'
 > = {
@@ -302,6 +314,8 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ...(opts.topicLen !== undefined ? { topicLen: opts.topicLen } : {}),
       ...(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);
@@ -331,6 +345,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';
 
@@ -398,7 +415,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`);
@@ -484,12 +501,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;
       }
@@ -505,12 +525,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;
@@ -520,7 +541,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
 
         const { state, actor } = attachConnection(runtime, cfg, messages, accounts, 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
@@ -561,12 +582,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: {
@@ -617,7 +636,12 @@ function attachConnection(
     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
@@ -638,9 +662,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
@@ -730,29 +752,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-loader.test.ts

@@ -55,6 +55,20 @@ describe('loadServerConfigFromCliArgs — minimal input', () => {
     expect(cfg.maxClients).toBe(50);
     expect(cfg.operCreds).toEqual([{ user: 'op', password: 'p' }]);
   });
+
+  it('threads serverPassword through to the parsed config', () => {
+    const cfg = loadServerConfigFromCliArgs({
+      serverName: 's',
+      networkName: 'n',
+      serverPassword: 'hunter2',
+    });
+    expect(cfg.serverPassword).toBe('hunter2');
+  });
+
+  it('leaves serverPassword undefined when not supplied', () => {
+    const cfg = loadServerConfigFromCliArgs({ serverName: 's', networkName: 'n' });
+    expect(cfg.serverPassword).toBeUndefined();
+  });
 });
 
 describe('loadServerConfigFromCliArgs — failure modes', () => {

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();
+  });
+});

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

@@ -215,6 +215,24 @@ describe('local-cli TCP transport — IRC flows', () => {
     await client.close();
   });
 
+  it('skips an empty line delivered over TCP without dispatching it', async () => {
+    // The LineScanner yields an empty string for a bare CRLF; the data
+    // handler's `if (line.length === 0) continue` must skip it without
+    // feeding an empty IRC line to the actor (server.ts:539).
+    const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
+    await client.opened();
+    await client.send('NICK blanker');
+    await client.send('USER blanker 0 * :Blanker');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    // A bare CRLF (blank line) followed by a valid PING: the blank line is
+    // ignored and the PING still resolves to a PONG.
+    await client.writeRaw('\r\n');
+    await client.send('PING :after-blank');
+    await client.waitFor((l) => l === 'PONG :after-blank');
+    await client.close();
+  });
+
   it('processes multiple IRC lines delivered in a single TCP write', async () => {
     const client = new TcpTestClient('127.0.0.1', server.tcpPort as number);
     await client.opened();
@@ -367,6 +385,31 @@ describe('local-cli TCP transport — shutdown', () => {
     expect(client.socket.destroyed).toBe(true);
   });
 
+  it('close() destroys a still-live registered TCP connection via the close sweep', async () => {
+    // Registering the client (awaiting 001) guarantees the server-side
+    // connection handler has run and the socket is in `tcpConnections`, so
+    // `close()` deterministically enters the close sweep (server.ts:765) and
+    // destroys the live socket. (Connecting without registering races the
+    // handler under coverage instrumentation.)
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
+    const client = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+    await client.opened();
+    await client.send('NICK sweepUser');
+    await client.send('USER sweepUser 0 * :Sweep');
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
+
+    const closed = new Promise<void>((resolve) => client.socket.once('close', () => resolve()));
+    await srv.close();
+    await closed;
+    expect(client.socket.destroyed).toBe(true);
+  });
+
   it('close() is a no-op for TCP when tcpPort was never enabled', async () => {
     const srv = await startLocalServer({
       port: 0,
@@ -408,3 +451,49 @@ describe('local-cli TCP transport — shutdown', () => {
     await srv.close();
   });
 });
+
+describe('local-cli TCP transport — admission gate', () => {
+  it('emits ERROR :Closing link and destroys the socket when admitConnection denies', async () => {
+    // Tight per-IP cap with a permissive rate limit so only the per-IP
+    // simultaneous-connection gate refuses the second connection.
+    const srv = await startLocalServer({
+      port: 0,
+      tcpPort: 0,
+      hostname: '127.0.0.1',
+      serverName: 'admit.example.com',
+      networkName: 'AdmitNet',
+      maxConnectionsPerIp: 1,
+      maxConnectionsPerUser: 1_000,
+      perIpConnectionRate: { max: 1_000, windowMs: 60_000 },
+    });
+
+    try {
+      // First connection fills the per-IP cap (maxConnectionsPerIp: 1).
+      const first = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+      await first.opened();
+
+      // Second connection from the same IP is denied at the TCP admission
+      // gate BEFORE an actor is attached. The server writes the RFC-style
+      // ERROR notice then destroys the socket (server.ts 511-517).
+      const rejected = new TcpTestClient('127.0.0.1', srv.tcpPort as number);
+      const errorLine = await rejected.waitFor((l) => l.startsWith('ERROR :Closing link'), 2_000);
+      expect(errorLine).toContain('connection limit reached');
+      expect(errorLine).toContain('max_connections_per_ip');
+
+      // The server destroys the socket after the ERROR notice.
+      await new Promise<void>((resolve) => {
+        if (rejected.socket.destroyed) resolve();
+        else rejected.socket.once('close', () => resolve());
+      });
+      expect(rejected.socket.destroyed).toBe(true);
+
+      // The denied socket is removed from the server's tracked set so the
+      // runtime admission counters don't leak it.
+      expect(srv.testTcpSockets?.has(rejected.socket)).toBe(false);
+
+      await first.close();
+    } finally {
+      await srv.close();
+    }
+  });
+});