serverless-ircd 0.1.0 → 0.2.0

package/packages/cf-adapter/src/connection-do.ts

@@ -34,7 +34,12 @@ import {
   type Clock,
   type ConnId,
   type ConnectionState,
+  ConsoleLogger,
   type IdFactory,
+  InMemoryMessageStore,
+  LogLevel,
+  type Logger,
+  type MessageStore,
   type MotdProvider,
   type RawLine,
   type ServerConfig,
@@ -90,6 +95,15 @@ export class ConnectionDO extends DurableObject<Env> {
    * should seed `createdAt` with its receive time.
    */
   private channelAccess: PassthroughChannelAccess | undefined;
+  /**
+   * Per-connection chat-history store backing `draft/chathistory`
+   * playback. The minimum-viable in-worker ring buffer is scoped to this
+   * connection: messages this connection sends are recorded and replayable
+   * by the same connection. A Durable-Object-backed persistent variant
+   * (shared across connections, keyed by channel) is a documented
+   * follow-up. Lazily constructed so the first frame seeds it.
+   */
+  private messages: MessageStore | undefined;
   private readonly clock: Clock = SystemClock;
   private readonly ids: IdFactory = new UuidIdFactory();
   private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
@@ -293,6 +307,10 @@ export class ConnectionDO extends DurableObject<Env> {
     if (this.channelAccess === undefined) {
       this.channelAccess = new PassthroughChannelAccess(this.clock.now(), this.env);
     }
+    // Workers Observability ingests `console.*` directly.
+    // Bound `connectionId` so every record the actor emits is filterable
+    // per-connection in the Workers dashboard.
+    const logger: Logger = new ConsoleLogger({ connectionId: state.id }, undefined, LogLevel.Info);
     return new ConnectionActor({
       state,
       runtime,
@@ -301,6 +319,8 @@ export class ConnectionDO extends DurableObject<Env> {
       clock: this.clock,
       ids: this.ids,
       motd,
+      messages: this.messageStore(),
+      logger,
     });
   }
 
@@ -351,6 +371,19 @@ export class ConnectionDO extends DurableObject<Env> {
     return { lines: () => raw.split('\n') };
   }
 
+  /**
+   * Lazily constructs the per-connection chat-history store. The ring
+   * buffer default cap matches the shared `InMemoryMessageStore`; a
+   * future persistent variant (DO/KV-backed, keyed by channel) will
+   * replace this without touching the actor wiring.
+   */
+  private messageStore(): MessageStore {
+    if (this.messages === undefined) {
+      this.messages = new InMemoryMessageStore();
+    }
+    return this.messages;
+  }
+
   // -------------------------------------------------------------------------
   // Test hooks (only invoked from `runInDurableObject` in tests)
   // -------------------------------------------------------------------------
@@ -394,6 +427,7 @@ export class ConnectionDO extends DurableObject<Env> {
       clock: this.clock,
       ids: this.ids,
       motd: this.motdProvider(),
+      messages: this.messageStore(),
     });
     await actor.receiveTextFrame('QUIT\r\n');
     await this.releaseAndPersist(state);

package/packages/cf-adapter/tests/cf-harness.ts

@@ -20,7 +20,7 @@ import type {
   IrcHarness,
   IrcHarnessFactory,
   SpawnClientOptions,
-} from './integration/harness.js';
+} from '@serverless-ircd/irc-test-support';
 
 /** Default tick for the polling waitFor* implementations (ms). */
 const POLL_MS = 10;
@@ -57,7 +57,7 @@ export interface CfHarnessEnv {
  *
  * ```ts
  * import { env } from 'cloudflare:test';
- * import { runIrcScenarios } from './integration/scenarios.js';
+ * import { runIrcScenarios } from '@serverless-ircd/irc-test-support';
  * import { makeCfHarnessFactory } from './cf-harness';
  *
  * runIrcScenarios([makeCfHarnessFactory({ env })]);

package/packages/cf-adapter/tests/cf-integration.test.ts

@@ -1,7 +1,7 @@
 /**
  * Parametrized IRC scenarios against the Cloudflare runtime — 036.
  *
- * Reuses the scenario runner from `./integration/scenarios.js`
+ * Reuses the scenario runner from `@serverless-ircd/irc-test-support`
  * (032) and registers the CF harness factory built on top of the
  * real ConnectionDO / RegistryDO / ChannelDO worker bindings. Each
  * scenario spawns one or more real WebSockets and drives the full
@@ -26,9 +26,9 @@
  */
 
 import { env, reset } from 'cloudflare:test';
+import { runIrcScenarios } from '@serverless-ircd/irc-test-support';
 import { afterAll, afterEach, beforeAll } from 'vitest';
 import { makeCfHarnessFactory } from './cf-harness';
-import { runIrcScenarios } from './integration/scenarios.js';
 
 declare global {
   namespace Cloudflare {

package/packages/cf-adapter/tests/config-loader.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Config loading for the cf-adapter.
+ *
+ * Verifies the shared `ServerConfigSchema` (from `irc-core`) is consumed
+ * by the Cloudflare adapter — both adapters (CF + AWS) build the same
+ * shape from their platform-native sources.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { loadServerConfigFromCfEnv } from '../src/config-loader';
+
+interface CfEnvLike {
+  SERVER_NAME?: string;
+  NETWORK_NAME?: string;
+  MOTD_LINES?: string;
+  MAX_CLIENTS?: string;
+  CHANNEL_PREFIXES?: string;
+  OPER_USER?: string;
+  OPER_PASSWORD?: string;
+  MAX_CHANNELS_PER_USER?: string;
+  MAX_TARGETS_PER_COMMAND?: string;
+  NICK_LEN?: string;
+  CHANNEL_LEN?: string;
+  TOPIC_LEN?: string;
+  MAX_LIST_ENTRIES?: string;
+  QUIT_MESSAGE?: string;
+}
+
+function baseEnv(): CfEnvLike {
+  return { SERVER_NAME: 'irc.cf.example.com', NETWORK_NAME: 'CfNet' };
+}
+
+describe('loadServerConfigFromCfEnv — valid env', () => {
+  it('returns a parsed config derived from the minimal required vars', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.serverName).toBe('irc.cf.example.com');
+    expect(cfg.networkName).toBe('CfNet');
+    // Defaults still apply.
+    expect(cfg.channelPrefixes.length).toBeGreaterThan(0);
+    expect(cfg.maxClients).toBeGreaterThan(0);
+    expect(cfg.operCreds).toEqual([]);
+  });
+
+  it('splits MOTD_LINES on newlines into motdLines', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      MOTD_LINES: 'line 1\nline 2\nline 3',
+    });
+    expect(cfg.motdLines).toEqual(['line 1', 'line 2', 'line 3']);
+  });
+
+  it('treats an undefined MOTD_LINES as the default empty MOTD', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(cfg.motdLines).toEqual([]);
+  });
+
+  it('parses MAX_CLIENTS as an integer', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), MAX_CLIENTS: '4242' });
+    expect(cfg.maxClients).toBe(4242);
+  });
+
+  it('parses CHANNEL_PREFIXES verbatim', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      CHANNEL_PREFIXES: '#&+',
+    });
+    expect(cfg.channelPrefixes).toBe('#&+');
+  });
+
+  it('builds operCreds from OPER_USER + OPER_PASSWORD when both set', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      OPER_USER: 'admin',
+      OPER_PASSWORD: 'hunter2',
+    });
+    expect(cfg.operCreds).toEqual([{ user: 'admin', password: 'hunter2' }]);
+  });
+
+  it('parses numeric limit overrides from string env vars', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      MAX_CHANNELS_PER_USER: '12',
+      MAX_TARGETS_PER_COMMAND: '3',
+      NICK_LEN: '20',
+      CHANNEL_LEN: '40',
+      TOPIC_LEN: '300',
+      MAX_LIST_ENTRIES: '7',
+    });
+    expect(cfg.maxChannelsPerUser).toBe(12);
+    expect(cfg.maxTargetsPerCommand).toBe(3);
+    expect(cfg.nickLen).toBe(20);
+    expect(cfg.channelLen).toBe(40);
+    expect(cfg.topicLen).toBe(300);
+    expect(cfg.maxListEntries).toBe(7);
+  });
+
+  it('honours a custom QUIT_MESSAGE', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      QUIT_MESSAGE: 'Bye from CF',
+    });
+    expect(cfg.quitMessage).toBe('Bye from CF');
+  });
+});
+
+describe('loadServerConfigFromCfEnv — failure modes', () => {
+  it('throws when SERVER_NAME is missing', () => {
+    expect(() => loadServerConfigFromCfEnv({ NETWORK_NAME: 'CfNet' })).toThrowError(/serverName/u);
+  });
+
+  it('throws when NETWORK_NAME is missing', () => {
+    expect(() => loadServerConfigFromCfEnv({ SERVER_NAME: 's' })).toThrowError(/networkName/u);
+  });
+
+  it('throws when MAX_CLIENTS is non-numeric', () => {
+    expect(() => loadServerConfigFromCfEnv({ ...baseEnv(), MAX_CLIENTS: 'lots' })).toThrowError(
+      /maxClients/u,
+    );
+  });
+
+  it('throws when OPER_USER is set but OPER_PASSWORD is missing', () => {
+    expect(() => loadServerConfigFromCfEnv({ ...baseEnv(), OPER_USER: 'admin' })).toThrowError(
+      /password/u,
+    );
+  });
+
+  it('throws when OPER_PASSWORD is set but OPER_USER is missing', () => {
+    expect(() => loadServerConfigFromCfEnv({ ...baseEnv(), OPER_PASSWORD: 'p' })).toThrowError(
+      /user/u,
+    );
+  });
+
+  it('aggregates multiple errors into a single readable Error', () => {
+    try {
+      loadServerConfigFromCfEnv({
+        MAX_CLIENTS: 'oops',
+        OPER_USER: 'admin',
+      });
+      expect.fail('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      const msg = (err as Error).message;
+      expect(msg).toMatch(/invalid server config/iu);
+      // Both bad fields are surfaced.
+      expect(msg).toMatch(/serverName/u);
+      expect(msg).toMatch(/maxClients/u);
+    }
+  });
+});

package/packages/cf-adapter/tests/connection-do.test.ts

@@ -123,6 +123,23 @@ async function register(client: IrcWsClient, nick: string): Promise<void> {
   await client.waitForMessage((l) => l.includes(' 001 '));
 }
 
+/**
+ * Negotiates the chathistory cap set then registers. Mirrors the
+ * pre-registration `CAP REQ` → `NICK`/`USER` → `CAP END` flow a real
+ * client uses.
+ */
+async function registerWithChathistory(client: IrcWsClient, nick: string): Promise<void> {
+  // `echo-message` is included so tests can deterministically wait for a
+  // PRIVMSG to be recorded before issuing a follow-up CHATHISTORY query
+  // (otherwise the two async webSocketMessage handlers race).
+  client.send('CAP REQ :draft/chathistory server-time message-tags batch echo-message\r\n');
+  await client.waitForMessage((l) => / CAP \S+ ACK :/.test(l));
+  client.send(`NICK ${nick}\r\n`);
+  client.send(`USER ${nick} 0 * :${nick}\r\n`);
+  client.send('CAP END\r\n');
+  await client.waitForMessage((l) => l.includes(' 001 '));
+}
+
 /**
  * Forces the ConnectionDO to drop its in-memory cache of the
  * {@link ConnectionState}, simulating wake-from-hibernation. The next
@@ -324,6 +341,31 @@ describe('ConnectionDO — alarms', () => {
   });
 });
 
+describe('ConnectionDO — chathistory end-to-end', () => {
+  it('records a PRIVMSG and replays it via CHATHISTORY LATEST in a BATCH', async () => {
+    const client = await connect('conn-chathist-1');
+    await registerWithChathistory(client, 'cf-alice');
+
+    client.send('JOIN #cf-chathist\r\n');
+    await client.waitForMessage((l) => l.includes(' 366 ') && l.includes('#cf-chathist'));
+
+    client.send('PRIVMSG #cf-chathist :recorded via cf\r\n');
+    // Wait for the echo (echo-message cap) so the PRIVMSG is recorded
+    // before the CHATHISTORY query arrives as a separate frame.
+    await client.waitForMessage((l) => l.includes('PRIVMSG #cf-chathist :recorded via cf'));
+
+    client.send('CHATHISTORY LATEST #cf-chathist * 10\r\n');
+    const batchOpen = await client.waitForMessage((l) =>
+      /^BATCH \+\S+ chathistory #cf-chathist/.test(l),
+    );
+    expect(batchOpen).toMatch(/^BATCH \+\S+ chathistory #cf-chathist/);
+
+    await client.waitForMessage((l) => l.includes('PRIVMSG #cf-chathist :recorded via cf'));
+
+    client.ws.close();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // End of file
 // ---------------------------------------------------------------------------

package/packages/in-memory-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/in-memory-runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "Single-process reference implementation of the IrcRuntime port, backed by Maps",
   "license": "BSD-3-Clause",

package/packages/in-memory-runtime/src/in-memory-runtime.ts

@@ -13,6 +13,9 @@
  */
 
 import {
+  type AdmissionConfig,
+  type AdmissionDecision,
+  AdmissionStats,
   type ChanName,
   type ChanSnapshot,
   type ChannelDelta,
@@ -25,6 +28,7 @@ import {
   type RawLine,
   applyChannelDelta as applyDelta,
   createChannel,
+  decideAdmission,
   toChannelSnapshot,
   toSnapshot as toConnSnapshot,
 } from '@serverless-ircd/irc-core';
@@ -41,20 +45,93 @@ export interface ConnectionHandlers {
 interface TrackedConnection {
   state: ConnectionState;
   handlers: ConnectionHandlers;
+  /**
+   * Optional admission record id paired with this connection at register
+   * time. When set, {@link InMemoryRuntime.unregisterConnection} releases
+   * it so per-IP / per-user connection counters stay accurate.
+   */
+  admissionRecordId?: string;
 }
 
 function lower(s: string): string {
   return s.toLowerCase();
 }
 
+let disabledRecordCounter = 0;
+/**
+ * Returns a unique record id for the "admission disabled" path. The id is
+ * never consulted (no {@link AdmissionStats} exists), but emitting one
+ * keeps {@link admitConnection}'s return shape uniform.
+ */
+function _disabledRecordId(): string {
+  disabledRecordCounter += 1;
+  return `disabled-${disabledRecordCounter}`;
+}
+
+export interface InMemoryRuntimeOptions {
+  clock: Clock;
+  /**
+   * Connection-admission policy. When omitted the admission gate is
+   * disabled — every {@link InMemoryRuntime.admitConnection} call returns
+   * an admit decision. Adapters that want to enforce per-IP / per-user /
+   * rate limits pass the same {@link AdmissionConfig} derived from the
+   * deployment's `ServerConfig`.
+   */
+  readonly admission?: AdmissionConfig;
+}
+
 export class InMemoryRuntime implements IrcRuntime {
   private readonly clock: Clock;
   private readonly connections = new Map<ConnId, TrackedConnection>();
   private readonly channels = new Map<string, ChannelState>();
   private readonly nicks = new Map<string, ConnId>();
+  private readonly admissionStats: AdmissionStats | undefined;
+  private readonly admissionConfig: AdmissionConfig | undefined;
 
-  constructor(opts: { clock: Clock }) {
+  constructor(opts: InMemoryRuntimeOptions) {
     this.clock = opts.clock;
+    if (opts.admission !== undefined) {
+      this.admissionConfig = opts.admission;
+      this.admissionStats = new AdmissionStats(this.clock);
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Admission gate (NOT part of the IrcRuntime port — adapter only)
+  // ------------------------------------------------------------------
+
+  /**
+   * Decides whether a new connection should be admitted under the
+   * configured {@link AdmissionConfig}. Returns `{ ok: true, recordId }`
+   * when the connection may proceed; the caller MUST then call
+   * {@link commitAdmission} exactly once with the returned recordId.
+   *
+   * Returns `{ ok: false, reason }` when the connection must be refused.
+   *
+   * When no admission policy was supplied at construction, this method
+   * unconditionally admits (the gate is disabled).
+   */
+  admitConnection(ip: string, user: string | undefined): AdmissionDecision {
+    if (this.admissionConfig === undefined || this.admissionStats === undefined) {
+      return { ok: true, recordId: _disabledRecordId() };
+    }
+    return decideAdmission(ip, user, this.admissionStats, this.admissionConfig);
+  }
+
+  /**
+   * Records an accepted admission. MUST be called exactly once per
+   * successful {@link admitConnection}. No-op when admission is disabled.
+   */
+  commitAdmission(ip: string, user: string | undefined, recordId: string): void {
+    this.admissionStats?.recordAdmission(ip, user, recordId);
+  }
+
+  /**
+   * Releases a previously-committed admission record. Safe to call with
+   * an unknown id. No-op when admission is disabled.
+   */
+  releaseAdmission(recordId: string): void {
+    this.admissionStats?.release(recordId);
   }
 
   // ------------------------------------------------------------------
@@ -65,13 +142,31 @@ export class InMemoryRuntime implements IrcRuntime {
    * Tracks a connection and its transport handlers. The runtime keeps a
    * reference to `state`; the actor may continue mutating it in place and
    * the runtime will observe the changes via {@link getConnectionInfo}.
+   *
+   * @param admissionRecordId Optional record id returned by
+   *   {@link admitConnection} + {@link commitAdmission}. When supplied,
+   *   {@link unregisterConnection} releases it automatically so the
+   *   per-IP / per-user connection counters stay accurate without the
+   *   adapter remembering to call {@link releaseAdmission} itself.
    */
-  registerConnection(state: ConnectionState, handlers: ConnectionHandlers): void {
-    this.connections.set(state.id, { state, handlers });
+  registerConnection(
+    state: ConnectionState,
+    handlers: ConnectionHandlers,
+    admissionRecordId?: string,
+  ): void {
+    const tracked: TrackedConnection =
+      admissionRecordId !== undefined
+        ? { state, handlers, admissionRecordId }
+        : { state, handlers };
+    this.connections.set(state.id, tracked);
   }
 
   /** Stops tracking a connection. Idempotent. Does NOT release its nick. */
   unregisterConnection(conn: ConnId): void {
+    const tracked = this.connections.get(conn);
+    if (tracked !== undefined && tracked.admissionRecordId !== undefined) {
+      this.releaseAdmission(tracked.admissionRecordId);
+    }
     this.connections.delete(conn);
   }
 
@@ -102,6 +197,16 @@ export class InMemoryRuntime implements IrcRuntime {
     return created;
   }
 
+  /**
+   * Peek-only channel lookup that does NOT create the channel. Returns the
+   * authoritative {@link ChannelState} when it exists, or `undefined`.
+   * Used by query-only commands (CHATHISTORY) that must distinguish a
+   * missing channel from an empty one.
+   */
+  getChannel(name: ChanName): ChannelState | undefined {
+    return this.channels.get(lower(name));
+  }
+
   // ------------------------------------------------------------------
   // IrcRuntime — transport
   // ------------------------------------------------------------------

package/packages/in-memory-runtime/src/index.ts

@@ -6,4 +6,4 @@
  * and AWS runtimes.
  */
 export { InMemoryRuntime } from './in-memory-runtime.js';
-export type { ConnectionHandlers } from './in-memory-runtime.js';
+export type { ConnectionHandlers, InMemoryRuntimeOptions } from './in-memory-runtime.js';

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,
@@ -500,3 +502,116 @@ 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);
+  });
+});

package/packages/irc-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "Platform-agnostic IRC protocol core: parser, serializer, command reducers, state shapes",
   "license": "BSD-3-Clause",
@@ -23,7 +23,17 @@
     "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"
+  }
 }