serverless-ircd 0.1.0 → 0.3.0

package/apps/local-cli/tests/e2e.test.ts

@@ -178,6 +178,19 @@ describe('local-cli error paths', () => {
     await first.close();
   });
 
+  it('validates the supplied config through the shared ServerConfigSchema at boot', async () => {
+    // nickLen=0 is rejected by the schema (must be a positive integer).
+    await expect(
+      startLocalServer({
+        port: 0,
+        hostname: '127.0.0.1',
+        serverName: 'irc.local.example.com',
+        networkName: 'LocalNet',
+        nickLen: 0,
+      }),
+    ).rejects.toThrowError(/invalid server config/iu);
+  });
+
   it('logs and recovers from a per-socket error without crashing the server', async () => {
     const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
     const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
@@ -344,3 +357,116 @@ describe('local-cli error paths', () => {
     await srv.close();
   });
 });
+
+describe('local-cli chathistory end-to-end', () => {
+  const CHATHISTORY_CAPS = 'draft/chathistory server-time message-tags batch';
+
+  /** Registers a client that has negotiated the chathistory cap set. */
+  async function registerWithCaps(srv: LocalServer, nick: string): Promise<TestClient> {
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    client.send(`CAP REQ :${CHATHISTORY_CAPS}\r\n`);
+    await client.waitFor((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.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    return client;
+  }
+
+  it('records a PRIVMSG and replays it via CHATHISTORY LATEST in a BATCH', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const alice = await registerWithCaps(srv, 'ch-alice');
+
+    alice.send('JOIN #chathist-e2e\r\n');
+    await alice.waitFor((l) => l.includes(' 366 '));
+
+    alice.send('PRIVMSG #chathist-e2e :backlog hello\r\n');
+
+    alice.send('CHATHISTORY LATEST #chathist-e2e * 10\r\n');
+    const batchOpen = await alice.waitFor((l) => /^BATCH \+\S+ chathistory #chathist-e2e/.test(l));
+    expect(batchOpen).toMatch(/^BATCH \+\S+ chathistory #chathist-e2e/);
+
+    const replay = await alice.waitFor((l) => l.includes('PRIVMSG #chathist-e2e :backlog hello'));
+    expect(replay).toContain('PRIVMSG #chathist-e2e :backlog hello');
+
+    await alice.close();
+    await srv.close();
+  });
+
+  it('prepends a chathistory BATCH on rejoin after messages were sent', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+
+    // Seed history as alice: join + send a message that bob has missed.
+    const alice = await registerWithCaps(srv, 'ch-seed');
+    alice.send('JOIN #rejoin-e2e\r\n');
+    await alice.waitFor((l) => l.includes(' 366 ') && l.includes('#rejoin-e2e'));
+    alice.send('PRIVMSG #rejoin-e2e :while you were away\r\n');
+    // Give the frame a moment to record before bob joins.
+    await new Promise((r) => setTimeout(r, 50));
+
+    // A second cap-enabled client joins the same channel and must receive
+    // the auto-playback BATCH before the normal JOIN/353/366 sequence.
+    const bob = await registerWithCaps(srv, 'ch-rejoin');
+    bob.send('JOIN #rejoin-e2e\r\n');
+    const playback = await bob.waitFor((l) => /^BATCH \+\S+ chathistory #rejoin-e2e/.test(l));
+    expect(playback).toMatch(/^BATCH \+\S+ chathistory #rejoin-e2e/);
+    await bob.waitFor((l) => l.includes('PRIVMSG #rejoin-e2e :while you were away'));
+
+    await alice.close();
+    await bob.close();
+    await srv.close();
+  });
+});
+
+describe('local-cli SASL PLAIN end-to-end', () => {
+  /** base64(`\0authcid\0password`) — the PLAIN payload format. */
+  function plainB64(authcid: string, password: string): string {
+    return Buffer.from(`\0${authcid}\0${password}`, 'utf8').toString('base64');
+  }
+
+  it('completes SASL PLAIN with 900/903 for valid seeded creds', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      saslAccounts: [{ username: 'sasl-alice', password: 's3cret' }],
+    });
+
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    client.send('CAP REQ :sasl\r\n');
+    await client.waitFor((l) => / CAP \S+ ACK :sasl/.test(l));
+    client.send('AUTHENTICATE PLAIN\r\n');
+    await client.waitFor((l) => l === 'AUTHENTICATE +');
+    client.send(`AUTHENTICATE ${plainB64('sasl-alice', 's3cret')}\r\n`);
+    await client.waitFor((l) => l.includes(' 900 '));
+    const success = await client.waitFor((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    client.send('NICK sasl-alice\r\n');
+    client.send('USER sasl-alice 0 * :Sasl Alice\r\n');
+    client.send('CAP END\r\n');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.close();
+    await srv.close();
+  });
+
+  it('rejects SASL PLAIN with 904 for invalid creds', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      saslAccounts: [{ username: 'sasl-bob', password: 'right' }],
+    });
+
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    client.send('CAP REQ :sasl\r\n');
+    await client.waitFor((l) => / CAP \S+ ACK :sasl/.test(l));
+    client.send('AUTHENTICATE PLAIN\r\n');
+    await client.waitFor((l) => l === 'AUTHENTICATE +');
+    client.send(`AUTHENTICATE ${plainB64('sasl-bob', 'wrong')}\r\n`);
+    const fail = await client.waitFor((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    await client.close();
+    await srv.close();
+  });
+});

package/apps/local-cli/tests/security-e2e.test.ts

@@ -0,0 +1,239 @@
+/**
+ * End-to-end tests for the production-hardening security features:
+ *   server password enforcement, hostmask cloaking, and
+ *   the connection-admission gate.
+ *
+ * These tests boot a real `startLocalServer` with the relevant config
+ * knobs and drive it over WebSocket — the same path a real IRC client
+ * takes. The unit-test coverage for each limit lives next to the
+ * implementation; this file verifies the wiring through the local CLI.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+class TestClient {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string) {
+    this.ws = new WebSocket(url);
+    this.ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws.readyState === WebSocket.OPEN) resolve();
+      else if (this.ws.readyState === WebSocket.CLOSED)
+        reject(new Error('socket closed before open'));
+      else {
+        this.ws.once('open', () => resolve());
+        this.ws.once('error', reject);
+        this.ws.once('close', () => reject(new Error('socket closed before open')));
+      }
+    });
+  }
+
+  /** Resolves once the underlying socket closes. */
+  closed(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.ws.readyState === WebSocket.CLOSED) resolve();
+      else this.ws.once('close', () => resolve());
+    });
+  }
+
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1_000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`));
+      }, timeoutMs);
+      const check = (line: string) => {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          this.ws.off('message', onMessage);
+          resolve(line);
+        }
+      };
+      const onMessage = (data: { toString: (enc: string) => string }): void => {
+        const text = data.toString('utf8');
+        for (const line of text.split(/\r?\n/u)) {
+          if (line.length > 0) check(line);
+        }
+      };
+      for (const line of this.received) {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.ws.on('message', onMessage);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server password
+// ---------------------------------------------------------------------------
+
+describe('local-cli e2e — server password', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'pwd.example.com',
+      networkName: 'PwdNet',
+      serverPassword: 's3cret',
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('rejects a client that registers without the password', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK alice');
+    await client.send('USER alice 0 * :Alice');
+    // 464 ERR_PASSWDMISMATCH followed by ERROR :Closing link.
+    await client.waitFor((l) => l.includes(' 464 '));
+    await client.waitFor((l) => l.startsWith('ERROR :Closing link'));
+    await client.close();
+  });
+
+  it('rejects a client that supplies the wrong password', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('PASS wrong');
+    await client.send('NICK bob');
+    await client.send('USER bob 0 * :Bob');
+    await client.waitFor((l) => l.includes(' 464 '));
+    await client.close();
+  });
+
+  it('admits a client that supplies the correct password', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('PASS s3cret');
+    await client.send('NICK carol');
+    await client.send('USER carol 0 * :Carol');
+    await client.waitFor((l) => l.startsWith(':pwd.example.com 001 '));
+    await client.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Hostmask cloaking
+// ---------------------------------------------------------------------------
+
+describe('local-cli e2e — hostmask cloaking', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'cloak.example.com',
+      networkName: 'CloakNet',
+      cloaking: { enabled: true, secret: 'hunter2', cloakedSuffix: 'hidden.lan' },
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('emits the cloaked host in the 001 welcome line', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK alice');
+    await client.send('USER alice 0 * :Alice');
+    const welcome = await client.waitFor((l) => l.startsWith(':cloak.example.com 001 '));
+    // The cloaked host ends in the configured suffix and is NOT the raw IP.
+    expect(welcome.endsWith('.hidden.lan')).toBe(true);
+    // 001 format: :server 001 nick :Welcome to the Network IRC Network, nick!user@host
+    const hostSegment = welcome.split('@').slice(-1)[0] ?? '';
+    expect(hostSegment.endsWith('.hidden.lan')).toBe(true);
+    await client.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Admission gate — per-IP connection cap
+// ---------------------------------------------------------------------------
+
+describe('local-cli e2e — admission gate (per-IP cap)', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'cap.example.com',
+      networkName: 'CapNet',
+      // Tight caps so the e2e test can saturate them quickly.
+      maxConnectionsPerIp: 2,
+      maxConnectionsPerUser: 100,
+      perIpConnectionRate: { max: 1_000, windowMs: 60_000 },
+    });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('admits connections up to the cap then refuses further admissions', async () => {
+    const url = `ws://127.0.0.1:${server.port}/`;
+    const c1 = new TestClient(url);
+    const c2 = new TestClient(url);
+    await c1.opened();
+    await c2.opened();
+    // First two register fine.
+    await c1.send('NICK a1');
+    await c1.send('USER a1 0 * :A');
+    await c1.waitFor((l) => l.startsWith(':cap.example.com 001 '));
+    await c2.send('NICK a2');
+    await c2.send('USER a2 0 * :A');
+    await c2.waitFor((l) => l.startsWith(':cap.example.com 001 '));
+
+    // Third exceeds the per-IP cap (maxConnectionsPerIp: 2). The server
+    // sends an ERROR notice and closes the socket. Either opened() rejects
+    // (close-before-open) or the ERROR line arrives before close.
+    const c3 = new TestClient(url);
+    // Wait for either rejection path without racing into an unhandled
+    // rejection: opened() rejects on close, and we catch it.
+    await c3.opened().catch(() => {
+      // Expected: server closed the socket during/before handshake.
+    });
+    // If the socket did open, the server still sends ERROR then closes.
+    if (c3.ws.readyState === WebSocket.OPEN) {
+      await c3.waitFor((l) => l.startsWith('ERROR :Closing link'));
+    }
+    await c3.closed();
+
+    await c1.close();
+    await c2.close();
+  });
+});

package/biome.json

@@ -12,7 +12,9 @@
       "**/coverage/**",
       "**/node_modules/**",
       "**/.turbo/**",
-      "pnpm-lock.yaml"
+      "pnpm-lock.yaml",
+      "cdk.out/",
+      "*.template.json"
     ]
   },
   "formatter": {

package/docs/ADR-001-pure-reducers-and-effect-system.md

@@ -0,0 +1,74 @@
+# ADR-001: Pure reducers and the effect system
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+Every IRC daemon must decide where side effects happen. A traditional ircd
+threads mutable state and IO through command handlers — the handler reads a
+channel roster, sends messages, mutates a user record, and returns. That makes
+handlers hard to unit-test (they require a live socket, a real timer, a
+populated data store) and hard to reason about (the handler's observable
+behaviour is inseparable from its IO).
+
+ServerlessIRCd targets two cloud adapters (Cloudflare Workers, AWS Lambda)
+that share one protocol core. If the core performed IO directly, each adapter
+would need its own mock surface for every core test — or worse, the core
+would grow adapter-specific code paths.
+
+## Decision
+
+Every command handler is a **pure function** with the signature:
+
+```ts
+type Reducer<S> = (state: S, msg: IrcMessage, ctx: Ctx) => { state: S; effects: Effect[] };
+```
+
+- **No IO in the reducer.** No `await`, no `fetch`, no `setTimeout`, no
+  `Date.now()`, no `Math.random()`. The reducer reads `ctx.clock.now()` and
+  `ctx.ids.nonce()` instead (see ADR-007).
+- **Side effects are values.** The reducer returns an `Effect[]` — a
+  discriminated union (`Send`, `Broadcast`, `Disconnect`, `ReserveNick`,
+  `ChangeNick`, `ReleaseNick`, `ApplyChannelDelta`, `SendToNick`, …). Each
+  effect tag maps one-to-one to an `IrcRuntime` method.
+- **A single `dispatch(effects, runtime)` function** in `irc-server`
+  interprets the effects against the bound runtime. Only `dispatch` awaits.
+- **Reducer purity is enforced by convention and testability, not by a
+  sandbox.** The type system carries the contract; the 100% coverage gate on
+  `irc-core` verifies it empirically.
+
+## Consequences
+
+**Positive:**
+- Every reducer is a trivial unit test: arrange state, apply message, assert
+  `state` and `effects`. No mocks, no fakes beyond an injected `Clock` and
+  `IdFactory`.
+- The same reducer code runs unchanged on in-memory, CF, and AWS runtimes.
+  Adapter work is "wire the runtime", not "rewrite the handler".
+- Reducer behaviour is deterministic and reproducible — critical for the
+  parametrized contract suite (TICKET-032) that runs identical scenarios
+  across all three runtimes.
+- Mutation testing (Stryker, TICKET-048) is meaningful because reducers have
+  no hidden IO to mask a mutation's effect.
+
+**Negative:**
+- The `Effect` union grows with every new side-effect type. Adding a novel
+  effect (e.g. `QueryHistory` for chathistory) requires touching `effects.ts`,
+  `dispatch.ts`, and every runtime implementation. This is by design (the
+  type system makes missing-runtime-support a compile error) but adds
+  ceremony.
+- Reducers cannot directly observe the result of a side effect they emit
+  (e.g. "did the broadcast actually reach anyone?"). Cross-effect
+  coordination is deferred to the actor layer, which can pre-fetch runtime
+  state before invoking the reducer.
+
+## References
+
+- PLAN §2.1 — "The key idea: pure reducers + location-of-authority"
+- PLAN §2.2 — `IrcRuntime` port
+- `packages/irc-core/src/effects.ts` — `Effect` union
+- `packages/irc-core/src/types.ts` — `Reducer<S>` signature
+- `packages/irc-server/src/dispatch.ts` — `dispatch(effects, runtime)`

package/docs/ADR-002-location-of-authority.md

@@ -0,0 +1,82 @@
+# ADR-002: Location-of-authority state split
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+An IRC server manages several kinds of state: connection records (nick, caps,
+away status), channel rosters (who is in `#foo`, with what prefix), channel
+metadata (topic, modes, ban lists), and the nick registry (nick → connection
+map). In a single-process ircd all of this lives in one address space, so
+read-modify-write races are handled with locks or a single event loop.
+
+ServerlessIRCd runs on stateless-per-request compute (Lambda) or
+per-entity-isolated compute (Durable Objects). There is no global lock. If
+two connections race to JOIN the same channel, or two clients race to claim
+the same nick, the outcome must still be correct. Traditional locking is
+impossible across instances.
+
+## Decision
+
+Each piece of state has **exactly one authority** — the single entity that
+owns the canonical copy and serializes all mutations to it. Reducers are
+routed to the authority that owns the state they mutate:
+
+| Command family | Authority | Primary state |
+|---|---|---|
+| Registration (NICK/USER/PASS) | Connection entity | `ConnectionState` |
+| PING/PONG, QUIT, AWAY, user MODE | Connection entity | `ConnectionState` |
+| JOIN/PART/channel MODE/TOPIC/KICK/INVITE | Channel entity | `ChannelState` + roster |
+| PRIVMSG/NOTICE to channel | Channel entity | Fanout (reads roster) |
+| PRIVMSG/NOTICE to user | Sender Connection | Nick → Connection route |
+| Nick reservation | Registry entity | Nick → Connection map |
+
+Cross-authority coordination is done via **effects**, not direct mutation.
+When a connection accepts a JOIN, the connection-authority reducer emits an
+`ApplyChannelDelta` effect that the channel authority consumes. The channel
+authority is the sole writer of its roster; the connection never touches it
+directly.
+
+Platform mapping:
+- **Cloudflare:** each authority is a Durable Object (`ConnectionDO`,
+  `ChannelDO`, `RegistryDO`). DO single-threaded serial execution gives the
+  uniqueness invariant for free — two concurrent requests to the same DO are
+  queued, not racing.
+- **AWS:** each authority is a DynamoDB table with conditional writes
+  (`ConditionExpression`) or `TransactWriteItems` for multi-row atomicity
+  (e.g. JOIN spans `Connections` and `ChannelMembers`).
+
+## Consequences
+
+**Positive:**
+- Races are structurally impossible, not defended against. Two clients
+  claiming the same nick both route to the same `RegistryDO` shard (or the
+  same `Nicks` row with a conditional PutItem) — exactly one wins.
+- The reducer signature stays uniform (`Reducer<S>`) regardless of which
+  authority it runs in. The actor layer routes; the reducer does not know or
+  care whether it is running in a DO or a Lambda.
+- Each authority can be tested in isolation. The channel reducer tests
+  arrange a `ChannelState` and assert effects; they never need a live
+  connection registry.
+
+**Negative:**
+- Cross-authority coordination requires a round-trip (DO `stub()` call on CF;
+  extra DynamoDB write on AWS). A JOIN that updates both the connection's
+  joined-list and the channel roster is two writes, not one.
+- The actor layer must pre-fetch authoritative state before invoking a
+  reducer (e.g. WHOIS needs the target connection's state from a different
+  authority). This adds a `prefetchChannelState` step in the actor pipeline.
+- Listing all channels (LIST) or resolving every member of a channel (WHO)
+  requires aggregating across authorities — there is no global view. The CF
+  adapter needs a channel registry (TICKET-073); the AWS adapter does a
+  DynamoDB scan.
+
+## References
+
+- PLAN §2.1 — location-of-authority table
+- PLAN §4 — state model & authoritative ownership
+- ADR-001 — pure reducers (how effects flow between authorities)
+- `packages/irc-server/src/actor.ts` — `route()` switch (authority routing)

package/docs/ADR-003-durable-object-sharding.md

@@ -0,0 +1,93 @@
+# ADR-003: Cloudflare Durable Object sharding strategy
+
+**Date:** 2025-02-01 (Phase 3)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+Cloudflare Durable Objects (DOs) are single-threaded per-instance: all
+requests to a given DO instance are serialized. This is ideal for enforcing
+uniqueness invariants (two racing requests land on the same DO, one after the
+other), but a single DO instance is a throughput ceiling. ServerlessIRCd needs
+three DO classes:
+
+1. **ConnectionDO** — one per WebSocket connection. Keyed by `connectionId`.
+   No sharding needed: each connection is its own instance.
+2. **ChannelDO** — one per channel. Keyed by lowercased channel name.
+   No sharding needed: one DO per channel is the natural unit; a hot channel
+   (1k+ members) is bounded by DO fanout latency, not by DO count.
+3. **RegistryDO** — holds the global nick → connectionId map. If this were a
+   single DO, every nick registration on the entire server would serialize
+   through one instance. That is an unacceptable bottleneck for any non-trivial
+   deployment.
+
+The open question (PLAN §9): *"Channel DO sharding granularity (one DO per
+channel vs. bucketed)?"* and *"Registry DO: how to shard?"*
+
+## Decision
+
+**ConnectionDO:** one instance per connection (`idFromName(connectionId)`).
+No sharding.
+
+**ChannelDO:** one instance per channel
+(`idFromName(lowercasedChannelName)`). No bucketing. If a hot channel exceeds
+DO throughput limits, the mitigation is fanout batching (one `stub()` call
+carrying multiple lines) rather than splitting the channel across DOs. A
+single channel's roster and modes live in one DO so that all mutations are
+serialized correctly.
+
+**RegistryDO:** sharded by `hash(lowercased(nick)) % N`, where `N` defaults
+to **32** (`DEFAULT_REGISTRY_SHARDS`). The hash function is FNV-1a 32-bit,
+chosen for its uniform distribution, deterministic output (no randomness),
+and trivial implementation.
+
+```
+shard = fnv1a32(nick.toLowerCase()) % N
+key   = `s${shard}`   // e.g. "s7", "s31"
+stub  = env.REGISTRY_DO.get(env.REGISTRY_DO.idFromName(key))
+```
+
+Two clients racing on the same nick always land on the same shard (because
+lowercasing collapses case variants), so the single-shard uniqueness check
+covers all case variants. Different nicks spread across shards, so
+registration throughput scales with the fleet size.
+
+Cross-shard nick changes (old nick and new nick hash to different shards)
+use a two-phase reserve-new-then-release-old. The new-nick shard wins the
+race; the old-nick shard is released only after the new reservation succeeds.
+
+`N` is configurable via the `REGISTRY_SHARDS` environment variable. Changing
+`N` in production requires a migration (re-sharding every existing nick entry
+to its new shard).
+
+## Consequences
+
+**Positive:**
+- Nick uniqueness is race-free within the DO model. No conditional writes,
+  no optimistic concurrency — the DO's serial execution is the lock.
+- Registration throughput scales horizontally: 32 shards handle 32× the
+  single-DO throughput for distinct nicks.
+- One DO per channel keeps channel semantics simple: JOIN/PART/MODE/KICK all
+  serialize through the same instance.
+
+**Negative:**
+- Changing `N` (the shard count) requires migrating every existing nick to
+  its new shard. This is an offline migration, not a live reshard. The shard
+  count should be chosen conservatively at deployment time.
+- The channel registry problem: there is no DO that "knows" all channels
+  (LIST, TICKET-073). A dedicated registry DO or KV index is needed — this is
+  a known gap tracked in TICKET-073.
+- Hot-nick collisions (many nicks hashing to the same shard) are possible but
+  statistically rare with FNV-1a and `N = 32` for typical populations.
+
+## References
+
+- PLAN §9 — open question: "Channel DO sharding granularity"
+- PLAN §6.1 — `RegistryDO` sharded by `hash(nick) % N`
+- `packages/cf-adapter/src/sharding.ts` — `shardNick`, `registryKeyForNick`,
+  `DEFAULT_REGISTRY_SHARDS = 32`
+- `packages/cf-adapter/src/registry-do.ts` — per-shard registry authority
+- TICKET-034 — RegistryDO implementation
+- TICKET-073 — CF runtime stubbed lookups (channel registry gap)