serverless-ircd 0.2.0 → 0.4.0

package/packages/irc-server/tests/actor.test.ts

@@ -1,4 +1,5 @@
 import {
+  type AccountStore,
   CapturingLogger,
   type ChanName,
   type ChanSnapshot,
@@ -11,24 +12,33 @@ import {
   FakeClock,
   type FloodControlConfig,
   InMemoryMessageStore,
+  InMemoryNickHistoryStore,
   LogLevel,
   type Logger,
   type MessageStore,
+  type MtlsIdentityProvider,
   type Nick,
+  type NickHistoryStore,
   Numerics,
   type RawLine,
+  type SaslPayload,
+  type SaslResult,
   SequentialIdFactory,
   type ServerConfig,
   type StoredMessage,
   applyChannelDelta as applyDelta,
   createChannel,
   createConnection,
+  encodeBase64,
   isChannelTarget,
   toChannelSnapshot,
+  toSnapshot,
 } from '@serverless-ircd/irc-core';
 import { describe, expect, it } from 'vitest';
 import { ConnectionActor } from '../src/actor';
 import type { IrcRuntime } from '../src/runtime';
+import { TcpByteStreamTransport, WsTextFrameTransport } from '../src/transport';
+import type { Transport } from '../src/transport';
 
 // ---------------------------------------------------------------------------
 // Fakes
@@ -116,7 +126,8 @@ class FakeRuntime implements IrcRuntime {
   }
   async getConnectionInfo(conn: ConnId): Promise<ConnSnapshot | null> {
     this.calls.push({ method: 'getConnectionInfo', args: [conn] });
-    return null;
+    const state = this.testConnections.get(conn);
+    return state === undefined ? null : toSnapshot(state);
   }
   async getConnection(conn: ConnId): Promise<ConnectionState | null> {
     this.calls.push({ method: 'getConnection', args: [conn] });
@@ -154,6 +165,11 @@ function makeActor(opts: {
   logger?: Logger;
   traceId?: string;
   messages?: MessageStore;
+  accounts?: AccountStore;
+  mtlsIdentity?: MtlsIdentityProvider;
+  history?: NickHistoryStore;
+  operCreds?: ReadonlyArray<{ user: string; password: string }>;
+  transport?: Transport;
 }): { actor: ConnectionActor; runtime: FakeRuntime; conn: ConnectionState } {
   const clock = opts.clock ?? new FakeClock(1_000);
   const conn = createConnection({ id: 'c1', connectedSince: 0 });
@@ -179,6 +195,7 @@ function makeActor(opts: {
     topicLen: 390,
     quitMessage: 'Client Quit',
     ...(opts.floodControl !== undefined ? { floodControl: opts.floodControl } : {}),
+    ...(opts.operCreds !== undefined ? { operCreds: opts.operCreds } : {}),
   };
   const ids = new SequentialIdFactory();
   type ActorOpts = ConstructorParameters<typeof ConnectionActor>[0];
@@ -203,6 +220,18 @@ function makeActor(opts: {
   if (opts.messages !== undefined) {
     finalOpts.messages = opts.messages;
   }
+  if (opts.accounts !== undefined) {
+    finalOpts.accounts = opts.accounts;
+  }
+  if (opts.mtlsIdentity !== undefined) {
+    finalOpts.mtlsIdentity = opts.mtlsIdentity;
+  }
+  if (opts.history !== undefined) {
+    finalOpts.history = opts.history;
+  }
+  if (opts.transport !== undefined) {
+    finalOpts.transport = opts.transport;
+  }
   const actor = new ConnectionActor(finalOpts);
   return { actor, runtime, conn };
 }
@@ -266,6 +295,112 @@ describe('ConnectionActor — framing', () => {
   });
 });
 
+describe('ConnectionActor — TCP byte-stream transport seam', () => {
+  it('two TCP chunks split mid-line produce exactly one PRIVMSG broadcast', async () => {
+    const { actor, runtime } = makeActor({ transport: new TcpByteStreamTransport() });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    // Split the single message mid-payload across two chunks. The partial
+    // line is buffered across the first chunk; only the second completes it.
+    await actor.receive('PRIVMSG #foo :hel');
+    expect(runtime.calls).toHaveLength(0);
+    await actor.receive('lo\r\n');
+
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]?.args[0]).toBe('#foo');
+    const lines = broadcasts[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':alice!alice@example.com PRIVMSG #foo :hello');
+  });
+
+  it('one message per WS text frame and one per CRLF over TCP produce identical effects', async () => {
+    // Same bytes, same connection setup, two transports. The WS actor gets
+    // the whole frame in one receiveTextFrame; the TCP actor gets the same
+    // bytes split across arbitrary chunks via receive().
+    const wsSetup = makeActor({});
+    const tcpSetup = makeActor({ transport: new TcpByteStreamTransport() });
+    for (const rt of [wsSetup.runtime, tcpSetup.runtime]) {
+      await rt.applyChannelDelta('#foo', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+      });
+    }
+    wsSetup.runtime.calls.length = 0;
+    tcpSetup.runtime.calls.length = 0;
+
+    const stream = 'PRIVMSG #foo :hello\r\n';
+    await wsSetup.actor.receiveTextFrame(stream);
+    // Feed the TCP actor the same bytes in 4-byte chunks.
+    for (let i = 0; i < stream.length; i += 4) {
+      await tcpSetup.actor.receive(stream.slice(i, i + 4));
+    }
+
+    const wsBroadcast = wsSetup.runtime.calls.filter((c) => c.method === 'broadcast');
+    const tcpBroadcast = tcpSetup.runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(tcpBroadcast).toHaveLength(wsBroadcast.length);
+    expect((tcpBroadcast[0]?.args[1] as RawLine[])[0]?.text).toBe(
+      (wsBroadcast[0]?.args[1] as RawLine[])[0]?.text,
+    );
+  });
+
+  it('buffers a partial line across multiple chunks with no loss or duplication', async () => {
+    const { actor, runtime } = makeActor({ transport: new TcpByteStreamTransport() });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    // Three messages, each fed byte-by-byte. Every complete line is emitted
+    // exactly once; nothing is lost or duplicated at the chunk boundaries.
+    const stream = 'PING :a\r\nPRIVMSG #foo :b\r\nPING :c\r\n';
+    for (const ch of stream) {
+      await actor.receive(ch);
+    }
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(sends).toHaveLength(2); // PONG :a, PONG :c
+    expect((sends[0]?.args[1] as RawLine[])[0]?.text).toBe('PONG :a');
+    expect((sends[1]?.args[1] as RawLine[])[0]?.text).toBe('PONG :c');
+    expect(broadcasts).toHaveLength(1); // PRIVMSG #foo :b
+    expect((broadcasts[0]?.args[1] as RawLine[])[0]?.text).toBe(
+      ':alice!alice@example.com PRIVMSG #foo :b',
+    );
+  });
+
+  it('uses the default WS-frame transport when none is injected (backward compat)', () => {
+    // No `transport` option → the actor still frames WS text frames exactly
+    // as before. Confirms the default is the stateless WS transport.
+    const { actor, runtime } = makeActor({});
+    // A trailing unterminated line is still emitted by the WS transport
+    // (frame = complete unit), so this produces one PONG with no terminator.
+    return actor.receiveTextFrame('PING :tok').then(() => {
+      const sends = runtime.calls.filter((c) => c.method === 'send');
+      expect(sends).toHaveLength(1);
+      expect((sends[0]?.args[1] as RawLine[])[0]?.text).toBe('PONG :tok');
+    });
+  });
+
+  it('a TCP actor does NOT emit a trailing unterminated line until the terminator arrives', async () => {
+    const tcpActor = makeActor({ transport: new TcpByteStreamTransport() });
+    const wsActor = makeActor({ transport: new WsTextFrameTransport() });
+    tcpActor.runtime.calls.length = 0;
+    wsActor.runtime.calls.length = 0;
+
+    // WS treats the frame as complete → emits a PONG. TCP buffers the
+    // unterminated line → emits nothing yet. This is the defining
+    // behavioural difference of stateful byte-stream framing.
+    await wsActor.actor.receiveTextFrame('PING :unterminated');
+    await tcpActor.actor.receive('PING :unterminated');
+    expect(wsActor.runtime.calls.filter((c) => c.method === 'send')).toHaveLength(1);
+    expect(tcpActor.runtime.calls).toHaveLength(0);
+    // …until the terminator completes the line.
+    await tcpActor.actor.receive('\r\n');
+    expect(tcpActor.runtime.calls.filter((c) => c.method === 'send')).toHaveLength(1);
+  });
+});
+
 describe('ConnectionActor — malformed input', () => {
   it('emits 421 for an unparseable line and continues processing the rest', async () => {
     const { actor, runtime } = makeActor({});
@@ -478,6 +613,57 @@ describe('ConnectionActor — additional routing', () => {
     expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(1);
   });
 
+  it('routes TAGMSG to a channel broadcast (never 421) when message-tags cap is present', async () => {
+    const bobConn = createConnection({ id: 'c2', connectedSince: 0 });
+    bobConn.nick = 'bob';
+    bobConn.user = 'bob';
+    bobConn.host = 'example.org';
+    bobConn.registration = 'registered';
+    bobConn.caps = new Set<string>(['message-tags']);
+    const { actor, runtime } = makeActor({
+      conn: { caps: new Set<string>(['message-tags']) },
+    });
+    runtime.addConnection(bobConn);
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'alice' },
+        { type: 'add', conn: 'c2', nick: 'bob' },
+      ],
+    });
+    runtime.calls.length = 0;
+    await actor.receiveTextFrame('@+typing=active TAGMSG #foo\r\n');
+
+    // Cap-gated broadcast dispatches per-recipient via send (only to
+    // message-tags-enabled members, excluding the sender).
+    const sends = runtime.calls.filter((c) => c.method === 'send' && c.args[0] === 'c2');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe('@+typing=active :alice!alice@example.com TAGMSG #foo');
+    // Critical: never 421 for a cap-enabled TAGMSG.
+    for (const call of runtime.calls) {
+      if (call.method === 'send') {
+        for (const line of call.args[1] as RawLine[]) {
+          expect(line.text).not.toContain(' 421 ');
+        }
+      }
+    }
+  });
+
+  it('still emits 421 for TAGMSG when message-tags cap is not negotiated', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+    await actor.receiveTextFrame('TAGMSG #foo\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 421 ');
+    expect(lines[0]?.text).toContain('TAGMSG');
+  });
+
   it('routes PRIVMSG with mixed targets (#chan,nick) into 2 invocations', async () => {
     const { actor, runtime } = makeActor({});
     await runtime.applyChannelDelta('#foo', {
@@ -599,6 +785,76 @@ describe('ConnectionActor — additional routing', () => {
     }
   });
 
+  it('routes WHOWAS of a quit nick through whowasReducer (314 + 369, never 421)', async () => {
+    const history = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    history.record({
+      nick: 'bob',
+      connId: 'c2',
+      username: 'bob',
+      hostname: 'example.com',
+      realname: 'Bob',
+      signoffTime: 500,
+    });
+    const { actor, runtime } = makeActor({ history });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOWAS bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThanOrEqual(2);
+    const firstBatch = sends[0]?.args[1] as RawLine[];
+    expect(firstBatch[0]?.text).toContain(' 314 ');
+    expect(firstBatch[0]?.text).toContain(' bob ');
+    const endBatch = sends[sends.length - 1]?.args[1] as RawLine[];
+    expect(endBatch[0]?.text).toContain(' 369 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes WHOWAS of an unknown nick to 406 then 369 (never 421)', async () => {
+    const history = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    const { actor, runtime } = makeActor({ history });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOWAS ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const notFound = sends[0]?.args[1] as RawLine[];
+    expect(notFound[0]?.text).toContain(' 406 ');
+    expect(notFound[0]?.text).toContain(' ghost ');
+    const end = sends[1]?.args[1] as RawLine[];
+    expect(end[0]?.text).toContain(' 369 ');
+  });
+
+  it('still emits 406 + 369 for WHOWAS when no history store is bound (no crash)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOWAS ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const notFound = sends[0]?.args[1] as RawLine[];
+    expect(notFound[0]?.text).toContain(' 406 ');
+    const end = sends[1]?.args[1] as RawLine[];
+    expect(end[0]?.text).toContain(' 369 ');
+  });
+
+  it('records a nick into history on QUIT when a store is bound', async () => {
+    const history = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    const { actor } = makeActor({ history });
+
+    await actor.receiveTextFrame('QUIT\r\n');
+
+    const entries = history.query('alice', 10);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.nick).toBe('alice');
+  });
+
   it('routes AUTHENTICATE PLAIN (post CAP REQ sasl) through authenticateReducer, never 421', async () => {
     // Pre-registration: client has opened CAP negotiation and requested sasl.
     // AUTHENTICATE must reach the SASL reducer, not the 421 fallthrough.
@@ -712,6 +968,63 @@ describe('ConnectionActor — additional routing', () => {
     }
   });
 
+  it('routes OPER with matching creds through operReducer (381, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({
+      operCreds: [{ user: 'alice', password: 'secret' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('OPER alice secret\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':irc.example.com 381 alice :You are now an IRC operator');
+    expect(conn.userModes.oper).toBe(true);
+    // Critical: never 421 for OPER.
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes OPER with wrong creds through operReducer (464, never 421)', async () => {
+    const { actor, runtime } = makeActor({
+      operCreds: [{ user: 'alice', password: 'secret' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('OPER alice wrong\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 464 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes OPER with no configured creds through operReducer (491, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('OPER alice secret\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 491 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
   it('emits 421 with empty command when routeSingleChannel gets no channel (TOPIC)', async () => {
     const { actor, runtime } = makeActor({});
     await actor.receiveTextFrame('TOPIC\r\n');
@@ -1270,3 +1583,306 @@ describe('ConnectionActor — CHATHISTORY', () => {
     // …but there is no store to record into.
   });
 });
+
+// ===========================================================================
+// SASL / AccountStore — actor plumbing (ctx.accounts threaded through buildCtx)
+// ===========================================================================
+
+describe('ConnectionActor — SASL AccountStore plumbing', () => {
+  /** Capture-and-respond fake AccountStore (mirrors the irc-core sasl tests). */
+  class FakeAccountStore implements AccountStore {
+    readonly calls: Array<{ mech: string; payload: SaslPayload }> = [];
+    constructor(private readonly result: SaslResult) {}
+    verify(mech: string, payload: SaslPayload): SaslResult {
+      this.calls.push({ mech, payload });
+      return this.result;
+    }
+  }
+
+  /** Builds the PLAIN base64 payload `authzid\0authcid\0password`. */
+  function plainPayload(authcid: string, password: string): string {
+    return encodeBase64(`\0${authcid}\0${password}`);
+  }
+
+  /** A connection that has opened CAP negotiation and requested `sasl`. */
+  function saslReadyConn(): Partial<ConnectionState> {
+    return {
+      registration: 'pre-registration',
+      capNegotiating: true,
+      caps: new Set<string>(['sasl']),
+    };
+  }
+
+  it('completes SASL PLAIN with 900/903 when a bound AccountStore accepts creds', async () => {
+    const accounts = new FakeAccountStore({ ok: true, account: 'alice' });
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      accounts,
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE PLAIN\r\n');
+    await actor.receiveTextFrame(`AUTHENTICATE ${plainPayload('alice', 'secret')}\r\n`);
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    // Second frame emits the success numerics; gather every sent line.
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 900 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 903 '))).toBe(true);
+    // Critical: never 904 for valid creds.
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(false);
+    // The AccountStore was consulted with the parsed PLAIN credentials.
+    expect(accounts.calls).toEqual([
+      { mech: 'PLAIN', payload: { kind: 'PLAIN', username: 'alice', password: 'secret' } },
+    ]);
+    // Account name recorded on the connection for extended-join/account-tag.
+    expect(conn.account).toBe('alice');
+  });
+
+  it('emits 904 ERR_SASLFAIL when no AccountStore is bound (regression guard)', async () => {
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      // No `accounts` option → ctx.accounts is undefined.
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE PLAIN\r\n');
+    await actor.receiveTextFrame(`AUTHENTICATE ${plainPayload('alice', 'secret')}\r\n`);
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(true);
+    // No success numerics.
+    expect(lines.some((l) => l.text.includes(' 900 '))).toBe(false);
+    expect(lines.some((l) => l.text.includes(' 903 '))).toBe(false);
+    // Account name never recorded.
+    expect(conn.account).toBeUndefined();
+  });
+
+  it('emits 904 when a bound AccountStore rejects the credentials', async () => {
+    const accounts = new FakeAccountStore({ ok: false, reason: 'invalid credentials' });
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      accounts,
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE PLAIN\r\n');
+    await actor.receiveTextFrame(`AUTHENTICATE ${plainPayload('alice', 'wrong')}\r\n`);
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 903 '))).toBe(false);
+    expect(conn.account).toBeUndefined();
+  });
+});
+
+describe('ConnectionActor — SASL EXTERNAL + mTLS plumbing', () => {
+  /** Fake AccountStore that accepts EXTERNAL with a known cert subject. */
+  class FakeAccountStore implements AccountStore {
+    readonly calls: Array<{ mech: string; payload: SaslPayload }> = [];
+    constructor(private readonly result: SaslResult) {}
+    verify(mech: string, payload: SaslPayload): SaslResult {
+      this.calls.push({ mech, payload });
+      return this.result;
+    }
+  }
+
+  /** Fake MtlsIdentityProvider returning a canned subject for 'c1'. */
+  class FakeMtlsProvider implements MtlsIdentityProvider {
+    constructor(private readonly identity: string | undefined) {}
+    getIdentity(connId: string): string | undefined {
+      return connId === 'c1' ? this.identity : undefined;
+    }
+  }
+
+  function saslReadyConn(): Partial<ConnectionState> {
+    return {
+      registration: 'pre-registration',
+      capNegotiating: true,
+      caps: new Set<string>(['sasl']),
+    };
+  }
+
+  it('completes SASL EXTERNAL with 900/903 when mTLS provider and store accept', async () => {
+    const accounts = new FakeAccountStore({ ok: true, account: 'alice' });
+    const mtlsIdentity = new FakeMtlsProvider('CN=alice');
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      accounts,
+      mtlsIdentity,
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE EXTERNAL\r\n');
+    await actor.receiveTextFrame('AUTHENTICATE +\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 900 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 903 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(false);
+    expect(accounts.calls).toEqual([
+      { mech: 'EXTERNAL', payload: { kind: 'EXTERNAL', identity: 'CN=alice' } },
+    ]);
+    expect(conn.account).toBe('alice');
+  });
+
+  it('returns 908 for EXTERNAL when no mTLS provider is bound', async () => {
+    const accounts = new FakeAccountStore({ ok: true, account: 'alice' });
+    const { actor, runtime, conn } = makeActor({
+      conn: saslReadyConn(),
+      accounts,
+      // No mtlsIdentity → EXTERNAL should 908 at mechanism phase.
+    });
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE EXTERNAL\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends.flatMap((s) => s.args[1] as RawLine[]);
+    expect(lines.some((l) => l.text.includes(' 908 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 904 '))).toBe(false);
+    expect(conn.account).toBeUndefined();
+  });
+});
+
+describe('ConnectionActor — server-info commands (VERSION/TIME/ADMIN/INFO/USERHOST/ISON)', () => {
+  it('routes VERSION through versionReducer (351, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('VERSION\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 351 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('routes TIME through timeReducer (391, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TIME\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 391 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('routes ADMIN through adminReducer (256, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ADMIN\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 256 ');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('routes INFO through infoReducer (371 + 374, never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('INFO\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines.some((l) => l.text.includes(' 371 '))).toBe(true);
+    expect(lines.some((l) => l.text.includes(' 374 '))).toBe(true);
+    expect(lines.every((l) => !l.text.includes(' 421 '))).toBe(true);
+  });
+
+  it('routes USERHOST resolving online nicks (302, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bobuser';
+    bobState.host = 'bobhost';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('USERHOST bob ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 302 ');
+    expect(lines[0]?.text).toContain('bob=+bobuser@bobhost');
+    // Offline nick `ghost` is omitted from the reply.
+    expect(lines[0]?.text).not.toContain('ghost');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('USERHOST marks away users with - and opers with *', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bobuser';
+    bobState.host = 'bobhost';
+    bobState.away = 'brb';
+    bobState.userModes.oper = true;
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('USERHOST bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('bob*=-bobuser@bobhost');
+  });
+
+  it('routes ISON resolving online nicks (303, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ISON bob ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(' 303 ');
+    expect(lines[0]?.text).toContain('bob');
+    expect(lines[0]?.text).not.toContain('ghost');
+    expect(lines[0]?.text).not.toContain(' 421 ');
+  });
+
+  it('ISON matches case-insensitively and reports the registered spelling', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'Bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('ISON BOB\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain(':Bob');
+  });
+});