serverless-ircd 0.5.0 → 0.7.0

package/apps/aws-stack/tests/coverage-command.test.ts

@@ -0,0 +1,155 @@
+/**
+ * CI-hardening acceptance test for the aws-stack coverage command.
+ *
+ * Drives the real `pnpm --filter @serverless-ircd/aws-stack coverage`
+ * pipeline in a subprocess and asserts two things the ticket requires:
+ *
+ *   1. The command exits 0 (no `[ELIFECYCLE]` / OOM crash).
+ *   2. The vitest text reporter prints an `All files` coverage row.
+ *
+ * Before the bundle-stub fix this command exhausted CI memory re-running
+ * esbuild for every `NodejsFunction` synth (one per stack-related test,
+ * multiplied by 3–4 Lambda constructs each), and died with
+ * `[ELIFECYCLE] Command failed with exit code N` before the coverage
+ * table could print. The stub (`makeLambda` in `src/aws-stack.ts`,
+ * armed by `tests/vitest.setup.ts`) makes the synth a no-op for
+ * bundling so the pipeline completes in seconds.
+ *
+ * Recursion guard: the subprocess inherits
+ * `IRC_AWS_COVERAGE_SELF_TEST=1`, which makes this describe block skip
+ * itself when re-entered. Without that, the outer coverage run would
+ * spawn the coverage command, which spawns the coverage command, … .
+ *
+ * Slow-path: the subprocess still spins up pnpm + vitest + the v8
+ * coverage provider, so the test carries a generous timeout. It is
+ * intentionally part of the default `pnpm test` run because it is the
+ * end-to-end guard against the coverage pipeline silently regressing
+ * back into the bundling loop.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+/** Skip-self env var handed to the subprocess so it does not re-spawn. */
+const SELF_TEST_FLAG = 'IRC_AWS_COVERAGE_SELF_TEST';
+
+/** Hard ceiling for the subprocess; the stubbed suite finishes well under this. */
+const COVERAGE_TIMEOUT_MS = 240_000;
+
+/**
+ * Strips ANSI color / cursor escapes from `combined` so the assertion
+ * regexes below can be plain text. Vitest always writes the coverage
+ * banner and table through its colorizer even when stdout is piped, so
+ * without this the banner reads `% \u001b[2mCoverage report from …`
+ * and a literal `/Coverage report from v8/` regex fails to match.
+ */
+function stripAnsi(text: string): string {
+  // The ANSI color escape is the literal ESC byte (0x1B) followed by `[`
+  // and a parameter list. biome's noControlCharactersInRegex flags the
+  // inline `\u001b` literal, so the regex is built from a hex string to
+  // make the intent explicit while satisfying the linter.
+  const ansiPattern = new RegExp(`[${String.fromCharCode(27)}]\\[[0-9;]*m`, 'g');
+  return text.replace(ansiPattern, '');
+}
+
+describe.skipIf(process.env[SELF_TEST_FLAG] === '1')(
+  'aws-stack coverage command (ci-hardening acceptance)',
+  () => {
+    it(
+      'completes and prints an "All files" coverage row',
+      () => {
+        // Strip the `npm_package_*` / `npm_config_*` env vars that the outer
+        // `pnpm run coverage` sets. When those leak into the spawned pnpm,
+        // its `--filter` resolution short-circuits to the current package
+        // and fails with `ERR_PNPM_RECURSIVE_RUN_NO_SCRIPT` even though the
+        // workspace package exposes the script. The inner pnpm must resolve
+        // the filter against the workspace root, not the parent run context.
+        //
+        // Also strip AI-agent env vars (CLAUDECODE, OPENCODE, …): vitest's
+        // std-env dependency detects them and flips the text reporter into
+        // `skipFull` mode, which hides the `All files` row this test exists
+        // to assert on. CI runners never set these; the strip only matters
+        // when the suite is launched from inside an agent shell.
+        const cleanedEnv: Record<string, string | undefined> = { ...process.env };
+        for (const key of Object.keys(cleanedEnv)) {
+          if (
+            key.startsWith('npm_package_') ||
+            key.startsWith('npm_config_') ||
+            key.startsWith('npm_lifecycle_') ||
+            key === 'INIT_CWD' ||
+            key === 'OPENCODE' ||
+            key === 'CLAUDECODE' ||
+            key === 'CLAUDE_CODE' ||
+            key === 'GEMINI_CLI' ||
+            key === 'CODEX_SANDBOX' ||
+            key === 'CODEX_THREAD_ID' ||
+            key === 'AUGMENT_AGENT' ||
+            key === 'GOOSE_PROVIDER'
+          ) {
+            cleanedEnv[key] = '';
+          }
+        }
+        cleanedEnv[SELF_TEST_FLAG] = '1';
+
+        const result = spawnSync(
+          'pnpm',
+          [
+            '--filter',
+            '@serverless-ircd/aws-stack',
+            'exec',
+            'vitest',
+            'run',
+            '--coverage',
+            // Send the inner run's coverage output to a sibling directory so
+            // it cannot race the outer vitest that spawned us (both would
+            // otherwise write to `./coverage` and the loser crashes with
+            // "Something removed the coverage directory").
+            '--coverage.reportsDirectory=coverage-self-test',
+          ],
+          {
+            encoding: 'utf8',
+            env: cleanedEnv,
+          },
+        );
+
+        // Exit code 0 = no `[ELIFECYCLE]` / early exit. Report the captured
+        // output in the assertion message so a CI failure shows what the
+        // subprocess actually printed instead of a bare status code.
+        if (result.status !== 0) {
+          throw new Error(
+            `coverage command exited with status ${result.status as number | string}\n` +
+              `--- stdout ---\n${result.stdout}\n` +
+              `--- stderr ---\n${result.stderr}`,
+          );
+        }
+
+        const combined = stripAnsi(`${result.stdout}\n${result.stderr}`);
+
+        // The vitest text reporter prefixes its table with this banner; the
+        // `All files` summary row follows. Asserting both makes the test
+        // robust to incidental wording changes elsewhere in the output.
+        expect(combined, 'coverage command must emit the v8 coverage banner').toMatch(
+          /Coverage report from v8/,
+        );
+        expect(combined, 'coverage command must emit an "All files" summary row').toMatch(
+          /All files/,
+        );
+
+        // Belt-and-braces: if the bundle stub ever regresses, the subprocess
+        // would flood `Bundling asset TestStack/IrcHandler/Code/Stage…` once
+        // per Lambda per test (dozens to hundreds of times) and eventually
+        // OOM in CI. With the stub active the count is at most a handful
+        // (only the deliberately-ungated production-path test triggers real
+        // esbuild runs, and it bounds itself to one stack). Assert the count
+        // stays small so a regression fails loudly here instead of looking
+        // like a mysterious `[ELIFECYCLE]` exit on the CI runner.
+        const bundleCount = (combined.match(/Bundling asset/g) ?? []).length;
+        expect(
+          bundleCount,
+          'coverage command must not loop esbuild bundling across the test synth',
+        ).toBeLessThan(10);
+      },
+      COVERAGE_TIMEOUT_MS,
+    );
+  },
+);

package/apps/aws-stack/tests/stack.test.ts

@@ -483,11 +483,11 @@ describe('IrcAwsStack — server identity props (configurable deploy identity)',
     );
   });
 
-  it('applies the default server identity when the props are omitted', () => {
+  it('applies a non-placeholder fallback server identity when the props are omitted', () => {
     const { template } = makeTemplate();
     expect(
       findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
-    ).toBe('irc.example.com');
+    ).toBe('irc.localhost');
     expect(
       findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
     ).toBe('ExampleNet');

package/apps/aws-stack/tests/synth-no-bundle.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Red→green driver for the aws-stack test-mode bundle stub.
+ *
+ * The IrcAwsStack constructs up to four `NodejsFunction` resources. Each
+ * one invokes esbuild at synth time to bundle the Lambda handler entry.
+ * Repeated across the full `apps/aws-stack` test suite, the bundler ran
+ * dozens of times per coverage invocation and exhausted CI memory before
+ * the vitest coverage table could be printed (the failure mode behind
+ * the coverage-command crash).
+ *
+ * Setting `IRC_AWS_STACK_TEST_NO_BUNDLE=1` (done once for the whole
+ * suite by `tests/vitest.setup.ts`) flips the stack onto a stub code
+ * path that emits an inline Lambda zip and skips esbuild entirely,
+ * while preserving every other CloudFormation shape the rest of the
+ * suite asserts on (runtime, env vars, IAM grants, route wiring, …).
+ *
+ * The assertions below lock that stub in place. They fail loudly the
+ * moment a refactor re-routes the stack back to `NodejsFunction` under
+ * test, or drops the env-var guard, so the coverage pipeline cannot
+ * silently regress back into an unbounded esbuild loop.
+ */
+
+import { App } from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { IrcAwsStack } from '../src/aws-stack.js';
+
+/**
+ * Collects every `AWS::Lambda::Function`'s `Code` block from a synthesized
+ * template. Under the stub each Code must be `{ ZipFile: … }` (inline) and
+ * must NOT be `{ S3Bucket: …, S3Key: … }` (the shape CDK emits only after
+ * esbuild has run).
+ */
+function lambdaCodeBlocks(template: Template): Array<Record<string, unknown>> {
+  const fns = template.findResources('AWS::Lambda::Function') as Record<
+    string,
+    { Properties?: { Code?: Record<string, unknown> } }
+  >;
+  return Object.values(fns).map((fn) => fn.Properties?.Code ?? {});
+}
+
+describe('IrcAwsStack — test-mode bundle stub (no esbuild)', () => {
+  it('emits inline (ZipFile) Lambda code for the default wss stack so esbuild is skipped', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack');
+    const template = Template.fromStack(stack);
+    const codes = lambdaCodeBlocks(template);
+    // handler + sweeper + pingChecker.
+    expect(codes).toHaveLength(3);
+    for (const code of codes) {
+      expect(code).toHaveProperty('ZipFile');
+      expect(code).not.toHaveProperty('S3Bucket');
+      expect(code).not.toHaveProperty('S3Key');
+    }
+  });
+
+  it('emits inline (ZipFile) Lambda code for the NLB streaming handler when tcpTlsDomainName is set', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      environmentName: 'staging',
+      tcpTlsDomainName: 'irc.example.com',
+    });
+    const template = Template.fromStack(stack);
+    const codes = lambdaCodeBlocks(template);
+    // handler + sweeper + pingChecker + nlbHandler.
+    expect(codes).toHaveLength(4);
+    for (const code of codes) {
+      expect(code).toHaveProperty('ZipFile');
+      expect(code).not.toHaveProperty('S3Bucket');
+    }
+  });
+
+  it('preserves the Node 24 runtime on every stubbed Lambda', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      tcpTlsDomainName: 'irc.example.com',
+    });
+    const template = Template.fromStack(stack);
+    template.allResourcesProperties('AWS::Lambda::Function', {
+      Runtime: 'nodejs24.x',
+    });
+  });
+});
+
+/**
+ * Production-path coverage. The stub above is the test-only fast path; the
+ * `NodejsFunction` branch in `makeLambda` is what every real `cdk synth`
+ * takes. Exercising it once here covers the otherwise-unreached return and
+ * asserts the production Code shape (`S3Bucket` / asset-backed) so a
+ * refactor that accidentally drops the production path fails loudly.
+ *
+ * Bounded to a single synth (one stack, no `tcpTlsDomainName`) so esbuild
+ * runs at most three times — enough to cover the branch without
+ * re-introducing the unbounded bundling loop the stub exists to dodge.
+ */
+describe('IrcAwsStack — production bundling path (no stub)', () => {
+  let savedFlag: string | undefined;
+
+  beforeEach(() => {
+    savedFlag = process.env.IRC_AWS_STACK_TEST_NO_BUNDLE;
+    process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = '';
+  });
+
+  afterEach(() => {
+    if (savedFlag !== undefined) {
+      process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = savedFlag;
+    } else {
+      process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = '';
+    }
+  });
+
+  it('uses NodejsFunction (S3-bundled asset) when the stub env var is unset', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack');
+    const template = Template.fromStack(stack);
+    const fns = template.findResources('AWS::Lambda::Function') as Record<
+      string,
+      { Properties?: { Code?: Record<string, unknown> } }
+    >;
+    const codes = Object.values(fns).map((fn) => fn.Properties?.Code ?? {});
+    expect(codes).toHaveLength(3);
+    for (const code of codes) {
+      // Production synth emits an S3-backed asset (esbuild ran). No
+      // `ZipFile` should appear on any production Lambda.
+      expect(code).toHaveProperty('S3Bucket');
+      expect(code).not.toHaveProperty('ZipFile');
+    }
+  });
+});

package/apps/aws-stack/tests/vitest.setup.ts

@@ -0,0 +1,18 @@
+/**
+ * Vitest setup for the aws-stack test suite.
+ *
+ * Runs once per test file before any test body executes. Sets the flag
+ * consumed by `makeLambda()` in `src/aws-stack.ts` to route every Lambda
+ * construct onto the inline-zip stub, so synthesizing the stack under
+ * test does NOT invoke esbuild. Without this, the ~80 stack-related
+ * tests each triggered one esbuild bundle per Lambda (4 functions × 80
+ * synths = 320+ bundles per coverage run), which exhausted CI memory
+ * before the vitest coverage table could print.
+ *
+ * The stub preserves every CloudFormation shape the rest of the suite
+ * asserts on (runtime, env vars, IAM grants, route wiring, …) while
+ * making the bundling step a no-op. Production synth (`bin/aws.ts`) is
+ * driven by `cdk synth` / the CDK CLI, never via vitest, so it cannot
+ * accidentally inherit this env var.
+ */
+process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = '1';

package/apps/aws-stack/vitest.config.ts

@@ -4,6 +4,9 @@ export default defineConfig({
   test: {
     include: ['tests/**/*.test.ts'],
     exclude: ['cdk.out/**', 'dist/**', 'node_modules/**'],
+    setupFiles: ['./tests/vitest.setup.ts'],
+    testTimeout: 60_000,
+    fileParallelism: false,
     coverage: {
       provider: 'v8',
       all: false,

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

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.5.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-tcp-container/src/config-loader.ts

@@ -58,14 +58,13 @@ const DEFAULT_TCP_PORT = 6667;
 const DEFAULT_TCP_HOST = '0.0.0.0';
 const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
 
-/** Default server name / network when env vars are missing. */
-const DEFAULT_SERVER_NAME = 'irc.example.com';
-const DEFAULT_NETWORK_NAME = 'ExampleNet';
-
 /**
  * Loads and validates the IRC server config plus container-specific knobs
  * from a platform env. Throws on an invalid IRC config (bad port number,
- * missing required fields, etc.) so boot fails fast.
+ * missing required fields, etc.) so boot fails fast. `SERVER_NAME` and
+ * `NETWORK_NAME` are required — omitting them produces a readable error
+ * pointing at the missing knob rather than silently advertising a
+ * placeholder identity.
  */
 export function loadContainerConfig(env: ContainerConfigEnv): ContainerConfig {
   const server = parseServerConfig(buildServerInput(env));
@@ -89,8 +88,8 @@ function parseIntOrDefault(raw: string | undefined, def: number): number {
 
 function buildServerInput(env: ContainerConfigEnv): Record<string, unknown> {
   const input: Record<string, unknown> = {
-    serverName: env.SERVER_NAME ?? DEFAULT_SERVER_NAME,
-    networkName: env.NETWORK_NAME ?? DEFAULT_NETWORK_NAME,
+    serverName: env.SERVER_NAME,
+    networkName: env.NETWORK_NAME,
   };
   if (env.SERVER_VERSION !== undefined) input.serverVersion = env.SERVER_VERSION;
   if (env.CREATED_AT !== undefined) input.createdAt = parseCreatedAt(env.CREATED_AT);

package/apps/cf-tcp-container/src/container-server.ts

@@ -286,6 +286,9 @@ function attachConnection(
     history,
     logger,
     transport: new TcpByteStreamTransport(),
+    // Spectrum terminates TLS at the edge before forwarding plaintext TCP
+    // to this origin, so every connection is secure → user mode `S`.
+    secure: true,
   });
 
   runtime.registerConnection(

package/apps/cf-tcp-container/tests/config-loader.test.ts

@@ -40,9 +40,16 @@ describe('config-loader — IRC server config', () => {
     ]);
   });
 
-  it('applies schema default serverName when unset', () => {
-    const cfg = loadContainerConfig({ NETWORK_NAME: 'TestNet' } as ContainerConfigEnv);
-    expect(cfg.server.serverName).toBe('irc.example.com');
+  it('throws a readable error naming serverName when SERVER_NAME is unset', () => {
+    expect(() =>
+      loadContainerConfig({ NETWORK_NAME: 'TestNet' } as ContainerConfigEnv),
+    ).toThrowError(/serverName/u);
+  });
+
+  it('throws a readable error naming networkName when NETWORK_NAME is unset', () => {
+    expect(() =>
+      loadContainerConfig({ SERVER_NAME: 'irc.test' } as ContainerConfigEnv),
+    ).toThrowError(/networkName/u);
   });
 });
 

package/apps/cf-tcp-container/wrangler.toml

@@ -47,7 +47,7 @@ new_sqlite_classes = ["IrcTcpOrigin"]
 
 # --- Environment ---
 [vars]
-SERVER_NAME = "irc.example.com"
+SERVER_NAME = "irc.your-domain.invalid"
 NETWORK_NAME = "ExampleNet"
 MOTD_LINES = "Welcome to the ServerlessIRCd TCP origin."
 TCP_PORT = "6667"

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",
@@ -27,6 +27,7 @@
     "@cloudflare/vitest-pool-workers": "0.18.6",
     "@cloudflare/workers-types": "^5.20260714.1",
     "@types/ws": "^8.5.13",
+    "@vitest/coverage-istanbul": "^4.1.0",
     "@vitest/coverage-v8": "^4.1.0",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",

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';
+}

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);
   },
 };