serverless-ircd 0.10.0 → 0.11.0

package/packages/irc-server/src/actor.ts

@@ -35,6 +35,7 @@ import {
   type ConnectionState,
   DEFAULT_MONITOR_LIMIT,
   DEFAULT_MULTILINE_MAX_BYTES,
+  DEFAULT_MULTILINE_MAX_ENTRIES,
   Effect,
   type Effect as EffectType,
   EmptyMotdProvider,
@@ -54,6 +55,7 @@ import {
   NoopLoggerInstance,
   Numerics,
   OPERSERV_NICK,
+  type OperFailureStats,
   type RawLine,
   type Reducer,
   SHORTCUT_TO_SERVICE,
@@ -63,6 +65,7 @@ import {
   applyLabelToEffects,
   buildCtx,
   buildMultilineFanout,
+  byteLength,
   caseFold,
   chathistoryReducer,
   extractLabel,
@@ -91,6 +94,7 @@ import {
 } from '@serverless-ircd/irc-core';
 import { dispatch } from './dispatch.js';
 import type { DispatchOptions } from './dispatch.js';
+import { parseErrorReason, truncateToken } from './redact.js';
 import { type RoutedReducers, buildRoutedReducers } from './routing.js';
 import type { IrcRuntime } from './runtime.js';
 import { type Transport, WsTextFrameTransport } from './transport.js';
@@ -205,6 +209,19 @@ export interface ConnectionActorOptions {
    * watched nick later connects or quits.
    */
   readonly monitor?: MonitorStore;
+  /**
+   * Per-IP failed-`OPER` counter shared across every connection's actor
+   * (absent when the deployment's runtime does not maintain one — e.g.
+   * per-connection Durable Object adapters). When bound, `ctx.operFailures`
+   * is defined so the OPER reducer throttles brute-force guessing per
+   * source host: after `serverConfig.oper.maxFailures` credential
+   * failures within `oper.failureWindowSeconds`, further attempts from
+   * that host are rejected with `491` before the credential store is
+   * consulted and a `BroadcastOperNotice` notifies every oper. The
+   * instance MUST share the actor's clock so window arithmetic is
+   * coherent.
+   */
+  readonly operFailures?: OperFailureStats;
   /**
    * Network-statistics source for the `LUSERS` and `STATS` commands
    * (absent when no stats backend is wired). When bound, the actor
@@ -265,6 +282,7 @@ export class ConnectionActor {
   private readonly away: AwayStore | undefined;
   private readonly services: ServicesStore | undefined;
   private readonly monitor: MonitorStore | undefined;
+  private readonly operFailures: OperFailureStats | undefined;
   private readonly stats: ServerStats | undefined;
   private readonly reducers: RoutedReducers;
   /**
@@ -290,9 +308,10 @@ export class ConnectionActor {
    * In-progress IRCv3 `draft/multiline` batch, if any. Set when the client
    * sends `BATCH +id draft/multiline :<target>` (and the connection
    * negotiated the cap), populated by each intervening `PRIVMSG`/`NOTICE`,
-   * and cleared when the closing `BATCH -id` is finalized. While set, the
-   * actor diverts `PRIVMSG`/`NOTICE` into the accumulator instead of
-   * running the normal channel/user reducers.
+   * and cleared when the closing `BATCH -id` is finalized — or earlier on
+   * an incremental-budget abort or connection teardown ({@link dispose}).
+   * While set, the actor diverts `PRIVMSG`/`NOTICE` into the accumulator
+   * instead of running the normal channel/user reducers.
    */
   private openMultilineBatch:
     | {
@@ -318,6 +337,7 @@ export class ConnectionActor {
     this.away = opts.away;
     this.services = opts.services;
     this.monitor = opts.monitor;
+    this.operFailures = opts.operFailures;
     this.stats = opts.stats;
     this.logger = opts.logger ?? NoopLoggerInstance;
     this.pinnedTraceId = opts.traceId;
@@ -374,23 +394,41 @@ export class ConnectionActor {
     await this.receive(text);
   }
 
+  /**
+   * Connection teardown hook. Clears any state that must not outlive the
+   * connection — currently an abandoned `draft/multiline` batch (a client
+   * that disconnects between `BATCH +id` and `BATCH -id` would otherwise
+   * leave the accumulator mid-flight). Adapters call this when the
+   * underlying socket closes; safe to call at any lifecycle point.
+   */
+  dispose(): void {
+    this.openMultilineBatch = undefined;
+  }
+
   private async processLine(line: string, log: Logger, traceId: string): Promise<void> {
     let msg: IrcMessage;
     let parseFailed = false;
+    let parseErr: unknown;
     try {
       msg = parse(line);
-    } catch {
+    } catch (err) {
       // `parse` only throws `IrcParseError` (every throw inside the parser
       // constructs one); the untyped catch is the strict-mode narrowing
       // artifact for `unknown`. Every parse failure becomes a `421` so the
       // actor never crashes on a single bad line (acceptance criteria).
       parseFailed = true;
+      parseErr = err;
       msg = { tags: {}, command: '', params: [] };
     }
     if (parseFailed) {
+      // The raw line is NEVER logged: a hostile client can smuggle a
+      // credential past the parser (e.g. a malformed line whose payload
+      // carries `PASS <secret>`). Operators get the leading token
+      // (capped), the length, and a stable reason code instead.
       log.warn('frame.parse-error', {
-        line,
-        token: firstToken(line),
+        token: truncateToken(firstToken(line)),
+        length: line.length,
+        reason: parseErrorReason(parseErr),
       });
       const token = firstToken(line);
       await dispatch(
@@ -502,6 +540,7 @@ export class ConnectionActor {
       ...(this.history !== undefined ? { history: this.history } : {}),
       ...(this.away !== undefined ? { away: this.away } : {}),
       ...(this.services !== undefined ? { services: this.services } : {}),
+      ...(this.operFailures !== undefined ? { operFailures: this.operFailures } : {}),
       ...(label !== undefined ? { label } : {}),
     });
 
@@ -591,6 +630,7 @@ export class ConnectionActor {
         return this.routeMultiChannel(
           msg,
           (chan, singleParamMsg) => this.reducers.part(chan, singleParamMsg, ctx).effects,
+          ctx,
         );
       case 'TOPIC':
         return this.routeSingleChannel(msg, (chan) => this.reducers.topic(chan, msg, ctx).effects);
@@ -1109,6 +1149,12 @@ export class ConnectionActor {
    * `draft/multiline` batch. The inner line's target must match the batch
    * target and (after the first line) its command must match too; a
    * mismatch aborts the batch with a `FAIL` and clears the accumulator.
+   *
+   * The byte budget (`multilineMaxBytes`) and entry ceiling
+   * (`multilineMaxEntries`) are enforced incrementally on each push: the
+   * line that would push the batch past either limit aborts it immediately
+   * (synthesized `BATCH -id` + `FAIL`) instead of being buffered for a
+   * close the client may never send.
    */
   private accumulateMultilineLine(msg: IrcMessage): EffectType[] {
     const open = this.openMultilineBatch;
@@ -1141,10 +1187,46 @@ export class ConnectionActor {
         ]),
       ];
     }
+    // Incremental budget enforcement: the byte budget and entry ceiling are
+    // checked on every push, not just on close, so a client cannot buffer
+    // unbounded content in a batch it never closes.
+    const maxEntries = this.serverConfig.multilineMaxEntries ?? DEFAULT_MULTILINE_MAX_ENTRIES;
+    if (open.entries.length >= maxEntries) {
+      return this.abortMultilineBatch(open, 'MULTILINE_MAX_LINES', maxEntries, 'line');
+    }
+    const maxBytes = this.serverConfig.multilineMaxBytes ?? DEFAULT_MULTILINE_MAX_BYTES;
+    const candidateBytes =
+      multilineByteLength(open.entries) + (open.entries.length === 0 ? 0 : 1) + byteLength(text);
+    if (candidateBytes > maxBytes) {
+      return this.abortMultilineBatch(open, 'MULTILINE_MAX_BYTES', maxBytes, 'byte');
+    }
     open.entries.push({ text });
     return [];
   }
 
+  /**
+   * Aborts an open `draft/multiline` batch that just violated the
+   * incremental budget: clears the accumulator and emits a synthesized
+   * `BATCH -id` close (so batch-aware clients exit the batch) followed by
+   * the `FAIL` rejection carrying the limit that was exceeded.
+   */
+  private abortMultilineBatch(
+    open: { readonly id: string; readonly target: string },
+    code: 'MULTILINE_MAX_BYTES' | 'MULTILINE_MAX_LINES',
+    limit: number,
+    unit: 'byte' | 'line',
+  ): EffectType[] {
+    this.openMultilineBatch = undefined;
+    return [
+      Effect.send(this.state.id, [
+        { text: `BATCH -${open.id}` },
+        {
+          text: `:${this.serverConfig.serverName} FAIL BATCH ${code} ${open.target} :Multi-line batch exceeds the ${limit} ${unit} limit`,
+        },
+      ]),
+    ];
+  }
+
   /**
    * Finalizes an open `draft/multiline` batch on `BATCH -id`. Channel targets
    * delegate to the pure {@link finalizeMultilineBatch} reducer (cap-split
@@ -1310,6 +1392,7 @@ export class ConnectionActor {
   private routeMultiChannel(
     msg: IrcMessage,
     run: (chan: ChannelState, singleParamMsg: IrcMessage) => EffectType[],
+    ctx: ReturnType<typeof buildCtx>,
   ): EffectType[] {
     const effects: EffectType[] = [];
     const rawParam = msg.params[0] ?? '';
@@ -1322,11 +1405,19 @@ export class ConnectionActor {
       // 461 ERR_NEEDMOREPARAMS rather than the actor silently doing nothing.
       return run(this.channels.getOrCreateChannel(''), msg);
     }
-    for (const name of names) {
+    // Target cap (e.g. `PART #a,#b,#c,…`): only the first
+    // `maxTargetsPerCommand` channels are processed; every dropped
+    // channel gets a `407 ERR_TOOMANYTARGETS` so the client can see the
+    // truncation instead of the part being silently ignored.
+    const cap = ctx.serverConfig.maxTargetsPerCommand;
+    for (const name of names.slice(0, cap)) {
       const chan = this.channels.getOrCreateChannel(name);
       const singleParamMsg: IrcMessage = { ...msg, params: [name, ...tail] };
       effects.push(...run(chan, singleParamMsg));
     }
+    for (const dropped of names.slice(cap)) {
+      effects.push(this.tooManyTargetsEffect(dropped, ctx));
+    }
     return effects;
   }
 
@@ -1356,7 +1447,12 @@ export class ConnectionActor {
       // proper 411 ERR_NORECIPIENT rather than silently doing nothing.
       return userReducer(this.state, msg, ctx).effects;
     }
-    for (const target of targets) {
+    // Target cap (e.g. `PRIVMSG #a,#b,#c,…`): only the first
+    // `maxTargetsPerCommand` targets are routed; every dropped target
+    // gets a `407 ERR_TOOMANYTARGETS` so the client can see the
+    // truncation instead of the message being silently ignored.
+    const cap = ctx.serverConfig.maxTargetsPerCommand;
+    for (const target of targets.slice(0, cap)) {
       const singleParamMsg: IrcMessage = { ...msg, params: [target, ...tail] };
       const serviceReducer = this.serviceReducerFor(target, msg.command);
       if (isChannelTarget(target)) {
@@ -1378,9 +1474,28 @@ export class ConnectionActor {
         effects.push(...userReducer(this.state, singleParamMsg, ctx).effects);
       }
     }
+    for (const dropped of targets.slice(cap)) {
+      effects.push(this.tooManyTargetsEffect(dropped, ctx));
+    }
     return effects;
   }
 
+  /**
+   * Builds the `407 ERR_TOOMANYTARGETS` Send effect for one target dropped
+   * by the `maxTargetsPerCommand` cap in {@link routeMessageTarget} /
+   * {@link routeMultiChannel}. Emitted once per dropped target after the
+   * allowed targets have been routed, so the client learns exactly which
+   * targets were not delivered to.
+   */
+  private tooManyTargetsEffect(target: string, ctx: ReturnType<typeof buildCtx>): EffectType {
+    const nick = ctx.connection.nick ?? '*';
+    const code = Numerics.ERR_TOOMANYTARGETS.toString().padStart(3, '0');
+    const line: RawLine = {
+      text: `:${this.serverConfig.serverName} ${code} ${nick} ${target} :Too many targets`,
+    };
+    return Effect.send(ctx.connId, [line]);
+  }
+
   /**
    * Resolves the service pseudo-client reducer for a nick target, or
    * `undefined` when the target is not a service nick / the command is not

package/packages/irc-server/src/dispatch.ts

@@ -53,6 +53,7 @@ const handlers: { [K in Effect['tag']]: Handler<Extract<Effect, { tag: K }>> } =
   ReleaseNick: (e, r, m) => releaseNickEtc(e, r, m),
   ApplyChannelDelta: (e, r) => r.applyChannelDelta(e.chan, e.delta),
   BroadcastWallops: (e, r) => r.broadcastWallops(e.lines, e.except),
+  BroadcastOperNotice: (e, r) => r.broadcastOperNotice(e.lines, e.except),
   EnforceNick: (e, r, _m, opts) => enforceNick(e, r, opts),
 };
 

package/packages/irc-server/src/index.ts

@@ -19,3 +19,10 @@ export {
 export type { Transport } from './transport.js';
 export { buildRoutedReducers, resolveFloodControl } from './routing.js';
 export type { RoutedReducers } from './routing.js';
+export {
+  MAX_LOG_TOKEN_CHARS,
+  parseErrorReason,
+  REDACTED,
+  redactLine,
+  truncateToken,
+} from './redact.js';

package/packages/irc-server/src/redact.ts

@@ -0,0 +1,159 @@
+/**
+ * Log-scrubbing helpers — the credential-exfiltration guards for log
+ * payloads.
+ *
+ * Threat model: a hostile client can deliberately smuggle secret
+ * material into server logs by sending a line whose payload carries a
+ * credential (e.g. `PASS hunter2` inside a frame that trips the parser).
+ * Anything derived from inbound client input that reaches a warn/error
+ * log record must pass through these helpers first:
+ *
+ *   - A site that must log a line logs `redactLine(line)` — the command
+ *     verb (and NickServ target + subcommand) survive for debuggability;
+ *     the credential-bearing parameters are replaced with `[REDACTED]`.
+ *   - Parse diagnostics never log the line at all: they log
+ *     `truncateToken(firstToken(line))` + the line length +
+ *     `parseErrorReason(err)` so operators can correlate without ever
+ *     storing client payload.
+ */
+
+/** Placeholder substituted for redacted credential material. */
+export const REDACTED = '[REDACTED]';
+
+/**
+ * Max characters of a leading token included in log records. Caps the
+ * volume a hostile client can push into logs with a single over-long
+ * garbage token (the wire itself allows 512 bytes per line).
+ */
+export const MAX_LOG_TOKEN_CHARS = 32;
+
+/**
+ * Command verbs whose parameters are credential material. `IDENTIFY`
+ * covers the service-shortcut form some clients send as a top-level
+ * command; the PRIVMSG/NOTICE-to-NickServ form is handled separately
+ * below.
+ */
+const SENSITIVE_COMMANDS: ReadonlySet<string> = new Set([
+  'PASS',
+  'AUTHENTICATE',
+  'OPER',
+  'IDENTIFY',
+]);
+
+/**
+ * rfc1459-lowercased service nick targets for PRIVMSG/NOTICE. Only
+ * messages aimed at these nicks are inspected for credential
+ * subcommands, so ordinary chat is never touched.
+ */
+const SERVICE_NICKS: ReadonlySet<string> = new Set(['nickserv', 'ns']);
+
+/**
+ * NickServ subcommands whose arguments are credentials (`IDENTIFY
+ * <password>`, the `ID <password>` alias). Anything else aimed at a
+ * service nick (INFO, HELP, …) is not secret and passes through.
+ */
+const SENSITIVE_SUBCOMMANDS: ReadonlySet<string> = new Set(['identify', 'id']);
+
+/**
+ * Redacts the credential-bearing parameters of a raw inbound IRC line
+ * while keeping the command verb (and, for service messages, the target
+ * and subcommand) for debuggability. Non-sensitive lines are returned
+ * unchanged; the input is never lengthened beyond a few placeholder
+ * characters.
+ *
+ * Sensitive shapes:
+ *   `PASS <pw>`                      → `PASS [REDACTED]`
+ *   `AUTHENTICATE <sasl-payload>`    → `AUTHENTICATE [REDACTED]`
+ *   `OPER <name> <pw>`               → `OPER [REDACTED]`
+ *   `IDENTIFY <pw>`                  → `IDENTIFY [REDACTED]`
+ *   `PRIVMSG NickServ :IDENTIFY <pw>`→ `PRIVMSG NickServ :IDENTIFY [REDACTED]`
+ *   (same for NOTICE, the `ID` alias, `ns`, and missing trailing colons)
+ *
+ * An optional leading `:source` prefix is preserved verbatim.
+ */
+export function redactLine(line: string): string {
+  // Split off an optional leading source prefix; the next token is the
+  // command position.
+  let head = '';
+  let rest = line;
+  if (line.startsWith(':')) {
+    const prefixEnd = line.indexOf(' ');
+    if (prefixEnd === -1) return line;
+    head = line.slice(0, prefixEnd);
+    rest = line.slice(prefixEnd + 1);
+  }
+
+  const commandEnd = rest.indexOf(' ');
+  const command = commandEnd === -1 ? rest : rest.slice(0, commandEnd);
+  const remainder = commandEnd === -1 ? '' : rest.slice(commandEnd + 1);
+  const verb = command.toUpperCase();
+
+  if (SENSITIVE_COMMANDS.has(verb)) {
+    if (remainder.length === 0) return line;
+    return withPrefix(head, `${command} ${REDACTED}`);
+  }
+
+  if (verb === 'PRIVMSG' || verb === 'NOTICE') {
+    const targetEnd = remainder.indexOf(' ');
+    const target = targetEnd === -1 ? remainder : remainder.slice(0, targetEnd);
+    const body = targetEnd === -1 ? '' : remainder.slice(targetEnd + 1);
+    if (SERVICE_NICKS.has(target.toLowerCase())) {
+      // Tolerate both conforming (`:IDENTIFY pw`) and colon-less bodies.
+      const bare = body.startsWith(':') ? body.slice(1) : body;
+      const hadColon = bare.length !== body.length;
+      const subEnd = bare.indexOf(' ');
+      const sub = subEnd === -1 ? bare : bare.slice(0, subEnd);
+      const hasArgs = subEnd !== -1;
+      if (hasArgs && SENSITIVE_SUBCOMMANDS.has(sub.toLowerCase())) {
+        return withPrefix(head, `${command} ${target} ${hadColon ? ':' : ''}${sub} ${REDACTED}`);
+      }
+    }
+  }
+
+  return line;
+}
+
+/**
+ * Caps a leading token at {@link MAX_LOG_TOKEN_CHARS} characters,
+ * suffixing an ellipsis marker when truncation occurred. The marker makes
+ * truncated tokens visually distinct from tokens that were exactly at the
+ * cap.
+ */
+export function truncateToken(token: string): string {
+  return token.length <= MAX_LOG_TOKEN_CHARS ? token : `${token.slice(0, MAX_LOG_TOKEN_CHARS)}...`;
+}
+
+/**
+ * Parser diagnostics (fixed strings or fixed prefixes) → stable reason
+ * codes. Codes are log query keys; they must stay stable even if the
+ * human-readable message is reworded.
+ */
+const PARSE_ERROR_REASONS: ReadonlyArray<readonly [prefix: string, reason: string]> = [
+  ['empty message', 'empty-message'],
+  ['message exceeds', 'input-cap-exceeded'],
+  ['tag section exceeds', 'tag-section-too-large'],
+  ['tag section with no message body', 'tags-without-body'],
+  ['too many tags', 'too-many-tags'],
+  ['source prefix with no command', 'prefix-without-command'],
+  ['missing command', 'missing-command'],
+  ['invalid command token', 'invalid-command-token'],
+];
+
+/**
+ * Maps a thrown parse error to a stable reason code for log records.
+ * `parse` only throws `IrcParseError` (every throw inside the parser
+ * constructs one), but the guard accepts any thrown value so callers can
+ * pass an `unknown` catch binding directly.
+ */
+export function parseErrorReason(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  for (const [prefix, reason] of PARSE_ERROR_REASONS) {
+    if (message.startsWith(prefix)) return reason;
+  }
+  return 'parse-failed';
+}
+
+/** Re-attaches the (possibly absent) source prefix to a redacted tail. */
+function withPrefix(head: string, tail: string): string {
+  return head.length === 0 ? tail : `${head} ${tail}`;
+}

package/packages/irc-server/src/runtime.ts

@@ -54,6 +54,20 @@ export interface IrcRuntime {
    *     oper's WALLOPS rate.
    */
   broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void>;
+  /**
+   * Oper-only notice fanout. Delivers `lines` to every live connection
+   * whose `+o` (oper) user mode is set, skipping `except`. Emitted by the
+   * OPER reducer's per-IP brute-force lockout gate
+   * (`:<server> NOTICE * :OPER lockout triggered for <host>`) so the oper
+   * corps learns a guessing attack is being throttled. Enumeration
+   * strategy mirrors {@link broadcastWallops} per adapter:
+   *   - in-memory: scans its connection map, filters `+o`.
+   *   - Cloudflare: walks the sharded registry, fetches each state to
+   *     check `+o`.
+   *   - AWS: `Scan`s the `Connections` table filtered to `+o` rows and
+   *     `PostToConnection`s each.
+   */
+  broadcastOperNotice(lines: RawLine[], except?: ConnId): Promise<void>;
 
   // nickname registry
   reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }>;

package/packages/irc-server/src/transport.ts

@@ -15,7 +15,7 @@
  * parser/reducer/dispatch pipeline.
  */
 
-import { splitFrameLines } from '@serverless-ircd/irc-core';
+import { MAX_BUFFER_BYTES, byteLength, splitFrameLines } from '@serverless-ircd/irc-core';
 
 export { splitFrameLines };
 
@@ -28,6 +28,22 @@ export interface Transport {
   feed(chunk: string): string[];
 }
 
+/** Options accepted by {@link TcpByteStreamTransport}. */
+export interface TcpByteStreamTransportOptions {
+  /**
+   * Invoked when an appended chunk grows the retained partial-line buffer
+   * past {@link MAX_BUFFER_BYTES} (measured in UTF-8 bytes, once per
+   * append). The transport drops the oversized tail and returns no lines;
+   * the owner should close the connection — a peer that streams more than
+   * 8 KiB without a line terminator can never produce a legal IRC line
+   * (the parser caps lines at 512 bytes), so the buffer is pure
+   * attacker-controlled memory. Writing `ERROR :Closing link: ...` and
+   * tearing down the socket is the caller's job: this seam has no write
+   * path.
+   */
+  onOverflow?: () => void;
+}
+
 /**
  * Splits a WebSocket text frame into IRC lines. Re-exported from
  * `@serverless-ircd/irc-core` (`ws-framing.ts`), which owns the canonical
@@ -65,6 +81,8 @@ export class WsTextFrameTransport implements Transport {
 export class TcpByteStreamTransport implements Transport {
   private buffer = '';
 
+  constructor(private readonly options?: TcpByteStreamTransportOptions) {}
+
   feed(chunk: string): string[] {
     if (chunk.length === 0) return [];
     this.buffer += chunk;
@@ -80,6 +98,15 @@ export class TcpByteStreamTransport implements Transport {
       }
     }
     this.buffer = this.buffer.slice(start);
+    // Cap the retained (unterminated) tail — checked once per append, in
+    // UTF-8 bytes. Complete lines flushed by this chunk never count against
+    // the budget, so legitimate multi-line batches far larger than the cap
+    // pass through; only an unterminated tail can grow unboundedly.
+    if (byteLength(this.buffer) > MAX_BUFFER_BYTES) {
+      this.buffer = '';
+      this.options?.onOverflow?.();
+      return [];
+    }
     return lines;
   }