serverless-ircd 0.7.0 → 0.9.0

package/README.md

@@ -6,46 +6,58 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.7.0 (preview).** The pure protocol core, the
-> `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
-> the **Cloudflare Workers** adapter, and the **AWS** (API Gateway
+> **Status:** **preview.** The pure protocol core, the `IrcRuntime`
+> port + in-memory runtime, a runnable local CLI server, the
+> **Cloudflare Workers** adapter, and the **AWS** (API Gateway
 > WebSocket + Lambda + DynamoDB + CDK) adapter are all functional and
-> deployed to staging. v0.4.0 shipped **dual transport**: both adapters
-> speak a real `irc+tls :6697` (TLS-over-TCP) surface for stock IRC
-> clients — Cloudflare via Spectrum + a Container origin, AWS via a
-> Network Load Balancer + Lambda streaming — alongside the WebSocket
-> path, plus **SASL `EXTERNAL` via mTLS** and a **Cloudflare D1-backed
-> SASL account store**. v0.5.0 completed the **protocol surface**: the
-> deferred IRC verbs (`KILL`, `REHASH`, `LUSERS` + `STATS`, `TRACE`,
-> `WALLOPS`, `SETNAME`) all land, and the S2S (`CONNECT` / `SQUIT` /
-> `LINKS`) and obsolete RFC 2812 (`SERVICE` / `SUMMON` / `USERS`) verbs
-> are formally dropped. v0.6.0 landed the **IRCv3 extension sweep
-> (Phase 12)** — ten caps (`account-notify`, `msgid`,
-> `standard-replies`, `MONITOR`, `labeled-response`, `sts`,
-> `draft/typing`, `draft/multiline`, `draft/read-marker`,
-> `draft/pre-away`), the ISUPPORT tokens for the new caps, and the
-> read-only user mode `S` (TLS connected). **v0.7.0 lands the web
-> client (Phase 14)**: a vendored **Kiwi IRC** SPA served at `/app/`
-> and a static landing page at `/` directly by the Cloudflare Worker,
-> with **Cross-Site WebSocket Hijacking (CSWSH) defense** wired into
-> the WS upgrade path (same-origin auto-derive by default, optional
-> `WEB_ORIGINS` allowlist for cross-origin deploys) — the browser
-> opens a native `wss://` straight to the existing IRC-over-WebSocket
-> endpoint. Remaining 0.x work: the client compatibility sweep
-> (WeeChat / HexChat / IRCCloud / TheLounge), the Playwright
-> browser-driven e2e for the SPA, IRC services (NickServ / ChanServ /
-> HostServ / OperServ / MemoServ), and driving the remaining
-> sub-100% packages to full coverage. See `CHANGELOG.md` for the
-> per-release manifests.
+> deployed to staging.
+>
+> **Dual transport.** Both adapters speak a real `irc+tls :6697`
+> (TLS-over-TCP) surface for stock IRC clients — Cloudflare via
+> Spectrum + a Container origin, AWS via a Network Load Balancer +
+> Lambda streaming — alongside the WebSocket path, plus **SASL
+> `EXTERNAL` via mTLS** and a **Cloudflare D1-backed SASL account
+> store**.
+>
+> **Complete protocol surface.** The deferred IRC verbs (`KILL`,
+> `REHASH`, `LUSERS` + `STATS`, `TRACE`, `WALLOPS`, `SETNAME`) are
+> implemented, and the S2S (`CONNECT` / `SQUIT` / `LINKS`) and obsolete
+> RFC 2812 (`SERVICE` / `SUMMON` / `USERS`) verbs are formally dropped.
+>
+> **IRCv3 extensions.** Negotiated caps include `account-notify`,
+> `msgid`, `standard-replies`, `MONITOR`, `labeled-response`, `sts`,
+> `draft/typing`, `draft/multiline`, `draft/read-marker`, and
+> `draft/pre-away`, plus the ISUPPORT tokens for each and the
+> read-only user mode `S` (TLS connected).
+>
+> **Web client.** A vendored **Kiwi IRC** SPA is served at
+> `/webclient/` and a static landing page at `/` directly by the
+> Cloudflare Worker, with **Cross-Site WebSocket Hijacking (CSWSH)
+> defense** wired into the WS upgrade path (same-origin auto-derive by
+> default, optional `WEB_ORIGINS` allowlist for cross-origin
+> deploys). The `docs/` wiki is rendered to standalone HTML at
+> `/docs/`.
+>
+> **Integrated IRC services.** NickServ, ChanServ, HostServ,
+> OperServ, and MemoServ run inside the daemon (no separate services
+> process, no S2S link) backed by a `ServicesStore` port with
+> **persistent D1 (Cloudflare) and DynamoDB (AWS) backends**
+> (write-behind, surviving redeploys). The SASL `AccountStore` and
+> NickServ accounts are **unified** under one scrypt-hashed credential
+> store, `PASS <nick>:<password>` identifies at or after registration,
+> and `draft/read-marker` / `draft/pre-away` persist through the
+> `ServicesStore`.
+>
+> See `CHANGELOG.md` for the per-release manifests.
 
 ---
 
 ## Why
 
 IRC servers have historically been long-running stateful processes. This
-project explores what happens when the protocol brain is a set of **pure
-reducers** and the only platform-specific code is the side-effect plumbing
-(transports, registries, fanout). The payoff:
+project moves the protocol logic into a set of **pure reducers** so that
+the only platform-specific code is the side-effect layer (transports,
+registries, fanout). The consequences:
 
 - Every command handler is a trivial unit test: arrange state, apply a message,
   assert the new state and emitted effects.
@@ -57,7 +69,7 @@ reducers** and the only platform-specific code is the side-effect plumbing
 
 ## Architecture
 
-Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
+Hexagonal / ports-and-adapters. The core implements the IRC protocol; adapters handle I/O.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -97,7 +109,7 @@ function. Both feed the same `ConnectionActor` through a `Transport`
 seam (`WsTextFrameTransport` vs. `TcpByteStreamTransport`); the
 parser/reducer/dispatch pipeline is identical.
 
-### The key idea: pure reducers + location-of-authority
+### Design: pure reducers + location-of-authority
 
 Each command handler is a pure function:
 
@@ -122,6 +134,7 @@ Each reducer runs in whichever authority **owns** the state it mutates:
 | PRIVMSG/NOTICE to channel   | Channel entity          | Fanout (reads roster)        |
 | Nick collision check        | Registry entity         | Nick → Connection map        |
 | NAMES / WHO / WHOIS         | Reads snapshots         | (no mutation)                |
+| Services (`PRIVMSG NickServ`/`ChanServ`/…) | Connection entity | `ServicesStore` (account/channel/vhost/memo state) |
 
 ---
 
@@ -130,7 +143,7 @@ Each reducer runs in whichever authority **owns** the state it mutates:
 ```
 ServerlessIRCd/
 ├── packages/
-│   ├── irc-core/          pure protocol + reducers (the brain)
+│   ├── irc-core/          pure protocol + reducers
 │   ├── irc-server/        orchestration, IrcRuntime port, dispatch
 │   ├── in-memory-runtime/ reference runtime (used by tests + local CLI)
 │   ├── irc-test-support/  parametrized IRC scenario suite + harness seam
@@ -140,11 +153,11 @@ ServerlessIRCd/
 │   ├── cf-worker/         worker entry, DO migrations, bindings, [assets] + CSWSH gate
 │   ├── cf-tcp-container/  Spectrum + Container origin for irc+tls :6697
 │   ├── aws-stack/         CDK stack (APIGW WS + NLB + Lambda streaming + DynamoDB)
-│   ├── web/               vendored Kiwi IRC SPA (→ /app/) + static landing page (→ /)
+│   ├── web/               vendored Kiwi IRC SPA (→ /webclient/) + static landing page (→ /)
 │   └── local-cli/         runnable WS + TCP server using in-memory-runtime
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
-│   ├── load-test/         synthetic WebSocket IRC client farm (10k conns, p50/p95/p99, drop rate)
+│   ├── load-test/         synthetic WebSocket IRC client pool (10k conns, p50/p95/p99, drop rate)
 │   ├── ci-hardening/      coverage-gate + mutation-config validators
 │   ├── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
 │   └── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
@@ -201,7 +214,7 @@ needs the upstream sources (`git submodule update --init apps/web/upstream`)
 and `yarn` (Kiwi ships a `yarn.lock`; `corepack enable` provides it):
 
 ```bash
-pnpm --filter web build   # builds the Kiwi SPA into apps/web/dist/app/ (/app/)
+pnpm --filter web build   # builds the Kiwi SPA into apps/web/dist/webclient/ (/webclient/)
 ```
 
 Coverage reports are written to `packages/*/coverage/`. CI (`.github/workflows/ci.yml`)
@@ -223,7 +236,7 @@ that share one runtime, so a TCP client and a WS client can see each other
 
 - a **WebSocket** listener (the serverless transport) on `--port`, and
 - an **RFC-style TCP** listener on `--tcp-port` (default `<port> + 1`) so
-  real IRC clients (WeeChat, HexChat, irssi, …) can dial in directly.
+  real IRC clients (WeeChat, HexChat, irssi, …) can connect directly.
 
 First build the workspace (the CLI runs from compiled `dist/`):
 
@@ -256,11 +269,60 @@ On startup it logs a JSON line like:
 | `--motd-file <p>`  | built-in      | Read MOTD lines from this file (one per line).         |
 | `--server-name <h>`| `irc.localhost` | Server hostname advertised in `001`/`005`. Production MUST override. |
 | `--network-name <n>`| `LocalNet`   | Network name advertised in `005 NETWORK=…`.            |
+| `--server-password <p>`|           | Server-password gate. When set, every connection must supply `PASS <p>` (or SASL-identify) before `001`. Treat as a secret. |
 | `-h, --help`       |               | Show help and exit.                                    |
 
 Pass `--host 0.0.0.0` to expose the server on all interfaces. `SIGINT` /
 `SIGTERM` perform a graceful shutdown (closes active sockets, then exits).
 
+### Server password (`SERVER_PASSWORD` / `--server-password`)
+
+All three adapters (Cloudflare Worker, AWS Lambda, local CLI) support an
+optional **server-password gate**. When the knob is set, every connection
+must supply the matching `PASS <value>` before `001 RPL_WELCOME` is
+emitted; when unset or empty the gate is disabled (the default).
+
+| Adapter        | Knob                                                                          |
+|----------------|-------------------------------------------------------------------------------|
+| Cloudflare     | `wrangler secret put SERVER_PASSWORD` (Workers secret; never a `[vars]` entry). |
+| AWS            | `SERVER_PASSWORD` Lambda env var (sourced from Secrets Manager / SSM).        |
+| local CLI      | `--server-password <p>` flag, or `serverPassword` on `StartServerOptions`.    |
+
+On a mismatched/missing `PASS` the server emits `464 ERR_PASSWDMISMATCH`
+and disconnects with reason `Bad Password`. **SASL short-circuit:** a
+connection that has authenticated an account via SASL
+(`AUTHENTICATE PLAIN` / `EXTERNAL`) is exempt — the reducer's gate
+treats `state.account !== undefined` as already authorised, so a
+deployment with both `SERVER_PASSWORD` and configured SASL accounts
+does not need to hand the shared password to identified users. The
+server-wide gate is a shared deployment secret (never log it); per-user
+credentials still go through the hashed SASL account store
+(`HashedAccountStore` / D1 / DynamoDB), which is unaffected.
+
+**PASS-based account login:** in addition to SASL, a client may identify
+to its NickServ account by sending `PASS <nick>:<password>` (the same
+`<nick>:<password>` literal the `SASL_ACCOUNTS` seed tooling uses).
+When an `AccountStore` is configured, `NICK alice` + `PASS alice:hunter2`
++ `USER …` verifies the credentials against the account store and, on
+success, logs the connection in as `alice` — emitting `900 RPL_LOGGEDIN`
++ `903 RPL_SASLSUCCESS` (the same "account is set" numerics SASL uses)
+before `001 RPL_WELCOME`, stamping user mode `+r`, and running the same
+read-marker / away / memo replay as a SASL login. The login is also
+honoured when `PASS <nick>:<password>` arrives **after** registration
+has completed (e.g. a client that sent `NICK`+`USER` before `PASS`, or
+any `PASS` arriving after `CAP END` resolved): the same verify +
+`applyAccountSuccess` pipeline runs, emitting `900`/`903` and stamping
+`+r` in-band. The nick left of the `:` must match the connection's
+current nick; a bare `PASS <value>` with no colon is always treated as
+a server-password candidate (silent no-op once registration has
+completed), never as account credentials. A wrong password or unknown
+nick is indistinguishable (no `904`/`464` from the auth path) and the
+connection simply proceeds un-identified when no server password is
+set. This composes with the gate above by precedence: an
+already-identified connection (SASL or PASS-auth) satisfies the gate;
+a `<nick>:<password>` that fails verify never matches a bare shared
+secret, so a server with both configured still rejects it with `464`.
+
 ### Connecting
 
 The WebSocket listener speaks WebSocket text frames (one IRC message per
@@ -283,9 +345,9 @@ given.
 The local CLI ships a built-in TCP listener, so no bridge is needed for local
 development. Deployed stacks (Cloudflare Workers and AWS API Gateway) are
 WebSocket-only, so a stock TCP IRC client (WeeChat, HexChat, irssi, …) cannot
-dial them directly. `tools/tcp-ws-forwarder` is a local bridge for that case:
+connect to them directly. `tools/tcp-ws-forwarder` is a local bridge for that case:
 it listens on a TCP port and, for each connection, opens one WebSocket to a
-`ws://` / `wss://` target and pumps IRC lines both ways — reassembling the TCP
+`ws://` / `wss://` target and forwards IRC lines both directions — reassembling the TCP
 byte stream into one message per WS frame outbound, and normalizing inbound
 frames back to canonical CRLF.
 
@@ -330,9 +392,9 @@ against any line-oriented WebSocket endpoint.
 
 ## Load testing (`tools/load-test`)
 
-A synthetic WebSocket IRC client farm (PLAN §7, Phase 7). It opens N
+A synthetic WebSocket IRC client pool. It opens N
 connections to a `ws://` / `wss://` target, registers each (NICK/USER),
-joins a channel, and optionally chats. Per-phase **p50 / p95 / p99
+joins a channel, and optionally chats. Per-stage **p50 / p95 / p99
 latency** (connect / register / join / message) and the **drop rate**
 are captured, then printed as a markdown report to stdout (and written
 to `--report <path>` when given).
@@ -379,12 +441,12 @@ report).
 
 ## Web client (`apps/web`)
 
-A vendored **Kiwi IRC** SPA served at `/app/` and a static project
+A vendored **Kiwi IRC** SPA served at `/webclient/` and a static project
 landing page served at `/`, both baked out of `apps/web/dist/` and
 served directly by the Cloudflare Worker via its `[assets]` binding.
-The browser opens a native `wss://` straight to the Worker's existing
+The browser opens a native `wss://` directly to the Worker's
 IRC-over-WebSocket endpoint — no proxy, gateway, or transport
-adaptation in the hot path. See `docs/WebClientGuide.md` for the
+adaptation in the request path. See `docs/WebClientGuide.md` for the
 end-to-end contributor/operator guide.
 
 Build the SPA + landing page (needs the submodule + `yarn`, provided by
@@ -392,12 +454,22 @@ Build the SPA + landing page (needs the submodule + `yarn`, provided by
 
 ```bash
 git submodule update --init apps/web/upstream   # one-time per clone
+git submodule update --init docs                # one-time per clone (docs site)
 pnpm --filter web build:staging                 # or :prod / default
 # → apps/web/dist/index.html        (landing page, served at /)
-# → apps/web/dist/app/index.html    (Kiwi SPA, served at /app/)
-# → apps/web/dist/app/static/config.json  (baked, env-specific)
+# → apps/web/dist/webclient/index.html    (Kiwi SPA, served at /webclient/)
+# → apps/web/dist/webclient/static/config.json  (baked, env-specific)
+# → apps/web/dist/docs/<slug>.html      (rendered docs/, served at /docs/)
 ```
 
+The build also renders the `docs/` submodule (the Gitea wiki, 23 GFM
+markdown files) to standalone HTML under `apps/web/dist/docs/` so the
+existing `[assets]` binding serves them at `/docs/<slug>.html` (and
+`/docs/` for the index — `Home.md` becomes `index.html`). Requires the
+`docs/` submodule checkout; the build fails loudly with the recovery
+command if it is missing or empty (mirroring the Kiwi `upstream/` guard).
+`Home.md` is the docs landing page; `ADR-Index.md` lists every ADR.
+
 Then run everything locally (Worker serves SPA + landing page + WS on
 one origin):
 
@@ -405,7 +477,8 @@ one origin):
 pnpm build                                     # workspace packages
 pnpm --filter @serverless-ircd/cf-worker dev   # http://localhost:8787
 #   /        → landing page
-#   /app/    → Kiwi SPA (opens ws://localhost:8787/)
+#   /webclient/    → Kiwi SPA (opens ws://localhost:8787/)
+#   /docs/   → rendered docs/ (Home → index, per-page HTML)
 #   /health  → plaintext liveness
 ```
 
@@ -496,84 +569,33 @@ port and an `IdFactory` port are injected so tests are fully deterministic.
 
 ## Roadmap
 
-A v1 ships when `irc-core` is at 100% coverage, the parametrized contract
-suite passes against every runtime, both adapters are deployed to staging,
-and ≥3 reference clients (WeeChat, HexChat, IRCCloud, TheLounge) connect
-cleanly. Per-release manifests live in `CHANGELOG.md`.
-
-- **Phase 0** — Foundation (monorepo, turbo, vitest, biome, CI). ✅
-- **Phase 1** — Pure protocol engine: reducers, IRCv3 caps, isupport,
-  SASL (`PLAIN`), token-bucket flood control, chat history. ✅ (most in
-  **v0.1.0**; SASL/flood/chathistory landed in **v0.2.0**).
-- **Phase 2** — `IrcRuntime` port, in-memory runtime, `ConnectionActor`,
-  local CLI, parametrized contract suite. ✅ landed in **v0.1.0**.
-- **Phase 3** — Cloudflare adapter (ConnectionDO / ChannelDO / RegistryDO).
-  ✅ landed in **v0.1.0** (staging deploy via CI; prod deploy is manual).
-- **Phase 4** — AWS adapter (APIGW WS + Lambda + DynamoDB + CDK).
-  ✅ landed in **v0.2.0** (staging deploy via CI; prod deploy is manual).
-- **Phase 5** — Observability, security hardening, config, CI gates.
-  ✅ landed across v0.2.0–v0.4.0 (logger port, server-password, cloaking,
-  admission limits, coverage + mutation gates, OPER credential auth, the
-  Cloudflare config loader, and AWS max-clients admission); the
-  required-`serverName` gate closed in **v0.6.0**.
-- **Phase 6** — TLS hardening & raw TCP transport (`irc+tls :6697`).
-  ✅ landed in **v0.4.0**: generalized `ConnectionActor` transport seam,
-  Cloudflare Spectrum + Container origin, AWS NLB + Lambda streaming,
-  mTLS → SASL `EXTERNAL`, transport-parametrized contract suite, ADR-009.
-- **Phase 7 — Load testing & compatibility sweep.** 🔄 partial as of
-  **v0.6.0**: the `tools/load-test` 10k-connection harness is in-tree;
-  the formal 10k-connection report per platform and the client
-  compatibility matrix (WeeChat / HexChat / IRCCloud / TheLounge) are
-  still pending.
-- **Phase 8 — PLAN-FIXES remediation.** ✅ landed across v0.3.0–v0.4.0
-  (MessageStore wired into all three adapters, AccountStore end-to-end,
-  the DynamoDB `Accounts` table decided, CF enumeration RPCs, AWS QUIT
-  fanout, `OPER` / `TAGMSG` / `WHOWAS`, RFC 1459 case-mapping, real
-  MOTD, config-driven server identity, AWS max-clients admission,
-  CF D1 SASL store, and a sweep of dead-code / stale-comment cleanup).
-- **Phase 9 — Runtime & tooling baseline.** ✅ landed in **v0.4.0**
-  (Node ≥ 24 / pnpm 11).
-- **Phase 10 — IRCv3 WebSocket extension.** ✅ landed in **v0.4.0**:
-  `text.ircv3.net` / `binary.ircv3.net` subprotocol negotiation +
-  per-message framing across the CF Worker, AWS APIGW, local CLI, and
-  `tcp-ws-forwarder` (510-byte budget, `1009`/`1003` close codes,
-  legacy fallback).
-- **Phase 11 — Deferred IRC verbs.** ✅ landed in **v0.5.0**: `KILL`,
-  `REHASH`, `LUSERS` + `STATS`, `TRACE`, `WALLOPS`, `SETNAME`, plus
-  the formal drop of the S2S (`CONNECT`/`SQUIT`/`LINKS`) and obsolete
-  RFC 2812 (`SERVICE`/`SUMMON`/`USERS`) verbs. The protocol surface is
-  feature-complete for modern clients.
-- **Phase 12 — IRCv3 extension sweep.** ✅ landed in **v0.6.0**: ten
-  negotiated caps (`account-notify`, `msgid`, `standard-replies`,
-  `MONITOR`, `labeled-response`, `sts`, `draft/typing`,
-  `draft/multiline`, `draft/read-marker`, `draft/pre-away`), the
-  ISUPPORT tokens for the new caps (`MONITOR`/`MULTILINE`/`TYPING`/
-  `STATUSMSG`/`EXTBAN`/`ACCOUNTEXTBAN`), the read-only user mode `S`
-  (TLS connected), and the async push fanout seam (Registry hooks →
-  `MONITOR` online/offline, `BroadcastWallops`-style caps-gated
-  delivery).
-- **Phase 13 — IRC services.** ⬳ pending: `ServicesStore` port +
-  NickServ / ChanServ / HostServ / OperServ / MemoServ. Adapter
-  backends (D1 / DynamoDB) ship alongside; until then
-  `draft/read-marker` and `draft/pre-away` use in-memory reference
-  stores and do not survive an adapter restart.
-- **Phase 14 — Web client.** 🔄 partial as of **v0.7.0**: a vendored
-  Kiwi IRC SPA is served at `/app/` and a static landing page at `/`
-  by the Cloudflare Worker via an `[assets]` binding, with a Zod-
-  validated per-env config matrix and **CSWSH defense** (same-origin
-  auto-derive + optional `WEB_ORIGINS` allowlist). The Playwright
-  headless-browser e2e is the remaining open ticket.
-  See `docs/WebClientGuide.md` for the contributor/operator guide.
-- **Coverage hardening.** 🔄 partial as of **v0.7.0**: `aws-adapter`
-  and `aws-stack` clear the 90% gate (v0.6.0); the CF packages run
-  under istanbul (v0.6.0). The remaining packages (`cf-adapter`,
-  `local-cli`, `load-test`, `cf-tcp-container`, `tcp-ws-forwarder`,
-  `irc-test-support`, `web`) are **above the gate but below 100%** —
-  follow-ups drive each to 100%.
+A v1 ships when the parametrized contract suite passes against every
+runtime, the client compatibility matrix is signed off, and every
+package clears its coverage gate. Per-release manifests live in
+`CHANGELOG.md`.
+
+Active follow-ups:
+
+- **Client compatibility sweep** — formal sign-off on ≥3 reference
+  clients (WeeChat / HexChat / IRCCloud / TheLounge) against both
+  deployed adapters, on both the WebSocket and `irc+tls :6697`
+  surfaces.
+- **Web client e2e** — Playwright headless-browser e2e exercising the
+  vendored Kiwi IRC SPA against a deployed stack.
+- **Coverage hardening** — `aws-adapter` and `aws-stack` clear the 90%
+  gate; the CF packages run under istanbul. The remaining packages
+  (`cf-adapter`, `local-cli`, `load-test`, `cf-tcp-container`,
+  `tcp-ws-forwarder`, `irc-test-support`, `web`) sit above the gate
+  but below 100%; follow-ups drive each to full coverage. `irc-core`,
+  `irc-server`, and `in-memory-runtime` are at 100%.
+- **Persistent ChanServ ban list** — ban masks currently live on
+  `ChannelState.banMasks` and do not survive an empty-recreate of a
+  channel. Extending `ServicesStore` with a persistent ban list is the
+  documented next step.
 
 ---
 
-## Protocol scope (v1)
+## Protocol scope
 
 **Core (RFC 1459/2812 subset):** registration (`NICK`/`USER`/`CAP`/`PASS`),
 `PING`/`PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`, `MODE` (user +
@@ -590,14 +612,59 @@ disconnect), `REHASH` (config reload via `IrcRuntime.reloadConfig()`),
 `WALLOPS` (global broadcast to every `+w` user).
 
 (Out of scope: the S2S verbs `CONNECT`/`SQUIT`/`LINKS` and the obsolete
-RFC 2812 verbs `SERVICE`/`SUMMON`/`USERS` are **formally dropped** as of
-v0.5.0 — they return `421 ERR_UNKNOWNCOMMAND`, and their reserved
-numerics have been removed. S2S linking is a PLAN non-goal.)
-
-**Channel modes:** `o v b i k l t n m s p`.
+RFC 2812 verbs `SERVICE`/`SUMMON`/`USERS` are **formally dropped** —
+they return `421 ERR_UNKNOWNCOMMAND`, and their reserved numerics have
+been removed. S2S linking is a stated non-goal.)
+
+**Channel modes:** `o v b i k l t n m s p`, plus the
+services-derived modes `r` (registered), `R` (block unidentified
+join/message), `M` (moderated-identified) — settable only via ChanServ,
+not via `MODE`.
 **User modes:** `i`, `o` (local only), `w`, `s`, and the read-only `S`
 (TLS connected — set by the transport at registration, surfaced in WHOIS
-via `276 RPL_WHOISSECURE`, not settable via `MODE`).
+via `276 RPL_WHOISSECURE`, not settable via `MODE`) and the read-only
+`r` (registered — set by NickServ `IDENTIFY` / SASL login, surfaced as
+`+r`, not settable via `MODE`).
+
+**Integrated IRC services:** the service nicks `NickServ`, `ChanServ`,
+`HostServ`, `OperServ`, and `MemoServ` are reserved and routed to
+dedicated pure reducers when a `ServicesStore` is bound — there is **no
+separate services process and no S2S link**. Each service also accepts a
+**shortcut verb** (`/NICKSERV`, `/NS`, `/CS`, `/HS`, `/MS`, `/OS`, …)
+that the daemon rewrites to the equivalent `PRIVMSG <Service> :<args>`
+for clients with a dedicated slash-command UX. Reached via `PRIVMSG
+<Service> :<subcommand>`:
+
+- **NickServ** — `REGISTER` / `IDENTIFY` (alias: `ID`) / `DROP` / `INFO`
+  (owner + oper only for the `Email:` line) / `SET ENFORCE` + nick
+  enforcement on the `NICK` path. `INFO <nick>` with no target resolves
+  to the caller's own account.
+- **ChanServ** — `REGISTER` / `DROP` / `SET` (`FOUNDER` / `MLOCK` /
+  `RESTRICTED` / `KEEPTOPIC`) / `INFO` / `ACCESS` (`SOP` / `AOP` / `HOP`
+  / `VOP`, each `ADD` / `DEL` / `LIST`) / `LEVELS`, plus the prefix /
+  roster mutation verbs `OP`, `DEOP`, `VOICE`, `DEVOICE`, `KICK`, and
+  `BAN` / `UNBAN` (each emits the corresponding `:ChanServ MODE` /
+  `KICK` broadcast and `ApplyChannelDelta` against the channel
+  authority). Auto-op / auto-voice on `JOIN` follows the access list;
+  the first joiner of a registered channel no longer gets auto-opped
+  merely for being first.
+- **HostServ** — `ON` / `OFF` / `REQUEST` + oper `SET` / `APPROVE` /
+  `ACTIVATE` / `REJECT` / `LIST`, with `CHGHOST` fanout. An assigned
+  vhost is **auto-applied on identify** (SASL, NickServ `IDENTIFY`, or
+  PASS-auth): `state.host` is set, `state.vhostActive` is stamped, and
+  any currently-joined `chghost`-capable peers see the broadcast.
+  Oper-only subcommands are hidden from non-opers in the help NOTICE.
+- **OperServ** — `AKILL` / `JUPE` / `UNJUPE` / `RAW` (oper-only).
+- **MemoServ** — `SEND` / `LIST` / `READ` / `DEL` with queue delivery
+  at identify.
+
+The SASL `AccountStore` and NickServ accounts share one scrypt-hashed
+credential store, so a registered nick is also a SASL login and vice
+versa. Backends: D1 on Cloudflare, DynamoDB on AWS, in-memory for the
+local CLI / tests (all write-behind; registrations survive redeploys).
+When no store is bound, services commands reply `501` and the rest of
+the daemon is unaffected. See `docs/Services.md` for the full
+reference.
 
 **IRCv3 extensions (negotiated via `CAP`):** `message-tags` (incl. the
 `TAGMSG` command), `server-time`, `account-tag`, `account-notify`
@@ -614,7 +681,9 @@ shared between live and `draft/chathistory` replay), `standard-replies`
 so compliant clients upgrade from plaintext to TLS and pin the secure
 listener), `draft/chathistory`, `safelist`, `draft/typing` (typing-indicator
 broadcast), `draft/multiline=<n>` (multi-line `BATCH`, default 4096-byte
-budget), `draft/read-marker` (per-account persisted last-read), and
+budget), `draft/read-marker` (per-account persisted last-read, with the
+timestamp-based `MARKREAD <target> [timestamp]` verb plus the
+`+draft/read-marker` tag fanout), and
 `draft/pre-away` (per-account persisted away reason, replayed at
 identify). Case-insensitive nick/channel comparison uses **RFC 1459**
 case-mapping (advertised via `005 CASEMAPPING=rfc1459`). The new
@@ -634,32 +703,23 @@ bridges a stock TCP client to a deployed WebSocket endpoint.
 
 ## Further reading
 
-- `CHANGELOG.md` — per-release manifests (Keep a Changelog format), including
-  the v0.2.0 work (AWS adapter, SASL, flood control, security hardening, CI
-  gates), v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
-  ChannelRegistryDO, SASL account persistence), v0.4.0 (dual transport
-  `irc+tls :6697`, SASL `EXTERNAL`/mTLS, WHOWAS + remaining verbs, D1 account
-  store, Node 24/pnpm 11), v0.5.0 (deferred IRC verbs `KILL` / `REHASH`
-  / `LUSERS` + `STATS` / `TRACE` / `WALLOPS` / `SETNAME`, plus the formal
-  drop of the S2S and obsolete RFC 2812 verbs), v0.6.0 (the IRCv3
-  extension sweep — `account-notify`, `msgid`, `standard-replies`,
-  `MONITOR`, `labeled-response`, `sts`, `draft/typing`, `draft/multiline`,
-  `draft/read-marker`, `draft/pre-away`, plus user mode `S`; the
-  required-`serverName` gate; `tools/load-test`; aws-adapter / aws-stack
-  coverage unblocks; CF packages moved to istanbul; deploys now
-  manual-only), and **v0.7.0** (the web client — vendored Kiwi IRC SPA
-  at `/app/`, static landing page at `/`, Cloudflare Worker `[assets]`
-  binding, per-env Zod-validated config matrix, and CSWSH defense via
-  same-origin auto-derive + optional `WEB_ORIGINS`; `/health` becomes
-  an explicit route; mutation-killing tests for `irc-core`'s parser /
-  batch / numerics).
-- `docs/WebClientGuide.md` — end-to-end contributor/operator doc for the
-  web client: build pipeline, per-env config matrix, CSWSH rationale and
-  the optional `WEB_ORIGINS` var, local dev, optional Cloudflare Pages
-  alternative, and troubleshooting.
-- `docs/Cloudflare-TCP-Deployment.md` and `docs/AWS-TCP-Deployment.md` —
-  end-to-end guides for the `:6697` TCP+TLS variants (Spectrum/Container on
-  CF, NLB + Lambda streaming on AWS), including mTLS trust-store setup.
-- `README.md` in each `packages/*` and `apps/*` — per-package notes (e.g.
-  `packages/aws-adapter/README.md` for the DynamoDB-Local test setup,
-  `apps/aws-stack/README.md` for CDK commands and localstack validation).
+- `CHANGELOG.md` — per-release manifests in Keep a Changelog format.
+- `docs/Services.md` — operator and contributor reference for the
+  integrated IRC services: architecture (integrated vs. pseudo-client),
+  the per-service command tables (including ChanServ `OP`/`DEOP`/
+  `VOICE`/`DEVOICE`/`KICK`/`BAN`/`UNBAN`, HostServ oper approval flow,
+  the `+r`/`+R`/`+M` modes, nick enforcement, the unified scrypt
+  account store, service shortcut verbs), adapter backends, and an
+  end-to-end registration walkthrough.
+- `docs/WebClientGuide.md` — end-to-end contributor/operator doc for
+  the web client: build pipeline, per-env config matrix, CSWSH
+  rationale and the optional `WEB_ORIGINS` var, local dev, optional
+  Cloudflare Pages alternative, and troubleshooting.
+- `docs/Cloudflare-TCP-Deployment.md` and `docs/AWS-TCP-Deployment.md`
+  — end-to-end guides for the `:6697` TCP+TLS variants
+  (Spectrum/Container on CF, NLB + Lambda streaming on AWS), including
+  mTLS trust-store setup.
+- `README.md` in each `packages/*` and `apps/*` — per-package notes
+  (e.g. `packages/aws-adapter/README.md` for the DynamoDB-Local test
+  setup, `apps/aws-stack/README.md` for CDK commands and localstack
+  validation).

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": true,
   "description": "AWS CDK v2 stack: API Gateway v2 WebSocket API, Lambda, DynamoDB tables, least-privilege IAM",
   "license": "BSD-3-Clause",