serverless-ircd 0.1.0

package/packages/irc-core/tests/commands/join.test.ts

@@ -0,0 +1,687 @@
+import { describe, expect, it } from 'vitest';
+import { handleJoinZero, isValidChannelName, joinReducer } from '../../src/commands/join';
+import { Effect } from '../../src/effects';
+import type { Effect as EffectType, RawLine } from '../../src/effects';
+import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
+import { type ChannelState, createChannel } from '../../src/state/channel';
+import { type ConnectionState, createConnection } from '../../src/state/connection';
+import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
+
+const serverConfig: ServerConfig = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+};
+
+function makeCtx(conn: ConnectionState, clock = new FakeClock(1_000)): Ctx {
+  return buildCtx({
+    serverConfig,
+    clock,
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: conn,
+  });
+}
+
+function makeConn(id = 'c1', nick = 'alice'): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  s.nick = nick;
+  s.user = nick;
+  s.host = 'example.com';
+  s.realname = nick.charAt(0).toUpperCase() + nick.slice(1);
+  s.registration = 'registered';
+  return s;
+}
+
+function makeChan(name = '#foo'): ChannelState {
+  return createChannel({ name, nameLower: name.toLowerCase(), createdAt: 0 });
+}
+
+const L = (text: string): RawLine => ({ text });
+
+/** Adds a non-op member to the channel for setups that need a pre-populated roster. */
+function addMember(chan: ChannelState, connId: string, nick: string, op = false): void {
+  chan.members.set(connId, { conn: connId, nick, op, voice: false });
+}
+
+// ============================================================================
+// isValidChannelName
+// ============================================================================
+
+describe('isValidChannelName', () => {
+  it('accepts a # channel', () => {
+    expect(isValidChannelName('#foo', 50)).toBe(true);
+  });
+
+  it('accepts a & channel', () => {
+    expect(isValidChannelName('&foo', 50)).toBe(true);
+  });
+
+  it('accepts a single-char name after the prefix', () => {
+    expect(isValidChannelName('#a', 50)).toBe(true);
+  });
+
+  it('rejects an empty string', () => {
+    expect(isValidChannelName('', 50)).toBe(false);
+  });
+
+  it('rejects a name without a channel prefix', () => {
+    expect(isValidChannelName('foo', 50)).toBe(false);
+  });
+
+  it('rejects a name starting with +', () => {
+    expect(isValidChannelName('+foo', 50)).toBe(false);
+  });
+
+  it('rejects a name containing a space', () => {
+    expect(isValidChannelName('#foo bar', 50)).toBe(false);
+  });
+
+  it('rejects a name containing a comma', () => {
+    expect(isValidChannelName('#foo,bar', 50)).toBe(false);
+  });
+
+  it('rejects a name containing a colon', () => {
+    expect(isValidChannelName('#foo:bar', 50)).toBe(false);
+  });
+
+  it('rejects a name exceeding the length cap', () => {
+    expect(isValidChannelName(`#${'a'.repeat(50)}`, 50)).toBe(false);
+  });
+
+  it('accepts a name at exactly the length cap', () => {
+    expect(isValidChannelName(`#${'a'.repeat(49)}`, 50)).toBe(true);
+  });
+});
+
+// ============================================================================
+// joinReducer — success path
+// ============================================================================
+
+describe('joinReducer — success', () => {
+  it('broadcasts JOIN to the channel including the joiner and sends 353/366 to the joiner', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.applyChannelDelta('#foo', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'alice', op: true }],
+      }),
+      Effect.broadcast(
+        '#foo',
+        [L(':alice!alice@example.com JOIN #foo')],
+        undefined,
+        'extended-join',
+        [L(':alice!alice@example.com JOIN #foo _ :Alice')],
+      ),
+      Effect.send('c1', [
+        L(':irc.example.com 353 alice = #foo :@alice'),
+        L(':irc.example.com 366 alice #foo :End of /NAMES list.'),
+      ]),
+    ]);
+  });
+
+  it('adds the joiner to the channel roster as a regular member when others are present', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c2', 'bob');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const entry = out.state.members.get('c1');
+    expect(entry).toBeDefined();
+    if (entry !== undefined) {
+      expect(entry.nick).toBe('alice');
+      expect(entry.op).toBe(false);
+      expect(entry.voice).toBe(false);
+    }
+  });
+
+  it('grants op to the first user to join a channel', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const entry = out.state.members.get('c1');
+    expect(entry?.op).toBe(true);
+  });
+
+  it('adds the channel to the connection joinedChannels set (cross-authority mutation)', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(conn.joinedChannels.has('#foo')).toBe(true);
+  });
+
+  it('updates the connection lastSeen to ctx.clock.now()', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const clock = new FakeClock(9_000);
+    const ctx = makeCtx(conn, clock);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.state).toBe(chan);
+    expect(conn.lastSeen).toBe(9_000);
+  });
+
+  it('lists existing members with their prefixes in the 353 NAMES reply', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c2', 'bob', true);
+    addMember(chan, 'c3', 'carol');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    // bob is op (@), carol is a regular member. alice is added by this join and
+    // is NOT op (she is not first). Names list is one space-separated trailing
+    // param; we assert the substring membership rather than exact ordering since
+    // roster iteration order matches insertion.
+    const sendEffect = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Send' }> => e.tag === 'Send',
+    );
+    expect(sendEffect).toBeDefined();
+    const namesLine = sendEffect?.lines.find((l) => l.text.startsWith(':irc.example.com 353'));
+    expect(namesLine).toBeDefined();
+    expect(namesLine?.text).toContain('@bob');
+    expect(namesLine?.text).toContain('carol');
+    expect(namesLine?.text).toContain('alice');
+  });
+
+  it('uses * as the secret-channel sigil in 353 when +s is set', () => {
+    const chan = makeChan('#foo');
+    chan.modes.secret = true;
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const sendEffect = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Send' }> => e.tag === 'Send',
+    );
+    const namesLine = sendEffect?.lines.find((l) => l.text.startsWith(':irc.example.com 353'));
+    expect(namesLine?.text).toContain('353 alice * #foo');
+  });
+
+  it('uses @ as the private-channel sigil in 353 when +p is set', () => {
+    const chan = makeChan('#foo');
+    chan.modes.private = true;
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const sendEffect = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Send' }> => e.tag === 'Send',
+    );
+    const namesLine = sendEffect?.lines.find((l) => l.text.startsWith(':irc.example.com 353'));
+    expect(namesLine?.text).toContain('353 alice @ #foo');
+  });
+
+  it('accepts the correct key for a +k channel', () => {
+    const chan = makeChan('#foo');
+    chan.modes.key = 'secret';
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo', 'secret'], tags: {} }, ctx);
+
+    expect(out.state.members.has('c1')).toBe(true);
+  });
+
+  it('proceeds with the join when the ban list is non-empty but no mask matches', () => {
+    const chan = makeChan('#foo');
+    chan.banMasks.add('*!*@baddomain.example');
+    chan.banMasks.add('evil!*@*');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.state.members.has('c1')).toBe(true);
+    const sendEffect = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Send' }> => e.tag === 'Send',
+    );
+    expect(sendEffect).toBeDefined();
+  });
+
+  it('allows an invited user to bypass +i', () => {
+    const chan = makeChan('#foo');
+    chan.modes.inviteOnly = true;
+    // Pending invites are keyed by lowercased nick.
+    chan.pendingInvites.add('alice');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.state.members.has('c1')).toBe(true);
+    // invite is consumed
+    expect(out.state.pendingInvites.has('alice')).toBe(false);
+  });
+
+  it('includes the joiner in the broadcast (no except)', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.except).toBeUndefined();
+  });
+
+  it('returns the same state reference (mutation permitted, no copy)', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.state).toBe(chan);
+  });
+
+  it('builds the JOIN source from the connection hostmask without @host when host is absent', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+    delete conn.host;
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toContainEqual<EffectType>(
+      Effect.broadcast('#foo', [L(':alice!alice JOIN #foo')], undefined, 'extended-join', [
+        L(':alice!alice JOIN #foo _ :Alice'),
+      ]),
+    );
+  });
+
+  it('falls back to ? and * placeholders when the connection has no nick', () => {
+    const chan = makeChan('#foo');
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    // Roster entry uses '?' since no nick is available.
+    expect(out.state.members.get('c1')?.nick).toBe('?');
+    // JOIN broadcast source is '?'.
+    expect(out.effects).toContainEqual<EffectType>(Effect.broadcast('#foo', [L(':? JOIN #foo')]));
+    // 353/366 use '*' as the numeric target. The joiner is first, so it is
+    // also an op and appears as `@?` in the names list.
+    const sendEffect = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Send' }> => e.tag === 'Send',
+    );
+    expect(sendEffect?.lines[0]?.text).toBe(':irc.example.com 353 * = #foo :@?');
+    expect(sendEffect?.lines[1]?.text).toBe(':irc.example.com 366 * #foo :End of /NAMES list.');
+  });
+});
+
+// ============================================================================
+// joinReducer — rejections
+// ============================================================================
+
+describe('joinReducer — rejections', () => {
+  it('emits 461 ERR_NEEDMOREPARAMS when no channel is supplied', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: [], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 461 alice JOIN :Not enough parameters')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('emits 403 ERR_NOSUCHCHANNEL for a channel name without a valid prefix', () => {
+    const chan = makeChan('foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 403 alice foo :No such channel')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('emits 403 ERR_NOSUCHCHANNEL for a channel name containing a comma', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo,bar'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 403 alice #foo,bar :No such channel')]),
+    ]);
+  });
+
+  it('emits 405 ERR_TOOMANYCHANNELS when the connection is at the max-channels limit', () => {
+    const chan = makeChan('#newchan');
+    const conn = makeConn();
+    for (let i = 0; i < serverConfig.maxChannelsPerUser; i++) {
+      conn.joinedChannels.add(`#c${i}`);
+    }
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#newchan'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [
+        L(':irc.example.com 405 alice #newchan :You have joined too many channels'),
+      ]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('does not count a channel the user is already on against the max-channels limit', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    for (let i = 0; i < serverConfig.maxChannelsPerUser; i++) {
+      conn.joinedChannels.add(`#c${i}`);
+    }
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    // No error: the user is already on #foo, so this is a silent no-op.
+    expect(out.effects).toEqual([]);
+  });
+
+  it('emits 474 ERR_BANNEDFROMCHAN when a ban mask matches the joiner hostmask', () => {
+    const chan = makeChan('#foo');
+    chan.banMasks.add('*!*@example.com');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 474 alice #foo :Cannot join channel (+b)')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('honors the ? wildcard in ban masks when checking the joiner hostmask', () => {
+    const chan = makeChan('#foo');
+    // `?` matches exactly one char; five `?` match the 5-char user segment
+    // `alice` between `!` and `@` in alice!alice@example.com.
+    chan.banMasks.add('alice!?????@example.com');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 474 alice #foo :Cannot join channel (+b)')]),
+    ]);
+  });
+
+  it('emits 473 ERR_INVITEONLYCHAN when +i is set and the connection has no pending invite', () => {
+    const chan = makeChan('#foo');
+    chan.modes.inviteOnly = true;
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 473 alice #foo :Cannot join channel (+i)')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('emits 471 ERR_CHANNELISFULL when +l is set and the roster is at the limit', () => {
+    const chan = makeChan('#foo');
+    chan.modes.limit = 1;
+    addMember(chan, 'c2', 'bob');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 471 alice #foo :Cannot join channel (+l)')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('emits 475 ERR_BADCHANNELKEY when +k is set and no key was supplied', () => {
+    const chan = makeChan('#foo');
+    chan.modes.key = 'secret';
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 475 alice #foo :Cannot join channel (+k)')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('emits 475 ERR_BADCHANNELKEY when +k is set and the supplied key is wrong', () => {
+    const chan = makeChan('#foo');
+    chan.modes.key = 'secret';
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo', 'wrong'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 475 alice #foo :Cannot join channel (+k)')]),
+    ]);
+    expect(out.state.members.has('c1')).toBe(false);
+  });
+
+  it('uses * in numeric replies when the connection has no nick (defensive)', () => {
+    const chan = makeChan('badname');
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['badname'], tags: {} }, ctx);
+
+    // 403 path fires numericErr, which substitutes `*` for the absent nick.
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 403 * badname :No such channel')]),
+    ]);
+  });
+});
+
+// ============================================================================
+// joinReducer — already on channel
+// ============================================================================
+
+describe('joinReducer — already on channel', () => {
+  it('is a silent no-op when the joiner is already on the channel', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    expect(out.effects).toEqual([]);
+    expect(out.state.members.size).toBe(1);
+  });
+});
+
+// ============================================================================
+// handleJoinZero
+// ============================================================================
+
+describe('handleJoinZero', () => {
+  it('emits a PART broadcast and roster-removal delta for every joined channel', () => {
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    conn.joinedChannels.add('#bar');
+    const ctx = makeCtx(conn);
+
+    const effects = handleJoinZero(ctx);
+
+    expect(effects).toEqual<EffectType[]>(
+      expect.arrayContaining([
+        Effect.broadcast('#foo', [L(':alice!alice@example.com PART #foo')]),
+        Effect.broadcast('#bar', [L(':alice!alice@example.com PART #bar')]),
+      ]),
+    );
+    // One roster-removal delta per channel.
+    const deltas = effects.filter(
+      (e): e is Extract<EffectType, { tag: 'ApplyChannelDelta' }> => e.tag === 'ApplyChannelDelta',
+    );
+    expect(deltas).toHaveLength(2);
+  });
+
+  it('clears the connection joinedChannels set', () => {
+    const conn = makeConn();
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn);
+
+    handleJoinZero(ctx);
+
+    expect(conn.joinedChannels.size).toBe(0);
+  });
+
+  it('emits no effects when the connection has joined no channels', () => {
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const effects = handleJoinZero(ctx);
+
+    expect(effects).toEqual([]);
+  });
+});
+
+// ============================================================================
+// joinReducer — IRCv3 extended-join
+// (https://ircv3.net/specs/extensions/extended-join-3.1.html)
+//
+// Peers that negotiated `extended-join` see the account + realname in the
+// JOIN line; legacy peers see the bare channel. The reducer cannot see each
+// recipient's caps, so it emits one cap-split Broadcast: `lines` (legacy) for
+// non-cap members and `capLines` (extended) for cap-enabled members. The
+// dispatch layer resolves per-recipient.
+// ============================================================================
+
+describe('joinReducer — extended-join', () => {
+  it('emits a cap-split broadcast with the extended JOIN for cap-enabled peers', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    // Extended format: :nick!user@host JOIN #chan account :realname.
+    // Account is `_` (not logged in); realname from USER.
+    expect(out.effects).toContainEqual<EffectType>(
+      Effect.broadcast(
+        '#foo',
+        [L(':alice!alice@example.com JOIN #foo')],
+        undefined,
+        'extended-join',
+        [L(':alice!alice@example.com JOIN #foo _ :Alice')],
+      ),
+    );
+  });
+
+  it('uses the authenticated account name in the extended JOIN when set', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    conn.account = 'alice-account';
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const extended = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> =>
+        e.tag === 'Broadcast' && e.cap === 'extended-join',
+    );
+    expect(extended?.capLines).toEqual([
+      L(':alice!alice@example.com JOIN #foo alice-account :Alice'),
+    ]);
+  });
+
+  it('uses _ as the account when the joiner is not authenticated', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const extended = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> =>
+        e.tag === 'Broadcast' && e.cap === 'extended-join',
+    );
+    expect(extended?.capLines?.[0]?.text).toBe(':alice!alice@example.com JOIN #foo _ :Alice');
+  });
+
+  it('carries the legacy JOIN line for non-cap peers', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.lines).toEqual([L(':alice!alice@example.com JOIN #foo')]);
+  });
+
+  it('includes the joiner in the broadcast (no except)', () => {
+    const chan = makeChan('#foo');
+    const conn = makeConn();
+    conn.caps.add('extended-join');
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.except).toBeUndefined();
+  });
+
+  it('falls back to a legacy-only broadcast when realname is absent (defensive)', () => {
+    const chan = makeChan('#foo');
+    // Bare connection: no nick, user, host, or realname.
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    const ctx = makeCtx(conn);
+
+    const out = joinReducer(chan, { command: 'JOIN', params: ['#foo'], tags: {} }, ctx);
+
+    // No cap-split: plain legacy broadcast with no cap/capLines fields.
+    expect(out.effects).toContainEqual<EffectType>(Effect.broadcast('#foo', [L(':? JOIN #foo')]));
+    const broadcast = out.effects.find(
+      (e): e is Extract<EffectType, { tag: 'Broadcast' }> => e.tag === 'Broadcast',
+    );
+    expect(broadcast?.cap).toBeUndefined();
+    expect(broadcast?.capLines).toBeUndefined();
+  });
+});