serverless-ircd 0.8.0 → 0.10.0

package/packages/irc-core/src/account-migration.ts

@@ -0,0 +1,140 @@
+/**
+ * Pure helpers for the one-shot `accounts` → `nickserv_accounts` /
+ * `Services` migration (`tools/migrate-accounts-to-services.ts`).
+ *
+ * Lives in `irc-core` so both adapter test suites can import the helpers
+ * without a cross-adapter dependency. The CLI entry point (wrangler /
+ * DynamoDB IO) lives in the tools script; these helpers are side-effect-
+ * free and fully unit-testable.
+ */
+
+import { caseFold } from './case-fold.js';
+import { hashAccountCredential } from './credential-hashing.js';
+
+/**
+ * DDL for the `nickserv_accounts` table (the migration target). Inlined
+ * rather than imported from `@serverless-ircd/cf-adapter` so the helpers
+ * are testable from any package. Kept in sync with
+ * `cf-adapter/src/d1-services-store.ts`.
+ */
+export const MIGRATION_NICKSERV_ACCOUNTS_SQL =
+  "CREATE TABLE IF NOT EXISTS nickserv_accounts (nick_key TEXT PRIMARY KEY, nick TEXT NOT NULL, account TEXT NOT NULL, email TEXT NOT NULL, created_at INTEGER NOT NULL, enforce TEXT NOT NULL, cert_subjects TEXT NOT NULL DEFAULT '[]', algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)";
+
+/** Parsed `SASL_ACCOUNTS` env var entry. */
+export interface ParsedSaslAccount {
+  username: string;
+  password: string;
+}
+
+/** A raw legacy `accounts` row read from D1 or DynamoDB. */
+export interface LegacyAccountRow {
+  account: string;
+  algorithm: string;
+  salt: string;
+  hash: string;
+}
+
+/** Parses the `SASL_ACCOUNTS` env var into credential entries. */
+export function parseSaslAccountsForMigration(raw: string | undefined): ParsedSaslAccount[] {
+  if (raw === undefined || raw.length === 0) return [];
+  const out: ParsedSaslAccount[] = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}
+
+/**
+ * Builds the set of `INSERT OR IGNORE` SQL statements that backfill the
+ * legacy `accounts` rows plus the `SASL_ACCOUNTS` env-seed entries into
+ * `nickserv_accounts`. Pure (no IO).
+ *
+ * - Legacy rows are copied verbatim (the pre-hashed scrypt credential is
+ *   preserved; the plaintext is NOT re-hashed). The services row carries
+ *   `cert_subjects = '[]'`, email `''`, enforce `'none'`, `created_at 0`.
+ * - `SASL_ACCOUNTS` env-seed entries are hashed fresh (the env var carries
+ *   plaintext passwords). Only entries whose username is NOT already
+ *   present in the legacy rows are emitted (legacy rows win over the env
+ *   seed).
+ * - `INSERT OR IGNORE` guarantees idempotency: an existing
+ *   `nickserv_accounts` row (registered via NickServ or a prior seed) is
+ *   never clobbered.
+ *
+ * @returns The array of executable SQL statements (CREATE TABLE + INSERTs).
+ */
+export function buildMigrationSql(
+  legacyRows: ReadonlyArray<LegacyAccountRow>,
+  saslAccountsRaw: string | undefined,
+): string[] {
+  const statements: string[] = [MIGRATION_NICKSERV_ACCOUNTS_SQL];
+
+  const seen = new Set<string>();
+
+  for (const row of legacyRows) {
+    const nickKey = caseFold('rfc1459', row.account);
+    seen.add(nickKey);
+    statements.push(buildInsertOrIgnore(row.account, row));
+  }
+
+  for (const acct of parseSaslAccountsForMigration(saslAccountsRaw)) {
+    const nickKey = caseFold('rfc1459', acct.username);
+    if (seen.has(nickKey)) continue;
+    seen.add(nickKey);
+    const cred = hashAccountCredential(acct.username, acct.password);
+    statements.push(buildInsertOrIgnore(acct.username, cred));
+  }
+
+  return statements;
+}
+
+function buildInsertOrIgnore(
+  username: string,
+  cred: { algorithm: string; salt: string; hash: string },
+): string {
+  const nickKey = caseFold('rfc1459', username);
+  return `INSERT OR IGNORE INTO nickserv_accounts (nick_key, nick, account, email, created_at, enforce, cert_subjects, algorithm, salt, hash) VALUES ('${sqlEscape(nickKey)}', '${sqlEscape(username)}', '${sqlEscape(username)}', '', 0, 'none', '[]', '${sqlEscape(cred.algorithm)}', '${sqlEscape(cred.salt)}', '${sqlEscape(cred.hash)}')`;
+}
+
+/** Doubles single quotes for safe embedding in a D1 SQL string literal. */
+function sqlEscape(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+/**
+ * Builds the DynamoDB `PutItem` input for a legacy row, targeting the
+ * `Services` table's `NICK:<fold>` / `#` item. Pure.
+ *
+ * The caller wraps this in a conditional PutItem
+ * (`ConditionExpression: attribute_not_exists(pk)`) so an existing nick
+ * registration is never clobbered.
+ */
+export function buildServicesPutItem(
+  row: { account: string; algorithm: string; salt: string; hash: string },
+  tableName: string,
+): { TableName: string; Item: Record<string, unknown> } {
+  const fold = caseFold('rfc1459', row.account);
+  return {
+    TableName: tableName,
+    Item: {
+      pk: `NICK:${fold}`,
+      sk: '#',
+      type: 'nick',
+      nick: row.account,
+      account: row.account,
+      email: '',
+      createdAt: 0,
+      enforce: 'none',
+      certSubjects: [],
+      algorithm: row.algorithm,
+      salt: row.salt,
+      hash: row.hash,
+    },
+  };
+}

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

@@ -13,8 +13,10 @@
  *
  * {@link passBasedAccountAuth} is the legacy IRC convention of carrying
  * NickServ credentials in `PASS <nick>:<password>` at registration; it
- * resolves at registration completion via the injected
- * {@link AccountStore} and, on success, delegates to
+ * resolves at registration completion via the bound
+ * {@link ServicesStore} (`services.verifyNick` — the same single
+ * credential home NickServ `REGISTER`, SASL PLAIN, and NickServ
+ * `IDENTIFY` consult) and, on success, delegates to
  * {@link applyAccountSuccess}.
  */
 
@@ -25,6 +27,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 +38,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 +60,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 +90,7 @@ export function applyAccountSuccess(
     Effect.send(ctx.connId, [loggedInLine(ctx, account), saslSuccessLine(ctx)]),
     ...awayEffects,
     ...memoEffects,
+    ...vhostEffects,
     ...emitAccountNotify({ conn: state, account }),
   ];
 }
@@ -101,48 +114,60 @@ 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.
+ *
+ * Credentials are verified against the bound {@link ServicesStore} via
+ * `services.verifyNick` — the same single credential home NickServ
+ * `REGISTER`, SASL PLAIN, and NickServ `IDENTIFY` consult. 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 ServicesStore} 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
+ * the failure path performs the same scrypt work whether the payload
  * nick was unknown or the password was wrong — the observable outcome
  * (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;
-  if (store === undefined) return [];
-  const result = store.verify('PLAIN', {
-    kind: 'PLAIN',
-    username: parsed.nick,
-    password: parsed.password,
-  });
+  const services = ctx.services;
+  if (services === undefined) return [];
+  const result = services.verifyNick(parsed.nick, parsed.password);
   if (result.ok) {
     return applyAccountSuccess(state, ctx, result.account);
   }
   // Equalise timing: perform a verify against a fixed dummy entry so a
-  // failed PASS-auth always costs one extra AccountStore call regardless
-  // of whether the payload nick was unknown or the password was wrong.
-  store.verify('PLAIN', {
-    kind: 'PLAIN',
-    username: PASS_AUTH_DUMMY_NICK,
-    password: PASS_AUTH_DUMMY_PASSWORD,
-  });
+  // failed PASS-auth always costs one extra scrypt verify regardless of
+  // whether the payload nick was unknown or the password was wrong.
+  services.verifyNick(PASS_AUTH_DUMMY_NICK, PASS_AUTH_DUMMY_PASSWORD);
   return [];
 }
 

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',
   );
 }