serverless-ircd 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,436 @@
+# Changelog
+
+All notable changes to ServerlessIRCd are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/) with
+the 0.x convention (any release may change anything).
+
+For the release process itself — versioning policy, pre-release checklist,
+cutting a tag, rolling back — see [`docs/release.md`](docs/release.md).
+Cross-reference `progress.md` / `tickets.md` for per-ticket detail.
+
+## [0.3.0] - 2026-07-25
+
+### Added — Operator authentication (`@serverless-ircd/irc-core`)
+
+- **`OPER` command reducer**: `OPER <name> <password>` authenticates the
+  caller against the deployment's configured operator credentials
+  (`OperCred[]`) and, on success, grants the `o` user mode, replying
+  `381 RPL_YOUREOPER`. Missing parameters → `461 ERR_NEEDMOREPARAMS`;
+  no credentials configured → `491 ERR_NOOPERHOST`; wrong name/password
+  → `464 ERR_PASSWDMISMATCH`. Already an operator is an idempotent
+  no-op that re-confirms with `381`. `OPER` is the *only* path to oper
+  — user `MODE +o` is hard-rejected with `481 ERR_NOPRIVILEGES` — and
+  unlocks the `313 RPL_WHOISOPERATOR` branch of WHOIS and the `*`
+  oper flag of WHO.
+
+### Added — IRCv3 `TAGMSG` (`@serverless-ircd/irc-core`)
+
+- **`TAGMSG` reducer** (message-tags extension): carries tags only, no
+  text body. Gated behind the `message-tags` capability (clients that
+  did not negotiate it see `421 ERR_UNKNOWNCOMMAND`). Follows NOTICE
+  semantics — no numeric error replies on any rejection path — for both
+  channel and user targets, and is recorded so `draft/chathistory`
+  replay picks up `TAGMSG` lines.
+
+### Added — RFC 1459 case-mapping (`@serverless-ircd/irc-core`)
+
+- **`case-fold.ts`**: RFC 1459 case-insensitive comparison for nicks
+  and channels, advertised via `005 CASEMAPPING=rfc1459`. Replaces the
+  prior ASCII-only comparison across nick collision/registry, kick and
+  invite target lookup, and membership matching.
+
+### Added — Registration MOTD (`@serverless-ircd/irc-core`)
+
+- The registration welcome now renders the **real configured MOTD**
+  (`motd-lines.ts`), replacing the placeholder banner. The `MOTD`
+  command and the welcome flow share one rendering path.
+
+### Added — Cloudflare adapter (`@serverless-ircd/cf-adapter`)
+
+- **`ChannelRegistryDO`**: a fourth Durable Object holding the channel
+  directory (channel name → `ChannelDO` routing), alongside
+  `ConnectionDO`, `ChannelDO`, and `RegistryDO`. Wired into the Worker
+  exports, bindings, and SQLite migrations.
+- **Cloudflare config loader**: reduces Workers `vars` to the shared
+  `ServerConfigSchema`, matching the AWS (`loadServerConfigFromLambdaEnv`)
+  and local-CLI loaders.
+- `CfRuntime` completed — the previously stubbed `IrcRuntime` methods
+  (`getConnection`, `getChannelConnections`, `listChannels`, and
+  cross-connection `disconnect`) are now implemented.
+
+### Added — SASL account persistence (`@serverless-ircd/aws-adapter`)
+
+- SASL `PLAIN` accounts are now persisted in the DynamoDB `Accounts`
+  table with **scrypt** password hashes (never plaintext). The Lambda
+  cold-start path scans the table once and loads credentials into the
+  synchronous `AccountStore` port.
+- **`tools/seed-aws-accounts.ts`**: provisioning script that scrypt-hashes
+  `username:password` pairs (from CLI args or a file) and writes them
+  to the `Accounts` table. Re-running with the same username overwrites
+  the prior row.
+
+### Changed
+
+- `@serverless-ircd/in-memory-runtime`: `admitConnection` now returns a
+  stable empty `recordId` when admission is disabled, dropping the
+  per-call id minting (the id was never consulted).
+- Deploy scripts: root `pnpm deploy:aws:staging` / `deploy:aws:prod`
+  now run `pnpm build` before `cdk deploy`, so the esbuild-bundled
+  Lambda picks up fresh workspace `dist/` — matching what CI already
+  did and fixing local deploys shipping stale code.
+
+### Known limitations
+
+- SASL `EXTERNAL` (mTLS) and production TLS transport remain pending
+  (0.x work).
+- Deployed stacks remain WebSocket-only; stock TCP IRC clients still
+  reach them through the local `tcp-ws-forwarder` bridge.
+
+### Security
+
+- None. No vulnerabilities have been reported or fixed in this release.
+
+---
+
+## [0.2.0] - 2026-07-23
+
+### Added — Authentication & flood control (`@serverless-ircd/irc-core`)
+
+- **SASL `AUTHENTICATE`**: pure reducer for the IRCv3 SASL exchange.
+  `PLAIN` is fully implemented (decodes the payload, validates against
+  the injected synchronous `AccountStore` port, emits `900 RPL_LOGGEDIN`
+  + `903 RPL_SASLSUCCESS` on success, `904 ERR_SASLFAIL` on failure).
+  `EXTERNAL` is recognized but stubbed to `904` until mTLS lands; any
+  other mechanism gets `908 ERR_SASLMECHS`. Multi-frame `<=400`-byte
+  chunked payloads and `AUTHENTICATE *` abort (`906 ERR_SASLABORT`) are
+  handled. `CAP sasl` is now negotiated end-to-end (no longer
+  advertised-only).
+- **Token-bucket flood control**: `wrapFloodControl` is a pure
+  higher-order reducer wrapper enforcing a per-connection token bucket.
+  The bucket is refilled from the injected `Clock` (deterministic —
+  never `Date.now()`) and, once it crosses the configured negative
+  threshold, short-circuits with `Disconnect("Excess Flood")` without
+  invoking the inner reducer — matching hybrid/charybdis/Unreal.
+- **Per-command flood cost**: each command carries an integer cost;
+  control-plane commands (`PING`/`PONG`/`QUIT`/`CAP`/`AUTHENTICATE`)
+  are exempt so registration and keepalive can never be starved.
+
+### Added — IRCv3 chat history (`@serverless-ircd/irc-core`)
+
+- **`draft/chathistory`**: pure reducer for `CHATHISTORY <sub> <target>
+  [<args>...]`. Reads backlog from the injected `MessageStore` port and
+  replays matching `PRIVMSG`/`NOTICE`/`TAGMSG` lines wrapped in a single
+  `BATCH chathistory <target>` frame, each carrying its original
+  `@time=…` (server-time) and `msgid=…` tags. The cap must be
+  negotiated before queries are accepted. Backed by a flood-wrapped
+  routed-reducer path so chat-history reads cannot bypass the bucket.
+
+### Added — Observability & configuration (`@serverless-ircd/irc-core`)
+
+- **Structured logger port**: a `Logger` port with `traceId` /
+  `connectionId` propagation, injected through `ctx` so reducers and
+  the actor layer emit structured JSON logs without ambient state.
+- **Shared `ServerConfigSchema`**: a single Zod-style schema validating
+  `serverName`, `networkName`, `motdLines`, `serverPassword`,
+  `cloaking`, `maxConnectionsPerIp`, `maxConnectionsPerUser`, and
+  `perIpConnectionRate` with the same defaults across every adapter.
+  Each adapter ships a thin loader (`loadServerConfigFromLambdaEnv`,
+  CF `vars`, local CLI flags) that reduces to the shared schema.
+
+### Added — Security hardening (`@serverless-ircd/irc-core`, `@serverless-ircd/in-memory-runtime`, `@serverless-ircd/local-cli`)
+
+- **Server password enforcement**: when `serverPassword` is set in
+  `ServerConfig`, connections must supply it via `PASS <password>`
+  (or authenticate via SASL PLAIN) before registration completes;
+  otherwise the server replies `464 ERR_PASSWDMISMATCH` and closes
+  the link.
+- **Hostmask cloaking**: `cloakHost(realHost, config, suffix)` replaces
+  the client's visible IP with a deterministic 64-bit FNV-1a hash
+  encoded as lowercase base32, using a deployment-wide secret. Enabled
+  via `cloaking: { enabled, secret, cloakedSuffix }` in `ServerConfig`.
+- **Connection admission gate**: `AdmissionStats` + `decideAdmission`
+  enforce three independent limits at connection-accept time, each with
+  a distinct rejection reason:
+  - Per-IP simultaneous-connection cap (`maxConnectionsPerIp`, default 10).
+  - Per-user simultaneous-connection cap (`maxConnectionsPerUser`,
+    default 5; falls back to source IP when no SASL identity is present).
+  - Per-IP connection-rate limit (sliding window
+    `perIpConnectionRate`, default 5 per 60 s).
+- **512-byte input cap**: the IRC line parser rejects any line whose
+  post-CRLF-strip length exceeds `MAX_INPUT_BYTES` (512), matching
+  RFC 2812 §2.3 and the existing output-side `enforceLineLimit`.
+
+### Added — AWS adapter (`@serverless-ircd/aws-adapter`, `@serverless-ircd/aws-stack`)
+
+The second serverless substrate lands, mirroring the Cloudflare adapter
+on the same `irc-core` reducers and `IrcRuntime` port. Cloudflare and
+AWS are now both deployable.
+
+- **`AwsRuntime`**: `IrcRuntime` implementation backed by DynamoDB +
+  `ApiGatewayManagementApi`. Marshal/unmarshal helpers map irc-core
+  state shapes to/from DynamoDB rows.
+- **Lambda handlers**: `$connect` / `$disconnect` / `$default` entry
+  point dispatched on `event.requestContext.routeKey`, wired through
+  `ConnectionActor` + `dispatch` against `AwsRuntime`.
+- **Gone-connection sweeper** (`sweeperHandler`): scheduled Lambda that
+  reaps connections whose WebSocket link is dead, using atomic DynamoDB
+  membership transactions so roster/part fanout stays consistent.
+- **Idle / PING checker** (`pingCheckerHandler`): scheduled Lambda that
+  drives the PING / no-PONG disconnect sweep, the AWS analogue of the
+  Cloudflare DO `alarm()`.
+- **CDK v2 stack** (`apps/aws-stack`): API Gateway v2 WebSocket API +
+  auto-deploying `prod` stage, one Node 20 `NodejsFunction` for the
+  runtime, one for the sweeper, and one for the PING checker, five
+  DynamoDB tables (`Connections`, `ChannelMeta`, `ChannelMembers`,
+  `Nicks`, `Accounts`), and least-privilege IAM (per-table data-plane
+  grants + `execute-api:ManageConnections` scoped to the stage).
+- **Per-environment isolation**: `environmentName` prop isolates
+  stacks (`IrcAwsStack-<env>`); configurable server identity
+  (name / network / MOTD).
+- **AWS deploy workflow** (`.github/workflows/deploy-aws.yml`):
+  serialized `cdk deploy --all` to staging on every push to `main`,
+  followed by the smoke e2e (`scripts/smoke.mjs`) against the deployed
+  `ConnectUrl`. Supports static keys or OIDC web-identity role
+  assumption.
+
+### Added — Shared test harness (`@serverless-ircd/irc-test-support`)
+
+- New workspace package owning the parametrized IRC scenario suite
+  (`runIrcScenarios`, 31 Phase 2 scenarios) and the
+  `IrcHarnessFactory` / `IrcHarness` / `ClientHarness` seam each
+  adapter implements. Ships the reference `inMemoryHarnessFactory`.
+  cf-adapter and aws-adapter integration tests both consume it, so the
+  same flows run against in-memory, Cloudflare, and AWS runtimes.
+
+### Added — CI / build
+
+- **Coverage gate**: vitest per-package `thresholds` now enforce 100%
+  line/function/branch/statement on `irc-core` / `irc-server` /
+  `in-memory-runtime` and ≥90% on every other package. The gate is a
+  dedicated named CI step; a regression blocks the merge.
+- **Mutation testing**: Stryker spot-checks on `irc-core/protocol` and
+  `irc-core/commands` (≥80% mutation score gate), running as a parallel
+  CI job. Repo-level `pnpm mutation` / `mutation:protocol` /
+  `mutation:commands` scripts drive it locally.
+- **`@serverless-ircd/ci-hardening`** tool: validates the coverage-gate
+  and mutation-testing configs exist and meet the documented
+  thresholds, catching drift (a lowered threshold or dropped Stryker
+  config) before it reaches `main`.
+- **CF observability**: Worker `observability.invocation_logs` enabled
+  for runtime visibility in the Cloudflare dashboard.
+- **tcp-ws-forwarder logging**: structured logger with configurable
+  log levels.
+
+### Changed
+
+- `CAP LS` now advertises `draft/chathistory`; `sasl` is negotiated
+  end-to-end rather than advertised-only.
+- The local CLI now binds a **second RFC-style TCP listener** by default
+  (`--tcp-port`, default `<port> + 1`) alongside the WebSocket listener,
+  so stock IRC clients can dial in directly without the forwarder.
+  Pass `--no-tcp` for WebSocket-only. `--motd-file` loads the MOTD from
+  disk.
+
+### Known limitations
+
+- **No config loader for oper credentials / max clients.** Server name,
+  network, MOTD, cloaking secret, and admission limits are configurable,
+  but oper credentials and dynamic max-client limits remain hardcoded
+  defaults.
+- **No TLS / raw TCP transport in production.** The local CLI exposes a
+  TCP listener for development; deployed stacks (CF + AWS) are
+  WebSocket text frames only. `irc+tls` is 0.x work.
+- **SASL `EXTERNAL` is reserved.** It is recognized but returns `904`
+  until mTLS lands.
+- **`chathistory` storage is adapter-supplied.** The `MessageStore` port
+  is implemented per adapter; clients that query backlog against a
+  runtime with no store configured will see an empty result.
+
+## [0.1.0] - 2026-07-21
+
+First tagged release. Establishes the pure-reducer protocol core, the
+runtime port + reference implementation, a runnable local CLI server,
+and a working Cloudflare Workers adapter deployed to staging.
+
+This is a **preview release**. The AWS adapter, SASL authentication,
+flood control, server-password enforcement, and a CI coverage gate
+are not yet implemented — see **Known limitations** below. The
+Cloudflare staging deployment is functional; production deploys are
+manual per `docs/release.md` §8.3.
+
+### Added — Protocol core (`@serverless-ircd/irc-core`)
+
+- Pure reducer architecture: every command handler is
+  `(state, msg, ctx) => { state, effects }`. Side effects are values
+  (`Effect[]`), interpreted by a separate `dispatch` step.
+- Discriminated `Effect` taxonomy (`Send`, `Broadcast`, `Disconnect`,
+  `ReserveNick`, `ChangeNick`, `ReleaseNick`, `ApplyChannelDelta`,
+  `Lookup`, …) covering every side effect referenced in PLAN §2.1.
+- Determinism ports `Clock` and `IdFactory` injected into `ctx` so
+  reducers never touch real timers or randomness.
+- RFC 1459 / 2812 command set: registration (`NICK` / `USER` / `PASS`),
+  `PING` / `PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`,
+  `TOPIC`, `NAMES`, `MOTD`, `MODE` (channel + user), `KICK`, `INVITE`,
+  `WHO`, `WHOIS`, `LIST`.
+- Channel modes: `o v b i k l t n m s p`. User modes: `i`, `o` (local
+  only), `w`, `s`.
+- Welcome numeric sequence `001`–`005` with `isupport` (`005`)
+  generator emitting `NETWORK=`, `CHANLIMIT=`, `CASEMAPPING=`,
+  `SAFELIST`, and the negotiated IRCv3 caps.
+- IRCv3 `CAP` negotiation: full `LS` / `REQ` / `ACK` / `NAK` / `END` /
+  `LIST` / `NEW` / `DEL` lifecycle.
+- IRCv3 extensions: `message-tags`, `server-time`, `echo-message`,
+  `multi-prefix`, `extended-join`, `chghost`, `away-notify`,
+  `invite-notify`, `batch`, and the `safelist` capability +
+  `SAFELIST` isupport token.
+
+### Added — Orchestration (`@serverless-ircd/irc-server`)
+
+- The `IrcRuntime` port: side-effect interface (transport + state IO)
+  that every adapter implements.
+- `dispatch(effects, runtime)` interpreter that walks an `Effect[]`
+  against a bound runtime, with ordering and dedup verified.
+- `ConnectionActor`: bytes → framed messages → reducer → dispatch.
+  Drives the full registration handshake, PING/PONG cadence, and
+  command dispatch.
+
+### Added — In-memory runtime (`@serverless-ircd/in-memory-runtime`)
+
+- Single-process reference implementation of `IrcRuntime` backed by
+  in-memory Maps. Used by integration tests and the local CLI server.
+
+### Added — Local CLI server (`@serverless-ircd/local-cli`)
+
+- Runnable WebSocket IRC server on `ws://127.0.0.1:6667/` (default),
+  built on the in-memory runtime. Speaks WebSocket text frames, one
+  IRC message per frame. `SIGINT` / `SIGTERM` perform graceful
+  shutdown. Manual-test harness and e2e fixture target.
+- CLI flags: `--port`, `--host`, `-h/--help`.
+
+### Added — Cloudflare adapter (`@serverless-ircd/cf-adapter`)
+
+- `ConnectionDO`: hibernatable WebSocket handler (one DO per
+  connection). Owns `ConnectionState`, drives `ConnectionActor`,
+  persists state across hibernation, drives the PING / no-PONG
+  disconnect sweep via `alarm()`.
+- `RegistryDO`: sharded nick-uniqueness authority. Shard assignment is
+  `fnv1a32(lowercased(nick)) mod N`, default fleet size 32. DO
+  single-threadedness makes the uniqueness invariant structural.
+- `ChannelDO`: per-lowercased-channel-name DO holding roster, modes,
+  topic, and fanout via `ConnectionDO` stubs.
+- `CfRuntime`: implements the `IrcRuntime` port against the three DO
+  classes.
+
+### Added — Cloudflare Worker (`@serverless-ircd/cf-worker`)
+
+- Worker edge entry point: WebSocket upgrade → allocates
+  `connectionId = crypto.randomUUID()` → routes to `ConnectionDO`.
+  Non-upgrade requests get a human-readable 200 health string.
+- `wrangler.toml` with default (production) + `[env.staging]`
+  environments, DO bindings, `[[migrations]]` block.
+- `scripts/smoke.mjs`: replay CONNECT → NICK/USER → JOIN → PRIVMSG →
+  QUIT and assert the server emits `001`, `376`, `353`, `366`, then
+  closes. Run by CI against staging, runnable locally against
+  `wrangler dev`.
+
+### Added — TCP ↔ WebSocket forwarder (`@serverless-ircd/tcp-ws-forwarder`)
+
+- Local bridge so stock TCP IRC clients (WeeChat, HexChat, irssi) can
+  reach the WebSocket-only server. Listens on a TCP port, opens one
+  WebSocket per connection, reassembles the TCP byte stream into one
+  message per WS frame outbound, normalizes inbound frames back to
+  canonical CRLF. Transport-agnostic — ships no
+  `@serverless-ircd/*` dependency.
+
+### Added — CI / build
+
+- GitHub Actions CI (`.github/workflows/ci.yml`): lint, typecheck,
+  test with coverage on every push / pull request to `main`.
+- GitHub Actions CF deploy (`.github/workflows/deploy-cf.yml`):
+  serialized staging deploy on every push to `main`, followed by the
+  smoke e2e against the deployed URL. Failure blocks the merge.
+- Toolchain: pnpm 9 workspaces, turbo, TypeScript (strict +
+  `exactOptionalPropertyTypes`), vitest + `@vitest/coverage-v8`,
+  fast-check, Biome.
+
+### Added — Documentation
+
+- `README.md` — architecture, repository layout, toolchain, local
+  server + forwarder usage, testing strategy, roadmap, protocol scope.
+- `docs/architecture-aws.md` — AWS adapter design notes (adapter
+  itself lands in a later release).
+- `docs/deployment-cf.md` — end-to-end Cloudflare deployment guide
+  (prerequisites, account setup, local dev, staging + production
+  deploys, config reference, sharding, cost, CI/CD, troubleshooting).
+- `docs/release.md` — this release process runbook.
+
+### Changed
+
+- None (this is the first tagged release).
+
+### ⚠️ Migration required
+
+- None. No prior releases to migrate from. The DO `[[migrations]]`
+  block in `wrangler.toml` is `tag = "v1"` and will provision cleanly
+  on a fresh account.
+
+### Known limitations
+
+- **No AWS adapter.** Tickets TICKET-039 through TICKET-044 (CDK
+  stack, APIGW WebSocket handlers, DynamoDB transactions, EventBridge
+  timers, deploy pipeline, deployment doc) are pending. Cloudflare is
+  the only deployable platform in 0.1.0.
+- **No SASL.** `CAP sasl` is advertised in the capability list but
+  `AUTHENTICATE` is not wired into the dispatcher. Plain-text password
+  authentication via `PASS` is also not enforced (TICKET-046).
+- **No flood control.** A token-bucket wrapper (TICKET-028) is
+  pending. Misbehaving clients can send unbounded commands.
+- **No server-password enforcement, rate limits, cloaking, or oper
+  credentials** (TICKET-046).
+- **No config loader.** Server name, network name, MOTD, channel
+  prefixes, max clients, oper creds are hardcoded defaults
+  (TICKET-047). The `MOTD.txt` file at the repo root is informational
+  only; the live MOTD is compiled into the Worker from
+  `[vars].MOTD_LINES`.
+- **No CI coverage gate.** Coverage is computed and uploaded as an
+  artifact, but no threshold is enforced (TICKET-048). Inspect
+  `packages/*/coverage/` before deploying.
+- **No TLS / raw TCP transport.** v1 is WebSocket text frames only.
+  TLS-hardened and `irc+tls` transports are 0.x work (TICKET-052
+  through TICKET-058). Stock TCP IRC clients reach the server through
+  the local `tcp-ws-forwarder` bridge.
+- **No `chathistory` playback.** TICKET-063 is pending; clients that
+  request backlog on JOIN will see an empty batch or no response.
+
+### Security
+
+- None. No vulnerabilities have been reported or fixed in this
+  release. Report security issues per the contributing guide.
+
+---
+
+<!-- Release template — copy for the next release, fill in, move above this line.
+
+## [Unreleased]
+
+### Added
+-
+
+### Changed
+-
+
+### ⚠️ Migration required
+-
+
+### Fixed
+-
+
+### Known limitations
+-
+
+### Security
+-
+
+-->