serverless-ircd 0.10.0 → 0.11.0

package/apps/cf-tcp-container/tests/dockerfile.test.ts

@@ -0,0 +1,110 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Static assertions on the container image's runtime hardening.
+ *
+ * The IRC stack (parser + actor + transport) processes untrusted input,
+ * so the runtime process must never be UID 0. Docker is not available in
+ * every environment (including the CI runner image), so the Dockerfile is
+ * verified statically here; a live `docker run … id -u` smoke runs in CI
+ * wherever a docker daemon is available.
+ */
+
+const DOCKERFILE_URL = new URL('../Dockerfile', import.meta.url);
+
+/** Non-comment, non-empty Dockerfile lines of the runtime stage. */
+function runtimeStageLines(content: string): string[] {
+  const stageStart = content.indexOf('AS runtime');
+  expect(stageStart, 'Dockerfile must define an `AS runtime` stage').toBeGreaterThan(0);
+  return content
+    .slice(stageStart)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'));
+}
+
+async function readRuntimeLines(): Promise<string[]> {
+  return runtimeStageLines(await readFile(DOCKERFILE_URL, 'utf8'));
+}
+
+describe('Dockerfile — non-root runtime hardening', () => {
+  it('runs the runtime stage as USER node before CMD', async () => {
+    const lines = await readRuntimeLines();
+    const userIndex = lines.findIndex((l) => /^USER\s+node\b/.test(l));
+    const cmdIndex = lines.findIndex((l) => /^CMD\b/.test(l));
+    expect(userIndex, 'runtime stage must declare USER node').toBeGreaterThan(-1);
+    expect(cmdIndex, 'runtime stage must declare CMD').toBeGreaterThan(-1);
+    expect(userIndex).toBeLessThan(cmdIndex);
+  });
+
+  it('never escalates back to root after dropping privileges', async () => {
+    const lines = await readRuntimeLines();
+    const userIndex = lines.findIndex((l) => /^USER\s+node\b/.test(l));
+    expect(userIndex).toBeGreaterThan(-1);
+    const after = lines.slice(userIndex + 1);
+    expect(
+      after.filter((l) => /^USER\s+(root|0)\b/.test(l)),
+      'no USER root may follow USER node',
+    ).toHaveLength(0);
+  });
+
+  it('chowns /data to node:node while still root (before USER node)', async () => {
+    const lines = await readRuntimeLines();
+    const chownIndex = lines.findIndex((l) => /chown\s+(-R\s+)?node:node\s+.*\/data/.test(l));
+    const userIndex = lines.findIndex((l) => /^USER\s+node\b/.test(l));
+    expect(chownIndex, 'runtime stage must chown node:node /data').toBeGreaterThan(-1);
+    expect(userIndex).toBeGreaterThan(-1);
+    // chown requires root: it must happen before privileges are dropped.
+    expect(chownIndex).toBeLessThan(userIndex);
+  });
+
+  it('creates the /data volume directory it chowns', async () => {
+    const content = await readFile(DOCKERFILE_URL, 'utf8');
+    expect(content).toMatch(/mkdir\s+-p\s+\/data/);
+    expect(content).toMatch(/VOLUME\s+\["\/data"\]/);
+  });
+
+  it('documents that cert mounts must stay readable by UID 1000', async () => {
+    const content = await readFile(DOCKERFILE_URL, 'utf8');
+    // Group consecutive `#` lines into blocks so multi-line comments count.
+    const blocks: string[] = [];
+    for (const line of content.split('\n')) {
+      if (line.trim().startsWith('#')) {
+        if (blocks.length === 0) blocks.push(line);
+        else blocks[blocks.length - 1] += `\n${line}`;
+      } else {
+        blocks.push('');
+      }
+    }
+    const certBlocks = blocks.filter((b) => /cert/i.test(b));
+    expect(certBlocks.length, 'Dockerfile must mention certs').toBeGreaterThan(0);
+    expect(
+      certBlocks.some((b) => /UID\s*1000/i.test(b)),
+      'a cert comment must require UID-1000 readability',
+    ).toBe(true);
+  });
+});
+
+describe('Dockerfile — TLS-at-origin image defaults', () => {
+  it('exposes the TLS port 6697', async () => {
+    const content = await readFile(DOCKERFILE_URL, 'utf8');
+    expect(content).toMatch(/^EXPOSE\s+6697\b/m);
+  });
+
+  it('does not expose the plaintext port 6667 (debug-localhost only, never routed)', async () => {
+    const content = await readFile(DOCKERFILE_URL, 'utf8');
+    expect(content).not.toMatch(/^EXPOSE\s+6667\b/m);
+  });
+
+  it('defaults TLS_CERT_PATH / TLS_KEY_PATH to the documented /data/certs mount', async () => {
+    const content = await readFile(DOCKERFILE_URL, 'utf8');
+    expect(content).toMatch(/^ENV\s+TLS_CERT_PATH=\/data\/certs\//m);
+    expect(content).toMatch(/^ENV\s+TLS_KEY_PATH=\/data\/certs\//m);
+  });
+
+  it('classifies the image as production so the no-TLS boot guard applies', async () => {
+    const content = await readFile(DOCKERFILE_URL, 'utf8');
+    expect(content).toMatch(/^ENV\s+NODE_ENV=production\b/m);
+  });
+});

package/apps/cf-tcp-container/tests/proxy-protocol.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest';
+import { consumeProxyV1Header } from '../src/proxy-protocol.js';
+
+/**
+ * PROXY protocol v1 header parsing (the line Cloudflare Spectrum prepends
+ * to every forwarded TCP flow when `proxy_protocol = "v1"`).
+ *
+ * The header is a single ASCII line:
+ *   PROXY TCP4 <src_ip> <dst_ip> <src_port> <dst_port>\r\n
+ * and may arrive split across TCP chunks, so `consumeProxyV1Header` is
+ * incremental: it reports `incomplete` until the trailing CRLF is seen.
+ */
+describe('proxy-protocol — consumeProxyV1Header', () => {
+  it('parses a complete TCP4 header and returns the source IP', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 40001 6697\r\n', 'ascii'),
+    );
+    expect(result).toEqual({
+      status: 'complete',
+      sourceIp: '203.0.113.7',
+      remainder: Buffer.alloc(0),
+    });
+  });
+
+  it('returns the bytes after the header as the remainder', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 40001 6697\r\nNICK alice\r\n', 'ascii'),
+    );
+    expect(result.status).toBe('complete');
+    if (result.status === 'complete') {
+      expect(result.remainder.toString('ascii')).toBe('NICK alice\r\n');
+    }
+  });
+
+  it('parses a complete TCP6 header', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP6 2001:db8::1 2001:db8::2 40002 6697\r\n', 'ascii'),
+    );
+    expect(result).toEqual({
+      status: 'complete',
+      sourceIp: '2001:db8::1',
+      remainder: Buffer.alloc(0),
+    });
+  });
+
+  it('accepts boundary ports 0 and 65535', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 0 65535\r\n', 'ascii'),
+    );
+    expect(result.status).toBe('complete');
+  });
+
+  it('accepts a maximal-length valid TCP6 header (104 bytes incl. CRLF)', () => {
+    const v6 = '0000:0000:0000:0000:0000:0000:0000:0000'; // 39 chars
+    const line = `PROXY TCP6 ${v6} ${v6} 65535 65535\r\n`;
+    expect(line.length).toBe(104);
+    const result = consumeProxyV1Header(Buffer.from(line, 'ascii'));
+    expect(result.status).toBe('complete');
+  });
+
+  it('reports incomplete for an empty buffer', () => {
+    expect(consumeProxyV1Header(Buffer.alloc(0))).toEqual({ status: 'incomplete' });
+  });
+
+  it('reports incomplete for a plausible partial header without CRLF', () => {
+    expect(consumeProxyV1Header(Buffer.from('PROXY TCP4 203.0.11', 'ascii'))).toEqual({
+      status: 'incomplete',
+    });
+  });
+
+  it('reassembles a header split across two buffers (caller-concatenated)', () => {
+    const part1 = Buffer.from('PROXY TCP6 2001:db8:', 'ascii');
+    const part2 = Buffer.from(':42 2001:db8::2 40003 6697\r\n', 'ascii');
+    const result = consumeProxyV1Header(Buffer.concat([part1, part2]));
+    expect(result).toEqual({
+      status: 'complete',
+      sourceIp: '2001:db8::42',
+      remainder: Buffer.alloc(0),
+    });
+  });
+
+  it('rejects a buffer that exceeds the max header length with no CRLF', () => {
+    const result = consumeProxyV1Header(Buffer.from(`PROXY ${'a'.repeat(200)}`, 'ascii'));
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a short non-PROXY prefix (direct IRC client, no CRLF yet)', () => {
+    expect(consumeProxyV1Header(Buffer.from('NICK', 'ascii'))).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a long non-PROXY prefix with no CRLF', () => {
+    expect(consumeProxyV1Header(Buffer.from('NOTAPROXYLINE lorem ipsum dolor', 'ascii'))).toEqual({
+      status: 'invalid',
+    });
+  });
+
+  it('rejects a CRLF-terminated line that is not a PROXY header', () => {
+    // The direct-connection case: an IRC client speaks IRC immediately.
+    const result = consumeProxyV1Header(Buffer.from('NICK direct\r\nUSER direct 0 * :d\r\n'));
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a CRLF-terminated header longer than the 107-byte maximum', () => {
+    const line = `PROXY UNKNOWN ${'x'.repeat(93)}`; // 107 chars + CRLF = 109 bytes
+    const result = consumeProxyV1Header(Buffer.from(`${line}\r\n`, 'ascii'));
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects the UNKNOWN family', () => {
+    const result = consumeProxyV1Header(Buffer.from('PROXY UNKNOWN\r\n', 'ascii'));
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a six-token UNKNOWN header (family check, not token count)', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY UNKNOWN 1.2.3.4 5.6.7.8 1234 5678\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a TCP4 header carrying an IPv6 source address', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 2001:db8::1 198.51.100.2 40004 6697\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a TCP6 header carrying an IPv4 source address', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP6 203.0.113.7 2001:db8::2 40005 6697\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a non-numeric source port', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 abc 6697\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a destination port above 65535', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 40006 99999\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a header with a missing token', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 40007\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a signature-only line (family slot empty)', () => {
+    expect(consumeProxyV1Header(Buffer.from('PROXY\r\n', 'ascii'))).toEqual({
+      status: 'invalid',
+    });
+  });
+
+  it('rejects a three-token header (destination address missing)', () => {
+    expect(consumeProxyV1Header(Buffer.from('PROXY TCP4 203.0.113.7\r\n', 'ascii'))).toEqual({
+      status: 'invalid',
+    });
+  });
+
+  it('rejects a four-token header (source port missing)', () => {
+    expect(
+      consumeProxyV1Header(Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2\r\n', 'ascii')),
+    ).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a header with an extra token', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('PROXY TCP4 203.0.113.7 198.51.100.2 40008 6697 extra\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+
+  it('rejects a lowercase signature (the protocol is case-sensitive)', () => {
+    const result = consumeProxyV1Header(
+      Buffer.from('proxy tcp4 203.0.113.7 198.51.100.2 40009 6697\r\n', 'ascii'),
+    );
+    expect(result).toEqual({ status: 'invalid' });
+  });
+});

package/apps/cf-tcp-container/tests/spectrum-terraform.test.ts

@@ -0,0 +1,135 @@
+import { execFile } from 'node:child_process';
+import { copyFile, mkdir, mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Static→plan assertions on the Spectrum terraform config.
+ *
+ * `terraform` + network access to the provider registry are not guaranteed
+ * on every runner, so the suite skips when the binary is missing. When
+ * present, the config is initialized in a scratch dir and the decoded
+ * plan is asserted — this is the authoritative seam for the
+ * `tls_mode` default (end-to-end TLS, not edge-terminated).
+ */
+
+const TERRAFORM_DIR_URL = new URL('../terraform', import.meta.url);
+
+/** Wall-clock budget for one terraform invocation (provider download included). */
+const TF_CMD_TIMEOUT_MS = 120_000;
+
+const hasTerraform = await (async () => {
+  try {
+    await execFileAsync('terraform', ['version'], { timeout: 15_000 });
+    return true;
+  } catch {
+    return false;
+  }
+})();
+
+interface PlannedResource {
+  address: string;
+  values: Record<string, unknown>;
+}
+
+async function runTerraform(cwd: string, args: string[], envExtra: Record<string, string>) {
+  return execFileAsync('terraform', args, {
+    cwd,
+    timeout: TF_CMD_TIMEOUT_MS,
+    env: { ...process.env, ...envExtra },
+  });
+}
+
+/** Decoded planned values of the spectrum application resource. */
+async function planSpectrumApp(): Promise<PlannedResource> {
+  const work = await mkdtemp(join(tmpdir(), 'sirc-tf-plan-'));
+  try {
+    const files = (await readdir(TERRAFORM_DIR_URL)).filter((f) => f.endsWith('.tf'));
+    for (const f of files) {
+      await copyFile(join(TERRAFORM_DIR_URL.pathname, f), join(work, f));
+    }
+    // Shared provider cache so the (large) cloudflare provider is only
+    // downloaded once per machine, not once per test run.
+    const pluginCache = join(tmpdir(), 'sirc-tf-plugin-cache');
+    await mkdir(pluginCache, { recursive: true });
+
+    // The plan is computed from configuration only (`-refresh=false`, no
+    // state, dummy token): the provider never contacts the Cloudflare API.
+    const env = {
+      TF_PLUGIN_CACHE_DIR: pluginCache,
+      CLOUDFLARE_API_TOKEN: 'dummy-token-plan-only',
+    };
+    await runTerraform(work, ['init', '-backend=false', '-input=false', '-no-color'], env);
+    await runTerraform(
+      work,
+      [
+        'plan',
+        '-input=false',
+        '-no-color',
+        '-refresh=false',
+        '-var',
+        'zone_id=0123456789abcdef',
+        '-var',
+        'origin_address=origin.example.com',
+        '-out=plan.tfplan',
+      ],
+      env,
+    );
+    const { stdout } = await runTerraform(work, ['show', '-json', 'plan.tfplan'], env);
+    const plan = JSON.parse(stdout) as {
+      planned_values?: { root_module?: { resources?: PlannedResource[] } };
+    };
+    const resources = plan.planned_values?.root_module?.resources ?? [];
+    const app = resources.find((r) => r.address === 'cloudflare_spectrum_application.irc_tls');
+    if (app === undefined) {
+      throw new Error(
+        `spectrum application resource missing from plan; got: ${JSON.stringify(resources.map((r) => r.address))}`,
+      );
+    }
+    return app;
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+describe.skipIf(!hasTerraform)('spectrum.tf — decoded terraform plan', () => {
+  let app: PlannedResource;
+
+  beforeAll(async () => {
+    app = await planSpectrumApp();
+  }, 180_000);
+
+  it('defaults the spectrum application to end-to-end TLS (tls = "full")', () => {
+    expect(app.values.tls).toBe('full');
+  });
+
+  it('defaults origin_port to the origin TLS listener (6697)', () => {
+    expect(app.values.origin_port).toBe(6697);
+  });
+
+  it('still forwards the real client IP via PROXY protocol v1', () => {
+    expect(app.values.proxy_protocol).toBe('v1');
+  });
+
+  it('still exposes the public TLS port 6697', () => {
+    expect(app.values.protocol).toBe('tcp/6697');
+  });
+
+  it('pins the accepted TLS versions to 1.2 and 1.3 (no legacy fallback)', () => {
+    // Spectrum TCP apps cannot pin per-app TLS versions: the Cloudflare
+    // API and this provider expose no `tls_versions` field (an explicit
+    // `tls_versions = [...]` fails `terraform plan` with "Unsupported
+    // argument"), and the edge floor is fixed at TLS 1.1 (SSLv3 / TLS 1.0
+    // are never negotiable). The 1.2/1.3 pin is therefore enforced at the
+    // origin listener (`minVersion`/`maxVersion` in container-server.ts,
+    // covered by tests/container-server-tls.test.ts). This assertion is
+    // the tripwire: the day the provider gains `tls_versions`, the
+    // planned values carry the (null) key, this test fails, and the pin
+    // must move onto the Spectrum app itself.
+    expect(app.values.tls_versions).toBeUndefined();
+  });
+});

package/apps/cf-tcp-container/tests/tls-e2e.test.ts

@@ -163,6 +163,10 @@ function startTlsProxy(opts: {
     const server = tlsCreateServer({ key: opts.key, cert: opts.cert }, (tlsSocket) => {
       const origin = createConnection({ host: opts.originHost, port: opts.originPort });
       originSockets.add(origin);
+      // Spectrum with `proxy_protocol = "v1"` prepends a PROXY header to
+      // every forwarded flow carrying the real client IP; the analogue
+      // does the same when the origin connection is established.
+      origin.write('PROXY TCP4 127.0.0.1 192.0.2.1 40000 6697\r\n');
       tlsSocket.pipe(origin);
       origin.pipe(tlsSocket);
       const cleanup = (): void => {
@@ -222,7 +226,7 @@ describe('container-server — TLS e2e via in-process proxy (Spectrum analogue)'
       key: cert.key,
       cert: cert.cert,
       originHost: '127.0.0.1',
-      originPort: origin.port,
+      originPort: origin.port as number,
     });
   }, 30_000);
 

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

@@ -3,14 +3,19 @@
 ## Cloudflare Containers config for the ServerlessIRCd TCP origin.
 ##
 ## Deploys the IRC TCP container (apps/cf-tcp-container) to the Cloudflare
-## Containers platform. The container listens on port 6667 (plaintext TCP);
-## Cloudflare Spectrum (configured separately in terraform/spectrum.tf)
-## terminates TLS on :6697 and forwards plaintext to this container.
+## Containers platform. The container terminates TLS itself on :6697
+## (TLS_CERT_PATH / TLS_KEY_PATH below); Cloudflare Spectrum (configured
+## separately in terraform/spectrum.tf) runs in tls_mode = "full" and
+## re-encrypts edge→origin. Plaintext :6667 is debug-only
+## (DEBUG_PLAINTEXT=localhost binds 127.0.0.1; forbidden in prod).
 ##
 ## Prerequisites:
 ##   - Cloudflare account with Containers beta access.
 ##   - wrangler v4.112+ (`pnpm add -g wrangler`).
 ##   - The container image is built from apps/cf-tcp-container/Dockerfile.
+##   - A PEM cert/key pair mounted at /data/certs/ (see docs/
+##     Cloudflare-TCP-Deployment.md for Let's Encrypt / BYO /
+##     Cloudflare Origin Cert options).
 ##
 ## Deploy:
 ##   wrangler deploy
@@ -25,7 +30,7 @@ compatibility_flags = ["nodejs_compat"]
 enabled = true
 
 # --- Container definition ---
-# The IRC TCP origin container. Listens on port 6667; the Worker below is a
+# The IRC TCP origin container. Serves TLS on :6697; the Worker below is a
 # thin management/health-check wrapper (Spectrum routes TCP directly to the
 # container origin, not through the Worker).
 [[containers]]
@@ -50,5 +55,13 @@ new_sqlite_classes = ["IrcTcpOrigin"]
 SERVER_NAME = "irc.your-domain.invalid"
 NETWORK_NAME = "ExampleNet"
 MOTD_LINES = "Welcome to the ServerlessIRCd TCP origin."
+# TLS listener: the origin terminates TLS (Spectrum tls_mode = "full").
+# Paths point at the documented /data/certs mount; files must be
+# readable by UID 1000 (node).
+TLS_CERT_PATH = "/data/certs/tls.pem"
+TLS_KEY_PATH = "/data/certs/tls.key"
+# Plaintext debug listener knobs — inert unless DEBUG_PLAINTEXT=localhost
+# is set (localhost-only; rejected when NODE_ENV=production, which the
+# Dockerfile sets by default).
 TCP_PORT = "6667"
 PERSISTENCE_PATH = "/data/state.json"

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",
@@ -13,7 +13,7 @@
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "dev": "wrangler dev",
-    "deploy": "wrangler deploy",
+    "deploy": "node ../../tools/ci-hardening/dist/cf-deploy-cli.js wrangler.toml",
     "smoke": "node scripts/smoke.mjs",
     "clean": "rimraf dist coverage .tsbuildinfo .turbo"
   },

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

@@ -31,17 +31,24 @@
  */
 
 import {
+  COUNTER_INSTANCE_NAME,
   ChannelDO,
   ChannelRegistryDO,
   ConnectionDO,
+  CounterDO,
+  type CounterRpc,
   type Env,
+  RATE_LIMIT_INSTANCE_NAME,
+  RateLimitDO,
+  type RateLimitRpc,
   RegistryDO,
+  loadServerConfigFromCfEnv,
 } 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`.
-export { ChannelDO, ChannelRegistryDO, ConnectionDO, RegistryDO };
+export { ChannelDO, ChannelRegistryDO, ConnectionDO, CounterDO, RateLimitDO, RegistryDO };
 export type { Env };
 
 /**
@@ -99,12 +106,33 @@ const ORIGIN_DENIED_BODY = 'WebSocket upgrade refused: the request Origin is not
 const ORIGIN_UNCONFIGURED_BODY =
   'WebSocket upgrades refused: could not determine the request origin and WEB_ORIGINS is not configured.';
 
+/**
+ * Body of the HTTP 429 admission rejection, delivered once the global
+ * live-connection counter (`maxClients` cap) is full. Carries the IRC
+ * `ERROR :Closing link` line so non-browser clients (the
+ * tcp-ws-forwarder, curl) surface a readable reason: pre-handshake there
+ * is no WebSocket, so the body is the only channel available ("delivered
+ * where possible"). 429 — not 403 — marks this as back-pressure: the
+ * client is welcome to retry once a slot frees.
+ */
+const SERVER_FULL_BODY = 'ERROR :Closing link: server full';
+
+/**
+ * Body of the HTTP 429 rejection for an IP over its `perIpConnectionRate`
+ * budget. Same conventions as {@link SERVER_FULL_BODY}: the IRC ERROR
+ * line rides in the body, and 429 marks back-pressure — the client is
+ * welcome to retry once the sliding window decays.
+ */
+const RATE_EXCEEDED_BODY = 'ERROR :Closing link: connection rate exceeded';
+
 /**
  * Default edge handler.
  *
  * Routing order:
- *   1. WebSocket upgrade → CSWSH `Origin` check, then per-connection
- *      `ConnectionDO`.
+ *   1. WebSocket upgrade → CSWSH `Origin` check → per-IP upgrade rate
+ *      check (`perIpConnectionRate` via the RateLimitDO; 429 when over
+ *      budget) → `maxClients` admission check (global live-connection
+ *      counter; 429 when full), then per-connection `ConnectionDO`.
  *   2. `GET /health` → plaintext liveness response.
  *   3. everything else → `env.ASSETS` (Kiwi SPA at `/webclient/`, landing at `/`).
  *
@@ -128,9 +156,53 @@ export default {
           headers: { 'content-type': 'text/plain; charset=utf-8' },
         });
       }
+      const config = loadServerConfigFromCfEnv(env);
+      // Per-IP upgrade rate check: budget how fast one source IP may
+      // drive connection setup (credential brute-force needs exactly
+      // that setup rate). Keyed by CF-Connecting-IP, which the
+      // Cloudflare edge stamps on every request — without it there is
+      // no key to budget on, so the check is skipped (production
+      // traffic always enters via the edge). Runs BEFORE the global
+      // counter so a flooding IP never consumes `maxClients` slots.
+      const clientIp = request.headers.get('CF-Connecting-IP');
+      if (clientIp !== null) {
+        const limiter = env.RATE_LIMIT_DO.get(
+          env.RATE_LIMIT_DO.idFromName(RATE_LIMIT_INSTANCE_NAME),
+        );
+        const verdict = await (limiter as unknown as RateLimitRpc).check(
+          clientIp,
+          config.perIpConnectionRate.max,
+          config.perIpConnectionRate.windowMs,
+        );
+        if (!verdict.allowed) {
+          return new Response(RATE_EXCEEDED_BODY, {
+            status: 429,
+            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);
+      const doId = env.CONNECTION_DO.idFromName(connId);
+      // Admission cap: reserve a slot in the global live-connection
+      // counter before the upgrade is forwarded. The CounterDO entry is
+      // keyed by the ConnectionDO hex id (`doId.toString()` — exactly
+      // what the DO itself computes from `ctx.id` on its teardown
+      // paths), so the slot is released under the same key when the
+      // connection closes without threading the id through the request.
+      // Concurrent upgrades are linearised by the counter DO's
+      // serialized event loop, so the cap holds under races. A DO that
+      // dies without a close event is reconciled by the counter's lazy
+      // TTL reap (its PING-alarm heartbeats stop), so slots self-heal.
+      const maxClients = config.maxClients;
+      const counter = env.COUNTER_DO.get(env.COUNTER_DO.idFromName(COUNTER_INSTANCE_NAME));
+      const admission = await (counter as unknown as CounterRpc).admit(doId.toString(), maxClients);
+      if (!admission.admitted) {
+        return new Response(SERVER_FULL_BODY, {
+          status: 429,
+          headers: { 'content-type': 'text/plain; charset=utf-8' },
+        });
+      }
+      const stub = env.CONNECTION_DO.get(doId);
       return stub.fetch(request);
     }
     const url = new URL(request.url);

package/apps/cf-worker/tests/raw-modules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient declaration so `?raw` imports (Vite's built-in transform that
+ * inlines a file's text at bundle time) typecheck under the strict
+ * `tsconfig.test.json`. Mirrors the declaration used by the irc-server and
+ * cf-adapter test suites for their source-level regression guards.
+ */
+declare module '*?raw' {
+  const content: string;
+  // eslint-disable-next-line import/no-default-export
+  export default content;
+}

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

@@ -27,6 +27,10 @@ declare global {
       REGISTRY_DO: DurableObjectNamespace;
       CHANNEL_DO: DurableObjectNamespace;
       CHANNEL_REGISTRY_DO: DurableObjectNamespace;
+      // Global live-connection admission counter (maxClients cap).
+      COUNTER_DO: DurableObjectNamespace;
+      // Per-IP upgrade rate limiter (perIpConnectionRate budget).
+      RATE_LIMIT_DO: DurableObjectNamespace;
       SERVER_NAME: string;
       NETWORK_NAME: string;
       MOTD_LINES: string;