serverless-ircd 0.10.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

@@ -11,9 +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>`;
-## they live in the Workers KV secrets store, not the repo.
+## 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"
@@ -32,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
@@ -52,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"
@@ -141,6 +189,27 @@ class_name = "ChannelDO"
 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.
 # ## ---------------------------------------------------------------------------
@@ -170,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.10.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;
   }
 

package/apps/local-cli/src/server.ts

@@ -44,6 +44,7 @@ import {
   type Logger,
   type MessageStore,
   type NickHistoryStore,
+  type OperCred,
   type RawLine,
   type ServerConfig,
   type ServicesStore,
@@ -182,8 +183,15 @@ export interface LocalServerConfig {
    * like `REHASH` are unreachable; supply a non-empty list to let a client
    * oper up. Threaded straight through to the reducer-facing
    * {@link ServerConfig} via the shared schema.
+   *
+   * 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.
    */
-  readonly operCreds?: Array<{ user: string; password: string }>;
+  readonly operCreds?: ReadonlyArray<OperCred>;
 }
 
 export interface StartServerOptions extends LocalServerConfig {
@@ -525,7 +533,16 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       const tcpSockets = new Set<Socket>();
       const tcpServer = createServer((socket) => {
         tcpSockets.add(socket);
-        const scanner = new LineScanner();
+        const scanner = new LineScanner({
+          // A > 8 KiB unterminated tail is pure attacker-controlled memory
+          // (no legal IRC line can exceed 512 bytes): answer with the
+          // RFC-style ERROR notice and destroy the socket. Cleanup runs in
+          // the shared 'close' handler below.
+          onOverflow: () => {
+            safeSocketWrite(socket, 'ERROR :Closing link: input buffer overflow\r\n');
+            socket.destroy();
+          },
+        });
 
         // Admission gate — same policy as the WS path: refuse before the
         // actor is attached so per-IP / per-user counters stay authoritative.
@@ -686,6 +703,10 @@ function attachConnection(
     messages,
     ...(services !== undefined ? { services } : {}),
     history,
+    // Shared per-IP failed-OPER counter: one budget per source host across
+    // every connection the CLI hosts (runtime-owned, bound to the runtime
+    // clock). Drives the OPER brute-force lockout.
+    operFailures: runtime.operFailures,
     logger,
     ...(transport.actorTransport !== undefined ? { transport: transport.actorTransport } : {}),
   });

package/apps/local-cli/tests/line-scanner.test.ts

@@ -79,3 +79,67 @@ describe('LineScanner', () => {
     expect(sc.flush()).toEqual([]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Input buffer cap: a peer streaming megabytes with no line terminator must
+// not grow the carry unboundedly. The cap is 8 KiB of raw bytes on the
+// retained (unterminated) tail, checked once per push — complete lines
+// flushed by the same chunk never count against the budget.
+// ---------------------------------------------------------------------------
+
+describe('LineScanner — input buffer cap', () => {
+  it('signals onOverflow and drops the carry when an appended tail exceeds the 8 KiB cap', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    expect(sc.push(enc('x'.repeat(9 * 1024)))).toEqual([]);
+    expect(overflows.length).toBe(1);
+    // The oversized tail is dropped, not retained.
+    expect(sc.flush()).toEqual([]);
+  });
+
+  it('checks the cap once per push (chunk), not per byte', () => {
+    // A single 9 KiB chunk that overflows fires the callback exactly once —
+    // the guard runs on the appended carry, not per input byte.
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    sc.push(enc('y'.repeat(9 * 1024)));
+    expect(overflows.length).toBe(1);
+  });
+
+  it('signals overflow only on the push that crosses the cap (accumulated chunks)', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    expect(sc.push(enc('a'.repeat(4 * 1024)))).toEqual([]);
+    expect(overflows.length).toBe(0);
+    expect(sc.push(enc('b'.repeat(5 * 1024)))).toEqual([]);
+    expect(overflows.length).toBe(1);
+  });
+
+  it('does NOT overflow a buffered partial line at (just under) the cap', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    // Exactly 8192 bytes: at the cap, still allowed.
+    sc.push(enc('z'.repeat(8192)));
+    expect(overflows.length).toBe(0);
+    expect(sc.flush()).toEqual(['z'.repeat(8192)]);
+  });
+
+  it('does not overflow a chunk of complete lines totalling over the cap (batching)', () => {
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    // 20 terminated ~500-byte lines ≈ 10 KiB in one chunk: every line is
+    // complete, so the carry is empty and nothing overflows.
+    const chunk = `${Array.from({ length: 20 }, (_, i) => `PING :${`${i}`.padStart(495, '-')}`).join('\r\n')}\r\n`;
+    expect(chunk.length).toBeGreaterThan(8192);
+    expect(sc.push(enc(chunk)).length).toBe(20);
+    expect(overflows.length).toBe(0);
+  });
+
+  it('measures the carry in bytes (multi-byte UTF-8 counts at wire size)', () => {
+    // 'é' encodes to 2 UTF-8 bytes: 5000 × é = 10000 bytes > 8192.
+    const overflows: number[] = [];
+    const sc = new LineScanner({ onOverflow: () => overflows.push(1) });
+    sc.push(enc('é'.repeat(5000)));
+    expect(overflows.length).toBe(1);
+  });
+});