serverless-ircd 0.2.0 → 0.4.0

package/.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: pnpm
 
       - name: Install dependencies
@@ -112,7 +112,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: pnpm
 
       - name: Install dependencies

package/.github/workflows/deploy-aws.yml

@@ -63,13 +63,11 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: pnpm
 
       - name: Install dependencies

package/.github/workflows/deploy-cf-tcp.yml

@@ -0,0 +1,87 @@
+name: deploy-cf-tcp
+
+# Cloudflare TCP+TLS deploy pipeline (Spectrum + Container origin).
+#
+# Deploys the IRC TCP container origin (apps/cf-tcp-container) to Cloudflare
+# Containers and applies the Spectrum TLS config (terraform). Spectrum
+# terminates TLS on :6697 and forwards plaintext TCP to the container.
+#
+# This pipeline runs alongside deploy-cf.yml (the WebSocket path). The two
+# are independent: a deployment can enable either or both transports.
+#
+# Secrets (configure under repo Settings → Secrets and variables → Actions):
+#   CLOUDFLARE_API_TOKEN    Spectrum/Containers API token.
+#   CLOUDFLARE_ACCOUNT_ID   Account ID for the target zone.
+#   CF_ZONE_ID              Zone ID for the Spectrum hostname.
+#   CF_TCP_ORIGIN_ADDRESS   Hostname/IP of the container origin.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/cf-tcp-container/**'
+      - '.github/workflows/deploy-cf-tcp.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: cf-tcp-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy-staging:
+    name: deploy cf-tcp staging
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build workspace
+        run: pnpm build
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm --filter '@serverless-ircd/cf-tcp-container' test
+
+      - name: Deploy container to staging
+        working-directory: apps/cf-tcp-container
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: wrangler deploy --env staging
+
+      - name: Apply Spectrum TLS config
+        working-directory: apps/cf-tcp-container/terraform
+        env:
+          TF_VAR_zone_id: ${{ secrets.CF_ZONE_ID }}
+          TF_VAR_origin_address: ${{ secrets.CF_TCP_ORIGIN_ADDRESS }}
+          TF_VAR_hostname: irc-staging.example.com
+        run: |
+          terraform init
+          terraform apply -auto-approve
+
+      - name: Smoke e2e (irc+tls)
+        if: ${{ vars.CF_TCP_SMOKE_HOST != '' }}
+        env:
+          SMOKE_HOST: ${{ vars.CF_TCP_SMOKE_HOST }}
+          SMOKE_PORT: '6697'
+        run: |
+          # Minimal smoke: connect over TLS, register, join, privmsg, quit.
+          # Uses openssl s_client for the TLS handshake + IRC line exchange.
+          echo "NICK smoke\r\nUSER smoke 0 * :Smoke\r\nQUIT :smoke\r\n" | \
+            timeout 10 openssl s_client -connect "${SMOKE_HOST}:${SMOKE_PORT}" -quiet 2>/dev/null | \
+            grep -q "001" && echo "SMOKE PASS" || (echo "SMOKE FAIL" && exit 1)

package/.github/workflows/deploy-cf.yml

@@ -49,7 +49,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: pnpm
 
       - name: Install dependencies

package/.node-version

@@ -0,0 +1 @@
+24

package/.nvmrc

@@ -0,0 +1 @@
+24

package/CHANGELOG.md

@@ -10,6 +10,248 @@ 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.4.0] - 2026-07-31
+
+The headline is **dual transport**: both adapters now speak a real
+`irc+tls :6697` (TLS-over-TCP) surface for stock IRC clients in
+production — not just the local CLI — alongside the WebSocket path. This
+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. Phase 7 (TLS hardening & raw TCP) is
+complete.
+
+### Added — Dual transport: WebSocket + `irc+tls :6697`
+
+The wss-only transport decision (ADR-005) is superseded by **ADR-009**
+(dual transport). The shared `ConnectionActor` now drives either
+transport through a generalized seam; the parser/reducer/dispatch
+pipeline is unchanged.
+
+- **Transport seam** (`@serverless-ircd/irc-server`,
+  `@serverless-ircd/irc-core`): the `\r\n` line-framing is extracted into
+  a `Transport` abstraction. `ConnectionActor` accepts a
+  `WsTextFrameTransport` (one message per WS frame, prior behavior) or a
+  `TcpByteStreamTransport` (stateful `\r\n` framing across chunks with
+  partial-line buffering). Both produce identical reducer invocations.
+- **Cloudflare TCP+TLS** (`@serverless-ircd/cf-tcp-container`): a new
+  workspace app — **Cloudflare Spectrum** terminates TLS at the edge and
+  forwards plaintext TCP to a stateful **Container** origin running the
+  IRC core. Ships a `Dockerfile`, config loader, deploy pipeline
+  (`.github/workflows/deploy-cf-tcp.yml`), and root
+  `deploy:cf-tcp:staging` / `deploy:cf-tcp:prod` scripts.
+- **AWS TCP+TLS** (`@serverless-ircd/aws-adapter`, `@serverless-ircd/aws-stack`):
+  a **Network Load Balancer** with a `tls` listener terminates TLS and
+  invokes a **Lambda streaming function** (`nlb-stream.ts`) as the target.
+  Connection identity is derived from NLB flow metadata; bidirectional
+  traffic flows over the Lambda response stream, reusing `AwsRuntime`.
+  CDK constructs for NLB + target group + ACM cert are added.
+- **Transport-parametrized contract suite** (`@serverless-ircd/irc-test-support`):
+  every scenario now runs across a `Transport` dimension
+  (in-memory+WS, in-memory+TCP, …), with TCP-specific framing scenarios
+  (chunk boundaries, mixed `\r\n`/`\n` line endings, partial sends).
+- **Docs**: `docs/Cloudflare-TCP-Deployment.md` and
+  `docs/AWS-TCP-Deployment.md` — end-to-end :6697 deployment guides
+  (prerequisites, mTLS trust-store setup, cost/ops caveats).
+
+### Added — SASL `EXTERNAL` via mTLS (`@serverless-ircd/irc-core`, adapters)
+
+- **mTLS support**: an `MtlsIdentityProvider` port in `irc-core` feeds
+  the verified client-certificate subject into `AccountStore`. Cloudflare
+  uses API Shield mTLS (uploaded CA pool); AWS uses API Gateway
+  custom-domain mTLS (PEM trust store, subject in the `$connect` event).
+  Identity is plumbed via a port — no cloud deps in `irc-core`.
+- **`EXTERNAL` now authenticates** (was a stubbed `904 ERR_SASLFAIL` in
+  v0.2.0): `AUTHENTICATE EXTERNAL` against a bound provider succeeds with
+  `900 RPL_LOGGEDIN` / `903 RPL_SASLSUCCESS` when the cert maps to an
+  account.
+- **mTLS-conditional advertisement**: the `sasl` cap value and
+  `908 ERR_SASLMECHS` are now driven by whether an mTLS provider is bound
+  — `PLAIN` only by default, `PLAIN,EXTERNAL` when one is. `AUTHENTICATE
+  EXTERNAL` without mTLS returns `908` (mechanism not available) instead
+  of the misleading `904`. Operators enable EXTERNAL by configuring edge
+  mTLS — no code change required.
+
+### Added — Remaining IRC query verbs (`@serverless-ircd/irc-core`)
+
+- **`WHOWAS`**: a nick-history store (port + in-memory reference impl)
+  records `(nick, connId, username, hostname, signoffTime)` on QUIT /
+  NICK-change and purges past a TTL. `WHOWAS <nick>{,<nick>} [<count>]`
+  queries it — `314 RPL_WHOWASUSER` per match, `369 RPL_ENDOFWHOWAS`
+  terminator, `406 ERR_WASNOSUCHNICK` when no match.
+- **`VERSION`** (`351`), **`TIME`** (`391`, uses the injected `Clock`),
+  **`ADMIN`** (`256`/`257`/`258`), **`INFO`** (`371`/`374`),
+  **`USERHOST`** (`302`), **`ISON`** (`303`) — each a reducer + a route
+  case with spec-correct numerics. Completes the standard query-verb set.
+
+### Added — Server identity from config (`@serverless-ircd/irc-core`)
+
+- The `002` / `003` / `004` registration replies now reflect
+  `ServerConfig.serverVersion` / `createdAt` — the hardcoded
+  `'0.1.0'` / `'Phase 1'` placeholders are gone. A build step
+  (`scripts/generate-build-info.mjs`) bakes the package version and a
+  build timestamp into `RPL_CREATED` (`003`) when the config omits them.
+
+### Added — Cloudflare D1-backed SASL account store (`@serverless-ircd/cf-adapter`, `@serverless-ircd/irc-core`)
+
+- Brings the CF adapter to parity with the AWS `DynamoAccountStore`. A
+  persistent `AccountStore` pre-loads scrypt-hashed rows from a new
+  **D1** database (`ACCOUNTS_DB` binding) at `ConnectionDO`
+  construction.
+- **Shared scrypt hashing**: `hashAccountCredential` /
+  `verifyHashedPassword` are extracted to `irc-core` so both adapters use
+  one implementation (never plaintext).
+- **Table-then-env precedence**: when the D1 table has rows it is
+  authoritative; when empty or unreachable the adapter falls back to the
+  `SASL_ACCOUNTS` env-var seed, preserving current behavior.
+- **`tools/seed-cf-accounts.ts`**: provisioning CLI that scrypt-hashes
+  `username:password` pairs into the D1 `accounts` table (re-run
+  overwrites the prior row).
+
+### Added — AWS max-clients admission (`@serverless-ircd/aws-adapter`)
+
+- `$connect` now enforces `serverConfig.maxClients` (was a reserved
+  no-op — `void params.serverConfig;`). Connections over the cap are
+  rejected at accept time, matching the Cloudflare admission gate.
+
+### Changed
+
+- **Toolchain**: bumped from Node ≥ 20 / pnpm 9 to **Node ≥ 24 / pnpm
+  11** (aligns the Lambda and Cloudflare Workers runtimes). Re-run
+  `corepack enable` to pick up the pinned pnpm.
+- `@serverless-ircd/irc-core`: the request/response lookup `Effect`
+  variants (`LookupNick`, `GetConnectionInfo`, `GetChannelSnapshot`) are
+  removed from `effects.ts` and `dispatch` — they were dead scaffolding
+  with no producer or consumer.
+- `@serverless-ircd/cf-adapter`: the dead channel-registration loop in
+  `ConnectionDO.webSocketMessage` and the reserved outbound-batching
+  field are removed (the latter was a never-wired optimization).
+
+### ⚠️ Migration required
+
+- **Cloudflare: new D1 binding for SASL accounts.** To persist SASL
+  accounts, create the D1 database and add the `ACCOUNTS_DB` binding
+  (default + staging) to `wrangler.toml`:
+  ```bash
+  wrangler d1 create serverless-ircd-accounts
+  wrangler d1 execute serverless-ircd-accounts --command \
+    "CREATE TABLE IF NOT EXISTS accounts (account TEXT PRIMARY KEY, algorithm TEXT NOT NULL, salt TEXT NOT NULL, hash TEXT NOT NULL)"
+  ```
+  **No action is required to keep working** — when the D1 table is empty
+  or unreachable the adapter falls back to the `SASL_ACCOUNTS` env-var
+  seed. There is **no Durable-Object persisted-state schema change**
+  (`PERSISTED_STATE_VERSION` stays `1`); code rollback across this
+  release is safe.
+- **Local toolchain**: Node ≥ 24 / pnpm 11 is now required. Re-run
+  `corepack enable`.
+
+### Known limitations
+
+- 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.
+- Oper-gated verbs (`KILL`, `REHASH`, `CONNECT`, `SQUIT`, `TRACE`,
+  `WALLOPS`, `SETNAME`, …) still return `421 ERR_UNKNOWNCOMMAND`.
+- `serverName` still defaults to the `irc.example.com` placeholder when
+  an adapter config omits it (pending).
+
+### Security
+
+- SASL `EXTERNAL` no longer returns a misleading `904 ERR_SASLFAIL` when
+  mTLS isn't configured — it returns `908 ERR_SASLMECHS` and the
+  mechanism is not advertised until a trust store is bound. SASL
+  credentials remain scrypt-hashed only (never plaintext), now via a
+  single shared implementation across both adapters.
+
+---
+
+## [0.3.0] - 2026-07-25
+
+### Added — Operator authentication (`@serverless-ircd/irc-core`)
+
+- **`OPER` command reducer**: `OPER <name> <password>` authenticates the
+  caller against the deployment's configured operator credentials
+  (`OperCred[]`) and, on success, grants the `o` user mode, replying
+  `381 RPL_YOUREOPER`. Missing parameters → `461 ERR_NEEDMOREPARAMS`;
+  no credentials configured → `491 ERR_NOOPERHOST`; wrong name/password
+  → `464 ERR_PASSWDMISMATCH`. Already an operator is an idempotent
+  no-op that re-confirms with `381`. `OPER` is the *only* path to oper
+  — user `MODE +o` is hard-rejected with `481 ERR_NOPRIVILEGES` — and
+  unlocks the `313 RPL_WHOISOPERATOR` branch of WHOIS and the `*`
+  oper flag of WHO.
+
+### Added — IRCv3 `TAGMSG` (`@serverless-ircd/irc-core`)
+
+- **`TAGMSG` reducer** (message-tags extension): carries tags only, no
+  text body. Gated behind the `message-tags` capability (clients that
+  did not negotiate it see `421 ERR_UNKNOWNCOMMAND`). Follows NOTICE
+  semantics — no numeric error replies on any rejection path — for both
+  channel and user targets, and is recorded so `draft/chathistory`
+  replay picks up `TAGMSG` lines.
+
+### Added — RFC 1459 case-mapping (`@serverless-ircd/irc-core`)
+
+- **`case-fold.ts`**: RFC 1459 case-insensitive comparison for nicks
+  and channels, advertised via `005 CASEMAPPING=rfc1459`. Replaces the
+  prior ASCII-only comparison across nick collision/registry, kick and
+  invite target lookup, and membership matching.
+
+### Added — Registration MOTD (`@serverless-ircd/irc-core`)
+
+- The registration welcome now renders the **real configured MOTD**
+  (`motd-lines.ts`), replacing the placeholder banner. The `MOTD`
+  command and the welcome flow share one rendering path.
+
+### Added — Cloudflare adapter (`@serverless-ircd/cf-adapter`)
+
+- **`ChannelRegistryDO`**: a fourth Durable Object holding the channel
+  directory (channel name → `ChannelDO` routing), alongside
+  `ConnectionDO`, `ChannelDO`, and `RegistryDO`. Wired into the Worker
+  exports, bindings, and SQLite migrations.
+- **Cloudflare config loader**: reduces Workers `vars` to the shared
+  `ServerConfigSchema`, matching the AWS (`loadServerConfigFromLambdaEnv`)
+  and local-CLI loaders.
+- `CfRuntime` completed — the previously stubbed `IrcRuntime` methods
+  (`getConnection`, `getChannelConnections`, `listChannels`, and
+  cross-connection `disconnect`) are now implemented.
+
+### Added — SASL account persistence (`@serverless-ircd/aws-adapter`)
+
+- SASL `PLAIN` accounts are now persisted in the DynamoDB `Accounts`
+  table with **scrypt** password hashes (never plaintext). The Lambda
+  cold-start path scans the table once and loads credentials into the
+  synchronous `AccountStore` port.
+- **`tools/seed-aws-accounts.ts`**: provisioning script that scrypt-hashes
+  `username:password` pairs (from CLI args or a file) and writes them
+  to the `Accounts` table. Re-running with the same username overwrites
+  the prior row.
+
+### Changed
+
+- `@serverless-ircd/in-memory-runtime`: `admitConnection` now returns a
+  stable empty `recordId` when admission is disabled, dropping the
+  per-call id minting (the id was never consulted).
+- Deploy scripts: root `pnpm deploy:aws:staging` / `deploy:aws:prod`
+  now run `pnpm build` before `cdk deploy`, so the esbuild-bundled
+  Lambda picks up fresh workspace `dist/` — matching what CI already
+  did and fixing local deploys shipping stale code.
+
+### Known limitations
+
+- SASL `EXTERNAL` (mTLS) and production TLS transport remain pending
+  (0.x work).
+- Deployed stacks remain WebSocket-only; stock TCP IRC clients still
+  reach them through the local `tcp-ws-forwarder` bridge.
+
+### Security
+
+- None. No vulnerabilities have been reported or fixed in this release.
+
+---
+
 ## [0.2.0] - 2026-07-23
 
 ### Added — Authentication & flood control (`@serverless-ircd/irc-core`)
@@ -294,31 +536,29 @@ manual per `docs/release.md` §8.3.
 
 ### Known limitations
 
-- **No AWS adapter.** Tickets TICKET-039 through TICKET-044 (CDK
-  stack, APIGW WebSocket handlers, DynamoDB transactions, EventBridge
-  timers, deploy pipeline, deployment doc) are pending. Cloudflare is
-  the only deployable platform in 0.1.0.
+- **No AWS adapter.** The CDK stack, APIGW WebSocket handlers, DynamoDB
+  transactions, EventBridge timers, deploy pipeline, and deployment doc
+  are pending. Cloudflare is the only deployable platform in 0.1.0.
 - **No SASL.** `CAP sasl` is advertised in the capability list but
   `AUTHENTICATE` is not wired into the dispatcher. Plain-text password
-  authentication via `PASS` is also not enforced (TICKET-046).
-- **No flood control.** A token-bucket wrapper (TICKET-028) is
-  pending. Misbehaving clients can send unbounded commands.
+  authentication via `PASS` is also not enforced.
+- **No flood control.** A token-bucket wrapper is pending. Misbehaving
+  clients can send unbounded commands.
 - **No server-password enforcement, rate limits, cloaking, or oper
-  credentials** (TICKET-046).
+  credentials.**
 - **No config loader.** Server name, network name, MOTD, channel
-  prefixes, max clients, oper creds are hardcoded defaults
-  (TICKET-047). The `MOTD.txt` file at the repo root is informational
-  only; the live MOTD is compiled into the Worker from
-  `[vars].MOTD_LINES`.
+  prefixes, max clients, oper creds are hardcoded defaults. The
+  `MOTD.txt` file at the repo root is informational only; the live MOTD
+  is compiled into the Worker from `[vars].MOTD_LINES`.
 - **No CI coverage gate.** Coverage is computed and uploaded as an
-  artifact, but no threshold is enforced (TICKET-048). Inspect
+  artifact, but no threshold is enforced. Inspect
   `packages/*/coverage/` before deploying.
 - **No TLS / raw TCP transport.** v1 is WebSocket text frames only.
-  TLS-hardened and `irc+tls` transports are 0.x work (TICKET-052
-  through TICKET-058). Stock TCP IRC clients reach the server through
-  the local `tcp-ws-forwarder` bridge.
-- **No `chathistory` playback.** TICKET-063 is pending; clients that
-  request backlog on JOIN will see an empty batch or no response.
+  TLS-hardened and `irc+tls` transports are 0.x work. Stock TCP IRC
+  clients reach the server through the local `tcp-ws-forwarder` bridge.
+- **No `chathistory` playback.** Chat-history playback is pending;
+  clients that request backlog on JOIN will see an empty batch or no
+  response.
 
 ### Security
 

package/README.md

@@ -4,18 +4,23 @@ 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.2.0 (preview).** The pure protocol core, the
+> **Status:** **v0.4.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. SASL (`PLAIN`), token-bucket flood control,
-> server-password enforcement, hostmask cloaking, connection admission,
-> IRCv3 chat history, and a CI coverage + mutation-testing gate landed
-> in v0.2.0. Remaining 0.x work: oper credentials /
-> config loader, SASL `EXTERNAL` (mTLS), and production TLS transport.
-> See `CHANGELOG.md` for the per-release manifests.
+> 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
+> 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.
 
 ---
 
@@ -57,14 +62,25 @@ Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
 │  packages/cf-adapter       │      │  packages/aws-adapter        │
 │    ConnectionDO            │      │    $connect/$disconnect/     │
 │    ChannelDO               │      │    $default Lambda handlers  │
-│    RegistryDO              │      │    DynamoDB tables           │
-│    CfRuntime               │      │    AwsRuntime                │
+│    ChannelRegistryDO       │      │    DynamoDB tables           │
+│    RegistryDO              │      │    AwsRuntime                │
+│    CfRuntime               │      │                              │
 └────────────────────────────┘      └──────────────────────────────┘
 ```
 
 `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:
@@ -106,11 +122,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
+│   ├── ci-hardening/      coverage-gate + mutation-config validators
+│   ├── 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
 ```
@@ -121,7 +140,7 @@ ServerlessIRCd/
 
 | Concern          | Choice                                            |
 |------------------|---------------------------------------------------|
-| Runtime          | Node ≥ 20, ES2022+                                |
+| Runtime          | Node ≥ 24, ES2022+                                |
 | Package mgr      | pnpm workspaces                                   |
 | Build cache      | turbo                                             |
 | Language         | TypeScript (strict, `exactOptionalPropertyTypes`) |
@@ -135,9 +154,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)
@@ -316,10 +338,16 @@ 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.
-  ✅ mostly landed (logger port, server-password, cloaking, admission
-  limits, coverage + mutation gates). Remaining: oper credentials / config
-  loader.
-- **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),
+  client compatibility sweep (WeeChat, HexChat, IRCCloud, TheLounge),
+  remaining ADRs.
 
 ---
 
@@ -327,23 +355,31 @@ 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`.
+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.)
 
 **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`, `server-time`,
-`account-tag`, `echo-message`, `batch`, `sasl` (`PLAIN` implemented,
-`EXTERNAL` reserved pending mTLS), `multi-prefix`, `away-notify`, `chghost`,
-`invite-notify`, `extended-join`, `draft/chathistory`, `safelist`.
+**IRCv3 extensions (negotiated via `CAP`):** `message-tags` (incl. the
+`TAGMSG` command), `server-time`, `account-tag`, `echo-message`, `batch`,
+`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.
 
 ---
 
@@ -351,7 +387,13 @@ 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).
+  gates), v0.3.0 (OPER, TAGMSG, RFC 1459 case-mapping, real MOTD,
+  ChannelRegistryDO, SASL account persistence), and v0.4.0 (dual transport
+  `irc+tls :6697`, SASL `EXTERNAL`/mTLS, WHOWAS + remaining verbs, D1 account
+  store, Node 24/pnpm 11).
+- `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,7 +1,7 @@
 # `@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
@@ -12,7 +12,7 @@ The Lambda handler is currently a stub (`{ statusCode: 200 }`); the real
 
 ## 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`)

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 } } : {}),
 };