serverless-ircd 0.9.0 → 0.11.0

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

@@ -2,13 +2,18 @@
 /**
  * CF TCP container origin entry point.
  *
- * Boots the IRC core as a plaintext TCP server behind Cloudflare Spectrum.
- * Spectrum terminates TLS at the edge and forwards plaintext TCP to this
- * process. Configuration comes from environment variables (set by the
- * Cloudflare Container runtime, Docker, or Kubernetes).
+ * Boots the IRC core as a TLS-terminating origin behind Cloudflare
+ * Spectrum (`tls_mode = "full"`): the process presents its own
+ * certificate on :6697 (TLS_CERT_PATH / TLS_KEY_PATH) and Spectrum
+ * re-encrypts edge→origin, so no plaintext IRC crosses the network.
+ * A plaintext listener is available only for localhost debugging
+ * (DEBUG_PLAINTEXT=localhost, bound to 127.0.0.1). Configuration comes
+ * from environment variables (set by the Cloudflare Container runtime,
+ * Docker, or Kubernetes).
  *
  * Usage:
- *   TCP_PORT=6667 SERVER_NAME=irc.example.com node dist/main.js
+ *   TLS_CERT_PATH=/certs/tls.pem TLS_KEY_PATH=/certs/tls.key \
+ *     SERVER_NAME=irc.example.com node dist/main.js
  *
  * The process runs until SIGINT/SIGTERM. On shutdown it writes a final
  * persistence snapshot (when PERSISTENCE_PATH is set) so channel state
@@ -21,9 +26,17 @@ import { startContainerServer } from './container-server.js';
 async function main(): Promise<void> {
   const cfg = loadContainerConfig(process.env as Record<string, string | undefined>);
 
+  if (!cfg.plaintextDebug && cfg.tls === undefined) {
+    throw new Error(
+      'no listener configured: set TLS_CERT_PATH + TLS_KEY_PATH to serve TLS on :6697, ' +
+        'or DEBUG_PLAINTEXT=localhost for a localhost-only plaintext debug listener',
+    );
+  }
+
   const server = await startContainerServer({
-    port: cfg.tcpPort,
     host: cfg.tcpHost,
+    ...(cfg.plaintextDebug ? { port: cfg.tcpPort } : {}),
+    ...(cfg.tls !== undefined ? { tls: cfg.tls } : {}),
     serverName: cfg.server.serverName,
     networkName: cfg.server.networkName,
     motdLines: cfg.server.motdLines,
@@ -47,7 +60,9 @@ async function main(): Promise<void> {
       level: 'info',
       msg: 'cf-tcp-container listening',
       host: server.host,
-      port: server.port,
+      port: server.port ?? null,
+      tlsPort: server.tlsPort ?? null,
+      plaintextDebug: cfg.plaintextDebug,
       persistence: cfg.persistencePath ?? null,
       serverName: cfg.server.serverName,
     })}\n`,

package/apps/cf-tcp-container/src/proxy-protocol.ts

@@ -0,0 +1,112 @@
+/**
+ * PROXY protocol v1 header parsing.
+ *
+ * Cloudflare Spectrum fronts this origin with `proxy_protocol = "v1"`:
+ * every forwarded TCP flow begins with the ASCII line
+ *
+ *   PROXY TCP4 <src_ip> <dst_ip> <src_port> <dst_port>\r\n
+ *   PROXY TCP6 <src_ip> <dst_ip> <src_port> <dst_port>\r\n
+ *
+ * (spec: the header is at most 107 bytes including the trailing CRLF).
+ * The source IP recovered here is the real client address — the TCP
+ * peer address seen by this origin is always a Spectrum edge IP.
+ *
+ * Dependency decision: hand-rolled parser (no npm `proxy-protocol`
+ * dependency). The v1 header is one fixed-format, ASCII-only line; the
+ * ~40 lines below fully validate it while avoiding the supply-chain
+ * surface of a third-party package on the connection hot path. (The
+ * decision is also recorded in this package's package.json.)
+ *
+ * The header may arrive split across TCP chunks, so
+ * {@link consumeProxyV1Header} is incremental: feed it the bytes
+ * buffered so far and it reports `incomplete` until the trailing CRLF
+ * is available, `invalid` for anything that can no longer be a legal
+ * header (wrong signature, over-length, unknown family, malformed
+ * address/port), or `complete` with the recovered source IP plus any
+ * bytes that followed the header.
+ */
+
+import { isIP } from 'node:net';
+
+/** Max PROXY v1 header length in bytes, including the trailing CRLF. */
+export const PROXY_V1_MAX_HEADER_BYTES = 107;
+
+const SIGNATURE = 'PROXY ';
+const CRLF = '\r\n';
+
+/** Outcome of {@link consumeProxyV1Header}. */
+export type ProxyV1HeaderResult =
+  | { readonly status: 'complete'; readonly sourceIp: string; readonly remainder: Buffer }
+  | { readonly status: 'incomplete' }
+  | { readonly status: 'invalid' };
+
+/**
+ * Consumes a PROXY protocol v1 header from `buffer` (the bytes received
+ * on the connection so far). Pure function: the caller keeps
+ * concatenating chunks and re-invoking until the result is no longer
+ * `incomplete`.
+ */
+export function consumeProxyV1Header(buffer: Buffer): ProxyV1HeaderResult {
+  const crlf = buffer.indexOf(CRLF);
+  if (crlf === -1) {
+    // No terminator yet. Reject as soon as the bytes can no longer be a
+    // header prefix: over the 107-byte budget, or not spelling "PROXY ".
+    if (buffer.length > PROXY_V1_MAX_HEADER_BYTES) {
+      return { status: 'invalid' };
+    }
+    const prefix = buffer.subarray(0, SIGNATURE.length).toString('ascii');
+    if (!SIGNATURE.startsWith(prefix)) {
+      return { status: 'invalid' };
+    }
+    return { status: 'incomplete' };
+  }
+
+  const headerEnd = crlf + CRLF.length;
+  if (headerEnd > PROXY_V1_MAX_HEADER_BYTES) {
+    return { status: 'invalid' };
+  }
+
+  // One slot per expected token plus a trailing slot that must stay
+  // empty: fewer than 6 tokens surfaces as `undefined`, more than 6
+  // populates `extra`.
+  const [signature, family, srcIp, dstIp, srcPort, dstPort, extra] = buffer
+    .subarray(0, crlf)
+    .toString('ascii')
+    .split(' ');
+  if (
+    family === undefined ||
+    srcIp === undefined ||
+    dstIp === undefined ||
+    srcPort === undefined ||
+    dstPort === undefined ||
+    extra !== undefined ||
+    signature !== 'PROXY'
+  ) {
+    return { status: 'invalid' };
+  }
+  const expectedFamily = family === 'TCP4' ? 4 : family === 'TCP6' ? 6 : 0;
+  if (expectedFamily === 0) {
+    // Spectrum always announces TCP4/TCP6; UNKNOWN (and anything else)
+    // is rejected so a header cannot be used to hide the source address.
+    return { status: 'invalid' };
+  }
+  if (isIP(srcIp) !== expectedFamily || isIP(dstIp) !== expectedFamily) {
+    return { status: 'invalid' };
+  }
+  if (!isValidPort(srcPort) || !isValidPort(dstPort)) {
+    return { status: 'invalid' };
+  }
+  return {
+    status: 'complete',
+    sourceIp: srcIp,
+    remainder: buffer.subarray(headerEnd),
+  };
+}
+
+function isValidPort(token: string): boolean {
+  if (!/^\d{1,5}$/u.test(token)) {
+    return false;
+  }
+  const value = Number.parseInt(token, 10);
+  return value >= 0 && value <= 65_535;
+}

package/apps/cf-tcp-container/terraform/spectrum.tf

@@ -1,9 +1,11 @@
 ###############################################################################
 # Cloudflare Spectrum config for the ServerlessIRCd TCP+TLS transport.
 #
-# Spectrum terminates TLS on port 6697 and forwards plaintext TCP to the
-# container origin. The origin is the Cloudflare Container (or external
-# compute) running the IRC core on port 6667.
+# TLS is end-to-end: clients terminate TLS with Spectrum on :6697 and
+# Spectrum re-encrypts to the origin, which runs its own TLS listener on
+# :6697 (see apps/cf-tcp-container/src/container-server.ts). No plaintext
+# IRC bytes ever cross the origin network, so a direct-reach attacker can
+# neither read PASS/AUTHENTICATE/PRIVMSG off the wire nor spoof them.
 #
 # Usage:
 #   terraform init
@@ -12,10 +14,26 @@
 #     -var origin_address=container-origin.example.com \
 #     -var hostname=irc.example.com
 #
-# The `tls = "flexible"` mode means TLS is terminated by Spectrum and the
-# connection to the origin is plaintext (matching the container's plaintext
-# TCP listener). For mTLS passthrough (SASL EXTERNAL via client cert), set
-# `tls = "full"` and configure the origin to present its own certificate.
+# The `tls = "full"` default means the origin must present a certificate
+# the TLS listener accepts (Let's Encrypt, BYO, or a Cloudflare Origin
+# Cert — see docs/Cloudflare-TCP-Deployment.md). For strict origin-cert
+# validation at the edge, set `tls_mode = "strict"`.
+#
+# Origin ingress lockdown (operator-side step): restrict ingress to the
+# origin's :6697 to Cloudflare's published IP ranges so the origin is only
+# reachable through Spectrum. On platforms with a firewall / security-group
+# primitive, source the ranges from the current Cloudflare IP list, e.g.:
+#
+#   data "cloudflare_lists" "all" {}
+#
+#   resource "cloudflare_list" "cf_ips" {
+#     account_id = var.cloudflare_account_id
+#     name       = "cloudflare-ips"
+#     kind       = "IP"
+#   }
+#
+# (Maintained list source: https://www.cloudflare.com/ips/ — keep the
+# firewall entries in sync when Cloudflare publishes range changes.)
 ###############################################################################
 
 variable "zone_id" {
@@ -30,8 +48,8 @@ variable "origin_address" {
 
 variable "origin_port" {
   type        = number
-  default     = 6667
-  description = "Port the TCP origin listens on (plaintext IRC)."
+  default     = 6697
+  description = "Port the origin's TLS listener serves (Spectrum re-encrypts to it)."
 }
 
 variable "hostname" {
@@ -48,8 +66,8 @@ variable "spectrum_port" {
 
 variable "tls_mode" {
   type        = string
-  default     = "flexible"
-  description = "Spectrum TLS mode: flexible (TLS→CF, plain→origin) or full (TLS end-to-end)."
+  default     = "full"
+  description = "Spectrum TLS mode: full (TLS end-to-end, the secure default) or strict (edge validates the origin cert)."
 
   validation {
     condition     = contains(["flexible", "full", "strict"], var.tls_mode)
@@ -75,6 +93,17 @@ resource "cloudflare_spectrum_application" "irc_tls" {
   ip_firewall        = true
   argo_smart_routing = true
 
+  # NOTE on TLS version pinning (1.2 / 1.3 only): Spectrum TCP
+  # applications CANNOT pin per-app TLS versions — the Cloudflare API
+  # and the terraform provider expose no `tls_versions` field for them
+  # (setting one fails `terraform plan` with "Unsupported argument"),
+  # and Cloudflare's fixed defaults apply at the edge: SSLv3 and TLS 1.0
+  # are never negotiable, TLS 1.1 is the floor. The explicit TLS 1.2/1.3
+  # pin for this deployment is therefore enforced on the origin leg in
+  # `apps/cf-tcp-container/src/container-server.ts`: the origin TLS
+  # listener terminates the re-encrypted Spectrum→origin connection
+  # with `minVersion: 'TLSv1.2'` / `maxVersion: 'TLSv1.3'`.
+
   # PROXY protocol v1 forwards the real client IP to the origin so the
   # container's admission gate (per-IP limits) sees the actual source.
   proxy_protocol = "v1"

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

@@ -161,6 +161,29 @@ describe('config-loader — container-specific knobs', () => {
     expect(cfg.server.operCreds).toEqual([{ user: 'admin', password: 'secret' }]);
   });
 
+  it('parses OPER_USER + OPER_SALT + OPER_HASH into a hashed operCred', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      OPER_USER: 'admin',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(cfg.server.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
+  it('prefers the hashed operCred form when both plaintext and hashed env vars are set', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      OPER_USER: 'admin',
+      OPER_PASSWORD: 'legacy',
+      OPER_SALT: 'c2FsdA==',
+      OPER_HASH: 'aGFzaA==',
+    });
+    expect(cfg.server.operCreds).toEqual([{ user: 'admin', salt: 'c2FsdA==', hash: 'aGFzaA==' }]);
+  });
+
   it('exercises the OPER_PASSWORD ?? "" default then rejects partial OPER_USER-only creds', () => {
     // The `?? ''` default for the missing OPER_PASSWORD is exercised, but
     // parseServerConfig then rejects the empty password — partial oper
@@ -265,3 +288,150 @@ describe('config-loader — container-specific knobs', () => {
     expect(cfg.server.serverName).toBe('irc.test');
   });
 });
+
+describe('config-loader — TLS termination at the origin', () => {
+  it('tls is undefined when no cert env is set (non-prod)', () => {
+    const cfg = loadContainerConfig({ SERVER_NAME: 'irc.test', NETWORK_NAME: 'TestNet' });
+    expect(cfg.tls).toBeUndefined();
+  });
+
+  it('reads TLS_CERT_PATH + TLS_KEY_PATH into a tls config with default port 6697', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      TLS_CERT_PATH: '/data/certs/tls.pem',
+      TLS_KEY_PATH: '/data/certs/tls.key',
+    });
+    expect(cfg.tls).toEqual({
+      certPath: '/data/certs/tls.pem',
+      keyPath: '/data/certs/tls.key',
+      port: 6697,
+    });
+  });
+
+  it('reads TLS_PORT override', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      TLS_CERT_PATH: '/certs/tls.pem',
+      TLS_KEY_PATH: '/certs/tls.key',
+      TLS_PORT: '7000',
+    });
+    expect(cfg.tls?.port).toBe(7000);
+  });
+
+  it('defaults TLS_PORT when TLS_PORT is empty or invalid', () => {
+    for (const bad of ['', 'not-a-number']) {
+      const cfg = loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        TLS_CERT_PATH: '/certs/tls.pem',
+        TLS_KEY_PATH: '/certs/tls.key',
+        TLS_PORT: bad,
+      });
+      expect(cfg.tls?.port).toBe(6697);
+    }
+  });
+
+  it('throws naming TLS_KEY_PATH when only TLS_CERT_PATH is set', () => {
+    expect(() =>
+      loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        TLS_CERT_PATH: '/certs/tls.pem',
+      }),
+    ).toThrowError(/TLS_KEY_PATH/u);
+  });
+
+  it('throws naming TLS_CERT_PATH when only TLS_KEY_PATH is set', () => {
+    expect(() =>
+      loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        TLS_KEY_PATH: '/certs/tls.key',
+      }),
+    ).toThrowError(/TLS_CERT_PATH/u);
+  });
+
+  it('refuses to start in prod-classified mode without TLS_CERT_PATH', () => {
+    expect(() =>
+      loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        NODE_ENV: 'production',
+      }),
+    ).toThrowError(/TLS_CERT_PATH/u);
+  });
+
+  it('refuses DEBUG_PLAINTEXT in prod-classified mode even with TLS configured', () => {
+    expect(() =>
+      loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        NODE_ENV: 'production',
+        TLS_CERT_PATH: '/certs/tls.pem',
+        TLS_KEY_PATH: '/certs/tls.key',
+        DEBUG_PLAINTEXT: 'localhost',
+      }),
+    ).toThrowError(/DEBUG_PLAINTEXT/u);
+  });
+
+  it('the prod no-TLS guard fires before the DEBUG_PLAINTEXT guard', () => {
+    expect(() =>
+      loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        NODE_ENV: 'production',
+        DEBUG_PLAINTEXT: 'localhost',
+      }),
+    ).toThrowError(/TLS_CERT_PATH/u);
+  });
+});
+
+describe('config-loader — plaintext debug listener gate', () => {
+  it('plaintextDebug is false when DEBUG_PLAINTEXT is unset', () => {
+    const cfg = loadContainerConfig({ SERVER_NAME: 'irc.test', NETWORK_NAME: 'TestNet' });
+    expect(cfg.plaintextDebug).toBe(false);
+  });
+
+  it('enables plaintextDebug for the exact flag value DEBUG_PLAINTEXT=localhost', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      DEBUG_PLAINTEXT: 'localhost',
+    });
+    expect(cfg.plaintextDebug).toBe(true);
+  });
+
+  it('forces the plaintext bind host to 127.0.0.1 when plaintextDebug is enabled', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      DEBUG_PLAINTEXT: 'localhost',
+      TCP_HOST: '0.0.0.0',
+    });
+    expect(cfg.plaintextDebug).toBe(true);
+    expect(cfg.tcpHost).toBe('127.0.0.1');
+  });
+
+  it('rejects DEBUG_PLAINTEXT values other than localhost', () => {
+    expect(() =>
+      loadContainerConfig({
+        SERVER_NAME: 'irc.test',
+        NETWORK_NAME: 'TestNet',
+        DEBUG_PLAINTEXT: '0.0.0.0',
+      }),
+    ).toThrowError(/localhost/u);
+  });
+
+  it('keeps the normal TCP_HOST default when plaintextDebug is disabled', () => {
+    const cfg = loadContainerConfig({
+      SERVER_NAME: 'irc.test',
+      NETWORK_NAME: 'TestNet',
+      TLS_CERT_PATH: '/certs/tls.pem',
+      TLS_KEY_PATH: '/certs/tls.key',
+    });
+    expect(cfg.plaintextDebug).toBe(false);
+    expect(cfg.tcpHost).toBe('0.0.0.0');
+  });
+});