serverless-ircd 0.8.0 → 0.10.0

package/README.md

@@ -6,48 +6,68 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.8.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**
-> — 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**: a vendored **Kiwi IRC** SPA 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 browser
-> opens a native `wss://` straight to the existing IRC-over-WebSocket
-> endpoint. **v0.8.0 lands integrated IRC services** — NickServ
-> (`REGISTER` / `IDENTIFY` / `DROP` / `INFO` / `SET ENFORCE` +
-> nick enforcement), ChanServ (`REGISTER` / `DROP` / `SET` /
-> `ACCESS` / `LEVELS` + the `+r` / `+R` / `+M` channel modes),
-> HostServ (`ON` / `OFF` / `REQUEST` + oper `SET` / `APPROVE`),
-> OperServ (`AKILL` / `JUPE` / `RAW`), and MemoServ
-> (`SEND` / `LIST` / `READ` / `DEL`) — 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 registration, and `draft/read-marker` gains the timestamp-based
-> `MARKREAD` verb. Remaining 0.x work: the client compatibility sweep
-> (WeeChat / HexChat / IRCCloud / TheLounge), the Playwright
-> browser-driven e2e for the SPA, 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 (via its `[assets]` binding) **or** by AWS via an
+> **S3 + CloudFront + OAC** `StaticSite` construct (opt-in via CDK
+> context). One `apps/web/dist/` artifact ships on both platforms
+> unchanged. The `docs/` wiki is rendered to standalone HTML at
+> `/docs/`. Both platforms wire **Cross-Site WebSocket Hijacking
+> (CSWSH) defense** into the WS upgrade path: the CF Worker uses
+> same-origin auto-derive by default with an optional `WEB_ORIGINS`
+> allowlist for cross-origin deploys; the AWS `$connect` Lambda uses
+> an explicit `WEB_ORIGINS` allowlist only (the SPA and the API
+> Gateway wss endpoint are on different origins, so auto-derive does
+> not apply). AWS deploys are **stack-output-driven** (a two-phase
+> `scripts/deploy-web-aws.mjs` bakes the real `ConnectUrl` into the
+> SPA config, then `s3 sync` + CloudFront invalidation).
+>
+> **Deploy security.** The AWS CI deploy is **OIDC-only** — the
+> GitHub Actions workflow assumes an IAM role via GitHub OIDC web
+> identity (no long-lived access keys, with an in-workflow assertion
+> that the assumed role matches `AWS_DEPLOY_ROLE_ARN` before any
+> `cdk deploy`). API Gateway full-frame body logging
+> (`DataTraceEnabled`) is **off by default and hard-locked**, so IRC
+> frames (`PASS`, `AUTHENTICATE <SASL-PLAIN>`, channel keys,
+> `PRIVMSG`/`NOTICE`) are never written to CloudWatch; the only way
+> back on is an explicit two-flag sandbox escape hatch.
+>
+> **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 `ServicesStore` is the
+> **single credential home**: SASL PLAIN, SASL EXTERNAL (CertFP),
+> NickServ `IDENTIFY`, and `PASS <nick>:<password>` all verify through
+> the same scrypt-hashed `verifyNick` / `verifyCertFP` surface, and
+> `draft/read-marker` / `draft/pre-away` persist through the
+> `ServicesStore`.
+>
+> See `CHANGELOG.md` for the per-release manifests.
 
 ---
 
@@ -160,6 +180,8 @@ ServerlessIRCd/
 │   ├── 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
+├── scripts/
+│   └── deploy-web-aws.mjs stack-output-driven AWS web client deploy (describe → bake → s3 sync → invalidate)
 ├── pnpm-workspace.yaml    turbo.json   tsconfig.base.json
 └── README.md              CHANGELOG.md
 ```
@@ -295,27 +317,33 @@ 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.
+credentials still go through the unified services credential store
+(`ServicesStore.verifyNick` — D1 `nickserv_accounts` / DynamoDB
+`Services`), which is unaffected.
 
 **PASS-based account login:** in addition to SASL, a client may identify
-to its NickServ account at registration 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 nick left of the `:` must match the `NICK` sent; a bare
-`PASS <value>` with no colon is always treated as a server-password
-candidate, 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`.
+to its NickServ account by sending `PASS <nick>:<password>` (the same
+`<nick>:<password>` literal the `SASL_ACCOUNTS` seed tooling uses).
+When a `ServicesStore` is configured, `NICK alice` + `PASS alice:hunter2`
++ `USER …` verifies the credentials via `services.verifyNick` 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
 
@@ -386,7 +414,7 @@ against any line-oriented WebSocket endpoint.
 
 ## Load testing (`tools/load-test`)
 
-A synthetic WebSocket IRC client pool (PLAN §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-stage **p50 / p95 / p99
 latency** (connect / register / join / message) and the **drop rate**
@@ -436,47 +464,104 @@ report).
 ## Web client (`apps/web`)
 
 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://` directly to the Worker's
-IRC-over-WebSocket endpoint — no proxy, gateway, or transport
-adaptation in the request path. See `docs/WebClientGuide.md` for the
-end-to-end contributor/operator guide.
+landing page served at `/`, both baked out of `apps/web/dist/`. The same
+artifact is served by **both** platforms:
+
+| Platform    | HTTP/SPA origin                                    | WebSocket origin                                  | Same-origin? |
+|-------------|----------------------------------------------------|---------------------------------------------------|--------------|
+| Cloudflare  | the Worker (`*.workers.dev` / custom domain)       | the same Worker                                   | **Yes** — one domain serves both |
+| AWS         | CloudFront (`*.cloudfront.net` / custom domain)    | API Gateway (`*.execute-api.*.amazonaws.com`)     | **No** — two different endpoints |
+
+On Cloudflare the Worker's `[assets]` binding serves the SPA and the WS
+upgrade on one origin — the browser opens a native `wss://` directly to
+the Worker, no proxy or gateway. On AWS the SPA is fronted by an
+**S3 + CloudFront + OAC** `StaticSite` construct
+(`apps/aws-stack/src/static-site.ts`, opt-in via CDK context) and a
+two-phase deploy bakes the real `ConnectUrl` into the SPA config (see
+"Deploying on AWS" below). See `docs/WebClientGuide.md` for the CF
+end-to-end guide and `docs/AWS-Deployment.md` §16 for the AWS path.
 
 Build the SPA + landing page (needs the submodule + `yarn`, provided by
 `corepack enable`):
 
 ```bash
 git submodule update --init apps/web/upstream   # one-time per clone
-pnpm --filter web build:staging                 # or :prod / default
+git submodule update --init docs                # one-time per clone (docs site)
+pnpm --filter web build                          # or build:prod (CF) / build:prod-aws (AWS)
 # → apps/web/dist/index.html        (landing page, served at /)
 # → 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/)
 ```
 
-Then run everything locally (Worker serves SPA + landing page + WS on
-one origin):
+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.
+
+### Deploying on Cloudflare
+
+Run everything locally (Worker serves SPA + landing page + WS on one
+origin):
 
 ```bash
 pnpm build                                     # workspace packages
 pnpm --filter @serverless-ircd/cf-worker dev   # http://localhost:8787
 #   /        → landing page
 #   /webclient/    → Kiwi SPA (opens ws://localhost:8787/)
+#   /docs/   → rendered docs/ (Home → index, per-page HTML)
 #   /health  → plaintext liveness
 ```
 
-Deploy staging (Worker + assets in one command):
+Deploy the Worker (Worker + assets in one command):
+
+```bash
+pnpm deploy:cf   # wrangler deploy
+```
+
+### Deploying on AWS
+
+The web client is **opt-in**: provision the `StaticSite` construct by
+passing `webSite*` CDK context on the stack deploy, and (once the SPA
+ships) set `webOrigins` for the CSWSH defence:
+
+```bash
+pnpm deploy:aws -- \
+  -c webSiteCustomDomain=app.example.com \
+  -c webSiteCertificateArn=arn:aws:acm:us-east-1:... \
+  -c webSiteHostedZoneName=example.com. -c webSiteHostedZoneId=... \
+  -c webOrigins=https://app.example.com
+```
+
+Then bake + ship the SPA (stack-output-driven — reads `ConnectUrl`,
+`WebsiteBucketName`, `WebsiteDistributionId` from the stack outputs,
+bakes the real wss URL into `config.json`, `s3 sync`s the build, and
+invalidates the CloudFront edge cache):
 
 ```bash
-pnpm deploy:cf:staging   # wrangler deploy --env staging
+node scripts/deploy-web-aws.mjs
 ```
 
+The ACM certificate **must** be in `us-east-1` (CloudFront requirement).
+See `docs/AWS-Deployment.md` §16 for the full two-phase flow, the
+`server` / `direct_path` config split (irc-framework prepends `wss://`
+itself, so the host is baked scheme-less), and the custom-domain setup.
+
 ### WebSocket Origin policy (CSWSH defense)
 
-WebSocket upgrades do **not** follow the same-origin policy, so the
-Worker rejects browser upgrades whose `Origin` is not allowed — see
-`apps/cf-worker/src/origin-allowlist.ts` and the SPA guide §5. Two
-modes, evaluated in order:
+WebSocket upgrades do **not** follow the same-origin policy, so a
+malicious page can open a WebSocket to the IRC server from a victim's
+browser and drive the session with their credentials (Cross-Site
+WebSocket Hijacking, CSWSH). Both adapters enforce an `Origin` policy
+on the upgrade — but the **modes differ**, because the CF Worker serves
+the SPA and the wss endpoint on the same origin while AWS serves them
+on different origins:
+
+**Cloudflare** — see `apps/cf-worker/src/origin-allowlist.ts` and the
+SPA guide §5. Two modes, evaluated in order:
 
 1. **Explicit allowlist** — set `WEB_ORIGINS` (comma-separated) for
    cross-origin deploys (SPA on a different domain than the Worker,
@@ -485,11 +570,27 @@ modes, evaluated in order:
    unset/empty, the Worker compares the browser's `Origin` against the
    request's own origin. Match → proceed; mismatch → `403 Forbidden`.
 
-`WEB_ORIGINS` is **optional** — same-origin auto-derive needs zero
-per-env config and works for `*.workers.dev`, custom domains, and
-preview URLs alike. Non-browser clients (curl, WeeChat, the
-`tcp-ws-forwarder`, scripted harnesses) never send `Origin` and pass
-through unchanged in both modes.
+`WEB_ORIGINS` is **optional** on CF — same-origin auto-derive needs
+zero per-env config and works for `*.workers.dev`, custom domains, and
+preview URLs alike.
+
+**AWS** — see `packages/aws-adapter/src/origin-allowlist.ts` and
+`docs/AWS-Deployment.md` §8.2. **Explicit allowlist only** (no
+auto-derive): the SPA is on a CloudFront origin and the wss endpoint is
+on an API Gateway origin, so the request's own host is never the SPA's
+origin. The defence is **opt-in** — unset `WEB_ORIGINS` skips the check
+entirely (existing bare-IRC deployments without a web frontend are
+unchanged on upgrade); set it to the SPA's origin(s) once the web client
+ships:
+
+```bash
+pnpm deploy:aws -- -c webOrigins=https://app.example.com
+# or as a stack prop: webOrigins: 'https://app.example.com,https://staging.app.example.com'
+```
+
+Non-browser clients (curl, WeeChat, the `tcp-ws-forwarder`, scripted
+harnesses) never send `Origin` and pass through unchanged on both
+platforms.
 
 ---
 
@@ -552,92 +653,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`.
-
-- **Foundation** (monorepo, turbo, vitest, biome, CI). ✅
-- **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**).
-- **`IrcRuntime` port** — in-memory runtime, `ConnectionActor`,
-  local CLI, parametrized contract suite. ✅ landed in **v0.1.0**.
-- **Cloudflare adapter** (ConnectionDO / ChannelDO / RegistryDO).
-  ✅ landed in **v0.1.0** (staging deploy via CI; prod deploy is manual).
-- **AWS adapter** (APIGW WS + Lambda + DynamoDB + CDK).
-  ✅ landed in **v0.2.0** (staging deploy via CI; prod deploy is manual).
-- **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**.
-- **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.
-- **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.
-- **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).
-- **Runtime & tooling baseline.** ✅ landed in **v0.4.0**
-  (Node ≥ 24 / pnpm 11).
-- **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).
-- **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.
-- **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).
-- **IRC services.** ✅ landed in **v0.8.0**: `ServicesStore` port
-  + integrated NickServ (`REGISTER`/`IDENTIFY`/`DROP`/`INFO`/`SET
-  ENFORCE` + nick enforcement), ChanServ (`REGISTER`/`DROP`/`SET`/
-  `ACCESS`/`LEVELS` + `+r`/`+R`/`+M`), HostServ
-  (`ON`/`OFF`/`REQUEST` + oper `SET`/`APPROVE`), OperServ
-  (`AKILL`/`JUPE`/`RAW`), MemoServ (`SEND`/`LIST`/`READ`/`DEL`).
-  Persistent backends ship alongside — **D1** on Cloudflare,
-  **DynamoDB** on AWS — both write-behind so registrations survive
-  redeploys. The SASL `AccountStore` and NickServ accounts are
-  **unified** under one scrypt-hashed credential store, `PASS
-  <nick>:<password>` identifies at registration, and `draft/read-marker`
-  / `draft/pre-away` now persist through the `ServicesStore` (no longer
-  in-memory-only). See `docs/Services.md`.
-- **Web client.** 🔄 partial as of **v0.7.0**: a vendored
-  Kiwi IRC SPA is served at `/webclient/` 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 +
@@ -654,9 +696,9 @@ 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.)
+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
@@ -668,24 +710,48 @@ 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** (v0.8.0): 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**. Reached via
-`PRIVMSG <Service> :<subcommand>`:
-NickServ (`REGISTER` / `IDENTIFY` / `DROP` / `INFO` / `SET ENFORCE` +
-nick enforcement on the `NICK` path), ChanServ (`REGISTER` / `DROP` /
-`SET` / `INFO` / `ACCESS` / `LEVELS` + auto-op on `JOIN`), HostServ
-(`ON` / `OFF` / `REQUEST` + oper `SET` / `APPROVE` / `LIST`, with
-`CHGHOST` fanout), OperServ (`AKILL` / `JUPE` / `UNJUPE` / `RAW`), and
-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.
+**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 / `SET PASSWORD` (self-service password
+  change; requires the current password re-supplied). `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 `ServicesStore` is the **single credential home**: SASL PLAIN, SASL
+EXTERNAL (CertFP), NickServ `IDENTIFY`, and `PASS <nick>:<password>` all
+verify through the same scrypt-hashed `verifyNick` / `verifyCertFP`
+surface, 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`
@@ -724,42 +790,29 @@ 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 `/webclient/`, 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), and **v0.8.0** (integrated
-  IRC services — NickServ / ChanServ / HostServ / OperServ / MemoServ
-  backed by a `ServicesStore` port with persistent D1 + DynamoDB
-  backends; unified SASL + NickServ scrypt-hashed account store;
-  `PASS <nick>:<password>` registration login; the `draft/read-marker`
-  `MARKREAD` verb).
+- `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, the `+r`/`+R`/`+M` modes, nick
-  enforcement, 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).
+  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 **Cloudflare** 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/AWS-Deployment.md` — end-to-end AWS deploy guide: first-time
+  setup, CDK reference, DynamoDB capacity planning, region strategy,
+  cost notes, **OIDC-only CI** (§17), **APIGW `DataTraceEnabled` hard-
+  lock** (§7.6), and the **S3 + CloudFront + OAC web client** (§16,
+  including the two-phase stack-output-driven deploy and the
+  `webOrigins` CSWSH knob).
+- `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).