serverless-ircd 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -10,6 +10,311 @@ For the release process itself — versioning policy, pre-release checklist,
 cutting a tag, rolling back — see [`docs/Release-Process.md`](docs/Release-Process.md).
 Cross-reference `progress.md` / `tickets.md` for per-ticket detail.
 
+## [0.10.0] - 2026-08-13
+
+The main change in this release is **AWS web client parity** — the
+vendored Kiwi IRC SPA is no longer Cloudflare-only. AWS now hosts it
+via an **S3 + CloudFront + OAC** `StaticSite` construct (opt-in via
+CDK context) with a **stack-output-driven two-phase deploy**, and the
+API Gateway `$connect` route gains an opt-in `WEB_ORIGINS` CSWSH
+defence that mirrors the CF Worker's. Alongside it: the SASL
+`AccountStore` is **collapsed into `ServicesStore`** as the single
+credential home (a one-shot backfill migration ships for existing
+deployments), **NickServ `SET PASSWORD`** lands as self-service
+password change, and the staging/prod deploy split is **collapsed**
+into a single target per platform. A round of **AWS deploy security
+hardening** ships: the CI workflow is **OIDC-only** (no long-lived
+access keys), and API Gateway full-frame body logging
+(`DataTraceEnabled`) is **off by default and hard-locked** so IRC
+frames are never written to CloudWatch. Finally, `UuidIdFactory` now
+sources its random bytes from `globalThis.crypto` (CSPRNG) instead of
+`Math.random`, so generated `msgid` / session ids are cryptographic-
+grade.
+
+### Added — AWS web client (`@serverless-ircd/aws-stack`, `@serverless-ircd/aws-adapter`, `@serverless-ircd/web`)
+
+The web client is no longer Cloudflare-only. AWS provisions a
+static-site origin for the SPA while the wss IRC endpoint stays on
+API Gateway — two origins, same `apps/web/dist/` artifact.
+
+- **`StaticSite` construct** (`apps/aws-stack/src/static-site.ts`): a
+  private S3 origin bucket fronted by a CloudFront distribution with
+  **Origin Access Control (OAC)** — direct S3 access is denied by the
+  bucket policy; only CloudFront URLs resolve. `defaultRootObject` is
+  `index.html` (the project landing page at `/`), and a custom error
+  response maps S3 `403`/`404` → `200 /webclient/index.html` so
+  client-side SPA routes resolve. Custom domain (ACM certificate +
+  Route53 `ARecord` alias) is opt-in via CDK context
+  (`webSiteCustomDomain` / `webSiteCertificateArn` /
+  `webSiteHostedZoneName` / `webSiteHostedZoneId`); omitted by default
+  to use `*.cloudfront.net`. Three stable CfnOutputs (`WebsiteURL`,
+  `WebsiteBucketName`, `WebsiteDistributionId`) drive the deploy
+  pipeline below.
+- **CloudFront directory-index viewer-request function**: S3 REST
+  (used with OAC) does not serve index documents, so `/docs/` or
+  `/docs` would 404 and fall through to the SPA error response
+  (serving the Kiwi shell instead of the rendered docs index). A
+  viewer-request CloudFront function now resolves directory-style
+  URIs: trailing-slash paths (`/docs/`, `/`) get `index.html`
+  appended as an internal rewrite, and extensionless paths without a
+  trailing slash (`/docs`) get a `301` redirect to the trailing-slash
+  form so the browser resolves relative asset links against the
+  directory. Real assets (`.html`, `.css`, `.js`, …) are served
+  unchanged. Mirrors the CF Worker `[assets]` binding, which resolves
+  directory indexes automatically.
+- **`$connect` Origin allowlist (CSWSH defence)**: API Gateway
+  WebSocket has no built-in `Origin` validation, so the `$connect`
+  Lambda now enforces it. `WEB_ORIGINS` (comma-separated) is parsed
+  into a normalised lowercase set at cold start; a browser-sent
+  `Origin` not in the set is denied with `403` (API Gateway closes
+  the upgrade). The defence is **opt-in** — unset `WEB_ORIGINS`
+  disables the check entirely so existing bare-IRC deployments without
+  a web frontend are unchanged on upgrade. Non-browser clients (curl,
+  WeeChat, the `tcp-ws-forwarder`, the NLB TCP+TLS path) never send
+  `Origin` and always proceed. Deliberate divergence from the CF
+  policy: **explicit-allowlist only** (no same-origin auto-derive),
+  because 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. Mirrors the CF Worker's parsing semantics (trimmed,
+  lowercased, scheme+host match).
+- **`prod-aws` build env**: a new `apps/web/static/config.prod-aws.json`
+  + `--env prod-aws` (and a `build:prod-aws` pnpm script) select the
+  AWS API-Gateway-shaped config. The `server` field carries
+  `{{API_ID}}` / `{{REGION}}` / `{{STAGE}}` placeholders the deploy
+  pipeline substitutes at bake time, so no concrete wss URL is
+  hardcoded in the repo. Because irc-framework prepends `wss://`
+  itself from `tls: true`, the baked URL is **split** into a
+  hostname-only `server` and a stage-name `direct_path` (e.g.
+  `/<stage>`) — baking the full `wss://` URL into `server` produced
+  a doubled-scheme `wss://wss//...` URL that Firefox rejects.
+- **Stack-output-driven deploy pipeline** (`scripts/deploy-web-aws.mjs`,
+  a new `@serverless-ircd/deploy-scripts` workspace package): unlike
+  the CF Worker (where `wrangler deploy` ships the SPA in the same
+  command as the runtime), the AWS SPA deploy is **two-phase** because
+  the baked `config.json` carries the API Gateway WebSocket URL as a
+  literal that does not exist at synth time. The script runs
+  `describe-stacks` → `pnpm --filter web build:prod-aws -- --api-url
+  <ConnectUrl>` → `aws s3 sync --delete` →
+  `cloudfront create-invalidation /*`. Fails loudly on missing stack
+  outputs or unsubstituted `{{...}}` placeholders. The
+  `deploy-web` CI job (`.github/workflows/deploy-aws.yml`) runs it
+  with `needs: deploy`.
+
+### Added — NickServ `SET PASSWORD` (`@serverless-ircd/irc-core`)
+
+- **Self-service password change.** `PRIVMSG NickServ :SET PASSWORD
+  <old> <new>` re-verifies the current password (defence against a
+  hijacked `+r` session), enforces a configurable minimum (default 8)
+  and a fixed maximum (256, the scrypt input budget), then re-hashes
+  and persists via `ServicesStore.setNickPassword`. The caller's
+  session stays `+r`; other sessions on the same account are not
+  kicked. Wrong old password is indistinguishable from "no such
+  account" (no enumeration vector). Wired through
+  `InMemoryServicesStore` and `PersistentServicesStore` with round-
+  trip tests on the D1 and DynamoDB backends.
+
+### Added — CSPRNG-backed ids (`@serverless-ircd/irc-core`)
+
+- **`UuidIdFactory` now uses `globalThis.crypto.getRandomValues`.** The
+  previous `Math.random`-based UUIDv4 generation was unsuitable for
+  unforgeable `msgid` / session ids — a predictable id would let a
+  client forge message attribution. The global `crypto.getRandomValues`
+  is available on Node ≥ 19 and Cloudflare Workers without an import.
+  Generated ids are now cryptographic-grade. The `IdFactory` port and
+  the deterministic `testIdFactory` test seam are unchanged, so
+  reducer determinism (reducers never touch real randomness) is
+  preserved; only the production factory changed.
+
+### Changed — Single credential home (`@serverless-ircd/irc-core`, `@serverless-ircd/cf-adapter`, `@serverless-ircd/aws-adapter`)
+
+The SASL `AccountStore` port is **removed**. `ServicesStore` is now
+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. This
+closes the cross-store credential drift flagged as a known limitation
+in v0.9.0 — a nick registered via NickServ `REGISTER` after the worker
+booted now authenticates via SASL/PASS immediately, because there is
+no second store to drift out of sync with.
+
+- **`ServicesStore` grows CertFP**: `verifyCertFP` / `addCertFP` /
+  `removeCertFP` are added to the port, and `RegisteredNick` gains a
+  `certSubjects: string[]` field so SASL EXTERNAL resolves through the
+  services store (previously SASL EXTERNAL only worked against the
+  static `InMemoryAccountStore`, never the hashed D1/DynamoDB table).
+- **D1 `cert_subjects` column auto-migrates**: the CF D1 path runs
+  `ALTER TABLE nickserv_accounts ADD COLUMN cert_subjects` inside
+  `migrateServicesSchema` on cold start (`CREATE TABLE IF NOT EXISTS`
+  + the `ALTER`), so no manual DDL is needed. DynamoDB is schemaless.
+- **Removed**: `AccountStore` port, `InMemoryAccountStore`,
+  `HashedAccountStore`, the D1/DynamoDB `account-store`
+  implementations, `SaslPayload` / `SaslResult` / `SaslAccountCredential`
+  / `constantTimeEquals` / `ingestAccountCredential`, and the
+  `accounts` / `Accounts` table reads. The new code only reads
+  `nickserv_accounts` / `Services`.
+- **`tools/migrate-accounts-to-services.ts`**: a one-shot, idempotent,
+  never-overwrite backfill of legacy `accounts` / `Accounts` rows into
+  `nickserv_accounts` / `Services`. Reads the still-deployed
+  `SASL_ACCOUNTS` env var at run time so env-seeded accounts are
+  carried into the services table. `cert_subjects` defaults to `'[]'`
+  for every migrated row (the legacy table had no cert column).
+  **Run this before the v0.10.0 build deploys** — see the migration
+  section below.
+
+### Changed — Single deploy target per platform
+
+The staging/prod deploy split is **collapsed** into one target per
+platform. Staging vs production isolation is now driven by which
+account/region (AWS) or which Worker credentials (CF) the deploy
+targets, not by stack/table/Worker name templating.
+
+- **AWS CDK**: drops the `environmentName` prop, `prefixedTableName`,
+  and the `IrcAwsStack-<env>` stack id. Tables use bare logical ids
+  (`Connections`, `Nicks`, …); the stack is always `IrcAwsStack`.
+- **Cloudflare**: drops the `env.staging` blocks in the cf-worker and
+  cf-tcp-container wrangler configs.
+- **Web build**: drops `build:staging` / `config.staging.json`; `--env`
+  now accepts only `prod` (or the default dev config) and `prod-aws`.
+- **CI**: collapses `deploy-*: staging` jobs into single `deploy` /
+  `deploy-web` jobs; script names align (`pnpm deploy:cf`,
+  `pnpm deploy:aws`, `pnpm deploy:cf:tcp`, `pnpm smoke:aws`,
+  `pnpm smoke:cf`). Deploy workflows remain `workflow_dispatch`-only
+  (no push trigger).
+
+### Added — AWS deploy security
+
+- **OIDC-only CI deploys.** The GitHub Actions deploy workflow
+  (`deploy-aws.yml`) accepts **only** GitHub OIDC web-identity
+  credentials. `aws-access-key-id` / `aws-secret-access-key` inputs
+  are dropped from every `configure-aws-credentials` step in both the
+  `deploy` and `deploy-web` jobs; the workflow requires
+  `AWS_DEPLOY_ROLE_ARN` and fails fast with `::error::` if it is
+  unset, then asserts `aws sts get-caller-identity` matches the
+  configured role before any `cdk deploy` (defence-in-depth against a
+  silent fallback to ambient static credentials). Long-lived access
+  keys powerful enough to deploy CloudFormation + IAM + Lambda +
+  DynamoDB are effectively account-admin; a single exfil vector
+  yields full account takeover. The full IAM trust policy snippet,
+  condition keys, and verification steps are in
+  `docs/AWS-Deployment.md` §17. A `ci-hardening` lint + test suite
+  (`findAwsCredentialSteps`, `readWorkflowPermissions`) locks the
+  OIDC-only contract on every PR.
+- **API Gateway `DataTraceEnabled` off by default and hard-locked.**
+  Full-frame body tracing wrote every IRC frame (`PASS <password>`,
+  `AUTHENTICATE <base64-SASL-PLAIN>`, `JOIN #chan <key>`,
+  `PRIVMSG`/`NOTICE`) to the APIGW execution-log group, leaking
+  credentials to anyone with `logs:GetLogEvents`. Now safe-by-default
+  (`false`); because the staging/prod split collapsed, there is no
+  quiet "non-prod" path to re-enable it. The only way back on is an
+  explicit **two-step opt-in** (`-c allowDataTrace=true` **and** `-c
+  iUnderstandThisLeaksCredentials=true`) that refuses synthesis unless
+  both flags are set — see `docs/AWS-Deployment.md` §7.6. Tear the
+  sandbox stack down immediately after debugging; never deploy that
+  combination to a shared account.
+
+### Changed — Documentation
+
+- **`README.md` updated** to cover AWS web client hosting (the web
+  client section was previously Cloudflare-only), the AWS `$connect`
+  CSWSH defence, the OIDC-only deploy model, the `DataTraceEnabled`
+  hard-lock, and the `scripts/deploy-web-aws.mjs` two-phase deploy.
+  The CF-vs-AWS origin difference is laid out in a table, and the
+  CSWSH section now documents both adapters' modes (same-origin
+  auto-derive on CF; explicit-allowlist-only on AWS).
+
+### ⚠️ Migration required
+
+- **Run `tools/migrate-accounts-to-services.ts` BEFORE deploying
+  v0.10.0** if the deployment has any rows in the legacy `accounts`
+  (CF D1) / `Accounts` (AWS DynamoDB) table. The v0.10.0 build only
+  reads `nickserv_accounts` / `Services`, so legacy rows that are not
+  backfilled will stop authenticating. The script is one-shot,
+  idempotent (`INSERT OR IGNORE` on D1 / conditional `PutItem` on
+  DynamoDB), and never-overwrites a nick already registered in the
+  services table. It reads the still-deployed `SASL_ACCOUNTS` env var
+  at run time so env-seeded accounts are carried through. See the
+  script header for the per-platform invocation:
+
+  ```bash
+  # Cloudflare D1
+  node --import tsx tools/migrate-accounts-to-services.ts \
+    --platform cf --database <d1-name> --remote
+
+  # AWS DynamoDB
+  node --import tsx tools/migrate-accounts-to-services.ts \
+    --platform aws --accounts-table Accounts --services-table Services \
+    --region us-east-1
+  ```
+
+- **Single deploy target: rename your deploy commands.** The
+  staging-specific commands are gone. Update any scripts, runbooks, or
+  CI that called `pnpm deploy:cf:staging` / `pnpm deploy:aws:staging`
+  / `--env staging` to the single-target form (`pnpm deploy:cf`,
+  `pnpm deploy:aws`). Staging vs production isolation is now by
+  account/region (AWS) or by Worker credentials (CF), not by command
+  suffix.
+- **AWS CI: switch to OIDC.** If the repo still has
+  `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` secrets, delete them
+  and invalidate the underlying IAM access key. Configure
+  `AWS_DEPLOY_ROLE_ARN` (a GitHub-OIDC-trusted role) per
+  `docs/AWS-Deployment.md` §17; there is no static-key fallback.
+- **No persisted-DO-state schema change.** `PERSISTED_STATE_VERSION`
+  stays `1`. The `cert_subjects` D1 column is added by an idempotent
+  `ALTER TABLE` on cold start; the D1/DynamoDB services-row shape
+  change is backward-compatible for reads. **Code rollback across
+  this release is safe** provided the account-migration backfill was
+  run (rolling back the code re-introduces the legacy `accounts`/
+  `Accounts` reads, which still work as long as the table still
+  exists — it is not auto-dropped).
+
+### Known limitations
+
+- **The web client remains partial.** The Playwright headless-browser
+  e2e against a deployed frontend is still pending; the SPA is
+  exercised via the WS smoke (`scripts/smoke.mjs`) and the `apps/web`
+  unit / build-smoke suite.
+- **The AWS web client `StaticSite` requires a custom domain to
+  provision via `bin/aws.ts`.** Provisioning the construct without a
+  custom domain (default `*.cloudfront.net` only) currently requires
+  editing `bin/aws.ts` to pass `webSite: {}` directly. Tracked as a
+  follow-up.
+- Same transport limits as v0.9.0: the **CF TCP path requires
+  Cloudflare Spectrum (Enterprise tier)** plus a stateful Container
+  origin; the **AWS TCP path** uses NLB + Lambda streaming and is
+  subject to Lambda idle-timeout / stream-duration limits. The
+  WebSocket path remains the zero-extra-deps default.
+- **mTLS (for SASL `EXTERNAL`) requires a custom domain + uploaded
+  CA/trust-store** on both platforms and is not enabled by default.
+  The `cert_subjects` plumbing lands the server-side storage; the
+  adapter-side client-cert capture at the TLS edge remains a
+  follow-up.
+- **Client compatibility sweep** (WeeChat / HexChat / IRCCloud /
+  TheLounge / matrix-IRC bridge) remains pending.
+- **Coverage hardening is partial.** `irc-core`, `irc-server`,
+  `in-memory-runtime`, and **`cf-adapter`** (new this release) sit at
+  100%; `aws-adapter` and `aws-stack` clear the 90% gate. The
+  remaining packages (`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 full coverage.
+
+### Security
+
+- **OIDC-only AWS deploys** (above): removes long-lived access keys
+  from the deploy path — the highest-impact exfil vector against an
+  AWS account with deploy permissions.
+- **APIGW `DataTraceEnabled` hard-locked off** (above): IRC frames
+  (including `PASS`, `AUTHENTICATE <SASL-PLAIN>`, channel keys) are
+  no longer written to CloudWatch even if an operator toggles the
+  console setting by hand; the two-flag escape hatch cannot be set by
+  accident.
+- **CSPRNG-backed `msgid` / session ids** (above): generated ids are
+  now cryptographic-grade, closing a forgery vector in the previous
+  `Math.random`-based `UuidIdFactory`.
+- No other auth path changed. The scrypt-hashed credential store,
+  server-password gate, and CF-side CSWSH defence are unchanged from
+  v0.9.0.
+
+---
+
 ## [0.9.0] - 2026-08-10
 
 The main change in this release is **rounding out the integrated IRC

package/README.md

@@ -32,20 +32,39 @@ 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.
 >
 > **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.
@@ -161,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
 ```
@@ -296,14 +317,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 +464,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 +487,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 +502,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 +516,52 @@ 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
+```
+
+### 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,
@@ -502,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.
 
 ---
 
@@ -637,8 +721,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,9 +743,11 @@ 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.
+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
@@ -712,9 +799,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