serverless-ircd 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -10,6 +10,90 @@ For the release process itself — versioning policy, pre-release checklist,
 cutting a tag, rolling back — see [`docs/release.md`](docs/release.md).
 Cross-reference `progress.md` / `tickets.md` for per-ticket detail.
 
+## [0.3.0] - 2026-07-25
+
+### Added — Operator authentication (`@serverless-ircd/irc-core`)
+
+- **`OPER` command reducer**: `OPER <name> <password>` authenticates the
+  caller against the deployment's configured operator credentials
+  (`OperCred[]`) and, on success, grants the `o` user mode, replying
+  `381 RPL_YOUREOPER`. Missing parameters → `461 ERR_NEEDMOREPARAMS`;
+  no credentials configured → `491 ERR_NOOPERHOST`; wrong name/password
+  → `464 ERR_PASSWDMISMATCH`. Already an operator is an idempotent
+  no-op that re-confirms with `381`. `OPER` is the *only* path to oper
+  — user `MODE +o` is hard-rejected with `481 ERR_NOPRIVILEGES` — and
+  unlocks the `313 RPL_WHOISOPERATOR` branch of WHOIS and the `*`
+  oper flag of WHO.
+
+### Added — IRCv3 `TAGMSG` (`@serverless-ircd/irc-core`)
+
+- **`TAGMSG` reducer** (message-tags extension): carries tags only, no
+  text body. Gated behind the `message-tags` capability (clients that
+  did not negotiate it see `421 ERR_UNKNOWNCOMMAND`). Follows NOTICE
+  semantics — no numeric error replies on any rejection path — for both
+  channel and user targets, and is recorded so `draft/chathistory`
+  replay picks up `TAGMSG` lines.
+
+### Added — RFC 1459 case-mapping (`@serverless-ircd/irc-core`)
+
+- **`case-fold.ts`**: RFC 1459 case-insensitive comparison for nicks
+  and channels, advertised via `005 CASEMAPPING=rfc1459`. Replaces the
+  prior ASCII-only comparison across nick collision/registry, kick and
+  invite target lookup, and membership matching.
+
+### Added — Registration MOTD (`@serverless-ircd/irc-core`)
+
+- The registration welcome now renders the **real configured MOTD**
+  (`motd-lines.ts`), replacing the placeholder banner. The `MOTD`
+  command and the welcome flow share one rendering path.
+
+### Added — Cloudflare adapter (`@serverless-ircd/cf-adapter`)
+
+- **`ChannelRegistryDO`**: a fourth Durable Object holding the channel
+  directory (channel name → `ChannelDO` routing), alongside
+  `ConnectionDO`, `ChannelDO`, and `RegistryDO`. Wired into the Worker
+  exports, bindings, and SQLite migrations.
+- **Cloudflare config loader**: reduces Workers `vars` to the shared
+  `ServerConfigSchema`, matching the AWS (`loadServerConfigFromLambdaEnv`)
+  and local-CLI loaders.
+- `CfRuntime` completed — the previously stubbed `IrcRuntime` methods
+  (`getConnection`, `getChannelConnections`, `listChannels`, and
+  cross-connection `disconnect`) are now implemented.
+
+### Added — SASL account persistence (`@serverless-ircd/aws-adapter`)
+
+- SASL `PLAIN` accounts are now persisted in the DynamoDB `Accounts`
+  table with **scrypt** password hashes (never plaintext). The Lambda
+  cold-start path scans the table once and loads credentials into the
+  synchronous `AccountStore` port.
+- **`tools/seed-aws-accounts.ts`**: provisioning script that scrypt-hashes
+  `username:password` pairs (from CLI args or a file) and writes them
+  to the `Accounts` table. Re-running with the same username overwrites
+  the prior row.
+
+### Changed
+
+- `@serverless-ircd/in-memory-runtime`: `admitConnection` now returns a
+  stable empty `recordId` when admission is disabled, dropping the
+  per-call id minting (the id was never consulted).
+- Deploy scripts: root `pnpm deploy:aws:staging` / `deploy:aws:prod`
+  now run `pnpm build` before `cdk deploy`, so the esbuild-bundled
+  Lambda picks up fresh workspace `dist/` — matching what CI already
+  did and fixing local deploys shipping stale code.
+
+### Known limitations
+
+- SASL `EXTERNAL` (mTLS) and production TLS transport remain pending
+  (0.x work).
+- Deployed stacks remain WebSocket-only; stock TCP IRC clients still
+  reach them through the local `tcp-ws-forwarder` bridge.
+
+### Security
+
+- None. No vulnerabilities have been reported or fixed in this release.
+
+---
+
 ## [0.2.0] - 2026-07-23
 
 ### Added — Authentication & flood control (`@serverless-ircd/irc-core`)

package/README.md

@@ -6,16 +6,20 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates. No S2S linking in v1.
 
-> **Status:** **v0.2.0 (preview).** The pure protocol core, the
+> **Status:** **v0.3.0 (preview).** The pure protocol core, the
 > `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
 > the **Cloudflare Workers** adapter, and the **AWS** (API Gateway
 > WebSocket + Lambda + DynamoDB + CDK) adapter are all functional and
-> deployed to staging. SASL (`PLAIN`), token-bucket flood control,
-> server-password enforcement, hostmask cloaking, connection admission,
-> IRCv3 chat history, and a CI coverage + mutation-testing gate landed
-> in v0.2.0. Remaining 0.x work: oper credentials /
-> config loader, SASL `EXTERNAL` (mTLS), and production TLS transport.
-> See `CHANGELOG.md` for the per-release manifests.
+> deployed to staging. v0.2.0 delivered SASL (`PLAIN`), token-bucket
+> flood control, server-password enforcement, hostmask cloaking,
+> connection admission, and IRCv3 chat history; v0.3.0 adds **OPER**
+> credential auth, the IRCv3 **TAGMSG** command, **RFC 1459
+> case-mapping**, a real **MOTD** in the registration welcome, a
+> **ChannelRegistryDO** (4th Cloudflare Durable Object) plus a
+> Cloudflare config loader, and **SASL account persistence** in
+> DynamoDB (scrypt hashes) with a `seed-aws-accounts` provisioning
+> tool. Remaining 0.x work: SASL `EXTERNAL` (mTLS) and production TLS
+> transport. See `CHANGELOG.md` for the per-release manifests.
 
 ---
 
@@ -57,8 +61,9 @@ Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
 │  packages/cf-adapter       │      │  packages/aws-adapter        │
 │    ConnectionDO            │      │    $connect/$disconnect/     │
 │    ChannelDO               │      │    $default Lambda handlers  │
-│    RegistryDO              │      │    DynamoDB tables           │
-│    CfRuntime               │      │    AwsRuntime                │
+│    ChannelRegistryDO       │      │    DynamoDB tables           │
+│    RegistryDO              │      │    AwsRuntime                │
+│    CfRuntime               │      │                              │
 └────────────────────────────┘      └──────────────────────────────┘
 ```
 
@@ -110,7 +115,8 @@ ServerlessIRCd/
 │   └── local-cli/         runnable WS + TCP server using in-memory-runtime
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
-│   └── ci-hardening/      coverage-gate + mutation-config validators
+│   ├── ci-hardening/      coverage-gate + mutation-config validators
+│   └── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
 ├── pnpm-workspace.yaml    turbo.json   tsconfig.base.json
 └── README.md              CHANGELOG.md
 ```
@@ -316,9 +322,9 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 - **Phase 4** — AWS adapter (APIGW WS + Lambda + DynamoDB + CDK).
   ✅ landed in **v0.2.0** (staging auto-deploy via CI; prod deploy is manual).
 - **Phase 5** — Observability, security hardening, config, CI gates.
-  ✅ mostly landed (logger port, server-password, cloaking, admission
-  limits, coverage + mutation gates). Remaining: oper credentials / config
-  loader.
+  ✅ landed (logger port, server-password, cloaking, admission limits,
+  coverage + mutation gates, OPER credential auth, and the Cloudflare
+  config loader all shipped across v0.2.0–v0.3.0).
 - **Phase 6** — Load testing, client compatibility sweep, ADRs.
 
 ---
@@ -328,15 +334,17 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 **Core (RFC 1459/2812 subset):** registration (`NICK`/`USER`/`CAP`/`PASS`),
 `PING`/`PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`, `MODE` (user +
 channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`, `MOTD`,
-`AWAY`.
+`AWAY`, `OPER` (credential auth → `o` user mode).
 
 **Channel modes:** `o v b i k l t n m s p`.
 **User modes:** `i`, `o` (local only), `w`, `s`.
 
-**IRCv3 extensions (negotiated via `CAP`):** `message-tags`, `server-time`,
-`account-tag`, `echo-message`, `batch`, `sasl` (`PLAIN` implemented,
-`EXTERNAL` reserved pending mTLS), `multi-prefix`, `away-notify`, `chghost`,
-`invite-notify`, `extended-join`, `draft/chathistory`, `safelist`.
+**IRCv3 extensions (negotiated via `CAP`):** `message-tags` (incl. the
+`TAGMSG` command), `server-time`, `account-tag`, `echo-message`, `batch`,
+`sasl` (`PLAIN` implemented, `EXTERNAL` reserved pending mTLS),
+`multi-prefix`, `away-notify`, `chghost`, `invite-notify`, `extended-join`,
+`draft/chathistory`, `safelist`. Case-insensitive nick/channel comparison
+uses **RFC 1459** case-mapping (advertised via `005 CASEMAPPING=rfc1459`).
 
 **Transport:** deployed stacks (Cloudflare Workers, AWS API Gateway) speak
 WebSocket text frames only (one IRC message per frame, with tolerance for
@@ -351,7 +359,8 @@ WebSocket endpoint through the local
 
 - `CHANGELOG.md` — per-release manifests (Keep a Changelog format), including
   the v0.2.0 work (AWS adapter, SASL, flood control, security hardening, CI
-  gates).
+  gates) and v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
+  ChannelRegistryDO, SASL account persistence).
 - `README.md` in each `packages/*` and `apps/*` — per-package notes (e.g.
   `packages/aws-adapter/README.md` for the DynamoDB-Local test setup,
   `apps/aws-stack/README.md` for CDK commands and localstack validation).

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",

package/apps/cf-worker/src/worker.ts

@@ -22,11 +22,17 @@
  * See `wrangler.toml` and `docs/deployment-cf.md`.
  */
 
-import { ChannelDO, ConnectionDO, type Env, RegistryDO } from '@serverless-ircd/cf-adapter';
+import {
+  ChannelDO,
+  ChannelRegistryDO,
+  ConnectionDO,
+  type Env,
+  RegistryDO,
+} from '@serverless-ircd/cf-adapter';
 
 // Re-exported for wrangler DO binding resolution. The class names below
 // MUST match `class_name` in `wrangler.toml`.
-export { ChannelDO, ConnectionDO, RegistryDO };
+export { ChannelDO, ChannelRegistryDO, ConnectionDO, RegistryDO };
 export type { Env };
 
 /**

package/apps/cf-worker/tests/smoke.test.ts

@@ -26,6 +26,7 @@ declare global {
       CONNECTION_DO: DurableObjectNamespace;
       REGISTRY_DO: DurableObjectNamespace;
       CHANNEL_DO: DurableObjectNamespace;
+      CHANNEL_REGISTRY_DO: DurableObjectNamespace;
       SERVER_NAME: string;
       NETWORK_NAME: string;
       MOTD_LINES: string;

package/apps/cf-worker/wrangler.test.toml

@@ -28,6 +28,10 @@ class_name = "RegistryDO"
 name = "CHANNEL_DO"
 class_name = "ChannelDO"
 
+[[durable_objects.bindings]]
+name = "CHANNEL_REGISTRY_DO"
+class_name = "ChannelRegistryDO"
+
 [[migrations]]
 tag = "v1"
-new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
+new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]

package/apps/cf-worker/wrangler.toml

@@ -91,6 +91,10 @@ class_name = "RegistryDO"
 name = "CHANNEL_DO"
 class_name = "ChannelDO"
 
+[[durable_objects.bindings]]
+name = "CHANNEL_REGISTRY_DO"
+class_name = "ChannelRegistryDO"
+
 # Staging environment bindings (wrangler requires per-env blocks).
 [[env.staging.durable_objects.bindings]]
 name = "CONNECTION_DO"
@@ -104,20 +108,40 @@ class_name = "RegistryDO"
 name = "CHANNEL_DO"
 class_name = "ChannelDO"
 
-## ---------------------------------------------------------------------------
-## Durable Object migrations.
-## ---------------------------------------------------------------------------
-## `tag` is the user-defined migration id; wrangler refuses to deploy if
-## the on-disk migrations don't match the live Workers state. `new_classes`
-## declares the three DO classes on first deploy; subsequent schema
-## changes (renames, deletions, splits) extend this list with their own
-## `tag` so the runtime can migrate persisted state.
-##
-## See https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
-[[migrations]]
-tag = "v1"
-new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
-
-[[env.staging.migrations]]
-tag = "v1"
-new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
+[[env.staging.durable_objects.bindings]]
+name = "CHANNEL_REGISTRY_DO"
+class_name = "ChannelRegistryDO"
+
+# ## ---------------------------------------------------------------------------
+# ## Durable Object migrations.
+# ## ---------------------------------------------------------------------------
+# ## `tag` is the user-defined migration id; wrangler refuses to deploy if
+# ## the on-disk migrations don't match the live Workers state. `new_classes`
+# ## declares the three DO classes on first deploy; subsequent schema
+# ## changes (renames, deletions, splits) extend this list with their own
+# ## `tag` so the runtime can migrate persisted state.
+# ##
+# ## See https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
+# [[migrations]]
+# tag = "v1"
+# new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
+
+# [[env.staging.migrations]]
+# tag = "v1"
+# new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
+
+[exports.ConnectionDO]
+type = "durable-object"
+storage = "sqlite"
+
+[exports.RegistryDO]
+type = "durable-object"
+storage = "sqlite"
+
+[exports.ChannelDO]
+type = "durable-object"
+storage = "sqlite"
+
+[exports.ChannelRegistryDO]
+type = "durable-object"
+storage = "sqlite"

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
   "license": "BSD-3-Clause",

package/apps/local-cli/src/config-loader.ts

@@ -32,6 +32,7 @@ export interface CliConfigInput {
   channelLen?: number;
   topicLen?: number;
   quitMessage?: string;
+  saslAccounts?: Array<{ username: string; password: string }>;
 }
 
 /**

package/apps/local-cli/src/main.ts

@@ -14,7 +14,7 @@
  * Both listeners share one runtime, so a TCP client and a WS client can
  * see each other (cross-transport channel broadcast). Pass `--no-tcp` to
  * run WebSocket-only; the WebSocket port / hostname / MOTD are tunable via
- * flags (a fuller config-loader lands in a later ticket).
+ * flags.
  *
  * Usage:
  *   pnpm --filter local-cli start -- --port 6667 --tcp-port 6668 --host 127.0.0.1

package/apps/local-cli/src/server.ts

@@ -28,10 +28,12 @@ import { randomUUID } from 'node:crypto';
 import { type Server, type Socket, createServer } from 'node:net';
 import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
 import {
+  type AccountStore,
   type AdmissionConfig,
   type ChanName,
   type ConnectionState,
   ConsoleLogger,
+  InMemoryAccountStore,
   InMemoryMessageStore,
   LogLevel,
   type Logger,
@@ -57,6 +59,7 @@ type ResolvedServerConfig = Omit<
   | 'maxConnectionsPerUser'
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
+  | 'saslAccounts'
 > &
   Pick<
     LocalServerConfig,
@@ -65,6 +68,7 @@ type ResolvedServerConfig = Omit<
     | 'maxConnectionsPerIp'
     | 'maxConnectionsPerUser'
     | 'perIpConnectionRate'
+    | 'saslAccounts'
   >;
 
 /** Default per-IP / per-user caps used when callers don't override. */
@@ -121,6 +125,13 @@ export interface LocalServerConfig {
    * CLI — the store is bound unconditionally).
    */
   historyMaxPerChannel?: number;
+  /**
+   * SASL PLAIN account credentials. When non-empty the server seeds an
+   * in-memory {@link AccountStore} so `AUTHENTICATE PLAIN` succeeds for the
+   * listed accounts. When omitted/empty, SASL account verification is
+   * disabled (`ctx.accounts` undefined → `904 ERR_SASLFAIL`).
+   */
+  saslAccounts?: Array<{ username: string; password: string }>;
 }
 
 export interface StartServerOptions extends LocalServerConfig {
@@ -178,6 +189,7 @@ const DEFAULT_CONFIG: Omit<
   | 'maxConnectionsPerUser'
   | 'perIpConnectionRate'
   | 'historyMaxPerChannel'
+  | 'saslAccounts'
 > = {
   serverName: 'irc.example.com',
   networkName: 'ExampleNet',
@@ -242,6 +254,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ...(opts.channelLen !== undefined ? { channelLen: opts.channelLen } : {}),
       ...(opts.topicLen !== undefined ? { topicLen: opts.topicLen } : {}),
       ...(opts.quitMessage !== undefined ? { quitMessage: opts.quitMessage } : {}),
+      ...(opts.saslAccounts !== undefined ? { saslAccounts: opts.saslAccounts } : {}),
     });
   } catch (err) {
     return Promise.reject(err);
@@ -268,6 +281,9 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     ...(opts.perIpConnectionRate !== undefined
       ? { perIpConnectionRate: opts.perIpConnectionRate }
       : {}),
+    ...(opts.saslAccounts !== undefined && opts.saslAccounts.length > 0
+      ? { saslAccounts: opts.saslAccounts }
+      : {}),
   };
   const hostname = opts.hostname ?? '127.0.0.1';
 
@@ -295,6 +311,14 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   // is replayable when bob queries CHATHISTORY). The cap is config-driven.
   const messages = new InMemoryMessageStore(opts.historyMaxPerChannel);
 
+  // SASL account store: seeded from config so `AUTHENTICATE PLAIN` works
+  // end-to-end. `undefined` (no accounts configured) leaves the actor's
+  // `ctx.accounts` unset, preserving the no-store behaviour.
+  const accounts =
+    cfg.saslAccounts !== undefined && cfg.saslAccounts.length > 0
+      ? new InMemoryAccountStore(cfg.saslAccounts)
+      : undefined;
+
   const wss = new WebSocketServer({ port: opts.port, host: hostname });
   const wsConnections = new Map<WebSocket, ConnectionBindings>();
 
@@ -312,7 +336,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     const admissionRecordId = decision.recordId;
     runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-    const { state, actor } = attachConnection(runtime, cfg, messages, {
+    const { state, actor } = attachConnection(runtime, cfg, messages, accounts, {
       sendText: (text) => {
         if (ws.readyState === WebSocket.OPEN) ws.send(text);
       },
@@ -389,7 +413,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
         const admissionRecordId = decision.recordId;
         runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-        const { state, actor } = attachConnection(runtime, cfg, messages, {
+        const { state, actor } = attachConnection(runtime, cfg, messages, accounts, {
           sendText: (text) => {
             if (socket.writable) socket.write(text);
           },
@@ -481,6 +505,7 @@ function attachConnection(
   runtime: InMemoryRuntime,
   cfg: ResolvedServerConfig,
   messages: MessageStore,
+  accounts: AccountStore | undefined,
   transport: {
     sendText: (text: string) => void;
     closeTransport: () => void;
@@ -523,6 +548,7 @@ function attachConnection(
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
     messages,
+    ...(accounts !== undefined ? { accounts } : {}),
     logger,
   });
 

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

@@ -418,3 +418,55 @@ describe('local-cli chathistory end-to-end', () => {
     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/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)