serverless-ircd 0.9.0 → 0.11.0

package/README.md

@@ -32,20 +32,60 @@ One TypeScript codebase. Two serverless substrates.
 >
 > **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/`.
+> 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. The CF deploy
+> workflow refuses placeholder hostnames (`irc.example.com` /
+> `irc.your-domain.invalid`), and a CI **env-var drift guard** keeps
+> the `consumed-env-vars` block of `apps/cf-worker/wrangler.toml`
+> exactly in sync with the config loader.
+>
+> **Abuse controls & hardening.** Layered admission control on both
+> platforms: a global `MAX_CLIENTS` cap (Cloudflare reserves a
+> `CounterDO` slot per upgrade; AWS keeps an atomic connection counter
+> — over-cap connects get `429`), per-IP simultaneous-connection caps
+> and sliding-window connect-rate limits (a `RateLimitDO` at the CF
+> edge; a source-IP GSI count + APIGW stage throttling + an opt-in
+> WAFv2 per-IP rate rule on AWS), and a per-connection inbound
+> frame-rate window at every adapter boundary. Credential handling is
+> hardened end-to-end: scrypt-hashed oper credentials, constant-time
+> server-password comparison, timing-equalized nick verification (no
+> account enumeration), SASL/OPER/IDENTIFY brute-force lockouts, and
+> credential redaction from parse-error logs. SASL `EXTERNAL` is
+> **operator opt-in** (`EXTERNAL_ENABLED`, default off), gated on a
+> bound mTLS identity source **and** a TLS transport, and binds
+> accounts to the client cert's **DER SHA-256 fingerprint**
+> (`fp:<hex>`, with a canonical-DN fallback).
 >
 > **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
+> (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.
@@ -102,12 +142,18 @@ Hexagonal / ports-and-adapters. The core implements the IRC protocol; adapters h
 **Two transports, one core.** Both adapters accept WebSocket text frames
 (the serverless default) **and** a raw `irc+tls :6697` (TLS-over-TCP)
 surface for stock IRC clients. The TCP+TLS edge is platform-specific —
-Cloudflare **Spectrum** terminates TLS and forwards plaintext TCP to a
-stateful **Container** origin (`apps/cf-tcp-container`); AWS terminates
-TLS at a **Network Load Balancer** and invokes a **Lambda streaming**
-function. Both feed the same `ConnectionActor` through a `Transport`
-seam (`WsTextFrameTransport` vs. `TcpByteStreamTransport`); the
-parser/reducer/dispatch pipeline is identical.
+Cloudflare **Spectrum** fronts a stateful **Container** origin
+(`apps/cf-tcp-container`) with `proxy_protocol = "v1"` and
+`tls_mode = "full"`: the container itself terminates TLS (pinned to
+1.2/1.3), requires and parses a PROXY v1 header on every flow to recover
+the real client IP, and runs as a non-root user. AWS terminates TLS at a
+**Network Load Balancer** — the streaming handler asserts the flow is
+TLS-secured (surfacing user mode `S`), rejects missing or malformed flow
+headers, and enforces the same per-IP connect-rate budget — and invokes a
+**Lambda streaming** function. Both feed the same `ConnectionActor`
+through a `Transport` seam (`WsTextFrameTransport` vs.
+`TcpByteStreamTransport`); the parser/reducer/dispatch pipeline is
+identical.
 
 ### Design: pure reducers + location-of-authority
 
@@ -158,9 +204,13 @@ ServerlessIRCd/
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
 │   ├── load-test/         synthetic WebSocket IRC client pool (10k conns, p50/p95/p99, drop rate)
-│   ├── ci-hardening/      coverage-gate + mutation-config validators
+│   ├── ci-hardening/      coverage-gate + mutation-config + env-var-drift validators
+│   ├── hash-oper-cred.ts  scrypt oper-credential generator (OPER_SALT + OPER_HASH)
 │   ├── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
-│   └── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
+│   ├── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
+│   └── migrate-accounts-to-services.ts  one-shot AccountStore→ServicesStore credential backfill
+├── 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
 ```
@@ -220,8 +270,8 @@ pnpm --filter web build   # builds the Kiwi SPA into apps/web/dist/webclient/ (/
 Coverage reports are written to `packages/*/coverage/`. CI (`.github/workflows/ci.yml`)
 runs lint, typecheck, the coverage gate, the parametrized contract suite, and a
 Stryker mutation spot-check on every push and pull request. Coverage thresholds
-enforce 100% on `irc-core` / `irc-server` / `in-memory-runtime` and ≥90% on every
-other package.
+enforce 100% on `irc-core` / `irc-server` / `in-memory-runtime` / `ci-hardening`
+and ≥90% on every other package.
 
 ---
 
@@ -296,14 +346,15 @@ 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 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
+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
@@ -442,12 +493,22 @@ 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`):
@@ -455,7 +516,7 @@ 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
+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)
@@ -470,8 +531,10 @@ existing `[assets]` binding serves them at `/docs/<slug>.html` (and
 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):
+### Deploying on Cloudflare
+
+Run everything locally (Worker serves SPA + landing page + WS on one
+origin):
 
 ```bash
 pnpm build                                     # workspace packages
@@ -482,18 +545,73 @@ pnpm --filter @serverless-ircd/cf-worker dev   # http://localhost:8787
 #   /health  → plaintext liveness
 ```
 
-Deploy staging (Worker + assets in one command):
+Deploy the Worker (Worker + assets in one command):
+
+```bash
+pnpm deploy:cf   # wrangler deploy
+```
+
+#### Configuration vars & secrets (Cloudflare)
+
+Every env var the Worker consumes is enumerated — and
+**drift-guarded in CI** — in the `consumed-env-vars` block of
+`apps/cf-worker/wrangler.toml`, classified as a plaintext `[vars]`
+knob or a `[secret]`. Credential material must be set as Workers
+secrets, never `[vars]`:
+
+| Secret | Purpose |
+|--------|---------|
+| `SERVER_PASSWORD` | server-wide PASS gate (see [above](#server-password-server_password---server-password)) |
+| `OPER_PASSWORD` | legacy plaintext oper credential |
+| `OPER_SALT` + `OPER_HASH` | hashed oper credential — generate with `node --import tsx tools/hash-oper-cred.ts --user admin --stdin` |
+| `SASL_ACCOUNTS` | newline-delimited `user:password` SASL seed list (see `tools/seed-cf-accounts.ts`) |
+
+Set each with `wrangler secret put <NAME>`. Everything else
+(`SERVER_NAME`, `MAX_CLIENTS`, `MAX_CONNECTIONS_PER_IP`,
+`PER_IP_CONNECTION_RATE_*`, `MAX_FRAMES_PER_WINDOW`,
+`FRAME_WINDOW_SECONDS`, `EXTERNAL_ENABLED`, …) is a non-sensitive
+`[vars]` knob.
+
+### 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:cf:staging   # wrangler deploy --env staging
+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
+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,
@@ -502,11 +620,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.
 
 ---
 
@@ -546,6 +680,73 @@ deployed stack exercises the spec path end-to-end.
 
 ---
 
+## Abuse controls & credential hardening
+
+Every transport edge enforces layered admission and rate limits, and
+every credential path verifies through hardened, timing-equalized
+comparisons. The knobs below are `[vars]` on the Cloudflare Worker and
+mirrored as Lambda env vars on AWS.
+
+### Connection admission & rate limiting
+
+| Layer                  | Knobs                                             | Enforcement |
+|------------------------|---------------------------------------------------|-------------|
+| Global cap             | `MAX_CLIENTS`                                     | CF reserves a `CounterDO` slot before each upgrade and answers `429` (`ERROR :Closing link: server full`) at the cap (slots released on close, TTL-reaped if a DO dies); AWS keeps an atomic connection counter in DynamoDB. |
+| Per-IP simultaneous    | `MAX_CONNECTIONS_PER_IP`                          | Admission gates on both platforms reject over-budget source IPs with `429`. |
+| Per-IP connect rate    | `PER_IP_CONNECTION_RATE_MAX` / `PER_IP_CONNECTION_RATE_WINDOW_MS` | CF: a `RateLimitDO` sliding window keyed on `CF-Connecting-IP`, checked at the worker edge (rejections never consume budget, so a blocked IP recovers after window decay). AWS: `$connect` counts in-window establishments via a `sourceIp+connectedSince` GSI, the NLB path applies the same budget to new flows, APIGW stage throttling backstops globally, and an opt-in WAFv2 per-IP rate rule (`-c wafConnectRateLimit=<n>`) sits at the edge. |
+| Per-connection frames  | `MAX_FRAMES_PER_WINDOW` / `FRAME_WINDOW_SECONDS`  | Inbound frame budget enforced at the adapter boundary before the actor / storage write. |
+| Line-buffer memory     | (fixed)                                           | TCP input buffers capped at 8 KiB at every transport edge (local CLI, container origin, NLB handler, forwarder). |
+
+### Protocol budgets
+
+All length limits are enforced in **UTF-8 bytes**, not UTF-16 code
+units: the 510-byte WS frame / 512-byte TCP line budgets, `TOPICLEN`
+enforced on character boundaries, `draft/multiline` batch byte budgets
+enforced incrementally as lines arrive, at most 15 tags and an
+8192-byte tag section per message, long NAMES rosters split across
+multiple `353` replies within the 510-byte budget, `CHATHISTORY`
+limits capped at a configurable ceiling (default 100), and
+`MAX_TARGETS_PER_COMMAND` capping comma-split targets. The parser
+rejects bare-`CR` smuggling and NUL/control characters in channel
+names, builds tag maps with a null prototype (blocking prototype
+pollution), and `OPER` requires a registered connection (`451
+ERR_NOTREGISTERED`).
+
+### Credentials & anti-abuse
+
+Oper credentials verify against scrypt hashes (`OPER_USER` +
+`OPER_SALT`/`OPER_HASH`, generated with `tools/hash-oper-cred.ts`);
+the server password compares in constant time; `verifyNick` runs a
+dummy scrypt verify on unknown nicks so response timings cannot
+enumerate accounts. Brute force is throttled at every auth surface: a
+per-connection SASL failure lockout, a per-IP `OPER` failure lockout,
+and a per-account NickServ `IDENTIFY` freeze. HostServ auto-approve
+honours a vhost denylist/allowlist, and ChanServ `DEOP`/`KICK` protect
+founders and enforce caller rank. Parse-error logs carry only
+token/length/reason — `PASS` / `AUTHENTICATE` payloads are redacted —
+and the Worker's log sampling defaults to 10%.
+
+### SASL EXTERNAL (mTLS)
+
+`EXTERNAL` is advertised and accepted only when **all** of the
+following hold: an mTLS identity source is bound for the connection
+(CF API Shield / AWS API Gateway client certs), the operator opt-in
+`EXTERNAL_ENABLED` is set (default **off**), and the transport is
+TLS-secured. Otherwise the `sasl` cap and `908 ERR_SASLMECHS` list
+`PLAIN` only — refusals do not count toward the SASL lockout.
+Accounts bind to the client cert's **DER SHA-256 fingerprint**
+(`fp:<hex>` entries — what Cloudflare surfaces from
+`request.cf.tlsClientAuth`; the preferred binding) or a **canonical
+subject DN** (the only identifier API Gateway exposes; DNs are
+canonicalised — types lower-cased, whitespace collapsed, RDN/AVA order
+sorted — so re-issued or differently-ordered certificates still match).
+Transports without any client-cert surface — the Spectrum container
+origin, and the NLB stream handler unless an mTLS provider is injected
+— pin the mechanism off and reject `AUTHENTICATE EXTERNAL` with a
+transport-specific `904`.
+
+---
+
 ## Testing strategy
 
 This project follows strict TDD (Red → Green → Refactor) — every reducer is
@@ -582,12 +783,17 @@ Active follow-ups:
   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%.
+- **Coverage hardening** — `irc-core`, `irc-server`,
+  `in-memory-runtime`, `local-cli`, `cf-worker`, `aws-stack`,
+  `load-test`, `cf-tcp-container`, `tcp-ws-forwarder`,
+  `irc-test-support`, and `ci-hardening` sit at 100% line coverage;
+  `cf-adapter` (~99.7%) and `aws-adapter` (~98%) clear the 90% gate
+  with follow-ups driving each to full coverage.
+- **Protocol follow-ups** — `WHOX` (`WHO <mask> %<fields>` /
+  `354 RPL_WHOSPCRPL`), `LIST` search masks + `ELIST=MNTU` filters,
+  `cap-notify` capability-change push, services data lifecycle
+  (last-used tracking + expiry sweep), and a persisted oper audit
+  trail.
 - **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
@@ -637,8 +843,9 @@ for clients with a dedicated slash-command UX. Reached via `PRIVMSG
 
 - **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.
+  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 /
@@ -658,19 +865,32 @@ for clients with a dedicated slash-command UX. Reached via `PRIVMSG
 - **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
+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.
+The credential env vars that seed and unlock these paths
+(`SASL_ACCOUNTS`, `OPER_*`, `SERVER_PASSWORD`) are Workers secrets on
+Cloudflare — the full consumed-var list lives in the drift-guarded
+`consumed-env-vars` block of `apps/cf-worker/wrangler.toml` (see
+[Configuration vars & secrets](#configuration-vars-secrets-cloudflare)).
+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`
 (pushes `ACCOUNT` on SASL login/logout), `echo-message`, `batch`,
-`sasl` (`PLAIN` always; `EXTERNAL` via mTLS when a client-cert trust store
-is bound), `multi-prefix`, `away-notify`, `chghost`, `invite-notify`,
+`sasl` (`PLAIN` always; `EXTERNAL` only under the triple gate of
+operator opt-in (`EXTERNAL_ENABLED`, default off) + a bound edge-mTLS
+identity source + a TLS connection — accounts bind to the client
+cert's DER SHA-256 fingerprint or a canonical subject DN, refusals
+answer `908 ERR_SASLMECHS` listing `PLAIN` only, and the
+`cf-tcp-container` Spectrum origin rejects `AUTHENTICATE EXTERNAL`
+with a transport-specific `904`; see
+[Abuse controls & credential hardening](#abuse-controls--credential-hardening)),
+`multi-prefix`, `away-notify`, `chghost`, `invite-notify`,
 `extended-join`, `msgid` (`@+msgid=<id>` on every PRIVMSG/NOTICE/TAGMSG,
 shared between live and `draft/chathistory` replay), `standard-replies`
 (`FAIL`/`WARN`/`NOTE` replacements for a curated numeric subset),
@@ -712,9 +932,15 @@ bridges a stock TCP client to a deployed WebSocket endpoint.
   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.
+  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

package/apps/aws-stack/README.md

@@ -21,8 +21,7 @@ The Lambda handler is currently a stub (`{ statusCode: 200 }`); the real
 
 ```sh
 pnpm cdk:synth          # synthesize the CloudFormation template (cdk.out/)
-pnpm deploy:staging     # cdk deploy --all
-pnpm deploy:prod        # cdk deploy --all --require-approval never
+pnpm deploy             # cdk deploy --all --require-approval never
 pnpm test               # synth-time assertions (no AWS, no Docker)
 pnpm typecheck
 ```
@@ -30,9 +29,8 @@ pnpm typecheck
 Repo-level shortcuts (from the monorepo root):
 
 ```sh
-pnpm deploy:aws:staging
-pnpm deploy:aws:prod
-pnpm smoke:aws:staging   # deferred (smoke harness not yet wired)
+pnpm deploy:aws
+pnpm smoke:aws          # deferred (smoke harness not yet wired)
 ```
 
 ## Optional localstack validation

package/apps/aws-stack/bin/aws.ts

@@ -5,11 +5,13 @@
  * CDK CLI's default account/region when those env vars are set; otherwise
  * the stack is environment-agnostic (suitable for `cdk synth` and localstack).
  *
- * Per-environment isolation is driven by the `environmentName` CDK context
- * variable (`-c environmentName=staging`). It defaults to `staging` so the
- * existing deploy pipeline stays green without changes, and it is folded
- * into the CloudFormation stack id (`IrcAwsStack-<environmentName>`) so
- * parallel envs coexist in one account+region.
+ * There is a single deploy target per platform (the staging/prod split was
+ * collapsed). This app synthesizes exactly one stack named `IrcAwsStack`;
+ * staging vs production isolation is driven by which AWS account and region
+ * the deploy credentials target, not by stack-name templating. Server
+ * identity (`serverName`, `networkName`, `motd`) and the optional TCP+TLS
+ * domain are read from CDK context so deploys can override them without
+ * editing source.
  */
 
 import { App } from 'aws-cdk-lib';
@@ -20,8 +22,6 @@ const app = new App();
 
 const account = process.env.CDK_DEFAULT_ACCOUNT;
 const region = process.env.CDK_DEFAULT_REGION;
-const environmentName =
-  (app.node.tryGetContext('environmentName') as string | undefined) ?? 'staging';
 
 // Server identity is read from CDK context so deploys can override it
 // without editing source (`-c serverName=…`, `-c networkName=…`,
@@ -44,13 +44,122 @@ const motdLines = Array.isArray(rawMotd)
 // docs/AWS-TCP-Deployment.md.
 const tcpTlsDomainName = app.node.tryGetContext('tcpTlsDomainName') as string | undefined;
 
+// `$connect` Origin allowlist (CSWSH defence). Opt-in: only provisioned
+// when this context var is supplied as a non-empty string. Comma-separated
+// origin list (e.g. `'https://app.example.com, https://staging.app.example.com'`).
+// When omitted, the `$connect` handler skips the Origin check entirely
+// (existing AWS deployments without a web frontend are unchanged).
+const webOrigins = app.node.tryGetContext('webOrigins') as string | undefined;
+
+// API Gateway full-frame body tracing (`DataTraceEnabled`). Safe-by-default:
+// omitted → `false` (no IRC frame bodies logged). Re-enabling requires BOTH
+// `-c allowDataTrace=true` AND `-c iUnderstandThisLeaksCredentials=true`; the
+// stack REFUSES synth with a credential-leak error if only the first is set.
+// Since the staging/prod split was collapsed every synth is effectively a
+// prod synth, so there is no quiet "non-prod" path — use ONLY in a throwaway
+// sandbox for live debugging. See docs/AWS-Deployment.md (§7.6).
+const allowDataTrace = app.node.tryGetContext('allowDataTrace') as boolean | string | undefined;
+const iUnderstandThisLeaksCredentials = app.node.tryGetContext('iUnderstandThisLeaksCredentials') as
+  | boolean
+  | string
+  | undefined;
+
+// CDK context vars arrive as strings; normalise the booleans so the stack's
+// guard sees real booleans (and `--c allowDataTrace=false` stays false-y).
+const allowDataTraceBool = parseContextBool(allowDataTrace);
+const acknowledgeLeakBool = parseContextBool(iUnderstandThisLeaksCredentials);
+
+// DynamoDB table-deletion escape hatch (state-table protection). Safe-by-
+// default: omitted → the stack keeps state tables RETAIN + deletion-protected
+// + PITR-on. `-c allowTableDeletion=true` flips state tables to DESTROY +
+// deletion-protection OFF so a deliberate `cdk destroy` teardown can delete
+// them (the data is irreversibly lost — DynamoDB tables do not snapshot on
+// delete). `Connections` is always DESTROY regardless. See §9.4 / §11.
+const allowTableDeletion = app.node.tryGetContext('allowTableDeletion') as
+  | boolean
+  | string
+  | undefined;
+const allowTableDeletionBool = parseContextBool(allowTableDeletion);
+
+// DynamoDB point-in-time recovery toggle. Defaults to ON (the stack's own
+// default when omitted); `-c enablePitr=false` disables PITR on every state
+// table (PITR is billed continuously at ~$0.20/GB-month per table; RETAIN
+// and deletionProtection are free). `Connections` never carries PITR. The
+// flag is independent of `allowTableDeletion` — a teardown keeps PITR on.
+const enablePitr = app.node.tryGetContext('enablePitr') as boolean | string | undefined;
+const enablePitrBool = parseContextBool(enablePitr);
+
+// Web client hosting (S3 + CloudFront + OAC) is opt-in. Supplying
+// `webSiteCustomDomain` provisions the static-site construct; prod passes
+// the custom domain + cert + hosted zone, staging leaves them unset to use
+// the default `*.cloudfront.net` URL. See docs/AWS-Deployment.md (web section).
+const webSiteCustomDomain = app.node.tryGetContext('webSiteCustomDomain') as string | undefined;
+const webSiteCertificateArn = app.node.tryGetContext('webSiteCertificateArn') as string | undefined;
+const webSiteHostedZoneName = app.node.tryGetContext('webSiteHostedZoneName') as string | undefined;
+const webSiteHostedZoneId = app.node.tryGetContext('webSiteHostedZoneId') as string | undefined;
+const webSite =
+  webSiteCustomDomain !== undefined
+    ? {
+        customDomain: webSiteCustomDomain,
+        ...(webSiteCertificateArn !== undefined ? { certificateArn: webSiteCertificateArn } : {}),
+        ...(webSiteHostedZoneName !== undefined ? { hostedZoneName: webSiteHostedZoneName } : {}),
+        ...(webSiteHostedZoneId !== undefined ? { hostedZoneId: webSiteHostedZoneId } : {}),
+      }
+    : undefined;
+
+// Optional WAFv2 per-IP edge rate limit on the WebSocket API's `$connect`
+// (requests per 5-minute window per client IP). Omitted → no WAF
+// resources; `-c wafConnectRateLimit=2000` provisions the WebACL with a
+// rate-based rule + the stage association. CDK context values arrive as
+// strings, so parse to an integer and drop non-numeric values.
+const rawWafConnectRateLimit = app.node.tryGetContext('wafConnectRateLimit');
+const wafConnectRateLimit =
+  typeof rawWafConnectRateLimit === 'number'
+    ? rawWafConnectRateLimit
+    : typeof rawWafConnectRateLimit === 'string' && /^\d+$/u.test(rawWafConnectRateLimit.trim())
+      ? Number.parseInt(rawWafConnectRateLimit.trim(), 10)
+      : undefined;
+
 const stackProps: IrcStackProps = {
-  environmentName,
   ...(serverName !== undefined ? { serverName } : {}),
   ...(networkName !== undefined ? { networkName } : {}),
   ...(motdLines !== undefined ? { motdLines } : {}),
   ...(tcpTlsDomainName !== undefined ? { tcpTlsDomainName } : {}),
+  ...(webOrigins !== undefined && webOrigins.length > 0 ? { webOrigins } : {}),
+  ...(webSite !== undefined ? { webSite } : {}),
+  ...(allowDataTraceBool !== undefined ? { allowDataTrace: allowDataTraceBool } : {}),
+  ...(acknowledgeLeakBool !== undefined
+    ? { iUnderstandThisLeaksCredentials: acknowledgeLeakBool }
+    : {}),
+  ...(allowTableDeletionBool !== undefined ? { allowTableDeletion: allowTableDeletionBool } : {}),
+  ...(enablePitrBool !== undefined ? { enablePitr: enablePitrBool } : {}),
+  ...(wafConnectRateLimit !== undefined ? { wafConnectRateLimit } : {}),
   ...(account && region ? { env: { account, region } } : {}),
 };
 
-new IrcAwsStack(app, `IrcAwsStack-${environmentName}`, stackProps);
+new IrcAwsStack(app, 'IrcAwsStack', stackProps);
+
+/**
+ * Normalises a CDK context value (`-c key=value`) into a boolean.
+ * CDK passes context values as strings, so `'true'` / `'false'` are
+ * parsed; anything else (including `undefined`) returns `undefined` so
+ * the downstream optional prop is simply omitted. The data-trace guard
+ * in `IrcAwsStack` is strict-equality-checked against `true`, so a stray
+ * string here would otherwise defeat the opt-in.
+ */
+function parseContextBool(value: boolean | string | undefined): boolean | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalised = value.trim().toLowerCase();
+  if (normalised === 'true') {
+    return true;
+  }
+  if (normalised === 'false') {
+    return false;
+  }
+  return undefined;
+}