serverless-ircd 0.3.0 → 0.5.0

package/README.md

@@ -4,22 +4,26 @@ A serverless IRC daemon where the IRC protocol logic lives in a pure,
 platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 (Durable Objects) or **AWS** (API Gateway WebSockets + Lambda + DynamoDB).
 
-One TypeScript codebase. Two serverless substrates. No S2S linking in v1.
+One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.3.0 (preview).** The pure protocol core, the
+> **Status:** **v0.5.0 (preview).** The pure protocol core, the
 > `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
 > the **Cloudflare Workers** adapter, and the **AWS** (API Gateway
 > WebSocket + Lambda + DynamoDB + CDK) adapter are all functional and
-> deployed to staging. v0.2.0 delivered SASL (`PLAIN`), token-bucket
-> flood control, server-password enforcement, hostmask cloaking,
-> connection admission, and IRCv3 chat history; v0.3.0 adds **OPER**
-> credential auth, the IRCv3 **TAGMSG** command, **RFC 1459
-> case-mapping**, a real **MOTD** in the registration welcome, a
-> **ChannelRegistryDO** (4th Cloudflare Durable Object) plus a
-> Cloudflare config loader, and **SASL account persistence** in
-> DynamoDB (scrypt hashes) with a `seed-aws-accounts` provisioning
-> tool. Remaining 0.x work: SASL `EXTERNAL` (mTLS) and production TLS
-> transport. See `CHANGELOG.md` for the per-release manifests.
+> deployed to staging. v0.4.0 shipped **dual transport**: both adapters
+> speak a real `irc+tls :6697` (TLS-over-TCP) surface for stock IRC
+> clients — Cloudflare via Spectrum + a Container origin, AWS via a
+> Network Load Balancer + Lambda streaming — alongside the WebSocket
+> path, plus **SASL `EXTERNAL` via mTLS** and a **Cloudflare D1-backed
+> SASL account store**. v0.5.0 completes the **protocol surface**: the
+> deferred IRC verbs (`KILL`, `REHASH`, `LUSERS` + `STATS`, `TRACE`,
+> `WALLOPS`, `SETNAME`) all land, and the S2S (`CONNECT` / `SQUIT` /
+> `LINKS`) and obsolete RFC 2812 (`SERVICE` / `SUMMON` / `USERS`) verbs
+> are formally dropped — every standard verb a modern client expects is
+> now implemented. Remaining 0.x work: the load/compat sweep
+> (10k-connection load test + client compatibility matrix) and a
+> required-`serverName` config gate. See `CHANGELOG.md` for the
+> per-release manifests.
 
 ---
 
@@ -70,6 +74,16 @@ Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
 `packages/in-memory-runtime` is the reference implementation of
 `IrcRuntime`, used by integration tests and the local CLI server.
 
+**Two transports, one core.** Both adapters accept WebSocket text frames
+(the serverless default) **and** a raw `irc+tls :6697` (TLS-over-TCP)
+surface for stock IRC clients. The TCP+TLS edge is platform-specific —
+Cloudflare **Spectrum** terminates TLS and forwards plaintext TCP to a
+stateful **Container** origin (`apps/cf-tcp-container`); AWS terminates
+TLS at a **Network Load Balancer** and invokes a **Lambda streaming**
+function. Both feed the same `ConnectionActor` through a `Transport`
+seam (`WsTextFrameTransport` vs. `TcpByteStreamTransport`); the
+parser/reducer/dispatch pipeline is identical.
+
 ### The key idea: pure reducers + location-of-authority
 
 Each command handler is a pure function:
@@ -111,12 +125,14 @@ ServerlessIRCd/
 │   └── aws-adapter/       Lambda + DynamoDB + AwsRuntime
 ├── apps/
 │   ├── cf-worker/         worker entry, DO migrations, bindings
-│   ├── aws-stack/         CDK stack (APIGW WS + Lambda + DynamoDB)
+│   ├── cf-tcp-container/  Spectrum + Container origin for irc+tls :6697
+│   ├── aws-stack/         CDK stack (APIGW WS + NLB + Lambda streaming + DynamoDB)
 │   └── local-cli/         runnable WS + TCP server using in-memory-runtime
 ├── tools/
 │   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
 │   ├── ci-hardening/      coverage-gate + mutation-config validators
-│   └── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
+│   ├── seed-aws-accounts.ts  scrypt-hash SASL PLAIN accounts into DynamoDB
+│   └── seed-cf-accounts.ts   scrypt-hash SASL PLAIN accounts into Cloudflare D1
 ├── pnpm-workspace.yaml    turbo.json   tsconfig.base.json
 └── README.md              CHANGELOG.md
 ```
@@ -127,7 +143,7 @@ ServerlessIRCd/
 
 | Concern          | Choice                                            |
 |------------------|---------------------------------------------------|
-| Runtime          | Node ≥ 20, ES2022+                                |
+| Runtime          | Node ≥ 24, ES2022+                                |
 | Package mgr      | pnpm workspaces                                   |
 | Build cache      | turbo                                             |
 | Language         | TypeScript (strict, `exactOptionalPropertyTypes`) |
@@ -141,9 +157,12 @@ ServerlessIRCd/
 
 ## Getting started
 
-Requires Node ≥ 20 and pnpm 9.
+Requires Node ≥ 24 and pnpm 11. Enable corepack so the `packageManager`
+pin is resolved automatically:
 
 ```bash
+corepack enable            # lets the pinned pnpm@11 run on any Node ≥ 24
+
 pnpm install              # install workspace deps
 
 pnpm build                # build all packages (turbo)
@@ -283,6 +302,42 @@ against any line-oriented WebSocket endpoint.
 
 ---
 
+## WebSocket transport (IRCv3 subprotocols)
+
+The WebSocket entry points (the local CLI, the Cloudflare Worker, and the
+AWS API Gateway `$connect` route) implement the
+[IRCv3 WebSocket support](https://ircv3.net/specs/websocket.html) subprotocol
+negotiation. A client advertises support by offering one of two registered
+subprotocols in its opening handshake's `Sec-WebSocket-Protocol` header:
+
+| Subprotocol        | Frames   | Notes                                            |
+|--------------------|----------|--------------------------------------------------|
+| `text.ircv3.net`   | UTF-8 text   | Lone surrogates → U+FFFD; binary frames rejected (close `1003`). |
+| `binary.ircv3.net` | binary       | UTF-8 encoded bytes; same framing as `text`.     |
+
+The server echoes back the first supported entry in client-preference order
+(in the `101` response's `Sec-WebSocket-Protocol` header). Once negotiated,
+the connection uses **spec framing**:
+
+- **One IRC message per WebSocket message** — a frame is never split on an
+  embedded line break. A single optional trailing `CR-LF` (or bare `LF`) is
+  stripped; the remainder is exactly one IRC line.
+- **No trailing `CR-LF` on the wire**, outbound or inbound.
+- **510-byte message budget** — the 512-byte IRC line limit minus the omitted
+  `CR-LF`. A message exceeding 510 bytes is a protocol violation and the
+  connection is closed with RFC 6455 code `1009` (Message Too Big).
+
+**Legacy fallback.** A client that offers no recognized subprotocol (or none
+at all) is still accepted, in **legacy mode**: frames are split on `\r\n` so
+older clients that concatenate several messages into one frame keep working,
+and the parser's existing 512-byte line cap applies. Nothing breaks until a
+client opts into a subprotocol. The in-tree
+[`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-to-a-deployed-stack-tcpws-forwarder)
+offers `binary.ircv3.net` upstream, so a stock TCP IRC client bridged to a
+deployed stack exercises the spec path end-to-end.
+
+---
+
 ## Testing strategy
 
 This project follows strict TDD (Red → Green → Refactor) — every reducer is
@@ -322,10 +377,35 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 - **Phase 4** — AWS adapter (APIGW WS + Lambda + DynamoDB + CDK).
   ✅ landed in **v0.2.0** (staging auto-deploy via CI; prod deploy is manual).
 - **Phase 5** — Observability, security hardening, config, CI gates.
-  ✅ landed (logger port, server-password, cloaking, admission limits,
-  coverage + mutation gates, OPER credential auth, and the Cloudflare
-  config loader all shipped across v0.2.0–v0.3.0).
-- **Phase 6** — Load testing, client compatibility sweep, ADRs.
+  ✅ landed across v0.2.0–v0.4.0 (logger port, server-password, cloaking,
+  admission limits, coverage + mutation gates, OPER credential auth, the
+  Cloudflare config loader, and AWS max-clients admission).
+- **Phase 6** — TLS hardening & raw TCP transport (`irc+tls :6697`).
+  ✅ landed in **v0.4.0**: generalized `ConnectionActor` transport seam,
+  Cloudflare Spectrum + Container origin, AWS NLB + Lambda streaming,
+  mTLS → SASL `EXTERNAL`, transport-parametrized contract suite, ADR-009.
+- **Phase 7** — Load testing (10k concurrent connections per platform)
+  and client compatibility sweep (WeeChat, HexChat, IRCCloud, TheLounge).
+  ⬳ pending; the dual-transport surface it needs
+  landed in v0.4.0.
+- **Phase 8 — PLAN-FIXES remediation.** ✅ landed across v0.3.0–v0.4.0
+  (MessageStore wired into all three adapters, AccountStore end-to-end,
+  the DynamoDB `Accounts` table decided, CF enumeration RPCs, AWS QUIT
+  fanout, `OPER` / `TAGMSG` / `WHOWAS`, RFC 1459 case-mapping, real
+  MOTD, config-driven server identity, AWS max-clients admission,
+  CF D1 SASL store, and a sweep of dead-code / stale-comment cleanup).
+- **Phase 9 — Runtime & tooling baseline.** ✅ landed in **v0.4.0**
+  (Node ≥ 24 / pnpm 11).
+- **Phase 10 — IRCv3 WebSocket extension.** ✅ landed in **v0.4.0**:
+  `text.ircv3.net` / `binary.ircv3.net` subprotocol negotiation +
+  per-message framing across the CF Worker, AWS APIGW, local CLI, and
+  `tcp-ws-forwarder` (510-byte budget, `1009`/`1003` close codes,
+  legacy fallback).
+- **Phase 11 — Deferred IRC verbs.** ✅ landed in **v0.5.0**: `KILL`,
+  `REHASH`, `LUSERS` + `STATS`, `TRACE`, `WALLOPS`, `SETNAME`, plus
+  the formal drop of the S2S (`CONNECT`/`SQUIT`/`LINKS`) and obsolete
+  RFC 2812 (`SERVICE`/`SUMMON`/`USERS`) verbs. The protocol surface is
+  feature-complete for modern clients.
 
 ---
 
@@ -333,25 +413,40 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
 
 **Core (RFC 1459/2812 subset):** registration (`NICK`/`USER`/`CAP`/`PASS`),
 `PING`/`PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`, `MODE` (user +
-channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`, `MOTD`,
-`AWAY`, `OPER` (credential auth → `o` user mode).
+channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`,
+`WHOWAS`, `MOTD`, `AWAY`, `OPER` (credential auth → `o` user mode), the
+query verbs `VERSION`, `TIME`, `ADMIN`, `INFO`, `USERHOST`, `ISON`, the
+network-statistics verbs `LUSERS` and `STATS` (`u` uptime + `l` link-info
+letters; unknown letters get the charybdis-style empty body), the
+routing-diagnostic verb `TRACE` (oper-gated per-connection detail), the
+realname-change verb `SETNAME`, and the oper verbs `KILL` (force-
+disconnect), `REHASH` (config reload via `IrcRuntime.reloadConfig()`),
+`WALLOPS` (global broadcast to every `+w` user).
+
+(Out of scope: the S2S verbs `CONNECT`/`SQUIT`/`LINKS` and the obsolete
+RFC 2812 verbs `SERVICE`/`SUMMON`/`USERS` are **formally dropped** as of
+v0.5.0 — they return `421 ERR_UNKNOWNCOMMAND`, and their reserved
+numerics have been removed. S2S linking is a PLAN non-goal.)
 
 **Channel modes:** `o v b i k l t n m s p`.
 **User modes:** `i`, `o` (local only), `w`, `s`.
 
 **IRCv3 extensions (negotiated via `CAP`):** `message-tags` (incl. the
 `TAGMSG` command), `server-time`, `account-tag`, `echo-message`, `batch`,
-`sasl` (`PLAIN` implemented, `EXTERNAL` reserved pending mTLS),
+`sasl` (`PLAIN` always; `EXTERNAL` via mTLS when a client-cert trust store
+is bound),
 `multi-prefix`, `away-notify`, `chghost`, `invite-notify`, `extended-join`,
 `draft/chathistory`, `safelist`. Case-insensitive nick/channel comparison
 uses **RFC 1459** case-mapping (advertised via `005 CASEMAPPING=rfc1459`).
 
 **Transport:** deployed stacks (Cloudflare Workers, AWS API Gateway) speak
-WebSocket text frames only (one IRC message per frame, with tolerance for
-`\r\n`-joined frames). The local CLI additionally binds a plain RFC TCP
-listener for direct IRC-client access. Stock TCP IRC clients reach a deployed
-WebSocket endpoint through the local
-[`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-to-a-deployed-stack-tcpws-forwarder).
+WebSocket text frames by default (one IRC message per frame, with tolerance
+for `\r\n`-joined frames), and optionally expose a raw `irc+tls :6697`
+(TLS-over-TCP) surface — Cloudflare via **Spectrum + Container**, AWS via a
+**Network Load Balancer + Lambda streaming** function. The local CLI
+additionally binds a plain RFC TCP listener for direct IRC-client access,
+and the [`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-to-a-deployed-stack-tcpws-forwarder)
+bridges a stock TCP client to a deployed WebSocket endpoint.
 
 ---
 
@@ -359,8 +454,15 @@ WebSocket endpoint through the local
 
 - `CHANGELOG.md` — per-release manifests (Keep a Changelog format), including
   the v0.2.0 work (AWS adapter, SASL, flood control, security hardening, CI
-  gates) and v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
-  ChannelRegistryDO, SASL account persistence).
+  gates), v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
+  ChannelRegistryDO, SASL account persistence), v0.4.0 (dual transport
+  `irc+tls :6697`, SASL `EXTERNAL`/mTLS, WHOWAS + remaining verbs, D1 account
+  store, Node 24/pnpm 11), and v0.5.0 (deferred IRC verbs `KILL` / `REHASH`
+  / `LUSERS` + `STATS` / `TRACE` / `WALLOPS` / `SETNAME`, plus the formal
+  drop of the S2S and obsolete RFC 2812 verbs).
+- `docs/Cloudflare-TCP-Deployment.md` and `docs/AWS-TCP-Deployment.md` —
+  end-to-end guides for the `:6697` TCP+TLS variants (Spectrum/Container on
+  CF, NLB + Lambda streaming on AWS), including mTLS trust-store setup.
 - `README.md` in each `packages/*` and `apps/*` — per-package notes (e.g.
   `packages/aws-adapter/README.md` for the DynamoDB-Local test setup,
   `apps/aws-stack/README.md` for CDK commands and localstack validation).

package/apps/aws-stack/README.md

@@ -1,18 +1,18 @@
 # `@serverless-ircd/aws-stack`
 
 AWS CDK v2 stack that provisions the AWS substrate for ServerlessIRCd
-(PLAN §6.2): an API Gateway v2 WebSocket API, a single Node 20 Lambda wired
+(PLAN §6.2): an API Gateway v2 WebSocket API, a single Node 24 Lambda wired
 to the `$connect` / `$disconnect` / `$default` routes, five DynamoDB tables
 (`Connections`, `ChannelMeta`, `ChannelMembers`, `Nicks`, `Accounts`), and the
 least-privilege IAM glue to let the Lambda read/write the tables and post back
 to connected clients via the management API.
 
 The Lambda handler is currently a stub (`{ statusCode: 200 }`); the real
-`AwsRuntime` dispatch lands in TICKET-040.
+`AwsRuntime` dispatch lands with the AWS runtime work.
 
 ## Prerequisites
 
-- Node.js 20+
+- Node.js 24+
 - pnpm (workspace root installs this package)
 - An AWS account with credentials configured
   (`aws configure`, `AWS_PROFILE`, or `SSO`)
@@ -32,7 +32,7 @@ Repo-level shortcuts (from the monorepo root):
 ```sh
 pnpm deploy:aws:staging
 pnpm deploy:aws:prod
-pnpm smoke:aws:staging   # deferred to TICKET-043
+pnpm smoke:aws:staging   # deferred (smoke harness not yet wired)
 ```
 
 ## Optional localstack validation
@@ -70,4 +70,5 @@ LOCALSTACK=1 pnpm test
 ## Handoff
 
 Lambda runtime logic, DynamoDB access patterns, and the `AwsRuntime`
-implementation are TICKET-040. The scheduler/sweeper is TICKET-041/042.
+implementation land with the AWS runtime work. The scheduler/sweeper is
+the EventBridge sweeper work.

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

@@ -38,11 +38,18 @@ const motdLines = Array.isArray(rawMotd)
     ? rawMotd.split('\n')
     : undefined;
 
+// TCP+TLS (irc+tls :6697) is opt-in: only provisioned when this context
+// var is supplied. When omitted, only the wss (API Gateway WebSocket)
+// path deploys (the default documented in docs/AWS-Deployment.md). See
+// docs/AWS-TCP-Deployment.md.
+const tcpTlsDomainName = app.node.tryGetContext('tcpTlsDomainName') as string | undefined;
+
 const stackProps: IrcStackProps = {
   environmentName,
   ...(serverName !== undefined ? { serverName } : {}),
   ...(networkName !== undefined ? { networkName } : {}),
   ...(motdLines !== undefined ? { motdLines } : {}),
+  ...(tcpTlsDomainName !== undefined ? { tcpTlsDomainName } : {}),
   ...(account && region ? { env: { account, region } } : {}),
 };
 

package/apps/aws-stack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.2.0",
+  "version": "0.5.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 +
@@ -17,9 +17,24 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 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 {
+  CfnIntegrationResponse,
+  WebSocketApi,
+  type WebSocketIntegration,
+  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 +44,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 +109,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 +151,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 +167,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 +181,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: {
@@ -163,9 +196,6 @@ export class IrcAwsStack extends Stack {
     }
 
     const webSocketApi = new WebSocketApi(this, 'IrcWsApi', {
-      connectRouteOptions: {
-        integration: new WebSocketLambdaIntegration('ConnectIntegration', handler),
-      },
       disconnectRouteOptions: {
         integration: new WebSocketLambdaIntegration('DisconnectIntegration', handler),
       },
@@ -174,6 +204,32 @@ export class IrcAwsStack extends Stack {
       },
     });
 
+    // The `$connect` route is added explicitly (rather than via
+    // `connectRouteOptions`) so the negotiated IRCv3 WebSocket subprotocol can
+    // be echoed back to the client. API Gateway selects the WebSocket
+    // subprotocol from the `$connect` integration response, so the route is
+    // configured to return a response and an `IntegrationResponse` maps the
+    // `Sec-WebSocket-Protocol` header from the Lambda's reply onto the
+    // handshake. The Lambda reads the client's offer, selects the first
+    // supported entry, and returns it in its response header (see
+    // `handleConnect` / `dispatch`).
+    const connectRoute = webSocketApi.addRoute('$connect', {
+      integration: new WebSocketLambdaIntegration('ConnectIntegration', handler),
+      returnResponse: true,
+    });
+    const connectIntegration = connectRoute.node.findChild(
+      'ConnectIntegration',
+    ) as WebSocketIntegration;
+    new CfnIntegrationResponse(this, 'ConnectSubprotocolResponse', {
+      apiId: webSocketApi.apiId,
+      integrationId: connectIntegration.integrationId,
+      integrationResponseKey: '$default',
+      responseParameters: {
+        'method.response.header.Sec-WebSocket-Protocol':
+          'integration.response.header.Sec-WebSocket-Protocol',
+      },
+    });
+
     // The stage name is intentionally NOT suffixed with the environment:
     // each environment is its own CloudFormation stack (and therefore its
     // own WebSocket API), so `prod` in every env resolves to a distinct
@@ -232,6 +288,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,