serverless-ircd 0.6.0 → 0.7.0

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

@@ -13,6 +13,14 @@
  *   • Cross-DO coordination (registry + channel) is owned by
  *     `ConnectionDO` and `CfRuntime`; the worker never touches it.
  *
+ * Request routing (non-WS):
+ *   • `/health` — plaintext human-readable liveness string (the previous
+ *     catch-all response, now scoped to an explicit path so the root URL
+ *     is free for the landing page).
+ *   • everything else — falls through to the `[assets]` binding, which
+ *     serves the Kiwi SPA at `/app/` and the landing page at `/` from
+ *     `apps/web/dist`. The asset layer is configured in `wrangler.toml`.
+ *
  * The DO classes are re-exported so `wrangler.toml`'s
  * `durable_objects.bindings.class_name` can resolve them in this
  * module's scope (wrangler requires the class to be exported from the
@@ -29,6 +37,7 @@ import {
   type Env,
   RegistryDO,
 } from '@serverless-ircd/cf-adapter';
+import { decideOrigin, parseWebOrigins } from './origin-allowlist';
 
 // Re-exported for wrangler DO binding resolution. The class names below
 // MUST match `class_name` in `wrangler.toml`.
@@ -36,9 +45,68 @@ export { ChannelDO, ChannelRegistryDO, ConnectionDO, RegistryDO };
 export type { Env };
 
 /**
- * Default edge handler. Non-WebSocket requests get a human-readable
- * health response; WebSocket upgrades are routed to a per-connection
- * `ConnectionDO`.
+ * Production {@link Env} for the worker entry. Extends the cf-adapter
+ * {@link Env} with the `ASSETS` binding (the static-asset `Fetcher` for
+ * `/app/` SPA + `/` landing page). The cf-adapter's internal types stay
+ * asset-agnostic; only the edge entry knows about the asset layer.
+ */
+export interface WorkerEnv extends Env {
+  /**
+   * Static-asset `Fetcher` backed by `apps/web/dist` (production) or
+   * `tests/fixtures/web-dist` (test). Non-WS, non-`/health` requests are
+   * forwarded here so the asset layer serves the SPA and landing page
+   * without the worker inspecting asset paths.
+   */
+  ASSETS: Fetcher;
+  /**
+   * Optional comma-separated allowlist of web origins permitted to open
+   * WebSocket upgrades (CSWSH defense — browsers send `Origin` on every
+   * cross-origin upgrade; WebSocket upgrades do not otherwise enforce
+   * same-origin).
+   *
+   * When set, only listed origins proceed. When unset/empty (the default),
+   * the Worker auto-derives the expected origin from the request's own
+   * `Host` header (same-origin enforcement) — no per-env configuration
+   * needed. Set this only for cross-origin deployments where the SPA is
+   * served from a different domain than the Worker.
+   *
+   * Non-browser clients (curl, WeeChat, the `tcp-ws-forwarder`) omit
+   * `Origin` and pass through unchanged regardless of mode.
+   */
+  WEB_ORIGINS: string;
+}
+
+/**
+ * Human-readable liveness string surfaced at `GET /health`. Previously the
+ * catch-all response for every non-WS request; now scoped to an explicit
+ * path so `/` can serve the landing page from the `[assets]` binding.
+ */
+const HEALTH_BODY =
+  'ServerlessIRCd (Cloudflare Worker). Connect via WebSocket to begin an IRC session.';
+
+/**
+ * Response body sent when a browser-sent `Origin` is not allowed.
+ * Mentioned in `docs/web-client.md` as the canonical CSWSH rejection.
+ */
+const ORIGIN_DENIED_BODY = 'WebSocket upgrade refused: the request Origin is not allowed.';
+
+/**
+ * Response body sent when neither the allowlist nor the request origin could
+ * be determined. In practice this never fires on Cloudflare (the platform
+ * always sets `Host`), but the pure policy function keeps the case for
+ * defensive completeness.
+ */
+const ORIGIN_UNCONFIGURED_BODY =
+  'WebSocket upgrades refused: could not determine the request origin and WEB_ORIGINS is not configured.';
+
+/**
+ * Default edge handler.
+ *
+ * Routing order:
+ *   1. WebSocket upgrade → CSWSH `Origin` check, then per-connection
+ *      `ConnectionDO`.
+ *   2. `GET /health` → plaintext liveness response.
+ *   3. everything else → `env.ASSETS` (Kiwi SPA at `/app/`, landing at `/`).
  *
  * The connection id is allocated here via `crypto.randomUUID()` (the
  * Web Crypto API is sync-available in Workers for RFC-4122 v4 UUIDs).
@@ -47,19 +115,31 @@ export type { Env };
  * it before falling back to a fresh uuid.
  */
 export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
+  async fetch(request: Request, env: WorkerEnv): Promise<Response> {
     if (request.headers.get('Upgrade') === 'websocket') {
+      const allowlist = parseWebOrigins(env.WEB_ORIGINS);
+      const url = new URL(request.url);
+      const requestOrigin = `${url.protocol}//${url.host}`;
+      const decision = decideOrigin(request.headers.get('Origin'), allowlist, requestOrigin);
+      if (decision !== 'allow') {
+        const body = decision === 'fail-closed' ? ORIGIN_UNCONFIGURED_BODY : ORIGIN_DENIED_BODY;
+        return new Response(body, {
+          status: 403,
+          headers: { 'content-type': 'text/plain; charset=utf-8' },
+        });
+      }
       const connId = crypto.randomUUID();
       const id = env.CONNECTION_DO.idFromName(connId);
       const stub = env.CONNECTION_DO.get(id);
       return stub.fetch(request);
     }
-    return new Response(
-      'ServerlessIRCd (Cloudflare Worker). Connect via WebSocket to begin an IRC session.',
-      {
+    const url = new URL(request.url);
+    if (url.pathname === '/health') {
+      return new Response(HEALTH_BODY, {
         status: 200,
         headers: { 'content-type': 'text/plain; charset=utf-8' },
-      },
-    );
+      });
+    }
+    return env.ASSETS.fetch(request);
   },
 };

package/apps/cf-worker/tests/fixtures/web-dist/app/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<!--
+  Test-only fixture mirroring the real `apps/web/dist/app/index.html` produced
+  by the Kiwi SPA build (`pnpm --filter web build`). The cf-worker smoke suite
+  points its `[assets]` binding here so the worker's fall-through routing
+  (WS → ConnectionDO, /health → plaintext, else → ASSETS) is exercised without
+  depending on the (slow, submodule-heavy) Kiwi build. Production points at
+  `apps/web/dist`; this fixture only stands in for the test run.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>KiwiIRC</title>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/apps/cf-worker/tests/fixtures/web-dist/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<!--
+  Test-only fixture standing in for the landing page shipped by the
+  `apps/web` build (`apps/web/dist/index.html`). Production will serve a
+  real landing page at `/`; the cf-worker smoke suite asserts that `GET /`
+  is served by the `[assets]` binding rather than the legacy plaintext
+  health response (now exclusive to `/health`).
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>ServerlessIRCd</title>
+  </head>
+  <body>
+    <h1>ServerlessIRCd</h1>
+    <p>A serverless IRC daemon.</p>
+  </body>
+</html>

package/apps/cf-worker/tests/origin-allowlist.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Unit tests for the WebSocket `Origin` allowlist helpers.
+ *
+ * The worker's CSWSH defense is split into two pure functions
+ * (`parseWebOrigins`, `decideOrigin`) so the policy logic is exhaustively
+ * coverable without driving a Durable Object through `worker.fetch`. The
+ * integration-side assertions (status codes against the real handler) live
+ * in `ws-origin.test.ts`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { decideOrigin, parseWebOrigins } from '../src/origin-allowlist';
+
+describe('parseWebOrigins', () => {
+  it('splits a comma-separated list into a set of normalized origins', () => {
+    expect(parseWebOrigins('https://example.com, https://app.example.com')).toEqual(
+      new Set(['https://example.com', 'https://app.example.com']),
+    );
+  });
+
+  it('lowercases origins for case-insensitive comparison', () => {
+    expect(parseWebOrigins('https://Example.COM/Path').has('https://example.com/path')).toBe(true);
+  });
+
+  it('drops whitespace-only and empty entries', () => {
+    expect(parseWebOrigins('https://example.com, ,   ,https://b.example.com')).toEqual(
+      new Set(['https://example.com', 'https://b.example.com']),
+    );
+  });
+
+  it('returns an empty set for an empty/undefined var (fail-closed sentinel)', () => {
+    expect(parseWebOrigins('').size).toBe(0);
+    expect(parseWebOrigins('   ').size).toBe(0);
+    expect(parseWebOrigins(undefined).size).toBe(0);
+  });
+});
+
+describe('decideOrigin', () => {
+  const allowlist = parseWebOrigins('https://example.com, https://app.example.com');
+
+  // ---- missing Origin = non-browser client (curl, WeeChat, tcp-ws-forwarder)
+
+  it('allows a missing Origin header (non-browser client)', () => {
+    expect(decideOrigin(null, allowlist, 'https://example.com')).toBe('allow');
+  });
+
+  it('allows an empty Origin header (treated like a missing header)', () => {
+    expect(decideOrigin('', allowlist, 'https://example.com')).toBe('allow');
+  });
+
+  // ---- explicit allowlist (WEB_ORIGINS is set)
+
+  it('allows an Origin that is in the allowlist', () => {
+    expect(decideOrigin('https://example.com', allowlist, 'https://example.com')).toBe('allow');
+  });
+
+  it('allows an Origin that differs only by case', () => {
+    expect(decideOrigin('https://EXAMPLE.com', allowlist, 'https://example.com')).toBe('allow');
+  });
+
+  it('denies an Origin that is not in the allowlist', () => {
+    expect(decideOrigin('https://evil.example.net', allowlist, 'https://example.com')).toBe('deny');
+  });
+
+  it('denies an Origin that matches requestOrigin but is NOT in the allowlist (allowlist wins)', () => {
+    // WEB_ORIGINS takes precedence: if the operator pinned an explicit list,
+    // same-origin is NOT automatically allowed unless the origin is listed.
+    const strict = parseWebOrigins('https://only-this.com');
+    expect(decideOrigin('https://example.com', strict, 'https://example.com')).toBe('deny');
+  });
+
+  // ---- auto-derive (WEB_ORIGINS is empty — same-origin enforcement)
+
+  it('auto-allows a same-origin Origin when the allowlist is empty', () => {
+    expect(decideOrigin('https://example.com', new Set(), 'https://example.com')).toBe('allow');
+  });
+
+  it('auto-denies a cross-origin Origin when the allowlist is empty', () => {
+    expect(decideOrigin('https://evil.example.net', new Set(), 'https://example.com')).toBe('deny');
+  });
+
+  it('auto-derive is case-insensitive', () => {
+    expect(decideOrigin('https://EXAMPLE.com', new Set(), 'https://example.com')).toBe('allow');
+  });
+
+  it('auto-allows a missing Origin even when the allowlist is empty (non-browser client)', () => {
+    expect(decideOrigin(null, new Set(), 'https://example.com')).toBe('allow');
+  });
+
+  // ---- fail-closed (cannot determine same-origin AND no allowlist)
+
+  it('fail-closes when a browser sends an Origin but neither allowlist nor requestOrigin exist', () => {
+    expect(decideOrigin('https://example.com', new Set(), null)).toBe('fail-closed');
+  });
+
+  it('still allows a missing Origin even when neither allowlist nor requestOrigin exist (non-browser client)', () => {
+    // Non-browser clients never send Origin; they pass through regardless of
+    // configuration state. Only browser-sent Origins can be fail-closed.
+    expect(decideOrigin(null, new Set(), null)).toBe('allow');
+  });
+});

package/apps/cf-worker/tests/smoke.test.ts

@@ -30,6 +30,12 @@ declare global {
       SERVER_NAME: string;
       NETWORK_NAME: string;
       MOTD_LINES: string;
+      // Static-assets binding (`[assets]` in `wrangler.test.toml`, pointed at
+      // `tests/fixtures/web-dist`). Production points at `apps/web/dist`; the
+      // fixture mirrors the `app/index.html` + `index.html` layout so the
+      // worker's fall-through routing is exercised without depending on the
+      // Kiwi SPA build.
+      ASSETS: Fetcher;
     }
   }
 }
@@ -47,13 +53,33 @@ function numericEquals(line: string, code: string): boolean {
 }
 
 describe('cf-worker deploy glue', () => {
-  it('non-WebSocket GET returns a human-readable health response', async () => {
-    const response = await worker.fetch(new Request('https://irc.example.com/'), env);
+  it('GET /health returns a human-readable plaintext health response', async () => {
+    const response = await worker.fetch(new Request('https://irc.example.com/health'), env);
     expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toBe('text/plain; charset=utf-8');
     const body = await response.text();
     expect(body.toLowerCase()).toContain('serverlessircd');
   });
 
+  it('GET /app/ serves the SPA index from the [assets] binding', async () => {
+    const response = await worker.fetch(new Request('https://irc.example.com/app/'), env);
+    expect(response.status).toBe(200);
+    const body = await response.text();
+    // The fixture SPA HTML carries this marker so the test asserts the
+    // assets binding (not the /health plaintext branch) produced the body.
+    expect(body).toContain('<title>KiwiIRC</title>');
+  });
+
+  it('GET / (landing page) is served by the [assets] binding, not the health plaintext', async () => {
+    const response = await worker.fetch(new Request('https://irc.example.com/'), env);
+    expect(response.status).toBe(200);
+    const body = await response.text();
+    // The fixture landing page carries this marker; the old health
+    // plaintext response is now exclusively at /health.
+    expect(body).toContain('<title>ServerlessIRCd</title>');
+    expect(body).not.toContain('Connect via WebSocket');
+  });
+
   it('completes CONNECT → REGISTER → JOIN → PRIVMSG → QUIT', async () => {
     // ----- CONNECT: WebSocket upgrade through the worker's fetch handler.
     const upgrade = new Request('https://irc.example.com/', {

package/apps/cf-worker/tests/ws-origin.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Integration tests for the WebSocket `Origin` policy (CSWSH defense).
+ *
+ * Drives the production worker entry (`src/worker.ts`) end-to-end through
+ * `worker.fetch` to assert the `Origin` header policy is enforced at the
+ * edge, before any upgrade reaches `ConnectionDO`. The pure policy logic
+ * is covered separately in `origin-allowlist.test.ts`; these tests assert
+ * the wiring (status codes + that the DO is never reached on a rejection).
+ *
+ * Two modes are exercised:
+ *
+ *   • Explicit allowlist — `WEB_ORIGINS` is set in `wrangler.test.toml`
+ *     `[vars]` as `https://example.com`. Only listed origins proceed.
+ *
+ *   • Auto-derive (same-origin) — per-test override blanks `WEB_ORIGINS`;
+ *     the Worker compares the browser's `Origin` against the request's own
+ *     host. Same-origin upgrades proceed; cross-origin are rejected.
+ */
+
+import { env } from 'cloudflare:test';
+import { describe, expect, it } from 'vitest';
+import worker from '../src/worker';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      WEB_ORIGINS: string;
+    }
+  }
+}
+
+const UPGRADE_URL = 'https://irc.example.com/';
+/** The request's own origin — what auto-derive compares Origin against. */
+const SELF_ORIGIN = 'https://irc.example.com';
+
+function upgradeRequest(origin?: string): Request {
+  const headers: Record<string, string> = { Upgrade: 'websocket' };
+  if (origin !== undefined) headers.Origin = origin;
+  return new Request(UPGRADE_URL, { headers });
+}
+
+describe('WS Origin policy — explicit allowlist (WEB_ORIGINS set)', () => {
+  it('proceeds (101) when the Origin is in WEB_ORIGINS', async () => {
+    const response = await worker.fetch(upgradeRequest('https://example.com'), env);
+    expect(response.status).toBe(101);
+    response.webSocket?.accept();
+    response.webSocket?.close();
+  });
+
+  it('rejects with 403 when the Origin is not in WEB_ORIGINS', async () => {
+    const response = await worker.fetch(upgradeRequest('https://evil.example.net'), env);
+    expect(response.status).toBe(403);
+    expect(response.webSocket).toBeNull();
+    const body = await response.text();
+    expect(body.toLowerCase()).toContain('origin');
+  });
+
+  it('proceeds (101) when the Origin header is missing (non-browser client)', async () => {
+    const response = await worker.fetch(upgradeRequest(), env);
+    expect(response.status).toBe(101);
+    response.webSocket?.accept();
+    response.webSocket?.close();
+  });
+});
+
+describe('WS Origin policy — auto-derive (WEB_ORIGINS unset → same-origin)', () => {
+  /** Env with WEB_ORIGINS blanked so the Worker falls back to auto-derive. */
+  const autoEnv = { ...env, WEB_ORIGINS: '' };
+
+  it('proceeds (101) for a same-origin upgrade', async () => {
+    const response = await worker.fetch(upgradeRequest(SELF_ORIGIN), autoEnv);
+    expect(response.status).toBe(101);
+    response.webSocket?.accept();
+    response.webSocket?.close();
+  });
+
+  it('rejects with 403 for a cross-origin upgrade', async () => {
+    const response = await worker.fetch(upgradeRequest('https://evil.example.net'), autoEnv);
+    expect(response.status).toBe(403);
+    expect(response.webSocket).toBeNull();
+  });
+
+  it('proceeds (101) when the Origin header is missing (non-browser client)', async () => {
+    const response = await worker.fetch(upgradeRequest(), autoEnv);
+    expect(response.status).toBe(101);
+    response.webSocket?.accept();
+    response.webSocket?.close();
+  });
+});

package/apps/cf-worker/wrangler.test.toml

@@ -11,10 +11,33 @@ main = "src/worker.ts"
 compatibility_date = "2024-11-01"
 compatibility_flags = ["nodejs_compat"]
 
+# Static-assets binding. Production points at `../../apps/web/dist` (the Kiwi
+# SPA + landing page built by `apps/web`); the test config points at a fixture
+# so the smoke suite does not depend on the (slow) Kiwi upstream build. The
+# fixture mirrors the `app/index.html` + `index.html` layout; the worker's
+# fall-through routing (`/health` → plaintext, else → ASSETS) is what's under
+# test, not the SPA contents.
+[assets]
+directory = "./tests/fixtures/web-dist"
+binding = "ASSETS"
+# `none` returns 404 for unmatched paths — the SPA lives at `/app/` and the
+# landing page at `/`, both with real `index.html` files, so no SPA fallback
+# is required.
+not_found_handling = "none"
+# Mirror production: route every request through the Worker first so WS
+# upgrades at `/` aren't intercepted by the asset platform (which would
+# serve `index.html` with 200 instead of a 101 upgrade).
+run_worker_first = true
+
 [vars]
 SERVER_NAME = "irc.example.com"
 NETWORK_NAME = "ServerlessIRCd"
 MOTD_LINES = "Welcome to the cf-worker smoke test."
+# CSWSH allowlist. The ws-origin integration suite asserts an upgrade from
+# `https://example.com` proceeds and `https://evil.example.net` is rejected
+# (the fail-closed branch overrides this per request via `{ ...env,
+# WEB_ORIGINS: '' }`).
+WEB_ORIGINS = "https://example.com"
 
 [[durable_objects.bindings]]
 name = "CONNECTION_DO"

package/apps/cf-worker/wrangler.toml

@@ -49,6 +49,15 @@ invocation_logs = true
 ## (`loadServerConfigFromCfEnv`) fails fast at boot when it is unset.
 ## Production deployments MUST override it to the public hostname
 ## clients see in numerics (001, 005, etc.).
+##
+## `WEB_ORIGINS` is the OPTIONAL comma-separated allowlist of web origins
+## permitted to open WebSocket upgrades (CSWSH defense). When set, only
+## listed origins proceed. When unset/empty (the default), the Worker
+## auto-derives the expected origin from the request's own `Host` header
+## (same-origin enforcement) — no per-env config needed. Set this only for
+## cross-origin deployments where the SPA is served from a different domain
+## than the Worker. Non-browser clients (curl, WeeChat, tcp-ws-forwarder)
+## omit `Origin` and pass through unchanged regardless.
 [vars]
 SERVER_NAME = "irc.your-domain.invalid"
 NETWORK_NAME = "ServerlessIRCd"
@@ -57,6 +66,41 @@ Welcome to ServerlessIRCd.
 This is a deployed Cloudflare Worker.
 """
 
+## ---------------------------------------------------------------------------
+## Static assets — Kiwi SPA + landing page.
+## ---------------------------------------------------------------------------
+## The `[assets]` binding serves `apps/web/dist` (built by `pnpm --filter web
+## build`). The non-WS, non-`/health` branch of `worker.ts`'s `fetch` falls
+## through to this binding, so:
+##   • `/app/`              → the Kiwi IRC SPA (`dist/app/index.html` + its
+##                            hashed assets under `/app/assets/...`).
+##   • `/`                  → the landing page (`dist/index.html`, shipped by
+##                            the `apps/web` build).
+##   • `/health`            → plaintext liveness (handled by the worker, not
+##                            assets).
+## The deploy workflow (`deploy-cf.yml`) runs `pnpm build` before `wrangler
+## deploy` so `apps/web/dist` is freshly populated. `wrangler dev` serves the
+## same asset layer against the locally-built `dist`.
+[assets]
+## Relative to this file (`apps/cf-worker/`), so `../../apps/web/dist`.
+directory = "../../apps/web/dist"
+## Expose the asset `Fetcher` on `env.ASSETS` (see `WorkerEnv` in `worker.ts`).
+binding = "ASSETS"
+## Return 404 for unmatched paths. The SPA lives at `/app/` and the landing
+## page at `/`; both are concrete `index.html` files, so no SPA fallback is
+## required. Kiwi uses query/hash-based client routing, not path routing.
+not_found_handling = "none"
+## Route EVERY request through the Worker before the asset platform serves a
+## matching static file. Without this, the default (`run_worker_first = false`)
+## causes the asset platform to serve `dist/index.html` at `/` with 200 OK for
+## WebSocket upgrade requests — the Worker's `Upgrade: websocket` check never
+## fires and the client sees "HTTP error: 200 OK" instead of a 101 upgrade.
+## The WS endpoint and the landing page share path `/`, so a path-pattern
+## exclusion can't tell them apart; the Worker must run first for everything.
+## The Worker falls through to `env.ASSETS.fetch(request)` for non-WS,
+## non-`/health` requests, so static content is unaffected.
+run_worker_first = true
+
 ## ---------------------------------------------------------------------------
 ## Staging environment.
 ## ---------------------------------------------------------------------------
@@ -79,6 +123,16 @@ This is a deployed Cloudflare Worker.
 This Worker was deployed by CI from the main branch.
 """
 
+# Staging serves the same `apps/web/dist` asset layer. Wrangler requires the
+# per-env assets block so `--env staging` deploys both the Worker and its
+# assets in a single `wrangler deploy --env staging` (the same `pnpm build`
+# populates `dist/` ahead of the deploy step).
+[env.staging.assets]
+directory = "../../apps/web/dist"
+binding = "ASSETS"
+not_found_handling = "none"
+run_worker_first = true
+
 ## ---------------------------------------------------------------------------
 ## D1 database — SASL account persistence.
 ## ---------------------------------------------------------------------------

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": true,
   "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
   "license": "BSD-3-Clause",