serverless-ircd 0.2.0 → 0.3.0

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)

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,86 @@
+# ADR-006: SASL mechanism scope (PLAIN only, EXTERNAL deferred)
+
+**Date:** 2025-01-20 (Phase 1)
+**Status:** Accepted (EXTERNAL re-evaluation tracked in 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
+
+v1 ships **SASL PLAIN only** as a functional mechanism. EXTERNAL is
+**recognized but stubbed**: the reducer accepts `AUTHENTICATE EXTERNAL`,
+acknowledges the mechanism, and immediately returns `904 ERR_SASLFAIL` with a
+documented code comment cross-referencing TICKET-054 (mTLS) and TICKET-079
+(decision: implement or stop advertising).
+
+The `sasl` cap advertises `PLAIN,EXTERNAL` (both names listed) so clients
+that probe mechanism availability see EXTERNAL as nominally supported. The
+actual `904` on EXTERNAL attempt is the functional gate. TICKET-079 is the
+follow-up that decides whether to implement EXTERNAL against a pluggable
+`MtlsIdentityProvider` or stop advertising it until mTLS lands.
+
+`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.
+
+## Consequences
+
+**Positive:**
+- PLAIN works end-to-end in v1 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 forward-compatible: advertising it now means clients that
+  prefer EXTERNAL will attempt it; once mTLS lands (Phase 7), the same
+  `AUTHENTICATE EXTERNAL` flow succeeds without a client-side 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:**
+- EXTERNAL is advertised but non-functional in v1 — a client that negotiates
+  `sasl` and sends `AUTHENTICATE EXTERNAL` gets `904` with no actionable
+  error message. This is a poor UX until TICKET-079 resolves (stop-advertising
+  is the recommended interim per the ticket).
+- 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

package/docs/ADR-007-deterministic-ports.md

@@ -0,0 +1,82 @@
+# ADR-007: Deterministic ports for time and ID generation
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+IRC protocol behaviour is time-sensitive: idle/PING timers, WHOIS signon
+time, `server-time` tags (ISO-8601 timestamps on every message), SASL nonce
+generation, chathistory message IDs. A traditional ircd calls `Date.now()`
+and `crypto.randomUUID()` directly in handlers. This makes tests
+non-deterministic: the same input produces different output on every run,
+depending on when the test executed.
+
+Non-determinism is fatal for the parametrized contract suite (TICKET-032),
+which runs identical scenarios across in-memory, CF, and AWS runtimes. If a
+reducer embeds `Date.now()`, the expected `@time=` tag changes every
+millisecond and the assertion cannot be written.
+
+## Decision
+
+Time and ID generation are **injected ports**, not global calls:
+
+```ts
+interface Clock {
+  now(): number;  // epoch milliseconds
+}
+
+interface IdFactory {
+  nonce(): string;     // unique message ID for message-tags/chathistory
+  traceId(): string;   // per-request trace ID for observability
+}
+```
+
+Both are passed through `Ctx` to every reducer. Reducers read `ctx.clock.now()`
+and `ctx.ids.nonce()` — never `Date.now()` or `Math.random()`.
+
+Concrete implementations:
+- **`FakeClock`** (tests): returns a fixed value set at construction.
+  Deterministic: `new FakeClock(10_000)` always reports `now() === 10_000`.
+- **`SystemClock`** (production): wraps `Date.now()`.
+- **`SequentialIdFactory`** (tests): returns `id-0`, `id-1`, `id-2`, …
+  Deterministic: the same sequence of calls produces the same IDs.
+- **`RandomIdFactory`** (production): wraps `crypto.randomUUID()`.
+
+## Consequences
+
+**Positive:**
+- Reducer tests are fully deterministic. The same `(state, message, ctx)`
+  triple always produces the same `{ state, effects }`. No flaky tests.
+- The contract suite can assert exact wire output including `@time=` tags
+  and `msgid=` tags, because the fake clock and ID factory are pinned.
+- Time travel is trivial in tests: advance the `FakeClock` between messages
+  to test idle/PING logic, flood-control refill, and chathistory bounds.
+- The reducer purity contract (ADR-001) is enforceable: a reducer that calls
+  `Date.now()` is simply not using the injected port, and the test will fail
+  because the output is wrong.
+
+**Negative:**
+- Every call site that needs time or an ID must thread `ctx` — there is no
+  shortcut. This is a small constant cost per reducer.
+- The `Clock` and `IdFactory` must be consistent across the actor's lifetime.
+  The actor pins them at construction; switching mid-connection would
+  produce inconsistent timestamps. This is enforced by the actor's readonly
+  fields.
+- `Date.now()` resolution is milliseconds; sub-millisecond ordering is not
+  possible with this port. This has not been a problem for IRC (message
+  ordering is preserved by connection/channel authority serialization, not
+  by timestamp).
+
+## References
+
+- PLAN §9 — "Time/IDs: injected ports (Clock, IdFactory) for deterministic
+  tests"
+- PLAN §8 — "Determinism rules: inject a Clock and deterministic ID/nonce
+  ports. No real timers/random in reducers."
+- ADR-001 — pure reducers (why determinism matters)
+- `packages/irc-core/src/ports.ts` — `Clock`, `IdFactory`, `FakeClock`,
+  `SequentialIdFactory`, `SystemClock`, `RandomIdFactory`
+- `packages/irc-core/src/types.ts` — `Ctx.clock`, `Ctx.ids`

package/docs/ADR-008-monorepo-tooling.md

@@ -0,0 +1,60 @@
+# ADR-008: Monorepo and tooling stack
+
+**Date:** 2025-01-10 (Phase 0)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+ServerlessIRCd is a multi-package TypeScript project: a platform-agnostic
+core (`irc-core`), an orchestration layer (`irc-server`), a reference runtime
+(`in-memory-runtime`), two cloud adapters (`cf-adapter`, `aws-adapter`), and
+several apps (`local-cli`, `cf-worker`, `aws-stack`). The toolchain must
+support cross-package type checking, incremental builds, a unified test
+runner, and CI that enforces coverage gates per package.
+
+## Decision
+
+| Concern | Choice | Rationale |
+|---|---|---|
+| Package manager | **pnpm** (workspaces) | Fast, disk-efficient, first-class monorepo support |
+| Build orchestration | **turbo** (caching) | Incremental builds, remote cache, task dependency graph |
+| TypeScript | Project references + `tsconfig.base.json` | Strict mode, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess` |
+| Test runner | **vitest** | ESM-native, fast, integrates with Workers (`vitest-pool-workers`), built-in coverage |
+| Coverage | v8 provider, gate ≥90% (100% on `irc-core`) | Enforced in CI (`.github/workflows/ci.yml`) |
+| Lint/format | **Biome** | Single tool (replaces ESLint + Prettier), fast, zero config drift |
+| CF bundler | **wrangler** (esbuild internally) | Native Workers toolchain |
+| AWS bundler | **esbuild** (Lambda bundles) + **CDK v2** (infra) | Tree-shaking, fast cold starts |
+| Runtime target | Node 20 (Lambda) + latest Workers runtime; ES2022+ | Aligns with platform-supported runtimes |
+
+## Consequences
+
+**Positive:**
+- pnpm workspaces + turbo give fast local dev: only changed packages rebuild;
+  tests run incrementally.
+- vitest's ESM-native design avoids the CJS/ESM interop pain that plagues
+  Jest-based monorepos. The same test files run under `vitest-pool-workers`
+  (real `workerd`) for CF adapter tests.
+- Biome eliminates the ESLint/Prettier config drift problem — one tool, one
+  config, one command (`biome check`).
+- TypeScript project references enforce package boundaries at compile time:
+  `irc-core` cannot accidentally import from `cf-adapter`.
+
+**Negative:**
+- pnpm's strict node-linker can surprise contributors used to npm/yarn's
+  hoisting. `node_modules` is per-package; global scripts need
+  `pnpm --filter`.
+- turbo's caching requires consistent environment hashing; a CI cache miss
+  (e.g. different Node minor version) degrades to a full rebuild silently.
+- Biome is newer than ESLint and lacks some ecosystem plugins. Custom rules
+  (e.g. "no ticket IDs in source files") are enforced via convention
+  (`AGENTS.md`) rather than a Biome plugin.
+
+## References
+
+- PLAN §9 — "Monorepo: pnpm + TypeScript project references; turbo for
+  caching"
+- `pnpm-workspace.yaml`, `turbo.json`, `tsconfig.base.json`, `biome.json`
+- `.github/workflows/ci.yml` — coverage gates and CI pipeline
+- `AGENTS.md` — code style conventions

package/docs/AWS-Adapter-Architecture.md

@@ -235,8 +235,9 @@ splitting yields clearer conditional writes and transactions.
                                     ┌──────────────┬────────────┐
                                     │ PK           │ account    │
                                     ├──────────────┼────────────┤
-                                    │ passHash     │ bytes      │
-                                    │ salt         │ bytes      │
+                                    │ algorithm    │ string     │
+                                    │ salt         │ string     │
+                                    │ hash         │ string     │
                                     └──────────────┴────────────┘
 ```
 
@@ -247,8 +248,9 @@ logic:
   nick reservation atomic across concurrent Lambdas.
 - `ChannelMembers` PK+SK composite — `TransactWriteItems` for JOIN/PART
   updates `Connections.joined` and `ChannelMembers` in one atomic write.
-- `Accounts.passHash` — never plaintext; PLAIN SASL verifies against
-  this hash server-side.
+- `Accounts` row schema — `{ account (PK), algorithm, salt, hash }`,
+  all strings. Never plaintext; PLAIN SASL verifies the scrypt hash
+  server-side.
 
 ---
 

package/docs/AWS-Deployment.md

@@ -481,6 +481,11 @@ any of them** — to enable one, add an `addEnvironment(...)` line in
 | `TOPIC_LEN`               | int     | `topicLen`            |
 | `MAX_LIST_ENTRIES`        | int     | `maxListEntries`      |
 | `QUIT_MESSAGE`            | string  | `quitMessage`         |
+| `SASL_ACCOUNTS`           | string  | `saslAccounts`        |
+
+`SASL_ACCOUNTS` is the legacy/config fallback (newline-delimited
+`username:password` pairs); it is used only when the `Accounts` table is
+empty. When the table has rows it is authoritative — see §8.1.
 
 Invalid values cause a readable boot-time error — the Lambda will
 throw on the first invocation (cold start). Test changes locally with
@@ -523,11 +528,12 @@ namespaces).
 
 ## 8. Secrets
 
-**As of v1 the Lambda consumes no secret bindings.** Server password,
-SASL `AccountStore` hashes, and oper creds are handled by later
-hardening work; when they ship, the natural homes are AWS Secrets
-Manager or SSM Parameter Store (the AWS adapter architecture doc
-calls both out as supporting services).
+**As of v1 the Lambda consumes no Secrets-Manager/SSM bindings.** Server
+password and oper creds are handled by later hardening work; when they
+ship, the natural homes are AWS Secrets Manager or SSM Parameter Store
+(the AWS adapter architecture doc calls both out as supporting
+services). SASL account credentials, however, **are** persisted — in the
+`Accounts` DynamoDB table (see §8.1).
 
 When secrets land, the typical pattern will be:
 
@@ -544,6 +550,77 @@ aws secretsmanager create-secret \
   --secret-string "$(openssl rand -base64 32)"
 ```
 
+### 8.1 SASL accounts (`Accounts` table + seed tooling)
+
+SASL PLAIN credentials live in the `Accounts` DynamoDB table as
+`HashedAccountCredential` rows — `{ account, algorithm, salt, hash }`,
+all strings, with scrypt hashes encoded as base64 (never plaintext).
+At Lambda cold start, `buildDepsFromEnv` → `resolveAccountStore`
+scans the table once and pre-loads every row into a
+`DynamoAccountStore`; the synchronous `verify()` called from the SASL
+reducer works against that in-memory snapshot. The snapshot is rebuilt
+on every cold start, so account changes take effect within one cold
+start (seconds to minutes).
+
+**Precedence** (`resolveAccountStore`, in `account-store.ts`):
+
+1. The `Accounts` table is **authoritative when it has ≥1 row** — the
+   table wins and the config seed is ignored.
+2. When the table is empty, the adapter falls back to the
+   `SASL_ACCOUNTS` env var (newline-delimited `username:password` pairs,
+   see §7.3) so existing deployments keep working without migrating.
+3. When neither source has accounts, no `AccountStore` is bound and
+   `AUTHENTICATE PLAIN` returns `904 ERR_SASLFAIL`.
+
+**Seed / CRUD tooling.** Provision accounts by writing
+`HashedAccountCredential` rows produced by `hashAccountCredential`
+(scrypt, random salt, base64-encoded). The adapter exports
+`putAccountCredential(docClient, tableName, username, password)`
+for this — a repeat call for the same `username` overwrites the row
+(the PK is `account`). A minimal seeding snippet (Node 20, from the repo
+root):
+
+```bash
+node --input-type=module -e '
+  import { createDynamoDocumentClient, putAccountCredential } from "@serverless-ircd/aws-adapter";
+  const dynamo = createDynamoDocumentClient({ region: "us-east-1" });
+  await putAccountCredential(dynamo, "StagingAccounts", "alice", "change-me");
+  console.log("seeded alice");
+'
+```
+
+A repo-local seed script (`tools/seed-aws-accounts.ts`) wraps the same
+calls for batch provisioning:
+
+```bash
+# Seed against DynamoDB Local:
+npx tsx tools/seed-aws-accounts.ts \
+  --table StagingAccounts \
+  --endpoint http://localhost:8000 \
+  --accounts alice:s3cret bob:password2
+
+# Or from a file (newline-delimited username:password):
+npx tsx tools/seed-aws-accounts.ts \
+  --table StagingAccounts \
+  --region us-east-1 \
+  --file accounts.txt
+```
+
+For a one-off `aws-cli` write, hash the password out-of-band and put the
+row directly:
+
+```bash
+# Hash with the adapter, then write the row yourself:
+aws dynamodb put-item \
+  --table-name StagingAccounts \
+  --item '{"account":{"S":"alice"},"algorithm":{"S":"scrypt"},"salt":{"S":"<base64-salt>"},"hash":{"S":"<base64-hash>"}}'
+```
+
+> The `Accounts` table is granted to all three Lambdas (`handler`,
+> `sweeper`, `pingChecker`) via `grantReadWriteData`; only the handler
+> reads it at cold start. The sweeper/ping-checker never touch SASL
+> state, but sharing the grant keeps the IAM story uniform.
+
 **Never** put credentials, password hashes, or API tokens in
 `aws-stack.ts`, in Lambda env vars, or in committed files. Lambda env
 vars are visible in the console and in CloudFormation describe output;
@@ -611,8 +688,10 @@ code):
 - `ChannelMembers` PK+SK composite — `TransactWriteItems` for JOIN/PART
   updates `Connections.joined` and `ChannelMembers` in one atomic
   write (up to 100 items per transaction, the AWS limit).
-- `Accounts.passHash` — never plaintext; SASL PLAIN verifies against
-  this hash server-side.
+- `Accounts` row schema — `{ account (PK), algorithm, salt, hash }`,
+  all strings. `algorithm` is `'scrypt'`; `salt` and `hash` are
+  base64-encoded. Never plaintext. SASL PLAIN verifies against this
+  hash server-side. Seed rows with `putAccountCredential` (see §8.1).
 
 ### 9.3 The hottest pattern: channel fanout
 

package/docs/Cloudflare-Deployment-Guide.md

@@ -31,14 +31,14 @@ namespaces that hold all IRC state:
                              ▼
    ┌─────────────────────────────────────────────────────────────┐
    │  ConnectionDO  (one per WebSocket connection)               │
-   │    • hibernatable WS via HibernatingWebSocketHandler       │
-   │    • owns ConnectionState, drives ConnectionActor          │
-   │    • DO storage persists state across hibernation          │
-   │    • alarm() drives the PING / no-PONG disconnect sweep    │
+   │    • hibernatable WS via HibernatingWebSocketHandler        │
+   │    • owns ConnectionState, drives ConnectionActor           │
+   │    • DO storage persists state across hibernation           │
+   │    • alarm() drives the PING / no-PONG disconnect sweep     │
    └────┬───────────────────────────────┬────────────────────────┘
         │ stub() RPC                    │ stub() RPC
         ▼                               ▼
-   ┌──────────────────────┐    ┌─────────────────────────────────┐
+   ┌──────────────────────┐    ┌──────────────────────────────────┐
    │  RegistryDO          │    │  ChannelDO                       │
    │  (sharded by nick)   │    │  (one per lowercased chan name)  │
    │  • nick uniqueness   │    │  • roster + modes + topic        │