serverless-ircd 0.6.0 → 0.7.0

package/.github/workflows/ci.yml

@@ -151,7 +151,12 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build workspace (irc-core mutation targets)
-        run: pnpm build
+        # Scope the build to irc-core and its workspace deps only. The
+        # mutation spot-check mutates irc-core/protocol and irc-core/commands,
+        # so building the rest of the workspace (notably @serverless-ircd/web,
+        # which spawns `yarn` to build the Kiwi upstream SPA) is unnecessary
+        # and fails on runner images that don't ship yarn.
+        run: pnpm turbo run build --filter=@serverless-ircd/irc-core...
 
       - name: Stryker spot-check on irc-core/protocol
         # Mutation score threshold >=80% is enforced by the

package/.gitmodules

@@ -1,3 +1,6 @@
 [submodule "docs"]
 	path = docs
 	url = https://gitea.com/fowlmouth/ServerlessIRCd.wiki.git
+[submodule "apps/web/upstream"]
+	path = apps/web/upstream
+	url = https://github.com/kiwiirc/kiwiirc.git

package/CHANGELOG.md

@@ -10,6 +10,220 @@ For the release process itself — versioning policy, pre-release checklist,
 cutting a tag, rolling back — see [`docs/release.md`](docs/release.md).
 Cross-reference `progress.md` / `tickets.md` for per-ticket detail.
 
+## [0.7.0] - 2026-08-04
+
+The headline is the **web client (Phase 14)**: a vendored **Kiwi IRC**
+SPA served at `/app/` and a static project landing page served at `/`
+directly by the Cloudflare Worker, with **Cross-Site WebSocket
+Hijacking (CSWSH) defense** wired into the WS upgrade path. The browser
+opens a native `wss://` straight to the existing IRC-over-WebSocket
+endpoint — no proxy, gateway, or transport adaptation in the hot path.
+Alongside it: a round of **test hardening** (mutation-killing tests for
+`irc-core`'s parser / batch / numerics, and CF-harness / scenario fixes
+for slow transports).
+
+### Added — Web client (`@serverless-ircd/web`, `@serverless-ircd/cf-worker`)
+
+Six Phase 14 tickets light up the project's browser surface. The Worker
+becomes the single origin for the landing page, the SPA, **and** the
+WebSocket. Same-origin by default — which is what makes the CSWSH
+defense almost zero-config.
+
+- **`apps/web` workspace package (`@serverless-ircd/web`)**: a new
+  pnpm workspace package owning the Kiwi build orchestration and config
+  schema. The package layout reserves `dist/app/` for the Kiwi SPA
+  (served at `/app/`) and `dist/index.html` for the landing page
+  (served at `/`). No `@serverless-ircd/*` runtime dependency —
+  Kiwi talks to the Worker over plain WebSocket.
+- **Kiwi IRC vendored as a git submodule** (`apps/web/upstream/`,
+  tag-pinned): `scripts/build.mjs` patches the upstream `publicPath`
+  to `/app/`, runs `yarn build` inside the submodule, copies
+  `upstream/dist/` → `apps/web/dist/app/`, then layers our validated
+  `static/config.json` over the upstream default. The patch runs in
+  `finally` so the submodule stays clean; every hashed asset URL comes
+  out `/app/static/...` instead of root-relative. `.gitmodules` updated;
+  `biome.json` ignores `apps/web/upstream/**`. `git submodule update
+  --init` is now part of the contributor quickstart.
+- **Per-env config matrix + Zod schema** (`apps/web/src/config-schema.ts`,
+  `apps/web/src/build-env.ts`): `static/config.json`,
+  `static/config.staging.json`, `static/config.prod.json` are validated
+  against a Zod schema **before** being baked into
+  `dist/app/static/config.json`. `pnpm --filter web build` accepts a
+  `--env <staging|prod>` flag (unit-tested in isolation from the slow
+  Kiwi build). A malformed config (missing `server`, out-of-range
+  `port`, non-`#` channel, `direct: false`, …) aborts the build with
+  an aggregated, field-listing error rather than shipping a broken SPA.
+  The Kiwi `startupOptions.server` uses the `{{hostname}}` template
+  (resolved by the browser to `window.location.hostname` at load time),
+  so **one build artifact targets staging, prod, and preview deploys
+  without a per-env hostname**.
+- **Cloudflare Worker `[assets]` binding** (`apps/cf-worker/wrangler.toml`,
+  `apps/cf-worker/src/worker.ts`): the non-WS, non-`/health` branch of
+  the worker's `fetch` falls through to `env.ASSETS`, which serves
+  `apps/web/dist`. Per-env (`[env.staging.assets]`) blocks ship so
+  `wrangler deploy --env staging` deploys the Worker and the SPA in
+  one command. `run_worker_first = true` is set so WS upgrades aren't
+  intercepted by the asset platform serving `dist/index.html` at `/`
+  with a `200 OK` (the WS endpoint and the landing page share path
+  `/`; only the Worker can tell them apart).
+- **Static landing page** (`apps/web/landing/index.html`): framework-
+  free HTML + inline CSS, no JavaScript. The project's front door —
+  explains what ServerlessIRCd is, links to `/app/` (the IRC client),
+  the docs, and the source repo. The build copies it verbatim to
+  `dist/index.html`. Renders without JS; responsive; the build-smoke
+  suite asserts the `/app/` link, the docs link, and the viewport meta
+  tag so they cannot regress.
+- **`/health` is an explicit route**: the previous catch-all plaintext
+  liveness string now lives at `GET /health` so `/` is free for the
+  landing page. WS upgrades still route to `ConnectionDO`.
+
+### Added — CSWSH defense (`@serverless-ircd/cf-worker`)
+
+WebSocket upgrades do **not** follow the same-origin policy. A
+malicious page can `new WebSocket('wss://irc.example.com/')` from the
+victim's browser and drive an IRC session with the victim's
+credentials. The Worker now rejects upgrades whose `Origin` is not
+allowed — see `apps/cf-worker/src/origin-allowlist.ts` and
+`docs/WebClientGuide.md` §5.
+
+- **Two enforcement modes, evaluated in order:**
+  1. **Explicit allowlist** — when the `WEB_ORIGINS` var is set, only
+     listed origins proceed. Use this for cross-origin deployments
+     (SPA on a different domain than the Worker, e.g. Cloudflare
+     Pages).
+  2. **Auto-derive (same-origin)** — when `WEB_ORIGINS` is unset/empty
+     (the default), the Worker compares the browser's `Origin` against
+     the request's own origin (`${protocol}//${host}`). If they match,
+     the page opening the WS is the same origin as the server → safe.
+- **`WEB_ORIGINS` is optional.** Because mode 2 is the default and
+  requires zero per-env configuration, most deployments never need to
+  set it: the SPA and the Worker are on the same origin. It works for
+  `*.workers.dev`, custom domains, and preview URLs alike.
+- **Non-browser clients pass through unchanged.** curl, WeeChat, the
+  `tcp-ws-forwarder`, and scripted test harnesses never send `Origin`;
+  their upgrades are allowed in both modes so existing tooling keeps
+  working.
+- **No fail-open path.** A browser-sent `Origin` that is not allowed
+  → `403 Forbidden`. The extreme edge case (no allowlist AND
+  `Host` undeterminable, which never fires on Cloudflare) is
+  fail-closed `403`. The pure policy is exhaustively unit-tested in
+  `apps/cf-worker/tests/origin-allowlist.test.ts`; the worker
+  integration is covered by `tests/ws-origin.test.ts`.
+
+### Added — Documentation (`docs/WebClientGuide.md`)
+
+End-to-end contributor/operator doc covering: how the SPA, landing
+page, and WS endpoint fit on one origin; prerequisites (incl. `yarn`
+for the Kiwi build only); the quickstart (`git submodule update --init`
+→ `pnpm --filter web build:staging` → `pnpm deploy:cf:staging`); a
+walkthrough of the build pipeline and the per-env config matrix; the
+CSWSH rationale and the optional `WEB_ORIGINS` var; local dev
+(`wrangler dev` serves everything on `http://localhost:8787`); an
+optional Cloudflare Pages alternative for cross-origin prod deploys;
+the optional `webircgateway` SockJS fallback (strictly opt-in, not
+needed for normal operation); landing-page customisation; and a
+troubleshooting section. The acceptance criterion is that a new
+contributor can deploy a staging SPA following only this doc.
+
+### Added — Test hardening (`@serverless-ircd/irc-core`, `@serverless-ircd/cf-adapter`, `@serverless-ircd/irc-test-support`)
+
+- **Mutation-killing tests for `irc-core`**: the parser, batch, and
+  numerics suites were expanded to kill surviving Stryker mutants —
+  command-token anchors, strict source-prefix shape, malformed-input
+  diagnostic text, middle-param whitespace collapsing,
+  `unescapeTagValue` boundary conditions; empty-batch framing metadata
+  surviving elision; and `numericToName` round-trip parity against the
+  registry. A generated Stryker mutation report is committed under
+  `packages/irc-core/reports/mutation/`.
+- **CF harness / scenario fixes for slow transports**: the CF test
+  harness now waits for the end of the registration burst (`376` /
+  `422`) instead of `001`, so late MOTD frames do not pollute
+  `received` after a test clears it. The NOTICE scenario now only
+  rejects NOTICE-relevant error numerics (rather than any numeric),
+  preventing delayed welcome / MOTD lines from false-positiving the
+  RFC no-error-replies check. No production code changed.
+
+### Changed
+
+- **Cloudflare Worker routing.** `/health` is the new liveness route;
+  the root `/` now serves the landing page from the `[assets]`
+  binding. WS upgrades still route to `ConnectionDO`. Operators who
+  scraped the root `/` for the plaintext health string must update
+  to `/health`.
+
+### ⚠️ Migration required
+
+- **New optional runtime var: `WEB_ORIGINS`.** Optional — same-origin
+  auto-derive is the default. Set it only for cross-origin SPA
+  deployments (SPA on Cloudflare Pages, Worker serving the WS only,
+  etc.):
+  ```toml
+  # apps/cf-worker/wrangler.toml
+  [vars]
+  WEB_ORIGINS = "https://irc.example.com,https://web.example.com"
+  ```
+- **New build prerequisite for the SPA.** Building `apps/web` needs
+  the Kiwi submodule (`git submodule update --init apps/web/upstream`)
+  and `yarn` (provided by `corepack enable`). The CF deploy workflow
+  runs `pnpm build` (which builds the SPA + landing page) before
+  `wrangler deploy`. If you deploy manually and skip the SPA build,
+  the Worker still works but `/app/` and `/` return 404 from the asset
+  layer.
+- **`/health` is the new liveness route.** Operators who scraped `/`
+  for the plaintext health string must update to `/health`.
+- **New workspace package.** `apps/web` is a new private package
+  (`@serverless-ircd/web`); `pnpm install` picks it up automatically
+  from the existing `pnpm-workspace.yaml` glob.
+- **No persisted-state schema change.** `PERSISTED_STATE_VERSION`
+  stays `1`. **Code rollback across this release is safe** — the
+  web-client work adds the `[assets]` binding and the `/health` route
+  but touches no Durable Object state.
+- No toolchain change. Node ≥ 24 / pnpm 11 (from v0.4.0) still apply.
+
+### Known limitations
+
+- **Phase 14 is partial.** The Playwright headless-browser e2e
+  against the deployed staging frontend remains pending
+  — the SPA is exercised via the existing WS smoke
+  (`scripts/smoke.mjs`) and the new `apps/web` unit / build-smoke
+  suite, but no browser-driven end-to-end test runs in CI yet.
+- **The web client is Cloudflare-only.** The `[assets]` binding is a
+  Cloudflare Worker feature; AWS deployments continue to require an
+  external static host for the SPA (and must add the SPA's origin to
+  the Worker-style `WEB_ORIGINS` equivalent if/when an AWS-side
+  CSWSH check lands).
+- Same transport limits as v0.6.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.
+- **Client compatibility sweep** (WeeChat / HexChat / IRCCloud /
+  TheLounge / matrix-IRC bridge) remains pending.
+- **Coverage hardening is partial.** `aws-adapter` and `aws-stack`
+  clear the 90% gate (v0.6.0); the remaining packages
+  (`cf-adapter`, `local-cli`, `load-test`, `cf-tcp-container`,
+  `tcp-ws-forwarder`, `irc-test-support`, and now `web`) are **above
+  the gate but below 100%** — follow-ups drive each to 100%.
+- The IRC services Phase 13 work (NickServ / ChanServ / HostServ /
+  OperServ / MemoServ) is pending; `draft/read-marker` and
+  `draft/pre-away` ship with in-memory reference stores, so marker /
+  away persistence does not survive an adapter restart until a
+  services backend lands.
+
+### Security
+
+- **CSWSH defense added.** WebSocket upgrades from browsers now
+  require an allowed `Origin`. Same-origin auto-derive is the default
+  (zero config); explicit `WEB_ORIGINS` allowlist for cross-origin
+  setups. Non-browser clients (no `Origin`) pass through unchanged.
+  There is no fail-open path. See `docs/WebClientGuide.md` §5. No
+  other auth path changed (SASL `PLAIN` / `EXTERNAL`, oper gate,
+  admission limits, and cloaking are unchanged from v0.6.0).
+
+---
+
 ## [0.6.0] - 2026-08-03
 
 The headline is the **IRCv3 extension sweep (Phase 12)**: ten negotiated

package/README.md

@@ -6,7 +6,7 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.6.0 (preview).** The pure protocol core, the
+> **Status:** **v0.7.0 (preview).** The pure protocol core, the
 > `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
 > the **Cloudflare Workers** adapter, and the **AWS** (API Gateway
 > WebSocket + Lambda + DynamoDB + CDK) adapter are all functional and
@@ -19,21 +19,24 @@ One TypeScript codebase. Two serverless substrates.
 > 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 lands the IRCv3 extension sweep
+> are formally dropped. v0.6.0 landed the **IRCv3 extension sweep
 > (Phase 12)** — ten caps (`account-notify`, `msgid`,
 > `standard-replies`, `MONITOR`, `labeled-response`, `sts`,
 > `draft/typing`, `draft/multiline`, `draft/read-marker`,
 > `draft/pre-away`), the ISUPPORT tokens for the new caps, and the
-> read-only user mode `S` (TLS connected) — closes the
-> required-`serverName` config gate, ships a `tools/load-test`
-> 10k-connection harness, and lifts `aws-adapter` / `aws-stack` over
-> the 90% coverage gate (CF packages moved to istanbul coverage,
-> clearing the v0.5.0 workerd-incompatibility caveat). Remaining 0.x
-> work: the client compatibility sweep (WeeChat / HexChat / IRCCloud /
-> TheLounge), IRC services (NickServ / ChanServ / HostServ /
-> OperServ / MemoServ), a web client (vendored Kiwi IRC), and driving
-> the remaining sub-100% packages to full coverage. See
-> `CHANGELOG.md` for the per-release manifests.
+> read-only user mode `S` (TLS connected). **v0.7.0 lands the web
+> client (Phase 14)**: a vendored **Kiwi IRC** SPA served at `/app/`
+> and a static landing page at `/` directly by the Cloudflare Worker,
+> with **Cross-Site WebSocket Hijacking (CSWSH) defense** wired into
+> the WS upgrade path (same-origin auto-derive by default, optional
+> `WEB_ORIGINS` allowlist for cross-origin deploys) — the browser
+> opens a native `wss://` straight to the existing IRC-over-WebSocket
+> endpoint. Remaining 0.x work: the client compatibility sweep
+> (WeeChat / HexChat / IRCCloud / TheLounge), the Playwright
+> browser-driven e2e for the SPA, IRC services (NickServ / ChanServ /
+> HostServ / OperServ / MemoServ), and driving the remaining
+> sub-100% packages to full coverage. See `CHANGELOG.md` for the
+> per-release manifests.
 
 ---
 
@@ -134,9 +137,10 @@ ServerlessIRCd/
 │   ├── cf-adapter/        Durable Objects + CfRuntime
 │   └── aws-adapter/       Lambda + DynamoDB + AwsRuntime
 ├── apps/
-│   ├── cf-worker/         worker entry, DO migrations, bindings
+│   ├── cf-worker/         worker entry, DO migrations, bindings, [assets] + CSWSH gate
 │   ├── cf-tcp-container/  Spectrum + Container origin for irc+tls :6697
 │   ├── aws-stack/         CDK stack (APIGW WS + NLB + Lambda streaming + DynamoDB)
+│   ├── web/               vendored Kiwi IRC SPA (→ /app/) + static landing page (→ /)
 │   └── local-cli/         runnable WS + TCP server using in-memory-runtime
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
@@ -174,6 +178,7 @@ pin is resolved automatically:
 ```bash
 corepack enable            # lets the pinned pnpm@11 run on any Node ≥ 24
 
+git submodule update --init   # docs + apps/web Kiwi upstream sources
 pnpm install              # install workspace deps
 
 pnpm build                # build all packages (turbo)
@@ -191,6 +196,14 @@ pnpm mutation             # Stryker spot-check on irc-core (protocol + commands)
 pnpm clean                # remove dist/coverage/.turbo + node_modules
 ```
 
+The web client (`apps/web`) vendors Kiwi IRC as a git submodule. Building it
+needs the upstream sources (`git submodule update --init apps/web/upstream`)
+and `yarn` (Kiwi ships a `yarn.lock`; `corepack enable` provides it):
+
+```bash
+pnpm --filter web build   # builds the Kiwi SPA into apps/web/dist/app/ (/app/)
+```
+
 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
@@ -364,6 +377,66 @@ report).
 
 ---
 
+## Web client (`apps/web`)
+
+A vendored **Kiwi IRC** SPA served at `/app/` and a static project
+landing page served at `/`, both baked out of `apps/web/dist/` and
+served directly by the Cloudflare Worker via its `[assets]` binding.
+The browser opens a native `wss://` straight to the Worker's existing
+IRC-over-WebSocket endpoint — no proxy, gateway, or transport
+adaptation in the hot path. See `docs/WebClientGuide.md` for the
+end-to-end contributor/operator guide.
+
+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
+# → apps/web/dist/index.html        (landing page, served at /)
+# → apps/web/dist/app/index.html    (Kiwi SPA, served at /app/)
+# → apps/web/dist/app/static/config.json  (baked, env-specific)
+```
+
+Then 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
+#   /app/    → Kiwi SPA (opens ws://localhost:8787/)
+#   /health  → plaintext liveness
+```
+
+Deploy staging (Worker + assets in one command):
+
+```bash
+pnpm deploy:cf:staging   # wrangler deploy --env staging
+```
+
+### 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:
+
+1. **Explicit allowlist** — set `WEB_ORIGINS` (comma-separated) for
+   cross-origin deploys (SPA on a different domain than the Worker,
+   e.g. Cloudflare Pages). Only listed origins proceed.
+2. **Same-origin auto-derive (the default)** — when `WEB_ORIGINS` is
+   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.
+
+---
+
 ## WebSocket transport (IRCv3 subprotocols)
 
 The WebSocket entry points (the local CLI, the Cloudflare Worker, and the
@@ -484,14 +557,19 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
   backends (D1 / DynamoDB) ship alongside; until then
   `draft/read-marker` and `draft/pre-away` use in-memory reference
   stores and do not survive an adapter restart.
-- **Phase 14 — Web client.** ⬳ pending: vendored Kiwi IRC SPA served
-  from the Worker, WS Origin allowlist (CSWSH defense), landing page,
-  headless browser e2e.
-- **Coverage hardening.** 🔄 partial as of **v0.6.0**: `aws-adapter`
-  and `aws-stack` now clear the 90% gate (CI boots DynamoDB Local via
-  a JRE; the CDK synth no longer re-bundles under coverage), and the
-  CF packages moved to istanbul to clear the v0.5.0 workerd-incompat.
-  Follow-ups drive each remaining sub-100% package to 100%.
+- **Phase 14 — Web client.** 🔄 partial as of **v0.7.0**: a vendored
+  Kiwi IRC SPA is served at `/app/` and a static landing page at `/`
+  by the Cloudflare Worker via an `[assets]` binding, with a Zod-
+  validated per-env config matrix and **CSWSH defense** (same-origin
+  auto-derive + optional `WEB_ORIGINS` allowlist). The Playwright
+  headless-browser e2e is the remaining open ticket.
+  See `docs/WebClientGuide.md` for the contributor/operator guide.
+- **Coverage hardening.** 🔄 partial as of **v0.7.0**: `aws-adapter`
+  and `aws-stack` clear the 90% gate (v0.6.0); the CF packages run
+  under istanbul (v0.6.0). The remaining packages (`cf-adapter`,
+  `local-cli`, `load-test`, `cf-tcp-container`, `tcp-ws-forwarder`,
+  `irc-test-support`, `web`) are **above the gate but below 100%** —
+  follow-ups drive each to 100%.
 
 ---
 
@@ -563,13 +641,22 @@ bridges a stock TCP client to a deployed WebSocket endpoint.
   `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), and **v0.6.0** (the IRCv3
+  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).
+  manual-only), and **v0.7.0** (the web client — vendored Kiwi IRC SPA
+  at `/app/`, static landing page at `/`, Cloudflare Worker `[assets]`
+  binding, per-env Zod-validated config matrix, and CSWSH defense via
+  same-origin auto-derive + optional `WEB_ORIGINS`; `/health` becomes
+  an explicit route; mutation-killing tests for `irc-core`'s parser /
+  batch / numerics).
+- `docs/WebClientGuide.md` — end-to-end contributor/operator doc for the
+  web client: build pipeline, per-env config matrix, CSWSH rationale and
+  the optional `WEB_ORIGINS` var, local dev, optional Cloudflare Pages
+  alternative, and troubleshooting.
 - `docs/Cloudflare-TCP-Deployment.md` and `docs/AWS-TCP-Deployment.md` —
   end-to-end guides for the `:6697` TCP+TLS variants (Spectrum/Container on
   CF, NLB + Lambda streaming on AWS), including mTLS trust-store setup.

package/apps/aws-stack/package.json

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

package/apps/cf-tcp-container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": true,
   "description": "Cloudflare Container TCP origin for the irc+tls :6697 transport — Spectrum terminates TLS at the edge, this container runs the IRC core over plaintext TCP",
   "license": "BSD-3-Clause",

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",

package/apps/cf-worker/src/origin-allowlist.ts

@@ -0,0 +1,99 @@
+/**
+ * WebSocket `Origin` policy — Cross-Site WebSocket Hijacking (CSWSH) defense.
+ *
+ * Browsers send an `Origin` header on every cross-origin WebSocket upgrade
+ * (RFC 6454); WebSocket upgrades do not otherwise enforce same-origin.
+ * Without a check, a malicious page can open a WS to the IRC server from
+ * the victim's browser and drive the session with the victim's credentials.
+ *
+ * Two enforcement modes, evaluated in order:
+ *
+ *   1. **Explicit allowlist** — when `WEB_ORIGINS` is set, only listed
+ *      origins proceed. Use this for cross-origin deployments (SPA on a
+ *      different domain than the Worker).
+ *
+ *   2. **Auto-derive (same-origin)** — when `WEB_ORIGINS` is unset/empty,
+ *      the Worker compares the browser's `Origin` against the request's own
+ *      origin (`${protocol}//${host}`). If they match, the page that opened
+ *      the WebSocket is the same origin as the server → safe. This is the
+ *      default and requires zero per-env configuration; it works for any
+ *      deployment hostname (`*.workers.dev`, custom domains, preview URLs).
+ *
+ * Non-browser clients (curl, WeeChat, the `tcp-ws-forwarder`, scripted test
+ * harnesses) never send `Origin`; their upgrades are allowed through unchanged
+ * so existing tooling keeps working.
+ *
+ * The policy is split into two pure functions so the logic is exhaustively
+ * unit-testable; the worker's `fetch` handler is the only integration site
+ * (see `tests/ws-origin.test.ts`).
+ */
+
+/**
+ * Outcome of evaluating an upgrade's `Origin` header.
+ *
+ *   • `'allow'`        — proceed: the origin is allowlisted or same-origin,
+ *                        or the header is absent (non-browser client).
+ *   • `'deny'`         — reject (`403`): a browser sent an `Origin` that is
+ *                        not allowlisted and not same-origin.
+ *   • `'fail-closed'`  — reject (`403`): neither the allowlist nor the
+ *                        request origin could be determined (extreme edge
+ *                        case — Cloudflare always sets `Host`).
+ */
+export type OriginDecision = 'allow' | 'deny' | 'fail-closed';
+
+/**
+ * Parse the comma-separated `WEB_ORIGINS` var into a normalized set of
+ * lowercased origins. Whitespace-only and empty entries are dropped so
+ * trailing commas / stray spaces don't pollute the set. An empty/undefined
+ * var yields an empty set, which {@link decideOrigin} treats as "fall back
+ * to auto-derive" (NOT fail-closed).
+ *
+ * Origins are lowercased wholesale for case-insensitive matching; the
+ * scheme and host are case-insensitive per RFC 3986, and lowercasing the
+ * whole string is the simplest normalization that handles the real-world
+ * browser-emitted form (`https://Example.com` → `https://example.com`).
+ */
+export function parseWebOrigins(raw: string | undefined): Set<string> {
+  return new Set(
+    (raw ?? '')
+      .split(',')
+      .map((entry) => entry.trim().toLowerCase())
+      .filter((entry) => entry.length > 0),
+  );
+}
+
+/**
+ * Decide whether a WebSocket upgrade's `Origin` header is permitted.
+ *
+ * @param originHeader  the raw `Origin` header value (`null` when absent).
+ * @param allowlist     the parsed {@link parseWebOrigins} set. When non-empty,
+ *                      it takes precedence over auto-derive (explicit operator
+ *                      override for cross-origin setups).
+ * @param requestOrigin the request's own origin (`${protocol}//${host}`),
+ *                      used for same-origin auto-derive when the allowlist is
+ *                      empty. `null` if the origin cannot be determined.
+ * @returns the {@link OriginDecision}; see the type docstring.
+ */
+export function decideOrigin(
+  originHeader: string | null,
+  allowlist: Set<string>,
+  requestOrigin: string | null,
+): OriginDecision {
+  // Missing Origin = non-browser client (curl, WeeChat, tcp-ws-forwarder).
+  if (originHeader === null || originHeader === '') return 'allow';
+
+  const origin = originHeader.trim().toLowerCase();
+
+  // Mode 1: explicit allowlist takes precedence.
+  if (allowlist.size > 0) {
+    return allowlist.has(origin) ? 'allow' : 'deny';
+  }
+
+  // Mode 2: auto-derive — compare Origin against the request's own origin.
+  if (requestOrigin !== null && requestOrigin !== '') {
+    return origin === requestOrigin.trim().toLowerCase() ? 'allow' : 'deny';
+  }
+
+  // Neither allowlist nor request origin available — fail-closed.
+  return 'fail-closed';
+}