serverless-ircd 0.1.0

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

@@ -0,0 +1,309 @@
+/**
+ * Pure reducer for the IRC `JOIN` command.
+ *
+ * PLAN §2.1 location-of-authority: JOIN runs in the Channel entity. The
+ * reducer's `state` argument is the channel's authoritative state; the
+ * joiner's identity is read from `ctx.connection`. Mutations to both
+ * `state.members` (the roster) and `ctx.connection.joinedChannels` (the
+ * connection's joined list) happen in place — the actor layer persists both.
+ *
+ * Multi-channel JOIN (`JOIN #a,#b k1,k2`) is split by the actor layer;
+ * this reducer handles one channel per invocation.
+ *
+ * `JOIN 0` (legacy "leave all channels") is routed by the actor layer to
+ * {@link handleJoinZero}, which emits PART-like effects for every joined
+ * channel.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { wrapBatch } from '../protocol/batch.js';
+import { Numerics } from '../protocol/numerics.js';
+import { type ChanName, type ChannelState, prefixOf } from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/**
+ * RFC 1459/2812 channel-name grammar. The first character must be a channel
+ * prefix (`#` or `&`); the rest may be any printable char except space, comma,
+ * or colon (which all carry protocol meaning).
+ */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+/**
+ * Returns true iff `name` matches the IRC channel-name grammar and is within
+ * the configured length cap.
+ */
+export function isValidChannelName(name: string, maxLen: number): boolean {
+  if (name.length === 0 || name.length > maxLen) return false;
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/**
+ * Returns the 353 NAMES sigil for a channel given its modes:
+ * `@` for `+p` (private), `*` for `+s` (secret), `=` otherwise (public).
+ *
+ * `+p` wins over `+s` when both are set (per RFC 2812 §3.2.4 — private is the
+ * stronger visibility hint for NAMES display).
+ */
+function namesSigil(state: ChannelState): string {
+  if (state.modes.private) return '@';
+  if (state.modes.secret) return '*';
+  return '=';
+}
+
+/** Builds the space-separated NAMES list with mode prefixes for a channel. */
+function buildNamesList(state: ChannelState): string {
+  const names: string[] = [];
+  for (const entry of state.members.values()) {
+    names.push(prefixOf(entry) + entry.nick);
+  }
+  return names.join(' ');
+}
+
+/**
+ * Formats a single numeric error line addressed to the connection's current
+ * nick (or `*` when unregistered). Optional `middle` is emitted before the
+ * trailing `:`-prefixed text.
+ */
+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(' ') };
+}
+
+/**
+ * Returns true iff `hostmask` matches the IRC ban mask `mask`. Masks use
+ * `*` (zero or more chars) and `?` (one char) wildcards; comparison is
+ * case-insensitive.
+ */
+function matchesBanMask(mask: string, hostmask: string): boolean {
+  let pattern = '^';
+  for (const ch of mask) {
+    if (ch === '*') {
+      pattern += '.*';
+    } else if (ch === '?') {
+      pattern += '.';
+    } else if (/[A-Za-z0-9]/.test(ch)) {
+      pattern += ch;
+    } else {
+      pattern += `\\${ch}`;
+    }
+  }
+  pattern += '$';
+  return new RegExp(pattern, 'i').test(hostmask);
+}
+
+/**
+ * Returns the hostmask string for the connection, falling back to the bare
+ * nick (or `?` when the connection has no nick yet). Used as the JOIN/PART
+ * message source.
+ */
+function joinerHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Handles `JOIN <chan> [<key>]` for a single channel.
+ *
+ * Pre-condition: `state` is the authoritative ChannelState for the channel
+ * named in `msg.params[0]`. The actor layer creates an empty channel (via
+ * `createChannel`) if the channel does not yet exist, then invokes this
+ * reducer.
+ *
+ * Validation order (deliberate): missing-param → invalid-name →
+ * already-on-channel (silent no-op) → max-channels → ban → invite-only →
+ * limit → key.
+ */
+export const joinReducer: 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', 'JOIN'),
+      ]),
+    );
+    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 };
+  }
+
+  // Already on the channel: silent no-op (RFC: re-joining is a no-op).
+  if (state.members.has(ctx.connId)) {
+    return { state, effects };
+  }
+
+  // Max-channels limit. Counts every channel the connection currently holds;
+  // the already-on-channel check above ensures we don't double-count the
+  // target when the actor layer hasn't pre-checked membership.
+  if (ctx.connection.joinedChannels.size >= ctx.serverConfig.maxChannelsPerUser) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_TOOMANYCHANNELS, 'You have joined too many channels', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const hostmask = joinerHostmask(ctx.connection);
+
+  // Ban check.
+  if (state.banMasks.size > 0) {
+    for (const mask of state.banMasks) {
+      if (matchesBanMask(mask, hostmask)) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_BANNEDFROMCHAN, 'Cannot join channel (+b)', rawName),
+          ]),
+        );
+        return { state, effects };
+      }
+    }
+  }
+
+  // Invite-only check. pendingInvites stores lowercased nicks.
+  const myNick = ctx.connection.nick;
+  const invited = myNick !== undefined && state.pendingInvites.has(myNick.toLowerCase());
+  if (state.modes.inviteOnly && !invited) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_INVITEONLYCHAN, 'Cannot join channel (+i)', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Limit check.
+  if (state.modes.limit !== undefined && state.members.size >= state.modes.limit) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_CHANNELISFULL, 'Cannot join channel (+l)', rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Key check.
+  if (state.modes.key !== undefined) {
+    const supplied = msg.params[1];
+    if (supplied !== state.modes.key) {
+      effects.push(
+        Effect.send(ctx.connId, [
+          numericErr(ctx, Numerics.ERR_BADCHANNELKEY, 'Cannot join channel (+k)', rawName),
+        ]),
+      );
+      return { state, effects };
+    }
+  }
+
+  // All checks passed: add to roster. First joiner gets op per RFC 2812.
+  const isFirst = state.members.size === 0;
+  state.members.set(ctx.connId, {
+    conn: ctx.connId,
+    nick: ctx.connection.nick ?? '?',
+    op: isFirst,
+    voice: false,
+  });
+
+  // Pending invite is consumed on a successful join.
+  if (myNick !== undefined) state.pendingInvites.delete(myNick.toLowerCase());
+
+  // Track the channel on the connection's joined set (cross-authority).
+  ctx.connection.joinedChannels.add(state.nameLower);
+
+  // Mirror the roster addition to the runtime's channel authority. In
+  // the in-memory runtime the actor's `state` IS the authoritative
+  // state, so this is a redundant idempotent update; in distributed
+  // runtimes (CF ChannelDO) this is the only path that mutates the
+  // authoritative roster, so subsequent broadcasts reach the new member.
+  effects.push(
+    Effect.applyChannelDelta(state.name, {
+      memberships: [
+        {
+          type: 'add',
+          conn: ctx.connId,
+          nick: ctx.connection.nick ?? '?',
+          op: isFirst,
+        },
+      ],
+    }),
+  );
+
+  const legacyJoin: RawLine = { text: `:${hostmask} JOIN ${state.name}` };
+  const realname = ctx.connection.realname;
+  if (realname !== undefined) {
+    const account = ctx.connection.account ?? '_';
+    const extendedJoin: RawLine = {
+      text: `:${hostmask} JOIN ${state.name} ${account} :${realname}`,
+    };
+    effects.push(
+      Effect.broadcast(state.name, [legacyJoin], undefined, 'extended-join', [extendedJoin]),
+    );
+  } else {
+    effects.push(Effect.broadcast(state.name, [legacyJoin]));
+  }
+
+  // NAMES list + end-of-names to the joiner only.
+  const nick = ctx.connection.nick ?? '*';
+  const sigil = namesSigil(state);
+  const names = buildNamesList(state);
+  const chanName = state.name;
+  const namesLines: RawLine[] = [
+    { text: `:${ctx.serverName} 353 ${nick} ${sigil} ${chanName} :${names}` },
+    { text: `:${ctx.serverName} 366 ${nick} ${chanName} :End of /NAMES list.` },
+  ];
+
+  // IRCv3 batch: wrap the joiner's NAMES reply when the joiner negotiated it.
+  const lines = ctx.connection.caps.has('batch')
+    ? wrapBatch(namesLines, ctx.ids.batchId(), 'join')
+    : namesLines;
+
+  effects.push(Effect.send(ctx.connId, lines));
+
+  return { state, effects };
+};
+
+/**
+ * Handles the legacy `JOIN 0` form, which parts the connection from every
+ * channel they currently occupy. The actor layer routes `JOIN 0` to this
+ * function instead of {@link joinReducer}.
+ *
+ * Emits, for each joined channel:
+ *   - `Broadcast(PART)` to the channel (including the parting connection,
+ *     matching PART semantics — clients expect the echo).
+ *   - `ApplyChannelDelta` removing the connection from the roster.
+ *
+ * Also clears `ctx.connection.joinedChannels`.
+ */
+export function handleJoinZero(ctx: Ctx): EffectType[] {
+  const effects: EffectType[] = [];
+  const hostmask = joinerHostmask(ctx.connection);
+
+  for (const chan of ctx.connection.joinedChannels) {
+    const chanName = chan as ChanName;
+    effects.push(Effect.broadcast(chanName, [{ text: `:${hostmask} PART ${chanName}` }]));
+    effects.push(
+      Effect.applyChannelDelta(chanName, {
+        memberships: [{ type: 'remove', conn: ctx.connId }],
+      }),
+    );
+  }
+
+  ctx.connection.joinedChannels.clear();
+  return effects;
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Pure reducer for the IRC `KICK` command.
+ *
+ * PLAN §2.1 location-of-authority: KICK runs in the Channel entity. The
+ * reducer's `state` argument is the channel's authoritative state; the
+ * kicker's identity is read from `ctx.connection`. Mutations to the roster
+ * are expressed as a `ApplyChannelDelta` effect (the actor layer additionally
+ * removes the channel from the kicked user's `joinedChannels` set — that
+ * cross-authority mutation is the actor's job, not the reducer's, since the
+ * reducer has no handle on the target's `ConnectionState`).
+ *
+ * Multi-channel KICK is not part of the RFC grammar; this reducer handles
+ * one channel per invocation.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ChannelState } 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 validation mirrors JOIN: same grammar, same length cap. */
+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);
+}
+
+/**
+ * Formats a single numeric error line addressed to the connection's current
+ * nick (or `*` when unregistered). Optional `middle` is emitted before the
+ * trailing `:`-prefixed text.
+ */
+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(' ') };
+}
+
+/**
+ * Returns the hostmask string for the connection, falling back to the bare
+ * nick (or `?` when the connection has no nick yet). Used as the KICK
+ * message source.
+ */
+function kickerHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Lowercases a nick using ASCII case folding (good enough for v1; rfc1459
+ * case mapping lands with the isupport `CASEMAPPING` token).
+ */
+function lowerNick(nick: string): string {
+  return nick.toLowerCase();
+}
+
+/**
+ * Handles `KICK <chan> <user> [:reason]`.
+ *
+ * Pre-condition: `state` is the authoritative ChannelState for the channel
+ * named in `msg.params[0]`.
+ *
+ * Validation order (deliberate): missing-channel → missing-target →
+ * invalid-name → kicker-not-on-channel → kicker-not-op →
+ * target-not-on-channel → success.
+ */
+export const kickReducer: Reducer<ChannelState> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  const rawName = msg.params[0];
+  const targetNick = msg.params[1];
+
+  if (rawName === undefined || targetNick === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'KICK'),
+      ]),
+    );
+    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 };
+  }
+
+  // Kicker must be on the channel to kick anyone.
+  const kickerEntry = state.members.get(ctx.connId);
+  if (kickerEntry === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NOTONCHANNEL, "You're not on that channel", rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Kicker must be an op.
+  if (!kickerEntry.op) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_CHANOPRIVSNEEDED, "You're not channel operator", rawName),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // Find the target by nick (case-insensitive). IRC nicks fold by ASCII.
+  const targetLower = lowerNick(targetNick);
+  let targetConnId: string | undefined;
+  for (const entry of state.members.values()) {
+    if (lowerNick(entry.nick) === targetLower) {
+      targetConnId = entry.conn;
+      break;
+    }
+  }
+  if (targetConnId === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(
+          ctx,
+          Numerics.ERR_USERNOTINCHANNEL,
+          'They are not on that channel',
+          `${targetNick} ${rawName}`,
+        ),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  // All checks passed: build the KICK line and remove the target.
+  const hostmask = kickerHostmask(ctx.connection);
+  const reason = msg.params[2];
+  const line: RawLine =
+    reason && reason.length > 0
+      ? { text: `:${hostmask} KICK ${state.name} ${targetNick} :${reason}` }
+      : { text: `:${hostmask} KICK ${state.name} ${targetNick}` };
+  effects.push(Effect.broadcast(state.name, [line]));
+
+  // Drop the target from the roster (the actor layer persists the delta and
+  // also removes the channel from the target's joinedChannels set).
+  state.members.delete(targetConnId);
+  effects.push(
+    Effect.applyChannelDelta(state.name, {
+      memberships: [{ type: 'remove', conn: targetConnId }],
+    }),
+  );
+
+  return { state, effects };
+};

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

@@ -0,0 +1,126 @@
+/**
+ * Pure reducer for the IRC `LIST` command.
+ *
+ * PLAN §2.1 location-of-authority: LIST reads channel state across the
+ * deployment but does not mutate it, so the reducer's `state` argument is
+ * the actor-supplied list of {@link ChanSnapshot} entries; the requester
+ * is `ctx.connection`.
+ *
+ * Wire format (RFC 2812 §3.2.7):
+ *   - `321 RPL_LISTSTART`  — `:<server> 321 <nick> Channel :Users  Name`
+ *   - `322 RPL_LIST`       — `:<server> 322 <nick> <chan> <#users> :<topic>`
+ *   - `323 RPL_LISTEND`    — `:<server> 323 <nick> :End of /LIST`
+ *
+ * Visibility rules (ticket spec):
+ *   - Secret (`+s`) channels are hidden from non-members.
+ *   - Membership is checked against `chan.members` using `ctx.connId`.
+ *
+ * Thundering-herd mitigation (PLAN §10 risk): the number of `322` entries
+ * is capped at `serverConfig.maxListEntries`. The cap applies after
+ * visibility filtering, so a member listing their own +s channels still
+ * sees them up to the cap.
+ *
+ * The actor layer is responsible for assembling the channel list to
+ * enumerate; this reducer performs no I/O. `LIST <chan>{,<chan>}` narrows
+ * the result to the requested channels (still subject to visibility and
+ * the cap).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ChanSnapshot } from '../state/channel.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 true iff the requester is permitted to see `chan` in LIST output.
+ * Secret channels require membership; everything else is public.
+ */
+function isVisible(chan: ChanSnapshot, ctx: Ctx): boolean {
+  if (!chan.modes.secret) return true;
+  return chan.members.has(ctx.connId);
+}
+
+/** Formats a single `322 RPL_LIST` line for `chan`. */
+function listLine(chan: ChanSnapshot, ctx: Ctx, nick: string): RawLine {
+  const codeStr = Numerics.RPL_LIST.toString().padStart(3, '0');
+  const topic = chan.topic?.text ?? '';
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${nick} ${chan.name} ${chan.members.size} :${topic}`,
+  };
+}
+
+/** Splits a comma-separated channel-list param into trimmed tokens. */
+function splitChannelParam(raw: string): string[] {
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Handles `LIST [<chan>{,<chan>}]`.
+ *
+ * Validation order (deliberate): visibility filter → cap → format.
+ * Unknown / invalid / non-existent channels in an explicit list are
+ * silently skipped (RFC 2812 §3.2.7).
+ */
+export const listReducer: Reducer<ChanSnapshot[]> = (state, msg, ctx) => {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+  const nick = ctx.connection.nick ?? '*';
+
+  const codeStr321 = Numerics.RPL_LISTSTART.toString().padStart(3, '0');
+  const codeStr323 = Numerics.RPL_LISTEND.toString().padStart(3, '0');
+
+  effects.push(
+    Effect.send(ctx.connId, [
+      { text: `:${ctx.serverName} ${codeStr321} ${nick} Channel :Users  Name` },
+    ]),
+  );
+
+  const max = ctx.serverConfig.maxListEntries;
+  const lines: RawLine[] = [];
+
+  const rawParam = msg.params[0];
+  if (rawParam === undefined || rawParam.trim().length === 0) {
+    for (const chan of state) {
+      if (lines.length >= max) break;
+      if (!isVisible(chan, ctx)) continue;
+      lines.push(listLine(chan, ctx, nick));
+    }
+  } else {
+    const requested = splitChannelParam(rawParam);
+    const seen = new Set<string>();
+    for (const rawName of requested) {
+      if (lines.length >= max) break;
+      if (!isValidChannelName(rawName, ctx.serverConfig.channelLen)) continue;
+      const lower = rawName.toLowerCase();
+      if (seen.has(lower)) continue;
+      seen.add(lower);
+      const chan = state.find((c) => c.nameLower === lower);
+      if (chan === undefined) continue;
+      if (!isVisible(chan, ctx)) continue;
+      lines.push(listLine(chan, ctx, nick));
+    }
+  }
+
+  if (lines.length > 0) {
+    effects.push(Effect.send(ctx.connId, lines));
+  }
+
+  effects.push(
+    Effect.send(ctx.connId, [{ text: `:${ctx.serverName} ${codeStr323} ${nick} :End of /LIST` }]),
+  );
+
+  return { state, effects };
+};