serverless-ircd 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -10,6 +10,181 @@ For the release process itself — versioning policy, pre-release checklist,
 cutting a tag, rolling back — see [`docs/release.md`](docs/release.md).
 Cross-reference `progress.md` / `tickets.md` for per-ticket detail.
 
+## [0.5.0] - 2026-08-02
+
+The headline is **protocol completion**: the deferred IRC verbs land
+(Phase 11), and the S2S / obsolete RFC 2812 verbs are **formally
+dropped** rather than left "deferred". With this release every standard
+IRC verb a modern client expects is implemented — the only remaining
+`421 ERR_UNKNOWNCOMMAND` paths are the deliberately-unimplemented S2S
+and obsolete verbs. The roadmap's 0.x protocol surface is complete;
+what remains is the load/compat sweep (10k-connection load test +
+client compatibility matrix) and the required-`serverName` config gate.
+
+### Added — Deferred IRC verbs (`@serverless-ircd/irc-core`, `@serverless-ircd/irc-server`)
+
+Six Phase 11 tickets light up the remaining command surface. Each ships
+a pure reducer, an actor route case (no more `421`), new numerics in
+`protocol/numerics.ts`, and unit + actor coverage. (The remaining two
+Phase 11 tickets are drops — see below.)
+
+- **`KILL`** (oper-gated force-disconnect): `KILL <nick>
+  <comment>` resolves the target via the nick registry + a live
+  connection fetch (mirroring WHOIS), checks the oper gate (`481
+  ERR_NOPRIVILEGES`), and emits a `Disconnect` effect carrying the
+  classic `Killed (<oper> (<comment>))` reason. Peer `QUIT` fanout in
+  the target's shared channels happens via the runtime's existing
+  `disconnect` path. Missing params → `461`; unknown nick → `401`; an
+  oper may `KILL` themselves (RFC-permitted).
+  **Platform asymmetry:** on Cloudflare the `disconnect` RPC closes the
+  target DO's socket immediately; on AWS a `$default` Lambda invocation
+  cannot close a *remote* APIGW WebSocket, so the target's
+  live socket only closes on its next `$disconnect` / sweeper cycle —
+  the QUIT fanout to peers still fires. The reducer is identical; the
+  difference is the bound runtime's `disconnect` semantics.
+- **`REHASH`** (oper-gated config reload): emits `382
+  RPL_REHASHING :<source>` and re-fetches `ServerConfig` from the
+  adapter's bound source via a new `IrcRuntime.reloadConfig()` port
+  method. The refreshed value swaps into the actor's live config
+  reference so subsequent commands observe it (rotated oper passwords,
+  new MOTD source, etc.). On reload failure the previous config stays
+  in effect and a graceful error-suffixed `382` follows — the oper is
+  **not** disconnected (a bad store read must never sever a live link).
+  Already-open connections keep their negotiated caps and registration;
+  transport/TLS reload requires a redeploy.
+- **`LUSERS` + `STATS`** (network statistics): backed by a
+  new async `ServerStats` port (`getStats(): Promise<ServerStatsSnapshot>`)
+  and an `InMemoryStats` reference impl. `LUSERS` emits the full
+  `251`–`255` sequence (only the non-zero counts, per RFC) plus the
+  optional `265` / `266` local/global counts. `STATS <query>` supports
+  the `u` (uptime, `242 RPL_STATSUPTIME`) and `l` (link info,
+  `211 RPL_STATSLINKINFO`) letters; unknown letters get the
+  charybdis-style empty body terminated by `219 RPL_ENDOFSTATS`. A
+  `<server>` argument that does not match the local server (case-
+  insensitive) yields `402 ERR_NOSUCHSERVER` (single-server network —
+  S2S aggregation is a PLAN non-goal). The `computeStatsSnapshot`
+  helper centralizes the oper/invisible/unknown classification so each
+  adapter's backend only has to gather raw counts.
+- **`TRACE`** (routing diagnostics): in a single-server
+  serverless IRCd `TRACE` collapses to a local-server line + the
+  `262 RPL_ENDOFTRACE` terminator. Per-connection `204
+  RPL_TRACEOPERATOR` / `205 RPL_TRACEUSER` detail is **oper-gated** —
+  non-opers see only the server line + `262` (no enumeration of `+i`
+  users they don't share a channel with). `TRACE <server>` where
+  `<server>` is not the local server → `402`.
+- **`WALLOPS`** (oper broadcast): `WALLOPS :<message>` is
+  oper-only to send (modern ircd convention — non-oper → `481`);
+  delivery fans out to every connection whose `+w` user mode is set via
+  a new `BroadcastWallops` effect interpreted by the runtime's
+  `broadcastWallops` method (global cross-connection fanout, not
+  channel-scoped). The originator is always excluded (skip-self,
+  matching NOTICE/PRIVMSG semantics). Empty message → `461`. The `+w`
+  user mode was already accepted by `MODE` and advertised in `004
+  RPL_MYINFO`; this lights up the consumer.
+- **`SETNAME`** (realname change): `SETNAME :<realname>`
+  updates `state.realname` so a subsequent `WHOIS` reflects the new
+  value in `311 RPL_WHOISUSER`. No broadcast is emitted in v1 (there
+  is no standard IRCv3 cap for relaying a realname change — a
+  `draft/setname` relay is a documented follow-up). Empty/missing
+  realname → `461`; the registration-time realname length cap applies.
+
+### Changed — S2S & obsolete verbs formally dropped (`@serverless-ircd/irc-core`)
+
+The remaining two Phase 11 tickets convert the "deferred" framing into
+an explicit **drop**. There is no behaviour change on the wire — the verbs
+already returned `421 ERR_UNKNOWNCOMMAND` — but the framing, comments,
+and reserved numerics are cleaned up so the codebase no longer carries
+dead scaffolding.
+
+- **S2S verbs** (`CONNECT`, `SQUIT`, `LINKS`): dropped as a PLAN
+  non-goal (single-server serverless IRCd; no mesh to connect, split,
+  or list). The now-unused numerics `RPL_LINKS (364)`,
+  `RPL_ENDOFLINKS (365)`, and `ERR_CANTKILLSERVER (483)` are removed
+  from `numerics.ts` and its auto-derived `numericToName` reverse map.
+  `ERR_NOSUCHSERVER (402)` is retained — `LUSERS` / `STATS` / `TRACE`
+  use it for remote-server gating.
+- **Obsolete RFC 2812 verbs** (`SERVICE`, `SUMMON`, `USERS`): dropped
+  (never widely implemented; no modern client uses them). The now-unused
+  numerics `RPL_YOURESERVICE (383)`, `ERR_NOSUCHSERVICE (408)`,
+  `ERR_SUMMONDISABLED (445)`, and `ERR_USERSDISABLED (446)` are removed.
+- The `actor.ts` default-branch triage comment was rewritten: the
+  six verbs are documented as **deliberately unimplemented** rather
+  than "deferred".
+- Source-level regression guards
+  (`packages/irc-core/tests/dropped-s2s-and-obsolete-verbs.test.ts`)
+  and a behaviour guard in `actor.test.ts` (the verbs still emit
+  `421`) pin the drop so the numerics or the "deferred" framing cannot
+  creep back in.
+
+### Added — Runtime ports for the new verbs
+
+- **`ServerStats` port** (`packages/irc-core/src/ports.ts`): async
+  `getStats()` returning `ServerStatsSnapshot` (users / invisible /
+  opers / unknown / channels / servers / local+global conn counts /
+  uptime anchor). Asynchronous because the aggregation crosses every
+  connection and channel — it cannot be pre-loaded into a synchronous
+  view the way MOTD or a credential table can. Each adapter implements
+  it against its authoritative store; `InMemoryStats` is the reference
+  impl. The `computeStatsSnapshot` helper holds the shared
+  classification logic (oper / invisible / unknown).
+- **`reloadConfig()` on `IrcRuntime`** (`packages/irc-server/src/runtime.ts`):
+  request/response port method the `REHASH` route calls to re-fetch
+  `ServerConfig` from the adapter's bound source (CF: KV/secret env;
+  AWS: Secrets Manager/SSM env; local-cli: the config file/options).
+  Modelled as a runtime method rather than a fire-and-forget effect
+  because the refreshed value must come back to the actor.
+
+### ⚠️ Migration required
+
+- **For adapter authors wiring the new ports.** `ServerStats` and
+  `reloadConfig` are optional at the type level (the actor falls back
+  to a zero-count snapshot when no `ServerStats` is bound, and
+  `REHASH` still emits `382` even if `reloadConfig` rejects — the
+  previous config is retained). To surface real counts and live
+  reloads, each adapter wires its own backend. No Durable-Object
+  persisted-state schema change (`PERSISTED_STATE_VERSION` stays `1`);
+  code rollback across this release is safe.
+- No toolchain change. Node ≥ 24 / pnpm 11 (from v0.4.0) still apply.
+
+### Known limitations
+
+- Same as v0.4.0's transport limits: the **CF TCP path requires
+  Cloudflare Spectrum (Enterprise tier)** plus a stateful Container
+  origin; the **AWS TCP path** uses NLB + Lambda streaming and is
+  subject to Lambda idle-timeout / stream-duration limits. The
+  WebSocket path remains the zero-extra-deps default.
+- **mTLS (for SASL `EXTERNAL`) requires a custom domain + uploaded
+  CA/trust-store** on both platforms and is not enabled by default.
+- `serverName` still defaults to the `irc.example.com` placeholder when
+  an adapter config omits it (pending).
+- `STATS` ships the `u` + `l` query letters; the full RFC matrix
+  (`k`, `K`, `q`, `g`, `x`, `z`, …) is intentionally out of scope for
+  v1 — unknown letters get the charybdis-style empty body + `219`.
+- Load testing (10k concurrent connections) and the client
+  compatibility sweep (WeeChat / HexChat / IRCCloud / TheLounge)
+  remain pending.
+- **Local coverage instrumentation on the Cloudflare-backed packages
+  (`@serverless-ircd/cf-adapter`, `@serverless-ircd/cf-worker`) is
+  incompatible with the current vitest toolchain.** `@vitest/coverage-v8`
+  v4.1.x imports `node:inspector/promises`, which the
+  `@cloudflare/vitest-pool-workers` (workerd) test pool cannot resolve.
+  The packages' test suites themselves pass (cf-adapter 185/185,
+  cf-worker 3/3); only `pnpm coverage` fails to load the coverage
+  module under the workerd pool. This is a documented [vitest-pool-workers
+  known issue](https://developers.cloudflare.com/workers/testing/vitest-integration/known-issues/#module-resolution)
+  and is expected to resolve with an upstream `@vitest/coverage-v8` or
+  pool-workers release. No production code is affected; CI behavior
+  depends on its installed versions.
+
+### Security
+
+- None. No vulnerabilities have been reported or fixed in this release.
+  The dropped S2S / obsolete verbs and their reserved numerics carried
+  no reachable code path; their removal reduces surface area but fixes
+  no defect.
+
+---
+
 ## [0.4.0] - 2026-07-31
 
 The headline is **dual transport**: both adapters now speak a real

package/README.md

@@ -6,21 +6,24 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates.
 
-> **Status:** **v0.4.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.4.0 ships **dual transport**: both adapters
-> now speak a real `irc+tls :6697` (TLS-over-TCP) surface for stock IRC
+> 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. It also lands **SASL `EXTERNAL` via mTLS**, the remaining
-> standard IRC verbs (`WHOWAS`, `VERSION`, `TIME`, `ADMIN`, `INFO`,
-> `USERHOST`, `ISON`), a **Cloudflare D1-backed SASL account store**,
-> config-driven server identity, and a **Node 24 / pnpm 11** toolchain.
-> Remaining 0.x work: oper-gated verbs (`KILL`/`REHASH`/…), a
-> required-`serverName` config gate, and load/compat testing. See
-> `CHANGELOG.md` for the per-release manifests.
+> 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.
 
 ---
 
@@ -299,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
@@ -345,9 +384,28 @@ cleanly. Per-release manifests live in `CHANGELOG.md`.
   ✅ 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),
-  client compatibility sweep (WeeChat, HexChat, IRCCloud, TheLounge),
-  remaining ADRs.
+- **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.
 
 ---
 
@@ -356,10 +414,19 @@ 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`,
-`WHOWAS`, `MOTD`, `AWAY`, `OPER` (credential auth → `o` user mode), plus
-the query verbs `VERSION`, `TIME`, `ADMIN`, `INFO`, `USERHOST`, `ISON`.
-(Oper-gated verbs — `KILL`/`REHASH`/`CONNECT`/`SQUIT`/`TRACE` — remain
-deferred.)
+`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`.
@@ -388,9 +455,11 @@ bridges a stock TCP client to a deployed WebSocket endpoint.
 - `CHANGELOG.md` — per-release manifests (Keep a Changelog format), including
   the v0.2.0 work (AWS adapter, SASL, flood control, security hardening, CI
   gates), v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
-  ChannelRegistryDO, SASL account persistence), and v0.4.0 (dual transport
+  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).
+  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.

package/apps/aws-stack/README.md

@@ -8,7 +8,7 @@ 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
 
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-stack",
-  "version": "0.4.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",

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

@@ -17,7 +17,12 @@ 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';
@@ -191,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),
       },
@@ -202,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

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

@@ -1,7 +1,7 @@
 /**
  * Synth-time assertions for the `apps/aws-stack` CDK stack.
  *
- * These are the primary red→green tests for the infrastructure ticket:
+ * These are the primary red→green tests for the infrastructure stack:
  * they assert the exact CloudFormation shape that `cdk synth` must
  * produce — five DynamoDB tables with the PLAN §4 schema, a single
  * Node 24 Lambda wired to all three WebSocket routes, the API Gateway
@@ -149,6 +149,52 @@ describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
     const { template } = makeTemplate();
     template.resourceCountIs('AWS::ApiGatewayV2::Route', 3);
   });
+
+  it('enables the $connect route to return a response (route response selection)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+      RouteKey: '$connect',
+      RouteResponseSelectionExpression: '$default',
+    });
+  });
+
+  it('creates a $connect route response so the upgrade can carry a response', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::RouteResponse', {
+      RouteResponseKey: '$default',
+    });
+  });
+});
+
+describe('IrcAwsStack — IRCv3 WebSocket subprotocol echo', () => {
+  it('attaches an integration response on the $connect route mapping Sec-WebSocket-Protocol', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
+      ResponseParameters: {
+        'method.response.header.Sec-WebSocket-Protocol':
+          'integration.response.header.Sec-WebSocket-Protocol',
+      },
+    });
+  });
+
+  it('binds the subprotocol integration response to the $connect integration', () => {
+    const { template, stack } = makeTemplate();
+    const responses = template.findResources('AWS::ApiGatewayV2::IntegrationResponse');
+    // Exactly one integration response is configured (the $connect subprotocol echo).
+    expect(Object.keys(responses)).toHaveLength(1);
+    // The IntegrationId Ref must resolve to a CfnIntegration under the $connect route.
+    const stackName = stack.stackName;
+    void stackName;
+    const cfnIntegrations = template.findResources('AWS::ApiGatewayV2::Integration');
+    expect(Object.keys(cfnIntegrations).length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('uses the $default integration response key', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
+      IntegrationResponseKey: '$default',
+    });
+  });
 });
 
 describe('IrcAwsStack — Lambda', () => {

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

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
   "license": "BSD-3-Clause",