serverless-ircd 0.1.0

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

@@ -0,0 +1,256 @@
+/**
+ * Pure reducers for the IRC `PRIVMSG` and `NOTICE` commands.
+ *
+ * PLAN §2.1 location-of-authority splits these by target type:
+ *
+ *   - **Channel target** (`PRIVMSG #foo :text`): the channel is authoritative
+ *     for `+n`/`+m`/`+b`, so the reducer's `state` is the channel's
+ *     {@link ChannelState}. Sender identity is `ctx.connection`. Emits a
+ *     single `Broadcast` effect (excluding the sender; `echo-message` echo
+ *     handled elsewhere).
+ *   - **User target** (`PRIVMSG bob :text`): the connection is authoritative
+ *     for the sender's identity, so the reducer's `state` is the sender's
+ *     {@link ConnectionState}. Emits a `SendToNick` effect that the dispatch
+ *     layer resolves via `lookupNick`; if the recipient is offline the
+ *     optional `notFoundLines` (PRIVMSG only) carries the `401` back to the
+ *     sender.
+ *
+ * Multi-target commands (`PRIVMSG #a,#b` / `PRIVMSG a,b`) are split by the
+ * actor layer, which also enforces `maxTargetsPerCommand`;
+ * each reducer handles exactly one target per invocation.
+ *
+ * RFC-critical: **`NOTICE` MUST NEVER produce a numeric error reply.** All
+ * rejection paths short-circuit with an empty effect list for NOTICE.
+ */
+
+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 grammar; mirrors {@link isValidChannelName} in `join.ts`. */
+const CHANNEL_NAME_RE = /^[#&][^\s,:]+$/u;
+
+/** Returns true iff `name` looks like a channel target (vs. a nick target). */
+function isChannelTarget(name: string): boolean {
+  return CHANNEL_NAME_RE.test(name);
+}
+
+/**
+ * Returns true iff `hostmask` matches the IRC ban mask `mask`. Identical to
+ * the implementation in `join.ts`; duplicated to keep the channel-message
+ * path self-contained (ban-matching consolidation is planned).
+ */
+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);
+}
+
+/**
+ * Formats a numeric error line addressed to the connection's current nick
+ * (or `*` when unregistered).
+ */
+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(' ') };
+}
+
+/** Resolves the sender's hostmask, falling back to nick then `?`. */
+function senderHostmask(conn: ConnectionState): string {
+  return hostmaskOf(conn) ?? conn.nick ?? '?';
+}
+
+/**
+ * Returns true iff `entry` may speak on a moderated channel: ops and voiced
+ * members pass; everyone else is blocked.
+ */
+function maySpeakOnModerated(entry: { op: boolean; voice: boolean } | undefined): boolean {
+  if (entry === undefined) return false;
+  return entry.op || entry.voice;
+}
+
+/** Command flavor: PRIVMSG surfaces errors; NOTICE is silent. */
+type MessageCommand = 'PRIVMSG' | 'NOTICE';
+
+/**
+ * Builds a channel-target reducer for one of PRIVMSG / NOTICE. The shared
+ * body validates params, checks `+n` / `+m` / `+b`, and emits `Broadcast`.
+ */
+function buildChannelReducer(command: MessageCommand): Reducer<ChannelState> {
+  return (state, msg, ctx) => {
+    ctx.connection.lastSeen = ctx.clock.now();
+
+    const effects: EffectType[] = [];
+    const silent = command === 'NOTICE';
+
+    const target = msg.params[0];
+    const text = msg.params[1];
+
+    if (target === undefined) {
+      if (!silent) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_NORECIPIENT, `No recipient given (${command})`),
+          ]),
+        );
+      }
+      return { state, effects };
+    }
+
+    if (text === undefined || text.length === 0) {
+      if (!silent) {
+        effects.push(
+          Effect.send(ctx.connId, [numericErr(ctx, Numerics.ERR_NOTEXTTOSEND, 'No text to send')]),
+        );
+      }
+      return { state, effects };
+    }
+
+    const senderEntry = state.members.get(ctx.connId);
+    const hostmask = senderHostmask(ctx.connection);
+
+    // +n (no external messages): sender must be a member.
+    if (state.modes.noExternal && senderEntry === undefined) {
+      if (!silent) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_CANNOTSENDTOCHAN, 'Cannot send to channel', state.name),
+          ]),
+        );
+      }
+      return { state, effects };
+    }
+
+    // +m (moderated): sender must be op or voiced.
+    if (state.modes.moderated && !maySpeakOnModerated(senderEntry)) {
+      if (!silent) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_CANNOTSENDTOCHAN, 'Cannot send to channel', state.name),
+          ]),
+        );
+      }
+      return { state, effects };
+    }
+
+    // +b (ban): sender's hostmask must not match any ban mask.
+    if (state.banMasks.size > 0) {
+      for (const mask of state.banMasks) {
+        if (matchesBanMask(mask, hostmask)) {
+          if (!silent) {
+            effects.push(
+              Effect.send(ctx.connId, [
+                numericErr(
+                  ctx,
+                  Numerics.ERR_CANNOTSENDTOCHAN,
+                  'Cannot send to channel',
+                  state.name,
+                ),
+              ]),
+            );
+          }
+          return { state, effects };
+        }
+      }
+    }
+
+    // All checks passed: broadcast to the channel, excluding the sender.
+    const line: RawLine = { text: `:${hostmask} ${command} ${state.name} :${text}` };
+    effects.push(Effect.broadcast(state.name, [line], ctx.connId));
+
+    // IRCv3 echo-message: echo the same line back to the sender, after
+    // the broadcast effect so clients observe their own message last.
+    if (ctx.connection.caps.has('echo-message')) {
+      effects.push(Effect.send(ctx.connId, [line]));
+    }
+
+    return { state, effects };
+  };
+}
+
+/**
+ * Builds a user-target reducer for one of PRIVMSG / NOTICE. The shared body
+ * validates params and emits a `SendToNick` effect. PRIVMSG attaches a
+ * `401` fallback for offline recipients; NOTICE omits the fallback entirely.
+ */
+function buildUserReducer(command: MessageCommand): Reducer<ConnectionState> {
+  return (state, msg, ctx) => {
+    state.lastSeen = ctx.clock.now();
+
+    const effects: EffectType[] = [];
+    const silent = command === 'NOTICE';
+
+    const target = msg.params[0];
+    const text = msg.params[1];
+
+    if (target === undefined) {
+      if (!silent) {
+        effects.push(
+          Effect.send(ctx.connId, [
+            numericErr(ctx, Numerics.ERR_NORECIPIENT, `No recipient given (${command})`),
+          ]),
+        );
+      }
+      return { state, effects };
+    }
+
+    if (text === undefined || text.length === 0) {
+      if (!silent) {
+        effects.push(
+          Effect.send(ctx.connId, [numericErr(ctx, Numerics.ERR_NOTEXTTOSEND, 'No text to send')]),
+        );
+      }
+      return { state, effects };
+    }
+
+    const hostmask = senderHostmask(state);
+    const line: RawLine = { text: `:${hostmask} ${command} ${target} :${text}` };
+    const notFoundLines = silent
+      ? undefined
+      : [numericErr(ctx, Numerics.ERR_NOSUCHNICK, 'No such nick/channel', target)];
+
+    effects.push(Effect.sendToNick(target, ctx.connId, [line], notFoundLines));
+
+    // IRCv3 echo-message: echo the same line back to the sender, after
+    // the SendToNick effect so clients observe their own message last.
+    if (ctx.connection.caps.has('echo-message')) {
+      effects.push(Effect.send(ctx.connId, [line]));
+    }
+
+    return { state, effects };
+  };
+}
+
+/** Reducer for `PRIVMSG <channel> :<text>`. Authority: ChannelState. */
+export const privmsgChannelReducer: Reducer<ChannelState> = buildChannelReducer('PRIVMSG');
+
+/** Reducer for `NOTICE <channel> :<text>`. Authority: ChannelState. */
+export const noticeChannelReducer: Reducer<ChannelState> = buildChannelReducer('NOTICE');
+
+/** Reducer for `PRIVMSG <nick> :<text>`. Authority: sender's ConnectionState. */
+export const privmsgUserReducer: Reducer<ConnectionState> = buildUserReducer('PRIVMSG');
+
+/** Reducer for `NOTICE <nick> :<text>`. Authority: sender's ConnectionState. */
+export const noticeUserReducer: Reducer<ConnectionState> = buildUserReducer('NOTICE');
+
+/** Exported for the actor layer so it knows which reducer a target string routes to. */
+export { isChannelTarget };

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

@@ -0,0 +1,70 @@
+/**
+ * Pure reducer for the IRC `QUIT` command.
+ *
+ * Per PLAN §2.1 this runs in the Connection entity. It does not own the
+ * channel rosters or the nick registry, so every mutation is expressed as
+ * an effect the runtime interprets:
+ *
+ *   - `Broadcast(QUIT)` to each joined channel (excluding the quitter,
+ *     who is being disconnected anyway).
+ *   - `ApplyChannelDelta` removing the connection from each channel roster.
+ *   - `ReleaseNick` for the reserved nick (only if registered).
+ *   - `Disconnect` to close the transport.
+ *
+ * The reducer is intentionally idempotent for never-registered connections:
+ * with no nick and no joined channels there is nothing to broadcast or
+ * release, so the only effect is `Disconnect`.
+ */
+
+import { Effect } from '../effects.js';
+import type { RawLine } from '../effects.js';
+import type { ChanName } from '../state/channel.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Reducer } from '../types.js';
+
+/**
+ * Handles `QUIT [:reason]`.
+ *
+ * Reason resolution: a non-empty `params[0]` is used verbatim; anything
+ * else (no params, or an explicit empty trailing) falls back to
+ * `ctx.serverConfig.quitMessage`.
+ */
+export const quitReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects = [];
+
+  const nick = state.nick;
+  if (nick !== undefined) {
+    const hostmask = hostmaskOf(state);
+    const reason = pickReason(msg.params, ctx.serverConfig.quitMessage);
+    const line: RawLine = { text: `:${hostmask} QUIT :${reason}` };
+
+    for (const chan of state.joinedChannels) {
+      effects.push(Effect.broadcast(chan as ChanName, [line], ctx.connId));
+    }
+    for (const chan of state.joinedChannels) {
+      effects.push(
+        Effect.applyChannelDelta(chan as ChanName, {
+          memberships: [{ type: 'remove', conn: ctx.connId }],
+        }),
+      );
+    }
+    effects.push(Effect.releaseNick(nick));
+  }
+
+  effects.push(Effect.disconnect(ctx.connId));
+
+  return { state, effects };
+};
+
+/**
+ * Returns the provided reason if it is a non-empty string, otherwise the
+ * configured default. Treats `QUIT` and `QUIT :` identically (per modern
+ * client behavior).
+ */
+function pickReason(params: string[], fallback: string): string {
+  const supplied = params[0];
+  return supplied && supplied.length > 0 ? supplied : fallback;
+}

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

@@ -0,0 +1,251 @@
+/**
+ * Pure reducers for the IRC registration handshake: `NICK`, `USER`, `PASS`.
+ *
+ * PLAN §2.1 location-of-authority: registration runs in the Connection
+ * entity. These reducers handle the pre-`CAP` handshake (CAP negotiation
+ * itself arrives in the CAP layer and calls back into {@link emitWelcomeIfReady}
+ * on `CAP END`).
+ *
+ * Nick collision (`433 ERR_NICKNAMEINUSE`) is detected by the Registry
+ * entity when it interprets the `ReserveNick` / `ChangeNick` effect; the
+ * reducer cannot observe that purely and so emits the reservation
+ * optimistically. The actor layer surfaces the collision
+ * numeric on `{ ok: false }`.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+import { generateIsupport } from './isupport.js';
+
+/**
+ * Server version reported in `002` / `004`. Placeholder until a config-driven
+ * version lands.
+ */
+const SERVER_VERSION = '0.1.0';
+
+/** "Created" text for `003 RPL_CREATED`. Placeholder. */
+const CREATED_TEXT = 'Phase 1';
+
+/** User mode letters for `004 RPL_MYINFO` (invisible, oper, wallops, server-notices). */
+const USER_MODES_004 = 'iosw';
+
+/** Channel mode letters for `004 RPL_MYINFO` (matches PLAN §3 channel mode set). */
+const CHANNEL_MODES_004 = 'biklmnstp';
+
+/**
+ * RFC 1459/2812 nickname grammar. First char must be a letter; subsequent
+ * chars may be letters, digits, underscore, hyphen, or the "special" set
+ * `[]\`^{|}`.
+ */
+const NICK_GRAMMAR_RE = /^[A-Za-z][\w\-\[\]\\`^{|}]*$/u;
+
+/**
+ * Returns true iff `nick` matches the IRC nick grammar and is within the
+ * configured length cap.
+ */
+export function isValidNick(nick: string, maxLen: number): boolean {
+  if (nick.length === 0 || nick.length > maxLen) return false;
+  return NICK_GRAMMAR_RE.test(nick);
+}
+
+/**
+ * Builds the welcome numeric block emitted once registration completes:
+ * `001`–`005` (with `005` as a placeholder) followed by
+ * the `375`/`372`/`376` MOTD placeholders (real MOTD content via the
+ * `MotdProvider` port).
+ *
+ * Caller guarantees `state.nick` and `state.user` are set.
+ */
+export function buildWelcomeLines(state: ConnectionState, ctx: Ctx): RawLine[] {
+  const prefix = `:${ctx.serverName}`;
+  const nick = state.nick;
+  if (nick === undefined) return [];
+  // hostmaskOf returns string|undefined, but after the guard above nick is
+  // always defined, so hostmaskOf always returns at least `nick`. The cast
+  // avoids a dead `??` branch that v8 coverage cannot satisfy.
+  const hostmask = hostmaskOf(state) as string;
+
+  return [
+    { text: `${prefix} 001 ${nick} :Welcome to the ${ctx.networkName} IRC Network, ${hostmask}` },
+    {
+      text: `${prefix} 002 ${nick} :Your host is ${ctx.serverName}, running version ${SERVER_VERSION}`,
+    },
+    { text: `${prefix} 003 ${nick} :This server was created in ${CREATED_TEXT}` },
+    {
+      text: `${prefix} 004 ${nick} ${ctx.serverName} ${SERVER_VERSION} ${USER_MODES_004} ${CHANNEL_MODES_004}`,
+    },
+    // 005 RPL_ISUPPORT — real tokens generated from serverConfig.
+    ...generateIsupport(ctx.serverConfig, state.caps, nick),
+    // MOTD placeholders — filled via MotdProvider elsewhere.
+    { text: `${prefix} 375 ${nick} :- ${ctx.serverName} Message of the day -` },
+    { text: `${prefix} 372 ${nick} :- MOTD placeholder` },
+    { text: `${prefix} 376 ${nick} :End of MOTD command` },
+  ];
+}
+
+/**
+ * Attempts to finalize registration: if both `nick` and `user` are present
+ * and the connection is not yet registered, transitions `state.registration`
+ * to `'registered'` and returns a `Send` effect carrying the welcome block.
+ * Otherwise returns `null` and leaves state untouched.
+ *
+ * Reused by the CAP `END` handler.
+ */
+export function emitWelcomeIfReady(state: ConnectionState, ctx: Ctx): EffectType | null {
+  if (state.registration === 'registered') return null;
+  if (state.nick === undefined || state.user === undefined) return null;
+  if (state.capNegotiating) return null;
+  state.registration = 'registered';
+  return Effect.send(ctx.connId, buildWelcomeLines(state, ctx));
+}
+
+/**
+ * Formats a single numeric error line addressed to the connection's current
+ * nick (or `*` when unregistered). Optional `middle` param is emitted before
+ * the trailing `:`-prefixed text — used for `432 <badnick>` and
+ * `461 <command>`.
+ */
+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(' ') };
+}
+
+/**
+ * Reducer for `NICK <nickname>`.
+ *
+ * Pre-registration: validates grammar, stashes the nick on the connection,
+ * emits `ReserveNick`, and attempts to complete registration.
+ *
+ * Post-registration: validates grammar, emits `ChangeNick` plus the
+ * `:oldhostmask NICK newnick` echo back to the client.
+ */
+export const nickReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  const effects: EffectType[] = [];
+  const nick = msg.params[0];
+
+  if (nick === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [numericErr(ctx, Numerics.ERR_NONICKNAMEGIVEN, 'No nickname given')]),
+    );
+    return { state, effects };
+  }
+
+  if (!isValidNick(nick, ctx.serverConfig.nickLen)) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_ERRONEUSNICKNAME, 'Erroneous nickname', nick),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  if (state.registration === 'registered') {
+    const oldNick = state.nick;
+    if (oldNick === undefined) {
+      return { state, effects };
+    }
+    // hostmaskOf is guaranteed non-undefined here because oldNick is defined.
+    const source = hostmaskOf(state) as string;
+    state.nick = nick;
+    effects.push(Effect.changeNick(ctx.connId, oldNick, nick));
+    effects.push(Effect.send(ctx.connId, [{ text: `:${source} NICK ${nick}` }]));
+    return { state, effects };
+  }
+
+  state.nick = nick;
+  if (state.registration === 'pre-registration') {
+    state.registration = 'registering';
+  }
+  effects.push(Effect.reserveNick(nick, ctx.connId));
+
+  const welcome = emitWelcomeIfReady(state, ctx);
+  if (welcome !== null) effects.push(welcome);
+
+  return { state, effects };
+};
+
+/**
+ * Reducer for `USER <user> <mode> <unused> :<realname>` (RFC 2812 form).
+ *
+ * Stores username (params[0]) and realname (params[3]); the historical
+ * mode/hostname/servername slots (params[1], params[2]) are ignored. If
+ * `NICK` has already been received, completes registration and emits the
+ * welcome block.
+ */
+export const userReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  const effects: EffectType[] = [];
+
+  if (state.registration === 'registered') {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_ALREADYREGISTRED, 'You may not reregister'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const user = msg.params[0];
+  const realname = msg.params[3];
+  if (user === undefined || realname === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'USER'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  state.user = user;
+  state.realname = realname;
+  if (state.registration === 'pre-registration') {
+    state.registration = 'registering';
+  }
+
+  const welcome = emitWelcomeIfReady(state, ctx);
+  if (welcome !== null) effects.push(welcome);
+
+  return { state, effects };
+};
+
+/**
+ * Reducer for `PASS <password>`.
+ *
+ * Only stashes the attempt as `state.passAttempt`. Actual server-password
+ * enforcement lives in the actor layer / security hardening
+ * since it requires comparing against the deployment's configured
+ * password, which the pure reducer does not see.
+ */
+export const passReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  const effects: EffectType[] = [];
+
+  if (state.registration === 'registered') {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_ALREADYREGISTRED, 'You may not reregister'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const password = msg.params[0];
+  if (password === undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericErr(ctx, Numerics.ERR_NEEDMOREPARAMS, 'Not enough parameters', 'PASS'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  state.passAttempt = password;
+
+  return { state, effects };
+};