serverless-ircd 0.8.0 → 0.9.0

package/packages/aws-adapter/tests/sweeper.test.ts

@@ -18,6 +18,7 @@ import { type ChanName, type Nick, createConnection } from '@serverless-ircd/irc
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { cleanupConnection } from '../src/aws-runtime.js';
 import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { CONNECTION_COUNT_META_ID } from '../src/connection-counter.js';
 import { createDynamoDocumentClient } from '../src/dynamo.js';
 import { type SweepParams, type SweepResult, handleSweep } from '../src/handlers/sweeper.js';
 import { marshalChannelMember, marshalConnection, marshalNick } from '../src/serialize.js';
@@ -424,4 +425,23 @@ describe('gone-connection sweeper — scan edge cases', () => {
     expect(result.scanned).toBe(1);
     expect(result.swept).toBe(0);
   });
+
+  it('skips the admission-counter meta row (never swept, never counted)', async () => {
+    // The atomic admission counter lives in the Connections table under a
+    // sentinel id. The sweeper must not treat it as a stale connection —
+    // it carries no idleSince and must never be torn down by the sweeper.
+    const client = new FakeScanDynamo([
+      {
+        items: [
+          { connectionId: CONNECTION_COUNT_META_ID, count: 7 },
+          { connectionId: 'real', idleSince: 0 },
+        ],
+      },
+    ]);
+    const result = await handleSweep(fakeSweepParams(client));
+    // The meta row is excluded from both `scanned` and `swept`; only the
+    // genuine stale connection is counted.
+    expect(result.scanned).toBe(1);
+    expect(result.swept).toBe(1);
+  });
 });

package/packages/cf-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-adapter",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Cloudflare Workers adapter: Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and CfRuntime implementing IrcRuntime",
   "license": "BSD-3-Clause",

package/packages/cf-adapter/src/connection-do.ts

@@ -827,7 +827,7 @@ const DEFAULT_MOTD: string[] = ['Welcome to the ServerlessIRCd Cloudflare adapte
  * synchronous reducers can mutate `members` (a Map) and `banMasks` /
  * `pendingInvites` (Sets) in place.
  */
-class PassthroughChannelAccess {
+export class PassthroughChannelAccess {
   private readonly cache = new Map<string, ChannelState>();
   constructor(
     private readonly now: number,
@@ -879,11 +879,23 @@ class PassthroughChannelAccess {
       createdAt: number;
     } | null;
     if (dto === null) return;
-    // Don't replace the cache with an empty snapshot — the channel
-    // effectively doesn't exist yet, and the local reducer should lazily
-    // seed it via getOrCreateChannel. This also avoids clobbering the
-    // local cache with ChannelDO's "name unknown" default state.
-    if (dto.members.length === 0) return;
+    // When the authoritative ChannelDO reports zero members (the
+    // post-deploy state), don't replace the cache with an empty roster —
+    // the local reducer should lazily seed memberships via
+    // getOrCreateChannel. But DO propagate the persisted topic / modes /
+    // ban list onto an existing cache entry so the JOIN reducer sees the
+    // survived topic and emits 332/333. Mirrors the AWS adapter's
+    // LambdaChannelAccess.refreshChannel empty-members branch.
+    if (dto.members.length === 0) {
+      const existing = this.cache.get(key);
+      if (existing !== undefined) {
+        existing.modes = { ...dto.modes };
+        existing.banMasks = new Set(dto.banMasks);
+        existing.pendingInvites = new Set(dto.pendingInvites);
+        if (dto.topic !== undefined) existing.topic = dto.topic;
+      }
+      return;
+    }
     const members = new Map<ConnId, { conn: ConnId; nick: string; op: boolean; voice: boolean }>();
     for (const entry of dto.members) {
       members.set(entry.conn, {

package/packages/cf-adapter/tests/connection-do-pure.test.ts

@@ -89,3 +89,133 @@ describe('wsFrameModeFromTags', () => {
     expect(wsFrameModeFromTags(['ws:spec-text', 'ws:legacy'])).toBe('spec-text');
   });
 });
+
+// ============================================================================
+// PassthroughChannelAccess.refreshChannel
+// ============================================================================
+//
+// refreshChannel pulls the authoritative snapshot from the ChannelDO and
+// rebuilds (or updates) the local cache entry. The zero-members branch is
+// the post-deploy state: the ChannelDO persisted a topic across the
+// deploy but its roster is empty, so the local cache must still absorb
+// the topic/modes/banMasks or the JOIN reducer runs against a topic-less
+// state and never emits 332/333.
+// ============================================================================
+
+import { PassthroughChannelAccess } from '../src/connection-do';
+import type { Env } from '../src/env';
+
+const EMPTY_MODES = {
+  inviteOnly: false,
+  topicLock: false,
+  noExternal: false,
+  moderated: false,
+  secret: false,
+  private: false,
+  registered: false,
+  blockUnidentified: false,
+  moderatedIdent: false,
+};
+
+/** Builds a fake Env whose CHANNEL_DO returns `snapshot` from getChannelSnapshot. */
+function makeEnvWithSnapshot(snapshot: unknown): Env {
+  const fakeChannelDo = {
+    idFromName: (key: string) => `id-${key}`,
+    get: () => ({ getChannelSnapshot: async () => snapshot }),
+  };
+  return { CHANNEL_DO: fakeChannelDo } as unknown as Env;
+}
+
+describe('PassthroughChannelAccess.refreshChannel', () => {
+  it('propagates topic/modes/banMasks onto the cached entry when the snapshot reports zero members', async () => {
+    const snap = {
+      modes: { ...EMPTY_MODES, topicLock: true },
+      banMasks: ['bad!*@*'],
+      topic: { text: 'survived deploy', setter: 'alice!alice@example.com', setAt: 1234 },
+      members: [],
+      pendingInvites: [],
+      createdAt: 0,
+    };
+    const env = makeEnvWithSnapshot(snap);
+    const access = new PassthroughChannelAccess(0, env);
+    const chan = access.getOrCreateChannel('#foo');
+    expect(chan.topic).toBeUndefined();
+
+    await access.refreshChannel('#foo');
+
+    expect(chan.topic?.text).toBe('survived deploy');
+    expect(chan.topic?.setter).toBe('alice!alice@example.com');
+    expect(chan.topic?.setAt).toBe(1234);
+    expect(chan.modes.topicLock).toBe(true);
+    expect(chan.banMasks.has('bad!*@*')).toBe(true);
+  });
+
+  it('leaves the cached topic unset when a zero-members snapshot carries no topic', async () => {
+    const snap = {
+      modes: { ...EMPTY_MODES },
+      banMasks: [],
+      members: [],
+      pendingInvites: [],
+      createdAt: 0,
+    };
+    const env = makeEnvWithSnapshot(snap);
+    const access = new PassthroughChannelAccess(0, env);
+    const chan = access.getOrCreateChannel('#foo');
+
+    await access.refreshChannel('#foo');
+
+    expect(chan.topic).toBeUndefined();
+  });
+
+  it('does not seed a cache entry when the snapshot reports zero members and none exists', async () => {
+    const snap = {
+      modes: { ...EMPTY_MODES },
+      banMasks: [],
+      topic: { text: 'x', setter: 's', setAt: 0 },
+      members: [],
+      pendingInvites: [],
+      createdAt: 0,
+    };
+    const env = makeEnvWithSnapshot(snap);
+    const access = new PassthroughChannelAccess(0, env);
+
+    await access.refreshChannel('#never');
+
+    // No cache entry was created: getOrCreateChannel now seeds a fresh one
+    // with no topic (the zero-members refresh must not seed a new entry).
+    const chan = access.getOrCreateChannel('#never');
+    expect(chan.topic).toBeUndefined();
+  });
+
+  it('rebuilds the cached entry from a snapshot with members', async () => {
+    const snap = {
+      modes: { ...EMPTY_MODES, secret: true },
+      banMasks: [],
+      topic: { text: 'hi', setter: 's', setAt: 9 },
+      members: [{ conn: 'c0', nick: 'alice', op: true, voice: false }],
+      pendingInvites: [],
+      createdAt: 7,
+    };
+    const env = makeEnvWithSnapshot(snap);
+    const access = new PassthroughChannelAccess(0, env);
+
+    await access.refreshChannel('#foo');
+
+    const chan = access.getOrCreateChannel('#foo');
+    expect(chan.topic?.text).toBe('hi');
+    expect(chan.modes.secret).toBe(true);
+    expect(chan.members.size).toBe(1);
+    expect(chan.members.get('c0')?.nick).toBe('alice');
+  });
+
+  it('is a no-op when the ChannelDO snapshot is null', async () => {
+    const env = makeEnvWithSnapshot(null);
+    const access = new PassthroughChannelAccess(0, env);
+    const chan = access.getOrCreateChannel('#foo');
+    chan.topic = { text: 'keep', setter: 's', setAt: 1 };
+
+    await access.refreshChannel('#foo');
+
+    expect(chan.topic?.text).toBe('keep');
+  });
+});

package/packages/in-memory-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/in-memory-runtime",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Single-process reference implementation of the IrcRuntime port, backed by Maps",
   "license": "BSD-3-Clause",

package/packages/irc-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Platform-agnostic IRC protocol core: parser, serializer, command reducers, state shapes",
   "license": "BSD-3-Clause",

package/packages/irc-core/src/commands/account-auth.ts

@@ -25,6 +25,7 @@ import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
 import type { Ctx } from '../types.js';
 import { emitAccountNotify } from './account-notify.js';
+import { applyAssignedVhost } from './hostserv.js';
 import { deliverUnreadMemos } from './memoserv.js';
 import { nowAwayLine, replayPersistedAway } from './pre-away.js';
 import { seedReadMarkers } from './read-marker.js';
@@ -35,11 +36,14 @@ import { seedReadMarkers } from './read-marker.js';
  *
  * Mutates `state`: sets `state.account`, stamps read-only user mode `r`
  * (`userModes.registered = true`), seeds `lastReadMarkers` from the bound
- * services store, replays the persisted away reason, and returns the
- * effects the caller must emit:
+ * services store, replays the persisted away reason, re-applies any assigned
+ * HostServ vhost (so a reconnecting user does not have to re-run
+ * `HostServ ON`), and returns the effects the caller must emit:
  *   - `Send` carrying `900 RPL_LOGGEDIN` + `903 RPL_SASLSUCCESS`;
  *   - an optional `306 RPL_NOWAWAY` when an away reason was replayed;
  *   - any queued MemoServ `NOTICE`s delivered from the services store;
+ *   - an optional `CHGHOST` fanout when a vhost was applied post-JOIN (empty
+ *     at SASL / PASS-auth time — no channels joined yet);
  *   - the `account-notify` `ACCOUNT` broadcasts to cap-enabled peers in
  *     shared channels (empty at identify time — no channels joined yet).
  *
@@ -54,11 +58,17 @@ export function applyAccountSuccess(
   // A successful account login is equivalent to NickServ IDENTIFY: stamp
   // read-only user mode `r` so `221`/WHOIS reflect the identified state.
   state.userModes.registered = true;
-  // IRCv3 draft/read-marker: restore the user's per-channel last-read
-  // markers from the persisted store so a reconnect resumes at their last
-  // read position. No-op when no services store is bound.
+  // HostServ vhost: re-apply any assigned vhost so a reconnecting user with
+  // a vhost does not have to re-run `HostServ ON` every session. Collected
+  // into a local array because the CHGHOST fanout is only non-empty when the
+  // connection has joined channels (never at SASL/PASS-auth time).
+  const vhostEffects: EffectType[] = [];
   if (ctx.services !== undefined) {
+    // IRCv3 draft/read-marker: restore the user's per-channel last-read
+    // markers from the persisted store so a reconnect resumes at their last
+    // read position. No-op when no services store is bound.
     seedReadMarkers(state, ctx.services, account);
+    applyAssignedVhost(state, ctx.services, account, vhostEffects);
   }
   // IRCv3 draft/pre-away: replay the user's persisted away reason onto the
   // fresh connection and emit 306 so the user sees they are still away.
@@ -78,6 +88,7 @@ export function applyAccountSuccess(
     Effect.send(ctx.connId, [loggedInLine(ctx, account), saslSuccessLine(ctx)]),
     ...awayEffects,
     ...memoEffects,
+    ...vhostEffects,
     ...emitAccountNotify({ conn: state, account }),
   ];
 }
@@ -101,18 +112,31 @@ export function parsePassAccountAttempt(
 /**
  * Attempts PASS-based account authentication at registration completion.
  *
- * Recognises the `<nick>:<password>` form in `state.passAttempt`, verifies
- * it against the bound {@link AccountStore} (PLAIN), and on success runs
- * the shared {@link applyAccountSuccess} chain. Returns the success
- * effects, or `[]` for every other outcome:
+ * Thin wrapper around {@link attemptPassAccountAuth} that reads the stashed
+ * `state.passAttempt`. See {@link attemptPassAccountAuth} for the full
+ * outcome matrix.
+ */
+export function passBasedAccountAuth(state: ConnectionState, ctx: Ctx): EffectType[] {
+  return attemptPassAccountAuth(state, ctx, state.passAttempt);
+}
+
+/**
+ * Shared verify + {@link applyAccountSuccess} pipeline for a raw
+ * `<nick>:<password>` attempt string.
+ *
+ * Used by both {@link passBasedAccountAuth} (at registration completion,
+ * reading `state.passAttempt`) and the post-registration late-PASS login
+ * in `passReducer` (reading the `PASS` param directly), so the two entry
+ * points share one verify+success path and never diverge.
+ *
+ * Returns the account-login success effects (`900`/`903`/`+r`/read-marker
+ * seeding/away replay/memo delivery/`account-notify`), or `[]` for every
+ * other outcome:
  *   - already identified (`state.account` set, e.g. via SASL) → no-op;
- *   - no `<nick>:<password>` form (bare value) → left to the server-password
- *     gate;
- *   - payload nick does not match `state.nick` (when set) → not a coherent
- *     account attempt, treated as failed auth;
- *   - no {@link AccountStore} bound → the `<nick>:<password>` form is
- *     ignored (collapses to the server-password gate);
- *   - verify failure (unknown nick or wrong password) → no account effects.
+ *   - no `<nick>:<password>` form (bare value or undefined) → no-op;
+ *   - payload nick does not match `state.nick` (when set) → no-op;
+ *   - no {@link AccountStore} bound → no-op;
+ *   - verify failure (unknown nick or wrong password) → no-op.
  *
  * A failed verify is followed by a verify against a fixed dummy entry so
  * the failure path performs the same AccountStore work whether the payload
@@ -120,9 +144,13 @@ export function parsePassAccountAttempt(
  * (no numerics, no disconnect, no state change) is identical for both
  * cases, giving no information to a remote attacker.
  */
-export function passBasedAccountAuth(state: ConnectionState, ctx: Ctx): EffectType[] {
+export function attemptPassAccountAuth(
+  state: ConnectionState,
+  ctx: Ctx,
+  attempt: string | undefined,
+): EffectType[] {
   if (state.account !== undefined) return [];
-  const parsed = parsePassAccountAttempt(state.passAttempt);
+  const parsed = parsePassAccountAttempt(attempt);
   if (parsed === null) return [];
   if (state.nick !== undefined && state.nick !== parsed.nick) return [];
   const store = ctx.accounts;

package/packages/irc-core/src/commands/chanserv.ts

@@ -47,8 +47,8 @@ import { caseFold } from '../case-fold.js';
 import { Effect } from '../effects.js';
 import type { Effect as EffectType, RawLine } from '../effects.js';
 import type { ChannelLevelOp, ServicesStore } from '../ports.js';
-import type { ChannelDelta } from '../state/channel.js';
-import type { ConnectionState } from '../state/connection.js';
+import type { ChannelDelta, Roster } from '../state/channel.js';
+import type { ConnId, ConnectionState } from '../state/connection.js';
 import type { Ctx, Reducer } from '../types.js';
 
 /** Canonical ChanServ pseudo-client nick. */
@@ -151,6 +151,32 @@ export const chanservReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
       return handleAccess(state, args, ctx, effects);
     case 'LEVELS':
       return handleLevels(state, args, ctx, effects);
+    case 'OP':
+      return handlePrefixCommand(state, args, ctx, effects, { verb: 'OP', field: 'op', set: true });
+    case 'DEOP':
+      return handlePrefixCommand(state, args, ctx, effects, {
+        verb: 'DEOP',
+        field: 'op',
+        set: false,
+      });
+    case 'VOICE':
+      return handlePrefixCommand(state, args, ctx, effects, {
+        verb: 'VOICE',
+        field: 'voice',
+        set: true,
+      });
+    case 'DEVOICE':
+      return handlePrefixCommand(state, args, ctx, effects, {
+        verb: 'DEVOICE',
+        field: 'voice',
+        set: false,
+      });
+    case 'KICK':
+      return handleKick(state, args, ctx, effects);
+    case 'BAN':
+      return handleBanMask(state, args, ctx, effects, { verb: 'BAN', add: true });
+    case 'UNBAN':
+      return handleBanMask(state, args, ctx, effects, { verb: 'UNBAN', add: false });
     default:
       if (sub !== undefined && SHORTHAND_VERBS.has(sub)) {
         return handleShorthand(state, sub, args, ctx, effects);
@@ -736,6 +762,264 @@ function isKnownLevelOp(op: string): op is ChannelLevelOp {
   return LEVEL_OPS.includes(op as ChannelLevelOp);
 }
 
+// ============================================================================
+// OP / DEOP / VOICE / DEVOICE / KICK / BAN / UNBAN
+// ============================================================================
+//
+// These six commands emit `ApplyChannelDelta` effects the actor layer applies
+// to the authoritative `ChannelState`. They operate on `ConnectionState`
+// (the ChanServ reducer's authority), so they cannot read or mutate the
+// roster directly — prefix/kick deltas carry a `targetNick` hint the actor
+// resolves against the channel roster at apply time. See
+// `resolveMembershipTarget` below and the {@link MembershipDelta.targetNick}
+// docstring in `state/channel.ts` for the resolution + patch contract.
+
+/** Roster field touched by a prefix command. */
+type PrefixField = 'op' | 'voice';
+
+interface PrefixCommandOpts {
+  verb: 'OP' | 'DEOP' | 'VOICE' | 'DEVOICE';
+  field: PrefixField;
+  set: boolean;
+}
+
+/**
+ * Authorisation gate for the prefix / kick / ban commands. Returns the bound
+ * {@link ServicesStore} on success; pushes the matching notice into `effects`
+ * and returns `null` on failure.
+ *
+ *   - Unidentified caller      → "You must identify …"
+ *   - Unregistered channel     → "Channel <chan> is not registered."
+ *   - Non-founder caller:
+ *       - `founderOnly: true`  → "Permission denied."
+ *       - `founderOnly: false` → allowed when caller's access level meets the
+ *         founder-configured `AUTOOP` threshold, otherwise "Permission denied."
+ *
+ * Privilege model: OP/DEOP/VOICE/DEVOICE accept the founder OR any
+ * AUTOOP-level access entry; KICK/BAN/UNBAN are founder-only.
+ */
+function requirePrivilegedChanServ(
+  state: ConnectionState,
+  channel: string,
+  ctx: Ctx,
+  effects: EffectType[],
+  opts: { founderOnly: boolean },
+): ServicesStore | null {
+  const services = ctx.services as ServicesStore;
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before changing channel settings.'));
+    return null;
+  }
+  const founder = services.getChannelFounder(channel);
+  if (founder === undefined) {
+    effects.push(notice(state, `Channel ${channel} is not registered.`));
+    return null;
+  }
+  if (caseFold('rfc1459', founder) === caseFold('rfc1459', state.account)) {
+    return services;
+  }
+  if (!opts.founderOnly) {
+    const level = services.getChannelAccess(channel, state.account);
+    const autoOp = services.getChannelLevel(channel, 'AUTOOP') ?? DEFAULT_CHANNEL_LEVELS.AUTOOP;
+    if (level >= autoOp) return services;
+  }
+  effects.push(notice(state, 'Permission denied.'));
+  return null;
+}
+
+/**
+ * Handles `OP|DEOP|VOICE|DEVOICE <#channel> <nick>`.
+ *
+ * Emits a `:ChanServ!ChanServ@services MODE <chan> ±<o|v> <nick>` broadcast
+ * (mirroring the ChanServ prefix grant broadcast in `join.ts`) and an
+ * `ApplyChannelDelta({ memberships: [{ type: 'add', targetNick, op|voice }] })`
+ * carrying a `targetNick` hint. The actor layer resolves the nick against the
+ * channel roster at apply time:
+ *   - resolved → the present `op`/`voice` field is *patched* onto the
+ *     existing entry (so op-ing a voiced user does not clear voice);
+ *   - absent   → the delta is a no-op and ChanServ NOTICEs the caller.
+ *
+ * `conn: ''` is a placeholder overwritten by the actor on resolution; the
+ * {@link MembershipDelta.targetNick} docstring describes the patch contract.
+ */
+function handlePrefixCommand(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+  opts: PrefixCommandOpts,
+): { state: ConnectionState; effects: EffectType[] } {
+  const channel = args[0];
+  const targetNick = args[1];
+  if (
+    channel === undefined ||
+    targetNick === undefined ||
+    !isValidChannelName(channel, ctx.serverConfig.channelLen)
+  ) {
+    effects.push(notice(state, `Syntax: ${opts.verb} <#channel> <nick>.`));
+    return { state, effects };
+  }
+
+  const services = requirePrivilegedChanServ(state, channel, ctx, effects, {
+    founderOnly: false,
+  });
+  if (services === null) return { state, effects };
+
+  const letter = opts.field === 'op' ? 'o' : 'v';
+  const sign = opts.set ? '+' : '-';
+  const membership = {
+    type: 'add' as const,
+    conn: '',
+    nick: targetNick,
+    targetNick,
+    ...(opts.field === 'op' ? { op: opts.set } : { voice: opts.set }),
+  };
+
+  effects.push(Effect.applyChannelDelta(channel, { memberships: [membership] }));
+  effects.push(
+    Effect.broadcast(channel, [
+      { text: `:${CHANSERV_HOSTMASK} MODE ${channel} ${sign}${letter} ${targetNick}` },
+    ]),
+  );
+  effects.push(notice(state, `Set mode ${sign}${letter} on ${targetNick} on ${channel}.`));
+  return { state, effects };
+}
+
+/**
+ * Handles `KICK <#channel> <nick> [:<reason>]`.
+ *
+ * Founder-only. Emits a `:ChanServ!ChanServ@services KICK <chan> <nick>
+ * [:<reason>]` broadcast and an `ApplyChannelDelta({ memberships: [{ type:
+ * 'remove', targetNick }] })`, mirroring `kick.ts:134-150`. The actor layer
+ * resolves `targetNick` against the roster and either removes the matching
+ * entry or no-ops with a NOTICE to the caller when the nick is absent.
+ *
+ * `conn: ''` is a placeholder overwritten by the actor on resolution.
+ */
+function handleKick(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const channel = args[0];
+  const targetNick = args[1];
+  if (
+    channel === undefined ||
+    targetNick === undefined ||
+    !isValidChannelName(channel, ctx.serverConfig.channelLen)
+  ) {
+    effects.push(notice(state, 'Syntax: KICK <#channel> <nick> [:<reason>].'));
+    return { state, effects };
+  }
+
+  const services = requirePrivilegedChanServ(state, channel, ctx, effects, {
+    founderOnly: true,
+  });
+  if (services === null) return { state, effects };
+
+  // Reason is everything after the channel + nick, with an optional leading
+  // `:` (RFC 2812 trailing form). The trailing splitter already removed the
+  // `:` prefix when present in a single token; rebuild from the original
+  // args to preserve spaces.
+  const reason = args.slice(2).join(' ').replace(/^:/u, '');
+
+  const line =
+    reason.length > 0
+      ? { text: `:${CHANSERV_HOSTMASK} KICK ${channel} ${targetNick} :${reason}` }
+      : { text: `:${CHANSERV_HOSTMASK} KICK ${channel} ${targetNick}` };
+
+  effects.push(Effect.broadcast(channel, [line]));
+  effects.push(
+    Effect.applyChannelDelta(channel, {
+      memberships: [{ type: 'remove', conn: '', targetNick }],
+    }),
+  );
+  effects.push(notice(state, `Kicked ${targetNick} from ${channel}.`));
+  return { state, effects };
+}
+
+interface BanCommandOpts {
+  verb: 'BAN' | 'UNBAN';
+  add: boolean;
+}
+
+/**
+ * Handles `BAN <#channel> <mask>` and `UNBAN <#channel> <mask>`.
+ *
+ * Founder-only. Emits an `ApplyChannelDelta({ banMaskChanges: [{ type, mask }] })`
+ * mirroring the ban-mask handling in `mode.ts`, plus a
+ * `:ChanServ!ChanServ@services MODE <chan> ±b <mask>` broadcast so clients
+ * update their ban-list views. The mask persists in `ChannelState.banMasks`
+ * via the actor's delta application.
+ *
+ * Kick-on-ban (Atheme's default) is intentionally NOT performed: ChanServ
+ * cannot enumerate the roster from `ConnectionState`, and a mask-based
+ * kick requires an actor-side enforcement pass. Tracked as a follow-up.
+ */
+function handleBanMask(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+  opts: BanCommandOpts,
+): { state: ConnectionState; effects: EffectType[] } {
+  const channel = args[0];
+  const mask = args[1];
+  if (
+    channel === undefined ||
+    mask === undefined ||
+    !isValidChannelName(channel, ctx.serverConfig.channelLen)
+  ) {
+    effects.push(notice(state, `Syntax: ${opts.verb} <#channel> <mask>.`));
+    return { state, effects };
+  }
+
+  const services = requirePrivilegedChanServ(state, channel, ctx, effects, {
+    founderOnly: true,
+  });
+  if (services === null) return { state, effects };
+
+  const sign = opts.add ? '+' : '-';
+  const changeType = opts.add ? 'add' : 'remove';
+
+  effects.push(
+    Effect.applyChannelDelta(channel, {
+      banMaskChanges: [{ type: changeType, mask }],
+    }),
+  );
+  effects.push(
+    Effect.broadcast(channel, [{ text: `:${CHANSERV_HOSTMASK} MODE ${channel} ${sign}b ${mask}` }]),
+  );
+  const confirmation = opts.add
+    ? `Set ban ${mask} on ${channel}.`
+    : `Removed ban ${mask} from ${channel}.`;
+  effects.push(notice(state, confirmation));
+  return { state, effects };
+}
+
+/**
+ * Resolves a target nick (case-insensitive under `CASEMAPPING=rfc1459`) to the
+ * connection id of the matching roster entry, or `undefined` when the nick is
+ * not on the channel.
+ *
+ * The actor layer calls this when applying an `ApplyChannelDelta` whose
+ * membership carries a {@link MembershipDelta.targetNick} hint (emitted by
+ * ChanServ OP/DEOP/VOICE/DEVOICE/KICK). A return value of `undefined` signals
+ * "target not on channel" → the actor treats the delta as a no-op and emits a
+ * ChanServ NOTICE back to the caller.
+ *
+ * Exposed so the dispatch layer (irc-server) and the ChanServ tests share a
+ * single resolution function, keeping the nick-folding rules in one place.
+ */
+export function resolveMembershipTarget(members: Roster, nick: string): ConnId | undefined {
+  const targetLower = caseFold('rfc1459', nick);
+  for (const entry of members.values()) {
+    if (caseFold('rfc1459', entry.nick) === targetLower) return entry.conn;
+  }
+  return undefined;
+}
+
 /**
  * Capitalises the first character of `value` (display helper). Callers
  * pre-validate that `value` is non-empty (the token splitter drops empty
@@ -759,14 +1043,14 @@ function notice(state: ConnectionState, text: string): EffectType {
 function helpNotice(state: ConnectionState): EffectType {
   return notice(
     state,
-    'Available commands: REGISTER, DROP, INFO, SET, ACCESS, LEVELS, SOP, AOP, HOP, VOP',
+    'Available commands: REGISTER, DROP, INFO, SET, ACCESS, LEVELS, SOP, AOP, HOP, VOP, OP, DEOP, VOICE, DEVOICE, KICK, BAN, UNBAN',
   );
 }
 
 function unknownNotice(state: ConnectionState): EffectType {
   return notice(
     state,
-    'Unknown command. Available: REGISTER, DROP, INFO, SET, ACCESS, LEVELS, SOP, AOP, HOP, VOP',
+    'Unknown command. Available: REGISTER, DROP, INFO, SET, ACCESS, LEVELS, SOP, AOP, HOP, VOP, OP, DEOP, VOICE, DEVOICE, KICK, BAN, UNBAN',
   );
 }