serverless-ircd 0.1.0 → 0.3.0

package/packages/irc-core/src/protocol/base64.ts

@@ -0,0 +1,16 @@
+/**
+ * Typed base64 helpers backed by the global `atob` / `btoa` available on
+ * every supported runtime (Node 16+, Cloudflare Workers, browsers). The
+ * project pins `lib: ES2022` which omits these names from the type table,
+ * so this module re-exports them with proper signatures.
+ */
+
+/** Decodes a base64 string to a Latin1/binary string (char per byte). */
+export function decodeBase64(input: string): string {
+  return (globalThis as unknown as { atob: (s: string) => string }).atob(input);
+}
+
+/** Encodes a Latin1/binary string (char per byte, 0–255) to base64. */
+export function encodeBase64(input: string): string {
+  return (globalThis as unknown as { btoa: (s: string) => string }).btoa(input);
+}

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

@@ -1,5 +1,5 @@
 export type { IrcMessage, IrcSource } from './messages.js';
-export { IrcParseError, parse, unescapeTagValue } from './parser.js';
+export { MAX_INPUT_BYTES, IrcParseError, parse, unescapeTagValue } from './parser.js';
 export { escapeTagValue, serialize, serializeFrame } from './serializer.js';
 export {
   MAX_LINE_BYTES,
@@ -9,6 +9,7 @@ export {
   formatServerTime,
 } from './outbound.js';
 export { wrapBatch, type BatchFrame } from './batch.js';
+export { decodeBase64, encodeBase64 } from './base64.js';
 export {
   formatNumeric,
   isNumericCommand,

package/packages/irc-core/src/protocol/numerics.ts

@@ -77,6 +77,17 @@ export const Numerics = {
   RPL_YOURESERVICE: 383,
   RPL_TIME: 391,
 
+  // SASL (IRCv3 sasl-3.2)
+  RPL_LOGGEDIN: 900,
+  RPL_LOGGEDOUT: 901,
+  ERR_NICKLOCKED: 902,
+  RPL_SASLSUCCESS: 903,
+  ERR_SASLFAIL: 904,
+  ERR_SASLTOOLONG: 905,
+  ERR_SASLABORT: 906,
+  ERR_SASLALREADY: 907,
+  ERR_SASLMECHS: 908,
+
   // Errors
   ERR_NOSUCHNICK: 401,
   ERR_NOSUCHSERVER: 402,

package/packages/irc-core/src/protocol/parser.ts

@@ -16,6 +16,19 @@ export class IrcParseError extends Error {
   }
 }
 
+/**
+ * RFC 1459 §2.3: maximum IRC message length in bytes. The spec counts the
+ * trailing CR-LF as part of the 512 budget; the parser strips CR-LF first,
+ * so this constant caps the post-strip body. Adopted verbatim by the
+ * output side (`outbound.ts` `MAX_LINE_BYTES`) — the same number everywhere
+ * so the wire contract reads "no IRC message exceeds 512 bytes".
+ *
+ * Applied to inputs as a hard cap: a single line longer than this is a
+ * protocol violation (the client is misbehaving or a downstream framer is
+ * broken) and is rejected with `IrcParseError` rather than parsed.
+ */
+export const MAX_INPUT_BYTES = 512;
+
 const TAG_ESCAPES: Readonly<Record<string, string>> = {
   ':': ';',
   s: ' ',
@@ -97,11 +110,23 @@ const COMMAND_RE = /^(?:[A-Za-z]+|[0-9]{3})$/;
 export function parse(line: string): IrcMessage {
   // Strip any trailing CR/LF (frame tolerance for ws text frames or TCP lines).
   const stripped = line.replace(/[\r\n]+$/u, '');
-  let rest = stripped;
-  if (rest.length === 0) {
+  if (stripped.length === 0) {
     throw new IrcParseError('empty message', line);
   }
 
+  // RFC 1459 §2.3 hard cap: reject any single message whose post-CRLF body
+  // exceeds {@link MAX_INPUT_BYTES} bytes. Prevents memory and processing
+  // abuse from over-long inputs and matches the symmetric cap enforced on
+  // outbound lines by `outbound.ts`.
+  if (stripped.length > MAX_INPUT_BYTES) {
+    throw new IrcParseError(
+      `message exceeds ${MAX_INPUT_BYTES}-byte input cap (${stripped.length} bytes)`,
+      line,
+    );
+  }
+
+  let rest = stripped;
+
   let tags: Record<string, string> = {};
   if (rest.startsWith('@')) {
     const space = rest.indexOf(' ');

package/packages/irc-core/src/state/connection.ts

@@ -29,6 +29,20 @@ export interface UserModes {
   serverNotices: boolean;
 }
 
+/**
+ * Per-connection token bucket used by the flood-control wrapper.
+ *
+ * Lazily initialized on the first observed message. `tokens` may go negative
+ * down to the configured `-disconnectThreshold`; once it crosses that line
+ * the wrapper emits `Disconnect("Excess Flood")`.
+ */
+export interface FloodBucketState {
+  /** Current token balance; may be negative up to `-threshold`. */
+  tokens: number;
+  /** Epoch ms of the last refill (source: injected `Clock`). */
+  lastRefill: number;
+}
+
 /**
  * Mutable, authoritative per-connection state.
  *
@@ -50,6 +64,19 @@ export interface ConnectionState {
   passAttempt?: string;
   /** SASL-authenticated account name, if any. */
   account?: string;
+  /**
+   * SASL mechanism currently being negotiated. Set on `AUTHENTICATE <MECH>`
+   * and cleared on success, failure, or abort. While set, the connection
+   * expects the next `AUTHENTICATE` frame to carry (or continue) the
+   * mechanism's payload.
+   */
+  saslMech?: string;
+  /**
+   * Buffered SASL payload chunks for multi-line `AUTHENTICATE` frames.
+   * Populated when the client splits a payload across `>400`-byte chunks
+   * and consumed once the final short chunk (or `+`) arrives.
+   */
+  saslBuffer?: string;
   registration: RegistrationState;
   /**
    * True once the client has sent `CAP LS` or `CAP REQ` and not yet sent
@@ -68,6 +95,20 @@ export interface ConnectionState {
   lastSeen: number;
   /** Connect-time epoch ms (drives WHOIS signon time). */
   connectedSince: number;
+  /**
+   * Per-connection token bucket consulted by the flood-control wrapper
+   * (`wrapWithFloodControl`). Absent until the wrapper sees its first
+   * message, so existing persisted state migrates without a schema bump.
+   */
+  floodBucket?: FloodBucketState;
+  /**
+   * Per-channel "last read" msgid marker for IRCv3 `draft/chathistory`
+   * playback. Keyed by lowercased channel name; the value is the msgid of
+   * the most recent message replayed (on JOIN) or queried (on CHATHISTORY).
+   * Subsequent JOINs only replay messages newer than this marker, so a
+   * PART/re-JOIN cycle with no new activity replays nothing.
+   */
+  lastReadMarkers?: Map<string, string>;
 }
 
 /**

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

@@ -7,10 +7,35 @@
  */
 
 import type { Effect } from './effects.js';
-import type { Clock, IdFactory, MotdProvider } from './ports.js';
+import type { FloodControlConfig } from './flood-control.js';
+import type { AccountStore, Clock, IdFactory, MessageStore, MotdProvider } from './ports.js';
 import type { IrcMessage } from './protocol/messages.js';
 import type { ConnectionState } from './state/connection.js';
 
+/**
+ * Hostmask cloaking configuration as seen by reducers. Mirrors the
+ * {@link ServerConfigSchema} shape; reducers only read these fields.
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface CloakingConfig {
+  readonly enabled: boolean;
+  readonly secret: string;
+  readonly cloakedSuffix?: string | undefined;
+}
+
+/**
+ * A single IRC operator credential. The {@link operReducer} consults the
+ * configured list to authenticate `OPER <name> <password>`. Both fields are
+ * compared verbatim; adapters are responsible for any hashing at the auth
+ * boundary if they layer one on top.
+ */
+export interface OperCred {
+  readonly user: string;
+  readonly password: string;
+}
+
 /**
  * Per-deployment server configuration. Adapters load this from a KV store
  * (CF) or Secrets Manager / SSM (AWS); the core only reads it.
@@ -21,6 +46,35 @@ import type { ConnectionState } from './state/connection.js';
 export interface ServerConfig {
   serverName: string;
   networkName: string;
+  /**
+   * Server password gate. Empty string or undefined disables enforcement.
+   * When set, registration refuses to complete until the connection
+   * supplies the matching value via `PASS`.
+   *
+   * Typed `string | undefined` (rather than just `string`) so the field is
+   * structurally compatible with Zod's `ServerConfigSchema` output under
+   * `exactOptionalPropertyTypes: true` — `.optional()` yields `T | undefined`.
+   */
+  readonly serverPassword?: string | undefined;
+  /**
+   * Cloaking config. Undefined when cloaking is disabled (the default);
+   * reducers consult `enabled` + `secret` to compute the visible host.
+   *
+   * Typed `CloakingConfig | undefined` to mirror Zod's `.optional()` output
+   * (see `serverPassword` note).
+   */
+  readonly cloaking?: CloakingConfig | undefined;
+  /**
+   * IRC operator credentials consulted by the `OPER` reducer. `undefined`
+   * (or an empty array) disables oper authentication entirely — an `OPER`
+   * attempt then receives `491 ERR_NOOPERHOST`.
+   *
+   * Typed `ReadonlyArray<OperCred> | undefined` to mirror Zod's `.optional()`
+   * output under `exactOptionalPropertyTypes: true`; the parsed config always
+   * supplies an array (defaulting to `[]`), so a parsed config is assignable
+   * here.
+   */
+  readonly operCreds?: ReadonlyArray<OperCred> | undefined;
   maxChannelsPerUser: number;
   maxTargetsPerCommand: number;
   maxListEntries: number;
@@ -28,6 +82,24 @@ export interface ServerConfig {
   channelLen: number;
   topicLen: number;
   quitMessage: string;
+  /**
+   * Per-connection message-rate flood control. `undefined` → the actor
+   * applies the documented default bucket; `null` → flood control disabled;
+   * an object → use those thresholds. The optional `commandCost` is wired
+   * in code when absent (control-plane commands are exempt by default) — it
+   * cannot be serialized from a config store.
+   */
+  readonly floodControl?: FloodControlConfig | null | undefined;
+  /**
+   * Maximum number of back-messages replayed on JOIN when the joiner has
+   * negotiated `draft/chathistory`. Defaults to 50 per the spec's
+   * recommendation when omitted. Only consulted when a {@link MessageStore}
+   * is bound.
+   *
+   * Typed `number | undefined` to mirror Zod's optional output shape under
+   * `exactOptionalPropertyTypes: true`.
+   */
+  chatHistoryPlaybackLimit?: number | undefined;
 }
 
 /** Per-invocation context handed to every reducer. */
@@ -41,6 +113,15 @@ export interface Ctx {
   readonly ids: IdFactory;
   /** Pre-loaded MOTD source for the `MOTD` reducer. */
   readonly motd: MotdProvider;
+  /** SASL account verification source (absent when no accounts are configured). */
+  readonly accounts?: AccountStore;
+  /**
+   * Chat-history persistence source (absent when chathistory playback is
+   * disabled for this deployment). When present, the PRIVMSG/NOTICE channel
+   * reducers record every accepted message and JOIN replays the backlog for
+   * cap-enabled joiners.
+   */
+  readonly messages?: MessageStore;
   /** The connection invoking the command. Reducers mutate this freely. */
   readonly connection: ConnectionState;
   /** Convenience: `connection.id`. */
@@ -65,12 +146,14 @@ export interface BuildCtxOptions {
   clock: Clock;
   ids: IdFactory;
   motd: MotdProvider;
+  accounts?: AccountStore;
+  messages?: MessageStore;
   connection: ConnectionState;
 }
 
 /** Constructs a {@link Ctx} from the required parts. */
 export function buildCtx(opts: BuildCtxOptions): Ctx {
-  return {
+  const ctx: Ctx = {
     serverConfig: opts.serverConfig,
     serverName: opts.serverConfig.serverName,
     networkName: opts.serverConfig.networkName,
@@ -79,5 +162,8 @@ export function buildCtx(opts: BuildCtxOptions): Ctx {
     motd: opts.motd,
     connection: opts.connection,
     connId: opts.connection.id,
+    ...(opts.accounts !== undefined ? { accounts: opts.accounts } : {}),
+    ...(opts.messages !== undefined ? { messages: opts.messages } : {}),
   };
+  return ctx;
 }

package/packages/irc-core/stryker.commands.conf.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "_comment": "Mutation-testing spot-check for irc-core/commands (coverage gate hardening). Targets every IRC command reducer shipped in Phase 1 (PING/USER/JOIN/PRIVMSG/MODE/KICK/INVITE/WHO/WHOIS/LIST/CAP/SASL/ISUPPORT/MOTD/CHATHISTORY/...). Reuses vitest as the test runner and asserts a mutation score >=80% (see tools/ci-hardening/src/validate.ts for the canonical threshold).",
+  "packageManager": "npm",
+  "testRunner": "vitest",
+  "plugins": ["@stryker-mutator/vitest-runner"],
+  "coverageAnalysis": "off",
+  "mutate": [
+    "src/commands/ping.ts",
+    "src/commands/quit.ts",
+    "src/commands/registration.ts",
+    "src/commands/join.ts",
+    "src/commands/part.ts",
+    "src/commands/privmsg.ts",
+    "src/commands/topic.ts",
+    "src/commands/names.ts",
+    "src/commands/motd.ts",
+    "src/commands/mode.ts",
+    "src/commands/kick.ts",
+    "src/commands/invite.ts",
+    "src/commands/who.ts",
+    "src/commands/whois.ts",
+    "src/commands/list.ts",
+    "src/commands/cap.ts",
+    "src/commands/sasl.ts",
+    "src/commands/isupport.ts",
+    "src/commands/chathistory.ts",
+    "src/commands/away.ts",
+    "src/commands/chghost.ts"
+  ],
+  "disableTypeChecks": "{src,tests}/**/*.ts",
+  "thresholds": {
+    "high": 80,
+    "low": 60,
+    "break": 80
+  },
+  "reporters": ["clear-text", "html"],
+  "timeoutMS": 5000,
+  "concurrency": 2,
+  "ignoreStatic": true
+}

package/packages/irc-core/stryker.protocol.conf.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "_comment": "Mutation-testing spot-check for irc-core/protocol (coverage gate hardening). Targets the parser, serializer, numerics, message framing, batch framing, base64 and outbound helpers. Runs the existing vitest suite against generated mutants and fails the build below MUTATION_SCORE_THRESHOLD=80 (see tools/ci-hardening/src/validate.ts).",
+  "packageManager": "npm",
+  "testRunner": "vitest",
+  "plugins": ["@stryker-mutator/vitest-runner"],
+  "coverageAnalysis": "off",
+  "mutate": [
+    "src/protocol/parser.ts",
+    "src/protocol/serializer.ts",
+    "src/protocol/numerics.ts",
+    "src/protocol/messages.ts",
+    "src/protocol/outbound.ts",
+    "src/protocol/batch.ts",
+    "src/protocol/base64.ts"
+  ],
+  "disableTypeChecks": "{src,tests}/**/*.ts",
+  "thresholds": {
+    "high": 80,
+    "low": 60,
+    "break": 80
+  },
+  "reporters": ["clear-text", "html"],
+  "timeoutMS": 5000,
+  "concurrency": 2
+}

package/packages/irc-core/tests/account-store.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type AccountStore,
+  InMemoryAccountStore,
+  type SaslPayload,
+  type SaslResult,
+} from '../src/ports';
+
+/** Convenience: a PLAIN payload. */
+function plain(username: string, password: string): SaslPayload {
+  return { kind: 'PLAIN', username, password };
+}
+
+describe('InMemoryAccountStore — PLAIN', () => {
+  it('implements the AccountStore port', () => {
+    const store: AccountStore = new InMemoryAccountStore([
+      { username: 'alice', password: 'secret' },
+    ]);
+    expect(store).toBeDefined();
+  });
+
+  it('accepts valid PLAIN credentials and returns the account name', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('alice', 'secret'));
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+
+  it('rejects a wrong password', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('alice', 'wrong'));
+    expect(out.ok).toBe(false);
+  });
+
+  it('rejects an unknown username', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('bob', 'secret'));
+    expect(out.ok).toBe(false);
+  });
+
+  it('matches the first of several configured accounts', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'a-secret' },
+      { username: 'bob', password: 'b-secret' },
+    ]);
+    expect(store.verify('PLAIN', plain('bob', 'b-secret'))).toEqual<SaslResult>({
+      ok: true,
+      account: 'bob',
+    });
+  });
+
+  it('rejects when constructed with an empty account list', () => {
+    const store = new InMemoryAccountStore([]);
+    const out = store.verify('PLAIN', plain('alice', 'secret'));
+    expect(out.ok).toBe(false);
+  });
+
+  it('does not confuse credentials across accounts (no password cross-match)', () => {
+    const store = new InMemoryAccountStore([
+      { username: 'alice', password: 'a-secret' },
+      { username: 'bob', password: 'b-secret' },
+    ]);
+    // bob's password with alice's username must fail.
+    expect(store.verify('PLAIN', plain('alice', 'b-secret')).ok).toBe(false);
+  });
+});
+
+describe('InMemoryAccountStore — mechanism handling', () => {
+  it('rejects any non-PLAIN mechanism with a failure result', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('EXTERNAL', { kind: 'RAW', data: 'cert-subject' });
+    expect(out.ok).toBe(false);
+  });
+
+  it('treats the mechanism name case-insensitively for PLAIN', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('plain', plain('alice', 'secret'));
+    expect(out).toEqual<SaslResult>({ ok: true, account: 'alice' });
+  });
+});
+
+describe('InMemoryAccountStore — failure reason', () => {
+  it('returns a human-readable reason on failure', () => {
+    const store = new InMemoryAccountStore([{ username: 'alice', password: 'secret' }]);
+    const out = store.verify('PLAIN', plain('alice', 'wrong'));
+    if (out.ok) throw new Error('expected failure');
+    expect(out.reason.length).toBeGreaterThan(0);
+  });
+});

package/packages/irc-core/tests/admission.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Tests for the per-IP / per-user connection admission gate.
+ *
+ * These tests cover the pure decision helpers in `admission.ts`. The
+ * runtime-level integration (tracking live connections per IP, sweeping
+ * them on disconnect) lives in the in-memory runtime and the CF / AWS
+ * adapters; this module asserts the policy those callers feed.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  type AdmissionConfig,
+  type AdmissionDecision,
+  AdmissionStats,
+  decideAdmission,
+} from '../src/admission';
+import { FakeClock } from '../src/ports';
+
+const BASE_CONFIG: AdmissionConfig = {
+  maxConnectionsPerIp: 3,
+  maxConnectionsPerUser: 2,
+  perIpConnectionRate: { max: 5, windowMs: 10_000 },
+};
+
+/** Per-IP-cap-isolated config: rate limit + per-user cap set high enough to never bind. */
+const IP_CAP_CONFIG: AdmissionConfig = {
+  maxConnectionsPerIp: 3,
+  maxConnectionsPerUser: 100,
+  perIpConnectionRate: { max: 1_000, windowMs: 10_000 },
+};
+
+/** Per-user-cap-isolated config: rate limit + per-IP cap set high enough to never bind. */
+const USER_CAP_CONFIG: AdmissionConfig = {
+  maxConnectionsPerIp: 100,
+  maxConnectionsPerUser: 2,
+  perIpConnectionRate: { max: 1_000, windowMs: 10_000 },
+};
+
+/** Rate-limit-isolated config: per-IP + per-user caps set high enough to never bind. */
+const RATE_CONFIG: AdmissionConfig = {
+  maxConnectionsPerIp: 100,
+  maxConnectionsPerUser: 100,
+  perIpConnectionRate: { max: 5, windowMs: 10_000 },
+};
+
+function makeStats(clock: FakeClock): AdmissionStats {
+  return new AdmissionStats(clock);
+}
+
+describe('decideAdmission — per-IP connection cap', () => {
+  it('admits the first connection from an IP', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    const decision = decideAdmission('1.2.3.4', 'alice', stats, IP_CAP_CONFIG);
+    expect(decision.ok).toBe(true);
+  });
+
+  it('admits connections up to the per-IP cap', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 3; i++) {
+      const d = decideAdmission('1.2.3.4', `user${i}`, stats, IP_CAP_CONFIG);
+      expect(d.ok).toBe(true);
+      if (d.ok) stats.recordAdmission('1.2.3.4', `user${i}`, d.recordId);
+    }
+  });
+
+  it('rejects a connection that would exceed the per-IP cap', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 3; i++) {
+      const d = decideAdmission('1.2.3.4', `user${i}`, stats, IP_CAP_CONFIG);
+      if (d.ok) stats.recordAdmission('1.2.3.4', `user${i}`, d.recordId);
+    }
+    const decision = decideAdmission('1.2.3.4', 'user3', stats, IP_CAP_CONFIG);
+    expect(decision.ok).toBe(false);
+    if (!decision.ok) {
+      expect(decision.reason).toBe('max_connections_per_ip');
+    }
+  });
+
+  it('counts per-IP independently for different IPs', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 3; i++) {
+      const d = decideAdmission('1.1.1.1', `a${i}`, stats, IP_CAP_CONFIG);
+      if (d.ok) stats.recordAdmission('1.1.1.1', `a${i}`, d.recordId);
+    }
+    // A different IP still has its full budget.
+    const d = decideAdmission('2.2.2.2', 'b', stats, IP_CAP_CONFIG);
+    expect(d.ok).toBe(true);
+  });
+});
+
+describe('decideAdmission — per-user connection cap', () => {
+  it('rejects a connection that would exceed the per-user cap', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 2; i++) {
+      const d = decideAdmission(`10.0.0.${i}`, 'alice', stats, USER_CAP_CONFIG);
+      if (d.ok) stats.recordAdmission(`10.0.0.${i}`, 'alice', d.recordId);
+    }
+    const decision = decideAdmission('10.0.0.5', 'alice', stats, USER_CAP_CONFIG);
+    expect(decision.ok).toBe(false);
+    if (!decision.ok) {
+      expect(decision.reason).toBe('max_connections_per_user');
+    }
+  });
+
+  it('treats an undefined user as IP-keyed (does not collapse anonymous connections together across IPs)', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    // Anonymous connection from IP #1.
+    const d1 = decideAdmission('1.1.1.1', undefined, stats, USER_CAP_CONFIG);
+    expect(d1.ok).toBe(true);
+    if (d1.ok) stats.recordAdmission('1.1.1.1', undefined, d1.recordId);
+    // Anonymous connection from a different IP is admitted (per-user cap is
+    // scoped to the IP when no SASL identity is available).
+    const d2 = decideAdmission('2.2.2.2', undefined, stats, USER_CAP_CONFIG);
+    expect(d2.ok).toBe(true);
+  });
+});
+
+describe('decideAdmission — per-IP connection-rate limit', () => {
+  it('admits bursts within the rate cap', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 5; i++) {
+      const d = decideAdmission('1.2.3.4', `u${i}`, stats, RATE_CONFIG);
+      expect(d.ok).toBe(true);
+      if (d.ok) stats.recordAdmission('1.2.3.4', `u${i}`, d.recordId);
+    }
+  });
+
+  it('rejects a connection exceeding the rate cap inside the window', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    // Use distinct users so per-user cap doesn't kick in first.
+    for (let i = 0; i < 5; i++) {
+      const d = decideAdmission('1.2.3.4', `u${i}`, stats, RATE_CONFIG);
+      if (d.ok) stats.recordAdmission('1.2.3.4', `u${i}`, d.recordId);
+    }
+    const decision = decideAdmission('1.2.3.4', 'u5', stats, RATE_CONFIG);
+    expect(decision.ok).toBe(false);
+    if (!decision.ok) {
+      expect(decision.reason).toBe('rate_limited_per_ip');
+    }
+  });
+
+  it('admits again once the window has elapsed', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 5; i++) {
+      const d = decideAdmission('1.2.3.4', `u${i}`, stats, RATE_CONFIG);
+      if (d.ok) stats.recordAdmission('1.2.3.4', `u${i}`, d.recordId);
+    }
+    // Within the window: rejected.
+    expect(decideAdmission('1.2.3.4', 'u5', stats, RATE_CONFIG).ok).toBe(false);
+    // Advance past the window: the stale rate entries are dropped.
+    clock.advance(10_001);
+    const after = decideAdmission('1.2.3.4', 'u5', stats, RATE_CONFIG);
+    expect(after.ok).toBe(true);
+  });
+});
+
+describe('decideAdmission — combined precedence', () => {
+  it('checks the rate limit before the per-IP cap', () => {
+    // Tight rate cap (2 in 10s) and a generous per-IP cap (100).
+    const cfg: AdmissionConfig = {
+      maxConnectionsPerIp: 100,
+      maxConnectionsPerUser: 100,
+      perIpConnectionRate: { max: 2, windowMs: 10_000 },
+    };
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    for (let i = 0; i < 2; i++) {
+      const d = decideAdmission('5.5.5.5', `u${i}`, stats, cfg);
+      if (d.ok) stats.recordAdmission('5.5.5.5', `u${i}`, d.recordId);
+    }
+    const decision = decideAdmission('5.5.5.5', 'u2', stats, cfg);
+    expect(decision.ok).toBe(false);
+    if (!decision.ok) {
+      expect(decision.reason).toBe('rate_limited_per_ip');
+    }
+  });
+});
+
+describe('AdmissionStats — release', () => {
+  it('decrements per-IP and per-user counts when a connection is released', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    const d1 = decideAdmission('1.2.3.4', 'alice', stats, BASE_CONFIG);
+    expect(d1.ok).toBe(true);
+    if (!d1.ok) throw new Error('precondition: d1 should admit');
+    stats.recordAdmission('1.2.3.4', 'alice', d1.recordId);
+    const d2 = decideAdmission('1.2.3.4', 'alice', stats, BASE_CONFIG);
+    expect(d2.ok).toBe(true);
+    if (!d2.ok) throw new Error('precondition: d2 should admit');
+    stats.recordAdmission('1.2.3.4', 'alice', d2.recordId);
+    // At cap now.
+    const d3 = decideAdmission('1.2.3.4', 'alice', stats, BASE_CONFIG);
+    expect(d3.ok).toBe(false);
+    // Release one; next attempt succeeds.
+    stats.release(d1.recordId);
+    const d4 = decideAdmission('1.2.3.4', 'alice', stats, BASE_CONFIG);
+    expect(d4.ok).toBe(true);
+  });
+
+  it('releasing an unknown record id is a no-op', () => {
+    const clock = new FakeClock(1_000);
+    const stats = makeStats(clock);
+    expect(() => stats.release('unknown')).not.toThrow();
+  });
+});
+
+describe('AdmissionStats — determinism', () => {
+  it('returns identical decisions for identical Clock + input streams', () => {
+    const run = (): AdmissionDecision => {
+      const clock = new FakeClock(1_000);
+      const stats = makeStats(clock);
+      for (let i = 0; i < 4; i++) {
+        const d = decideAdmission('1.1.1.1', `u${i}`, stats, BASE_CONFIG);
+        if (d.ok) stats.recordAdmission('1.1.1.1', `u${i}`, d.recordId);
+      }
+      return decideAdmission('1.1.1.1', 'u4', stats, BASE_CONFIG);
+    };
+    expect(run()).toEqual(run());
+  });
+});