serverless-ircd 0.7.0 → 0.9.0

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

@@ -0,0 +1,1006 @@
+import { describe, expect, it } from 'vitest';
+import { emitChghost } from '../../src/commands/chghost';
+import { HOSTSERV_NICK, hostservReducer } from '../../src/commands/hostserv';
+import type { Effect as EffectType } from '../../src/effects';
+import type { ServicesStore } from '../../src/ports';
+import {
+  EmptyMotdProvider,
+  FakeClock,
+  InMemoryServicesStore,
+  SequentialIdFactory,
+} from '../../src/ports';
+import type { IrcMessage } from '../../src/protocol/messages';
+import { type ConnectionState, createConnection } from '../../src/state/connection';
+import { type Ctx, type ServerConfig, buildCtx } from '../../src/types';
+
+const NOW = 1_700_000_000_000;
+
+const serverConfig: ServerConfig = {
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  maxChannelsPerUser: 30,
+  maxTargetsPerCommand: 10,
+  maxListEntries: 50,
+  nickLen: 30,
+  channelLen: 50,
+  topicLen: 390,
+  quitMessage: 'Client Quit',
+};
+
+/** ServerConfig with the HostServ oper-approval queue enabled. */
+const queueServerConfig: ServerConfig = {
+  ...serverConfig,
+  hostservAutoApproveVhosts: false,
+};
+
+/** ServerConfig with HostServ auto-approve explicitly on. */
+const autoApproveServerConfig: ServerConfig = {
+  ...serverConfig,
+  hostservAutoApproveVhosts: true,
+};
+
+function makeConn(id = 'c1', nick = 'alice'): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  s.nick = nick;
+  s.user = nick;
+  s.host = 'real.cloak.example.net';
+  s.realname = nick;
+  s.registration = 'registered';
+  return s;
+}
+
+function makeCtx(
+  state: ConnectionState,
+  services?: ServicesStore,
+  clock = new FakeClock(NOW),
+  cfg: ServerConfig = serverConfig,
+): Ctx {
+  return buildCtx({
+    serverConfig: cfg,
+    clock,
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+    connection: state,
+    ...(services !== undefined ? { services } : {}),
+  });
+}
+
+function privmsg(body: string): IrcMessage {
+  return { command: 'PRIVMSG', params: [HOSTSERV_NICK, body], tags: {} };
+}
+
+/** Extracts the text of every Send line emitted by the reducer. */
+function sentTexts(effects: EffectType[]): string[] {
+  return effects.flatMap((e) => (e.tag === 'Send' ? e.lines.map((l) => l.text) : []));
+}
+
+/** Builds an identified connection for the given account. */
+function identifiedConn(account: string, id = 'c1', nick = account): ConnectionState {
+  const conn = makeConn(id, nick);
+  conn.account = account;
+  conn.userModes.registered = true;
+  return conn;
+}
+
+/** Builds an oper + identified connection. */
+function operConn(account: string, id = 'c1', nick = account): ConnectionState {
+  const conn = identifiedConn(account, id, nick);
+  conn.userModes.oper = true;
+  return conn;
+}
+
+describe('hostservReducer — dispatch', () => {
+  it('exports the canonical HostServ pseudo-client nick', () => {
+    expect(HOSTSERV_NICK).toBe('HostServ');
+  });
+
+  it('returns a help NOTICE when no body is supplied', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = makeConn();
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(
+      conn,
+      { command: 'PRIVMSG', params: [HOSTSERV_NICK], tags: {} },
+      ctx,
+    );
+
+    expect(sentTexts(out.effects).some((t) => t.includes('Available commands'))).toBe(true);
+  });
+
+  it('returns a help NOTICE when the body is only whitespace', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = makeConn();
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('   '), ctx);
+
+    expect(sentTexts(out.effects).some((t) => t.includes('Available commands'))).toBe(true);
+  });
+
+  it('returns a NOTICE when no services store is bound', () => {
+    const conn = makeConn();
+    const ctx = makeCtx(conn);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Services are not available on this server.',
+    );
+  });
+
+  it('emits an unknown-command NOTICE for an unrecognised subcommand', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = makeConn();
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('FROBNICATE'), ctx);
+
+    expect(sentTexts(out.effects).some((t) => t.includes('Unknown command'))).toBe(true);
+  });
+
+  it('hides oper-only commands from a non-oper on empty body', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('bob');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg(''), ctx);
+
+    const lines = sentTexts(out.effects);
+    expect(lines).toContain(
+      ':HostServ!HostServ@services NOTICE bob :Available commands: ON, OFF, REQUEST',
+    );
+    const helpLine = lines.find((t) => t.includes('Available commands'));
+    for (const cmd of ['SET', 'APPROVE', 'REJECT', 'LIST']) {
+      expect(helpLine).not.toContain(cmd);
+    }
+  });
+
+  it('lists the full command set to an oper on empty body', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg(''), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Available commands: ON, OFF, REQUEST, SET, APPROVE, REJECT, LIST',
+    );
+  });
+
+  it('hides oper-only commands from a non-oper on an unknown subcommand', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('bob');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('FOOBAR'), ctx);
+
+    const lines = sentTexts(out.effects);
+    expect(lines).toContain(
+      ':HostServ!HostServ@services NOTICE bob :Unknown command. Available: ON, OFF, REQUEST',
+    );
+    const unknownLine = lines.find((t) => t.includes('Unknown command'));
+    for (const cmd of ['SET', 'APPROVE', 'REJECT', 'LIST']) {
+      expect(unknownLine).not.toContain(cmd);
+    }
+  });
+
+  it('lists the full command set to an oper on an unknown subcommand', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('FOOBAR'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Unknown command. Available: ON, OFF, REQUEST, SET, APPROVE, REJECT, LIST',
+    );
+  });
+
+  it('still rejects a non-oper who guesses an oper-only command (LIST)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('bob');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('LIST'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE bob :You must be an oper to use LIST.',
+    );
+  });
+
+  it('updates lastSeen to ctx.clock.now()', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW + 500));
+
+    hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(conn.lastSeen).toBe(NOW + 500);
+  });
+});
+
+// ============================================================================
+// ON
+// ============================================================================
+
+describe('hostservReducer — ON', () => {
+  it('rejects ON when the connection is not identified', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = makeConn();
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :You must identify before enabling a vhost.',
+    );
+    expect(conn.host).toBe('real.cloak.example.net');
+    expect(conn.vhostActive).toBeFalsy();
+  });
+
+  it('rejects ON when no vhost is recorded for the account', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :No vhost is assigned to your account.',
+    );
+    expect(conn.host).toBe('real.cloak.example.net');
+    expect(conn.vhostActive).toBeFalsy();
+  });
+
+  it('applies the vhost and emits CHGHOST to peers on ON', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('alice');
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(conn.host).toBe('cool.example.net');
+    expect(conn.vhostActive).toBe(true);
+    expect(conn.preVhostHost).toBe('real.cloak.example.net');
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Your vhost is now active.',
+    );
+    const broadcasts = out.effects.filter((e) => e.tag === 'Broadcast');
+    expect(broadcasts.length).toBe(1);
+  });
+
+  it('is a no-op NOTICE when the vhost is already active', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('alice');
+    conn.vhostActive = true;
+    conn.preVhostHost = 'real.cloak.example.net';
+    conn.host = 'cool.example.net';
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Your vhost is already active.',
+    );
+    expect(conn.host).toBe('cool.example.net');
+  });
+});
+
+// ============================================================================
+// OFF
+// ============================================================================
+
+describe('hostservReducer — OFF', () => {
+  it('rejects OFF when the connection is not identified', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = makeConn();
+    conn.vhostActive = true;
+    conn.preVhostHost = 'real.cloak.example.net';
+    conn.host = 'cool.example.net';
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('OFF'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :You must identify before changing your vhost.',
+    );
+    expect(conn.host).toBe('cool.example.net');
+  });
+
+  it('restores the real host and emits CHGHOST on OFF', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('alice');
+    conn.joinedChannels.add('#foo');
+    conn.vhostActive = true;
+    conn.preVhostHost = 'real.cloak.example.net';
+    conn.host = 'cool.example.net';
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('OFF'), ctx);
+
+    expect(conn.host).toBe('real.cloak.example.net');
+    expect(conn.vhostActive).toBe(false);
+    expect(conn.preVhostHost).toBeUndefined();
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Your vhost has been disabled.',
+    );
+    const broadcasts = out.effects.filter((e) => e.tag === 'Broadcast');
+    expect(broadcasts.length).toBe(1);
+  });
+
+  it('is a no-op NOTICE when no vhost is active', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    conn.host = 'real.cloak.example.net';
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('OFF'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :No vhost is currently active.',
+    );
+    expect(conn.host).toBe('real.cloak.example.net');
+  });
+});
+
+// ============================================================================
+// REQUEST
+// ============================================================================
+
+describe('hostservReducer — REQUEST', () => {
+  it('rejects REQUEST when the connection is not identified', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = makeConn();
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :You must identify before requesting a vhost.',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects REQUEST with no vhost argument', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REQUEST'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Syntax: REQUEST <vhost>',
+    );
+  });
+
+  it('rejects REQUEST with an invalid vhost (bad char)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REQUEST bad!host'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Invalid vhost: bad!host',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects REQUEST with an invalid vhost (single label only)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REQUEST localhost'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Invalid vhost: localhost',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('records the requested vhost against the account (auto-approve)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), autoApproveServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    expect(services.getVhost('alice')).toBe('cool.example.net');
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Vhost cool.example.net has been requested and approved.',
+    );
+  });
+
+  it('overwrites a previously-stored vhost on a subsequent REQUEST', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'one.example.net');
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), autoApproveServerConfig);
+
+    hostservReducer(conn, privmsg('REQUEST two.example.net'), ctx);
+
+    expect(services.getVhost('alice')).toBe('two.example.net');
+  });
+});
+
+// ============================================================================
+// REQUEST — oper-queue mode (hostservAutoApproveVhosts: false)
+// ============================================================================
+
+describe('hostservReducer — REQUEST (queue mode)', () => {
+  it('queues a pending request and replies pending-approval (no activation)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), queueServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    expect(services.getPendingVhost('alice')).toBe('cool.example.net');
+    expect(services.getVhost('alice')).toBeUndefined();
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Vhost cool.example.net is pending oper approval.',
+    );
+  });
+
+  it('does NOT emit any CHGHOST broadcast when queueing a pending request', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), queueServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    const broadcasts = out.effects.filter((e) => e.tag === 'Broadcast');
+    expect(broadcasts).toEqual([]);
+    expect(conn.host).toBe('real.cloak.example.net');
+    expect(conn.vhostActive).toBeFalsy();
+  });
+
+  it('overwrites a previously pending vhost on a subsequent queue-mode REQUEST', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'one.example.net');
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), queueServerConfig);
+
+    hostservReducer(conn, privmsg('REQUEST two.example.net'), ctx);
+
+    expect(services.getPendingVhost('alice')).toBe('two.example.net');
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects a queue-mode REQUEST when not identified', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = makeConn();
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), queueServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :You must identify before requesting a vhost.',
+    );
+    expect(services.getPendingVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects a queue-mode REQUEST with no vhost argument', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), queueServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Syntax: REQUEST <vhost>',
+    );
+    expect(services.getPendingVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects a queue-mode REQUEST with an invalid vhost', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), queueServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST bad!host'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Invalid vhost: bad!host',
+    );
+    expect(services.getPendingVhost('alice')).toBeUndefined();
+  });
+});
+
+describe('hostservReducer — REQUEST (auto-approve knob explicitly on)', () => {
+  it('auto-approves when hostservAutoApproveVhosts is true (explicit)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), autoApproveServerConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    expect(services.getVhost('alice')).toBe('cool.example.net');
+    expect(services.getPendingVhost('alice')).toBeUndefined();
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Vhost cool.example.net has been requested and approved.',
+    );
+  });
+
+  it('queues when hostservAutoApproveVhosts is undefined (default queue mode)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = identifiedConn('alice');
+    // The base serverConfig literal omits the knob entirely; queue mode is
+    // the default, so undefined must route through the oper queue.
+    const ctx = makeCtx(conn, services, new FakeClock(NOW), serverConfig);
+
+    const out = hostservReducer(conn, privmsg('REQUEST cool.example.net'), ctx);
+
+    expect(services.getVhost('alice')).toBeUndefined();
+    expect(services.getPendingVhost('alice')).toBe('cool.example.net');
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE alice :Vhost cool.example.net is pending oper approval.',
+    );
+  });
+});
+
+// ============================================================================
+// APPROVE / ACTIVATE (oper-only)
+// ============================================================================
+
+describe('hostservReducer — APPROVE (oper)', () => {
+  it('rejects APPROVE when the connection is not an oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('bob');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('APPROVE alice'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE bob :You must be an oper to use APPROVE.',
+    );
+    expect(services.getPendingVhost('alice')).toBe('cool.example.net');
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects APPROVE with no account argument', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('APPROVE'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Syntax: APPROVE <account>',
+    );
+  });
+
+  it('rejects APPROVE when no pending request exists for the account', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('APPROVE alice'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :No pending vhost request for alice.',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('activates the pending vhost and replies to the oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('APPROVE alice'), ctx);
+
+    expect(services.getVhost('alice')).toBe('cool.example.net');
+    expect(services.getPendingVhost('alice')).toBeUndefined();
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Vhost cool.example.net for alice has been approved and activated.',
+    );
+  });
+
+  it('emits a SendToNick NOTICE to the owner when online (best-effort delivery)', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('APPROVE alice'), ctx);
+
+    const sendToNicks = out.effects.filter((e) => e.tag === 'SendToNick');
+    expect(sendToNicks).toHaveLength(1);
+    if (sendToNicks[0]?.tag === 'SendToNick') {
+      expect(sendToNicks[0].nick).toBe('alice');
+      expect(sendToNicks[0].lines[0]?.text).toBe(
+        ':HostServ!HostServ@services NOTICE alice :Your vhost cool.example.net has been approved and activated. /msg HostServ ON to apply it.',
+      );
+    }
+  });
+
+  it('treats ACTIVATE as an alias for APPROVE', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ACTIVATE alice'), ctx);
+
+    expect(services.getVhost('alice')).toBe('cool.example.net');
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Vhost cool.example.net for alice has been approved and activated.',
+    );
+  });
+
+  it('folds the account name case-insensitively', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('Alice', 'cool.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    hostservReducer(conn, privmsg('APPROVE ALICE'), ctx);
+
+    expect(services.getVhost('alice')).toBe('cool.example.net');
+  });
+});
+
+// ============================================================================
+// REJECT (oper-only)
+// ============================================================================
+
+describe('hostservReducer — REJECT (oper)', () => {
+  it('rejects REJECT when the connection is not an oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('bob');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REJECT alice'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE bob :You must be an oper to use REJECT.',
+    );
+    expect(services.getPendingVhost('alice')).toBe('cool.example.net');
+  });
+
+  it('rejects REJECT with no account argument', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REJECT'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Syntax: REJECT <account>',
+    );
+  });
+
+  it('rejects REJECT when no pending request exists for the account', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REJECT alice'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :No pending vhost request for alice.',
+    );
+  });
+
+  it('drops the pending request and replies to the oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REJECT alice'), ctx);
+
+    expect(services.getPendingVhost('alice')).toBeUndefined();
+    expect(services.getVhost('alice')).toBeUndefined();
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Vhost request for alice has been rejected.',
+    );
+  });
+
+  it('emits a SendToNick NOTICE to the owner when online', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('REJECT alice'), ctx);
+
+    const sendToNicks = out.effects.filter((e) => e.tag === 'SendToNick');
+    expect(sendToNicks).toHaveLength(1);
+    if (sendToNicks[0]?.tag === 'SendToNick') {
+      expect(sendToNicks[0].nick).toBe('alice');
+      expect(sendToNicks[0].lines[0]?.text).toBe(
+        ':HostServ!HostServ@services NOTICE alice :Your vhost request for cool.example.net has been rejected.',
+      );
+    }
+  });
+});
+
+// ============================================================================
+// LIST (oper-only)
+// ============================================================================
+
+describe('hostservReducer — LIST (oper)', () => {
+  it('rejects LIST when the connection is not an oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('bob');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('LIST'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE bob :You must be an oper to use LIST.',
+    );
+  });
+
+  it('replies with an empty-queue NOTICE when no requests are pending', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('LIST'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :No pending vhost requests.',
+    );
+  });
+
+  it('enumerates each pending request as a NOTICE line', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.requestVhost('alice', 'a.example.net');
+    services.requestVhost('bob', 'b.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('LIST'), ctx);
+
+    const lines = sentTexts(out.effects);
+    expect(lines).toContain(':HostServ!HostServ@services NOTICE admin :alice: a.example.net');
+    expect(lines).toContain(':HostServ!HostServ@services NOTICE admin :bob: b.example.net');
+  });
+});
+
+// ============================================================================
+// SET (oper-only)
+// ============================================================================
+
+describe('hostservReducer — SET (oper)', () => {
+  it('rejects SET when the connection is not an oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.registerNick('alice', 'hunter2', 'alice@example.com');
+    const conn = identifiedConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('SET alice cool.example.net'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :You must be an oper to use SET.',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('rejects SET with missing arguments', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('SET'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Syntax: SET <account> <vhost>',
+    );
+  });
+
+  it('rejects SET with only an account', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('SET alice'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Syntax: SET <account> <vhost>',
+    );
+  });
+
+  it('rejects SET when the target account is not registered', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('SET alice cool.example.net'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Nick alice is not registered.',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+
+  it('sets the vhost directly when invoked by an oper', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.registerNick('alice', 'hunter2', 'alice@example.com');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('SET alice cool.example.net'), ctx);
+
+    expect(services.getVhost('alice')).toBe('cool.example.net');
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Vhost for alice is now set to cool.example.net.',
+    );
+  });
+
+  it('clears the vhost when the oper sets an empty vhost', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.registerNick('alice', 'hunter2', 'alice@example.com');
+    services.setVhost('alice', 'old.example.net');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(
+      conn,
+      { command: 'PRIVMSG', params: [HOSTSERV_NICK, 'SET alice *'], tags: {} },
+      ctx,
+    );
+
+    expect(services.getVhost('alice')).toBeUndefined();
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Vhost for alice has been cleared.',
+    );
+  });
+
+  it('rejects SET with an invalid vhost', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.registerNick('alice', 'hunter2', 'alice@example.com');
+    const conn = operConn('admin');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('SET alice bad!host'), ctx);
+
+    expect(sentTexts(out.effects)).toContain(
+      ':HostServ!HostServ@services NOTICE admin :Invalid vhost: bad!host',
+    );
+    expect(services.getVhost('alice')).toBeUndefined();
+  });
+});
+
+// ============================================================================
+// Integration: CHGHOST emission shape
+// ============================================================================
+
+describe('hostservReducer — CHGHOST emission shape', () => {
+  it('ON produces CHGHOST broadcasts that match emitChghost output', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('alice');
+    conn.user = 'aliceuser';
+    conn.host = 'real.cloak.example.net';
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    // The CHGHOST should be the same shape emitChghost would produce.
+    const expected = emitChghost({
+      conn,
+      oldUser: 'aliceuser',
+      oldHost: 'real.cloak.example.net',
+      newUser: 'aliceuser',
+      newHost: 'cool.example.net',
+    });
+    const broadcasts = out.effects.filter((e) => e.tag === 'Broadcast');
+    const expectedBroadcasts = expected.filter((e) => e.tag === 'Broadcast');
+    expect(broadcasts.length).toBe(expectedBroadcasts.length);
+    if (broadcasts.length > 0 && broadcasts[0]?.tag === 'Broadcast') {
+      const first = broadcasts[0];
+      expect(first.cap).toBe('chghost');
+      expect(first.capLines?.[0]?.text).toBe(
+        ':alice!aliceuser@real.cloak.example.net CHGHOST aliceuser :cool.example.net',
+      );
+    }
+  });
+
+  it('OFF produces CHGHOST broadcasting back to the real host', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('alice');
+    conn.user = 'aliceuser';
+    conn.host = 'cool.example.net';
+    conn.preVhostHost = 'real.cloak.example.net';
+    conn.vhostActive = true;
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('OFF'), ctx);
+
+    const broadcasts = out.effects.filter((e) => e.tag === 'Broadcast');
+    expect(broadcasts.length).toBe(1);
+    if (broadcasts[0]?.tag === 'Broadcast') {
+      expect(broadcasts[0].capLines?.[0]?.text).toBe(
+        ':alice!aliceuser@cool.example.net CHGHOST aliceuser :real.cloak.example.net',
+      );
+    }
+  });
+
+  it('ON does not emit CHGHOST when the connection has no joined channels', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = identifiedConn('alice');
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    const broadcasts = out.effects.filter((e) => e.tag === 'Broadcast');
+    expect(broadcasts).toEqual([]);
+    // The vhost is still applied to state.host
+    expect(conn.host).toBe('cool.example.net');
+    expect(conn.vhostActive).toBe(true);
+  });
+});
+
+// ============================================================================
+// Defensive fallbacks
+// ============================================================================
+
+describe('hostservReducer — defensive fallbacks', () => {
+  it('addresses the NOTICE to * when the connection has no nick', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.registration = 'registered';
+    const ctx = makeCtx(conn, services);
+
+    const out = hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(sentTexts(out.effects)[0]).toBe(
+      ':HostServ!HostServ@services NOTICE * :You must identify before enabling a vhost.',
+    );
+  });
+
+  it('ON applies the vhost even when the connection has no user/host', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    services.setVhost('alice', 'cool.example.net');
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.nick = 'alice';
+    conn.account = 'alice';
+    conn.userModes.registered = true;
+    conn.registration = 'registered';
+    conn.joinedChannels.add('#foo');
+    const ctx = makeCtx(conn, services);
+
+    hostservReducer(conn, privmsg('ON'), ctx);
+
+    expect(conn.host).toBe('cool.example.net');
+    expect(conn.vhostActive).toBe(true);
+    expect(conn.preVhostHost).toBe('');
+  });
+
+  it('OFF clears the vhost even when user/host/preVhostHost are all absent', () => {
+    const services = new InMemoryServicesStore({ clock: new FakeClock(NOW) });
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.nick = 'alice';
+    conn.account = 'alice';
+    conn.userModes.registered = true;
+    conn.registration = 'registered';
+    conn.vhostActive = true;
+    const ctx = makeCtx(conn, services);
+
+    hostservReducer(conn, privmsg('OFF'), ctx);
+
+    expect(conn.host).toBe('');
+    expect(conn.vhostActive).toBe(false);
+  });
+});