serverless-ircd 0.3.0 → 0.5.0

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

@@ -0,0 +1,119 @@
+/**
+ * Pure reducer for the IRC `REHASH` command (oper-gated config reload).
+ *
+ * PLAN §2.1 location-of-authority: REHASH runs in the Connection entity. The
+ * reducer is pure — it only enforces the oper gate and emits the
+ * `382 RPL_REHASHING` reply. The actual config re-fetch is a request/response
+ * side effect (re-invoke the adapter's bound config loader and swap the live
+ * {@link ServerConfig} reference on the actor), so — exactly like
+ * `lookupNick` / `getConnection` — it is NOT modelled as a fire-and-forget
+ * `Effect`; the actor layer performs it and surfaces success/failure back to
+ * the oper via a second `382` line on failure.
+ *
+ * Wire format:
+ *   - `REHASH` (no params).
+ *   - `382 RPL_REHASHING`:
+ *     `:<server> 382 <nick> :Rehashing from <source>`
+ *   - `481 ERR_NOPRIVILEGES`:
+ *     `:<server> 481 <nick> :Permission Denied - You're not an IRC operator`
+ *
+ * Behaviour:
+ *   - Non-oper → `481 ERR_NOPRIVILEGES`; no reload is signalled.
+ *   - Oper → emits `382` noting the bound config source and signals
+ *     `shouldReload: true`. The actor re-invokes its loader and swaps the
+ *     live config; on failure the previous config stays in effect and a
+ *     graceful error-suffixed `382` follows (handled by the actor).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { IrcMessage } from '../protocol/messages.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `481 ERR_NOPRIVILEGES` (matches `mode.ts`). */
+const NOPRIVILEGES_TRAILING_TEXT = "Permission Denied - You're not an IRC operator";
+
+/**
+ * Result of {@link rehashReducer}. Adds a `shouldReload` intent flag on top of
+ * the standard reducer shape so the actor layer knows whether to perform the
+ * async config re-fetch (oper gate passed) without re-deriving the gate.
+ */
+export interface RehashResult {
+  state: ConnectionState;
+  effects: EffectType[];
+  shouldReload: boolean;
+}
+
+/**
+ * Composes the trailing text for the `382 RPL_REHASHING` line. The success
+ * form notes the bound config source; the failure form (used by the actor on
+ * reload rejection) appends the error so the oper sees what went wrong
+ * without being disconnected.
+ */
+export function buildRehashTrailing(configSource: string, error?: string): string {
+  const base = `Rehashing from ${configSource}`;
+  return error === undefined ? base : `${base} failed: ${error}`;
+}
+
+/**
+ * Renders the full `:<server> 382 <nick> :<trailing>` wire line. Shared by
+ * the reducer (optimistic success line) and the actor (error-suffixed line
+ * on reload failure) so the two paths cannot drift in formatting.
+ */
+export function rehashLine(
+  serverName: string,
+  nick: string,
+  configSource: string,
+  error?: string,
+): RawLine {
+  const code = Numerics.RPL_REHASHING.toString().padStart(3, '0');
+  return { text: `:${serverName} ${code} ${nick} :${buildRehashTrailing(configSource, error)}` };
+}
+
+/**
+ * Handles `REHASH`.
+ *
+ * Enforces the oper gate, stamps `lastSeen`, and — for an oper — emits the
+ * `382 RPL_REHASHING` reply and signals the actor to perform the reload via
+ * `shouldReload`. The reducer never performs IO.
+ */
+export function rehashReducer(
+  state: ConnectionState,
+  _msg: IrcMessage,
+  ctx: Ctx,
+  configSource: string,
+): RehashResult {
+  state.lastSeen = ctx.clock.now();
+
+  if (!state.userModes.oper) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOPRIVILEGES, NOPRIVILEGES_TRAILING_TEXT),
+        ]),
+      ],
+      shouldReload: false,
+    };
+  }
+
+  const nick = ctx.connection.nick ?? '*';
+  return {
+    state,
+    effects: [Effect.send(ctx.connId, [rehashLine(ctx.serverName, nick, configSource)])],
+    shouldReload: true,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The nick falls back to
+ * `*` for an unregistered connection, matching the rest of the codebase's
+ * numeric formatting.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, `:${trailing}`].join(' ') };
+}

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}` };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Pure reducer for the IRC `SETNAME` command (RFC 2812 §4.1.7).
+ *
+ * PLAN §2.1 location-of-authority: SETNAME runs in the Connection entity.
+ * The reducer mutates `state.realname` (the GECOS field originally set by
+ * the `USER` reducer) and performs no IO.
+ *
+ * Wire format:
+ *   - `SETNAME :<realname>` — replaces `state.realname`.
+ *   - `461 ERR_NEEDMOREPARAMS` when the realname is missing/empty.
+ *   - `451 ERR_NOTREGISTERED` when issued before registration completes.
+ *
+ * Broadcast decision: there is no standard IRCv3 cap for relaying a
+ * realname change (the `chghost` cap covers user/host, not realname), so
+ * v1 updates `state.realname` silently. A subsequent `WHOIS` reflects the
+ * new value in `311 RPL_WHOISUSER`. A `draft/setname` relay cap is a
+ * documented follow-up.
+ *
+ * Length cap: registration-time `USER` does not enforce a realname length
+ * cap, so this command applies its own via `serverConfig.realnameLen`
+ * (falling back to {@link DEFAULT_REALNAME_LEN}). An over-cap value is
+ * rejected with `432 ERR_ERRONEUSNICKNAME` — the same numeric registration
+ * uses for an over-length `NICK` (the codebase's only registration-time
+ * "value rejected for length" precedent). The offending value is NOT
+ * echoed back so a client cannot amplify a multi-kilobyte payload via the
+ * error reply. Truncation (as `TOPIC` does) is deliberately not used: the
+ * spec frames an over-long realname as a rejection, not a silent trim.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/**
+ * Built-in realname length cap when `serverConfig.realnameLen` is unset.
+ * Matches the schema default and the common ircd-seven GECOS ceiling.
+ */
+const DEFAULT_REALNAME_LEN = 50;
+
+/** Fixed trailing text for `461 ERR_NEEDMOREPARAMS` (matches `USER`/`PASS`). */
+const NEEDMOREPARAMS_TRAILING = 'Not enough parameters';
+
+/** Fixed trailing text for `451 ERR_NOTREGISTERED`. */
+const NOTREGISTERED_TRAILING = 'You have not registered';
+
+/** Fixed trailing text for the over-cap `432` rejection. */
+const ERRONEOUS_REALNAME_TRAILING = 'Erroneous realname';
+
+/**
+ * Handles `SETNAME :<realname>`.
+ *
+ * Stamps `lastSeen`, enforces the registration + length gates, and on
+ * success replaces `state.realname` with no broadcast. The reducer never
+ * performs IO.
+ */
+export const setnameReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (state.registration !== 'registered') {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOTREGISTERED, NOTREGISTERED_TRAILING),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const realname = msg.params[0];
+  if (realname === undefined || realname.length === 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NEEDMOREPARAMS, NEEDMOREPARAMS_TRAILING, 'SETNAME'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const cap = ctx.serverConfig.realnameLen ?? DEFAULT_REALNAME_LEN;
+  if (realname.length > cap) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_ERRONEUSNICKNAME, ERRONEOUS_REALNAME_TRAILING),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  state.realname = realname;
+  return { state, effects };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> [:<middle>] :<trailing>` line. The nick
+ * falls back to `*` when the connection has not yet registered one, and the
+ * optional `middle` is omitted when not supplied — matching the numeric
+ * formatting used by the registration reducers.
+ */
+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/stats.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure reducer for the IRC `STATS` command (RFC 2812 §4.6.3).
+ *
+ * PLAN §2.1 location-of-authority: STATS is a read-only diagnostic that
+ * reports server statistics keyed by a single-letter query. The reducer
+ * takes an already-aggregated {@link ServerStatsSnapshot} (the actor
+ * awaits a {@link ServerStats} backend before calling here). The reducer
+ * never mutates anything but the requester's `lastSeen`.
+ *
+ * Wire format (RFC 2812 §5.1 + modern practice):
+ *   - `STATS <query> [<server>]`
+ *   - `211 RPL_STATSLINKINFO` (the `l` query): per-link sendq/byte/msg
+ *     counters. Single-server deployment collapses this to one line for
+ *     the bound server.
+ *   - `242 RPL_STATSUPTIME` (the `u` query):
+ *     `:<server> 242 <nick> :Server Up <d> days, <h>:<mm>:<ss>`
+ *   - `219 RPL_ENDOFSTATS`:
+ *     `:<server> 219 <nick> <query> :End of /STATS report`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Implemented query letters: `u` (uptime), `l` (link info). Unknown letters
+ * follow charybdis semantics: the reducer emits ONLY the `219` terminator
+ * with an empty body (no 461/401/etc). The remaining RFC letters
+ * (`k`/`K`/`q`/`g`/`x`/`z`/…) are deferred behind per-letter tests; the
+ * actor routes them here regardless so a future implementation is just
+ * another case branch.
+ *
+ * `<server>` resolves at the actor layer: a non-local name yields
+ * `402 ERR_NOSUCHSERVER` (single-server network — S2S routing is a PLAN
+ * non-goal). When the actor passes `serverTarget`, the reducer emits ONLY
+ * the 402 and nothing else.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ServerStatsSnapshot } from '../ports.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Fixed text emitted for `219 RPL_ENDOFSTATS`. */
+const ENDOFSTATS_TRAILING_TEXT = 'End of /STATS report';
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` numeric line
+ * addressed to the requester. When `middle` is empty the middle field is
+ * still emitted as a bare space-prefixed token (matches charybdis output
+ * for STATS with no query letter).
+ */
+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];
+  parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Formats an uptime delta (ms) as `Server Up <d> days, <h>:<mm>:<ss>`,
+ * matching charybdis's `RPL_STATSUPTIME` text. Days and hours are not
+ * zero-padded; minutes and seconds are.
+ */
+function formatUptime(deltaMs: number): string {
+  let totalSec = Math.floor(deltaMs / 1000);
+  const days = Math.floor(totalSec / 86_400);
+  totalSec -= days * 86_400;
+  const hours = Math.floor(totalSec / 3_600);
+  totalSec -= hours * 3_600;
+  const minutes = Math.floor(totalSec / 60);
+  totalSec -= minutes * 60;
+  const seconds = totalSec;
+  const mm = minutes.toString().padStart(2, '0');
+  const ss = seconds.toString().padStart(2, '0');
+  return `Server Up ${days} days, ${hours}:${mm}:${ss}`;
+}
+
+/**
+ * Handles `STATS <query> [<server>]`.
+ *
+ * @param snapshot      The aggregated network statistics (only `uptimeStartedAt`
+ *   is consulted here; full counts are surfaced by LUSERS).
+ * @param msg           The parsed `STATS` message.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<server>` names a
+ *   non-local server; the reducer emits `402 ERR_NOSUCHSERVER` against this
+ *   name.
+ */
+export function statsReducer(
+  snapshot: ServerStatsSnapshot,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (serverTarget !== undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHSERVER, NOSUCHSERVER_TRAILING_TEXT, serverTarget),
+      ]),
+    );
+    return { effects };
+  }
+
+  // Normalise: STATS with no query letter is treated as the empty string;
+  // case is folded to lower so the terminator matches the canonical charybdis
+  // output (`STATS U` and `STATS u` both terminate with `219 <nick> u`).
+  const rawQuery = msg.params[0] ?? '';
+  const query = rawQuery.toLowerCase();
+
+  if (query === 'u') {
+    const uptimeMs = ctx.clock.now() - snapshot.uptimeStartedAt;
+    const code = Numerics.RPL_STATSUPTIME.toString().padStart(3, '0');
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${ctx.connection.nick ?? '*'} :${formatUptime(uptimeMs)}`,
+        },
+      ]),
+    );
+  } else if (query === 'l') {
+    // Single-server: one link-info line for the bound server. All sendq /
+    // byte / message counters are zero for a stateless serverless runtime
+    // (no persistent S2S link); the trailing text is the configured server
+    // version so the client sees a self-describing entry.
+    const code = Numerics.RPL_STATSLINKINFO.toString().padStart(3, '0');
+    const requester = ctx.connection.nick ?? '*';
+    const version = ctx.serverConfig.serverVersion ?? '';
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${requester} ${ctx.serverName} 0 0 0 0 0 0 :${version}`,
+        },
+      ]),
+    );
+  }
+  // Terminator always emitted, even for unknown letters (charybdis
+  // semantics: unknown STATS letters produce no body lines, just 219).
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFSTATS, ENDOFSTATS_TRAILING_TEXT, query),
+    ]),
+  );
+
+  return { effects };
+}

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

@@ -35,12 +35,10 @@ function isValidChannelName(name: string, maxLen: number): boolean {
 }
 
 /** Formats a numeric error/reply line addressed to the connection's nick. */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+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}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }