serverless-ircd 0.7.0 → 0.8.0

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

@@ -0,0 +1,882 @@
+/**
+ * Pure reducer for the ChanServ services pseudo-client.
+ *
+ * ChanServ is invoked via `PRIVMSG ChanServ :<command>`. The actor routes
+ * any `PRIVMSG` whose target matches {@link CHANSERV_NICK}
+ * (case-insensitive) to {@link chanservReducer} instead of the normal
+ * user-target reducer.
+ *
+ * Supported subcommands:
+ *   - `REGISTER <#channel>` — registers the channel against the bound
+ *     {@link ServicesStore} with the invoking connection's account as the
+ *     founder. On success ChanServ sets the channel mode `+r` (registered).
+ *     The connection must be identified (NickServ `+r` user mode).
+ *   - `DROP <#channel>` — removes the channel registration (founder-only).
+ *     Clears the persisted `+r`/`+R`/`+M` channel modes via an
+ *     `ApplyChannelDelta`.
+ *   - `INFO <#channel>` — queries the registration record.
+ *   - `SET <subkey> <args…>` — updates the persisted channel record:
+ *       - `SET FOUNDER <account>` — transfer founder (identified target
+ *         that has a registered nick).
+ *       - `SET MLOCK <modestring>` — lock modes so the MODE reducer
+ *         reapplies them if an op tries to unset them.
+ *       - `SET RESTRICTED ON|OFF` — toggle the channel's `+R` mode
+ *         (block join/PRIVMSG from unidentified).
+ *       - `SET KEEPTOPIC ON|OFF` — persist the channel topic across
+ *         empty-recreate via {@link ServicesStore.setChannelTopic}.
+ *   - `ACCESS <#channel> ADD|DEL|LIST [args]` — manages the per-account
+ *     access list. `ADD <account> <level>` records a positive integer
+ *     level; `DEL <account>` removes; `LIST` enumerates founder + every
+ *     entry. The JOIN reducer consults the list to apply channel
+ *     prefixes (`@`/`+`) automatically.
+ *   - `SOP|AOP|HOP|VOP <#channel> ADD|DEL|LIST [account]` — shorthand
+ *     for the matching numeric level from {@link SHORTHAND_LEVELS}
+ *     (mirrors the Atheme convention).
+ *   - `LEVELS <#channel> SET|LIST|RESET [args]` — redefines the numeric
+ *     threshold the JOIN hook compares against for the `AUTO*` ops.
+ *     `SET <op> <level>` overrides; `LIST` enumerates; `RESET` clears
+ *     every override so the {@link DEFAULT_CHANNEL_LEVELS} take effect.
+ *
+ * The reducer is a pure `Reducer<ConnectionState>`: all side effects are
+ * emitted as {@link Effect}s. Channel-mode mutations are emitted as
+ * `ApplyChannelDelta` effects (the actor layer applies them to the
+ * authoritative {@link ChannelState}).
+ */
+
+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 { Ctx, Reducer } from '../types.js';
+
+/** Canonical ChanServ pseudo-client nick. */
+export const CHANSERV_NICK = 'ChanServ';
+
+/** Services hostmask fragment used by every services pseudo-client. */
+const SERVICES_HOST = 'services';
+
+/** Hostmask used as the source of ChanServ-emitted MODE prefix grants. */
+export const CHANSERV_HOSTMASK = `${CHANSERV_NICK}!${CHANSERV_NICK}@${SERVICES_HOST}`;
+
+/** Channel-name grammar; mirrors {@link isValidChannelName} in `join.ts`. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+/** Returns true iff `name` looks like a channel target. */
+function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/** ON / OFF values accepted by SET RESTRICTED / SET KEEPTOPIC. */
+const ON_OFF = new Set<string>(['ON', 'OFF']);
+
+/**
+ * Default numeric thresholds for the ChanServ `AUTO*` level checks. The
+ * JOIN hook consults these (or the founder-redefined overrides from
+ * {@link ServicesStore.getChannelLevel}) to decide whether to grant a
+ * channel prefix automatically.
+ *
+ * The values follow the Atheme convention: VOP (auto-voice) sorts below
+ * HOP (auto-halfop; this server has no `+h` prefix, but the level is
+ * preserved so founders can tier access) sorts below AOP (auto-op).
+ * Channel founders implicitly carry the maximum level (`Infinity`) and
+ * always receive `+o` on JOIN.
+ */
+export const DEFAULT_CHANNEL_LEVELS: Readonly<Record<ChannelLevelOp, number>> = {
+  AUTOVOICE: 3,
+  AUTOHALFOP: 4,
+  AUTOOP: 5,
+};
+
+/**
+ * Numeric access levels applied by the `SOP` / `AOP` / `HOP` / `VOP`
+ * shorthand commands. The shorthand subcommands exist purely as
+ * founder-friendly aliases for the matching numeric level; their values
+ * mirror the Atheme defaults so `AOP nick ADD` produces the same access
+ * level an explicit `ACCESS nick ADD 5` would.
+ *
+ * `SOP` has no `AUTO*` threshold wired to it (this server has no `+a`
+ * protect prefix); it is nonetheless tracked so founders can tier
+ * senior ops above AOPs without a numeric incantation.
+ */
+export const SHORTHAND_LEVELS: Readonly<Record<'SOP' | 'AOP' | 'HOP' | 'VOP', number>> = {
+  VOP: DEFAULT_CHANNEL_LEVELS.AUTOVOICE,
+  HOP: DEFAULT_CHANNEL_LEVELS.AUTOHALFOP,
+  AOP: DEFAULT_CHANNEL_LEVELS.AUTOOP,
+  SOP: 10,
+};
+
+/** Set of recognised shorthand verbs (uppercased). */
+const SHORTHAND_VERBS = new Set<string>(['SOP', 'AOP', 'HOP', 'VOP']);
+
+/** Ordered list of level op names, for LEVELS LIST and validation. */
+const LEVEL_OPS: readonly ChannelLevelOp[] = ['AUTOOP', 'AUTOHALFOP', 'AUTOVOICE'];
+
+/**
+ * Reducer for `PRIVMSG ChanServ :<subcommand> <args…>`.
+ * Authority: the invoking connection's {@link ConnectionState}.
+ */
+export const chanservReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (ctx.services === undefined) {
+    effects.push(notice(state, 'Services are not available on this server.'));
+    return { state, effects };
+  }
+
+  const body = msg.params[1] ?? '';
+  const tokens = body.split(/\s+/u).filter((t) => t.length > 0);
+  if (tokens.length === 0) {
+    effects.push(helpNotice(state));
+    return { state, effects };
+  }
+
+  const sub = tokens[0]?.toUpperCase();
+  const args = tokens.slice(1);
+
+  switch (sub) {
+    case 'REGISTER':
+      return handleRegister(state, args, ctx, effects);
+    case 'DROP':
+      return handleDrop(state, args, ctx, effects);
+    case 'INFO':
+      return handleInfo(state, args, ctx, effects);
+    case 'SET':
+      return handleSet(state, args, ctx, effects);
+    case 'ACCESS':
+      return handleAccess(state, args, ctx, effects);
+    case 'LEVELS':
+      return handleLevels(state, args, ctx, effects);
+    default:
+      if (sub !== undefined && SHORTHAND_VERBS.has(sub)) {
+        return handleShorthand(state, sub, args, ctx, effects);
+      }
+      effects.push(unknownNotice(state));
+      return { state, effects };
+  }
+};
+
+// ============================================================================
+// REGISTER
+// ============================================================================
+
+function handleRegister(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const channel = args[0];
+
+  if (channel === undefined || !isValidChannelName(channel, ctx.serverConfig.channelLen)) {
+    effects.push(notice(state, 'Syntax: REGISTER <#channel>'));
+    return { state, effects };
+  }
+
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before registering a channel.'));
+    return { state, effects };
+  }
+
+  const result = services.registerChannel(channel, state.account);
+  if (!result.ok) {
+    effects.push(notice(state, `Channel ${channel} is already registered.`));
+    return { state, effects };
+  }
+
+  // Set channel mode +r via an ApplyChannelDelta effect. The actor layer
+  // applies this to the authoritative ChannelState.
+  effects.push(Effect.applyChannelDelta(channel, setRegisteredDelta()));
+  effects.push(notice(state, `Channel ${channel} is now registered.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// DROP
+// ============================================================================
+
+function handleDrop(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const channel = args[0];
+
+  if (channel === undefined || !isValidChannelName(channel, ctx.serverConfig.channelLen)) {
+    effects.push(notice(state, 'Syntax: DROP <#channel>'));
+    return { state, effects };
+  }
+
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before dropping a channel.'));
+    return { state, effects };
+  }
+
+  const founder = services.getChannelFounder(channel);
+  if (founder === undefined) {
+    effects.push(notice(state, `Channel ${channel} is not registered.`));
+    return { state, effects };
+  }
+  if (caseFold('rfc1459', founder) !== caseFold('rfc1459', state.account)) {
+    effects.push(notice(state, `Only the founder of ${channel} may drop it.`));
+    return { state, effects };
+  }
+
+  services.dropChannel(channel);
+  // Clear the services-derived channel modes (r/R/M) on drop so the channel
+  // goes back to unregistered behaviour.
+  effects.push(Effect.applyChannelDelta(channel, clearServicesModesDelta()));
+  effects.push(notice(state, `Channel ${channel} has been dropped.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// INFO
+// ============================================================================
+
+function handleInfo(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const channel = args[0];
+
+  if (channel === undefined || !isValidChannelName(channel, ctx.serverConfig.channelLen)) {
+    effects.push(notice(state, 'Syntax: INFO <#channel>'));
+    return { state, effects };
+  }
+
+  const founder = services.getChannelFounder(channel);
+  if (founder === undefined) {
+    effects.push(notice(state, `Channel ${channel} is not registered.`));
+    return { state, effects };
+  }
+
+  effects.push(notice(state, `Channel: ${channel}`));
+  effects.push(notice(state, `Founder: ${founder}`));
+  return { state, effects };
+}
+
+// ============================================================================
+// SET
+// ============================================================================
+
+/**
+ * Handles `SET <subkey> <args…>`. Routes to the matching subcommand handler.
+ * All subcommands require the caller to be the channel founder.
+ */
+function handleSet(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const subkey = args[0]?.toUpperCase();
+  const channelArg = args[1];
+  const rest = args.slice(2);
+
+  // Validate channel name first; every SET subcommand requires one.
+  if (channelArg === undefined || !isValidChannelName(channelArg, ctx.serverConfig.channelLen)) {
+    effects.push(setSyntaxNotice(state, subkey));
+    return { state, effects };
+  }
+
+  if (state.account === undefined) {
+    effects.push(notice(state, 'You must identify before changing channel settings.'));
+    return { state, effects };
+  }
+
+  const founder = services.getChannelFounder(channelArg);
+  if (founder === undefined) {
+    effects.push(notice(state, `Channel ${channelArg} is not registered.`));
+    return { state, effects };
+  }
+  if (caseFold('rfc1459', founder) !== caseFold('rfc1459', state.account)) {
+    effects.push(notice(state, `Only the founder of ${channelArg} may change its settings.`));
+    return { state, effects };
+  }
+
+  switch (subkey) {
+    case 'FOUNDER':
+      return handleSetFounder(state, channelArg, rest, ctx, effects);
+    case 'MLOCK':
+      return handleSetMlock(state, channelArg, rest, ctx, effects);
+    case 'RESTRICTED':
+      return handleSetRestricted(state, channelArg, rest, ctx, effects);
+    case 'KEEPTOPIC':
+      return handleSetKeepTopic(state, channelArg, rest, ctx, effects);
+    default:
+      effects.push(setSyntaxNotice(state, undefined));
+      return { state, effects };
+  }
+}
+
+function handleSetFounder(
+  state: ConnectionState,
+  channel: string,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const newFounder = args[0];
+  if (newFounder === undefined) {
+    effects.push(notice(state, 'Syntax: SET FOUNDER <#channel> <account>'));
+    return { state, effects };
+  }
+  // The new founder must have a registered nick (account exists).
+  if (!services.isRegisteredNick(newFounder)) {
+    effects.push(notice(state, `Nick ${newFounder} is not registered.`));
+    return { state, effects };
+  }
+  services.setChannelFounder(channel, newFounder);
+  effects.push(notice(state, `Founder for ${channel} is now set to ${newFounder}.`));
+  return { state, effects };
+}
+
+function handleSetMlock(
+  state: ConnectionState,
+  channel: string,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  // MLOCK accepts a single modestring argument; an empty modestring (or the
+  // literal `*` per Atheme convention) clears the lock. The token arrives as
+  // args[0]; the splitter would have dropped a truly-empty token, so a `*`
+  // sentinel or absent arg means clear.
+  const modestring = args[0];
+  if (modestring === undefined || modestring === '*') {
+    services.setChannelMlock(channel, '');
+    effects.push(notice(state, `Mode lock for ${channel} has been cleared.`));
+    return { state, effects };
+  }
+  if (!isValidMlockString(modestring)) {
+    effects.push(notice(state, `Invalid mode lock: ${modestring}`));
+    return { state, effects };
+  }
+  services.setChannelMlock(channel, modestring);
+  effects.push(notice(state, `Mode lock for ${channel} is now set to ${modestring}.`));
+  return { state, effects };
+}
+
+function handleSetRestricted(
+  state: ConnectionState,
+  channel: string,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const value = args[0]?.toUpperCase();
+  if (value === undefined || !ON_OFF.has(value)) {
+    effects.push(notice(state, 'Syntax: SET RESTRICTED <#channel> ON|OFF'));
+    return { state, effects };
+  }
+  const on = value === 'ON';
+  services.setChannelRestricted(channel, on);
+  // SET RESTRICTED toggles the +R channel mode (ChanServ-driven).
+  effects.push(
+    Effect.applyChannelDelta(channel, { modeChanges: [{ mode: 'blockUnidentified', set: on }] }),
+  );
+  effects.push(notice(state, `Restricted (block unidentified) for ${channel} is now ${value}.`));
+  return { state, effects };
+}
+
+function handleSetKeepTopic(
+  state: ConnectionState,
+  channel: string,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const services = ctx.services as ServicesStore;
+  const value = args[0]?.toUpperCase();
+  if (value === undefined || !ON_OFF.has(value)) {
+    effects.push(notice(state, 'Syntax: SET KEEPTOPIC <#channel> ON|OFF'));
+    return { state, effects };
+  }
+  const on = value === 'ON';
+  services.setChannelKeepTopic(channel, on);
+  effects.push(notice(state, `Keep-topic for ${channel} is now ${value}.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// ACCESS
+// ============================================================================
+
+/**
+ * Validates the founder invariant for an ACCESS / LEVELS / shorthand
+ * subcommand. On success returns the bound {@link ServicesStore}; on
+ * failure pushes the matching notice into `effects` and returns `null`.
+ *
+ * Mirrors the founder-precondition block in {@link handleSet} so the
+ * access surface shares a single error-message shape with `SET`.
+ */
+function requireFounderForChannel(
+  state: ConnectionState,
+  channel: string,
+  ctx: Ctx,
+  effects: EffectType[],
+): 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)) {
+    effects.push(notice(state, `Only the founder of ${channel} may change its settings.`));
+    return null;
+  }
+  return services;
+}
+
+/**
+ * Handles `ACCESS <#channel> ADD|DEL|LIST [args]`.
+ *
+ *   - `ACCESS <chan> ADD <account> <level>` — records (or replaces) the
+ *     numeric access level for `account`. `<level>` must be a positive
+ *     integer.
+ *   - `ACCESS <chan> DEL <account>` — removes the access entry.
+ *   - `ACCESS <chan> LIST` — enumerates the founder and every access
+ *     entry with its level.
+ */
+function handleAccess(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const channel = args[0];
+  if (channel === undefined || !isValidChannelName(channel, ctx.serverConfig.channelLen)) {
+    effects.push(notice(state, 'Syntax: ACCESS <#channel> ADD|DEL|LIST [args].'));
+    return { state, effects };
+  }
+
+  const action = args[1]?.toUpperCase();
+  const rest = args.slice(2);
+  const services = ctx.services as ServicesStore;
+
+  if (action === 'LIST') {
+    const founder = services.getChannelFounder(channel);
+    if (founder === undefined) {
+      effects.push(notice(state, `Channel ${channel} is not registered.`));
+      return { state, effects };
+    }
+    effects.push(notice(state, `Channel: ${channel}`));
+    effects.push(notice(state, `Founder: ${founder}`));
+    for (const { account, level } of services.listChannelAccess(channel)) {
+      effects.push(notice(state, `Nick ${account} (level ${level})`));
+    }
+    effects.push(notice(state, 'End of access list.'));
+    return { state, effects };
+  }
+
+  const founderServices = requireFounderForChannel(state, channel, ctx, effects);
+  if (founderServices === null) return { state, effects };
+
+  switch (action) {
+    case 'ADD':
+      return handleAccessAdd(state, channel, rest, founderServices, effects);
+    case 'DEL':
+      return handleAccessDel(state, channel, rest, founderServices, effects);
+    default:
+      effects.push(notice(state, 'Syntax: ACCESS <#channel> ADD|DEL|LIST [args].'));
+      return { state, effects };
+  }
+}
+
+function handleAccessAdd(
+  state: ConnectionState,
+  channel: string,
+  args: string[],
+  services: ServicesStore,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const target = args[0];
+  const levelToken = args[1];
+  if (target === undefined || levelToken === undefined) {
+    effects.push(notice(state, 'Syntax: ACCESS <#channel> ADD <account> <level>.'));
+    return { state, effects };
+  }
+  const level = Number.parseInt(levelToken, 10);
+  if (!Number.isInteger(level) || level <= 0) {
+    effects.push(notice(state, 'Syntax: ACCESS <#channel> ADD <account> <level>.'));
+    return { state, effects };
+  }
+  if (!services.isRegisteredNick(target)) {
+    effects.push(notice(state, `Nick ${target} is not registered.`));
+    return { state, effects };
+  }
+  services.setChannelAccess(channel, target, level);
+  effects.push(
+    notice(
+      state,
+      `${capitalize(target)} added to the access list for ${channel} at level ${level}.`,
+    ),
+  );
+  return { state, effects };
+}
+
+function handleAccessDel(
+  state: ConnectionState,
+  channel: string,
+  args: string[],
+  services: ServicesStore,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const target = args[0];
+  if (target === undefined) {
+    effects.push(notice(state, 'Syntax: ACCESS <#channel> DEL <account>.'));
+    return { state, effects };
+  }
+  services.setChannelAccess(channel, target, 0);
+  effects.push(notice(state, `${capitalize(target)} removed from the access list for ${channel}.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// SOP / AOP / HOP / VOP shorthand
+// ============================================================================
+
+/**
+ * Handles `SOP|AOP|HOP|VOP <#channel> ADD|DEL|LIST [account]` shorthand.
+ *
+ * The verb selects a fixed numeric level from {@link SHORTHAND_LEVELS}
+ * (mirroring the Atheme convention) and routes the request through the
+ * canonical {@link handleAccessAdd} / {@link handleAccessDel} helpers so
+ * the only divergence between `AOP #chan ADD nick` and the explicit
+ * `ACCESS #chan ADD nick 5` is the level source.
+ */
+function handleShorthand(
+  state: ConnectionState,
+  verb: string,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const channel = args[0];
+  if (channel === undefined || !isValidChannelName(channel, ctx.serverConfig.channelLen)) {
+    effects.push(notice(state, `Syntax: ${verb} <#channel> ADD|DEL|LIST [account].`));
+    return { state, effects };
+  }
+
+  const action = args[1]?.toUpperCase();
+  const rest = args.slice(2);
+
+  if (action === 'LIST') {
+    return handleAccess(state, [channel, 'LIST'], ctx, effects);
+  }
+
+  const services = requireFounderForChannel(state, channel, ctx, effects);
+  if (services === null) return { state, effects };
+
+  // `verb` is one of SOP/AOP/HOP/VOP at the dispatch site, so the lookup
+  // is total; the cast keeps TS happy without a runtime branch.
+  const verbKey = verb as keyof typeof SHORTHAND_LEVELS;
+  const level = SHORTHAND_LEVELS[verbKey];
+
+  switch (action) {
+    case 'ADD':
+      return handleShorthandAdd(state, verb, channel, rest, level, services, effects);
+    case 'DEL':
+      return handleShorthandDel(state, verb, channel, rest, services, effects);
+    default:
+      effects.push(notice(state, `Syntax: ${verb} <#channel> ADD|DEL|LIST [account].`));
+      return { state, effects };
+  }
+}
+
+function handleShorthandAdd(
+  state: ConnectionState,
+  verb: string,
+  channel: string,
+  args: string[],
+  level: number,
+  services: ServicesStore,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const target = args[0];
+  if (target === undefined) {
+    effects.push(notice(state, `Syntax: ${verb} <#channel> ADD|DEL|LIST [account].`));
+    return { state, effects };
+  }
+  if (!services.isRegisteredNick(target)) {
+    effects.push(notice(state, `Nick ${target} is not registered.`));
+    return { state, effects };
+  }
+  services.setChannelAccess(channel, target, level);
+  effects.push(
+    notice(
+      state,
+      `${capitalize(target)} added to the access list for ${channel} at level ${level}.`,
+    ),
+  );
+  return { state, effects };
+}
+
+function handleShorthandDel(
+  state: ConnectionState,
+  verb: string,
+  channel: string,
+  args: string[],
+  services: ServicesStore,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const target = args[0];
+  if (target === undefined) {
+    effects.push(notice(state, `Syntax: ${verb} <#channel> ADD|DEL|LIST [account].`));
+    return { state, effects };
+  }
+  services.setChannelAccess(channel, target, 0);
+  effects.push(notice(state, `${capitalize(target)} removed from the access list for ${channel}.`));
+  return { state, effects };
+}
+
+// ============================================================================
+// LEVELS
+// ============================================================================
+
+/**
+ * Handles `LEVELS <#channel> SET|LIST|RESET [args]`.
+ *
+ *   - `LEVELS <chan> SET <op> <level>` — redefines the numeric threshold
+ *     the JOIN hook compares against for the `AUTO*` op. `<op>` must be
+ *     one of {@link LEVEL_OPS}.
+ *   - `LEVELS <chan> LIST` — enumerates every threshold, falling back
+ *     to the {@link DEFAULT_CHANNEL_LEVELS} default for ops the founder
+ *     has not overridden.
+ *   - `LEVELS <chan> RESET` — drops every override.
+ */
+function handleLevels(
+  state: ConnectionState,
+  args: string[],
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ConnectionState; effects: EffectType[] } {
+  const channel = args[0];
+  if (channel === undefined || !isValidChannelName(channel, ctx.serverConfig.channelLen)) {
+    effects.push(notice(state, 'Syntax: LEVELS <#channel> SET|LIST|RESET [args].'));
+    return { state, effects };
+  }
+
+  const action = args[1]?.toUpperCase();
+  const services = ctx.services as ServicesStore;
+
+  if (action === 'LIST') {
+    const founder = services.getChannelFounder(channel);
+    if (founder === undefined) {
+      effects.push(notice(state, `Channel ${channel} is not registered.`));
+      return { state, effects };
+    }
+    effects.push(notice(state, `Channel: ${channel}`));
+    const overrides = new Map<ChannelLevelOp, number>();
+    for (const { op, level } of services.listChannelLevels(channel)) overrides.set(op, level);
+    for (const op of LEVEL_OPS) {
+      const level = overrides.get(op) ?? DEFAULT_CHANNEL_LEVELS[op];
+      effects.push(notice(state, `${op} ${level}`));
+    }
+    effects.push(notice(state, 'End of level list.'));
+    return { state, effects };
+  }
+
+  const founderServices = requireFounderForChannel(state, channel, ctx, effects);
+  if (founderServices === null) return { state, effects };
+
+  if (action === 'RESET') {
+    founderServices.resetChannelLevels(channel);
+    effects.push(notice(state, `Levels for ${channel} reset to defaults.`));
+    return { state, effects };
+  }
+
+  if (action === 'SET') {
+    const opName = args[2]?.toUpperCase();
+    const levelToken = args[3];
+    if (opName === undefined || levelToken === undefined) {
+      effects.push(notice(state, 'Syntax: LEVELS <#channel> SET <op> <level>.'));
+      return { state, effects };
+    }
+    if (!isKnownLevelOp(opName)) {
+      effects.push(notice(state, `Unknown level ${opName}. Available: ${LEVEL_OPS.join(', ')}.`));
+      return { state, effects };
+    }
+    const level = Number.parseInt(levelToken, 10);
+    if (!Number.isInteger(level)) {
+      effects.push(notice(state, 'Syntax: LEVELS <#channel> SET <op> <level>.'));
+      return { state, effects };
+    }
+    founderServices.setChannelLevel(channel, opName, level);
+    effects.push(notice(state, `Level ${opName} for ${channel} is now ${level}.`));
+    return { state, effects };
+  }
+
+  effects.push(notice(state, 'Syntax: LEVELS <#channel> SET|LIST|RESET [args].'));
+  return { state, effects };
+}
+
+/** Returns true iff `op` is a recognised level-threshold name. */
+function isKnownLevelOp(op: string): op is ChannelLevelOp {
+  return LEVEL_OPS.includes(op as ChannelLevelOp);
+}
+
+/**
+ * Capitalises the first character of `value` (display helper). Callers
+ * pre-validate that `value` is non-empty (the token splitter drops empty
+ * args), so the empty-string degenerate case returns the empty string
+ * via `charAt(0)` returning `''` — no explicit length check needed.
+ */
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+// ============================================================================
+// Notice helpers
+// ============================================================================
+
+/** Builds a `:ChanServ!ChanServ@services NOTICE <nick> :<text>` line. */
+function notice(state: ConnectionState, text: string): EffectType {
+  return Effect.send(state.id, [servicesNotice(CHANSERV_NICK, state, text)]);
+}
+
+/** Builds a help `:ChanServ!ChanServ@services NOTICE <nick> :…` line. */
+function helpNotice(state: ConnectionState): EffectType {
+  return notice(
+    state,
+    'Available commands: REGISTER, DROP, INFO, SET, ACCESS, LEVELS, SOP, AOP, HOP, VOP',
+  );
+}
+
+function unknownNotice(state: ConnectionState): EffectType {
+  return notice(
+    state,
+    'Unknown command. Available: REGISTER, DROP, INFO, SET, ACCESS, LEVELS, SOP, AOP, HOP, VOP',
+  );
+}
+
+/** Builds a `SET <subkey>` syntax NOTICE; `subkey === undefined` lists every subcommand. */
+function setSyntaxNotice(state: ConnectionState, subkey: string | undefined): EffectType {
+  if (subkey === 'FOUNDER') return notice(state, 'Syntax: SET FOUNDER <#channel> <account>');
+  if (subkey === 'MLOCK') return notice(state, 'Syntax: SET MLOCK <#channel> <modestring>');
+  if (subkey === 'RESTRICTED') return notice(state, 'Syntax: SET RESTRICTED <#channel> ON|OFF');
+  if (subkey === 'KEEPTOPIC') return notice(state, 'Syntax: SET KEEPTOPIC <#channel> ON|OFF');
+  return notice(state, 'Available SET subcommands: FOUNDER, MLOCK, RESTRICTED, KEEPTOPIC');
+}
+
+/**
+ * Formats a services NOTICE line. The source hostmask is
+ * `<svc>!<svc>@services` regardless of the deployment's serverName so the
+ * pseudo-clients are stable across deployments and easy to identify in
+ * client UIs.
+ */
+function servicesNotice(svc: string, state: ConnectionState, text: string): RawLine {
+  const nick = state.nick ?? '*';
+  return { text: `:${svc}!${svc}@${SERVICES_HOST} NOTICE ${nick} :${text}` };
+}
+
+// ============================================================================
+// Mode-delta helpers
+// ============================================================================
+
+/** Builds a delta that sets the `+r` (registered) channel mode. */
+export function setRegisteredDelta(): ChannelDelta {
+  return { modeChanges: [{ mode: 'registered', set: true }] };
+}
+
+/** Builds a delta that clears every services-derived channel mode (r/R/M). */
+export function clearServicesModesDelta(): ChannelDelta {
+  return {
+    modeChanges: [
+      { mode: 'registered', set: false },
+      { mode: 'blockUnidentified', set: false },
+      { mode: 'moderatedIdent', set: false },
+    ],
+  };
+}
+
+// ============================================================================
+// MLOCK validation
+// ============================================================================
+
+/**
+ * Set of channel-mode letters that may appear in an MLOCK string. Booleans
+ * (i/t/n/m/s/p/r/R/M), parameterized-on-set (k/l), and prefix (o/v) plus the
+ * list mode (b) are all permitted;ChanServ reapplies only the boolean ones
+ * (parameterized modes are sticky via ChanServ-set state, not auto-set on
+ * every op MODE).
+ */
+const MLOCK_ALLOWED_LETTERS = new Set<string>([
+  'i',
+  't',
+  'n',
+  'm',
+  's',
+  'p',
+  'r',
+  'R',
+  'M',
+  'k',
+  'l',
+  'o',
+  'v',
+  'b',
+]);
+
+/**
+ * Returns true iff `modestring` is a syntactically-valid MLOCK argument: an
+ * optional leading sign, then one or more allowed mode letters, optionally
+ * followed by a space and arguments for parameterized modes (passed through
+ * verbatim; ChanServ does not currently reapply them).
+ */
+function isValidMlockString(modestring: string): boolean {
+  // Allow a bare sign-prefixed modestring (the common case). A leading `+`
+  // is implicit when omitted; the canonical form stores the explicit sign.
+  let s = modestring;
+  if (s.length > 0 && (s[0] === '+' || s[0] === '-')) {
+    s = s.slice(1);
+  }
+  if (s.length === 0) return false;
+  for (const ch of s) {
+    if (!MLOCK_ALLOWED_LETTERS.has(ch)) return false;
+  }
+  return true;
+}
+
+/**
+ * Parses the locked-mode letters out of a stored MLOCK modestring. Returns
+ * the set of boolean-mode letters that are positively locked (i.e. signed
+ * `+` or unsigned). Used by the MODE reducer to reapply modes an op tried to
+ * unset.
+ */
+export function positiveMlockLetters(mlock: string): Set<string> {
+  const out = new Set<string>();
+  let positive = true;
+  for (const ch of mlock) {
+    if (ch === '+') {
+      positive = true;
+      continue;
+    }
+    if (ch === '-') {
+      positive = false;
+      continue;
+    }
+    if (positive) out.add(ch);
+  }
+  return out;
+}