serverless-ircd 0.9.0 → 0.11.0

package/docs/Cloudflare-TCP-Deployment.md

@@ -12,7 +12,7 @@ the two are independent and a deployment can enable either or both.
 > This doc covers the *how*.
 
 **Acceptance criterion (TICKET-058):** a new contributor can deploy
-their own TCP+TLS staging instance following only this doc.
+their own TCP+TLS instance following only this doc.
 
 Cross-reference: `apps/cf-tcp-container/` (origin),
 `apps/cf-tcp-container/wrangler.toml` (container config),
@@ -36,22 +36,32 @@ path adds two stateful pieces in front of the shared IRC core:
   ┌──────────────────────────────────────────────────────────────┐
   │  Cloudflare Spectrum  (Enterprise)                           │
   │    • terminates TLS on :6697                                 │
-  │    • forwards plaintext TCP to the origin                    │
+  │    • re-encrypts to the origin (tls_mode = "full")           │
   │    • PROXY protocol v1 carries the real client IP            │
   └──────────────────────────┬───────────────────────────────────┘
-                             │ plaintext TCP (:6667)
+                             │ TLS (:6697, origin cert)
                              ▼
   ┌──────────────────────────────────────────────────────────────┐
   │  Cloudflare Container  (apps/cf-tcp-container)               │
-  │    • node:24 process, EXPOSE 6667                            │
+  │    • node:24 process, EXPOSE 6697 — terminates TLS itself    │
+  │      (TLS_CERT_PATH / TLS_KEY_PATH, mounted at /data/certs)  │
   │    • ConnectionActor + InMemoryRuntime + TcpByteStream-      │
   │      Transport (the shared transport seam, TICKET-053)       │
   │    • persistence snapshot at /data/state.json                │
   │      (channel topology survives restart; live connections    │
   │      do not — clients reconnect)                             │
+  │    • plaintext :6667 = localhost-only debug listener         │
+  │      (DEBUG_PLAINTEXT=localhost; never routed, never in      │
+  │      prod — a prod-classified boot refuses to start          │
+  │      without TLS material)                                   │
   └──────────────────────────────────────────────────────────────┘
 ```
 
+TLS is **end-to-end**: no plaintext IRC bytes ever cross the origin
+network, so an attacker who can reach the origin address directly can
+neither read `PASS`/`AUTHENTICATE`/`PRIVMSG` off the wire nor spoof
+them.
+
 The **parser → reducer → dispatch pipeline is shared verbatim** with the
 wss path. Only the line-framing transport differs: a `TcpByteStreamTransport`
 reassembles `\r\n`-terminated IRC lines across arbitrary TCP chunks
@@ -61,8 +71,8 @@ Two artifacts are deployed and configured:
 
 | Artifact                              | Tool           | What it does                                   |
 |---------------------------------------|----------------|------------------------------------------------|
-| `sirc-tcp-origin` Cloudflare Container| `wrangler`     | Builds + runs the IRC core container image.    |
-| `cloudflare_spectrum_application`     | `terraform`    | TLS termination on :6697 + origin forwarding.  |
+| `sirc-tcp-origin` Cloudflare Container| `wrangler`     | Builds + runs the IRC core container image (TLS origin). |
+| `cloudflare_spectrum_application`     | `terraform`    | TLS on :6697 + re-encrypted origin forwarding (`tls_mode = "full"`). |
 
 ---
 
@@ -77,7 +87,7 @@ Two artifacts are deployed and configured:
 | **Cloudflare Enterprise**| **Spectrum is an Enterprise-tier feature.** Required for the TCP path. |
 | Containers beta access   | Cloudflare Containers is in beta; request access in the dashboard.  |
 | A Cloudflare zone        | The public hostname (e.g. `irc.example.com`) must live in a zone you control. |
-| Git checkout             | Clean working tree on `main` for production deploys.                |
+| Git checkout             | Clean working tree on `main` for deploys.                |
 
 > The wss path runs on the Workers Free/Paid plan. The TCP path does
 > **not** — Spectrum mandates Enterprise. If you do not have Enterprise,
@@ -133,17 +143,19 @@ export CLOUDFLARE_ACCOUNT_ID=...
 
 ## 4. Local development
 
-Run the container origin locally without Spectrum — connect a plaintext
-TCP IRC client directly to :6667. This exercises the exact
-`ConnectionActor` + `TcpByteStreamTransport` pipeline.
+Run the container origin locally without Spectrum. The plaintext TCP
+listener is **debug-only and localhost-only**: it starts solely when
+`DEBUG_PLAINTEXT=localhost` is set (the config loader then forces the
+bind to `127.0.0.1` — `TCP_HOST` cannot widen it). This exercises the
+exact `ConnectionActor` + `TcpByteStreamTransport` pipeline.
 
 ```bash
 # Build the workspace + the container package.
 pnpm build
 
-# Run the origin on plaintext :6667 (default TCP_PORT).
-pnpm --filter @serverless-ircd/cf-tcp-container start \
-  -- --env-file <(printf 'SERVER_NAME=irc.local\nTCP_PORT=6667\n')
+# Run the origin with the localhost-only plaintext debug listener.
+DEBUG_PLAINTEXT=localhost SERVER_NAME=irc.local TCP_PORT=6667 \
+  pnpm --filter @serverless-ircd/cf-tcp-container start
 ```
 
 Connect a plaintext client (no TLS) to `localhost:6667`:
@@ -156,12 +168,19 @@ JOIN #test
 PRIVMSG #test :hello over plaintext TCP
 ```
 
-For a TLS-terminated local loop, put `stunnel` (or `openssl s_server`)
-in front of :6667 and connect on :6697 — mirroring the Spectrum topology.
+For a TLS local loop that mirrors production (TLS terminating *at the
+origin*), point the origin at a local cert pair instead — no debug
+flag needed:
+
+```bash
+TLS_CERT_PATH=./certs/tls.pem TLS_KEY_PATH=./certs/tls.key SERVER_NAME=irc.local \
+  pnpm --filter @serverless-ircd/cf-tcp-container start
+# → TLS listener on :6697; plaintext stays closed.
+```
 
 The unit + the TLS e2e suites live in `apps/cf-tcp-container/tests/`
-(including `tls-e2e.test.ts`, which runs a real TLS handshake against the
-origin). Run them with:
+(including `tls-e2e.test.ts` and `container-server-tls.test.ts`, which
+run real TLS handshakes against the origin). Run them with:
 
 ```bash
 pnpm --filter @serverless-ircd/cf-tcp-container test
@@ -169,27 +188,58 @@ pnpm --filter @serverless-ircd/cf-tcp-container test
 
 ---
 
-## 5. Deploy staging
+## 5. Deploy
 
-Staging is what CI deploys on every push that touches
-`apps/cf-tcp-container/**`. You can also deploy it manually.
+The deploy is `workflow_dispatch`-only (a maintainer triggers it by
+hand); you can also deploy manually.
 
 ### 5.1 Deploy the container origin
 
 ```bash
 # From the repo root:
-pnpm deploy:cf-tcp:staging
+pnpm deploy:cf-tcp
 # Equivalent to:
-#   pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:staging
-#   → wrangler deploy --env staging   (inside apps/cf-tcp-container)
+#   pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container run deploy
+#   → wrangler deploy   (inside apps/cf-tcp-container)
 ```
 
 This builds the container image from `apps/cf-tcp-container/Dockerfile`
-and deploys the `sirc-tcp-origin-staging` Container. The first deploy
-prints the **origin address** — copy it into `CF_TCP_ORIGIN_ADDRESS`
-(used by the Spectrum step next).
-
-### 5.2 Apply the Spectrum TLS config
+and deploys the `sirc-tcp-origin` Container. The first deploy prints
+the **origin address** — copy it into `CF_TCP_ORIGIN_ADDRESS` (used by
+the Spectrum step next).
+
+### 5.2 Provision the origin certificate
+
+`tls_mode = "full"` means the **origin terminates TLS itself**, so it
+needs a PEM cert/key pair. Mount it at `/data/certs/` (the image's
+documented default: `TLS_CERT_PATH=/data/certs/tls.pem`,
+`TLS_KEY_PATH=/data/certs/tls.key`; override via env if the pair lives
+elsewhere). Cert files must be readable by UID 1000 (`node`) — the
+container drops privileges before reading them. Any of these work:
+
+| Option                 | How                                                            | Notes |
+|------------------------|----------------------------------------------------------------|-------|
+| **Cloudflare Origin Cert** | Dashboard → SSL/TLS → Origin Server → Create Certificate.  | Free, long-lived, issued for your zone; the easiest option when the origin is only reached via Spectrum. Not publicly trusted (fine — clients validate the *edge* cert). |
+| **Let's Encrypt**      | `certbot certonly --dns-plugin … -d origin.example.com`, then copy `fullchain.pem`/`privkey.pem` to `/data/certs/tls.{pem,key}` and renew on a cron/sidecar. | Publicly trusted; needs automation for the 90-day rotation. |
+| **BYO cert**           | Any PEM pair from your CA.                                     | Your compliance rules apply. |
+
+> A prod-classified boot (`NODE_ENV=production`, set by the Dockerfile)
+> **refuses to start** without `TLS_CERT_PATH`/`TLS_KEY_PATH` — there is
+> no silent plaintext fallback. A missing/unreadable cert file also
+> fails fast at boot with the offending path in the error.
+
+### 5.3 Lock origin ingress down to Cloudflare IPs
+
+Spectrum is the only thing that should ever reach the origin's :6697.
+On any platform with a firewall / security-group primitive, restrict
+ingress to Cloudflare's published ranges (https://www.cloudflare.com/ips/)
+— otherwise a direct-reach attacker skips the edge entirely.
+`spectrum.tf` ships a commented `cloudflare_list` reference for keeping
+a managed list of the current ranges; Cloudflare Containers origins
+rely on Spectrum `ip_firewall` + the platform's own network isolation,
+but external-compute origins must apply the firewall on their side.
+
+### 5.4 Apply the Spectrum TLS config
 
 ```bash
 cd apps/cf-tcp-container/terraform
@@ -197,28 +247,29 @@ terraform init
 terraform apply \
   -var zone_id=$CF_ZONE_ID \
   -var origin_address=$CF_TCP_ORIGIN_ADDRESS \
-  -var hostname=irc-staging.example.com
+  -var hostname=irc.example.com
 ```
 
 This creates the `cloudflare_spectrum_application.irc_tls` resource:
-TLS on :6697 → plaintext TCP to the container origin on :6667.
+TLS on :6697 at the edge, **re-encrypted** to the container origin's
+TLS listener on :6697 (`tls_mode = "full"` — the secure default).
 
-### 5.3 Smoke test over TLS
+### 5.5 Smoke test over TLS
 
 ```bash
 # Minimal smoke: register + quit over the real TLS endpoint.
 printf 'NICK smoke\r\nUSER smoke 0 * :Smoke\r\nQUIT :smoke\r\n' | \
-  timeout 10 openssl s_client -connect irc-staging.example.com:6697 -quiet | \
+  timeout 10 openssl s_client -connect irc.example.com:6697 -quiet | \
   grep -q '001' && echo "SMOKE PASS" || echo "SMOKE FAIL"
 ```
 
 CI does the same — see `.github/workflows/deploy-cf-tcp.yml` step
 "Smoke e2e (irc+tls)", gated on the `CF_TCP_SMOKE_HOST` repo variable.
 
-### 5.4 Connect a real IRC client
+### 5.6 Connect a real IRC client
 
 ```
-/server add ircd irc-staging.example.com/6697
+/server add ircd irc.example.com/6697
 /set irc.server.ircd.ssl on
 /connect ircd
 /join #test
@@ -226,27 +277,6 @@ CI does the same — see `.github/workflows/deploy-cf-tcp.yml` step
 
 ---
 
-## 6. Deploy production
-
-Production is the default `wrangler.toml` environment (no `--env` flag).
-
-```bash
-# 1. Edit wrangler.toml [vars] for production identity.
-# 2. Deploy the container:
-pnpm deploy:cf-tcp:prod
-# 3. Apply Spectrum config for the production hostname:
-cd apps/cf-tcp-container/terraform
-terraform apply -var zone_id=$CF_ZONE_ID \
-  -var origin_address=$CF_TCP_ORIGIN_ADDRESS \
-  -var hostname=irc.example.com
-```
-
-There is **no CI auto-deploy to production** — production deploys are
-manual. Staging deploys on every push to `main` that touches the
-container path.
-
----
-
 ## 7. Configuration reference
 
 ### 7.1 Container — `apps/cf-tcp-container/wrangler.toml`
@@ -261,8 +291,13 @@ Top-level `[vars]` map directly to the container config loader
 | `SERVER_VERSION`     | Version string in `002`.                             | (from package version)   |
 | `CREATED_AT`         | Creation text/time in `003`.                         | build/deploy timestamp   |
 | `MOTD_LINES`         | Message-of-the-day, `\n`-delimited.                  | welcome banner           |
-| `TCP_PORT`           | Plaintext port the container listens on.             | `6667`                   |
-| `TCP_HOST`           | Bind address (Spectrum forwards from the edge).      | `0.0.0.0`                |
+| `NODE_ENV`           | `production` classifies the boot as prod: the loader then refuses to start without TLS material and rejects `DEBUG_PLAINTEXT`. The Dockerfile sets it. | (unset = dev) |
+| `TLS_CERT_PATH`      | PEM certificate the origin TLS listener presents. **Required in prod** (with `TLS_KEY_PATH`). | image: `/data/certs/tls.pem` |
+| `TLS_KEY_PATH`       | PEM private key for the origin TLS listener. **Required in prod** (with `TLS_CERT_PATH`). | image: `/data/certs/tls.key` |
+| `TLS_PORT`           | Origin TLS listener port.                            | `6697`                   |
+| `TCP_PORT`           | Plaintext debug-listener port — only used when `DEBUG_PLAINTEXT=localhost` is set. | `6667` |
+| `TCP_HOST`           | Bind address. Forced to `127.0.0.1` whenever the plaintext debug listener is enabled. | `0.0.0.0` |
+| `DEBUG_PLAINTEXT`    | Exact value `localhost` opts into the localhost-only plaintext debug listener. Any other value is rejected; forbidden in prod. | (unset = TLS-only) |
 | `PERSISTENCE_PATH`   | Snapshot file path; enables channel-state survival.  | `/data/state.json`       |
 | `SNAPSHOT_INTERVAL_MS`| Auto-snapshot cadence (ms).                         | `60000`                  |
 | `OPER_USER` / `OPER_PASSWORD` | Oper credentials for `OPER`.              | —                        |
@@ -294,10 +329,10 @@ sleep_after = "2h"
 |-------------------|---------------------------------------------------|---------------------|
 | `zone_id`         | Cloudflare zone for the hostname.                 | *(required)*        |
 | `origin_address`  | Hostname/IP of the container origin.              | *(required)*        |
-| `origin_port`     | Port the origin listens on (plaintext).           | `6667`              |
+| `origin_port`     | Port the origin's **TLS** listener serves.        | `6697`              |
 | `hostname`        | Public hostname clients connect to.               | `irc.example.com`   |
 | `spectrum_port`   | Public port Spectrum listens on.                  | `6697`              |
-| `tls_mode`        | `flexible` (TLS→CF, plain→origin) / `full` / `strict`. | `flexible`     |
+| `tls_mode`        | `full` (TLS end-to-end — the secure default) / `strict` (edge also validates the origin cert). | `full` |
 
 `ip_firewall = true` (Cloudflare's L3/L4 DDoS) and
 `argo_smart_routing = true` are on by default. `proxy_protocol = "v1"`
@@ -332,24 +367,39 @@ path (Durable Objects) does not have. Two layers of survival:
 
 ---
 
-## 9. mTLS (SASL EXTERNAL)
+## 9. mTLS (SASL EXTERNAL) — not supported on this transport
+
+SASL `EXTERNAL` requires the verified client certificate to reach the
+application layer. On the TCP container path it cannot: Spectrum
+forwards to the origin with **PROXY protocol v1**, which carries no
+client-cert subject, and although `tls_mode = "full"` terminates TLS at
+the origin (`TLS_CERT_PATH`/`TLS_KEY_PATH`), no client-certificate
+trust pool is wired through to the IRC core — there is no
+`MtlsIdentityProvider` to feed, in either TLS mode.
 
-SASL `EXTERNAL` needs the client certificate to reach the application
-layer (ADR-006, TICKET-054). On the TCP path this is the TLS handshake:
+The container therefore pins the mechanism off explicitly via the
+`sasl.externalUnsupportedMessage` transport override:
 
-- **Flexible mode (default):** Spectrum terminates TLS; the origin sees
-  plaintext. The cert is consumed at the edge and the app only gets a
-  verified subject via Cloudflare's mTLS config — SASL `EXTERNAL` is
-  **not** available in flexible mode.
-- **Full mode:** set `tls_mode = "full"` and configure the origin to
-  present its own certificate; configure Spectrum/API Shield mTLS with
-  your CA pool. The verified client-cert subject is then exposed to the
-  origin, feeding the `MtlsIdentityProvider` port → `AccountStore` →
-  `AUTHENTICATE EXTERNAL` succeeds (`903`) or fails (`904`).
+- the `sasl` capability advertises `PLAIN` only, and
+- a client sending `AUTHENTICATE EXTERNAL` is rejected up front with
+  `904 ERR_SASLFAIL` carrying the stable message
+  `SASL EXTERNAL not supported on this transport`.
 
-Cross-reference: TICKET-054 (mTLS support), ADR-006 (SASL scope). The wss
-path achieves the same via CF API Shield mTLS (see
-`Cloudflare-Deployment-Guide.md`).
+The refusal does not count toward the per-connection SASL failure
+lockout. Clients that need certificate-backed SASL should use the wss
+path (CF API Shield mTLS — see `Cloudflare-Deployment-Guide.md`) or the
+AWS NLB+TLS path (API Gateway custom-domain mTLS — see
+`AWS-TCP-Deployment.md`). Forwarding the client-cert subject via
+PROXY-protocol-v2 TLVs (which Spectrum can emit) is the documented
+follow-up if demand materialises; see `SASL-EXTERNAL.md`.
+
+- **Flexible mode (explicit downgrade):** Spectrum terminates TLS and
+  forwards plaintext TCP to the origin. EXTERNAL is equally unavailable
+  there, and plaintext origin traffic reintroduces the direct-reach
+  exposure this topology closed. Avoid it.
+
+Cross-reference: ADR-006 (SASL scope), `SASL-EXTERNAL.md` (mechanism
+scope + transport availability).
 
 ---
 
@@ -360,7 +410,7 @@ and SASL credentials ship as `[vars]` (`OPER_*`, `SASL_ACCOUNTS`). When
 strong-secret handling lands, set them via:
 
 ```bash
-wrangler secret put OPER_PASSWORD --env staging
+wrangler secret put OPER_PASSWORD
 ```
 
 CI uses these **GitHub Actions secrets/variables** (configure under
@@ -384,19 +434,20 @@ Settings → Secrets and variables → Actions):
 (the wss path). The two are independent — a deployment can enable
 either or both.
 
-Triggers: push to `main` touching `apps/cf-tcp-container/**` or the
-workflow itself, plus `workflow_dispatch`. Steps (in order):
+Triggers: `workflow_dispatch` only (a maintainer triggers it by hand;
+there is no automatic push-to-main deploy). Steps (in order):
 
 1. Checkout → pnpm 11 + Node 24 → `pnpm install --frozen-lockfile`.
 2. `pnpm build`, `pnpm typecheck`, `pnpm --filter cf-tcp-container test`.
-3. `wrangler deploy --env staging` (container).
+3. `wrangler deploy` (container).
 4. `terraform init && terraform apply -auto-approve` (Spectrum).
 5. TLS smoke (`openssl s_client`), gated on `CF_TCP_SMOKE_HOST`.
 
-Concurrency is serialized via `concurrency.group: cf-tcp-staging`.
+Concurrency is serialized via `concurrency.group: cf-tcp-deploy`.
 
-There is **no auto-deploy to production**; production is manual
-(`pnpm deploy:cf-tcp:prod` + `terraform apply` for the prod hostname).
+There is a single deploy target — the staging/prod split was collapsed,
+so the same workflow + account ships to whichever Container namespace
+the credentials target.
 
 ---
 
@@ -409,7 +460,7 @@ because of the stateful origin:
 |------------------------|------------------------------------|--------------------------------------------|
 | **Plan tier**          | Workers Paid ($5/mo) suffices.     | **Enterprise required** (Spectrum).        |
 | **Idle connections**   | Hibernation → ~zero memory cost.   | Origin holds every socket; `sleep_after` only helps when *all* connections are idle. |
-| **Compute**            | Per-request (WebSocket frames).    | **GB-second** of running container time.   |
+| **Compute**            | Per-request (WebSocket frames).    | **GB-second** of running container time. `tls_mode = "full"` moves TLS termination into the origin container, so it now pays the per-connection handshake CPU — budget handshakes/sec (each reconnect = one handshake) against the container's compute allocation when sizing `instance_type`. |
 | **State durability**   | DO storage (managed).              | Container volume snapshot (self-managed).  |
 | **DDoS**               | Cloudflare built-in.               | Spectrum `ip_firewall` + Argo.             |
 
@@ -437,10 +488,19 @@ respond. Causes:
 - `CF_TCP_ORIGIN_ADDRESS` points at the wrong origin. It must match the
   address printed by `wrangler deploy` (§5.1).
 - The origin crashed on boot. Check `wrangler tail` for the container
-  (or container logs in the dashboard). A common cause is an invalid
-  `MOTD_LINES` or a malformed `SASL_ACCOUNTS` line.
+  (or container logs in the dashboard). Common causes: the cert pair is
+  missing/unreadable at `TLS_CERT_PATH`/`TLS_KEY_PATH` (prod boots
+  refuse to start without it — the error names the offending path), an
+  invalid `MOTD_LINES`, or a malformed `SASL_ACCOUNTS` line.
+
+### 13.3 Origin refuses to boot: "refusing to start a prod-classified origin without TLS"
 
-### 13.3 Channel topic/modes lost after a restart
+`NODE_ENV=production` is set (the Dockerfile sets it by default) but
+`TLS_CERT_PATH`/`TLS_KEY_PATH` are not. Provision a cert pair (§5.2),
+mount it at `/data/certs/`, and restart. There is deliberately no
+plaintext fallback in prod.
+
+### 13.4 Channel topic/modes lost after a restart
 
 `PERSISTENCE_PATH` is unset or the volume is not attached. Confirm
 `PERSISTENCE_PATH=/data/state.json` in `[vars]` and that the `/data`
@@ -448,13 +508,13 @@ volume (`VOLUME ["/data"]` in the `Dockerfile`) is mounted on the
 container platform. Without it the snapshot is written to ephemeral
 storage and lost.
 
-### 13.4 Client IP seen as Spectrum's address
+### 13.5 Client IP seen as Spectrum's address
 
 `proxy_protocol = "v1"` must be set in `spectrum.tf` (it is by default).
 If you overrode it, the origin's per-IP admission gate sees Spectrum's
 egress IP for every client and will wrongly throttle/cap.
 
-### 13.5 Messages split across chunks get lost
+### 13.6 Messages split across chunks get lost
 
 This is a transport-layer bug, not a config issue — the
 `TcpByteStreamTransport` is contract-tested for chunk boundaries
@@ -462,7 +522,7 @@ This is a transport-layer bug, not a config issue — the
 `pnpm --filter @serverless-ircd/cf-tcp-container test` and the shared
 transport suite; a regression there will fail.
 
-### 13.6 `wrangler deploy` fails: `Containers beta not enabled`
+### 13.7 `wrangler deploy` fails: `Containers beta not enabled`
 
 Cloudflare Containers is in beta. Request access in the dashboard
 (Workers & Pages → Containers). Until granted, only the local Docker
@@ -477,20 +537,19 @@ path (§4) and the wss transport work.
 npx wrangler login                           # or set CLOUDFLARE_API_TOKEN
 terraform version                            # >= 1.5
 
-# Local dev (plaintext :6667, no Spectrum)
+# Local dev (TLS origin on :6697 with a local cert pair)
 pnpm build
-pnpm --filter @serverless-ircd/cf-tcp-container start
+TLS_CERT_PATH=./certs/tls.pem TLS_KEY_PATH=./certs/tls.key \
+  pnpm --filter @serverless-ircd/cf-tcp-container start
+# …or the localhost-only plaintext debug listener:
+DEBUG_PLAINTEXT=localhost pnpm --filter @serverless-ircd/cf-tcp-container start
 
-# Staging
-pnpm deploy:cf-tcp:staging                   # container
+# Deploy (single target — staging vs prod is which account you point at)
+pnpm deploy:cf-tcp                            # container
 cd apps/cf-tcp-container/terraform && \
   terraform apply -var zone_id=$CF_ZONE_ID \
     -var origin_address=$CF_TCP_ORIGIN_ADDRESS \
-    -var hostname=irc-staging.example.com     # Spectrum
-
-# Production (manual)
-pnpm deploy:cf-tcp:prod
-cd apps/cf-tcp-container/terraform && terraform apply ...   # prod hostname
+    -var hostname=irc.example.com             # Spectrum (tls_mode=full)
 
 # Tests
 pnpm --filter @serverless-ircd/cf-tcp-container test
@@ -501,10 +560,10 @@ Key files:
 | Path                                            | What                                       |
 |-------------------------------------------------|--------------------------------------------|
 | `apps/cf-tcp-container/src/main.ts`             | Container entry point.                     |
-| `apps/cf-tcp-container/src/container-server.ts` | TCP server + actor wiring + persistence.   |
-| `apps/cf-tcp-container/src/config-loader.ts`    | Env → `ServerConfig` + container knobs.    |
+| `apps/cf-tcp-container/src/container-server.ts` | TCP/TLS listeners + actor wiring + persistence. |
+| `apps/cf-tcp-container/src/config-loader.ts`    | Env → `ServerConfig` + container knobs (TLS + plaintext-debug gates). |
 | `apps/cf-tcp-container/src/persistence.ts`      | Channel-topology snapshot/restore.         |
 | `apps/cf-tcp-container/wrangler.toml`           | Container deploy config.                   |
-| `apps/cf-tcp-container/Dockerfile`              | Image (node:24, `/data` volume, :6667).    |
-| `apps/cf-tcp-container/terraform/spectrum.tf`   | Spectrum TLS :6697 → origin :6667.         |
+| `apps/cf-tcp-container/Dockerfile`              | Image (node:24, `/data` volume, :6697, UID 1000). |
+| `apps/cf-tcp-container/terraform/spectrum.tf`   | Spectrum TLS :6697 → origin TLS :6697 (`full`). |
 | `.github/workflows/deploy-cf-tcp.yml`           | Staging deploy + Spectrum + smoke CI.      |

package/docs/Release-Process.md

@@ -37,7 +37,7 @@ this repo itself) should pin exact versions.
 
 ### 1.1 Workspace version lock
 
-All fifteen `package.json` files (root + 14 workspace packages) carry the
+All sixteen `package.json` files (root + 15 workspace packages) carry the
 **same** version string. They are bumped together in the release
 commit. The pre-release checklist in §4 enforces this.
 
@@ -63,8 +63,8 @@ not always possible.
 | Push to `main`              | Maintainers              | Merging the release PR.               |
 | Push tags (`v*`)            | Maintainers              | `git push origin v0.x.0`.             |
 | Create GitHub Release       | Maintainers              | Publishing the release notes.         |
-| `CLOUDFLARE_API_TOKEN` secret | Repo Settings → Secrets | Local prod deploys. CI staging deploys. |
-| `CF_SMOKE_URL` variable     | Repo Settings → Variables | Staging smoke e2e in CI.              |
+| `CLOUDFLARE_API_TOKEN` secret | Repo Settings → Secrets | Manual + CI deploys (single target). |
+| `CF_SMOKE_URL` variable     | Repo Settings → Variables | Smoke e2e in CI (manual dispatch).     |
 
 There is no separate "release engineer" role. The maintainer who cuts
 the tag owns the release end-to-end, including the production deploy
@@ -101,7 +101,7 @@ git pull --ff-only origin main
 # 2. CI is green on the tip of main.
 #    Open: https://github.com/<owner>/<repo>/actions
 #    - CI workflow: lint / typecheck / coverage all green.
-#    - deploy-cf workflow: staging deploy + smoke e2e green.
+#    - deploy-cf workflow: deploy + smoke e2e green (manual dispatch).
 
 # 3. Local full verify.
 pnpm install --frozen-lockfile
@@ -120,9 +120,9 @@ pnpm build                       # every package produces dist/
 #    be green (step 2), so locally re-run `pnpm coverage` as a
 #    belt-and-braces check before tagging.
 
-# 5. Staging smoke e2e passes against the deployed tip-of-main.
+# 5. Smoke e2e passes against the deployed tip-of-main.
 node apps/cf-worker/scripts/smoke.mjs \
-  --url wss://serverless-ircd-staging.<subdomain>.workers.dev
+  --url wss://serverless-ircd.<subdomain>.workers.dev
 
 # 6. CHANGELOG.md is complete and accurate (§5).
 # 7. All package.json versions are bumped and lock-step (§6).
@@ -187,8 +187,9 @@ understand what changed and what they need to do.
 
 ## 6. Bumping versions
 
-There are fifteen `package.json` files. They must end up at the same
-version:
+There are sixteen `package.json` files (root + 15 workspace packages).
+They must end up at the same version (`tools/package.json` is a parent
+container with no `version` field and is not bumped):
 
 ```
 ./package.json                                          (workspace root)
@@ -206,6 +207,7 @@ apps/web/package.json
 tools/tcp-ws-forwarder/package.json
 tools/load-test/package.json
 tools/ci-hardening/package.json
+scripts/package.json                                    (deploy helpers)
 ```
 
 To cut `v0.X.Y`:
@@ -217,8 +219,8 @@ git checkout -b release/v0.X.Y
 # bump each file. The version field is the only change.
 # (Optional helper: `pnpm -r exec -- node -e '...'` if you script it.)
 
-# verify all eight files agree:
-rg '"version":' package.json packages/*/package.json apps/*/package.json tools/*/package.json
+# verify all files agree:
+rg '"version":' package.json packages/*/package.json apps/*/package.json tools/*/package.json scripts/package.json
 ```
 
 The lockfile (`pnpm-lock.yaml`) is unaffected — none of the workspace
@@ -270,7 +272,7 @@ git pull --ff-only origin main
 git log -1 --oneline              # expect: chore(release): v0.X.Y
 
 # Confirm versions are at the new release.
-rg '"version":' package.json packages/*/package.json apps/*/package.json tools/*/package.json
+rg '"version":' package.json packages/*/package.json apps/*/package.json tools/*/package.json scripts/package.json
 ```
 
 ### 8.1 Tag and push
@@ -299,8 +301,10 @@ configured (`git config tag.gpgSign true`).
 
 ### 8.3 Production deploy (manual)
 
-There is **no CI auto-deploy to production**. The maintainer runs the
-prod deploy by hand, from a clean checkout on the tag:
+There is a single deploy target per platform (`pnpm deploy:cf`); the
+staging/prod split was collapsed, so the same command ships to whichever
+Cloudflare account the credentials target. The maintainer runs the
+deploy by hand, from a clean checkout on the tag:
 
 ```bash
 git checkout v0.X.Y
@@ -313,17 +317,17 @@ pnpm build
 pnpm typecheck
 pnpm test
 
-# Deploy the Cloudflare Worker to production.
-pnpm deploy:cf:prod
-# → wrangler deploy   (default env = production)
+# Deploy the Cloudflare Worker.
+pnpm deploy:cf
+# → wrangler deploy
 
-# Tail prod logs while the first connections arrive.
+# Tail logs while the first connections arrive.
 npx wrangler tail
 
-# Smoke-check prod with the same script CI uses on staging.
-# You must point it at the prod wss:// URL:
+# Smoke-check the deploy with the same script CI uses.
+# You must point it at the wss:// URL:
 node apps/cf-worker/scripts/smoke.mjs \
-  --url wss://<prod-workers-subdomain>.workers.dev
+  --url wss://<workers-subdomain>.workers.dev
 ```
 
 If smoke fails on prod:
@@ -355,7 +359,7 @@ To redeploy a previous release:
 git checkout v0.W.Z                 # the previous tag
 pnpm install --frozen-lockfile
 pnpm build
-pnpm deploy:cf:prod
+pnpm deploy:cf
 ```
 
 This works as long as the previous release's code is compatible with
@@ -430,7 +434,7 @@ pnpm lint && pnpm typecheck && pnpm test && pnpm build
 
 # 2. Branch, bump versions + CHANGELOG, open PR (§6, §7).
 git checkout -b release/v0.X.Y
-# ... edit 8 × package.json + CHANGELOG.md ...
+# ... edit 16 × package.json + CHANGELOG.md ...
 git commit -am "chore(release): v0.X.Y"
 git push -u origin release/v0.X.Y
 # ... open PR, get it merged ...
@@ -445,7 +449,7 @@ git push origin v0.X.Y
 # 5. Prod deploy (§8.3).
 git checkout v0.X.Y
 pnpm install --frozen-lockfile && pnpm build
-pnpm deploy:cf:prod
+pnpm deploy:cf
 node apps/cf-worker/scripts/smoke.mjs --url wss://<prod>.workers.dev
 ```