serverless-ircd 0.5.0 → 0.6.0

package/apps/local-cli/tests/ws-subprotocol.test.ts

@@ -92,7 +92,12 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
   let server: LocalServer;
 
   beforeAll(async () => {
-    server = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    server = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      serverName: 'irc.local.example.com',
+      networkName: 'LocalNet',
+    });
   });
 
   afterAll(async () => {
@@ -121,7 +126,7 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.opened();
     await client.send('NICK spec-bin');
     await client.send('USER spec-bin 0 * :Spec Bin');
-    const welcome = await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    const welcome = await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     expect(welcome).toContain('spec-bin');
 
     await client.send('PING :bin-tok');
@@ -172,7 +177,7 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     // One bare line per WS message (no trailing CRLF).
     await client.send('NICK spec-alice');
     await client.send('USER spec-alice 0 * :Spec Alice');
-    const welcome = await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    const welcome = await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
     expect(welcome).toContain('spec-alice');
 
     // Every received message must be a single IRC line with no trailing CRLF
@@ -189,7 +194,7 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.opened();
     await client.send('NICK spec-bob');
     await client.send('USER spec-bob 0 * :Spec Bob');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     // The welcome sequence is many numerics (001..005, 375/372/376). In spec
     // mode each arrives as its own WS message; a legacy batch would have
@@ -204,7 +209,7 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.opened();
     await client.send('NICK spec-ping');
     await client.send('USER spec-ping 0 * :Spec Ping');
-    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
     await client.send('PING :spec-tok');
     const pong = await client.waitFor((l) => l === 'PONG :spec-tok');
@@ -219,7 +224,7 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
     await client.send('USER spec-budget 0 * :Spec Budget');
     // Drain the entire registration burst (001..376) so delayed numerics
     // don't pollute the post-overlong-message assertion below.
-    await client.waitFor((l) => l.startsWith(':irc.example.com 376 '));
+    await client.waitFor((l) => l.startsWith(':irc.local.example.com 376 '));
 
     client.received.length = 0;
     // 511-byte payload: `PRIVMSG #x :` (12 bytes) + 499 chars = 511 total.
@@ -244,7 +249,7 @@ describe('local-cli IRCv3 WebSocket subprotocol', () => {
       await client.opened();
       await client.send(`NICK ${nick}`);
       await client.send(`USER ${nick} 0 * :Spec Disc`);
-      await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+      await client.waitFor((l) => l.startsWith(':irc.local.example.com 001 '));
 
       const connId = await server.runtime.lookupNick(nick);
       expect(connId).not.toBeNull();

package/biome.json

@@ -10,6 +10,7 @@
     "ignore": [
       "**/dist/**",
       "**/coverage/**",
+      "**/coverage-self-test/**",
       "**/node_modules/**",
       "**/.turbo/**",
       "pnpm-lock.yaml",

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,110 @@
+# 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.
+
+### Outbound batching scope (TICKET-087)
+
+The fanout batching decided above is implemented **per call**:
+`ConnectionDO.deliver()` joins every line of one ChannelDO broadcast into a
+single `WebSocket.send()`, and the actor's `send` handler does the same for
+all lines of one frame's response. A speculative **cross-call** coalescing
+optimization (queueing lines from independent `deliver`/`send` invocations
+within one microtask and flushing them as one write) was reserved as a
+commented-out field in `ConnectionDO` and subsequently **dropped**: it would
+add a drain queue and a `queueMicrotask` scheduler, introduce ordering
+hazards between independent fan-out calls, and yield no measured benefit —
+nothing in the TICKET-049 load-test report or the ChannelDO fan-out path
+shows WS round-trips as a bottleneck. The AWS adapter batches at a different
+layer (per-invocation `outbound: string[]` accumulated then posted once), so
+no shared abstraction is worth extracting. Revisit only if WS round-trips
+become a demonstrated bottleneck.
+
+## 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)

package/docs/ADR-004-dynamodb-schema.md

@@ -0,0 +1,96 @@
+# ADR-004: AWS DynamoDB schema
+
+**Date:** 2025-02-15 (Phase 4)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+The AWS adapter runs IRC state on DynamoDB (single table family, not
+single-table design). Unlike Cloudflare Durable Objects, DynamoDB does not
+serialize access to a record by default — concurrent writes can interleave.
+Nick uniqueness, channel membership atomicity, and gone-connection cleanup
+all require explicit concurrency control.
+
+The schema must support: connection records, channel metadata, channel
+membership (roster), nick registry, and SASL account credentials. It must
+also handle the Lambda invocation model: each `$default` invocation is a
+fresh process that reads state, runs a reducer, and writes back — there is no
+in-memory state between invocations.
+
+## Decision
+
+Five tables, each with a clear partition-key boundary:
+
+| Table | Partition Key | Sort Key | TTL | Purpose |
+|---|---|---|---|---|
+| `Connections` | `connectionId` | — | `idleSince` | Per-connection state: nick, user, host, caps, joined channels, away |
+| `ChannelMeta` | `channelName` | — | — | Topic, modes, key, limit |
+| `ChannelMembers` | `channelName` | `connectionId` | — | Roster: membership + prefix flags (op/voice) |
+| `Nicks` | `nickLower` | — | — | Nick → connectionId registry |
+| `Accounts` | `account` | — | — | SASL credentials (scrypt-hashed, never plaintext) |
+
+**Concurrency invariants:**
+- **Nick uniqueness:** enforced via conditional `PutItem`
+  (`ConditionExpression: attribute_not_exists(nickLower)`). Two racing
+  Puts for the same nick — exactly one succeeds; the other gets a
+  `ConditionalCheckFailedException` → `433 ERR_NICKNAMEINUSE`.
+- **Membership atomicity:** `TransactWriteItems` spans `Connections`
+  (update `joinedChannels`) and `ChannelMembers` (add/remove member) in a
+  single atomic transaction. Concurrent JOIN/PART by the same connection
+  cannot leave inconsistent state.
+- **Gone connections:** `ApiGatewayManagementApi.postToConnection` throws
+  `GoneException` for a stale connection. The handler catches this, triggers
+  lazy cleanup (removes the `Connections` row + `ChannelMembers` rows), and
+  broadcasts QUIT to peers (TICKET-074). A sweeper Lambda reaps rows whose
+  `idleSince` TTL has expired.
+- **Environment isolation:** physical table names are environment-prefixed
+  (`<Env>Connections`, e.g. `StagingConnections`) so staging and production
+  can coexist in the same account + region (TICKET-066).
+
+**SASL credentials** (`Accounts`): stored as scrypt `HashedAccountCredential`
+rows (`{ account, algorithm, salt, hash }`, base64-encoded). The Lambda
+pre-loads all rows at cold start into an in-memory `DynamoAccountStore`; the
+reducer's `AccountStore.verify()` stays synchronous (reducers are pure — no
+async). Seed tooling (`tools/seed-aws-accounts.ts`) writes hashed rows; never
+plaintext.
+
+## Consequences
+
+**Positive:**
+- Clear separation of concerns: each table is one authority (matches
+  ADR-002). A channel's metadata, membership, and each member's connection
+  record are independently addressable.
+- Conditional writes + `TransactWriteItems` give race-free semantics without
+  locks — the natural fit for DynamoDB.
+- `idleSince` TTL auto-reaps idle connections even if the sweeper misses a
+  tick; the sweeper is a belt-and-suspenders cleanup, not the only path.
+- Pay-per-request billing means idle tables cost nothing; the schema does not
+  over-provision.
+
+**Negative:**
+- Five tables (vs. a single-table design) means more `TransactWriteItems`
+  spanning multiple partitions. `TransactWriteItems` consumes more RCUs than
+  individual writes and has a 100-item-per-transaction cap. Membership
+  transactions are 2 items (well within limits), but a future feature that
+  touches many channels in one command could approach the cap.
+- No cross-table GSI for "all channels a connection is in" — the
+  `Connections` row stores `joinedChannels` as a set, which must be updated
+  on every JOIN/PART. This duplicates membership data between `Connections`
+  and `ChannelMembers`, kept consistent by the transaction.
+- `Accounts` pre-loading at cold start means every Lambda cold start scans
+  the table. For deployments with thousands of accounts, this adds latency.
+  Mitigated by Lambda reuse (warm starts skip the scan); a cache layer or
+  on-demand lookup is a documented follow-up.
+
+## References
+
+- PLAN §4 — state model & authoritative ownership
+- PLAN §6.2 — DynamoDB tables
+- `packages/aws-adapter/src/cdk-table-defs.ts` — `TABLE_DEFS` (source of truth)
+- `packages/aws-adapter/src/aws-runtime.ts` — `AwsRuntime` implementation
+- TICKET-039 — CDK stack
+- TICKET-041 — DynamoDB transactions for membership
+- TICKET-066 — environment-name prefixing
+- TICKET-072 — `Accounts` table scrypt-hashed `AccountStore`

package/docs/ADR-005-wss-only-transport-v1.md

@@ -0,0 +1,83 @@
+# ADR-005: wss-only transport in v1 (no raw TCP)
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Superseded by ADR-009 (Phase 7 — TICKET-052)
+**Supersedes:** —
+
+## Context
+
+IRC is traditionally spoken over raw TCP (port 6667 plaintext, 6697 TLS).
+WebSocket Secure (wss) is a framing layer over TLS that adds an HTTP upgrade
+handshake. Serverless compute platforms have fundamentally different support
+for these two transports:
+
+- **Cloudflare Workers** can accept WebSocket upgrades but **cannot accept raw
+  TCP**. Spectrum (Enterprise tier) can terminate TLS and proxy to an origin,
+  but Workers itself is request-response.
+- **AWS API Gateway WebSocket API** provides persistent WebSocket connections
+  with per-message Lambda invocation. Raw TCP requires a Network Load Balancer
+  + Lambda streaming (invoke mode) — a fundamentally different integration.
+
+The v1 goal is a clean serverless story: one codebase, two adapters, zero
+stateful origin servers. Raw TCP on either platform requires additional,
+non-serverless infrastructure (a long-running container on CF; NLB + Lambda
+streaming on AWS).
+
+Additionally, wss carries one IRC message per WebSocket text frame, which
+simplifies framing: the server does not need to implement a stateful
+byte-stream line buffer. The parser still tolerates `\r\n`-joined frames
+(multiple messages in one text frame) for robustness, but the common case is
+one-message-per-frame.
+
+## Decision
+
+v1 ships **wss-only**. No plaintext TCP listener, no `irc://` scheme, no
+port 6667/6697. Clients connect via `wss://server.tld/` and speak IRC inside
+WebSocket text frames.
+
+Rationale:
+1. Both target platforms support wss natively without additional
+   infrastructure.
+2. wss is TLS-terminated at the edge (CF) or at API Gateway (AWS) — the
+   Lambda/Worker never sees plaintext credentials.
+3. One-message-per-frame eliminates the need for a TCP-style line-framing
+   buffer in the core (though the parser tolerates joined frames).
+4. The serverless cost/ops model is clean: no long-running origin, no TCP
+   keepalive management.
+
+The `ConnectionActor` transport seam accepts WebSocket text frames directly.
+A `Transport` interface is not abstracted in v1 — the actor's
+`receiveTextFrame(text)` is the only entry point.
+
+## Consequences
+
+**Positive:**
+- Zero infrastructure beyond the serverless platform. No TCP listener, no
+  origin server, no port management.
+- TLS everywhere — no accidental plaintext exposure.
+- Simple framing: WebSocket text frames are message-delimited by definition.
+- Lower operational burden for v1.
+
+**Negative:**
+- RFC 1459/2812 clients that only speak raw TCP cannot connect. WeeChat and
+  HexChat support WebSocket; some older clients and bots do not.
+- The WebSocket overhead (HTTP upgrade, per-frame masking) adds ~2–10 bytes
+  per message vs. raw TCP. Negligible for IRC's small message sizes.
+- Some IRCv3 extensions assume a TCP transport (e.g. SASL EXTERNAL via client
+  certs over TLS passthrough). Without raw TCP, mTLS must be done at the edge
+  (CF API Shield, API Gateway custom domain), which changes the cert
+  verification surface.
+
+**Superseded:** Phase 7 (TICKET-052) reverses this decision for v1.x: a
+dual-transport model (wss stays the default; `irc+tls` on :6697 is added via
+Cloudflare Spectrum + Container origin, and AWS NLB + Lambda streaming). This
+ADR documents the original v1 rationale; the superseding ADR covers the
+reversal and per-platform TCP+TLS mapping.
+
+## References
+
+- PLAN §3 — "No plaintext TCP in v1 (wss only)"
+- PLAN §9 — "Framing: wss-only"
+- TICKET-052 — superseding ADR: dual wss + irc+tls
+- `packages/irc-server/src/actor.ts` — `receiveTextFrame(text)` (single
+  transport entry point in v1)

package/docs/ADR-006-sasl-mechanism-scope.md

@@ -0,0 +1,96 @@
+# ADR-006: SASL mechanism scope (PLAIN always; EXTERNAL mTLS-conditional)
+
+**Date:** 2025-01-20 (Phase 1) · revised 2025-07-27 (TICKET-079)
+**Status:** Superseded (TICKET-079)
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+IRCv3 SASL (`CAP sasl`) lets a client authenticate during registration,
+before the welcome sequence. The server advertises supported mechanisms in
+the `sasl` cap value (e.g. `sasl=PLAIN,EXTERNAL`). Each mechanism has
+different infrastructure requirements:
+
+- **PLAIN:** the client sends `AUTHENTICATE PLAIN`, then a base64 payload of
+  `\0username\0password`. The server verifies the credentials against an
+  `AccountStore`. No client certificates, no TLS-passthrough — works over
+  any transport, including wss with edge-terminated TLS.
+- **EXTERNAL:** the server authenticates the client based on an external
+  identity, typically a client certificate verified via mutual TLS (mTLS).
+  This requires the TLS handshake to present the client cert to the
+  application layer. On serverless platforms with edge-terminated TLS
+  (Cloudflare, API Gateway), the application does not see the raw client
+  cert — it must be configured at the edge (API Shield mTLS, custom-domain
+  mTLS trust store). That infrastructure does not exist in v1 (ADR-005:
+  wss-only, no raw TCP; mTLS passthrough is Phase 7, TICKET-054).
+
+## Decision
+
+The server ships **SASL PLAIN** as the always-available mechanism and
+**SASL EXTERNAL** as an mTLS-conditional mechanism:
+
+- When **no** `MtlsIdentityProvider` is bound to the connection (the default
+  for non-mTLS deployments), the `sasl` cap advertises `PLAIN` only and
+  `AUTHENTICATE EXTERNAL` returns `908 ERR_SASLMECHS` listing `PLAIN` as the
+  sole available mechanism.
+- When an `MtlsIdentityProvider` **is** bound (the operator configured mTLS
+  at the edge — CF API Shield mTLS or AWS custom-domain mTLS), the `sasl` cap
+  advertises `PLAIN,EXTERNAL` and `AUTHENTICATE EXTERNAL` proceeds through
+  the full handshake: the verified client-cert subject is resolved via the
+  provider and verified against the `AccountStore`.
+
+This means EXTERNAL advertisement and functionality are driven entirely by
+whether mTLS is configured — operators enable EXTERNAL by configuring edge
+mTLS, with no code change required. The `saslCapValue(hasMtls)` helper in
+`caps/capabilities.ts` and the `supportedMechs(ctx)` helper in
+`commands/sasl.ts` are the single sources of truth for the advertised value.
+
+`AccountStore` is a port in `irc-core` consumed by the SASL reducer. The
+`verify(mechanism, payload)` method is **synchronous** — adapters pre-load
+credentials at boot so the reducer stays pure (ADR-001). PLAIN verification
+decodes the base64 payload, extracts username + password, and matches
+against the store. EXTERNAL verification resolves the cert subject via the
+`MtlsIdentityProvider` and matches it against the store.
+
+## Consequences
+
+**Positive:**
+- PLAIN works end-to-end with no special infrastructure. The
+  `AccountStore` port abstracts the credential store; adapters seed it from
+  config (in-memory), DynamoDB (AWS), or a persistent backend (D1/DO for CF,
+  TICKET-093).
+- EXTERNAL is fully functional when mTLS is configured (TICKET-054) and
+  correctly unadvertised when it is not — clients never waste a round-trip
+  on a mechanism that cannot succeed.
+- The mTLS-conditional advertisement is driven by the `MtlsIdentityProvider`
+  binding, so operators enable EXTERNAL by configuring edge mTLS with no
+  code change.
+- The synchronous `AccountStore.verify()` keeps the reducer pure and
+  deterministic. Async credential lookups (DynamoDB) are resolved at cold
+  start or via pre-loading, not inside the reducer.
+
+**Negative:**
+- Deployments without mTLS (the common case) cannot offer EXTERNAL. This is
+  inherent — EXTERNAL requires client-certificate verification at the TLS
+  layer, which is only available via edge mTLS configuration.
+- PLAIN sends the password base64-encoded (not encrypted) inside the wss
+  frame. wss provides the TLS layer, so the password is encrypted in transit
+  — but PLAIN is still weaker than EXTERNAL (no mutual auth).
+- The synchronous `AccountStore` contract means the adapter must pre-load all
+  credentials. For deployments with many accounts, cold-start latency grows
+  linearly with account count. A lazy/async lookup variant is a documented
+  follow-up but would require an async-reducer or effect-based credential
+  query — a significant architecture change.
+
+## References
+
+- PLAN §3 — "sasl (mechanisms: PLAIN, EXTERNAL reserved for later with mTLS)"
+- PLAN §9 — SASL mechanism scope
+- TICKET-026 — SASL reducer implementation
+- TICKET-071 — AccountStore wiring into ConnectionActor
+- TICKET-072 — AWS DynamoDB AccountStore (scrypt hashing)
+- TICKET-079 — SASL EXTERNAL: implement or stop advertising (interim decision)
+- TICKET-054 — mTLS support (Phase 7, enables functional EXTERNAL)
+- `packages/irc-core/src/commands/sasl.ts` — `authenticateReducer`
+- `packages/irc-core/src/ports.ts` — `AccountStore` port