serverless-ircd 0.1.0

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

@@ -0,0 +1,655 @@
+/**
+ * Pure reducers for the IRC `MODE` command.
+ *
+ * PLAN §2.1 location-of-authority splits MODE across two authorities:
+ *
+ *   - **Channel MODE** (`MODE #chan …`): the channel is authoritative for
+ *     modes, keys, ban masks, and prefix flags on its roster, so the
+ *     reducer's `state` argument is the channel's {@link ChannelState}.
+ *     Writes require op (482 otherwise); reads require membership for
+ *     +s/+p channels (442 otherwise).
+ *   - **User MODE** (`MODE <nick> …`): the connection is authoritative
+ *     for its own user modes, so the reducer's `state` argument is the
+ *     caller's {@link ConnectionState}. A user may only change their own
+ *     modes (502 otherwise). The oper flag (`+o`) is granted via the
+ *     future OPER command, not via MODE — `+o` here is rejected with 481.
+ *
+ * Mode classes (per modern IRC de-facto convention):
+ *   - Type A (list mode, always takes arg): `b` (ban mask).
+ *   - Type B (prefix mode, always takes nick arg): `o`, `v`.
+ *   - Type C (param-on-set, no-param-on-clear): `k`, `l`.
+ *   - Type D (boolean, no arg): `i`, `t`, `n`, `m`, `s`, `p`.
+ *
+ * Wire format:
+ *   - Read modes: `:<server> 324 <nick> <chan> <modestring> [args]`
+ *   - Query bans: `:<server> 367 <nick> <chan> <mask>` × N, then
+ *     `:<server> 368 <nick> <chan> :End of Channel Ban List`.
+ *   - Apply: `:<source> MODE <chan> <modestring> [args]` broadcast to the
+ *     channel.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { BooleanChannelMode, ChannelState } from '../state/channel.js';
+import type {
+  BanMaskChange,
+  ChannelDelta,
+  ChannelModeName,
+  MembershipDelta,
+  ModeChange,
+} from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** Channel-name grammar; mirrors {@link isValidChannelName} in `join.ts`. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/** Returns the caller's hostmask, falling back to nick then `?`. */
+function callerHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/** Formats a numeric error/reply line addressed to the connection's nick. */
+function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== undefined) parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/** Lowercases a nick using ASCII case folding (matches kick.ts). */
+function lowerNick(nick: string): string {
+  return nick.toLowerCase();
+}
+
+/** Boolean channel mode letters → mode-field name. */
+const BOOLEAN_LETTERS: Readonly<Record<string, BooleanChannelMode>> = {
+  i: 'inviteOnly',
+  t: 'topicLock',
+  n: 'noExternal',
+  m: 'moderated',
+  s: 'secret',
+  p: 'private',
+};
+
+/** Boolean channel mode letters in canonical 324 output order. */
+const BOOLEAN_LETTER_ORDER = ['i', 't', 'n', 'm', 's', 'p'] as const;
+
+/** Prefix channel mode letters (always take a nick arg). */
+const PREFIX_LETTERS = new Set<string>(['o', 'v']);
+
+/** List channel mode letters (always take a mask arg). */
+const LIST_LETTERS = new Set<string>(['b']);
+
+/** One parsed op from a modestring. */
+interface ModeOp {
+  sign: '+' | '-';
+  letter: string;
+  /** Consumed argument from the params tail, when applicable. */
+  arg?: string;
+}
+
+/** Result of applying a sequence of ops; used to rebuild the broadcast. */
+interface AppliedMode {
+  sign: '+' | '-';
+  letter: string;
+  /** Argument echoed back in the broadcast (e.g. the nick for +o). */
+  arg?: string;
+}
+
+// ============================================================================
+// Channel MODE
+// ============================================================================
+
+/**
+ * Handles `MODE <chan> [<modestring> [args…]]`.
+ *
+ * Validation order: missing-param → invalid-name → membership check for
+ * +s/+p reads → write authorization (member + op) → parse + apply per op.
+ */
+export const channelModeReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const rawName = msg.params[0];
+  if (rawName === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'MODE'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  if (!isValidChannelName(rawName, ctx.serverConfig.channelLen)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOSUCHCHANNEL, 'No such channel', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Read form: no modestring supplied.
+  const modestring = msg.params[1];
+  if (modestring === undefined) {
+    return readChannelModes(state, ctx, effects);
+  }
+
+  // Write form. Non-members cannot change modes.
+  const callerEntry = state.members.get(ctx.connId);
+  const isMember = callerEntry !== undefined;
+  if ((state.modes.secret || state.modes.private) && !isMember) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+  if (!isMember) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Ban-list query forms: `+b` with no arg, or `b` as a bare modestring.
+  if (msg.params.length === 2 && (modestring === 'b' || modestring === '+b')) {
+    return listBans(state, ctx, effects);
+  }
+
+  // Anything else with a sign in front requires op.
+  if (!callerEntry.op) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_CHANOPRIVSNEEDED, "You're not channel operator", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const ops = parseModestring(modestring, msg.params.slice(2));
+  const applied: AppliedMode[] = [];
+  const delta: ChannelDelta = {};
+
+  for (const op of ops) {
+    const result = applyChannelOp(state, ctx, op, effects, delta);
+    if (result !== null) applied.push(result);
+  }
+
+  if (applied.length > 0) {
+    // Mirror the mode/roster/ban changes to the runtime's channel
+    // authority BEFORE the broadcast so distributed runtimes (CF
+    // ChannelDO) have persisted the change before any peer's next
+    // prefetch observes it. In the in-memory runtime the actor's
+    // `state` IS authoritative so this is redundant.
+    if (
+      (delta.modeChanges !== undefined && delta.modeChanges.length > 0) ||
+      (delta.banMaskChanges !== undefined && delta.banMaskChanges.length > 0) ||
+      (delta.memberships !== undefined && delta.memberships.length > 0)
+    ) {
+      effects.push(Effect.applyChannelDelta(state.name, delta));
+    }
+    const hostmask = callerHostmask(ctx.connection);
+    effects.push(Effect.broadcast(state.name, [buildModeBroadcast(hostmask, state.name, applied)]));
+  }
+
+  return { state, effects };
+};
+
+/**
+ * Parses a modestring into a sequence of ops with consumed args.
+ *
+ *   - Signs `+`/`-` toggle the active sign; an unrecognized leading char is
+ *     treated as `+` (defensive — but the parser also emits 472 for unknown
+ *     letters so the visible behavior is still correct).
+ *   - Type B (`o`/`v`) and Type A (`b`) consume one arg on both signs.
+ *   - Type C (`k`/`l`) consume one arg on `+` only.
+ *   - Type D (boolean) consumes no arg.
+ *   - Unknown letters are still emitted as ops so applyChannelOp can produce
+ *     the 472 numeric; they consume no arg.
+ */
+function parseModestring(modestring: string, args: string[]): ModeOp[] {
+  const ops: ModeOp[] = [];
+  let sign: '+' | '-' = '+';
+  let argIdx = 0;
+
+  for (const ch of modestring) {
+    if (ch === '+') {
+      sign = '+';
+      continue;
+    }
+    if (ch === '-') {
+      sign = '-';
+      continue;
+    }
+
+    let arg: string | undefined;
+    if (consumesArgs(ch, sign)) {
+      arg = args[argIdx++];
+    }
+    ops.push({ sign, letter: ch, ...(arg !== undefined ? { arg } : {}) });
+  }
+
+  return ops;
+}
+
+/** Helper kept separate for clarity; mirrors the consuming-arg rules above. */
+function consumesArgs(letter: string, sign: '+' | '-'): boolean {
+  if (PREFIX_LETTERS.has(letter)) return true;
+  if (LIST_LETTERS.has(letter)) return true;
+  if (sign === '+' && (letter === 'k' || letter === 'l')) return true;
+  return false;
+}
+
+/**
+ * Applies a single parsed op to the channel state. Returns an
+ * {@link AppliedMode} to include in the broadcast, or `null` if the op was
+ * rejected (in which case the appropriate numeric was pushed to `effects`).
+ *
+ * Special case: `+b` with no arg is a ban-list query. The caller has already
+ * handled bare `b` / `+b` modestrings before reaching here, but defensive
+ * handling emits the list inline if a query sneaks through inside a combined
+ * modestring. In that case the op produces no AppliedMode and no broadcast.
+ */
+function applyChannelOp(
+  state: ChannelState,
+  ctx: Ctx,
+  op: ModeOp,
+  effects: EffectType[],
+  delta: ChannelDelta,
+): AppliedMode | null {
+  const { sign, letter } = op;
+
+  if (BOOLEAN_LETTERS[letter] !== undefined) {
+    const field = BOOLEAN_LETTERS[letter] as BooleanChannelMode;
+    state.modes[field] = sign === '+';
+    pushModeChange(delta, field, sign === '+');
+    return { sign, letter };
+  }
+
+  if (letter === 'k') {
+    if (sign === '+') {
+      if (op.arg === undefined || op.arg.length === 0) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'k'),
+          ]),
+        );
+        return null;
+      }
+      state.modes.key = op.arg;
+      pushModeChange(delta, 'key', true, op.arg);
+      return { sign, letter, arg: op.arg };
+    }
+    // Clearing k: ignore any supplied arg (modern behavior).
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+    delete state.modes.key;
+    pushModeChange(delta, 'key', false);
+    return { sign, letter };
+  }
+
+  if (letter === 'l') {
+    if (sign === '+') {
+      if (op.arg === undefined || op.arg.length === 0 || !/^[0-9]+$/u.test(op.arg)) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'l'),
+          ]),
+        );
+        return null;
+      }
+      const n = Number.parseInt(op.arg, 10);
+      state.modes.limit = n;
+      pushModeChange(delta, 'limit', true, n);
+      return { sign, letter, arg: String(n) };
+    }
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+    delete state.modes.limit;
+    pushModeChange(delta, 'limit', false);
+    return { sign, letter };
+  }
+
+  if (PREFIX_LETTERS.has(letter)) {
+    if (op.arg === undefined || op.arg.length === 0) {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', letter),
+        ]),
+      );
+      return null;
+    }
+    const target = findMemberByNick(state, op.arg);
+    if (target === null) {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericErr(
+            ctx,
+            Numerics.ERR_USERNOTINCHANNEL,
+            'They are not on that channel',
+            `${op.arg} ${state.name}`,
+          ),
+        ]),
+      );
+      return null;
+    }
+    if (letter === 'o') target.op = sign === '+';
+    else target.voice = sign === '+';
+    pushMembershipChange(delta, target.conn, target.nick, target.op, target.voice);
+    return { sign, letter, arg: target.nick };
+  }
+
+  if (LIST_LETTERS.has(letter)) {
+    // `b`: with no arg → query list (handled before we reach here for the
+    // bare modestring). Inside a combined modestring, treat no-arg +b as a
+    // query and emit the ban list inline.
+    if (op.arg === undefined || op.arg.length === 0) {
+      emitBanList(state, ctx, effects);
+      return null;
+    }
+    if (sign === '+') {
+      state.banMasks.add(op.arg);
+      pushBanMaskChange(delta, 'add', op.arg);
+    } else {
+      state.banMasks.delete(op.arg);
+      pushBanMaskChange(delta, 'remove', op.arg);
+    }
+    return { sign, letter, arg: op.arg };
+  }
+
+  // Unknown mode char.
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericErr(ctx, Numerics.ERR_UNKNOWNMODE, 'is unknown mode char to me', letter),
+    ]),
+  );
+  return null;
+}
+
+/** Appends a boolean/parameterized mode toggle to `delta.modeChanges`. */
+function pushModeChange(
+  delta: ChannelDelta,
+  mode: ChannelModeName,
+  set: boolean,
+  arg?: string | number,
+): void {
+  if (delta.modeChanges === undefined) delta.modeChanges = [];
+  const change: ModeChange = { mode, set };
+  if (arg !== undefined) change.arg = arg;
+  delta.modeChanges.push(change);
+}
+
+/** Appends a ban-mask add/remove to `delta.banMaskChanges`. */
+function pushBanMaskChange(delta: ChannelDelta, type: 'add' | 'remove', mask: string): void {
+  if (delta.banMaskChanges === undefined) delta.banMaskChanges = [];
+  const change: BanMaskChange = { type, mask };
+  delta.banMaskChanges.push(change);
+}
+
+/** Appends a roster entry update (prefix change) to `delta.memberships`. */
+function pushMembershipChange(
+  delta: ChannelDelta,
+  conn: string,
+  nick: string,
+  op: boolean,
+  voice: boolean,
+): void {
+  if (delta.memberships === undefined) delta.memberships = [];
+  const m: MembershipDelta = { type: 'add', conn, nick, op, voice };
+  delta.memberships.push(m);
+}
+
+/** Finds a roster entry by nick (case-insensitive); returns a writable ref. */
+function findMemberByNick(
+  state: ChannelState,
+  nick: string,
+): { conn: string; nick: string; op: boolean; voice: boolean } | null {
+  const targetLower = lowerNick(nick);
+  for (const entry of state.members.values()) {
+    if (lowerNick(entry.nick) === targetLower) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+/** Rebuilds the broadcast line for a sequence of applied ops. */
+function buildModeBroadcast(hostmask: string, chanName: string, applied: AppliedMode[]): RawLine {
+  let modeStr = '';
+  const args: string[] = [];
+  let curSign: '+' | '-' | '' = '';
+  for (const op of applied) {
+    if (op.sign !== curSign) {
+      modeStr += op.sign;
+      curSign = op.sign;
+    }
+    modeStr += op.letter;
+    if (op.arg !== undefined) args.push(op.arg);
+  }
+  const lead = `:${hostmask} MODE ${chanName} ${modeStr}`;
+  if (args.length === 0) return { text: lead };
+  return { text: `${lead} ${args.join(' ')}` };
+}
+
+// ============================================================================
+// Channel MODE — read / query helpers
+// ============================================================================
+
+/**
+ * Emits `324 RPL_CHANNELMODEIS` for the channel's current modes.
+ *
+ * Boolean modes are listed in {@link BOOLEAN_LETTER_ORDER}; parameterized
+ * modes follow in `k` then `l` order with their args. Prefix modes (`o`/`v`)
+ * are intentionally omitted from `324`; clients read them from NAMES.
+ */
+function readChannelModes(
+  state: ChannelState,
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ChannelState; effects: EffectType[] } {
+  // Visibility: +s/+p channels hide their modes from non-members.
+  const isMember = state.members.has(ctx.connId);
+  if ((state.modes.secret || state.modes.private) && !isMember) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", state.name),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const modeStr = buildReadModeString(state);
+  const nick = ctx.connection.nick ?? '*';
+  effects.push(
+    Effect.send(ctx.connId, [{ text: `:${ctx.serverName} 324 ${nick} ${state.name} ${modeStr}` }]),
+  );
+  return { state, effects };
+}
+
+/** Builds the modestring + args for a 324 reply. */
+function buildReadModeString(state: ChannelState): string {
+  let modeStr = '+';
+  const args: string[] = [];
+  for (const letter of BOOLEAN_LETTER_ORDER) {
+    const field = BOOLEAN_LETTERS[letter];
+    if (field !== undefined && state.modes[field]) modeStr += letter;
+  }
+  if (state.modes.key !== undefined) {
+    modeStr += 'k';
+    args.push(state.modes.key);
+  }
+  if (state.modes.limit !== undefined) {
+    modeStr += 'l';
+    args.push(String(state.modes.limit));
+  }
+  if (args.length === 0) return modeStr;
+  return `${modeStr} ${args.join(' ')}`;
+}
+
+/** Emits `367` per ban mask then `368`. */
+function listBans(
+  state: ChannelState,
+  ctx: Ctx,
+  effects: EffectType[],
+): { state: ChannelState; effects: EffectType[] } {
+  emitBanList(state, ctx, effects);
+  return { state, effects };
+}
+
+function emitBanList(state: ChannelState, ctx: Ctx, effects: EffectType[]): void {
+  const nick = ctx.connection.nick ?? '*';
+  for (const mask of state.banMasks) {
+    effects.push(
+      Effect.send(ctx.connId, [{ text: `:${ctx.serverName} 367 ${nick} ${state.name} ${mask}` }]),
+    );
+  }
+  effects.push(
+    Effect.send(ctx.connId, [
+      { text: `:${ctx.serverName} 368 ${nick} ${state.name} :End of Channel Ban List` },
+    ]),
+  );
+}
+
+// ============================================================================
+// User MODE
+// ============================================================================
+
+/** User-mode letters → field on {@link UserModes}. */
+const USER_MODE_LETTERS: Readonly<Record<string, keyof ConnectionState['userModes']>> = {
+  i: 'invisible',
+  w: 'wallops',
+  s: 'serverNotices',
+  o: 'oper',
+};
+
+/** User-mode letters in canonical 221 output order. */
+const USER_MODE_LETTER_ORDER = ['i', 'w', 's', 'o'] as const;
+
+/**
+ * Handles `MODE <nick> [<modestring>]`.
+ *
+ * Read form (`MODE <nick>` with no modestring): emits `221 RPL_UMODEIS`.
+ * Write form: mutates `state.userModes` and emits a `MODE` echo to the
+ * connection. `+o` is rejected with `481 ERR_NOPRIVILEGES` because oper is
+ * granted via the OPER command, not via user MODE.
+ *
+ * RFC 501/502: clients may only change their own user modes. A target nick
+ * that does not match the connection's own nick yields `502`.
+ */
+export const userModeReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const target = msg.params[0];
+  if (target === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'MODE'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Target must be the caller's own nick (case-insensitive).
+  const myNick = state.nick;
+  if (myNick === undefined || lowerNick(target) !== lowerNick(myNick)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_USERSDONTMATCH, 'Cannot change mode for other users'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Read form.
+  const modestring = msg.params[1];
+  if (modestring === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        { text: `:${ctx.serverName} 221 ${myNick} ${buildUserModeString(state)}` },
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Write form.
+  const applied: AppliedMode[] = [];
+  let sign: '+' | '-' = '+';
+  for (const ch of modestring) {
+    if (ch === '+') {
+      sign = '+';
+      continue;
+    }
+    if (ch === '-') {
+      sign = '-';
+      continue;
+    }
+
+    const field = USER_MODE_LETTERS[ch];
+    if (field === undefined) {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_UMODEUNKNOWNFLAG, 'Unknown MODE flag'),
+        ]),
+      );
+      continue;
+    }
+
+    // +o via user MODE is reserved for OPER; reject.
+    if (ch === 'o' && sign === '+') {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericErr(
+            ctx,
+            Numerics.ERR_NOPRIVILEGES,
+            "Permission Denied - You're not an IRC operator",
+          ),
+        ]),
+      );
+      continue;
+    }
+
+    state.userModes[field] = sign === '+';
+    applied.push({ sign, letter: ch });
+  }
+
+  if (applied.length > 0) {
+    const hostmask = callerHostmask(state);
+    let modeStr = '';
+    let curSign: '+' | '-' | '' = '';
+    for (const op of applied) {
+      if (op.sign !== curSign) {
+        modeStr += op.sign;
+        curSign = op.sign;
+      }
+      modeStr += op.letter;
+    }
+    effects.push(Effect.send(ctx.connId, [{ text: `:${hostmask} MODE ${myNick} ${modeStr}` }]));
+  }
+
+  return { state, effects };
+};
+
+/** Builds the modestring for a 221 reply (always `+`-prefixed). */
+function buildUserModeString(state: ConnectionState): string {
+  let modeStr = '+';
+  for (const letter of USER_MODE_LETTER_ORDER) {
+    const field = USER_MODE_LETTERS[letter];
+    if (field !== undefined && state.userModes[field]) modeStr += letter;
+  }
+  return modeStr;
+}