serverless-ircd 0.2.0 → 0.4.0

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "AWS CDK v2 stack: API Gateway v2 WebSocket API, Lambda, DynamoDB tables, least-privilege IAM",
   "license": "BSD-3-Clause",
@@ -19,8 +19,8 @@
     "smoke:staging": "node scripts/smoke.mjs"
   },
   "devDependencies": {
-    "aws-cdk": "^2.160.0",
-    "aws-cdk-lib": "^2.160.0",
+    "aws-cdk": "^2.262.0",
+    "aws-cdk-lib": "^2.262.0",
     "constructs": "^10.4.0",
     "@types/node": "^26.1.1",
     "@types/ws": "^8.5.13",
@@ -36,6 +36,6 @@
     "@serverless-ircd/aws-adapter": "workspace:*"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   }
 }

package/apps/aws-stack/src/aws-stack.ts

@@ -3,10 +3,10 @@
  *
  *   • 5 DynamoDB tables sourced from `@serverless-ircd/aws-adapter/cdk-table-defs`
  *     (Connections, ChannelMeta, ChannelMembers, Nicks, Accounts).
- *   • ONE Node 20 `NodejsFunction` bundling the AWS Lambda handler
+ *   • ONE Node 24 `NodejsFunction` bundling the AWS Lambda handler
  *     (`$connect` / `$disconnect` / `$default` dispatched on
  *     `event.requestContext.routeKey`).
- *   • ONE Node 20 `NodejsFunction` for the gone-connection sweeper
+ *   • ONE Node 24 `NodejsFunction` for the gone-connection sweeper
  *     (`sweeperHandler`), invoked on a fixed EventBridge schedule.
  *   • API Gateway v2 WebSocket API + auto-deploying `prod` stage.
  *   • Least-privilege IAM: scoped DynamoDB data-plane grants per table +
@@ -19,7 +19,17 @@ import { TABLE_DEFS } from '@serverless-ircd/aws-adapter/cdk-table-defs';
 import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
 import { WebSocketApi, WebSocketStage } from 'aws-cdk-lib/aws-apigatewayv2';
 import { WebSocketLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { Certificate } from 'aws-cdk-lib/aws-certificatemanager';
 import { Table } from 'aws-cdk-lib/aws-dynamodb';
+import { Vpc } from 'aws-cdk-lib/aws-ec2';
+import {
+  NetworkListener,
+  NetworkLoadBalancer,
+  NetworkTargetGroup,
+  Protocol,
+  TargetType,
+} from 'aws-cdk-lib/aws-elasticloadbalancingv2';
+import { LambdaTarget } from 'aws-cdk-lib/aws-elasticloadbalancingv2-targets';
 import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
 import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
 import { Runtime } from 'aws-cdk-lib/aws-lambda';
@@ -29,6 +39,9 @@ import type { Construct } from 'constructs';
 /** Stage name served by the auto-deploying WebSocket stage. */
 const STAGE_NAME = 'prod';
 
+/** IRC over TLS port served by the NLB listener (RFC-compliant :6697). */
+const IRC_TLS_PORT = 6697;
+
 /** Fixed rate for the gone-connection sweeper (matches the architecture doc). */
 const SWEEPER_SCHEDULE_RATE = Duration.minutes(5);
 
@@ -91,6 +104,21 @@ export interface IrcStackProps extends StackProps {
    * a `string[]` correctly. Defaults to a short two-line banner.
    */
   readonly motdLines?: string[];
+
+  /**
+   * Domain name for the TCP+TLS (IRC `:6697`) endpoint.
+   *
+   * When provided, the stack provisions:
+   *   - An ACM certificate for this domain.
+   *   - A Network Load Balancer with a `TLS` listener on `:6697`.
+   *   - A Lambda streaming target (the `nlbStreamHandler` export).
+   *
+   * The NLB terminates TLS at the edge and forwards plaintext TCP
+   * invocations to the Lambda. Connection identity is derived from
+   * NLB flow metadata (source IP + port). When omitted, only the wss
+   * (WebSocket) transport is deployed.
+   */
+  readonly tcpTlsDomainName?: string;
 }
 
 export class IrcAwsStack extends Stack {
@@ -118,11 +146,11 @@ export class IrcAwsStack extends Stack {
     );
 
     const handler = new NodejsFunction(this, 'IrcHandler', {
-      runtime: Runtime.NODEJS_20_X,
+      runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'handler',
       bundling: {
-        // AWS SDK v3 is in the Lambda Node 20 runtime; exclude it so the
+        // AWS SDK v3 is in the Lambda Node 24 runtime; exclude it so the
         // bundle stays small. irc-core / irc-server are bundled because
         // they are first-party.
         externalModules: ['@aws-sdk/*'],
@@ -134,7 +162,7 @@ export class IrcAwsStack extends Stack {
     // Catches connections that vanished without APIGW emitting $disconnect;
     // see packages/aws-adapter/src/handlers/sweeper.ts.
     const sweeper = new NodejsFunction(this, 'IrcSweeper', {
-      runtime: Runtime.NODEJS_20_X,
+      runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'sweeperHandler',
       bundling: {
@@ -148,7 +176,7 @@ export class IrcAwsStack extends Stack {
     // packages/aws-adapter/src/handlers/ping-checker.ts. The Cloudflare
     // adapter implements the equivalent flow inside `ConnectionDO.alarm()`.
     const pingChecker = new NodejsFunction(this, 'IrcPingChecker', {
-      runtime: Runtime.NODEJS_20_X,
+      runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'pingCheckerHandler',
       bundling: {
@@ -232,6 +260,90 @@ export class IrcAwsStack extends Stack {
       targets: [new LambdaFunction(pingChecker)],
     });
 
+    // -------------------------------------------------------------------------
+    // TCP+TLS adapter via Network Load Balancer.
+    //
+    // An NLB with a `TLS` listener terminates TLS at the edge and invokes a
+    // Lambda streaming function (`nlbStreamHandler`) for each chunk of client
+    // data. The Lambda response body is streamed back over the held-open TCP
+    // connection. Only provisioned when `tcpTlsDomainName` is supplied.
+    // -------------------------------------------------------------------------
+    if (props.tcpTlsDomainName !== undefined) {
+      const tcpTlsDomain = props.tcpTlsDomainName;
+
+      // ACM certificate for TLS termination at the NLB.
+      const cert = new Certificate(this, 'TlsCertificate', {
+        domainName: tcpTlsDomain,
+      });
+
+      // NLB requires a VPC. A dedicated two-AZ VPC keeps the NLB path
+      // isolated from the serverless (APIGW) path which has no VPC.
+      // Cast bypasses a CDK `exactOptionalPropertyTypes` friction between
+      // the concrete `Vpc` and the `IVpc` interface (optional vs required
+      // properties in the CDK jsii layer).
+      const vpc = new Vpc(this, 'NlbVpc', {
+        maxAzs: 2,
+        natGateways: 0,
+      }) as never;
+
+      // The NLB streaming Lambda — same entry, different handler export.
+      // Shares the bundled aws-adapter code (tree-shaken to the nlb-stream
+      // path by esbuild at synth time). Reuses the same DynamoDB tables,
+      // server identity, and MANAGEMENT_URL as the wss handler.
+      const nlbHandler = new NodejsFunction(this, 'IrcNlbHandler', {
+        runtime: Runtime.NODEJS_24_X,
+        entry: handlerEntry(),
+        handler: 'nlbStreamHandler',
+        bundling: {
+          externalModules: ['@aws-sdk/*'],
+        },
+      });
+
+      // Grant the NLB handler the same DynamoDB access as the wss handler.
+      for (const table of Object.values(tables)) {
+        table.grantReadWriteData(nlbHandler);
+      }
+
+      // Inject the same table names, server identity, and management URL.
+      for (const logicalId of Object.keys(TABLE_DEFS)) {
+        const envName = `${logicalId.toUpperCase()}_TABLE`;
+        nlbHandler.addEnvironment(envName, prefixedTableName(environmentName, logicalId));
+      }
+      nlbHandler.addEnvironment('SERVER_NAME', serverName);
+      nlbHandler.addEnvironment('NETWORK_NAME', networkName);
+      nlbHandler.addEnvironment('MOTD', motd);
+      nlbHandler.addEnvironment('MANAGEMENT_URL', stage.callbackUrl);
+
+      const nlb = new NetworkLoadBalancer(this, 'IrcNlb', {
+        vpc,
+        internetFacing: true,
+      });
+
+      const targetGroup = new NetworkTargetGroup(this, 'IrcNlbTargetGroup', {
+        port: IRC_TLS_PORT,
+        protocol: Protocol.TCP,
+        targetType: TargetType.LAMBDA,
+        targets: [new LambdaTarget(nlbHandler)],
+      });
+
+      new NetworkListener(this, 'IrcNlbTlsListener', {
+        // Cast bypasses a CDK `exactOptionalPropertyTypes` friction between
+        // the concrete `NetworkLoadBalancer` and the `INetworkLoadBalancer`
+        // interface (optional vs required `securityGroups`).
+        loadBalancer: nlb as never,
+        port: IRC_TLS_PORT,
+        protocol: Protocol.TLS,
+        certificates: [{ certificateArn: cert.certificateArn }],
+        defaultTargetGroups: [targetGroup],
+      });
+
+      new CfnOutput(this, 'TcpConnectUrl', {
+        description:
+          'TCP+TLS connect endpoint (irc+tls :6697). Connect via the NLB DNS name on port 6697.',
+        value: `${nlb.loadBalancerDnsName}:6697`,
+      });
+    }
+
     new CfnOutput(this, 'ConnectUrl', {
       description: 'WebSocket connect endpoint clients dial (wss).',
       value: stage.url,

package/apps/aws-stack/tests/stack.test.ts

@@ -4,7 +4,7 @@
  * These are the primary red→green tests for the infrastructure ticket:
  * they assert the exact CloudFormation shape that `cdk synth` must
  * produce — five DynamoDB tables with the PLAN §4 schema, a single
- * Node 20 Lambda wired to all three WebSocket routes, the API Gateway
+ * Node 24 Lambda wired to all three WebSocket routes, the API Gateway
  * v2 WebSocket API, the two stack outputs, and a least-privilege guard
  * that no IAM policy grants `Resource: '*'` or `Action: '*'`.
  *
@@ -157,10 +157,10 @@ describe('IrcAwsStack — Lambda', () => {
     template.resourceCountIs('AWS::Lambda::Function', 3);
   });
 
-  it('targets the Node 20 runtime for every function', () => {
+  it('targets the Node 24 runtime for every function', () => {
     const { template } = makeTemplate();
     template.allResourcesProperties('AWS::Lambda::Function', {
-      Runtime: 'nodejs20.x',
+      Runtime: 'nodejs24.x',
     });
   });
 });
@@ -462,3 +462,98 @@ describe('IrcAwsStack — server identity props (configurable deploy identity)',
     ).toBeUndefined();
   });
 });
+
+describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
+  /** Makes a template WITH the tcpTlsDomainName prop (enables the NLB path). */
+  function makeTcpTemplate(domainName = 'irc.example.com'): {
+    app: App;
+    stack: Stack;
+    template: Template;
+  } {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      environmentName: 'staging',
+      tcpTlsDomainName: domainName,
+    });
+    const template = Template.fromStack(stack);
+    return { app, stack, template };
+  }
+
+  describe('when tcpTlsDomainName is omitted (default)', () => {
+    it('creates no Network Load Balancer', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::ElasticLoadBalancingV2::LoadBalancer', 0);
+    });
+
+    it('creates no ACM certificate', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::CertificateManager::Certificate', 0);
+    });
+
+    it('still creates exactly three Lambda functions', () => {
+      const { template } = makeTemplate();
+      template.resourceCountIs('AWS::Lambda::Function', 3);
+    });
+  });
+
+  describe('when tcpTlsDomainName is provided', () => {
+    it('creates a Network Load Balancer', () => {
+      const { template } = makeTcpTemplate();
+      template.resourceCountIs('AWS::ElasticLoadBalancingV2::LoadBalancer', 1);
+    });
+
+    it('creates an ACM certificate for the provided domain', () => {
+      const { template } = makeTcpTemplate('irc.my.net');
+      template.hasResourceProperties('AWS::CertificateManager::Certificate', {
+        DomainName: 'irc.my.net',
+      });
+    });
+
+    it('creates a TLS listener on port 6697', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::ElasticLoadBalancingV2::Listener', {
+        Port: 6697,
+        Protocol: 'TLS',
+      });
+    });
+
+    it('creates a target group with Lambda as the target type', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::ElasticLoadBalancingV2::TargetGroup', {
+        TargetType: 'lambda',
+      });
+    });
+
+    it('creates a fourth Lambda function for the NLB streaming handler', () => {
+      const { template } = makeTcpTemplate();
+      template.resourceCountIs('AWS::Lambda::Function', 4);
+    });
+
+    it('targets the Node 24 runtime for the NLB handler Lambda', () => {
+      const { template } = makeTcpTemplate();
+      template.allResourcesProperties('AWS::Lambda::Function', {
+        Runtime: 'nodejs24.x',
+      });
+    });
+
+    it('grants the NLB permission to invoke the handler Lambda', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::Lambda::Permission', {
+        Principal: 'elasticloadbalancing.amazonaws.com',
+      });
+    });
+
+    it('still creates the wss WebSocket API (both transports coexist)', () => {
+      const { template } = makeTcpTemplate();
+      template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+        ProtocolType: 'WEBSOCKET',
+      });
+    });
+
+    it('emits a TcpConnectUrl output pointing at the NLB DNS', () => {
+      const { template } = makeTcpTemplate();
+      const outputs = template.toJSON().Outputs ?? {};
+      expect(outputs).toHaveProperty('TcpConnectUrl');
+    });
+  });
+});

package/apps/cf-tcp-container/Dockerfile

@@ -0,0 +1,69 @@
+# Cloudflare Container / Docker image for the ServerlessIRCd TCP origin.
+#
+# Spectrum terminates TLS at the edge and forwards plaintext TCP to this
+# container. The container runs the IRC core (ConnectionActor +
+# InMemoryRuntime) over the TcpByteStreamTransport seam on port 6667.
+#
+# Build context: the repository root (monorepo). The container needs the
+# irc-core, irc-server, and in-memory-runtime packages.
+#
+#   docker build -f apps/cf-tcp-container/Dockerfile -t sirc-tcp-origin .
+#   docker run -p 6667:6667 -e SERVER_NAME=irc.example.com sirc-tcp-origin
+#
+# For Cloudflare Containers deployment, the same image is referenced from
+# wrangler.toml.
+
+FROM node:24-slim AS builder
+
+WORKDIR /app
+
+# Install pnpm.
+RUN corepack enable && corepack prepare pnpm@11.17.0 --activate
+
+# Copy workspace config + lockfile first for layer caching.
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY tsconfig.base.json ./
+
+# Copy all workspace packages needed for the build.
+COPY packages/irc-core/ packages/irc-core/
+COPY packages/irc-server/ packages/irc-server/
+COPY packages/in-memory-runtime/ packages/in-memory-runtime/
+COPY apps/cf-tcp-container/ apps/cf-tcp-container/
+
+# Install dependencies and build.
+RUN pnpm install --frozen-lockfile
+RUN pnpm --filter '@serverless-ircd/irc-core' build && \
+    pnpm --filter '@serverless-ircd/irc-server' build && \
+    pnpm --filter '@serverless-ircd/in-memory-runtime' build && \
+    pnpm --filter '@serverless-ircd/cf-tcp-container' build
+
+# --- Runtime stage ---
+FROM node:24-slim AS runtime
+
+WORKDIR /app
+
+# Copy built artifacts + package manifests (for workspace resolution).
+COPY --from=builder /app/package.json /app/pnpm-workspace.yaml ./
+COPY --from=builder /app/packages/irc-core/package.json packages/irc-core/
+COPY --from=builder /app/packages/irc-core/dist/ packages/irc-core/dist/
+COPY --from=builder /app/packages/irc-server/package.json packages/irc-server/
+COPY --from=builder /app/packages/irc-server/dist/ packages/irc-server/dist/
+COPY --from=builder /app/packages/in-memory-runtime/package.json packages/in-memory-runtime/
+COPY --from=builder /app/packages/in-memory-runtime/dist/ packages/in-memory-runtime/dist/
+COPY --from=builder /app/apps/cf-tcp-container/package.json apps/cf-tcp-container/
+COPY --from=builder /app/apps/cf-tcp-container/dist/ apps/cf-tcp-container/dist/
+
+# Production install (only the workspace deps, no devDependencies).
+RUN corepack enable && corepack prepare pnpm@11.17.0 --activate && \
+    pnpm install --frozen-lockfile --prod
+
+# Persistence volume: Spectrum-origin channel state survives restarts.
+VOLUME ["/data"]
+
+EXPOSE 6667
+
+ENV TCP_PORT=6667
+ENV TCP_HOST=0.0.0.0
+ENV PERSISTENCE_PATH=/data/state.json
+
+CMD ["node", "--enable-source-maps", "apps/cf-tcp-container/dist/main.js"]

package/apps/cf-tcp-container/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@serverless-ircd/cf-tcp-container",
+  "version": "0.4.0",
+  "private": true,
+  "description": "Cloudflare Container TCP origin for the irc+tls :6697 transport — Spectrum terminates TLS at the edge, this container runs the IRC core over plaintext TCP",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/main.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "start": "node --enable-source-maps ./dist/main.js",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:prod": "wrangler deploy",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "dependencies": {
+    "@serverless-ircd/in-memory-runtime": "workspace:*",
+    "@serverless-ircd/irc-core": "workspace:*",
+    "@serverless-ircd/irc-server": "workspace:*"
+  },
+  "devDependencies": {
+    "@cloudflare/containers": "^0.1.0",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0",
+    "wrangler": "4.112.0"
+  }
+}

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

@@ -0,0 +1,145 @@
+/**
+ * CF TCP container config loader.
+ *
+ * Adapts platform-native env vars (Cloudflare Container runtime env or
+ * Docker/Kubernetes env) into the shared `ServerConfigSchema` from
+ * `irc-core`, plus a handful of container-specific knobs (TCP port/host,
+ * persistence path, snapshot interval).
+ *
+ * Mirrors `packages/cf-adapter/src/config-loader.ts` in shape — both
+ * adapters consume the same `ServerConfigSchema`; only the env-mapping
+ * and the extra container knobs differ.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * The env vars this loader reads. Every field is a string (the platform
+ * env shape); numeric fields are coerced inside {@link loadContainerConfig}.
+ */
+export interface ContainerConfigEnv {
+  SERVER_NAME?: string;
+  NETWORK_NAME?: string;
+  SERVER_VERSION?: string;
+  CREATED_AT?: string;
+  MOTD_LINES?: string;
+  MAX_CLIENTS?: string;
+  CHANNEL_PREFIXES?: string;
+  OPER_USER?: string;
+  OPER_PASSWORD?: string;
+  MAX_CHANNELS_PER_USER?: string;
+  MAX_TARGETS_PER_COMMAND?: string;
+  NICK_LEN?: string;
+  CHANNEL_LEN?: string;
+  TOPIC_LEN?: string;
+  MAX_LIST_ENTRIES?: string;
+  QUIT_MESSAGE?: string;
+  SASL_ACCOUNTS?: string;
+  /** Container-specific: plaintext TCP port Spectrum forwards to. */
+  TCP_PORT?: string;
+  /** Container-specific: bind address (default 0.0.0.0 for Spectrum origin). */
+  TCP_HOST?: string;
+  /** Container-specific: path to the persistence snapshot file. */
+  PERSISTENCE_PATH?: string;
+  /** Container-specific: auto-snapshot interval in milliseconds. */
+  SNAPSHOT_INTERVAL_MS?: string;
+}
+
+/** Fully-resolved container config: IRC server config + container knobs. */
+export interface ContainerConfig {
+  server: ParsedServerConfig;
+  tcpPort: number;
+  tcpHost: string;
+  persistencePath: string | undefined;
+  snapshotIntervalMs: number;
+}
+
+const DEFAULT_TCP_PORT = 6667;
+const DEFAULT_TCP_HOST = '0.0.0.0';
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
+
+/** Default server name / network when env vars are missing. */
+const DEFAULT_SERVER_NAME = 'irc.example.com';
+const DEFAULT_NETWORK_NAME = 'ExampleNet';
+
+/**
+ * Loads and validates the IRC server config plus container-specific knobs
+ * from a platform env. Throws on an invalid IRC config (bad port number,
+ * missing required fields, etc.) so boot fails fast.
+ */
+export function loadContainerConfig(env: ContainerConfigEnv): ContainerConfig {
+  const server = parseServerConfig(buildServerInput(env));
+  return {
+    server,
+    tcpPort: parseIntOrDefault(env.TCP_PORT, DEFAULT_TCP_PORT),
+    tcpHost: env.TCP_HOST?.trim() || DEFAULT_TCP_HOST,
+    persistencePath:
+      env.PERSISTENCE_PATH !== undefined && env.PERSISTENCE_PATH.length > 0
+        ? env.PERSISTENCE_PATH
+        : undefined,
+    snapshotIntervalMs: parseIntOrDefault(env.SNAPSHOT_INTERVAL_MS, DEFAULT_SNAPSHOT_INTERVAL_MS),
+  };
+}
+
+function parseIntOrDefault(raw: string | undefined, def: number): number {
+  if (raw === undefined || raw.trim().length === 0) return def;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) ? n : def;
+}
+
+function buildServerInput(env: ContainerConfigEnv): Record<string, unknown> {
+  const input: Record<string, unknown> = {
+    serverName: env.SERVER_NAME ?? DEFAULT_SERVER_NAME,
+    networkName: env.NETWORK_NAME ?? DEFAULT_NETWORK_NAME,
+  };
+  if (env.SERVER_VERSION !== undefined) input.serverVersion = env.SERVER_VERSION;
+  if (env.CREATED_AT !== undefined) input.createdAt = parseCreatedAt(env.CREATED_AT);
+  if (env.MOTD_LINES !== undefined && env.MOTD_LINES.length > 0) {
+    input.motdLines = env.MOTD_LINES.split('\n');
+  }
+  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 ?? '' }];
+  }
+  if (env.MAX_CHANNELS_PER_USER !== undefined) {
+    input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);
+  }
+  if (env.MAX_TARGETS_PER_COMMAND !== undefined) {
+    input.maxTargetsPerCommand = Number.parseInt(env.MAX_TARGETS_PER_COMMAND, 10);
+  }
+  if (env.NICK_LEN !== undefined) input.nickLen = Number.parseInt(env.NICK_LEN, 10);
+  if (env.CHANNEL_LEN !== undefined) input.channelLen = Number.parseInt(env.CHANNEL_LEN, 10);
+  if (env.TOPIC_LEN !== undefined) input.topicLen = Number.parseInt(env.TOPIC_LEN, 10);
+  if (env.MAX_LIST_ENTRIES !== undefined) {
+    input.maxListEntries = Number.parseInt(env.MAX_LIST_ENTRIES, 10);
+  }
+  if (env.QUIT_MESSAGE !== undefined) input.quitMessage = env.QUIT_MESSAGE;
+  if (env.SASL_ACCOUNTS !== undefined && env.SASL_ACCOUNTS.length > 0) {
+    input.saslAccounts = parseSaslAccountsLines(env.SASL_ACCOUNTS);
+  }
+  return input;
+}
+
+function parseCreatedAt(raw: string): string | number {
+  if (/^\d+$/.test(raw.trim())) {
+    const n = Number(raw.trim());
+    if (Number.isFinite(n)) return n;
+  }
+  return raw;
+}
+
+function parseSaslAccountsLines(raw: string): Array<{ username: string; password: string }> {
+  const out: Array<{ username: string; password: string }> = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    const username = trimmed.slice(0, sep);
+    const password = trimmed.slice(sep + 1);
+    if (username.length === 0 || password.length === 0) continue;
+    out.push({ username, password });
+  }
+  return out;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Cloudflare Container DO for the IRC TCP origin.
+ *
+ * The container runs the IRC core as a plaintext TCP server (port 6667).
+ * Spectrum terminates TLS on :6697 and forwards plaintext to this
+ * container. The DO wrapper provides persistent identity and lifecycle
+ * management.
+ */
+
+import { Container } from '@cloudflare/containers';
+
+export class IrcTcpOrigin extends Container {
+  // The IRC TCP server port inside the container.
+  defaultPort = 6667;
+  requiredPorts = [6667];
+
+  // Keep the container alive for long-lived IRC connections.
+  sleepAfter = '2h';
+
+  enableInternet = true;
+
+  envVars = {
+    TCP_PORT: '6667',
+    TCP_HOST: '0.0.0.0',
+  };
+
+  onStart(): void {
+    console.log('IrcTcpOrigin container started');
+  }
+
+  onStop(): void {
+    console.log('IrcTcpOrigin container stopping');
+  }
+
+  onError(error: Error): void {
+    console.error('IrcTcpOrigin container error:', error);
+  }
+}