serverless-ircd 0.10.0 → 0.11.0

package/apps/cf-tcp-container/src/config-loader.ts

@@ -27,6 +27,20 @@ export interface ContainerConfigEnv {
   CHANNEL_PREFIXES?: string;
   OPER_USER?: string;
   OPER_PASSWORD?: string;
+  /**
+   * Scrypt salt (base64) for the hashed oper credential form. When set
+   * alongside `OPER_USER` + `OPER_HASH`, the loader builds a hashed
+   * `{user, salt, hash}` cred instead of the legacy plaintext
+   * `{user, password}` shape. The hashed form is preferred when both
+   * are present so deployments can rotate without removing the legacy
+   * vars in the same step. Generate via `tools/hash-oper-cred.ts`.
+   */
+  OPER_SALT?: string;
+  /**
+   * Scrypt hash (base64) for the hashed oper credential form. See
+   * `OPER_SALT` for the full set of vars.
+   */
+  OPER_HASH?: string;
   MAX_CHANNELS_PER_USER?: string;
   MAX_TARGETS_PER_COMMAND?: string;
   NICK_LEN?: string;
@@ -39,6 +53,26 @@ export interface ContainerConfigEnv {
   TCP_PORT?: string;
   /** Container-specific: bind address (default 0.0.0.0 for Spectrum origin). */
   TCP_HOST?: string;
+  /**
+   * Container-specific: path to the PEM certificate the origin TLS
+   * listener (default port 6697) presents. Must be set together with
+   * `TLS_KEY_PATH`. Prod-classified boots (`NODE_ENV=production`) refuse
+   * to start without it — the origin terminates TLS end-to-end.
+   */
+  TLS_CERT_PATH?: string;
+  /** Container-specific: path to the PEM private key (see `TLS_CERT_PATH`). */
+  TLS_KEY_PATH?: string;
+  /** Container-specific: TLS listener port (default 6697). */
+  TLS_PORT?: string;
+  /**
+   * Container-specific: exact value `localhost` opts into the plaintext
+   * debug listener (bound to 127.0.0.1 only, for local development).
+   * Any other value is rejected; forbidden entirely in prod-classified
+   * mode.
+   */
+  DEBUG_PLAINTEXT?: string;
+  /** Platform convention: `production` classifies the boot as prod. */
+  NODE_ENV?: string;
   /** Container-specific: path to the persistence snapshot file. */
   PERSISTENCE_PATH?: string;
   /** Container-specific: auto-snapshot interval in milliseconds. */
@@ -50,13 +84,26 @@ export interface ContainerConfig {
   server: ParsedServerConfig;
   tcpPort: number;
   tcpHost: string;
+  /**
+   * TLS listener config. Present when `TLS_CERT_PATH` + `TLS_KEY_PATH`
+   * are set — the origin then terminates TLS itself (Spectrum
+   * `tls_mode = "full"` topology).
+   */
+  tls: { certPath: string; keyPath: string; port: number } | undefined;
+  /**
+   * True only when `DEBUG_PLAINTEXT=localhost`: a plaintext listener may
+   * bind — forced to 127.0.0.1 — strictly for local debugging.
+   */
+  plaintextDebug: boolean;
   persistencePath: string | undefined;
   snapshotIntervalMs: number;
 }
 
 const DEFAULT_TCP_PORT = 6667;
 const DEFAULT_TCP_HOST = '0.0.0.0';
+const DEFAULT_TLS_PORT = 6697;
 const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
+const PLAINTEXT_DEBUG_FLAG = 'localhost';
 
 /**
  * Loads and validates the IRC server config plus container-specific knobs
@@ -68,10 +115,33 @@ const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
  */
 export function loadContainerConfig(env: ContainerConfigEnv): ContainerConfig {
   const server = parseServerConfig(buildServerInput(env));
+  const tls = resolveTls(env);
+  const prod = env.NODE_ENV === 'production';
+  if (prod && tls === undefined) {
+    throw new Error(
+      'refusing to start a prod-classified origin without TLS: set TLS_CERT_PATH and TLS_KEY_PATH ' +
+        '(Spectrum tls_mode=full requires the origin to terminate TLS itself)',
+    );
+  }
+  const plaintextDebug = env.DEBUG_PLAINTEXT !== undefined;
+  if (plaintextDebug && prod) {
+    throw new Error(
+      'refusing to enable DEBUG_PLAINTEXT in a prod-classified origin (plaintext IRC is debug-only)',
+    );
+  }
+  if (plaintextDebug && env.DEBUG_PLAINTEXT !== PLAINTEXT_DEBUG_FLAG) {
+    throw new Error(
+      `invalid DEBUG_PLAINTEXT value ${JSON.stringify(env.DEBUG_PLAINTEXT)}: the only allowed value is 'localhost'`,
+    );
+  }
   return {
     server,
     tcpPort: parseIntOrDefault(env.TCP_PORT, DEFAULT_TCP_PORT),
-    tcpHost: env.TCP_HOST?.trim() || DEFAULT_TCP_HOST,
+    // Debug plaintext is localhost-only by construction; the operator
+    // cannot widen the bind even by setting TCP_HOST alongside the flag.
+    tcpHost: plaintextDebug ? '127.0.0.1' : env.TCP_HOST?.trim() || DEFAULT_TCP_HOST,
+    tls,
+    plaintextDebug,
     persistencePath:
       env.PERSISTENCE_PATH !== undefined && env.PERSISTENCE_PATH.length > 0
         ? env.PERSISTENCE_PATH
@@ -80,6 +150,23 @@ export function loadContainerConfig(env: ContainerConfigEnv): ContainerConfig {
   };
 }
 
+function resolveTls(env: ContainerConfigEnv): ContainerConfig['tls'] {
+  const hasCert = env.TLS_CERT_PATH !== undefined && env.TLS_CERT_PATH.length > 0;
+  const hasKey = env.TLS_KEY_PATH !== undefined && env.TLS_KEY_PATH.length > 0;
+  if (!hasCert && !hasKey) return undefined;
+  if (!hasCert) {
+    throw new Error('TLS_KEY_PATH is set but TLS_CERT_PATH is not — provide both or neither');
+  }
+  if (!hasKey) {
+    throw new Error('TLS_CERT_PATH is set but TLS_KEY_PATH is not — provide both or neither');
+  }
+  return {
+    certPath: env.TLS_CERT_PATH as string,
+    keyPath: env.TLS_KEY_PATH as string,
+    port: parseIntOrDefault(env.TLS_PORT, DEFAULT_TLS_PORT),
+  };
+}
+
 function parseIntOrDefault(raw: string | undefined, def: number): number {
   if (raw === undefined || raw.trim().length === 0) return def;
   const n = Number.parseInt(raw, 10);
@@ -99,7 +186,31 @@ function buildServerInput(env: ContainerConfigEnv): Record<string, unknown> {
   if (env.MAX_CLIENTS !== undefined) input.maxClients = Number.parseInt(env.MAX_CLIENTS, 10);
   if (env.CHANNEL_PREFIXES !== undefined) input.channelPrefixes = env.CHANNEL_PREFIXES;
   if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
-    input.operCreds = [{ user: env.OPER_USER ?? '', password: env.OPER_PASSWORD ?? '' }];
+    // Hashed form (OPER_USER + OPER_SALT + OPER_HASH) is preferred when
+    // both salt + hash are supplied — even if OPER_PASSWORD is also set,
+    // so a deployment can rotate to the hashed form without dropping the
+    // legacy var in the same release. The legacy plaintext
+    // `{user, password}` shape is retained for a single deprecation-
+    // cycle window.
+    const hasHashed = env.OPER_SALT !== undefined && env.OPER_HASH !== undefined;
+    if (hasHashed) {
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          salt: env.OPER_SALT ?? '',
+          hash: env.OPER_HASH ?? '',
+        },
+      ];
+    } else {
+      input.operCreds = [
+        {
+          user: env.OPER_USER ?? '',
+          password: env.OPER_PASSWORD ?? '',
+          ...(env.OPER_SALT !== undefined ? { salt: env.OPER_SALT } : {}),
+          ...(env.OPER_HASH !== undefined ? { hash: env.OPER_HASH } : {}),
+        },
+      ];
+    }
   }
   if (env.MAX_CHANNELS_PER_USER !== undefined) {
     input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);

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

@@ -2,12 +2,36 @@
  * CF TCP container origin — the stateful IRC server behind Cloudflare
  * Spectrum.
  *
- * Spectrum terminates TLS at the edge and forwards plaintext TCP to this
- * origin. The container runs the shared IRC core (`ConnectionActor` +
- * `InMemoryRuntime`) over the `TcpByteStreamTransport` seam,
- * which reassembles `\r\n`-terminated IRC lines across arbitrary TCP
- * chunks. The actor/reducer/dispatch pipeline is identical to the wss
- * path — only the line-framing transport differs.
+ * Spectrum forwards TLS end-to-end (`tls_mode = "full"`): this origin
+ * terminates TLS itself on :6697 with the certificate configured via
+ * `TLS_CERT_PATH` / `TLS_KEY_PATH` (see `config-loader.ts`). The
+ * container runs the shared IRC core (`ConnectionActor` +
+ * `InMemoryRuntime`) over the `TcpByteStreamTransport` seam, which
+ * reassembles `\r\n`-terminated IRC lines across arbitrary TCP chunks.
+ * The actor/reducer/dispatch pipeline is identical to the wss path —
+ * only the line-framing transport differs.
+ *
+ * Spectrum is configured with `proxy_protocol = "v1"`, so every flow
+ * (TLS and plaintext alike) must begin with a PROXY v1 header
+ * (`PROXY TCP4 <src_ip> ... \r\n`, see `proxy-protocol.ts`). The header
+ * is peeled off before any byte reaches the actor; the recovered source
+ * IP — the real client address, not the Spectrum edge IP — feeds
+ * `state.host` and the per-IP admission gate. Connections whose first
+ * bytes do not yield a valid header are closed with
+ * `ERROR :Closing link` (direct-connection bypass defense); the
+ * localhost debug listener requires the header too, e.g.:
+ *   printf 'PROXY TCP4 127.0.0.1 127.0.0.1 40000 6667\r\n...' | nc …
+ *
+ * A plaintext listener is available strictly for localhost-only local
+ * debugging; in a prod-classified boot the config loader refuses to
+ * start without TLS material.
+ *
+ * SASL EXTERNAL is explicitly unsupported on this transport: Spectrum's
+ * PROXY v1 forwarding carries no client-cert subject, so no mTLS
+ * identity source exists here and `AUTHENTICATE EXTERNAL` is rejected
+ * up front with `904 ERR_SASLFAIL` ("SASL EXTERNAL not supported on
+ * this transport"). Cert-backed SASL lives on the wss and NLB+TLS
+ * paths; see docs/SASL-EXTERNAL.md.
  *
  * When `persistencePath` is supplied, channel state (topics, modes, bans)
  * is restored from a snapshot file on boot and auto-saved on an interval
@@ -15,7 +39,9 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { type Server, type Socket, createServer } from 'node:net';
+import { createServer as tlsCreateServer } from 'node:tls';
 import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
 import {
   type AdmissionConfig,
@@ -37,13 +63,30 @@ import {
 } from '@serverless-ircd/irc-core';
 import { ConnectionActor, TcpByteStreamTransport } from '@serverless-ircd/irc-server';
 import { loadSnapshot, restoreRuntime, saveSnapshot, snapshotRuntime } from './persistence.js';
+import { consumeProxyV1Header } from './proxy-protocol.js';
+
+/**
+ * TLS listener configuration: the origin presents `certPath` / `keyPath`
+ * (PEM) on `port` (default 6697).
+ */
+export interface TlsListenerOptions {
+  readonly certPath: string;
+  readonly keyPath: string;
+  readonly port?: number | undefined;
+}
 
 /** Options accepted by {@link startContainerServer}. */
 export interface StartContainerOptions {
-  /** Plaintext TCP port. Use 0 for an ephemeral port. */
-  readonly port: number;
+  /**
+   * Plaintext TCP port — localhost debug only; a prod boot must serve
+   * TLS instead. Use 0 for an ephemeral port; omit to disable the
+   * plaintext listener entirely.
+   */
+  readonly port?: number | undefined;
   /** Bind address. Defaults to `0.0.0.0` (Spectrum forwards from the edge). */
   readonly host?: string;
+  /** TLS listener: terminates TLS at the origin (Spectrum `full` mode). */
+  readonly tls?: TlsListenerOptions;
   readonly serverName: string;
   readonly networkName: string;
   readonly motdLines?: string[];
@@ -75,7 +118,10 @@ export interface StartContainerOptions {
 
 /** A running container origin. Call {@link close} to shut down. */
 export interface ContainerServer {
-  readonly port: number;
+  /** Bound plaintext (debug) port; undefined when TLS-only. */
+  readonly port: number | undefined;
+  /** Bound TLS port; undefined when no TLS listener is configured. */
+  readonly tlsPort: number | undefined;
   readonly host: string;
   readonly runtime: InMemoryRuntime;
   readonly messages: MessageStore;
@@ -107,15 +153,34 @@ const DEFAULT_MAX_CONNECTIONS_PER_IP = 10;
 const DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
 const DEFAULT_PER_IP_CONNECTION_RATE = { max: 5, windowMs: 60_000 };
 const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
+const DEFAULT_TLS_PORT = 6697;
 
 /**
- * Starts the TCP container origin. Resolves once the TCP listener is
- * ready. When `persistencePath` is set and a snapshot file exists, channel
- * state is restored before any connection is accepted.
+ * Stable refusal for `AUTHENTICATE EXTERNAL` on this transport. Spectrum
+ * forwards with PROXY protocol v1, which carries no client-cert subject,
+ * so this origin has no mTLS identity source and SASL EXTERNAL is
+ * explicitly unsupported: the mechanism is pinned off via
+ * `sasl.externalUnsupportedMessage` and rejected up front with a
+ * transport-specific `904 ERR_SASLFAIL` carrying this exact text
+ * (asserted verbatim by the container tests — change with care).
+ */
+const SASL_EXTERNAL_UNSUPPORTED_MESSAGE = 'SASL EXTERNAL not supported on this transport';
+
+/**
+ * Starts the TCP container origin. Resolves once every configured
+ * listener (TLS on :6697 by default; optional plaintext debug listener)
+ * is ready. When `persistencePath` is set and a snapshot file exists,
+ * channel state is restored before any connection is accepted.
  */
 export async function startContainerServer(opts: StartContainerOptions): Promise<ContainerServer> {
   const host = opts.host ?? '0.0.0.0';
   const clock: Clock = opts.clock ?? { now: () => Date.now() };
+  if (opts.port === undefined && opts.tls === undefined) {
+    throw new Error(
+      'no listener configured: pass tls (cert/key paths) for the TLS listener, ' +
+        'or port for the localhost-only plaintext debug listener',
+    );
+  }
 
   const admission: AdmissionConfig | undefined =
     opts.maxConnectionsPerIp !== undefined ||
@@ -157,43 +222,71 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
   const connections = new Map<Socket, ConnectionBindings>();
   const sockets = new Set<Socket>();
 
-  const tcpServer = createServer((socket) => {
+  const onConnection = (socket: Socket): void => {
     sockets.add(socket);
 
-    // `remoteAddress` is always set on a TCP server's connection socket;
-    // the 'unknown' fallback is defensive and unreachable in practice.
-    /* c8 ignore start */
-    const ip = socket.remoteAddress ?? 'unknown';
-    /* c8 ignore stop */
-    const decision = runtime.admitConnection(ip, undefined);
-    if (!decision.ok) {
-      // A freshly-accepted TCP socket is always writable; the else branch
-      // (skip the ERROR write) is a defensive guard against an impossible
-      // race and cannot be exercised over a real socket.
+    // Set once the PROXY v1 header has been parsed and the connection
+    // admitted; until then inbound bytes are buffered as header bytes.
+    let bindings: ConnectionBindings | undefined;
+    let headerBuffer: Buffer = Buffer.alloc(0);
+
+    const reject = (reason: string): void => {
+      // Data-triggered rejects fire on a live, just-read-from socket;
+      // the else branch (skip the ERROR write) is a defensive guard
+      // against an impossible race and cannot be exercised over a real
+      // socket.
       /* c8 ignore start */
       if (socket.writable) {
-        socket.write(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
+        socket.write(`ERROR :Closing link: (${reason})\r\n`);
       }
       /* c8 ignore stop */
       socket.destroy();
       sockets.delete(socket);
-      return;
-    }
-    const admissionRecordId = decision.recordId;
-    runtime.commitAdmission(ip, undefined, admissionRecordId);
-
-    const { state, actor } = attachConnection(runtime, opts, messages, services, history, clock, {
-      sendText: (text) => {
-        if (socket.writable) socket.write(text);
-      },
-      closeTransport: () => socket.destroy(),
-      admissionRecordId,
-      sourceHost: ip,
-    });
-    connections.set(socket, { state, actor });
+    };
 
     socket.on('data', (chunk: Buffer) => {
-      actor.receive(chunk.toString('utf8')).catch((err) => {
+      if (bindings === undefined) {
+        const buffered = headerBuffer.length === 0 ? chunk : Buffer.concat([headerBuffer, chunk]);
+        const header = consumeProxyV1Header(buffered);
+        if (header.status === 'invalid') {
+          // The peer did not open with a valid PROXY v1 header: either a
+          // direct connection bypassing Spectrum, or a malformed/spoofed
+          // header. Either way the flow is closed before any byte
+          // reaches the IRC actor.
+          reject('invalid PROXY protocol v1 header');
+          return;
+        }
+        if (header.status === 'incomplete') {
+          // Header split across reads: wait for the trailing CRLF.
+          headerBuffer = buffered;
+          return;
+        }
+        const ip = header.sourceIp;
+        const decision = runtime.admitConnection(ip, undefined);
+        if (!decision.ok) {
+          reject(`connection limit reached: ${decision.reason}`);
+          return;
+        }
+        const admissionRecordId = decision.recordId;
+        runtime.commitAdmission(ip, undefined, admissionRecordId);
+
+        bindings = attachConnection(runtime, opts, messages, services, history, clock, {
+          sendText: (text) => {
+            if (socket.writable) socket.write(text);
+          },
+          closeTransport: () => socket.destroy(),
+          admissionRecordId,
+          sourceHost: ip,
+        });
+        connections.set(socket, bindings);
+        if (header.remainder.length > 0) {
+          bindings.actor.receive(header.remainder.toString('utf8')).catch((err) => {
+            logError('actor failure', err);
+          });
+        }
+        return;
+      }
+      bindings.actor.receive(chunk.toString('utf8')).catch((err) => {
         logError('actor failure', err);
       });
     });
@@ -201,14 +294,36 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
     const cleanup = (): void => {
       connections.delete(socket);
       sockets.delete(socket);
-      runtime.unregisterConnection(state.id);
+      // Rejected-before-admission flows never registered a connection.
+      if (bindings !== undefined) {
+        runtime.unregisterConnection(bindings.state.id);
+      }
     };
     socket.on('close', cleanup);
     socket.on('error', (err) => {
       logError('tcp socket error', err);
       cleanup();
     });
-  });
+  };
+
+  const binds: Array<{ server: Server; port: number }> = [];
+
+  if (opts.port !== undefined) {
+    binds.push({ server: createServer(onConnection), port: opts.port });
+  }
+
+  if (opts.tls !== undefined) {
+    const { cert, key } = await loadTlsMaterial(opts.tls);
+    // Same connection pipeline as plaintext: a TLSSocket is a Socket,
+    // and the actor sees the decrypted byte stream identically.
+    binds.push({
+      server: tlsCreateServer(
+        { cert, key, minVersion: 'TLSv1.2', maxVersion: 'TLSv1.3' },
+        onConnection,
+      ),
+      port: opts.tls.port ?? DEFAULT_TLS_PORT,
+    });
+  }
 
   // Auto-snapshot timer.
   const snapshotIntervalMs = opts.snapshotIntervalMs ?? DEFAULT_SNAPSHOT_INTERVAL_MS;
@@ -220,41 +335,85 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
       : undefined;
   if (timer !== undefined) timer.unref?.();
 
-  return new Promise<ContainerServer>((resolve, reject) => {
+  // Listening order matches construction: plaintext debug listener first
+  // (if any), TLS second. `binds` is never empty — the no-listener guard
+  // threw above.
+  const boundPorts = await Promise.all(binds.map((b) => listenOnce(b.server, b.port, host))).catch(
+    async (err: Error) => {
+      // Partial failure: unbind any listener that already made it so a
+      // rejected boot never leaves a stray port behind.
+      await Promise.all(binds.map((b) => new Promise<void>((res) => b.server.close(() => res()))));
+      throw err;
+    },
+  );
+  const plainPort = opts.port !== undefined ? boundPorts[0] : undefined;
+  const tlsPort = opts.tls !== undefined ? boundPorts[boundPorts.length - 1] : undefined;
+  return {
+    port: plainPort,
+    tlsPort,
+    host,
+    runtime,
+    messages,
+    history,
+    testSockets: sockets,
+    close: () =>
+      closeServer({
+        servers: binds.map((b) => b.server),
+        connections,
+        sockets,
+        timer,
+        runtime,
+        persistencePath: opts.persistencePath,
+      }),
+  };
+}
+
+/** Reads + validates the PEM pair, naming the offending path on failure. */
+async function loadTlsMaterial(tls: TlsListenerOptions): Promise<{ cert: Buffer; key: Buffer }> {
+  let cert: Buffer;
+  let key: Buffer;
+  try {
+    cert = await readFile(tls.certPath);
+  } catch (err) {
+    throw new Error(
+      `failed to read TLS certificate at ${tls.certPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  try {
+    key = await readFile(tls.keyPath);
+  } catch (err) {
+    throw new Error(
+      `failed to read TLS key at ${tls.keyPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return { cert, key };
+}
+
+/**
+ * Binds `server` on `port`/`host` and resolves with the actually-bound
+ * port (the listener's own AddressInfo, so ephemeral `0` binds resolve
+ * to the real port).
+ */
+function listenOnce(server: Server, port: number, host: string): Promise<number> {
+  return new Promise((resolve, reject) => {
     const onError = (err: Error): void => {
-      tcpServer.removeListener('listening', onListening);
+      server.removeListener('listening', onListening);
       reject(err);
     };
     const onListening = (): void => {
-      tcpServer.removeListener('error', onError);
-      const addr = tcpServer.address();
+      server.removeListener('error', onError);
+      const addr = server.address();
       // Inside the 'listening' handler `address()` is always an AddressInfo
-      // (TCP server, just bound); the null/string returns only occur for IPC
-      // sockets or before listening. The `opts.port` fallback is unreachable.
+      // (TCP server, just bound); the null/string returns only occur for
+      // IPC sockets or before listening. The `port` fallback is unreachable.
       /* c8 ignore start */
-      const port = typeof addr === 'object' && addr !== null ? addr.port : opts.port;
+      const bound = typeof addr === 'object' && addr !== null ? addr.port : port;
       /* c8 ignore stop */
-      resolve({
-        port,
-        host,
-        runtime,
-        messages,
-        history,
-        testSockets: sockets,
-        close: () =>
-          closeServer({
-            tcpServer,
-            connections,
-            sockets,
-            timer,
-            runtime,
-            persistencePath: opts.persistencePath,
-          }),
-      });
+      resolve(bound);
     };
-    tcpServer.once('listening', onListening);
-    tcpServer.once('error', onError);
-    tcpServer.listen(opts.port, host);
+    server.once('listening', onListening);
+    server.once('error', onError);
+    server.listen(port, host);
   });
 }
 
@@ -274,8 +433,9 @@ function attachConnection(
 ): ConnectionBindings {
   const id = randomUUID();
   const state = createConnection({ id, connectedSince: clock.now() });
-  // `transport.sourceHost` is always supplied (set to the peer IP) by the
-  // only call site above; the else branch is defensive and unreachable.
+  // `transport.sourceHost` is always supplied (set to the PROXY-header
+  // source IP) by the only call site above; the else branch is defensive
+  // and unreachable.
   /* c8 ignore start */
   if (transport.sourceHost !== undefined) {
     state.host = transport.sourceHost;
@@ -300,6 +460,11 @@ function attachConnection(
       quitMessage: opts.quitMessage ?? 'Client Quit',
       ...(opts.serverPassword !== undefined ? { serverPassword: opts.serverPassword } : {}),
       ...(opts.cloaking !== undefined ? { cloaking: opts.cloaking } : {}),
+      // SASL EXTERNAL non-support: PROXY v1 carries no client-cert
+      // subject, so the mechanism is pinned off with the transport-
+      // specific refusal (see SASL_EXTERNAL_UNSUPPORTED_MESSAGE) instead
+      // of failing generically at the three-way gate.
+      sasl: { externalUnsupportedMessage: SASL_EXTERNAL_UNSUPPORTED_MESSAGE },
     },
     clock,
     ids: DEFAULT_ID_FACTORY,
@@ -308,9 +473,19 @@ function attachConnection(
     ...(services !== undefined ? { services } : {}),
     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`.
+    transport: new TcpByteStreamTransport({
+      // 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. The 'close' handler performs
+      // the bookkeeping teardown (connections map + runtime unregister).
+      onOverflow: () => {
+        transport.sendText('ERROR :Closing link: input buffer overflow\r\n');
+        transport.closeTransport();
+      },
+    }),
+    // TLS terminates at this origin (Spectrum `full` mode re-encrypts to
+    // the origin's own TLS listener), so every connection is secure →
+    // user mode `S`.
     secure: true,
   });
 
@@ -335,14 +510,14 @@ function attachConnection(
 }
 
 async function closeServer(args: {
-  tcpServer: Server;
+  servers: Server[];
   connections: Map<Socket, ConnectionBindings>;
   sockets: Set<Socket>;
   timer: ReturnType<typeof setInterval> | undefined;
   runtime: InMemoryRuntime;
   persistencePath: string | undefined;
 }): Promise<void> {
-  const { tcpServer, connections, sockets, timer, runtime, persistencePath } = args;
+  const { servers, connections, sockets, timer, runtime, persistencePath } = args;
 
   if (timer !== undefined) clearInterval(timer);
 
@@ -364,10 +539,12 @@ async function closeServer(args: {
   // Stop accepting new connections. We do NOT await the callback because
   // `server.close()` waits for every connection's 'close' event, which can
   // hang if a destroyed socket's TCP cleanup is delayed by the OS. All
-  // sockets are already destroyed above; the server is safe to abandon.
-  tcpServer.close();
-  (tcpServer as Server & { closeAllConnections?: () => void }).closeAllConnections?.();
-  tcpServer.unref();
+  // sockets are already destroyed above; the servers are safe to abandon.
+  for (const server of servers) {
+    server.close();
+    (server as Server & { closeAllConnections?: () => void }).closeAllConnections?.();
+    server.unref();
+  }
 }
 
 async function snapshotNow(runtime: InMemoryRuntime, path: string): Promise<void> {