serverless-ircd 0.1.0 → 0.3.0

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

@@ -1,4 +1,6 @@
 import {
+  type AccountStore,
+  CapturingLogger,
   type ChanName,
   type ChanSnapshot,
   type ChannelDelta,
@@ -8,15 +10,26 @@ import {
   type ConnectionState,
   EmptyMotdProvider,
   FakeClock,
+  type FloodControlConfig,
+  InMemoryMessageStore,
+  LogLevel,
+  type Logger,
+  type MessageStore,
   type Nick,
   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';
@@ -56,6 +69,10 @@ class FakeRuntime implements IrcRuntime {
     return chan;
   }
 
+  getChannel(name: ChanName): ChannelState | undefined {
+    return this.channels.get(name.toLowerCase());
+  }
+
   async send(to: ConnId, lines: RawLine[]): Promise<void> {
     this.calls.push({ method: 'send', args: [to, lines] });
   }
@@ -104,7 +121,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] });
@@ -138,6 +156,12 @@ class FakeRuntime implements IrcRuntime {
 function makeActor(opts: {
   conn?: Partial<ConnectionState>;
   clock?: FakeClock;
+  floodControl?: FloodControlConfig | null;
+  logger?: Logger;
+  traceId?: string;
+  messages?: MessageStore;
+  accounts?: AccountStore;
+  operCreds?: ReadonlyArray<{ user: string; password: string }>;
 }): { actor: ConnectionActor; runtime: FakeRuntime; conn: ConnectionState } {
   const clock = opts.clock ?? new FakeClock(1_000);
   const conn = createConnection({ id: 'c1', connectedSince: 0 });
@@ -149,25 +173,49 @@ function makeActor(opts: {
   if (opts.conn) Object.assign(conn, opts.conn);
 
   const runtime = new FakeRuntime(clock);
-  const actor = new ConnectionActor({
+  // Build in one expression: `floodControl` is readonly, and only stamp it
+  // when the caller supplied a value so `undefined` (omit → default) stays
+  // distinct from `null` (explicit disable).
+  const serverConfig: ServerConfig = {
+    serverName: 'irc.example.com',
+    networkName: 'ExampleNet',
+    maxChannelsPerUser: 30,
+    maxTargetsPerCommand: 10,
+    maxListEntries: 50,
+    nickLen: 30,
+    channelLen: 50,
+    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];
+  // Strip readonly modifiers so we can conditionally assign `logger` /
+  // `traceId` without tripping the readonly guards on `ConnectionActorOptions`.
+  type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+  const finalOpts: Mutable<ActorOpts> = {
     state: conn,
     runtime,
     channels: runtime,
-    serverConfig: {
-      serverName: 'irc.example.com',
-      networkName: 'ExampleNet',
-      maxChannelsPerUser: 30,
-      maxTargetsPerCommand: 10,
-      maxListEntries: 50,
-      nickLen: 30,
-      channelLen: 50,
-      topicLen: 390,
-      quitMessage: 'Client Quit',
-    },
+    serverConfig,
     clock,
-    ids: new SequentialIdFactory(),
+    ids,
     motd: EmptyMotdProvider,
-  });
+  };
+  if (opts.logger !== undefined) {
+    finalOpts.logger = opts.logger;
+  }
+  if (opts.traceId !== undefined) {
+    finalOpts.traceId = opts.traceId;
+  }
+  if (opts.messages !== undefined) {
+    finalOpts.messages = opts.messages;
+  }
+  if (opts.accounts !== undefined) {
+    finalOpts.accounts = opts.accounts;
+  }
+  const actor = new ConnectionActor(finalOpts);
   return { actor, runtime, conn };
 }
 
@@ -442,6 +490,59 @@ 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', {
@@ -563,6 +664,176 @@ describe('ConnectionActor — additional routing', () => {
     }
   });
 
+  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.
+    const { actor, runtime, conn } = makeActor({
+      conn: {
+        registration: 'pre-registration',
+        capNegotiating: true,
+        caps: new Set<string>(['sasl']),
+      },
+    });
+    // The connection needs a nick for the reducer's `nickOf(ctx)` fallback.
+    conn.nick = 'alice';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE PLAIN\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    // SASL reducer responds with `AUTHENTICATE +` to request the payload.
+    expect(lines[0]?.text).toBe('AUTHENTICATE +');
+    // Critical: never 421 for AUTHENTICATE.
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AUTHENTICATE * (abort) through authenticateReducer, never 421', async () => {
+    const { actor, runtime } = makeActor({
+      conn: {
+        registration: 'pre-registration',
+        capNegotiating: true,
+        caps: new Set<string>(['sasl']),
+        saslMech: 'PLAIN',
+      },
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AUTHENTICATE *\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    // Abort → 906 ERR_SASLABORT.
+    expect(lines[0]?.text).toContain(' 906 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AWAY :reason through awayReducer, emitting 306 RPL_NOWAWAY (never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AWAY :gone\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 306 alice :You have been marked as being away');
+    // Critical: never 421 for AWAY.
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AWAY with no params through awayReducer, emitting 305 RPL_UNAWAY (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    // Start from an away state so the unset path is observable.
+    conn.away = 'previously away';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AWAY\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 305 alice :You are no longer marked as being away',
+    );
+    expect(conn.away).toBeUndefined();
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes AWAY with an empty reason through awayReducer, emitting 305 RPL_UNAWAY (never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.away = 'previously away';
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('AWAY :\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(' 305 ');
+    expect(conn.away).toBeUndefined();
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  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');
@@ -814,3 +1085,407 @@ describe('ConnectionActor — WHO', () => {
     expect(lines[0]?.text).toBe(':irc.example.com 403 alice badname :No such channel');
   });
 });
+
+describe('ConnectionActor — flood control', () => {
+  // Pre-add the connection to #foo so under-limit PRIVMSG frames broadcast
+  // (makes the pass-through vs. disconnect contrast observable).
+  async function joinFoo(runtime: FakeRuntime): Promise<void> {
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+  }
+
+  it('disconnects a client bursting PRIVMSG past the bucket capacity with "Excess Flood"', async () => {
+    const { actor, runtime } = makeActor({});
+    await joinFoo(runtime);
+
+    // Default bucket (capacity 10, threshold 0): the first 10 PRIVMSG pass,
+    // the 11th onward trip the Disconnect path.
+    for (let i = 0; i < 20; i++) {
+      await actor.receiveTextFrame('PRIVMSG #foo :flood\r\n');
+    }
+
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects.length).toBeGreaterThan(0);
+    expect(disconnects[0]?.args[1]).toBe('Excess Flood');
+    // The close path targets the actor's own connection.
+    expect(disconnects[0]?.args[0]).toBe('c1');
+  });
+
+  it('lets the same burst pass through unchanged when flood control is disabled (floodControl: null)', async () => {
+    const { actor, runtime } = makeActor({ floodControl: null });
+    await joinFoo(runtime);
+
+    for (let i = 0; i < 20; i++) {
+      await actor.receiveTextFrame('PRIVMSG #foo :flood\r\n');
+    }
+
+    // Disabled → every frame reaches the inner reducer and broadcasts; the
+    // close path is never invoked.
+    expect(runtime.calls.filter((c) => c.method === 'disconnect')).toHaveLength(0);
+    expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(20);
+  });
+
+  it('does not let an interleaved PING advance the bucket (control-plane exemption plumbed through)', async () => {
+    const { actor, runtime } = makeActor({});
+    await joinFoo(runtime);
+
+    // 10 PRIVMSG drain the default bucket exactly to zero (no disconnect yet).
+    for (let i = 0; i < 10; i++) {
+      await actor.receiveTextFrame('PRIVMSG #foo :flood\r\n');
+    }
+    expect(runtime.calls.filter((c) => c.method === 'disconnect')).toHaveLength(0);
+
+    // A PING is control-plane traffic: it must not decrement the bucket, so
+    // it neither disconnects here nor consumes the last token. (A flat-cost
+    // wrapper would trip the Disconnect on this very frame.)
+    await actor.receiveTextFrame('PING :keepalive\r\n');
+    expect(runtime.calls.filter((c) => c.method === 'disconnect')).toHaveLength(0);
+
+    // The bucket is still at zero, so the next PRIVMSG is the one that trips
+    // the disconnect — proving the PING was free.
+    await actor.receiveTextFrame('PRIVMSG #foo :one-more\r\n');
+    const disconnects = runtime.calls.filter((c) => c.method === 'disconnect');
+    expect(disconnects).toHaveLength(1);
+    expect(disconnects[0]?.args[1]).toBe('Excess Flood');
+  });
+});
+
+// ===========================================================================
+// Observability: structured logs + traceId/connectionId
+// ===========================================================================
+
+describe('ConnectionActor — observability', () => {
+  it('emits a structured log record with traceId and connectionId for a processed frame', async () => {
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger, traceId: 'trace-xyz' });
+
+    await actor.receiveTextFrame('PING :tok\r\n');
+
+    const received = logger.records.filter((r) => r.msg === 'frame.receive');
+    expect(received).toHaveLength(1);
+    const rec = received[0];
+    expect(rec?.level).toBe(LogLevel.Debug);
+    expect(rec?.traceId).toBe('trace-xyz');
+    expect(rec?.connectionId).toBe('c1');
+    expect(rec?.fields?.command).toBe('PING');
+    expect(rec?.fields?.lines).toBe(1);
+  });
+
+  it('stamps the same traceId on every record emitted while processing one frame', async () => {
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger, traceId: 'trace-abc' });
+
+    // A joined frame exercises the per-line path; a successful reducer
+    // followed by a parse failure exercises both frame.receive and
+    // frame.parse-error records on the same trace.
+    await actor.receiveTextFrame('PING :tok\r\nBADLINE_7_DIGITS\r\n');
+
+    expect(logger.records.length).toBeGreaterThan(0);
+    for (const rec of logger.records) {
+      expect(rec.traceId).toBe('trace-abc');
+      expect(rec.connectionId).toBe('c1');
+    }
+  });
+
+  it('emits a warn-level frame.parse-error record on a malformed line', async () => {
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger, traceId: 't1' });
+
+    // 5-digit numeric prefix is not a legal IRC command → parse fails.
+    await actor.receiveTextFrame('12345\r\n');
+
+    const errs = logger.records.filter((r) => r.msg === 'frame.parse-error');
+    expect(errs).toHaveLength(1);
+    expect(errs[0]?.level).toBe(LogLevel.Warn);
+    expect(errs[0]?.traceId).toBe('t1');
+    expect(typeof errs[0]?.fields?.line).toBe('string');
+  });
+
+  it('falls back to a NoopLogger and unknown traceId when omitted', async () => {
+    // The actor must still function when no logger/traceId is supplied — the
+    // codebase's default. No exceptions, no observable output.
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PING :tok\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+  });
+
+  it('allocates a fresh traceId per receiveTextFrame call when none was supplied', async () => {
+    // Each inbound frame gets its own trace id; the actor generates one
+    // itself via IdFactory.traceId() when the caller did not pin one. Two
+    // frames → two distinct ids.
+    const logger = new CapturingLogger();
+    const { actor } = makeActor({ logger });
+
+    await actor.receiveTextFrame('PING :a\r\n');
+    await actor.receiveTextFrame('PING :b\r\n');
+
+    const ids = new Set(logger.records.map((r) => r.traceId));
+    expect(ids.size).toBe(2);
+  });
+
+  it('logs dispatch effects with the bound traceId', async () => {
+    const logger = new CapturingLogger();
+    const { actor, runtime } = makeActor({ logger, traceId: 'trace-d1' });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    const dispatchLogs = logger.records.filter((r) => r.msg === 'dispatch');
+    expect(dispatchLogs.length).toBeGreaterThan(0);
+    for (const rec of dispatchLogs) {
+      expect(rec.traceId).toBe('trace-d1');
+      expect(rec.fields?.effects).toEqual(expect.any(Array));
+    }
+  });
+});
+
+// ===========================================================================
+// CHATHISTORY — dispatcher routing + MessageStore plumbing
+// ===========================================================================
+
+describe('ConnectionActor — CHATHISTORY', () => {
+  /** The full cap set a chathistory-capable client negotiates. */
+  const CHATHISTORY_CAPS = new Set<string>([
+    'draft/chathistory',
+    'server-time',
+    'message-tags',
+    'batch',
+  ]);
+
+  /** Records `count` chronological PRIVMSG messages into `store` for `chan`. */
+  function seedMessages(store: MessageStore, chan: string, count: number): StoredMessage[] {
+    const out: StoredMessage[] = [];
+    for (let i = 1; i <= count; i++) {
+      const m: StoredMessage = {
+        msgid: `m${i}`,
+        time: i * 1_000,
+        chan: chan.toLowerCase(),
+        command: 'PRIVMSG',
+        nick: 'bob',
+        user: 'bob',
+        host: 'ex.org',
+        text: `msg ${i}`,
+      };
+      store.record(m);
+      out.push(m);
+    }
+    return out;
+  }
+
+  it('routes CHATHISTORY LATEST to the reducer, emitting a BATCH chathistory frame (never 421)', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      messages: store,
+    });
+    // Create the channel so the peek resolves it (no creation side-effect
+    // during the query itself).
+    runtime.getOrCreateChannel('#foo');
+    seedMessages(store, '#foo', 2);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 2\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    // BATCH +id chathistory #foo … BATCH -id (id from the shared id factory).
+    expect(lines[0]?.text).toMatch(/^BATCH \+batch-\d+ chathistory #foo$/);
+    const batchId = lines[0]?.text.match(/^BATCH \+batch-(\d+)/)?.[1];
+    expect(lines[lines.length - 1]?.text).toBe(`BATCH -batch-${batchId}`);
+    // Two replay lines between the batch markers.
+    expect(lines).toHaveLength(4);
+    expect(lines[1]?.text).toContain('PRIVMSG #foo :msg 1');
+    expect(lines[2]?.text).toContain('PRIVMSG #foo :msg 2');
+    // Critical: never 421 for a cap-enabled CHATHISTORY query.
+    for (const line of lines) {
+      expect(line.text).not.toContain(' 421 ');
+    }
+  });
+
+  it('still emits 421 for CHATHISTORY when the cap is not negotiated (reducer cap-gating)', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: new Set<string>() },
+      messages: store,
+    });
+    runtime.getOrCreateChannel('#foo');
+    seedMessages(store, '#foo', 2);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 2\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('CHATHISTORY');
+  });
+
+  it('emits 403 ERR_NOSUCHCHANNEL for an unknown channel target', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      messages: store,
+    });
+    // Deliberately do NOT create #nope.
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #nope * 2\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(' 403 ');
+    expect(lines[0]?.text).toContain('#nope');
+  });
+
+  it('does not crash and emits nothing when no store is bound (ctx.messages undefined)', async () => {
+    const { actor, runtime } = makeActor({
+      conn: { caps: CHATHISTORY_CAPS },
+      // No `messages` option → ctx.messages is undefined.
+    });
+    runtime.getOrCreateChannel('#foo');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('CHATHISTORY LATEST #foo * 2\r\n');
+
+    // No store → the reducer's query returns [] → empty batch elided → no
+    // Send effects. Proves the no-store path is a graceful no-op.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(0);
+  });
+
+  it('records a channel PRIVMSG into the bound store (JOIN auto-playback data source)', async () => {
+    const store = new InMemoryMessageStore();
+    const { actor, runtime } = makeActor({ messages: store });
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    const recorded = store.query({ chan: '#foo', direction: 'latest', limit: 10 });
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0]?.text).toBe('hello');
+    expect(recorded[0]?.command).toBe('PRIVMSG');
+    expect(recorded[0]?.nick).toBe('alice');
+  });
+
+  it('does not record a PRIVMSG when no store is bound (unchanged behaviour)', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    // Broadcast still happens (the message is delivered live)…
+    expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(1);
+    // …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();
+  });
+});