ServerlessIRCd — Web Client Plan

A static, CDN-served Kiwi IRC web frontend that lets a browser connect directly to a deployed ServerlessIRCd instance. The SPA opens a native wss:// WebSocket to the Cloudflare Worker entry and speaks the IRC protocol one-message-per-text-frame — exactly what the server already emits today. No proxy in the hot path.

Status: planning. No code has landed. Tickets proposed in §7; once ratified they will be appended to tickets.md / progress.md under a new Phase 8 — Web client heading and supersede the corresponding sections here.

1. Goals & non-goals

Goals

• A drop-in static frontend that boots Kiwi IRC, pre-configured for a given ServerlessIRCd deployment (staging, prod, self-host).
• Browser talks directly to the existing WebSocket entry — no extra proxy, gateway, or transport adaptation in the v1 hot path.
• Per-environment builds with reproducible config (no runtime secrets in the bundle).
• Same TDD discipline as the rest of the monorepo: schema tests, build smoke, headless e2e against a deployed stack.
• One-command pnpm --filter web build:staging produces a deployable dist/ (or per-env variant).

Non-goals (v1 of the frontend)

• Server-side rendering / dynamic routing. Kiwi is a Vue SPA; SSR buys us nothing here.
• Custom Kiwi plugins, themes, or heavy branding. Stock chrome is fine for v1; the upstream build is layered with our static/config.json only.
• Server-side account / oper UI beyond what stock Kiwi ships. SASL PLAIN is already part of Kiwi's default flow.
• A second transport (SockJS, Kiwi multi-server transport via webircgateway). Documented as an optional fallback only.
• WEBIRC hostname injection at the gateway layer. ServerlessIRCd will do its own hostmask cloaking in TICKET-046; we don't need a WEBIRC proxy for it.

Design-for-later

• Plugin seam: a clean place under apps/web/plugins/ (mirrors Kiwi's plugin convention) so a future ticket can add SASL UI helpers, chathistory controls (once TICKET-063 lands), etc.
• Cloudflare Pages variant of the build output kept valid so prod can move off the Worker [assets] binding without rebuilding.

2. Architecture

┌────────────────────────────────────────────────────────────────────┐
│  Browser                                                           │
│    loads index.html + JS bundle (Kiwi IRC SPA)                     │
│    fetches /static/config.json at boot                             │
└────────────────────────────────────────────────────────────────────┘
          │                                │
          │ HTTPS (static assets)          │ wss (one IRC msg / frame)
          ▼                                ▼
┌────────────────────────────────────────────────────────────────────┐
│  apps/cf-worker  (existing Cloudflare Worker)                      │
│    fetch():                                                        │
│      • Upgrade: websocket  → ConnectionDO (existing path)          │
│          + Origin allowlist check (NEW, TICKET-070)                │
│      • otherwise            → [assets] binding serves dist/        │
└────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
                   (ConnectionDO / RegistryDO / ChannelDO
                    unchanged — see PLAN §6.1)

The Worker is the single origin for both the SPA and the WebSocket. That makes CORS trivial (same-origin) and lets one domain serve the whole product. A Cloudflare Pages deployment of the same dist/ is a documented alternative for prod if cost / separation of concerns ever favors it.

Why no webircgateway in the hot path? ServerlessIRCd already speaks the wire format browser Kiwi expects: native WebSocket text frames, one IRC message per frame, with \r\n-joined-frame tolerance (PLAN §9). The gateway exists in-tree (webircgateway/) and ships as an optional sidecar for environments where raw wss is blocked by corporate proxies or mobile carriers; it provides SockJS + Kiwi multi-server transport fallback in those cases. v1 of the frontend does not require it.

3. Component placement

3.1 New workspace package: apps/web

apps/web/
├── upstream/              Kiwi IRC source — git submodule, tag-pinned
│                          (mirrors existing `docs/` + `webircgateway/`
│                           submodule pattern)
├── static/
│   ├── config.json        Our environment-specific Kiwi config
│   ├── config.staging.json  Per-env override (build matrix)
│   ├── config.prod.json
│   └── assets/            Brand overrides (logo, favicon) — optional
├── src/
│   ├── config-schema.ts   Zod schema for config.json (the only TS we own)
│   └── plugins/           Reserved for future Kiwi plugins (empty in v1)
├── scripts/
│   └── build.mjs          Orchestrates upstream build + layers our config
├── tests/
│   ├── config-schema.test.ts   Zod validation, red/green per field
│   └── build-smoke.test.ts     Asserts dist/ shape post-build
├── package.json           pnpm workspace package (@serverless-ircd/web)
├── tsconfig.json          extends tsconfig.base.json
└── README.md              per-package developer notes

The package owns no IRC logic — it's purely a build/config layer over the upstream Kiwi SPA. The only TypeScript we ship is the Zod config schema and any future plugin shims.

3.2 Touchpoints with existing code

4. Decisions to confirm

Each row is a proposed default. Override before TICKET-066 lands.

4.1 Hosting — Worker assets vs Pages

• Worker [assets] binding (recommended for staging). Single domain serves SPA + WS. Simplest CORS story, simplest deploy story, one wrangler command. Adds zero runtime cost (assets are served by the Workers runtime, not by JS).
• Cloudflare Pages (alternative for prod). Decouples static deploys from Worker deploys — useful if frontend changes more often than the IRCd. Requires the Worker to allow the Pages origin in WEB_ORIGINS.

The build output is identical for both; the choice is a deploy-time knob, not a build-time one.

4.4 Origin allowlist — why it's mandatory

WebSocket upgrades do not follow the same-origin policy. An attacker page can new WebSocket('wss://irc.example.com/') and, if the user has previously registered a nick in another tab, race the connection into issuing commands on their behalf (CSWSH — cross-site WebSocket hijacking). The Worker MUST reject upgrades whose Origin header is not in a configured allowlist. This is a defense-in-depth item on top of any session/nick ownership semantics the IRCd grows later.

5. Kiwi IRC configuration surface

Kiwi reads a JSON config either from window.kiwiConfig or from /static/config.json fetched at boot (we use the latter — it lets us swap config per env without rebuilding the JS bundle). The schema we own mirrors the subset of Kiwi's documented config keys that we care about; unknown keys are passed through unchanged so the upstream's evolution doesn't break our build.

// static/config.staging.json (example)
{
  "server": "irc-staging.example.com",
  "port": 443,
  "tls": true,
  "path": "/",                       // WS path on the Worker
  "nick": "kiwi-?",                   // ? = random suffix
  "channels": ["#welcome"],
  "brand": "ServerlessIRCd (staging)",
  "windowTitle": "ServerlessIRCd staging",
  "showSendButton": true,
  "theme": "Default",
  "plugins": []
}

Zod schema (apps/web/src/config-schema.ts):

export const KiwiConfig = z.object({
  server: z.string().min(1),
  port: z.number().int().min(1).max(65535),
  tls: z.boolean(),
  path: z.string().startsWith('/').default('/'),
  nick: z.string().min(1),
  channels: z.array(z.string().startsWith('#')).default([]),
  brand: z.string().default('ServerlessIRCd'),
  windowTitle: z.string().default('ServerlessIRCd'),
}).passthrough();   // tolerate upstream keys we don't model

Build matrix:

A malformed config fails the build with a readable Zod error. No silent fall-through.

6. Testing strategy

Strict TDD per the project rules. The frontend is mostly assembled rather than authored, so the testable surface is narrow but real:

E2E reuses the scenario vocabulary already in apps/cf-worker/scripts/smoke.mjs so the WS smoke and the browser smoke share fixture data.

Determinism: the Zod schema, build smoke, and Origin check tests are all pure. The Playwright e2e is gated behind a --e2e flag (off by default in pnpm test, on in CI's nightly job) so it can't make the unit suite flaky.

7. Proposed tickets

Seven new tickets under a new Phase 8 — Web client heading in tickets.md / progress.md. Each follows the existing TDD outline shape (Red → Green → Refactor, acceptance criteria, dependencies).

TICKET-066 — apps/web workspace skeleton

• Phase: 8
• Points: 2
• Dependencies: —
• Description: Create the apps/web pnpm workspace package with an empty index.html, package.json, tsconfig.json extending tsconfig.base.json, and a vitest config. Add the build task to turbo.json. No Kiwi source yet — just the scaffolding so subsequent tickets have a home.
• Acceptance Criteria:
  • pnpm install recognizes @serverless-ircd/web.
  • pnpm --filter web test runs (no tests yet, exits 0).
  • pnpm --filter web typecheck passes against tsconfig.base.json.
  • Biome lints the new files without errors.
• TDD Outline: Red on a vitest asserting apps/web/package.json name === '@serverless-ircd/web'; green by adding the package.

TICKET-067 — Vendor Kiwi IRC as git submodule; build pipeline

• Phase: 8
• Points: 3
• Dependencies: TICKET-066
• Description: Add Kiwi IRC source as a git submodule at apps/web/upstream/ pinned to a release tag. scripts/build.mjs runs Kiwi's upstream build (yarn && yarn build inside upstream/), then copies upstream/dist/ into apps/web/dist/ and layers our static/config.json over the upstream default. pnpm --filter web build produces a working SPA bundle.
• Acceptance Criteria:
  • pnpm --filter web build from a clean checkout produces apps/web/dist/index.html, apps/web/dist/static/config.json, and the JS bundle.
  • The submodule is pinned to a specific upstream tag (not main).
  • .gitmodules entry added; git submodule update --init is in the contributor quickstart.
• TDD Outline: Red on a vitest build-smoke test asserting dist/index.html exists post-build; green by wiring build.mjs.

TICKET-068 — static/config.json Zod schema + per-env build matrix

• Phase: 8
• Points: 2
• Dependencies: TICKET-067
• Description: Ship src/config-schema.ts (Zod, see §5) with static/config.json, static/config.staging.json, and static/config.prod.json. build.mjs accepts a --env flag selecting which config to bake into dist/. Default config targets the staging Worker hostname.
• Acceptance Criteria:
  • Malformed config (missing server, out-of-range port, non-# channel) fails the build with a readable Zod error.
  • pnpm --filter web build:staging bakes config.staging.json; :prod bakes config.prod.json.
  • A vitest assertion confirms the configured server matches the requested env (catches cross-env bake mistakes in CI).
• TDD Outline: Red on Zod rejecting {}; green. Red on a config with port: 99999; green. Red on channels: ["foo"]; green.

TICKET-069 — Serve static assets from apps/cf-worker via [assets]

• Phase: 8
• Points: 2
• Dependencies: TICKET-067
• Description: Add a Wrangler [assets] binding to apps/cf-worker/wrangler.toml pointing at ../../apps/web/dist. The non-WS branch of worker.ts fetch() falls through to assets (the binding handles this automatically; the existing plaintext health response moves to a /health path). Per-env ([env.staging.assets]) blocks for staging.
• Acceptance Criteria:
  • wrangler dev serves dist/index.html at / and the JS bundle at its hashed asset path.
  • /health returns the previous plaintext response.
  • WS upgrade still routes to ConnectionDO.
  • Staging deploys both Worker and assets in one wrangler deploy --env staging.
• TDD Outline: Red on a vitest-pool-workers test asserting GET / returns the SPA HTML; green by adding the binding. Red on GET /health returning the plaintext string; green.

TICKET-070 — WS Origin allowlist in Worker (CSWSH defense)

• Phase: 8
• Points: 3
• Dependencies: TICKET-069
• Description: Worker validates the Origin header on every WS upgrade against a config-driven WEB_ORIGINS var (comma-separated, per-env). Disallowed origins get 403 Forbidden. Documentation in docs/web-client.md makes clear this is mandatory, not optional.
• Acceptance Criteria:
  • Upgrade with Origin in WEB_ORIGINS → proceeds (existing path).
  • Upgrade with Origin not in list → 403.
  • Upgrade with missing Origin (non-browser client — curl, the tcp-ws-forwarder, WeeChat) → proceeds (preserves existing non-browser tooling).
  • Empty/missing WEB_ORIGINS var → fail-closed (build error on wrangler deploy) so a deploy can never silently disable the check.
• TDD Outline: Red on disallowed Origin receiving 403 (currently proceeds); green by adding the check. Red on missing Origin with empty WEB_ORIGINS proceeding; green by failing closed.

TICKET-071 — E2E: headless browser vs deployed staging frontend

• Phase: 8
• Points: 5
• Dependencies: TICKET-068, TICKET-069, TICKET-070
• Description: Playwright e2e in apps/web/tests/e2e/ that opens the deployed staging SPA, asserts Kiwi reaches registered state (001/376), joins #welcome, sends a PRIVMSG, and sees the echo on its own buffer. Reuses the scenario fixture data already living in apps/cf-worker/scripts/smoke.mjs. Gated behind --e2e; wired into the nightly CI job, not the per-push suite.
• Acceptance Criteria:
  • Single test passes against the staging Worker + frontend.
  • The test fails clearly when the SPA fails to connect (timeout on registration).
  • Adding a new scenario is a one-file append (data-driven).
• TDD Outline: Red on a stub test asserting document.title matches the configured windowTitle; green once the SPA loads from staging. Then incrementally add the register/join/privmsg assertions.

TICKET-072 — Docs: docs/web-client.md

• Phase: 8
• Points: 1
• Dependencies: TICKET-071
• Description: End-to-end contributor/operator doc covering: how to bootstrap the submodule, build per-env, serve locally, deploy via wrangler; the CSWSH rationale and the mandatory WEB_ORIGINS var; when and how to deploy the optional webircgateway sidecar for SockJS fallback; how to swap to Cloudflare Pages if prod favors it.
• Acceptance Criteria:
  • A new contributor can git submodule update --init, pnpm install, pnpm --filter web build:staging, and wrangler deploy --env staging following only this doc.
  • WEB_ORIGINS is called out as mandatory, with examples.
  • webircgateway is clearly labeled optional with the triggering use case (proxy-blocked wss).
• TDD Outline: N/A (documentation). Reviewed by following the steps from scratch in a clean checkout.

8. Risks

9. Out of scope for v1 of the frontend

• Custom Kiwi plugins (SASL UI helpers, chathistory controls once TICKET-063 lands, etc.). The src/plugins/ directory is reserved.
• Custom themes / heavy branding. Stock Kiwi chrome with a logo swap.
• Server-side rendering or any server-side runtime.
• A second transport (SockJS / Kiwi multi-server transport via webircgateway). Documented as optional only.
• Account / oper login UI beyond stock Kiwi.
• Internationalization overrides beyond what Kiwi ships by default.
• Mobile-specific build variants (PWA manifest, etc.). The SPA is responsive out of the box; deferred to a follow-up if measured mobile usage justifies it.

10. Deliverables checklist (definition of done for v1 web client)

• apps/web workspace builds under turbo with no internal workspace runtime deps.
• pnpm --filter web build:staging produces a dist/ that, served by the staging Worker, reaches registered state in a real browser.
• Worker [assets] binding serves the SPA in staging; /health preserves the plaintext response.
• WS Origin allowlist enforced; missing WEB_ORIGINS fails the deploy.
• Playwright e2e green against staging on the nightly CI job.
• docs/web-client.md walkable from a clean checkout.
• All new tickets green in progress.md; PLAN §3 / README repo layout updated to mention apps/web.

11. Open questions

• Should the frontend live on the same domain as the Worker (current proposal) or a subdomain (web.example.com vs irc.example.com)? Same-domain is simpler; subdomain is more conventional for IRC networks. Decide before TICKET-069.
• Do we want a Makefile-style convenience target (pnpm web:dev) that boots both wrangler dev and a vite preview of the SPA in parallel, or keep them as separate commands? Lean toward convenience target.
• Should the Origin allowlist support wildcards (*.example.com) or exact-match only? Lean toward exact-match for v1; revisit if multi- tenant deployment ever demands it.