serverless-ircd 0.9.0 → 0.11.0

package/apps/cf-worker/tests/wrangler-config.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Guards on the production `apps/cf-worker/wrangler.toml`.
+ *
+ * The `[observability]` block controls how much of the worker's console
+ * output (every structured log record the ConnectionActor emits) is
+ * retained by Workers Analytics / `wrangler tail` / Logpush. Full-rate
+ * sampling is unnecessary for triage — every record is scrubbed to
+ * non-sensitive fields — and multiplies the volume of client-adjacent
+ * data retained, so the default is capped. This test pins the cap so a
+ * casual edit cannot silently restore 100% sampling.
+ */
+
+import { describe, expect, it } from 'vitest';
+import wranglerToml from '../wrangler.toml?raw';
+
+/**
+ * Extracts the raw right-hand side of `key = value` from a top-level
+ * `[section]` table of the production wrangler config. Walks lines and
+ * switches tables on whole-line headers only (so a comment that merely
+ * mentions `[observability]` cannot confuse the parse). Returns
+ * `undefined` when either the table or the binding is absent so
+ * missing-value regressions fail loudly.
+ */
+function tableBinding(section: string, key: string): string | undefined {
+  let inSection = false;
+  for (const line of wranglerToml.split('\n')) {
+    const header = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (header !== null) {
+      inSection = header[1] === section;
+      continue;
+    }
+    if (!inSection) continue;
+    const binding = line.match(new RegExp(`^\\s*${key}\\s*=\\s*(.+?)\\s*(?:#.*)?$`));
+    if (binding !== null) return binding[1];
+  }
+  return undefined;
+}
+
+describe('wrangler.toml observability', () => {
+  it('defaults head sampling to a reduced rate instead of 100%', () => {
+    expect(tableBinding('observability', 'head_sampling_rate')).toBe('0.1');
+  });
+
+  it('keeps observability enabled (records must still reach the pipeline)', () => {
+    expect(tableBinding('observability', 'enabled')).toBe('true');
+  });
+});

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

@@ -0,0 +1,112 @@
+/**
+ * Worker-edge admission cap (`maxClients`) integration tests.
+ *
+ * TDD outline:
+ *   "Red: maxClients = 1; a second upgrade is admitted today; assert it
+ *    receives 429 (with the `ERROR :Closing link: server full` body).
+ *    Green: CounterDO admission check at the edge."
+ *
+ * Drives the production worker entry (`src/worker.ts`) end-to-end through
+ * `worker.fetch` exactly like `ws-origin.test.ts`: the admission check,
+ * the 429 + ERROR-line rejection, and the slot lifecycle (release on
+ * close → re-admit) are asserted at the HTTP boundary, with the real
+ * CounterDO + ConnectionDO behind the bindings.
+ *
+ * `MAX_CLIENTS` is not set in `wrangler.test.toml` (schema default
+ * 10 000); cap-pinned tests override it per call via `{ ...env,
+ * MAX_CLIENTS: '1' }`, the same per-test env-override pattern the
+ * origin suite uses for `WEB_ORIGINS`.
+ */
+
+import { env, reset } from 'cloudflare:test';
+import { afterEach, describe, expect, it } from 'vitest';
+import worker from '../src/worker';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      WEB_ORIGINS: string;
+      /** Optional admission cap (parsed by the shared config loader). */
+      MAX_CLIENTS?: string;
+    }
+  }
+}
+
+const UPGRADE_URL = 'https://irc.example.com/';
+
+function upgradeRequest(): Request {
+  // No Origin header — non-browser client, so the CSWSH policy passes
+  // regardless of the WEB_ORIGINS value in the test vars.
+  return new Request(UPGRADE_URL, { headers: { Upgrade: 'websocket' } });
+}
+
+/** Env with the global admission cap pinned to a single client. */
+const capOne = { ...env, MAX_CLIENTS: '1' };
+
+// DO storage persists across tests in the same file; reset between each
+// so admission entries (and any half-closed connections) from one test
+// never leak into the next.
+afterEach(async () => {
+  await reset();
+});
+
+/**
+ * Polls upgrade attempts until one is admitted (101). The ConnectionDO
+ * teardown after a client-side close is event-driven and can lag in the
+ * test runtime, so the re-admit assertion polls instead of assuming
+ * synchrony. Every rejected attempt is a pure 429 (no socket, no state).
+ */
+async function waitForAdmission(testEnv: typeof env, timeoutMs = 8000): Promise<Response> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const response = await worker.fetch(upgradeRequest(), testEnv);
+    if (response.status === 101) return response;
+    await new Promise((r) => setTimeout(r, 50));
+    if (Date.now() > deadline) {
+      throw new Error(`upgrade was not admitted before timeout (${response.status})`);
+    }
+  }
+}
+
+describe('WS admission cap (maxClients) — worker edge', () => {
+  it('admits an upgrade while under the cap (101)', async () => {
+    const response = await worker.fetch(upgradeRequest(), env);
+    expect(response.status).toBe(101);
+    response.webSocket?.accept();
+    response.webSocket?.close();
+  });
+
+  it('rejects the next upgrade with 429 once maxClients is reached', async () => {
+    const first = await worker.fetch(upgradeRequest(), capOne);
+    expect(first.status).toBe(101);
+    first.webSocket?.accept();
+
+    const second = await worker.fetch(upgradeRequest(), capOne);
+    expect(second.status).toBe(429);
+    expect(second.webSocket).toBeNull();
+    const body = await second.text();
+    // The IRC-style ERROR line travels in the 429 body: pre-handshake
+    // there is no WebSocket to carry a frame, so the body is the only
+    // channel a non-browser client can read.
+    expect(body).toBe('ERROR :Closing link: server full');
+
+    first.webSocket?.close();
+  });
+
+  it('frees the slot on close so a later upgrade is admitted again', async () => {
+    const first = await worker.fetch(upgradeRequest(), capOne);
+    expect(first.status).toBe(101);
+    first.webSocket?.accept();
+
+    const second = await worker.fetch(upgradeRequest(), capOne);
+    expect(second.status).toBe(429);
+
+    // Close the admitted client; its ConnectionDO teardown releases the
+    // counter slot, so a subsequent upgrade must be admitted.
+    first.webSocket?.close();
+    const third = await waitForAdmission(capOne);
+    expect(third.status).toBe(101);
+    third.webSocket?.accept();
+    third.webSocket?.close();
+  });
+});

package/apps/cf-worker/tests/ws-rate-limit.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Worker-edge per-IP upgrade rate limit (`perIpConnectionRate`) tests.
+ *
+ * TDD outline:
+ *   "Red: the N+1th upgrade from one `CF-Connecting-IP` within the
+ *    window is admitted today; assert it receives 429. Green:
+ *    RateLimitDO check at the edge, keyed by CF-Connecting-IP."
+ *
+ * Drives the production worker entry (`src/worker.ts`) end-to-end
+ * through `worker.fetch` exactly like `ws-admission.test.ts`. The rate
+ * knobs are overridden per call via `{ ...env, PER_IP_... }` env vars,
+ * the same per-test override pattern the admission suite uses for
+ * `MAX_CLIENTS`.
+ */
+
+import { env, reset } from 'cloudflare:test';
+import { afterEach, describe, expect, it } from 'vitest';
+import worker from '../src/worker';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      WEB_ORIGINS: string;
+      MAX_CLIENTS?: string;
+      /** Optional per-IP upgrade rate budget (parsed by the config loader). */
+      PER_IP_CONNECTION_RATE_MAX?: string;
+      /** Optional per-IP rate window in milliseconds. */
+      PER_IP_CONNECTION_RATE_WINDOW_MS?: string;
+    }
+  }
+}
+
+const UPGRADE_URL = 'https://irc.example.com/';
+
+function upgradeRequest(ip?: string): Request {
+  // No Origin header — non-browser client, so the CSWSH policy passes
+  // regardless of the WEB_ORIGINS value in the test vars.
+  const headers: Record<string, string> = { Upgrade: 'websocket' };
+  if (ip !== undefined) {
+    headers['CF-Connecting-IP'] = ip;
+  }
+  return new Request(UPGRADE_URL, { headers });
+}
+
+/** Env with the per-IP upgrade budget pinned to 2 per 60 s. */
+const rateTwo = { ...env, PER_IP_CONNECTION_RATE_MAX: '2' };
+
+// DO storage persists across tests in the same file; reset between each so
+// rate entries (and any half-closed connections) never leak across tests.
+afterEach(async () => {
+  await reset();
+});
+
+describe('WS per-IP upgrade rate limit — worker edge', () => {
+  it('admits upgrades while the IP is within its budget (101)', async () => {
+    const first = await worker.fetch(upgradeRequest('203.0.113.10'), rateTwo);
+    expect(first.status).toBe(101);
+    first.webSocket?.accept();
+    first.webSocket?.close();
+
+    const second = await worker.fetch(upgradeRequest('203.0.113.10'), rateTwo);
+    expect(second.status).toBe(101);
+    second.webSocket?.accept();
+    second.webSocket?.close();
+  });
+
+  it('rejects the over-budget upgrade from the same IP with 429', async () => {
+    for (let i = 0; i < 2; i++) {
+      const r = await worker.fetch(upgradeRequest('203.0.113.11'), rateTwo);
+      expect(r.status).toBe(101);
+      r.webSocket?.accept();
+    }
+    const third = await worker.fetch(upgradeRequest('203.0.113.11'), rateTwo);
+    expect(third.status).toBe(429);
+    expect(third.webSocket).toBeNull();
+    const body = await third.text();
+    // The IRC-style ERROR line travels in the 429 body (same convention as
+    // the server-full rejection) so non-browser clients see a reason.
+    expect(body).toBe('ERROR :Closing link: connection rate exceeded');
+  });
+
+  it('keys the budget on CF-Connecting-IP (a saturated IP does not block another)', async () => {
+    const a1 = await worker.fetch(upgradeRequest('203.0.113.12'), rateTwo);
+    expect(a1.status).toBe(101);
+    a1.webSocket?.accept();
+    const a2 = await worker.fetch(upgradeRequest('203.0.113.12'), rateTwo);
+    expect(a2.status).toBe(101);
+    a2.webSocket?.accept();
+    expect(await worker.fetch(upgradeRequest('203.0.113.12'), rateTwo)).toHaveProperty(
+      'status',
+      429,
+    );
+
+    const other = await worker.fetch(upgradeRequest('198.51.100.7'), rateTwo);
+    expect(other.status).toBe(101);
+    other.webSocket?.accept();
+    other.webSocket?.close();
+  });
+
+  it('recovers the budget after the sliding window decays', async () => {
+    const shortWindow = {
+      ...env,
+      PER_IP_CONNECTION_RATE_MAX: '1',
+      PER_IP_CONNECTION_RATE_WINDOW_MS: '500',
+    };
+    const first = await worker.fetch(upgradeRequest('203.0.113.13'), shortWindow);
+    expect(first.status).toBe(101);
+    first.webSocket?.accept();
+    expect(await worker.fetch(upgradeRequest('203.0.113.13'), shortWindow)).toHaveProperty(
+      'status',
+      429,
+    );
+    // Wait out the 500 ms window; the single admission decays and the
+    // budget recovers.
+    await new Promise((r) => setTimeout(r, 700));
+    const after = await worker.fetch(upgradeRequest('203.0.113.13'), shortWindow);
+    expect(after.status).toBe(101);
+    after.webSocket?.accept();
+    after.webSocket?.close();
+  });
+
+  it('skips the rate check when CF-Connecting-IP is absent (non-edge request)', async () => {
+    // Only the Cloudflare edge sets CF-Connecting-IP; a request lacking it
+    // (e.g. a direct service-binding call) bypasses the per-IP budget —
+    // there is no key to budget on. Production traffic always enters via
+    // the edge, which stamps the header.
+    for (let i = 0; i < 3; i++) {
+      const r = await worker.fetch(upgradeRequest(), rateTwo);
+      expect(r.status).toBe(101);
+      r.webSocket?.accept();
+    }
+  });
+});

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

@@ -55,6 +55,20 @@ class_name = "ChannelDO"
 name = "CHANNEL_REGISTRY_DO"
 class_name = "ChannelRegistryDO"
 
+# Global live-connection admission counter (maxClients cap). Mirrors the
+# production binding; ws-admission.test.ts drives the worker edge through
+# admit / reject / re-admit after close.
+[[durable_objects.bindings]]
+name = "COUNTER_DO"
+class_name = "CounterDO"
+
+# Per-IP upgrade rate limiter (perIpConnectionRate). Mirrors the
+# production binding; ws-rate-limit.test.ts drives the worker edge
+# through allow / over-budget reject / window decay.
+[[durable_objects.bindings]]
+name = "RATE_LIMIT_DO"
+class_name = "RateLimitDO"
+
 # D1 backing for persistent SASL accounts
 [[d1_databases]]
 binding = "ACCOUNTS_DB"
@@ -63,4 +77,4 @@ database_id = "test-d1-worker-accounts"
 
 [[migrations]]
 tag = "v1"
-new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
+new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO", "CounterDO", "RateLimitDO"]

package/apps/cf-worker/wrangler.toml

@@ -3,8 +3,7 @@
 ## Cloudflare Worker production config for ServerlessIRCd.
 ##
 ## Deploy:
-##   pnpm deploy:cf:staging     # wrangler deploy --env staging
-##   pnpm deploy:cf:prod        # wrangler deploy
+##   pnpm deploy:cf        # wrangler deploy
 ##
 ## The `apps/cf-worker` worker is the public edge for the IRC service.
 ## It owns the three Durable Object namespaces from the cf-adapter
@@ -12,11 +11,45 @@
 ## upgrades to per-connection ConnectionDO instances. See
 ## `src/worker.ts` and PLAN §6.1.
 ##
-## Secrets: NEVER put secrets (API tokens, server passwords, account
-## credentials) in this file. Use `wrangler secret put <NAME>` per
-## environment; they live in the Workers KV secrets store, not the repo.
-## As of v1 the worker does not consume any secret bindings — server
-## password, SASL `AccountStore`, and oper creds are future work.
+## Secrets: NEVER put secrets in this file's [vars] table. Vars marked
+## [secret] below live in the Workers secrets store, not the repo — set
+## them with `wrangler secret put <NAME>`.
+##
+## Every env var the Worker consumes is enumerated in the block below,
+## classified `[vars]` (plaintext knob) or `[secret]` (credential
+## material). The block is drift-guarded by `tools/ci-hardening`
+## (tests/env-var-drift.test.ts): adding a var to `CfConfigEnv`
+## (`packages/cf-adapter/src/config-loader.ts`) without a matching
+## entry here fails CI.
+## BEGIN consumed-env-vars
+## [vars] SERVER_NAME — REQUIRED. Public hostname clients see in numerics (001/005). The deploy hostname guard refuses placeholders.
+## [vars] NETWORK_NAME — Network name surfaced in 002 / ISUPPORT (default "ServerlessIRCd").
+## [vars] SERVER_VERSION — Version string for 002/004/351/371 (schema default when unset).
+## [vars] CREATED_AT — Epoch-ms number or free text for 003 RPL_CREATED.
+## [vars] MOTD_LINES — Newline-delimited MOTD text.
+## [vars] MAX_CLIENTS — Global live-connection cap enforced by COUNTER_DO admission (default 10000).
+## [vars] CHANNEL_PREFIXES — Allowed channel-type prefixes.
+## [vars] MAX_CHANNELS_PER_USER — Per-user joined-channel cap.
+## [vars] MAX_TARGETS_PER_COMMAND — Cap on comma-split targets for PRIVMSG/NOTICE/PART.
+## [vars] NICK_LEN — Maximum nick byte length.
+## [vars] CHANNEL_LEN — Maximum channel-name byte length.
+## [vars] TOPIC_LEN — Maximum topic byte length.
+## [vars] MAX_LIST_ENTRIES — Cap on LIST reply entries.
+## [vars] QUIT_MESSAGE — Default QUIT part-message.
+## [vars] MAX_FRAMES_PER_WINDOW — Per-connection inbound frame ceiling enforced before the actor write.
+## [vars] FRAME_WINDOW_SECONDS — Sliding-window length (seconds) for the frame limit.
+## [vars] MAX_CONNECTIONS_PER_IP — Per-IP simultaneous-connection cap (admission gates).
+## [vars] PER_IP_CONNECTION_RATE_MAX — Per-IP new-connection budget per window (RATE_LIMIT_DO edge check).
+## [vars] PER_IP_CONNECTION_RATE_WINDOW_MS — Per-IP rate window length in ms.
+## [vars] EXTERNAL_ENABLED — Operator opt-in ('true'/'1') for certificate-backed SASL EXTERNAL; additionally requires a bound mTLS identity source and a TLS connection (default off).
+## [vars] OPER_USER — Oper username (pair with a credential secret below).
+## [secret] OPER_PASSWORD — Legacy plaintext oper password (prefer the hashed OPER_SALT + OPER_HASH form; rotate with tools/hash-oper-cred.ts).
+## [secret] OPER_SALT — Base64 scrypt salt of the hashed oper credential (generate with tools/hash-oper-cred.ts).
+## [secret] OPER_HASH — Base64 scrypt hash of the hashed oper credential (generate with tools/hash-oper-cred.ts).
+## [secret] SERVER_PASSWORD — Server-wide PASS gate (`PASS <value>` required before 001; SASL-identified connections are exempt).
+## [secret] SASL_ACCOUNTS — Newline-delimited `user:password` SASL PLAIN seed list (see tools/seed-cf-accounts.ts; supersedes the D1 store at boot when set).
+## [vars] WEB_ORIGINS — OPTIONAL comma-separated Origin allowlist (CSWSH defence). Read directly by the worker edge, not the config loader; unset = same-origin auto-derive.
+## END consumed-env-vars
 
 name = "serverless-ircd"
 main = "src/worker.ts"
@@ -35,10 +68,16 @@ compatibility_flags = ["nodejs_compat"]
 ## `dispatch.error`, `frame.parse-error`) are the canonical query keys.
 [observability]
 enabled = true
-## `head_sampling_rate` keeps 100% of console output — valuable during v1
-## and consistent with the per-frame traceId scheme (every request is
-## uniquely identifiable). Lower this (e.g. 0.1) once traffic grows.
-head_sampling_rate = 1
+## `head_sampling_rate` caps the share of console output Workers
+## Analytics retains. The default is 0.1 (10%): every record the actor
+## emits is scrubbed to non-sensitive fields (e.g. `frame.parse-error`
+## carries only token/length/reason, never the raw line), so full-rate
+## sampling is unnecessary for triage and only multiplies how much
+## client-adjacent data log destinations retain. Production operators
+## can tune this per environment by overriding the `[observability]`
+## block in an `[env.<name>]` section (e.g. staging at 1.0 while
+## debugging an incident).
+head_sampling_rate = 0.1
 
 [observability.logs]
 enabled = true
@@ -55,9 +94,15 @@ invocation_logs = true
 ## 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)
+## 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.
+##
+## `MAX_CLIENTS` is the OPTIONAL global live-connection cap (default
+## 10000). The Worker reserves a slot in the COUNTER_DO counter before
+## forwarding an upgrade and rejects with 429 (ERROR :Closing link:
+## server full) once the cap is reached; slots are released on
+## connection close and TTL-reaped if a DO dies without one.
 [vars]
 SERVER_NAME = "irc.your-domain.invalid"
 NETWORK_NAME = "ServerlessIRCd"
@@ -104,55 +149,20 @@ not_found_handling = "none"
 run_worker_first = true
 
 ## ---------------------------------------------------------------------------
-## Staging environment.
-## ---------------------------------------------------------------------------
-## `wrangler deploy --env staging` ships to the staging Worker + DO
-## namespace. The CI workflow (`.github/workflows/deploy-cf.yml`) deploys
-## here on every push to `main` and then runs the smoke e2e.
-[env.staging]
-name = "serverless-ircd-staging"
-
-[env.staging.observability]
-enabled = true
-head_sampling_rate = 1
-
-[env.staging.vars]
-SERVER_NAME = "irc-staging.example.com"
-NETWORK_NAME = "ServerlessIRCd (staging)"
-MOTD_LINES = """
-Welcome to ServerlessIRCd staging.
-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.
+## D1 database — unified services persistence (NickServ / ChanServ / SASL).
 ## ---------------------------------------------------------------------------
-## The `accounts` table stores scrypt-hashed SASL PLAIN credentials (never
-## plaintext). Loaded at ConnectionDO construction; when empty or unreachable
-## the resolver falls back to the `SASL_ACCOUNTS` env-var seed. Provision with:
+## The `nickserv_accounts` table is the single credential home for SASL
+## PLAIN, SASL EXTERNAL, PASS-auth, and NickServ IDENTIFY. All scrypt-hashed
+## credentials live here; the standalone `accounts` table was dropped.
+## Provision with:
 ##   wrangler d1 create serverless-ircd-accounts
-##   wrangler d1 execute serverless-ircd-accounts --command \
-##     "CREATE TABLE IF NOT EXISTS accounts (account TEXT PRIMARY KEY, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)"
-## Seed accounts via `tools/seed-cf-accounts.ts`.
+## The services tables self-provision on first load (ConnectionDO runs
+## `CREATE TABLE IF NOT EXISTS` for each table). Seed accounts via
+## `tools/seed-cf-accounts.ts`.
 [[d1_databases]]
 binding = "ACCOUNTS_DB"
 database_name = "serverless-ircd-accounts"
-# database_id is filled in by `wrangler d1 create` and is env-specific.
-
-[[env.staging.d1_databases]]
-binding = "ACCOUNTS_DB"
-database_name = "serverless-ircd-accounts-staging"
+# database_id is filled in by `wrangler d1 create`.
 
 ## ---------------------------------------------------------------------------
 ## Durable Object bindings.
@@ -179,22 +189,26 @@ class_name = "ChannelDO"
 name = "CHANNEL_REGISTRY_DO"
 class_name = "ChannelRegistryDO"
 
-# Staging environment bindings (wrangler requires per-env blocks).
-[[env.staging.durable_objects.bindings]]
-name = "CONNECTION_DO"
-class_name = "ConnectionDO"
-
-[[env.staging.durable_objects.bindings]]
-name = "REGISTRY_DO"
-class_name = "RegistryDO"
-
-[[env.staging.durable_objects.bindings]]
-name = "CHANNEL_DO"
-class_name = "ChannelDO"
-
-[[env.staging.durable_objects.bindings]]
-name = "CHANNEL_REGISTRY_DO"
-class_name = "ChannelRegistryDO"
+# Global live-connection counter enforcing `MAX_CLIENTS` (the
+# `maxClients` server-config cap). A single CounterDO instance (fixed
+# name) tracks one admission entry per live WebSocket; the Worker's
+# `fetch` reserves a slot per upgrade and rejects with 429 when full,
+# ConnectionDO releases the slot on every teardown path, and a lazy TTL
+# reap on each admit reconciles entries from DO instances that died
+# without delivering a close event.
+[[durable_objects.bindings]]
+name = "COUNTER_DO"
+class_name = "CounterDO"
+
+# Per-IP upgrade rate limiter enforcing `perIpConnectionRate` (knobs:
+# `PER_IP_CONNECTION_RATE_MAX` / `PER_IP_CONNECTION_RATE_WINDOW_MS`
+# vars, defaults 5 per 60 s). A single RateLimitDO instance (fixed name)
+# keeps one sliding-window admission-timestamp list per
+# CF-Connecting-IP; the Worker's `fetch` checks the budget before
+# forwarding an upgrade and rejects over-budget IPs with 429.
+[[durable_objects.bindings]]
+name = "RATE_LIMIT_DO"
+class_name = "RateLimitDO"
 
 # ## ---------------------------------------------------------------------------
 # ## Durable Object migrations.
@@ -210,10 +224,6 @@ class_name = "ChannelRegistryDO"
 # tag = "v1"
 # new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
 
-# [[env.staging.migrations]]
-# tag = "v1"
-# new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO", "ChannelRegistryDO"]
-
 [exports.ConnectionDO]
 type = "durable-object"
 storage = "sqlite"
@@ -229,3 +239,11 @@ storage = "sqlite"
 [exports.ChannelRegistryDO]
 type = "durable-object"
 storage = "sqlite"
+
+[exports.CounterDO]
+type = "durable-object"
+storage = "sqlite"
+
+[exports.RateLimitDO]
+type = "durable-object"
+storage = "sqlite"

package/apps/local-cli/package.json

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

package/apps/local-cli/src/config-loader.ts

@@ -9,7 +9,11 @@
  * surfaced at boot rather than mid-session.
  */
 
-import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+import {
+  type OperCred,
+  type ParsedServerConfig,
+  parseServerConfig,
+} from '@serverless-ircd/irc-core';
 
 /**
  * CLI / programmatic input for `loadServerConfigFromCliArgs`. Every
@@ -34,7 +38,15 @@ export interface CliConfigInput {
   motdLines?: string[];
   channelPrefixes?: string;
   maxClients?: number;
-  operCreds?: Array<{ user: string; password: string }>;
+  /**
+   * IRC operator credentials. Each entry is EITHER the at-rest hashed
+   * form `{user, salt, hash}` (recommended — generate via
+   * `tools/hash-oper-cred.ts`) OR the legacy plaintext form
+   * `{user, password}` (deprecated — retained for a single
+   * deprecation-cycle window). The two shapes can be mixed in the same
+   * array; the shared `OperCredSchema` validates either.
+   */
+  operCreds?: ReadonlyArray<OperCred>;
   /**
    * Server-password gate. Treat as a secret; the loader threads it
    * straight through (via `stripUndefined`) to `ServerConfig.serverPassword`

package/apps/local-cli/src/line-scanner.ts

@@ -18,9 +18,26 @@
  * exactly when a real IRC client connects to local-cli directly.
  */
 
+import { MAX_BUFFER_BYTES } from '@serverless-ircd/irc-core';
+
+/** Options accepted by {@link LineScanner}. */
+export interface LineScannerOptions {
+  /**
+   * Invoked when a pushed chunk grows the retained carry past
+   * {@link MAX_BUFFER_BYTES} (raw bytes, checked once per push). The
+   * scanner drops the oversized carry and returns no lines; the owner
+   * should write `ERROR :Closing link: ...` and destroy the socket — this
+   * seam has no write path. Mirrors the `TcpByteStreamTransport` cap so
+   * both sides of the WS↔TCP bridge enforce one identical budget.
+   */
+  onOverflow?: () => void;
+}
+
 export class LineScanner {
   private carry: Buffer = Buffer.alloc(0);
 
+  constructor(private readonly options?: LineScannerOptions) {}
+
   /**
    * Feeds a chunk of TCP bytes. Returns the complete lines found in this
    * chunk (joined with any leftover carry from prior chunks), in order,
@@ -42,6 +59,15 @@ export class LineScanner {
       nl = buf.indexOf(0x0a, start);
     }
     this.carry = buf.subarray(start);
+    // Cap the retained (unterminated) tail — checked once per push, in raw
+    // bytes. Complete lines flushed by this chunk never count against the
+    // budget, so legitimate multi-line batches far larger than the cap pass
+    // through; only an unterminated tail can grow unboundedly.
+    if (this.carry.length > MAX_BUFFER_BYTES) {
+      this.carry = Buffer.alloc(0);
+      this.options?.onOverflow?.();
+      return [];
+    }
     return lines;
   }