serverless-ircd 0.10.0 → 0.11.0

package/docs/Cloudflare-TCP-Deployment.md

@@ -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"`). |
 
 ---
 
@@ -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
@@ -189,7 +208,38 @@ 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 Apply the Spectrum TLS config
+### 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
@@ -201,9 +251,10 @@ terraform apply \
 ```
 
 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.
@@ -215,7 +266,7 @@ printf 'NICK smoke\r\nUSER smoke 0 * :Smoke\r\nQUIT :smoke\r\n' | \
 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.example.com/6697
@@ -240,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`.              | —                        |
@@ -273,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"`
@@ -311,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.
+
+The container therefore pins the mechanism off explicitly via the
+`sasl.externalUnsupportedMessage` transport override:
 
-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 `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`.
 
-- **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 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`.
 
-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`).
+- **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).
 
 ---
 
@@ -389,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.             |
 
@@ -417,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"
+
+`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.3 Channel topic/modes lost after a restart
+### 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`
@@ -428,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
@@ -442,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
@@ -457,16 +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
 
 # 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.example.com             # Spectrum
+    -var hostname=irc.example.com             # Spectrum (tls_mode=full)
 
 # Tests
 pnpm --filter @serverless-ircd/cf-tcp-container test
@@ -477,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/SASL-EXTERNAL.md

@@ -0,0 +1,175 @@
+# SASL EXTERNAL (CertFP) — certificate-to-account binding
+
+Operator and contributor reference for how `AUTHENTICATE EXTERNAL`
+(ServerlessIRCd's mTLS-backed SASL mechanism) turns a verified client
+certificate into a logged-in NickServ account.
+
+Cross-reference: the `MtlsIdentityProvider` port and
+`ServicesStore.verifyCertFP` in `packages/irc-core/src/ports.ts`, the
+canonicaliser in `packages/irc-core/src/certfp.ts`, the SASL EXTERNAL
+reducer in `packages/irc-core/src/commands/sasl.ts`, and
+`extractMtlsSubject` in `packages/cf-adapter/src/connection-do.ts`.
+
+---
+
+## 1. The chosen identifier
+
+Account binding uses, in preference order:
+
+1. **DER SHA-256 fingerprint (primary).** When the platform surfaces a
+   SHA-256 fingerprint of the certificate's DER encoding, it is the
+   account binding. Stored as `fp:<hex>` (lowercase, colon-free) in the
+   nick row's `certSubjects` list. A fingerprint binds **this exact
+   certificate** — a CA re-issuing a different cert with the same subject
+   does NOT map to the account, and two semantically-identical certs with
+   different DER do not collide.
+2. **Canonical DN (fallback).** On platforms that surface only the
+   certificate subject DN, the DN is canonicalised (see §3) and compared
+   as the binding. Subject-bound accounts accept any certificate whose
+   canonical DN matches — the Atheme-style `CertFP` behaviour.
+
+### Platform availability (verified)
+
+| Platform | Fields surfaced | Identifier used |
+| --- | --- | --- |
+| Cloudflare Workers (API Shield mTLS) | `request.cf.tlsClientAuthCertSubject` (legacy documented field) and `request.cf.tlsClientAuth.certSubjectDN`, **plus** `request.cf.tlsClientAuth.certFingerprintSHA256` (lowercase-hex SHA-256 of the DER; `""` on non-mTLS connections) | **Fingerprint** when non-empty, canonical DN otherwise |
+| AWS API Gateway (custom-domain mTLS) | `requestContext.identity.clientCertSubjectDN` only — no fingerprint, no DER | **Canonical DN** |
+
+Neither platform hands the raw DER to the WebSocket handler directly
+(Cloudflare does expose the leaf cert RFC 9440-encoded under
+`cf.tlsClientAuth.certRFC9440`, but the platform-computed
+`certFingerprintSHA256` is strictly simpler and equivalent for binding,
+and is preferred). The fingerprint therefore never needs to be computed
+in-process; `certfp.ts` only normalises the platform-supplied hex
+(lowercase, colon-stripping) so `AA:11` and `aa11` are the same binding.
+
+## 2. Flow
+
+```
+TLS handshake (edge terminates, validates client cert against CA store)
+  └─ adapter admission: extractMtlsSubject(request)  → CertIdentity
+       { subject: raw string,
+         canonicalDn: canonicalizeCertSubject(subject),
+         fingerprint?: platform SHA-256 hex }
+  └─ stored per-connection, surfaced via MtlsIdentityProvider.getIdentity(connId)
+client: CAP REQ sasl → AUTHENTICATE EXTERNAL → AUTHENTICATE +
+  └─ sasl reducer: identity = provider.getIdentity(connId)
+  └─ ServicesStore.verifyCertFP(identity):
+       arm 1: fp:<hex> byte-exact match against certSubjects   (primary)
+       arm 2: canonical-DN match against DN entries            (fallback)
+  └─ 900 RPL_LOGGEDIN + 903 RPL_SASLSUCCESS, or 904 ERR_SASLFAIL
+```
+
+## 2a. Operator opt-in — the three-way gate
+
+EXTERNAL is only advertised (in the `sasl` cap value and the `908
+ERR_SASLMECHS` list) and only accepted when **all three** of these hold:
+
+1. **An mTLS identity source is bound** for the deployment (CF API Shield
+   client certs / AWS APIGW custom-domain mTLS — the
+   `MtlsIdentityProvider` port returns an identity for the connection).
+2. **The operator opted in**: set `EXTERNAL_ENABLED=true` (or `1`) in the
+   CF Worker vars / Lambda environment. The adapters map it to
+   `sasl.externalEnabled` in the parsed server config; unset or any other
+   value keeps the mechanism off (a typo never silently enables it).
+3. **The connection is secure (TLS)** — the client-cert identity only
+   carries meaning over a transport the server trusts (the NLB+TLS
+   secure-connection flag on the AWS path, the always-TLS edge on CF).
+
+If any one of the three is missing, `AUTHENTICATE EXTERNAL` is refused
+with `908 ERR_SASLMECHS` listing `PLAIN` only, and the refusal does not
+count toward the per-connection SASL failure lockout (it is a
+protocol-level mechanism rejection, not a failed credential attempt).
+
+### Transport availability — the cf-tcp-container exclusion
+
+The three-way gate is the *generic* refusal path. One transport
+additionally pins the mechanism off explicitly: the **cf-tcp-container**
+origin (Cloudflare Spectrum → Container, the Cloudflare
+`irc+tls :6697` path). Spectrum forwards with PROXY protocol v1, which
+carries no client-cert subject, and although `tls_mode = "full"`
+terminates TLS at the origin itself, no client-certificate trust pool
+is wired through to the IRC core — there is no `MtlsIdentityProvider`
+to feed, so EXTERNAL can never succeed there regardless of the Spectrum
+TLS mode. Decision (documented, option *explicit non-support*): rather
+than letting `AUTHENTICATE EXTERNAL` fail generically at the gate, the
+container sets the `sasl.externalUnsupportedMessage` transport
+override, so:
+
+- the `sasl` cap value and the `908 ERR_SASLMECHS` list advertise
+  `PLAIN` only, and
+- `AUTHENTICATE EXTERNAL` is rejected up front with `904 ERR_SASLFAIL`
+  carrying the stable message
+  `SASL EXTERNAL not supported on this transport`.
+
+The refusal does not count toward the per-connection SASL failure
+lockout (a transport capability statement, not a failed credential
+attempt). The override wins even if `EXTERNAL_ENABLED` is set — a
+transport without an mTLS identity source must not half-accept the
+exchange. Extracting the client-cert subject from PROXY-protocol-v2
+TLVs (which Spectrum can emit) is the documented follow-up if demand
+materialises; until then SASL EXTERNAL is available on the **wss**
+(Cloudflare Workers + API Shield mTLS) and **NLB+TLS** (AWS API Gateway
+custom-domain mTLS) paths only.
+
+## 3. DN canonicalisation (RFC 4514-grounded)
+
+Subject DNs are compared after canonicalisation
+(`canonicalizeCertSubject` in `packages/irc-core/src/certfp.ts`):
+
+1. Attribute **types** are lowercased (`CN=` → `cn=`); attribute
+   **values** keep their case and compare **case-sensitively**.
+2. Whitespace around types/values is trimmed; runs of unescaped
+   whitespace inside a value collapse to a single space. Escaped
+   whitespace (e.g. a trailing `\ `) is preserved verbatim.
+3. RDNs (`a,b`) and the AVAs of a multi-valued RDN (`a+b`) are sorted, so
+   two semantically-equal DNs written in different orders or spacing
+   collapse to one canonical spelling:
+   `CN=alice ,  O = Example   Inc` ≡ `O=Example Inc,CN=alice`.
+4. RFC 4514 escapes (`\,`, `\+`, `\=` …) pass through intact — the
+   canonicaliser never splits on an escaped separator.
+
+Two certs whose DNs differ only in spacing/ordering therefore map to the
+same account; DNs that differ in **value case** do not.
+
+## 4. First-use migration of legacy bindings
+
+Accounts created before this scheme stored the platform subject string
+verbatim. `verifyCertFP` handles them transparently:
+
+- On a canonical-DN arm match, a stored legacy spelling is **rewritten**
+  to its canonical form in the nick row.
+- When the platform supplied a fingerprint, the `fp:<hex>` binding is
+  **pinned** alongside the DN entry, so subsequent verifies hit the
+  fingerprint arm.
+- The `PersistentServicesStore` subclass re-persists the nick row on
+  both rewrites (write-behind `upsertNick`), so the migration survives a
+  backend reload. No operator action is required; there is no separate
+  migration script.
+
+## 5. Attaching bindings
+
+- `ServicesStore.addCertFingerprint(nick, fp)` — attach a fingerprint
+  binding (normalised to `fp:<hex>`; idempotent).
+- `ServicesStore.addCertFP(nick, dn)` — attach a subject-DN binding
+  (canonicalised at verify time; idempotent).
+- **These are the binding seam.** Both are programmatic store APIs
+  today — persistence is the `certSubjects` JSON column on the D1
+  `nickserv_accounts` row (added by the store's idempotent
+  `ALTER TABLE ... ADD COLUMN cert_subjects` runtime migration) and the
+  `certSubjects` list attribute on the DynamoDB `Services` item
+  (schemaless; no table migration needed). The NickServ `CERT` command
+  (Atheme parity) that surfaces them to users is the documented
+  follow-up: it will call exactly these two mutators, nothing else.
+
+## 6. Failure modes
+
+| Condition | Result |
+| --- | --- |
+| `EXTERNAL_ENABLED` unset/false (default) | EXTERNAL refused at mechanism phase (`908`, `PLAIN` only) — flag off means off |
+| Insecure (non-TLS) connection | EXTERNAL refused at mechanism phase (`908`) even with mTLS + flag on |
+| No mTLS configured (no `MtlsIdentityProvider` bound) | EXTERNAL refused at mechanism phase (`908`) |
+| cf-tcp-container transport (`sasl.externalUnsupportedMessage` override) | up-front `904 ERR_SASLFAIL` — "SASL EXTERNAL not supported on this transport" (not counted toward the lockout) |
+| Cert presented but no account carries a matching fingerprint or canonical DN | `904 ERR_SASLFAIL` ("untrusted certificate") |
+| Fingerprint bound to account A, DN bound to account B | fingerprint arm wins — the verify returns account A |
+| Platform surfaces no fingerprint (API Gateway) | DN arm only; binding is DN-scoped |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.1.10",
-    "@serverless-ircd/aws-adapter": "0.10.0"
+    "@serverless-ircd/aws-adapter": "0.11.0"
   },
   "scripts": {
     "build": "turbo run build",
@@ -32,7 +32,7 @@
     "mutation:commands": "pnpm --filter @serverless-ircd/irc-core mutation:commands",
     "mutation": "pnpm run mutation:protocol && pnpm run mutation:commands",
     "clean": "turbo run clean && rimraf node_modules",
-    "deploy:cf": "pnpm --filter @serverless-ircd/cf-worker run deploy",
+    "deploy:cf": "pnpm build && pnpm --filter @serverless-ircd/cf-worker run deploy",
     "smoke:cf": "pnpm --filter @serverless-ircd/cf-worker run smoke",
     "deploy:cf-tcp": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container run deploy",
     "deploy:aws": "pnpm build && pnpm --filter @serverless-ircd/aws-stack run deploy",

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

package/packages/aws-adapter/src/admission.ts

@@ -1,10 +1,11 @@
 /**
  * Pure admission policy for the AWS `$connect` handler.
  *
- * The I/O (counting live rows in DynamoDB) lives in `handlers/connect.ts`;
- * the *decision* — "does this count fit under the caps?" — is a pure
- * function extracted here so it is trivial to unit-test every branch
- * without standing up DynamoDB Local.
+ * The I/O (counting live rows in DynamoDB) lives in `handlers/connect.ts`
+ * (`ip-admission.ts` for the per-IP walk, `connection-counter.ts` for the
+ * global counter); the *decision* — "do these counts fit under the caps?"
+ * — is a pure function extracted here so it is trivial to unit-test every
+ * branch without standing up DynamoDB Local.
  *
  * This is deliberately separate from irc-core's `decideAdmission` /
  * `AdmissionStats`: that helper is an in-memory counter design that
@@ -17,25 +18,30 @@
 /**
  * Live connection counts gathered from DynamoDB.
  *
- *   - `total` is always supplied (a paginated `Scan COUNT` over
+ *   - `total` is always supplied (the atomic meta-row counter over all
  *     `Connections`).
- *   - `perIp` is optional: counting connections per source IP needs a
- *     GSI on `sourceIp` (see `handlers/connect.ts` for the deferred
- *     per-IP follow-up). Until that lands, callers omit `perIp` and the
- *     per-IP branch of {@link decideConnectAdmission} is skipped.
+ *   - `perIp` / `recentPerIp` are supplied when the connecting client's
+ *     source IP is known: `perIp` counts the IP's live connections (the
+ *     `sourceIp` GSI) and `recentPerIp` counts those established inside
+ *     the `perIpConnectionRate` window. Callers omit both when the
+ *     event carries no source IP; the per-IP branches are then skipped.
  */
 export interface ConnectionCounts {
   readonly total: number;
   readonly perIp?: number;
+  readonly recentPerIp?: number;
 }
 
 /**
- * Effective caps sourced from {@link ParsedServerConfig}. `perIp` is
- * optional because per-IP enforcement is not yet wired on the AWS path.
+ * Effective caps sourced from {@link ParsedServerConfig}. The per-IP
+ * caps are optional because they only bind when the corresponding count
+ * is also available (see {@link ConnectionCounts}).
  */
 export interface AdmissionLimits {
   readonly maxClients: number;
   readonly maxConnectionsPerIp?: number;
+  /** Per-IP connection-rate budget (`perIpConnectionRate`). */
+  readonly perIpRate?: { readonly max: number; readonly windowMs: number };
 }
 
 /**
@@ -53,8 +59,10 @@ export type AdmissionOutcome =
  * ambient state.
  *
  * Precedence: the global `maxClients` cap is checked first (it is the
- * cheap, always-available gate), then the optional per-IP cap when both
- * the limit and the `perIp` count are present.
+ * cheap, always-available gate), then the optional per-IP simultaneous
+ * cap, then the optional per-IP rate window — matching the per-cap
+ * ordering of irc-core's single-process `decideAdmission` (global first
+ * here because its count is O(1)-available, unlike there).
  */
 export function decideConnectAdmission(
   counts: ConnectionCounts,
@@ -70,5 +78,12 @@ export function decideConnectAdmission(
   ) {
     return { admitted: false, statusCode: 429, reason: 'too many connections from this IP' };
   }
+  if (
+    limits.perIpRate !== undefined &&
+    counts.recentPerIp !== undefined &&
+    counts.recentPerIp >= limits.perIpRate.max
+  ) {
+    return { admitted: false, statusCode: 429, reason: 'connection rate exceeded for this IP' };
+  }
   return { admitted: true };
 }