serverless-ircd 0.1.0 → 0.3.0

package/packages/irc-core/src/config.ts

@@ -0,0 +1,270 @@
+/**
+ * Server configuration schema (Zod) — the single source of truth for what
+ * the deployment supplies at boot time.
+ *
+ * Adapters load this from their platform-native secret/config store
+ * (Cloudflare: KV/vars in `wrangler.toml`; AWS: Secrets Manager/SSM) and
+ * pass it through {@link parseServerConfig} before the runtime boots.
+ * Invalid config fails fast at boot with a readable error instead of
+ * corrupting connection state mid-flight.
+ *
+ * The reducer-facing {@link ServerConfig} (in `types.ts`) is a strict
+ * subset of this schema — the reducers do not care about MOTD text,
+ * channel-prefix policy, or max-clients (those are consumed by
+ * adapter-side plumbing: the MOTD provider, the JOIN validator's prefix
+ * table, and the connection admission gate). Oper credentials ARE surfaced
+ * on the reducer-facing config so the OPER reducer can authenticate.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema for a single IRC operator credential.
+ *
+ * Both fields are non-empty strings; the adapter is responsible for any
+ * hashing/constant-time comparison at the OPER auth boundary.
+ */
+export const OperCredSchema = z.object({
+  user: z.string().min(1),
+  password: z.string().min(1),
+});
+
+/**
+ * Schema for a single SASL PLAIN account credential. The `username` is also
+ * the canonical account name recorded on the connection (for `extended-join`
+ * / `account-tag`). Both fields are non-empty strings; adapters seed an
+ * {@link InMemoryAccountStore} from this list at boot.
+ */
+export const SaslAccountSchema = z.object({
+  username: z.string().min(1),
+  password: z.string().min(1),
+});
+
+/**
+ * Cloaking configuration. When enabled, the visible hostmask of every
+ * connecting client is replaced by `<cloak>.<suffix>` where `<cloak>` is a
+ * short deterministic hash of the client's real IP + the deployment
+ * secret. The real IP is never revealed on the wire.
+ *
+ * The `secret` MUST be set when `enabled` is true; the schema rejects a
+ * cloaking config that turns on cloaking without one.
+ */
+export const CloakingConfigSchema = z.object({
+  enabled: z.boolean(),
+  /** Strong per-deployment secret. Required when `enabled` is true. */
+  secret: z.string().min(1),
+  /**
+   * Suffix appended to every cloak (e.g. `"irc.example.com"` yields
+   * `<cloak>.irc.example.com`). Defaults to the deployment's `networkName`.
+   */
+  cloakedSuffix: z.string().min(1).optional(),
+});
+
+/**
+ * Per-IP connection-rate limit. Caps how many new connections a single
+ * source IP may open within a sliding `windowMs` window before the
+ * admission gate starts refusing them. Distinct from per-connection
+ * message-rate flood control: this guards the connection acceptance path
+ * rather than individual command flow.
+ */
+export const PerIpConnectionRateSchema = z.object({
+  /** Maximum connections from one IP within `windowMs`. */
+  max: z.number().int().positive(),
+  /** Sliding window length in milliseconds. */
+  windowMs: z.number().int().positive(),
+});
+
+/**
+ * Per-connection message-rate flood control (token bucket). Caps how many
+ * commands a single established connection may send in a burst before the
+ * server disconnects it with the canonical "Excess Flood" reason. Distinct
+ * from the per-IP connection admission rate: this bounds individual command
+ * flow on an already-admitted connection.
+ *
+ * Only the numeric knobs live here. The per-command cost is a function and
+ * cannot be serialized from a config store, so the actor wires the
+ * control-plane exemption (`PING`/`PONG`/`CAP`/`AUTHENTICATE`/`QUIT`) in
+ * code at construction time.
+ */
+export const FloodControlConfigSchema = z.object({
+  /** Bucket ceiling; the largest burst a fresh connection can sustain. */
+  capacity: z.number().int().positive(),
+  /** Tokens added per wall-clock second. */
+  refillRatePerSecond: z.number().int().nonnegative(),
+  /**
+   * How far the bucket may go negative before the wrapper disconnects.
+   * `0` kills on the first over-rate message; larger values grant slack.
+   */
+  disconnectThreshold: z.number().int().nonnegative(),
+});
+
+/**
+ * Documented default bucket. Tolerates a short interactive burst while
+ * killing an obvious flood. Matches the canonical fixture used throughout
+ * the flood-control test suite (capacity 10, 1 token/sec, no slack).
+ */
+export const DEFAULT_FLOOD_CONTROL_CONFIG: {
+  capacity: number;
+  refillRatePerSecond: number;
+  disconnectThreshold: number;
+} = {
+  capacity: 10,
+  refillRatePerSecond: 1,
+  disconnectThreshold: 0,
+};
+
+/**
+ * The full server-config schema. Optional fields default to deployment-
+ * sensible values so a minimal `{ serverName, networkName }` config is
+ * enough to boot; production deployments override the defaults.
+ */
+export const ServerConfigSchema = z.object({
+  /** Server hostname shown in numerics (`:serverName 001 nick ...`). */
+  serverName: z.string().min(1),
+  /** Network name advertised in `005 NETWORK=...` and WHOIS replies. */
+  networkName: z.string().min(1),
+
+  /**
+   * Server password. Empty string or undefined disables the password
+   * gate. When set, every connection must supply the same value via
+   * `PASS <password>` (or SASL PLAIN) before registration completes.
+   */
+  serverPassword: z.string().optional(),
+
+  /**
+   * Hostmask cloaking. When enabled, real client IPs are replaced by a
+   * deterministic cloak derived from `secret` + the source IP. Omit to
+   * disable cloaking entirely (the default).
+   */
+  cloaking: CloakingConfigSchema.optional(),
+
+  /**
+   * Maximum simultaneous connections from a single source IP. Enforced at
+   * the admission boundary (the in-memory runtime and CF / AWS adapters).
+   */
+  maxConnectionsPerIp: z.number().int().positive().default(10),
+
+  /**
+   * Maximum simultaneous connections from a single authenticated user
+   * (identified by SASL account, falling back to source IP when no SASL
+   * identity is established). Enforced at the admission boundary.
+   */
+  maxConnectionsPerUser: z.number().int().positive().default(5),
+
+  /**
+   * Per-IP connection-rate limit (sliding window). Caps how fast a single
+   * source IP may open new connections. Distinct from per-connection
+   * message-rate flood control.
+   */
+  perIpConnectionRate: PerIpConnectionRateSchema.default({
+    max: 5,
+    windowMs: 60_000,
+  }),
+
+  /**
+   * Per-connection message-rate flood control. Omit to apply the documented
+   * default bucket ({@link DEFAULT_FLOOD_CONTROL_CONFIG}); set to `null`
+   * explicitly to disable flood control for this deployment (e.g. a trusted
+   * loopback relay that enforces its own limits upstream).
+   */
+  floodControl: FloodControlConfigSchema.nullable().default(DEFAULT_FLOOD_CONTROL_CONFIG),
+
+  /**
+   * Message-of-the-day lines. Empty array => `422 ERR_NOMOTD`.
+   * Adapters typically feed these into a `StaticMotdProvider` at boot.
+   */
+  motdLines: z.array(z.string()).default([]),
+
+  /**
+   * Allowed channel-name prefix sigils (e.g. `#`, `#&+`). The first
+   * character is the canonical prefix advertised via `CHANTYPES` in
+   * the `005` reply.
+   */
+  channelPrefixes: z.string().min(1).default('#'),
+
+  /**
+   * Maximum simultaneous client connections this deployment will admit.
+   * Adapters enforce the cap at the `$connect` / WS-upgrade boundary.
+   */
+  maxClients: z.number().int().positive().default(10_000),
+
+  /**
+   * IRC operator credentials. The adapter's OPER auth path consults
+   * these; empty array disables OPER entirely.
+   */
+  operCreds: z.array(OperCredSchema).default([]),
+
+  /**
+   * SASL PLAIN account credentials. The adapter seeds an
+   * `InMemoryAccountStore` from this list at boot so `AUTHENTICATE PLAIN`
+   * succeeds end-to-end for the listed accounts. Empty array (the default)
+   * disables SASL account verification: `ctx.accounts` is then omitted and
+   * a client completing `AUTHENTICATE PLAIN` receives `904 ERR_SASLFAIL`.
+   * A persistent variant (DynamoDB `Accounts`, D1) is a documented
+   * follow-up; swapping it in means replacing the construction call.
+   */
+  saslAccounts: z.array(SaslAccountSchema).default([]),
+
+  // --- Reducer-facing limit knobs (mirrored on `ServerConfig`) ---
+
+  /** Maximum channels a single connection may JOIN. */
+  maxChannelsPerUser: z.number().int().positive().default(30),
+  /** Maximum targets per PRIVMSG/NOTICE/KICK command. */
+  maxTargetsPerCommand: z.number().int().positive().default(10),
+  /** Maximum entries returned by LIST/NAMES/ban-list queries. */
+  maxListEntries: z.number().int().nonnegative().default(50),
+  /** Maximum nickname length (advertised as `NICKLEN=`). */
+  nickLen: z.number().int().positive().default(30),
+  /** Maximum channel-name length (advertised as `CHANNELLEN=`). */
+  channelLen: z.number().int().positive().default(50),
+  /** Maximum topic length (advertised as `TOPICLEN=`). */
+  topicLen: z.number().int().nonnegative().default(390),
+  /** Default QUIT reason when the client disconnects without one. */
+  quitMessage: z.string().default('Client Quit'),
+
+  /**
+   * Maximum number of back-log messages replayed on JOIN for clients that
+   * negotiated `draft/chathistory`. The IRCv3 spec recommends 50; raise or
+   * lower per deployment. Only consulted when a MessageStore is bound.
+   */
+  chatHistoryPlaybackLimit: z.number().int().positive().default(50),
+});
+
+/** Input type: what adapters supply (fields with defaults may be omitted). */
+export type ServerConfigInput = z.input<typeof ServerConfigSchema>;
+
+/** Output type: what the schema yields post-parse (all fields populated). */
+export type ParsedServerConfig = z.output<typeof ServerConfigSchema>;
+
+/**
+ * Parses a raw config value against {@link ServerConfigSchema}, applying
+ * defaults and throwing a single aggregated {@link Error} on failure.
+ *
+ * Adapters call this exactly once at boot. The thrown message names every
+ * invalid field so operators can fix the config without round-tripping
+ * through Zod's error tree.
+ *
+ * @throws {Error} when `input` fails schema validation. The message
+ *   starts with "Invalid server config" and lists every offending field.
+ */
+export function parseServerConfig(input: unknown): ParsedServerConfig {
+  const result = ServerConfigSchema.safeParse(input);
+  if (!result.success) {
+    const lines = result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+      return `  - ${path}: ${issue.message}`;
+    });
+    throw new Error(`Invalid server config:\n${lines.join('\n')}`);
+  }
+  return result.data;
+}
+
+/**
+ * Default server config: the result of parsing an empty input. Useful as a
+ * known-good baseline for tests and for adapters that want to overlay
+ * per-deployment overrides via object spread.
+ */
+export const DEFAULT_SERVER_CONFIG: ParsedServerConfig = ServerConfigSchema.parse({
+  serverName: 'irc.example.com',
+  networkName: 'ServerlessIRCd',
+});

package/packages/irc-core/src/flood-control.ts

@@ -0,0 +1,175 @@
+/**
+ * Flood control as a pure higher-order reducer wrapper.
+ *
+ * Wraps any {@link Reducer} with a per-connection token bucket. The bucket is
+ * refilled using the injected {@link Clock} (deterministic — never
+ * `Date.now()`), stored on `ctx.connection.floodBucket`, and consulted
+ * before the inner reducer is invoked.
+ *
+ * On a healthy message the inner reducer is called and its
+ * `{ state, effects }` is passed through untouched. When the bucket crosses
+ * the configured negative threshold the wrapper short-circuits with a
+ * `Disconnect("Excess Flood")` effect (RFC 2812 §6 canonical reason) and
+ * does NOT call the inner reducer — matching the behaviour of mainstream
+ * IRC daemons (hybrid, charybdis, Unreal).
+ *
+ * The wrapper is generic over the inner reducer's state type: the bucket
+ * lives on `ctx.connection`, so this works for connection-authority
+ * reducers (`Reducer<ConnectionState>`) and channel-authority reducers
+ * (`Reducer<ChannelState>`) alike.
+ *
+ * Determinism invariant: given the same `Clock` readings and the same
+ * message stream the pass-through vs. disconnect decision is identical.
+ * There are no ambient inputs.
+ */
+
+import { Effect } from './effects.js';
+import type { FloodBucketState } from './state/connection.js';
+import type { Reducer } from './types.js';
+
+/** Canonical IRC quit reason for flooding (RFC 2812 §6). */
+export const EXCESS_FLOOD_REASON = 'Excess Flood';
+
+/**
+ * Token-bucket parameters. Tune per deployment via the wrapper factory; the
+ * wrapper does not read `ServerConfig` so existing config literals are
+ * untouched.
+ */
+export interface FloodControlConfig {
+  /** Bucket ceiling; the largest burst a fresh connection can sustain. */
+  capacity: number;
+  /** Tokens added per wall-clock second. */
+  refillRatePerSecond: number;
+  /**
+   * How far the bucket may go negative before the wrapper disconnects.
+   * `0` means the first over-rate message kills; larger values grant slack
+   * (e.g. `2` tolerates two messages past capacity before disconnecting).
+   */
+  disconnectThreshold: number;
+  /**
+   * Optional pure function returning the token cost of a command. The
+   * command is the parsed `IrcMessage.command`, already uppercased by the
+   * parser, so case-insensitivity is handled once upstream.
+   *
+   * When omitted, every command is charged the flat {@link MESSAGE_COST}
+   * (`1`) — i.e. the original wrapper behaviour is preserved bit-for-bit.
+   * Compose with {@link defaultCommandCost} to exempt control-plane
+   * traffic (`PING`/`PONG`/`CAP`/`AUTHENTICATE`/`QUIT`).
+   *
+   * A cost of `0` neither decrements the bucket nor triggers the disconnect
+   * path; the inner reducer is called as normal. Negative costs are rejected
+   * at wrapper-construction time — they would invert the bucket.
+   */
+  commandCost?: (command: string) => number;
+}
+
+/**
+ * Control-plane commands that mainstream ircds (charybdis, hybrid, Unreal) exempt
+ * from flood control. A client exchanging `PING`/`PONG` with the server or
+ * negotiating `CAP` / `AUTHENTICATE` during SASL must not flood itself out
+ * through no fault of its own.
+ *
+ * Override the set by composing your own cost function on top of this one.
+ */
+const EXEMPT_COMMANDS: ReadonlySet<string> = new Set([
+  'PING',
+  'PONG',
+  'CAP',
+  'AUTHENTICATE',
+  'QUIT',
+]);
+
+/**
+ * Ready-made per-command cost: `0` for the exempt control-plane set, `1`
+ * otherwise. Pass this as `FloodControlConfig.commandCost` to get sensible
+ * mainstream-ircd behaviour, or compose your own function to override the
+ * exempt set.
+ */
+export function defaultCommandCost(command: string): number {
+  return EXEMPT_COMMANDS.has(command) ? 0 : 1;
+}
+
+/** Cost charged for every message when no `commandCost` override is given. */
+const MESSAGE_COST = 1;
+
+/**
+ * Command used to probe a caller-supplied `commandCost` at wrapper-construction
+ * time for the negative-cost rejection. The parser uppercases commands, so the
+ * probe uses a canonical charged command.
+ */
+const COST_PROBE_COMMAND = 'PRIVMSG';
+
+/**
+ * Returns the post-refill token count at a given moment, capped at
+ * `capacity`. Pure — does not mutate the bucket.
+ */
+function refillTokens(bucket: FloodBucketState, now: number, config: FloodControlConfig): number {
+  const elapsedSec = Math.max(0, (now - bucket.lastRefill) / 1_000);
+  return Math.min(config.capacity, bucket.tokens + elapsedSec * config.refillRatePerSecond);
+}
+
+/**
+ * Pure computation of the next bucket balance after refilling and deducting
+ * the per-command cost. Shared by the pass-through and disconnect branches so
+ * they can never diverge. Lazily initializes the bucket to `capacity` tokens
+ * on the first observed message.
+ */
+function computeNextBalance(
+  previous: FloodBucketState | undefined,
+  now: number,
+  cost: number,
+  config: FloodControlConfig,
+): FloodBucketState {
+  const refilled = previous === undefined ? config.capacity : refillTokens(previous, now, config);
+  return { tokens: refilled - cost, lastRefill: now };
+}
+
+/**
+ * Wraps `inner` with a per-connection token-bucket flood-control check.
+ *
+ * The returned reducer:
+ *   1. Derives the per-command cost via `config.commandCost` (or the flat
+ *      {@link MESSAGE_COST} when omitted).
+ *   2. Lazily initializes `ctx.connection.floodBucket` to `capacity` tokens
+ *      on the first observed message.
+ *   3. Refills the bucket using `ctx.clock.now()` and deducts the cost.
+ *   4. Decides: if the new balance is at or above `-disconnectThreshold`,
+ *      delegates to `inner` (pass-through). Otherwise emits
+ *      `Disconnect("Excess Flood")` and skips `inner`.
+ *
+ * A command whose cost is `0` never trips the disconnect branch (the balance
+ * is unchanged after refill) and the inner reducer runs as normal.
+ *
+ * The bucket is updated in place on `ctx.connection` so subsequent invocations
+ * observe the new balance — this is the same in-place mutation pattern other
+ * connection-authority reducers use (e.g. `lastSeen` updates).
+ *
+ * Throws synchronously if `config.commandCost` returns a negative value for
+ * the probe command, since negative costs would invert the bucket.
+ */
+export function wrapWithFloodControl<S>(inner: Reducer<S>, config: FloodControlConfig): Reducer<S> {
+  const costOf = config.commandCost ?? (() => MESSAGE_COST);
+  if (config.commandCost !== undefined && config.commandCost(COST_PROBE_COMMAND) < 0) {
+    throw new Error(
+      'FloodControlConfig.commandCost returned a negative cost; costs must be non-negative',
+    );
+  }
+
+  return (state, msg, ctx) => {
+    const now = ctx.clock.now();
+    const conn = ctx.connection;
+
+    const cost = costOf(msg.command);
+    const next = computeNextBalance(conn.floodBucket, now, cost, config);
+    conn.floodBucket = next;
+
+    if (next.tokens < -config.disconnectThreshold) {
+      return {
+        state,
+        effects: [Effect.disconnect(conn.id, EXCESS_FLOOD_REASON)],
+      };
+    }
+
+    return inner(state, msg, ctx);
+  };
+}

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

@@ -10,9 +10,16 @@ export * from './caps/index.js';
 export * from './commands/index.js';
 export * from './effects.js';
 export * from './ports.js';
+export * from './flood-control.js';
+export * from './cloak.js';
+export * from './case-fold.js';
+export * from './admission.js';
+export * from './config.js';
 export type {
   BuildCtxOptions,
+  CloakingConfig,
   Ctx,
+  OperCred,
   Reducer,
   ReducerResult,
   ServerConfig,