serverless-ircd 0.1.0 → 0.3.0

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