serverless-ircd 0.3.0 → 0.4.0

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

@@ -1,86 +0,0 @@
-# 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

@@ -1,82 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-# 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