serverless-ircd 0.9.0 → 0.11.0

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/docs/Services.md

@@ -46,8 +46,9 @@ ServerlessIRCd chose **integrated services**. The rationale (full detail in
 - The pure-reducer + location-of-authority architecture already has the
   right seam: a `ServicesStore` port absorbs the side effects, and reducers
   stay pure and unit-testable.
-- One storage layer is shared conceptually with the SASL `AccountStore` —
-  authentication and nick ownership are meant to compose, not duplicate.
+- One storage layer (`ServicesStore`) is the **single credential home**
+  for SASL PLAIN, SASL EXTERNAL, PASS-auth, and NickServ IDENTIFY —
+  authentication and nick ownership compose, not duplicate.
 - The serverless substrates (Cloudflare Durable Objects, AWS DynamoDB)
   handle persistence natively; a separate long-running services process
   would defeat the deployment model.
@@ -90,6 +91,12 @@ If no store is bound, every services command replies:
   milliseconds, NickServ waits before force-disconnecting a `ghost`-enforced
   client. `0` makes `ghost` behave like `kill` (immediate). Omit for the
   **30 000 ms** default (`DEFAULT_NICK_ENFORCE_GRACE_MS`).
+- **`nickServ.minPasswordLength`** (`integer > 0`, optional) — minimum
+  length enforced by NickServ `SET PASSWORD` for the new password. Omit for
+  the **8** default (`DEFAULT_MIN_PASSWORD_LENGTH`); a shorter new password
+  is rejected before hashing with
+  `Password is too short (minimum <n> characters).`. The maximum (256) is
+  fixed, not configurable, to bound the scrypt input budget.
 
 ---
 
@@ -176,6 +183,7 @@ policy, and nick-info queries. A registered nick is an account.
 | `DROP` | `PRIVMSG NickServ :DROP [nick]` | Requires prior identify. Drops the registration, clears `state.account` and `+r`, fans `ACCOUNT *`. Reply: `Nickname <nick> has been dropped.` |
 | `INFO` | `PRIVMSG NickServ :INFO [nick]` | Defaults to the current nick. Replies (NOTICE): `Nick:`, `Account:`, and (only if the caller is identified as the owning account **or** is an oper) `Email:`. A non-owner sees `Nick:` / `Account:` only. Unregistered → `Nick <target> is not registered.` |
 | `SET ENFORCE` | `PRIVMSG NickServ :SET ENFORCE none|ghost|kill` | Requires identify as the owning account. See enforcement below. |
+| `SET PASSWORD` | `PRIVMSG NickServ :SET PASSWORD <old-password> <new-password>` | Requires identify as the owning account **and** re-supplies the current password (defence against a hijacked `+r` session). Re-hashes the new password (scrypt) and overwrites the credential. New-password length floor: `nickServ.minPasswordLength` (default **8**); fixed ceiling **256**. Reply: `Password changed.` Wrong old password → `Invalid password.` (same text as a failed `IDENTIFY`; no leak). The current session stays `+r`; **other sessions of the same account are NOT kicked.** |
 
 Help / unknown command: `Available commands: REGISTER, IDENTIFY, DROP, INFO, SET`.
 
@@ -431,27 +439,24 @@ Both accept `--accounts alice:s3cret bob:pw …` or `--file accounts.txt`
 ```
 # Cloudflare
 node --import tsx tools/seed-cf-accounts.ts \
-  --database serverless-ircd-accounts-staging --env staging --remote \
+  --database serverless-ircd-accounts --remote \
   --accounts alice:s3cret
 
-# AWS
+# AWS (the --table is the Services table, not the legacy Accounts table)
 node --import tsx tools/seed-aws-accounts.ts \
-  --table StagingAccounts --endpoint http://localhost:8000 \
+  --table StagingServices --endpoint http://localhost:8000 \
   --accounts alice:s3cret
 ```
 
-> **NickServ accounts vs SASL accounts.** NickServ registrations live in
-> the **`ServicesStore`** (`nickserv_accounts`), which is unified with the
-> SASL `AccountStore` the seed scripts above populate: a NickServ
-> registration is a SASL account and vice versa, both scrypt-hashed (see
-> the [walkthrough](#13-end-to-end-walkthrough)). The recommended way to
-> create a NickServ account is the live
-> `PRIVMSG NickServ :REGISTER …` flow over an established connection. A
-> dedicated `tools/seed-nickserv-accounts.ts` mirroring the SASL seeders
-> is tracked as a follow-up; because credentials are scrypt-hashed at rest
-> (see [§11](#11-security-characteristics--known-gaps)), bulk-seeded rows
-> must supply a scrypt `algorithm`/`salt`/`hash` triple rather than a
-> plaintext password.
+> **NickServ accounts vs SASL accounts — unified.** Both SASL PLAIN and
+> NickServ IDENTIFY consult the **`ServicesStore`** (`nickserv_accounts`).
+> There is no separate SASL credential table: a NickServ registration is a
+> SASL account and vice versa, both scrypt-hashed (see the
+> [walkthrough](#13-end-to-end-walkthrough)). The recommended way to create
+> a NickServ account is the live `PRIVMSG NickServ :REGISTER …` flow over
+> an established connection. The seed scripts above populate
+> `nickserv_accounts` directly via the same scrypt-hashed `registerNick`
+> path; the legacy standalone `accounts` / `Accounts` table was dropped.
 
 Operators can manage AKILL/JUPE entries via `PRIVMSG OperServ` (oper-only,
 see [§7](#7-operserv--network-bans-jupes-raw-oper-only)), or pre-populate
@@ -464,13 +469,13 @@ them by writing directly into the `ServicesStore` backing tables.
 Be aware of the following when operating or contributing to services:
 
 - **NickServ passwords are stored scrypt-hashed** in the `ServicesStore`
-  (the same scrypt path the SASL `AccountStore` uses:
-  `InMemoryServicesStore.registerNick` hashes via `hashAccountCredential`
+  (`InMemoryServicesStore.registerNick` hashes via `hashAccountCredential`
   before persisting; `verifyNick` re-derives via `verifyHashedPassword`;
   the D1 `nickserv_accounts` table stores `algorithm`/`salt`/`hash`
-  columns, never the plaintext password). NickServ and SASL accounts are
-  unified, so a NickServ registration is a SASL account and vice versa.
-  Treat the services backing store (D1 database / DynamoDB table) as
+  columns, never the plaintext password). The `ServicesStore` is the
+  **single credential home**: SASL PLAIN, SASL EXTERNAL, PASS-auth
+  (`PASS <nick>:<password>`), and NickServ `IDENTIFY` all verify through
+  the same `verifyNick` / `verifyCertFP` surface. Treat the services backing store (D1 database / DynamoDB table) as
   sensitive regardless: restrict access and enable at-rest encryption
   (DynamoDB encryption-at-rest is on by default).
 - **HostServ `REQUEST` approval mode is configurable** — the default
@@ -576,3 +581,45 @@ When `bob` later identifies and joins, ChanServ auto-ops them:
 
 That completes the core nick + channel registration flow. From here, the
 per-service references in §4–§8 cover every shipped command.
+
+---
+
+## 14. Unified credential verification — four entry points
+
+The `ServicesStore` is the **single credential home**. Every
+account-setting path reduces to "this connection is now account X" via
+one of four entry points, all of which consult the same scrypt-hashed
+credential on the `nickserv_accounts` row:
+
+| Entry point | Mechanism | Credential verify call | Reducer |
+|-------------|-----------|------------------------|---------|
+| **SASL PLAIN** | `AUTHENTICATE PLAIN` (IRCv3 `sasl`) | `services.verifyNick(username, password)` | `commands/sasl.ts` |
+| **SASL EXTERNAL** (CertFP) | `AUTHENTICATE EXTERNAL` (IRCv3 `sasl` + mTLS) | `services.verifyCertFP(certSubject)` (subject resolved by the unchanged `MtlsIdentityProvider`) | `commands/sasl.ts` |
+| **NickServ `IDENTIFY`** | `PRIVMSG NickServ :IDENTIFY <password>` | `services.verifyNick(state.nick, password)` | `commands/nickserv.ts` |
+| **PASS-auth** | `PASS <nick>:<password>` at or after registration | `services.verifyNick(nick, password)` | `commands/account-auth.ts` (`attemptPassAccountAuth`) |
+
+All four share the same `applyAccountSuccess` downstream chain: stamp
+`state.account`, set read-only `+r`, seed read-markers, replay persisted
+away, deliver queued memos, re-apply assigned vhost, and emit `900
+RPL_LOGGEDIN` + `903 RPL_SASLSUCCESS` + the `account-notify` `ACCOUNT`
+broadcast.
+
+A NickServ-registered nick authenticates through any of the four entry
+points without a second registration — the credential set by
+`PRIVMSG NickServ :REGISTER` IS the SASL/PASS credential.
+
+### SASL EXTERNAL (CertFP)
+
+SASL EXTERNAL maps a verified client-certificate subject to an account.
+The edge platform (CF API Shield mTLS, AWS API Gateway custom-domain
+mTLS) terminates TLS and validates the client cert; the verified subject
+is surfaced to the Worker / Lambda via the unchanged
+`MtlsIdentityProvider` port. The subject→account lookup lives in
+`ServicesStore.verifyCertFP`, which scans `certSubjects: string[]` on
+each registered nick (byte-exact, case-sensitive comparison — cert
+subjects are NOT case-folded). `addCertFP(account, subject)` /
+`removeCertFP(account, subject)` mutators are shipped for an upcoming
+NickServ `CERT ADD`/`LIST`/`DEL` command (Atheme parity); the
+`cert_subjects` column on `nickserv_accounts` / the `certSubjects`
+attribute on the DynamoDB `Services` item carries the array (JSON-encoded
+`'[]'` by default).

package/docs/WebClientGuide.md

@@ -11,9 +11,19 @@ Cross-reference: `PLAN.md` §6.1 (CF mapping), `docs/PlanWebClient.md`
 (design), `docs/Cloudflare-Deployment-Guide.md` (Worker deploy),
 `apps/cf-worker/wrangler.toml`, `apps/web/`.
 
+> **AWS counterpart.** This doc covers the **Cloudflare** web-client
+> path, where the Worker serves both the SPA and the WebSocket from
+> one origin. The AWS deployment **cannot** unify them — the SPA
+> lives on CloudFront (S3 + OAC) and the WebSocket endpoint on API
+> Gateway, so the baked config carries the API Gateway wss URL as a
+> literal and the deploy is a separate two-phase pipeline (stack →
+> bake → s3 sync → invalidate). For the AWS web client — construct,
+> build, deploy pipeline, the `WEB_ORIGINS` CSWSH defence, and custom
+> domain — see **`docs/AWS-Deployment.md` §16 (Web client)**.
+
 **Acceptance criterion (TICKET-139):** a new contributor can
 `git submodule update --init`, `pnpm install`,
-`pnpm --filter web build:staging`, and `wrangler deploy --env staging`
+`pnpm --filter web build`, and `wrangler deploy`
 following only this doc.
 
 ---
@@ -82,7 +92,7 @@ pnpm --version          # 11.x
 
 ---
 
-## 3. Quickstart (clean checkout → deployed staging SPA)
+## 3. Quickstart (clean checkout → deployed SPA)
 
 ```bash
 # 1. Pull submodules (docs wiki + Kiwi IRC upstream sources).
@@ -91,9 +101,9 @@ git submodule update --init
 # 2. Install workspace deps.
 pnpm install
 
-# 3. Build the SPA + landing page (default config = staging target).
-pnpm --filter web build:staging
-#    Equivalent: pnpm --filter @serverless-ircd/web build:staging
+# 3. Build the SPA + landing page (default config = dev target).
+pnpm --filter web build
+#    Equivalent: pnpm --filter @serverless-ircd/web build
 #    → apps/web/dist/index.html        (landing page)
 #    → apps/web/dist/webclient/index.html    (Kiwi SPA)
 #    → apps/web/dist/webclient/static/config.json  (baked, env-specific)
@@ -107,9 +117,9 @@ pnpm --filter @serverless-ircd/cf-worker dev
 #    → http://localhost:8787/webclient/  Kiwi SPA
 #    → ws://localhost:8787/        IRC-over-WebSocket (same endpoint)
 
-# 6. Deploy staging (Worker + assets in one command).
-pnpm deploy:cf:staging
-#    → wrangler deploy --env staging
+# 6. Deploy (Worker + assets in one command).
+pnpm deploy:cf
+#    → wrangler deploy
 ```
 
 Open `http://localhost:8787/webclient/` in a browser — Kiwi boots, reads
@@ -131,14 +141,14 @@ The build is an orchestrated layering over the upstream Kiwi build —
 
 | `pnpm ...` command | Reads | Bakes into `dist/webclient/static/config.json` |
 |---|---|---|
-| `--filter web build` | `static/config.json` | default (staging-shaped) config |
-| `--filter web build:staging` | `static/config.staging.json` | staging config |
+| `--filter web build` | `static/config.json` | dev default config |
 | `--filter web build:prod` | `static/config.prod.json` | prod config |
 
-`--env` is parsed by `src/build-env.ts`; an unknown value aborts the
-build with a readable error. The selected file is validated against the
-Zod schema (`src/config-schema.ts`) **before** it is baked, so a
-malformed config fails the build rather than shipping a broken SPA.
+`--env` is parsed by `src/build-env.ts`; an unknown value (including the
+retired `staging`) aborts the build with a readable error. The selected
+file is validated against the Zod schema (`src/config-schema.ts`)
+**before** it is baked, so a malformed config fails the build rather
+than shipping a broken SPA.
 
 ### 4.2 What the build does, in order
 
@@ -172,9 +182,9 @@ The schema models only the fields ServerlessIRCd cares about; the rest
 of Kiwi's surface is passed through untouched (`.passthrough()`).
 
 ```jsonc
-// static/config.staging.json
+// static/config.prod.json
 {
-  "windowTitle": "ServerlessIRCd (staging)",
+  "windowTitle": "ServerlessIRCd",
   "startupOptions": {
     "server": "{{hostname}}",   // resolved to window.location.hostname at boot
     "direct": true,             // MUST be true — direct WS, no kiwiServer gateway
@@ -191,7 +201,7 @@ Field notes (see the schema docstrings for the full rationale):
 - **`startupOptions.server`** — `{{hostname}}` (or `{{host}}` to keep
   a non-default port) is a Kiwi template resolved by the browser to
   `window.location.hostname` at load time. This is what lets one build
-  artifact target staging, prod, preview, and PR deploys without a
+  artifact target prod, preview, and PR deploys without a
   per-env hostname. A literal hostname is also accepted.
 - **`startupOptions.direct`** — MUST be `true`. ServerlessIRCd is a
   direct IRC-over-WebSocket server; the Kiwi default (`false`) routes
@@ -209,7 +219,7 @@ Field notes (see the schema docstrings for the full rationale):
 A malformed config aborts the build with an aggregated error, e.g.:
 
 ```
-config.staging.json: Invalid Kiwi web config:
+config.prod.json: Invalid Kiwi web config:
   - startupOptions.port: port must be a valid TCP port (1-65535)
   - startupOptions.channel: must begin with '#'
 ```
@@ -275,7 +285,7 @@ WEB_ORIGINS = "https://irc.example.com,https://web.example.com"
 
 ```bash
 # or per-deploy via the secret store / dashboard env vars:
-wrangler secret put WEB_ORIGINS --env staging
+wrangler secret put WEB_ORIGINS
 ```
 
 ### 5.3 Responses
@@ -323,8 +333,8 @@ node apps/cf-worker/scripts/smoke.mjs
 ### 6.2 Iterate on the SPA config without rebuilding Kiwi
 
 The Kiwi upstream build is the slow step. For a config-only change,
-edit `static/config.staging.json`, then re-run
-`pnpm --filter web build:staging` — step 2 of the build reuses
+edit `static/config.prod.json`, then re-run
+`pnpm --filter web build:prod` — step 2 of the build reuses
 `upstream/node_modules` and skips straight to re-baking the config
 (steps 4–6 are fast).
 
@@ -502,8 +512,7 @@ git submodule update --init          # docs + apps/web/upstream (Kiwi)
 pnpm install
 
 # Build the SPA + landing page (pick the env)
-pnpm --filter web build              # default config (staging-shaped)
-pnpm --filter web build:staging      # static/config.staging.json
+pnpm --filter web build              # default config (dev target)
 pnpm --filter web build:prod         # static/config.prod.json
 
 # Local dev (Worker serves SPA + landing page + WS on one origin)
@@ -511,8 +520,8 @@ pnpm build                           # build the rest of the workspace
 pnpm --filter @serverless-ircd/cf-worker dev   # http://localhost:8787
 node apps/cf-worker/scripts/smoke.mjs          # WS smoke
 
-# Deploy staging (Worker + assets in one command)
-pnpm deploy:cf:staging               # wrangler deploy --env staging
+# Deploy (Worker + assets in one command)
+pnpm deploy:cf                       # wrangler deploy
 
 # Tests / lint
 pnpm --filter web test
@@ -527,7 +536,7 @@ Key files:
 | `apps/web/scripts/build.mjs` | Orchestrates the upstream Kiwi build + layers our config. |
 | `apps/web/src/config-schema.ts` | Zod schema for `static/config.*.json` (the only TS we own). |
 | `apps/web/src/build-env.ts` | `--env` → config-file resolution (unit-tested). |
-| `apps/web/static/config.{,staging,prod}.json` | Per-env Kiwi configs (validated at build time). |
+| `apps/web/static/config.{,prod}.json` | Kiwi configs (validated at build time). |
 | `apps/web/landing/index.html` | Static landing page (project front door), copied to `dist/index.html`. |
 | `apps/web/tests/build-smoke.test.ts` | Landing-page + build-output assertions. |
 | `apps/cf-worker/src/worker.ts` | Edge handler: WS → `ConnectionDO`, `/health`, else `env.ASSETS`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.9.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.9.0"
+    "@serverless-ircd/aws-adapter": "0.11.0"
   },
   "scripts": {
     "build": "turbo run build",
@@ -32,13 +32,10 @@
     "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:staging": "pnpm --filter @serverless-ircd/cf-worker deploy:staging",
-    "deploy:cf:prod": "pnpm --filter @serverless-ircd/cf-worker deploy:prod",
-    "smoke:cf:staging": "pnpm --filter @serverless-ircd/cf-worker smoke:staging",
-    "deploy:cf-tcp:staging": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:staging",
-    "deploy:cf-tcp:prod": "pnpm build && pnpm --filter @serverless-ircd/cf-tcp-container deploy:prod",
-    "deploy:aws:staging": "pnpm build && pnpm --filter @serverless-ircd/aws-stack deploy:staging",
-    "deploy:aws:prod": "pnpm build && pnpm --filter @serverless-ircd/aws-stack deploy:prod",
-    "smoke:aws:staging": "pnpm --filter @serverless-ircd/aws-stack smoke:staging"
+    "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",
+    "smoke:aws": "pnpm --filter @serverless-ircd/aws-stack run smoke"
   }
 }

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.9.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 };
 }

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

@@ -239,15 +239,42 @@ export class AwsRuntime implements IrcRuntime {
    * phase — the APIGW call count is bounded by the genuine recipient set.
    */
   async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    await this.fanOutByUserMode(lines, except, 'wallops');
+  }
+
+  /**
+   * Oper-only notice fanout (the OPER reducer's per-IP lockout notice).
+   * Identical enumeration to {@link broadcastWallops} but the recipient
+   * gate is user mode `+o`: a filtered `Scan` of the `Connections` table
+   * followed by a `PostToConnection` per oper. The same cost note applies
+   * — the scan reads the whole table — but lockout notices only fire when
+   * a host trips the failed-OPER budget, so the rate is bounded by
+   * attacker behaviour, not by legitimate traffic.
+   */
+  async broadcastOperNotice(lines: RawLine[], except?: ConnId): Promise<void> {
+    await this.fanOutByUserMode(lines, except, 'oper');
+  }
+
+  /**
+   * Shared fan-out for {@link broadcastWallops} / {@link broadcastOperNotice}:
+   * paginated filtered `Scan` over `userModes.<mode>`, skipping `except`,
+   * delivering via `send` (which short-cuts the bound connection through
+   * the in-process handlers and tolerates vanished sockets).
+   */
+  private async fanOutByUserMode(
+    lines: RawLine[],
+    except: ConnId | undefined,
+    mode: 'wallops' | 'oper',
+  ): Promise<void> {
     let startKey: Record<string, NativeAttributeValue> | undefined;
     // Paginate the scan: DynamoDB caps a single Scan at 1 MB. Loop until
-    // no `LastEvaluatedKey` remains so every +w connection is reached.
+    // no `LastEvaluatedKey` remains so every matching connection is reached.
     do {
       const result = await this.dynamo.send(
         new ScanCommand({
           TableName: this.tables.Connections,
           FilterExpression: 'userModes.#m = :true',
-          ExpressionAttributeNames: { '#m': 'wallops' },
+          ExpressionAttributeNames: { '#m': mode },
           ExpressionAttributeValues: { ':true': true },
           ...(startKey !== undefined ? { ExclusiveStartKey: startKey } : {}),
         }),
@@ -259,7 +286,7 @@ export class AwsRuntime implements IrcRuntime {
         // `send` short-cuts the bound connection through the in-process
         // handlers and catches GoneException so vanished sockets are
         // cleaned up rather than aborting the fan-out mid-loop.
-        if (row.userModes.wallops) {
+        if (mode === 'wallops' ? row.userModes.wallops : row.userModes.oper) {
           await this.send(connId, lines);
         }
       }