serverless-ircd 0.2.0 → 0.4.0

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

@@ -0,0 +1,151 @@
+/**
+ * Pure reducer for the IRC `OPER` command.
+ *
+ * PLAN §2.1 location-of-authority: OPER runs in the Connection entity — it
+ * authenticates the caller against the deployment's configured operator
+ * credentials and, on success, grants the `o` user mode by setting
+ * `state.userModes.oper = true`. The reducer's `state` argument is the
+ * caller's authoritative {@link ConnectionState}.
+ *
+ * Oper is the *only* path that sets `userModes.oper`: a user `MODE +o` is
+ * hard-rejected with `481 ERR_NOPRIVILEGES` (see `mode.ts`). Once oper is
+ * granted here, the `RPL_WHOISOPERATOR` (313) branch of WHOIS and the `*`
+ * oper flag of WHO become reachable.
+ *
+ * Wire format (RFC 2812 §5.4.1, §4.1):
+ *   - `OPER <name> <password>` — authenticates and (on success) grants oper.
+ *   - `381 RPL_YOUREOPER`:
+ *     `:<server> 381 <nick> :You are now an IRC operator`
+ *   - `461 ERR_NEEDMOREPARAMS`:
+ *     `:<server> 461 <nick> OPER :Not enough parameters`
+ *   - `464 ERR_PASSWDMISMATCH`:
+ *     `:<server> 464 <nick> :Password Incorrect`
+ *   - `491 ERR_NOOPERHOST`:
+ *     `:<server> 491 <nick> :No O-lines for your host`
+ *
+ * Behaviour:
+ *   - Missing `<name>` or `<password>` → `461 ERR_NEEDMOREPARAMS`.
+ *   - Already an operator → graceful idempotent no-op that re-confirms with
+ *     `381` (no re-authentication required; the connection is already privy).
+ *   - No operator credentials configured (absent or empty) →
+ *     `491 ERR_NOOPERHOST`.
+ *   - Matching credential pair → grant oper, emit `381`.
+ *   - Wrong password / unknown name → `464 ERR_PASSWDMISMATCH`.
+ */
+
+import { Effect } from '../effects.js';
+import type { RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { OperCred } from '../types.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** Fixed text emitted for `381 RPL_YOUREOPER`. */
+const YOUREOPER_TRAILING_TEXT = 'You are now an IRC operator';
+
+/** Fixed text emitted for `464 ERR_PASSWDMISMATCH`. */
+const PASSWDMISMATCH_TRAILING_TEXT = 'Password Incorrect';
+
+/** Fixed text emitted for `491 ERR_NOOPERHOST`. */
+const NOOPERHOST_TRAILING_TEXT = 'No O-lines for your host';
+
+/** Fixed text emitted for `461 ERR_NEEDMOREPARAMS`. */
+const NEEDMOREPARAMS_TRAILING_TEXT = 'Not enough parameters';
+
+/**
+ * Returns true iff a credential pair in `creds` matches `name` / `password`
+ * exactly. Extracted as a pure helper so the match logic is testable in
+ * isolation and independent of connection state. Comparison is case
+ * sensitive and byte-exact (case-mapping is owned elsewhere).
+ */
+export function matchOperCred(
+  creds: ReadonlyArray<OperCred>,
+  name: string,
+  password: string,
+): boolean {
+  return creds.some((c) => c.user === name && c.password === password);
+}
+
+/**
+ * Handles `OPER <name> <password>`.
+ *
+ * Verifies the supplied pair against `serverConfig.operCreds` and, on
+ * success, grants the oper user mode. Emits the appropriate numeric reply
+ * in every branch. See the file header for the full decision table.
+ */
+export const operReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const name = msg.params[0];
+  const password = msg.params[1];
+
+  if (name === undefined || password === undefined) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NEEDMOREPARAMS, NEEDMOREPARAMS_TRAILING_TEXT, 'OPER'),
+        ]),
+      ],
+    };
+  }
+
+  // Already an operator: graceful idempotent re-confirm, no re-auth needed.
+  if (state.userModes.oper) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.RPL_YOUREOPER, YOUREOPER_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  const creds = ctx.serverConfig.operCreds;
+  if (creds === undefined || creds.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOOPERHOST, NOOPERHOST_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  if (matchOperCred(creds, name, password)) {
+    state.userModes.oper = true;
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.RPL_YOUREOPER, YOUREOPER_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  return {
+    state,
+    effects: [
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_PASSWDMISMATCH, PASSWDMISMATCH_TRAILING_TEXT),
+      ]),
+    ],
+  };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` line. The nick
+ * falls back to `*` when the connection has not yet registered one, matching
+ * the rest of the codebase's numeric formatting.
+ */
+function numericLine(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(' ') };
+}

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

@@ -52,6 +52,18 @@ export const quitReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
       );
     }
     effects.push(Effect.releaseNick(nick));
+    // Record the sign-off into nick history so WHOWAS can replay it. Only
+    // consulted when a NickHistoryStore is bound; absent → no-op.
+    if (ctx.history !== undefined) {
+      ctx.history.record({
+        nick,
+        connId: ctx.connId,
+        signoffTime: ctx.clock.now(),
+        ...(state.user !== undefined ? { username: state.user } : {}),
+        ...(state.host !== undefined ? { hostname: state.host } : {}),
+        ...(state.realname !== undefined ? { realname: state.realname } : {}),
+      });
+    }
   }
 
   effects.push(Effect.disconnect(ctx.connId));

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

@@ -14,6 +14,7 @@
  */
 
 import { cloakHost } from '../cloak.js';
+import { formatCreatedAt, resolveServerVersion } from '../config.js';
 import { Effect } from '../effects.js';
 import type { Effect as EffectType, RawLine } from '../effects.js';
 import { Numerics } from '../protocol/numerics.js';
@@ -21,15 +22,7 @@ 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.2.0';
-
-/** "Created" text for `003 RPL_CREATED`. Placeholder. */
-const CREATED_TEXT = 'Phase 1';
+import { buildMotdNumerics } from './motd-lines.js';
 
 /** User mode letters for `004 RPL_MYINFO` (invisible, oper, wallops, server-notices). */
 const USER_MODES_004 = 'iosw';
@@ -55,9 +48,9 @@ export function isValidNick(nick: string, maxLen: number): boolean {
 
 /**
  * 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).
+ * `001`–`005` (with `005` generated from the server config) followed by
+ * the MOTD numerics rendered from {@link Ctx.motd} — `375`/`372`×N/`376`
+ * for a configured MOTD, or `422 ERR_NOMOTD` when none is configured.
  *
  * Caller guarantees `state.nick` and `state.user` are set.
  */
@@ -69,22 +62,24 @@ export function buildWelcomeLines(state: ConnectionState, ctx: Ctx): RawLine[] {
   // 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;
+  const version = resolveServerVersion(ctx.serverConfig);
+  const created = formatCreatedAt(ctx.serverConfig.createdAt);
 
   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} 002 ${nick} :Your host is ${ctx.serverName}, running version ${version}`,
     },
-    { text: `${prefix} 003 ${nick} :This server was created in ${CREATED_TEXT}` },
+    { text: `${prefix} 003 ${nick} :This server was created in ${created}` },
     {
-      text: `${prefix} 004 ${nick} ${ctx.serverName} ${SERVER_VERSION} ${USER_MODES_004} ${CHANNEL_MODES_004}`,
+      text: `${prefix} 004 ${nick} ${ctx.serverName} ${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` },
+    // MOTD — rendered from the configured MotdProvider (375/372/376, or
+    // 422 ERR_NOMOTD when no MOTD is configured). Shares the exact rendering
+    // path with the standalone MOTD command.
+    ...buildMotdNumerics(ctx.serverName, nick, ctx.motd.lines()),
   ];
 }
 
@@ -213,6 +208,18 @@ export const nickReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
     }
     // hostmaskOf is guaranteed non-undefined here because oldNick is defined.
     const source = hostmaskOf(state) as string;
+    // Record the old nick into history so WHOWAS can replay it. Only
+    // consulted when a NickHistoryStore is bound; absent → no-op.
+    if (ctx.history !== undefined) {
+      ctx.history.record({
+        nick: oldNick,
+        connId: ctx.connId,
+        signoffTime: ctx.clock.now(),
+        ...(state.user !== undefined ? { username: state.user } : {}),
+        ...(state.host !== undefined ? { hostname: state.host } : {}),
+        ...(state.realname !== undefined ? { realname: state.realname } : {}),
+      });
+    }
     state.nick = nick;
     effects.push(Effect.changeNick(ctx.connId, oldNick, nick));
     effects.push(Effect.send(ctx.connId, [{ text: `:${source} NICK ${nick}` }]));

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

@@ -4,10 +4,13 @@
  * PLAN §2.1 location-of-authority: SASL runs in the Connection entity.
  * The reducer drives the multi-frame SASL exchange purely:
  *
- *   1. `AUTHENTICATE <MECH>` — selects a mechanism. `PLAIN` is supported and
- *      answers with `AUTHENTICATE +` (requesting the payload). `EXTERNAL` is
- *      recognized but stubbed to `904` until mTLS lands. Anything else gets
- *      `908 ERR_SASLMECHS` listing what is available.
+ *   1. `AUTHENTICATE <MECH>` — selects a mechanism. `PLAIN` is always
+ *      supported and answers with `AUTHENTICATE +` (requesting the payload).
+ *      `EXTERNAL` is supported only when an mTLS identity provider is
+ *      configured for the connection; without one, EXTERNAL falls through
+ *      to `908 ERR_SASLMECHS` (mechanism not available) listing what is.
+ *      The verified client-cert subject is resolved at finalise time.
+ *      Anything else gets `908 ERR_SASLMECHS` listing what is available.
  *   2. `AUTHENTICATE <b64>` / `AUTHENTICATE +` — delivers the payload (whole
  *      or in `<=400`-byte chunks; `+` marks an empty/final chunk). The
  *      decoded bytes are handed to the injected {@link AccountStore}; on
@@ -26,6 +29,7 @@
 
 import { Effect } from '../effects.js';
 import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { SaslResult } from '../ports.js';
 import { decodeBase64 } from '../protocol/base64.js';
 import { Numerics } from '../protocol/numerics.js';
 import { hostmaskOf } from '../state/connection.js';
@@ -38,8 +42,17 @@ const SASL_CHUNK_BYTES = 400;
 /** Total decoded-payload cap before `905 ERR_SASLTOOLONG`. */
 const SASL_MAX_BYTES = 8192;
 
-/** Mechanisms this server will accept today (advertised verbatim by the cap). */
-const SUPPORTED_MECHS = 'PLAIN,EXTERNAL';
+/**
+ * Mechanisms advertised in `908 ERR_SASLMECHS` and the `sasl` cap value,
+ * derived from whether mTLS is configured for this connection.
+ *
+ * PLAIN is always available; EXTERNAL only when an `MtlsIdentityProvider`
+ * is bound. Operators enable EXTERNAL by configuring mTLS at the edge
+ * — no code change required.
+ */
+function supportedMechs(ctx: Ctx): string {
+  return ctx.mtlsIdentity !== undefined ? 'PLAIN,EXTERNAL' : 'PLAIN';
+}
 
 /**
  * Reducer for `AUTHENTICATE [<param>]`. See module docs for the state
@@ -93,7 +106,12 @@ function handleMechanism(
     return { state, effects: [Effect.send(ctx.connId, [L('AUTHENTICATE +')])] };
   }
   if (mech === 'EXTERNAL') {
-    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+    if (ctx.mtlsIdentity === undefined) {
+      return { state, effects: [Effect.send(ctx.connId, [saslMechs(ctx)])] };
+    }
+    state.saslMech = 'EXTERNAL';
+    state.saslBuffer = '';
+    return { state, effects: [Effect.send(ctx.connId, [L('AUTHENTICATE +')])] };
   }
   return { state, effects: [Effect.send(ctx.connId, [saslMechs(ctx)])] };
 }
@@ -131,6 +149,18 @@ function finalize(
   payloadB64: string,
   mech: string,
   ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  if (mech === 'EXTERNAL') {
+    return finalizeExternal(state, ctx);
+  }
+  return finalizePlain(state, payloadB64, ctx);
+}
+
+/** SASL PLAIN: decode base64 payload, verify username/password. */
+function finalizePlain(
+  state: ConnectionState,
+  payloadB64: string,
+  ctx: Ctx,
 ): { state: ConnectionState; effects: EffectType[] } {
   const parsed = parsePlain(payloadB64);
 
@@ -145,12 +175,45 @@ function finalize(
     return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
   }
 
-  const result = store.verify(mech, {
+  const result = store.verify('PLAIN', {
     kind: 'PLAIN',
     username: parsed.username,
     password: parsed.password,
   });
 
+  return applyResult(state, result, ctx);
+}
+
+/** SASL EXTERNAL: resolve the mTLS cert subject and verify it. */
+function finalizeExternal(
+  state: ConnectionState,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
+  const provider = ctx.mtlsIdentity;
+  const identity = provider?.getIdentity(ctx.connId);
+
+  if (identity === undefined) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+
+  const store = ctx.accounts;
+  if (store === undefined) {
+    clearSasl(state);
+    return { state, effects: [Effect.send(ctx.connId, [saslFail(ctx)])] };
+  }
+
+  const result = store.verify('EXTERNAL', { kind: 'EXTERNAL', identity });
+
+  return applyResult(state, result, ctx);
+}
+
+/** Shared success/failure handling after a `verify` call. */
+function applyResult(
+  state: ConnectionState,
+  result: SaslResult,
+  ctx: Ctx,
+): { state: ConnectionState; effects: EffectType[] } {
   clearSasl(state);
 
   if (result.ok) {
@@ -228,7 +291,7 @@ function saslAlready(ctx: Ctx): RawLine {
 
 function saslMechs(ctx: Ctx): RawLine {
   return L(
-    `:${ctx.serverName} ${code(Numerics.ERR_SASLMECHS)} ${nickOf(ctx)} ${SUPPORTED_MECHS} :are the available SASL mechanisms`,
+    `:${ctx.serverName} ${code(Numerics.ERR_SASLMECHS)} ${nickOf(ctx)} ${supportedMechs(ctx)} :are the available SASL mechanisms`,
   );
 }
 

package/packages/irc-core/src/commands/server-info.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure reducers for the server-information query commands `VERSION`, `TIME`,
+ * `ADMIN`, and `INFO`.
+ *
+ * PLAN §2.1 location-of-authority: these are read-only Connection-entity
+ * commands — they do not mutate connection or channel state, only emit
+ * `Send` numeric replies addressed to the requester. Each is a thin
+ * config/clock-derived reply, so they share a numeric-formatting helper.
+ *
+ * Wire format (RFC 1459/2812):
+ *   - `VERSION [server]` → `351 RPL_VERSION`:
+ *     `:<server> 351 <nick> <version> <server> :<comments>`
+ *   - `TIME [server]` → `391 RPL_TIME`:
+ *     `:<server> 391 <nick> <server> :<human-readable time>`
+ *   - `ADMIN [server]` → `256 RPL_ADMINME`:
+ *     `:<server> 256 <nick> <server> :Administrative info`
+ *   - `INFO [server]` → `371 RPL_INFO` ×N + `374 RPL_ENDOFINFO`:
+ *     `:<server> 371 <nick> :<info line>`
+ *     `:<server> 374 <nick> :End of INFO list`
+ *
+ * The optional `<server>` target parameter is ignored on all four: this is a
+ * single-server implementation (PLAN §1 non-goal: no S2S linking), so a
+ * request addressed to another server still gets the local info.
+ */
+
+import { resolveServerVersion } from '../config.js';
+import { Effect } from '../effects.js';
+import type { RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer, ReducerResult } from '../types.js';
+
+/** Fixed trailing text for `256 RPL_ADMINME`. */
+const ADMINME_TRAILING_TEXT = 'Administrative info';
+
+/** Fixed trailing text for `374 RPL_ENDOFINFO`. */
+const ENDOFINFO_TRAILING_TEXT = 'End of INFO list';
+
+/**
+ * Handles `VERSION [server]`. Emits `351 RPL_VERSION` with the server version,
+ * server name, and network name as the comment.
+ */
+export const versionReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const version = resolveServerVersion(ctx.serverConfig);
+  const line: RawLine = numericLine(
+    ctx,
+    Numerics.RPL_VERSION,
+    nick,
+    `${version} ${ctx.serverName} :${ctx.networkName}`,
+  );
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles `TIME [server]`. Emits `391 RPL_TIME` with an ISO-8601 timestamp
+ * derived from the injected {@link Clock} (deterministic under the fake clock).
+ */
+export const timeReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const iso = new Date(ctx.clock.now()).toISOString();
+  const line = numericLine(ctx, Numerics.RPL_TIME, nick, `${ctx.serverName} :${iso}`);
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles `ADMIN [server]`. Emits `256 RPL_ADMINME` with the server name.
+ * No admin contact info is configured in v1, so the deeper `257`/`258`/`259`
+ * numerics are omitted (the server has no admin-email data to report).
+ */
+export const adminReducer: Reducer<ConnectionState> = (state, _msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const line = numericLine(
+    ctx,
+    Numerics.RPL_ADMINME,
+    nick,
+    `${ctx.serverName} :${ADMINME_TRAILING_TEXT}`,
+  );
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [line])],
+  };
+};
+
+/**
+ * Handles `INFO [server]`. Emits one or more `371 RPL_INFO` lines with
+ * server metadata followed by the `374 RPL_ENDOFINFO` terminator.
+ */
+export const infoReducer: Reducer<ConnectionState> = (
+  state,
+  _msg,
+  ctx,
+): ReducerResult<ConnectionState> => {
+  state.lastSeen = ctx.clock.now();
+
+  const nick = ctx.connection.nick ?? '*';
+  const version = resolveServerVersion(ctx.serverConfig);
+  const out: RawLine[] = [
+    numericLine(ctx, Numerics.RPL_INFO, nick, `:ServerlessIRCd - version ${version}`),
+    numericLine(ctx, Numerics.RPL_INFO, nick, `:Running on network ${ctx.networkName}`),
+    numericLine(ctx, Numerics.RPL_ENDOFINFO, nick, `:${ENDOFINFO_TRAILING_TEXT}`),
+  ];
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, out)],
+  };
+};
+
+/**
+ * Builds `:<server> <code> <nick> <rest>` where `rest` already carries its
+ * own leading colon / spacing for the trailing parameter. This keeps the
+ * three reducers DRY without duplicating the prefix logic.
+ */
+function numericLine(ctx: Ctx, code: number, nick: string, rest: string): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${ctx.serverName} ${codeStr} ${nick} ${rest}` };
+}