serverless-ircd 0.1.0 → 0.3.0

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

@@ -8,7 +8,14 @@ import {
 } from '../../src/commands/privmsg';
 import { Effect } from '../../src/effects';
 import type { Effect as EffectType, RawLine } from '../../src/effects';
-import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
+import {
+  EmptyMotdProvider,
+  FakeClock,
+  InMemoryMessageStore,
+  type MessageStore,
+  SequentialIdFactory,
+  type StoredMessage,
+} 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';
@@ -25,13 +32,18 @@ const serverConfig: ServerConfig = {
   quitMessage: 'Client Quit',
 };
 
-function makeCtx(conn: ConnectionState, clock = new FakeClock(1_000)): Ctx {
+function makeCtx(
+  conn: ConnectionState,
+  clock = new FakeClock(1_000),
+  messages?: MessageStore,
+): Ctx {
   return buildCtx({
     serverConfig,
     clock,
     ids: new SequentialIdFactory(),
     motd: EmptyMotdProvider,
     connection: conn,
+    ...(messages !== undefined ? { messages } : {}),
   });
 }
 
@@ -663,3 +675,135 @@ describe('noticeUserReducer', () => {
     expect(out.effects).toEqual([]);
   });
 });
+
+// ============================================================================
+// chathistory recording — MessageStore.record is driven from the channel
+// PRIVMSG/NOTICE reducer for every accepted message.
+// ============================================================================
+
+describe('privmsgChannelReducer — chathistory recording', () => {
+  it('records the accepted PRIVMSG into ctx.messages with a fresh msgid and time', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    const store = new InMemoryMessageStore();
+    const conn = makeConn();
+    const clock = new FakeClock(7_700);
+    const ctx = makeCtx(conn, clock, store);
+
+    privmsgChannelReducer(chan, { command: 'PRIVMSG', params: ['#foo', 'hi'], tags: {} }, ctx);
+
+    const recorded = store.query({ chan: '#foo', direction: 'latest', limit: 10 });
+    expect(recorded).toHaveLength(1);
+    const entry = recorded[0] as StoredMessage | undefined;
+    expect(entry).toBeDefined();
+    expect(entry?.msgid).toBe('nonce-0');
+    expect(entry?.time).toBe(7_700);
+    expect(entry?.chan).toBe('#foo');
+    expect(entry?.command).toBe('PRIVMSG');
+    expect(entry?.nick).toBe('alice');
+    expect(entry?.user).toBe('alice');
+    expect(entry?.host).toBe('example.com');
+    expect(entry?.text).toBe('hi');
+  });
+
+  it('records an accepted channel NOTICE too', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    const store = new InMemoryMessageStore();
+    const ctx = makeCtx(makeConn(), new FakeClock(1_000), store);
+
+    noticeChannelReducer(chan, { command: 'NOTICE', params: ['#foo', 'note'], tags: {} }, ctx);
+
+    const recorded = store.query({ chan: '#foo', direction: 'latest', limit: 10 });
+    expect(recorded).toHaveLength(1);
+    expect((recorded[0] as StoredMessage).command).toBe('NOTICE');
+    expect((recorded[0] as StoredMessage).text).toBe('note');
+  });
+
+  it('does NOT record when ctx.messages is absent (chathistory disabled)', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    const conn = makeConn();
+    const ctx = makeCtx(conn); // no store
+
+    // Should not throw and should still broadcast.
+    const out = privmsgChannelReducer(
+      chan,
+      { command: 'PRIVMSG', params: ['#foo', 'hi'], tags: {} },
+      ctx,
+    );
+    expect(out.effects[0]?.tag).toBe('Broadcast');
+  });
+
+  it('does NOT record a user-target PRIVMSG (only channel messages are persisted)', () => {
+    const store = new InMemoryMessageStore();
+    const conn = makeConn();
+    const ctx = makeCtx(conn, new FakeClock(1_000), store);
+
+    privmsgUserReducer(conn, { command: 'PRIVMSG', params: ['bob', 'hi'], tags: {} }, ctx);
+
+    expect(store.targets(0, 100_000)).toEqual([]);
+  });
+
+  it('does NOT record a user-target NOTICE', () => {
+    const store = new InMemoryMessageStore();
+    const conn = makeConn();
+    const ctx = makeCtx(conn, new FakeClock(1_000), store);
+
+    noticeUserReducer(conn, { command: 'NOTICE', params: ['bob', 'hi'], tags: {} }, ctx);
+
+    expect(store.targets(0, 100_000)).toEqual([]);
+  });
+
+  it('does NOT record when the message is blocked by +n (no external messages)', () => {
+    const chan = makeChan('#foo');
+    chan.modes.noExternal = true;
+    // sender c1 is NOT a member
+    const store = new InMemoryMessageStore();
+    const ctx = makeCtx(makeConn(), new FakeClock(1_000), store);
+
+    privmsgChannelReducer(chan, { command: 'PRIVMSG', params: ['#foo', 'hi'], tags: {} }, ctx);
+
+    expect(store.query({ chan: '#foo', direction: 'latest', limit: 10 })).toEqual([]);
+  });
+
+  it('does NOT record when the message is blocked by +m (moderated, no voice)', () => {
+    const chan = makeChan('#foo');
+    chan.modes.moderated = true;
+    addMember(chan, 'c1', 'alice', false, false); // not op, not voiced
+    const store = new InMemoryMessageStore();
+    const ctx = makeCtx(makeConn(), new FakeClock(1_000), store);
+
+    privmsgChannelReducer(chan, { command: 'PRIVMSG', params: ['#foo', 'hi'], tags: {} }, ctx);
+
+    expect(store.query({ chan: '#foo', direction: 'latest', limit: 10 })).toEqual([]);
+  });
+
+  it('does NOT record when the sender is banned (+b)', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    chan.banMasks.add('*!*@evil.com');
+    const conn = makeConn('c1', 'alice');
+    conn.host = 'evil.com';
+    const store = new InMemoryMessageStore();
+    const ctx = makeCtx(conn, new FakeClock(1_000), store);
+
+    privmsgChannelReducer(chan, { command: 'PRIVMSG', params: ['#foo', 'hi'], tags: {} }, ctx);
+
+    expect(store.query({ chan: '#foo', direction: 'latest', limit: 10 })).toEqual([]);
+  });
+
+  it('uses a distinct msgid per recorded message (ctx.ids.nonce() each time)', () => {
+    const chan = makeChan('#foo');
+    addMember(chan, 'c1', 'alice');
+    const store = new InMemoryMessageStore();
+    const conn = makeConn();
+    const ctx = makeCtx(conn, new FakeClock(1_000), store);
+
+    privmsgChannelReducer(chan, { command: 'PRIVMSG', params: ['#foo', 'one'], tags: {} }, ctx);
+    privmsgChannelReducer(chan, { command: 'PRIVMSG', params: ['#foo', 'two'], tags: {} }, ctx);
+
+    const recorded = store.query({ chan: '#foo', direction: 'latest', limit: 10 });
+    expect(recorded.map((m) => m.msgid)).toEqual(['nonce-0', 'nonce-1']);
+  });
+});

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

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { cloakHost } from '../../src/cloak';
 import { generateIsupport } from '../../src/commands/isupport';
 import {
   buildWelcomeLines,
@@ -10,7 +11,13 @@ import {
 } from '../../src/commands/registration';
 import { Effect } from '../../src/effects';
 import type { Effect as EffectType, RawLine } from '../../src/effects';
-import { EmptyMotdProvider, FakeClock, SequentialIdFactory } from '../../src/ports';
+import {
+  EmptyMotdProvider,
+  FakeClock,
+  SequentialIdFactory,
+  StaticMotdProvider,
+} from '../../src/ports';
+import type { MotdProvider } from '../../src/ports';
 import { type ConnectionState, createConnection } from '../../src/state/connection';
 import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
 
@@ -26,12 +33,16 @@ const serverConfig: ServerConfig = {
   quitMessage: 'Client Quit',
 };
 
-function makeCtx(state: ConnectionState, clock = new FakeClock(1_000)): Ctx {
+function makeCtx(
+  state: ConnectionState,
+  clock = new FakeClock(1_000),
+  motd: MotdProvider = EmptyMotdProvider,
+): Ctx {
   return buildCtx({
     serverConfig,
     clock,
     ids: new SequentialIdFactory(),
-    motd: EmptyMotdProvider,
+    motd,
     connection: state,
   });
 }
@@ -75,13 +86,11 @@ function expectedWelcome(nick: string, user: string, host: string | undefined):
   );
   return [
     L(`${prefix} 001 ${nick} :Welcome to the ExampleNet IRC Network, ${hostmask}`),
-    L(`${prefix} 002 ${nick} :Your host is ${sv}, running version 0.1.0`),
+    L(`${prefix} 002 ${nick} :Your host is ${sv}, running version 0.2.0`),
     L(`${prefix} 003 ${nick} :This server was created in Phase 1`),
-    L(`${prefix} 004 ${nick} ${sv} 0.1.0 iosw biklmnstp`),
+    L(`${prefix} 004 ${nick} ${sv} 0.2.0 iosw biklmnstp`),
     ...isupport,
-    L(`${prefix} 375 ${nick} :- ${sv} Message of the day -`),
-    L(`${prefix} 372 ${nick} :- MOTD placeholder`),
-    L(`${prefix} 376 ${nick} :End of MOTD command`),
+    L(`${prefix} 422 ${nick} :MOTD File is missing`),
   ];
 }
 
@@ -488,19 +497,22 @@ describe('passReducer', () => {
 // ============================================================================
 
 describe('buildWelcomeLines', () => {
-  it('produces the welcome block in the correct numeric order', () => {
+  it('produces the welcome block in the correct numeric order with MOTD content', () => {
     const state = makeState();
     state.nick = 'alice';
     state.user = 'alice';
     state.host = 'example.com';
-    const lines = buildWelcomeLines(state, makeCtx(state));
-    // 8 base lines (001-004, one or more 005, 375, 372, 376).
+    const lines = buildWelcomeLines(
+      state,
+      makeCtx(state, new FakeClock(1_000), new StaticMotdProvider(['line one', 'line two'])),
+    );
     expect(lines.length).toBeGreaterThanOrEqual(8);
     const codes = lines.map((l) => l.text.split(' ')[1]);
-    // First four numerics in fixed order; 005 (>=1); final three in order.
+    // First four numerics in fixed order; 005 (>=1); MOTD block last.
     expect(codes.slice(0, 4)).toEqual(['001', '002', '003', '004']);
     expect(codes[4]).toBe('005');
-    expect(codes.at(-3)).toBe('375');
+    expect(codes.at(-4)).toBe('375');
+    expect(codes.at(-3)).toBe('372');
     expect(codes.at(-2)).toBe('372');
     expect(codes.at(-1)).toBe('376');
   });
@@ -556,6 +568,89 @@ describe('buildWelcomeLines', () => {
   });
 });
 
+// ============================================================================
+// buildWelcomeLines — MOTD driven from MotdProvider
+// ============================================================================
+
+describe('buildWelcomeLines — MOTD content', () => {
+  it('emits one 372 per MOTD line sourced from the MotdProvider', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.host = 'example.com';
+    const lines = buildWelcomeLines(
+      state,
+      makeCtx(state, new FakeClock(1_000), new StaticMotdProvider(['line A', 'line B'])),
+    );
+    const rpl372 = lines.filter((l) => l.text.split(' ')[1] === '372');
+    expect(rpl372).toHaveLength(2);
+    expect(rpl372[0]).toEqual(L(':irc.example.com 372 alice :- line A'));
+    expect(rpl372[1]).toEqual(L(':irc.example.com 372 alice :- line B'));
+  });
+
+  it('frames the MOTD content with 375 start and 376 end', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const lines = buildWelcomeLines(
+      state,
+      makeCtx(state, new FakeClock(1_000), new StaticMotdProvider(['hi'])),
+    );
+    expect(lines).toContainEqual(
+      L(':irc.example.com 375 alice :- irc.example.com Message of the day -'),
+    );
+    expect(lines).toContainEqual(L(':irc.example.com 372 alice :- hi'));
+    expect(lines).toContainEqual(L(':irc.example.com 376 alice :End of MOTD command'));
+  });
+
+  it('reads MOTD lines fresh from the provider on each call', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const provider = new StaticMotdProvider(['first']);
+    const ctx = makeCtx(state, new FakeClock(1_000), provider);
+    const first = buildWelcomeLines(state, ctx).filter((l) => l.text.split(' ')[1] === '372');
+    provider.setLines(['first', 'second']);
+    const second = buildWelcomeLines(state, ctx).filter((l) => l.text.split(' ')[1] === '372');
+    expect(first).toHaveLength(1);
+    expect(second).toHaveLength(2);
+  });
+
+  it('splits over-long MOTD lines so every emitted line fits the 510-byte budget', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.host = 'example.com';
+    const long = 'A'.repeat(2_000);
+    const lines = buildWelcomeLines(
+      state,
+      makeCtx(state, new FakeClock(1_000), new StaticMotdProvider([long])),
+    );
+    for (const line of lines) {
+      expect(line.text.length).toBeLessThanOrEqual(510);
+    }
+    // The single over-long line is hard-wrapped into many 372 chunks.
+    const rpl372 = lines.filter((l) => l.text.split(' ')[1] === '372');
+    expect(rpl372.length).toBeGreaterThan(1);
+  });
+});
+
+describe('buildWelcomeLines — empty MOTD', () => {
+  it('emits 422 ERR_NOMOTD instead of a placeholder when no MOTD is configured', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const lines = buildWelcomeLines(state, makeCtx(state));
+    const codes = lines.map((l) => l.text.split(' ')[1]);
+    expect(codes.at(-1)).toBe('422');
+    expect(lines).toContainEqual(L(':irc.example.com 422 alice :MOTD File is missing'));
+    // No MOTD framing numerics leak through on the empty path.
+    expect(codes).not.toContain('375');
+    expect(codes).not.toContain('372');
+    expect(codes).not.toContain('376');
+  });
+});
+
 // ============================================================================
 // emitWelcomeIfReady
 // ============================================================================
@@ -567,33 +662,298 @@ describe('emitWelcomeIfReady', () => {
     state.user = 'alice';
     const ctx = makeCtx(state);
     const effect = emitWelcomeIfReady(state, ctx);
-    expect(effect).toEqual(Effect.send('c1', expectedWelcome('alice', 'alice', undefined)));
+    expect(effect).toEqual([Effect.send('c1', expectedWelcome('alice', 'alice', undefined))]);
     expect(state.registration).toBe('registered');
   });
 
-  it('returns null and does not transition when nick is missing', () => {
+  it('returns an empty array and does not transition when nick is missing', () => {
     const state = makeState();
     state.user = 'alice';
     const ctx = makeCtx(state);
     const effect = emitWelcomeIfReady(state, ctx);
-    expect(effect).toBeNull();
+    expect(effect).toEqual([]);
     expect(state.registration).toBe('pre-registration');
   });
 
-  it('returns null and does not transition when user is missing', () => {
+  it('returns an empty array and does not transition when user is missing', () => {
     const state = makeState();
     state.nick = 'alice';
     const ctx = makeCtx(state);
     const effect = emitWelcomeIfReady(state, ctx);
-    expect(effect).toBeNull();
+    expect(effect).toEqual([]);
     expect(state.registration).toBe('pre-registration');
   });
 
-  it('returns null when already registered', () => {
+  it('returns an empty array when already registered', () => {
     const state = registeredState();
     const ctx = makeCtx(state);
     const effect = emitWelcomeIfReady(state, ctx);
-    expect(effect).toBeNull();
+    expect(effect).toEqual([]);
+    expect(state.registration).toBe('registered');
+  });
+});
+
+// ============================================================================
+// emitWelcomeIfReady — server-password gate
+// ============================================================================
+
+/** Builds a ctx whose serverConfig has a serverPassword set. */
+function makeCtxWithPassword(state: ConnectionState, password: string): Ctx {
+  return buildCtx({
+    serverConfig: { ...serverConfig, serverPassword: password },
+    clock: new FakeClock(1_000),
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: state,
+  });
+}
+
+describe('emitWelcomeIfReady — server-password gate', () => {
+  it('proceeds with registration when no serverPassword is configured', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const ctx = makeCtx(state);
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(effects).toEqual([Effect.send('c1', expectedWelcome('alice', 'alice', undefined))]);
+    expect(state.registration).toBe('registered');
+  });
+
+  it('proceeds with registration when serverPassword is empty (disabled)', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const ctx = makeCtxWithPassword(state, '');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(state.registration).toBe('registered');
+    expect(effects).toEqual([Effect.send('c1', expectedWelcome('alice', 'alice', undefined))]);
+  });
+
+  it('blocks registration with 464 + Disconnect when passAttempt is missing', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(state.registration).not.toBe('registered');
+    expect(effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 464 alice :Password mismatch')]),
+      Effect.disconnect('c1', 'Bad Password'),
+    ]);
+  });
+
+  it('blocks registration with 464 + Disconnect when passAttempt is wrong', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.passAttempt = 'wrong';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(state.registration).not.toBe('registered');
+    expect(effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 464 alice :Password mismatch')]),
+      Effect.disconnect('c1', 'Bad Password'),
+    ]);
+  });
+
+  it('proceeds with registration when passAttempt matches serverPassword', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.passAttempt = 's3cret';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(state.registration).toBe('registered');
+    expect(effects).toEqual([Effect.send('c1', expectedWelcome('alice', 'alice', undefined))]);
+  });
+
+  it('satisfies the gate when SASL has authenticated an account (no PASS needed)', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.account = 'alice';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(state.registration).toBe('registered');
+    expect(effects).toEqual([Effect.send('c1', expectedWelcome('alice', 'alice', undefined))]);
+  });
+
+  it('does not register when nick is missing even if password is configured', () => {
+    const state = makeState();
+    state.user = 'alice';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(effects).toEqual([]);
+    expect(state.registration).toBe('pre-registration');
+  });
+
+  it('does not register when capNegotiating is true even if password is configured', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.capNegotiating = true;
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const effects = emitWelcomeIfReady(state, ctx);
+    expect(effects).toEqual([]);
+    expect(state.registration).toBe('pre-registration');
+  });
+});
+
+// ============================================================================
+// userReducer / nickReducer — server-password gate integration
+// ============================================================================
+
+describe('userReducer — server-password gate integration', () => {
+  it('emits 464 + Disconnect on the completing USER when passAttempt is wrong', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.registration = 'registering';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const out = userReducer(
+      state,
+      { command: 'USER', params: ['alice', '0', '*', 'Alice'], tags: {} },
+      ctx,
+    );
+    expect(state.registration).not.toBe('registered');
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', [L(':irc.example.com 464 alice :Password mismatch')]),
+      Effect.disconnect('c1', 'Bad Password'),
+    ]);
+  });
+
+  it('completes registration on the completing USER when passAttempt matches', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.passAttempt = 's3cret';
+    state.registration = 'registering';
+    const ctx = makeCtxWithPassword(state, 's3cret');
+    const out = userReducer(
+      state,
+      { command: 'USER', params: ['alice', '0', '*', 'Alice'], tags: {} },
+      ctx,
+    );
     expect(state.registration).toBe('registered');
+    expect(out.effects).toEqual<EffectType[]>([
+      Effect.send('c1', expectedWelcome('alice', 'alice', undefined)),
+    ]);
   });
 });
+
+// ============================================================================
+// emitWelcomeIfReady — hostmask cloaking integration
+// ============================================================================
+
+function makeCtxWithCloaking(
+  state: ConnectionState,
+  cloaking: { enabled: boolean; secret: string; cloakedSuffix?: string },
+): Ctx {
+  return buildCtx({
+    serverConfig: { ...serverConfig, cloaking },
+    clock: new FakeClock(1_000),
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: state,
+  });
+}
+
+describe('emitWelcomeIfReady — hostmask cloaking', () => {
+  it('leaves host untouched when cloaking is disabled', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.host = '203.0.113.5';
+    const ctx = makeCtxWithCloaking(state, { enabled: false, secret: 's3cret' });
+    emitWelcomeIfReady(state, ctx);
+    expect(state.host).toBe('203.0.113.5');
+  });
+
+  it('replaces the real host with a deterministic cloak when enabled', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.host = '203.0.113.5';
+    const ctx = makeCtxWithCloaking(state, { enabled: true, secret: 's3cret' });
+    emitWelcomeIfReady(state, ctx);
+    expect(state.host).toBe(
+      cloakHost('203.0.113.5', { enabled: true, secret: 's3cret' }, 'ExampleNet'),
+    );
+    expect(state.host).not.toBe('203.0.113.5');
+  });
+
+  it('uses the configured cloakedSuffix when supplied', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.host = '203.0.113.5';
+    const ctx = makeCtxWithCloaking(state, {
+      enabled: true,
+      secret: 's3cret',
+      cloakedSuffix: 'hidden.lan',
+    });
+    emitWelcomeIfReady(state, ctx);
+    expect(state.host).toBe(
+      cloakHost(
+        '203.0.113.5',
+        { enabled: true, secret: 's3cret', cloakedSuffix: 'hidden.lan' },
+        'ExampleNet',
+      ),
+    );
+    expect(state.host.endsWith('.hidden.lan')).toBe(true);
+  });
+
+  it('cloaks the host before building the welcome hostmask so 001 shows the cloak', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    state.host = '203.0.113.5';
+    const ctx = makeCtxWithCloaking(state, { enabled: true, secret: 's3cret' });
+    const effects = emitWelcomeIfReady(state, ctx);
+    const expectedCloak = cloakHost(
+      '203.0.113.5',
+      { enabled: true, secret: 's3cret' },
+      'ExampleNet',
+    );
+    const expectedHostmask = `alice!alice@${expectedCloak}`;
+    expect(effects).toEqual([
+      Effect.send('c1', expectedWelcomeWithHost('alice', expectedHostmask)),
+    ]);
+  });
+
+  it('does not cloak when host is already absent (nothing to cloak)', () => {
+    const state = makeState();
+    state.nick = 'alice';
+    state.user = 'alice';
+    const ctx = makeCtxWithCloaking(state, { enabled: true, secret: 's3cret' });
+    emitWelcomeIfReady(state, ctx);
+    expect(state.host).toBeUndefined();
+  });
+});
+
+/** Builds the welcome block with an explicit cloaked host (used for cloak tests). */
+function expectedWelcomeWithHost(nick: string, hostmask: string): RawLine[] {
+  const sv = 'irc.example.com';
+  const prefix = `:${sv}`;
+  const isupport = generateIsupport(
+    {
+      serverName: sv,
+      networkName: 'ExampleNet',
+      maxChannelsPerUser: 30,
+      maxTargetsPerCommand: 10,
+      maxListEntries: 50,
+      nickLen: 30,
+      channelLen: 50,
+      topicLen: 390,
+      quitMessage: 'Client Quit',
+    },
+    new Set<string>(),
+    nick,
+  );
+  return [
+    L(`${prefix} 001 ${nick} :Welcome to the ExampleNet IRC Network, ${hostmask}`),
+    L(`${prefix} 002 ${nick} :Your host is ${sv}, running version 0.2.0`),
+    L(`${prefix} 003 ${nick} :This server was created in Phase 1`),
+    L(`${prefix} 004 ${nick} ${sv} 0.2.0 iosw biklmnstp`),
+    ...isupport,
+    L(`${prefix} 422 ${nick} :MOTD File is missing`),
+  ];
+}