serverless-ircd 0.1.0 → 0.3.0

package/packages/in-memory-runtime/tests/in-memory-runtime.test.ts

@@ -1,4 +1,6 @@
 import {
+  type AdmissionConfig,
+  type AdmissionDecision,
   type ChannelDelta,
   type ConnectionState,
   FakeClock,
@@ -225,6 +227,14 @@ describe('InMemoryRuntime — applyChannelDelta / getChannelSnapshot', () => {
     expect(snap?.members.has('c1')).toBe(true);
   });
 
+  it('treats rfc1459 special chars [ \\ ] ^ as equal to { | } ~', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const a = rt.getOrCreateChannel('#[Foo]');
+    const b = rt.getOrCreateChannel('#{foo}');
+    expect(b).toBe(a);
+    expect(b.nameLower).toBe('#{foo}');
+  });
+
   it('returns null from getChannelSnapshot for an unknown channel', async () => {
     const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
     expect(await rt.getChannelSnapshot('#nope')).toBeNull();
@@ -500,3 +510,127 @@ describe('InMemoryRuntime — connection lifecycle', () => {
     expect(rt.getOrCreateChannel('#foo')).toBe(chan);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Admission gate
+// ---------------------------------------------------------------------------
+
+/** Strict per-IP cap, generous everything else, for isolated per-IP tests. */
+const IP_CAP_ONLY: AdmissionConfig = {
+  maxConnectionsPerIp: 2,
+  maxConnectionsPerUser: 100,
+  perIpConnectionRate: { max: 1_000, windowMs: 10_000 },
+};
+
+/** Strict per-user cap, generous everything else, for isolated per-user tests. */
+const USER_CAP_ONLY: AdmissionConfig = {
+  maxConnectionsPerIp: 100,
+  maxConnectionsPerUser: 2,
+  perIpConnectionRate: { max: 1_000, windowMs: 10_000 },
+};
+
+/** Strict rate limit, generous caps, for isolated rate-limit tests. */
+const RATE_ONLY: AdmissionConfig = {
+  maxConnectionsPerIp: 100,
+  maxConnectionsPerUser: 100,
+  perIpConnectionRate: { max: 2, windowMs: 10_000 },
+};
+
+describe('InMemoryRuntime — admission gate', () => {
+  it('admits the first connection from an IP when a policy is configured', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0), admission: IP_CAP_ONLY });
+    const decision = rt.admitConnection('1.2.3.4', undefined);
+    expect(decision.ok).toBe(true);
+    if (decision.ok) rt.commitAdmission('1.2.3.4', undefined, decision.recordId);
+  });
+
+  it('rejects a connection exceeding the per-IP cap', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0), admission: IP_CAP_ONLY });
+    for (let i = 0; i < 2; i++) {
+      const d = rt.admitConnection('1.1.1.1', `u${i}`);
+      if (d.ok) rt.commitAdmission('1.1.1.1', `u${i}`, d.recordId);
+    }
+    const third = rt.admitConnection('1.1.1.1', 'u2');
+    expect(third.ok).toBe(false);
+    if (!third.ok) expect(third.reason).toBe('max_connections_per_ip');
+  });
+
+  it('rejects a connection exceeding the per-user cap', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0), admission: USER_CAP_ONLY });
+    for (let i = 0; i < 2; i++) {
+      const d = rt.admitConnection(`10.0.0.${i}`, 'alice');
+      if (d.ok) rt.commitAdmission(`10.0.0.${i}`, 'alice', d.recordId);
+    }
+    const third = rt.admitConnection('10.0.0.9', 'alice');
+    expect(third.ok).toBe(false);
+    if (!third.ok) expect(third.reason).toBe('max_connections_per_user');
+  });
+
+  it('rejects a connection exceeding the per-IP rate cap', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0), admission: RATE_ONLY });
+    for (let i = 0; i < 2; i++) {
+      const d = rt.admitConnection('5.5.5.5', `u${i}`);
+      if (d.ok) rt.commitAdmission('5.5.5.5', `u${i}`, d.recordId);
+    }
+    const third = rt.admitConnection('5.5.5.5', 'u2');
+    expect(third.ok).toBe(false);
+    if (!third.ok) expect(third.reason).toBe('rate_limited_per_ip');
+  });
+
+  it('releaseAdmission decrements counters so subsequent admissions succeed', () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0), admission: IP_CAP_ONLY });
+    const d1 = rt.admitConnection('1.1.1.1', 'alice');
+    expect(d1.ok).toBe(true);
+    if (!d1.ok) return;
+    rt.commitAdmission('1.1.1.1', 'alice', d1.recordId);
+    const d2 = rt.admitConnection('1.1.1.1', 'alice');
+    expect(d2.ok).toBe(true);
+    if (!d2.ok) return;
+    rt.commitAdmission('1.1.1.1', 'alice', d2.recordId);
+    expect(rt.admitConnection('1.1.1.1', 'alice').ok).toBe(false);
+    rt.releaseAdmission(d1.recordId);
+    expect(rt.admitConnection('1.1.1.1', 'alice').ok).toBe(true);
+  });
+
+  it('unregisterConnection releases the admission record so the IP slot is freed', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0), admission: IP_CAP_ONLY });
+    const conn = makeConn('c1', 'alice');
+    // Simulate the local-CLI admission flow: admit, commit, register, and
+    // pair the record id with the connection for later release.
+    const d = rt.admitConnection('9.9.9.9', 'alice');
+    expect(d.ok).toBe(true);
+    if (!d.ok) return;
+    rt.commitAdmission('9.9.9.9', 'alice', d.recordId);
+    rt.registerConnection(conn, { send: () => {}, disconnect: () => {} }, d.recordId);
+    // IP slot now holds one connection.
+    const second = rt.admitConnection('9.9.9.9', 'bob');
+    expect(second.ok).toBe(true);
+    if (second.ok) rt.commitAdmission('9.9.9.9', 'bob', second.recordId);
+    // Third would exceed per-IP cap of 2.
+    expect(rt.admitConnection('9.9.9.9', 'carol').ok).toBe(false);
+    // Unregistering c1 frees its slot (the runtime releases the paired record).
+    rt.unregisterConnection('c1');
+    const fourth = rt.admitConnection('9.9.9.9', 'carol');
+    expect(fourth.ok).toBe(true);
+  });
+
+  it('returns an admit decision when no admission policy is configured (gate disabled)', () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const decisions: AdmissionDecision[] = [];
+    for (let i = 0; i < 100; i++) {
+      decisions.push(rt.admitConnection('1.1.1.1', 'alice'));
+    }
+    expect(decisions.every((d) => d.ok)).toBe(true);
+  });
+
+  it('returns a stable recordId when admission is disabled (no per-call minting)', () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const d1 = rt.admitConnection('1.1.1.1', 'alice');
+    const d2 = rt.admitConnection('2.2.2.2', 'bob');
+    expect(d1.ok).toBe(true);
+    expect(d2.ok).toBe(true);
+    if (d1.ok && d2.ok) {
+      expect(d1.recordId).toBe(d2.recordId);
+    }
+  });
+});

package/packages/irc-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Platform-agnostic IRC protocol core: parser, serializer, command reducers, state shapes",
   "license": "BSD-3-Clause",
@@ -23,7 +23,18 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
+    "mutation:protocol": "stryker run stryker.protocol.conf.json",
+    "mutation:commands": "stryker run stryker.commands.conf.json",
+    "mutation": "pnpm run mutation:protocol && pnpm run mutation:commands",
     "clean": "rimraf dist coverage .tsbuildinfo .turbo"
   },
-  "files": ["dist", "src", "README.md"]
+  "files": ["dist", "src", "README.md"],
+  "dependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "vitest": "^4.1.0"
+  }
 }

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

@@ -0,0 +1,216 @@
+/**
+ * Connection-admission gate — pure policy + stateful counter.
+ *
+ * Guards the connection acceptance path against three classes of abuse:
+ *
+ *   1. **Per-IP connection cap** (`maxConnectionsPerIp`): caps how many
+ *      simultaneous connections a single source IP may hold. Distinct
+ *      from per-connection flood control: this is the "how many sockets
+ *.     at once" gate, not the "how many commands per socket" gate.
+ *
+ *   2. **Per-user connection cap** (`maxConnectionsPerUser`): same idea,
+ *      keyed by SASL account name when available, falling back to the
+ *      source IP when the connection has not authenticated.
+ *
+ *   3. **Per-IP connection-rate limit** (`perIpConnectionRate`): caps how
+ *      fast a single source IP may open new connections within a sliding
+ *      window. Defends against connection-flood attacks that recycle
+ *      sockets to evade the per-IP cap.
+ *
+ * The policy itself is a pure function {@link decideAdmission}; the
+ * accounting state lives in {@link AdmissionStats}, which is injected so
+ * tests can pin the timeline via {@link FakeClock} and inspect state in
+ * isolation. Both adapters (in-memory runtime, CF / AWS) construct one
+ * `AdmissionStats` per process / per worker invocation and share it
+ * across every connection acceptance decision.
+ *
+ * Determinism: same Clock + same call stream → same decisions. There are
+ * no ambient inputs.
+ */
+
+import type { Clock } from './ports.js';
+
+/**
+ * Static policy consulted by {@link decideAdmission}. Adapters source the
+ * values from `ServerConfig` but the gate consumes this narrow shape so
+ * the unit tests do not need to construct a full config.
+ */
+export interface AdmissionConfig {
+  /** Maximum simultaneous connections from a single source IP. */
+  readonly maxConnectionsPerIp: number;
+  /** Maximum simultaneous connections from a single authenticated user. */
+  readonly maxConnectionsPerUser: number;
+  /** Per-IP connection-rate limit (sliding window). */
+  readonly perIpConnectionRate: { readonly max: number; readonly windowMs: number };
+}
+
+/** Positive admission outcome — caller should {@link AdmissionStats.recordAdmission}. */
+export interface AdmitDecision {
+  readonly ok: true;
+  /**
+   * Opaque record id handed back to {@link AdmissionStats.release} when the
+   * connection terminates. Unique per admission.
+   */
+  readonly recordId: string;
+}
+
+/** Negative admission outcome — the caller MUST close the connection. */
+export interface RejectDecision {
+  readonly ok: false;
+  /** Machine-readable reason code for logs / metrics / `Disconnect` effect. */
+  readonly reason: AdmissionRejectReason;
+}
+
+export type AdmissionRejectReason =
+  | 'max_connections_per_ip'
+  | 'max_connections_per_user'
+  | 'rate_limited_per_ip';
+
+export type AdmissionDecision = AdmitDecision | RejectDecision;
+
+/** Per-IP / per-user / rate counters. Owned by the runtime / adapter. */
+export class AdmissionStats {
+  private readonly clock: Clock;
+  private readonly perIpCount = new Map<string, number>();
+  private readonly perUserCount = new Map<string, number>();
+  /**
+   * Per-IP timestamps of recent admissions, used by the rate-limit check.
+   * Stored ascending; entries older than the window are pruned lazily.
+   */
+  private readonly perIpAdmitTimes = new Map<string, number[]>();
+  /** Reverse index: recordId → { ip, user }, used by {@link release}. */
+  private readonly records = new Map<string, { ip: string; user: string }>();
+  private nextRecordId = 1;
+
+  constructor(clock: Clock) {
+    this.clock = clock;
+  }
+
+  /**
+   * Returns the current per-IP connection count. Exposed for diagnostics
+   * and tests; not used by {@link decideAdmission}.
+   */
+  countForIp(ip: string): number {
+    return this.perIpCount.get(ip) ?? 0;
+  }
+
+  /** Returns the current per-user connection count. */
+  countForUser(user: string): number {
+    return this.perUserCount.get(user) ?? 0;
+  }
+
+  /**
+   * Records an accepted admission. MUST be called exactly once per
+   * successful {@link decideAdmission} so the counters stay accurate.
+   */
+  recordAdmission(ip: string, user: string | undefined, recordId: string): void {
+    const effectiveUser = user ?? ip;
+    this.perIpCount.set(ip, (this.perIpCount.get(ip) ?? 0) + 1);
+    this.perUserCount.set(effectiveUser, (this.perUserCount.get(effectiveUser) ?? 0) + 1);
+    const now = this.clock.now();
+    const times = this.perIpAdmitTimes.get(ip) ?? [];
+    times.push(now);
+    this.perIpAdmitTimes.set(ip, times);
+    this.records.set(recordId, { ip, user: effectiveUser });
+  }
+
+  /**
+   * Releases a previously-recorded admission, decrementing the relevant
+   * counters. Idempotent: releasing an unknown id is a no-op.
+   */
+  release(recordId: string): void {
+    const rec = this.records.get(recordId);
+    if (rec === undefined) return;
+    this.records.delete(recordId);
+
+    const ipCount = this.perIpCount.get(rec.ip);
+    if (ipCount !== undefined) {
+      const next = ipCount - 1;
+      if (next <= 0) this.perIpCount.delete(rec.ip);
+      else this.perIpCount.set(rec.ip, next);
+    }
+    const userCount = this.perUserCount.get(rec.user);
+    if (userCount !== undefined) {
+      const next = userCount - 1;
+      if (next <= 0) this.perUserCount.delete(rec.user);
+      else this.perUserCount.set(rec.user, next);
+    }
+  }
+
+  /**
+   * Returns the number of admissions recorded for `ip` within the last
+   * `windowMs` milliseconds (inclusive of the moment returned by
+   * `clock.now()`). Stale entries are pruned as a side effect.
+   */
+  recentAdmissions(ip: string, windowMs: number): number {
+    const times = this.perIpAdmitTimes.get(ip);
+    if (times === undefined || times.length === 0) return 0;
+    const cutoff = this.clock.now() - windowMs;
+    let writeIdx = 0;
+    for (let i = 0; i < times.length; i++) {
+      const t = times[i];
+      if (t === undefined) continue;
+      if (t >= cutoff) {
+        times[writeIdx++] = t;
+      }
+    }
+    if (writeIdx === 0) {
+      this.perIpAdmitTimes.delete(ip);
+      return 0;
+    }
+    times.length = writeIdx;
+    return writeIdx;
+  }
+
+  /**
+   * Allocates the next unique record id. Public so {@link decideAdmission}
+   * can mint ids without breaking encapsulation.
+   */
+  nextRecord(): string {
+    const id = this.nextRecordId.toString(36);
+    this.nextRecordId += 1;
+    return id;
+  }
+}
+
+/**
+ * Decides whether a new connection should be admitted.
+ *
+ * The check is performed in a fixed precedence order so the rejection
+ * reason is deterministic:
+ *   1. Per-IP connection-rate limit (cheapest to test).
+ *   2. Per-IP simultaneous connection cap.
+ *   3. Per-user simultaneous connection cap.
+ *
+ * On success the caller MUST call {@link AdmissionStats.recordAdmission}
+ * with the returned `recordId` before admitting any further connection;
+ * on failure the caller MUST close the connection.
+ *
+ * The decision is pure with respect to `(ip, user, stats, config)` — same
+ * inputs yield the same outcome, including the assigned `recordId`.
+ */
+export function decideAdmission(
+  ip: string,
+  user: string | undefined,
+  stats: AdmissionStats,
+  config: AdmissionConfig,
+): AdmissionDecision {
+  // 1. Rate limit (per-IP, sliding window).
+  const recent = stats.recentAdmissions(ip, config.perIpConnectionRate.windowMs);
+  if (recent >= config.perIpConnectionRate.max) {
+    return { ok: false, reason: 'rate_limited_per_ip' };
+  }
+
+  // 2. Per-IP cap.
+  if (stats.countForIp(ip) >= config.maxConnectionsPerIp) {
+    return { ok: false, reason: 'max_connections_per_ip' };
+  }
+
+  // 3. Per-user cap (falls back to IP when no SASL identity is present).
+  const effectiveUser = user ?? ip;
+  if (stats.countForUser(effectiveUser) >= config.maxConnectionsPerUser) {
+    return { ok: false, reason: 'max_connections_per_user' };
+  }
+
+  return { ok: true, recordId: stats.nextRecord() };
+}

package/packages/irc-core/src/caps/capabilities.ts

@@ -26,6 +26,7 @@ export const SUPPORTED_CAPABILITIES: ReadonlyArray<Capability> = Object.freeze([
   { name: 'away-notify' },
   { name: 'batch' },
   { name: 'chghost' },
+  { name: 'draft/chathistory' },
   { name: 'echo-message' },
   { name: 'extended-join' },
   { name: 'invite-notify' },

package/packages/irc-core/src/case-fold.ts

@@ -0,0 +1,64 @@
+/**
+ * IRC case-mapping (case folding) for nick and channel-name comparison.
+ *
+ * IRC servers compare nicks and channel names case-insensitively, but the
+ * exact set of characters that fold together is advertised to clients via
+ * the `005 RPL_ISUPPORT` `CASEMAPPING=` token. This module implements the
+ * two relevant mappings:
+ *
+ *   - `ascii`   — only `A`–`Z` fold to `a`–`z`.
+ *   - `rfc1459` — `ascii` plus the four characters `[ \ ] ^` folding to
+ *     `{ | } ~` respectively (per RFC 1459 §2.2). The targets
+ *     `{ | } ~` do NOT fold further, so the fold is idempotent:
+ *     `fold(fold(s)) === fold(s)`.
+ *
+ * The fold operates on one character at a time and leaves every other byte
+ * (including all non-ASCII) unchanged. It is pure and dependency-free so it
+ * runs unchanged on every runtime (Node, Workers, Lambda).
+ *
+ * Advertised via {@link CaseMapping} and consumed by the command reducers
+ * and the reference runtime so that the advertised case-mapping and the
+ * actual folding never diverge.
+ */
+
+/** Case-mapping algorithms supported for IRC-name comparison. */
+export type CaseMapping = 'rfc1459' | 'ascii';
+
+/**
+ * Lowercases `s` according to `mapping`, returning the canonical key used
+ * for case-insensitive nick and channel comparison.
+ *
+ * @param mapping  `rfc1459` (default behaviour everywhere in this server) or
+ *                 `ascii` (a strict subset — useful for strict-ASCII tests).
+ * @param s        The nick or channel name to fold.
+ */
+export function caseFold(mapping: CaseMapping, s: string): string {
+  let out = '';
+  for (let i = 0; i < s.length; i += 1) {
+    out += foldChar(mapping, s.charCodeAt(i));
+  }
+  return out;
+}
+
+/** Folds a single UTF-16 code unit per the active mapping. */
+function foldChar(mapping: CaseMapping, code: number): string {
+  if (code >= 0x41 && code <= 0x5a) {
+    // A–Z → a–z
+    return String.fromCharCode(code + 0x20);
+  }
+  if (mapping === 'rfc1459') {
+    switch (code) {
+      case 0x5b:
+        return '{'; // [ → {
+      case 0x5c:
+        return '|'; // \ → |
+      case 0x5d:
+        return '}'; // ] → }
+      case 0x5e:
+        return '~'; // ^ → ~
+      default:
+        break;
+    }
+  }
+  return String.fromCharCode(code);
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Hostmask cloaking — replaces a client's real source IP with a deterministic
+ * opaque identifier derived from the deployment secret + the IP.
+ *
+ * Goals (matching mainstream IRC daemon behaviour — charybdis / UnrealIRCd):
+ *   - The real IP is never revealed on the wire (in WHOIS, hostmasks, etc.).
+ *   - The same IP + secret always yields the same cloak (so per-IP
+ *     reputation/line enforcement still works).
+ *   - Two different IPs almost never collide.
+ *   - The cloak fits in a single DNS-label-safe segment.
+ *
+ * Implementation note: this uses a self-contained FNV-1a 32-bit hash plus a
+ * short base32 encoding so the module stays pure-TS and runs unchanged on
+ * Node 20, Cloudflare Workers, and Lambda. It is NOT a cryptographic MAC:
+ * an attacker who learns one cloak cannot recover the secret, but a
+ * determined attacker with the secret can forge cloaks. Deployments that
+ * need stronger unforgeability should override this module.
+ */
+
+import type { CloakingConfig } from './types.js';
+
+/**
+ * Returns the visible host for `realHost` after applying the deployment's
+ * cloaking policy.
+ *
+ *   - When `config.enabled === false`, `realHost` is returned verbatim.
+ *   - When `config.enabled === true`, a deterministic cloak of the form
+ *     `<hash>.<suffix>` is returned. The `<hash>` segment is derived from
+ *     `secret` + `realHost`; the `<suffix>` defaults to `defaultSuffix`
+ *     (typically the deployment's `networkName` lowercased) and may be
+ *     overridden via `config.cloakedSuffix`.
+ *
+ * The function is pure — same inputs always yield the same output. There
+ * is no ambient randomness or clock.
+ *
+ * @param realHost       The connection's real source IP (or any host string).
+ * @param config         Cloaking policy. See {@link CloakingConfig}.
+ * @param defaultSuffix  Suffix used when `config.cloakedSuffix` is absent.
+ */
+export function cloakHost(realHost: string, config: CloakingConfig, defaultSuffix: string): string {
+  if (!config.enabled) return realHost;
+  const suffix = config.cloakedSuffix ?? defaultSuffix;
+  // 64-bit hash assembled from two FNV-1a passes with different seeds so
+  // distinct IPs collide with probability ~ 1 / 2^64.
+  const hi = fnv1a32(`a:${config.secret}:${realHost}`);
+  const lo = fnv1a32(`b:${config.secret}:${realHost}`);
+  return `${base32(hi)}${base32(lo)}.${suffix}`;
+}
+
+/**
+ * FNV-1a 32-bit hash. Self-contained: no Node `crypto`, works on every
+ * serverless runtime. Output is an unsigned 32-bit integer.
+ */
+function fnv1a32(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    // 32-bit multiply by FNV prime using Math.imul to stay in u32 space.
+    h = Math.imul(h, 0x01000193);
+  }
+  // Force unsigned.
+  return h >>> 0;
+}
+
+/**
+ * Lowercase base32 (RFC 4648) encoding without padding, suitable for a
+ * DNS-safe identifier. Encodes 5 bits per character.
+ */
+const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+
+function base32(value: number): string {
+  // 32 bits -> 7 base32 chars (ceil(32/5) = 7 with one bit of padding,
+  // but we don't emit padding so 7 chars is the canonical length here).
+  let out = '';
+  let v = value;
+  for (let i = 0; i < 7; i++) {
+    out += BASE32_ALPHABET[v & 0x1f];
+    v = Math.floor(v / 32);
+  }
+  return out;
+}

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

@@ -199,8 +199,7 @@ function handleReq(
  */
 function handleEnd(state: ConnectionState, ctx: Ctx): ReducerResult<ConnectionState> {
   state.capNegotiating = false;
-  const welcome = emitWelcomeIfReady(state, ctx);
-  return { state, effects: welcome !== null ? [welcome] : [] };
+  return { state, effects: emitWelcomeIfReady(state, ctx) };
 }
 
 /**