serverless-ircd 0.8.0 → 0.10.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),
@@ -77,7 +77,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,
@@ -169,25 +169,25 @@ 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).
+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
 
@@ -197,7 +197,7 @@ 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:
@@ -208,7 +208,7 @@ TLS on :6697 → plaintext TCP to the container origin on :6667.
 ```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"
 ```
 
@@ -218,7 +218,7 @@ CI does the same — see `.github/workflows/deploy-cf-tcp.yml` step
 ### 5.4 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 +226,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`
@@ -360,7 +339,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 +363,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.
 
 ---
 
@@ -481,16 +461,12 @@ terraform version                            # >= 1.5
 pnpm build
 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
 
 # Tests
 pnpm --filter @serverless-ircd/cf-tcp-container test

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
 ```
 

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.
 
 ---
 
@@ -126,6 +133,38 @@ Notable conventions:
   `519` (ChanServ `+R` JOIN gate), `432` (OperServ JUPE), `404` (ChanServ
   `+R`/`+M` send gates), `472` (services-only channel-mode letters).
 
+### Shortcut aliases (`/NICKSERV`, `/NS`, `/CS`, …)
+
+For compatibility with the Atheme/Anope services convention (and IRCd
+alias modules such as InspIRCd `m_alias` / UnrealIRCd `alias{}`), every
+service also accepts a **shortcut verb** that the daemon rewrites to the
+canonical `PRIVMSG <ServiceNick> :<joined args>` before routing. These are
+not RFC-standardized but are widely expected by clients and users.
+
+| Shortcut verb(s) | Equivalent to |
+|---|---|
+| `NICKSERV`, `NS` | `PRIVMSG NickServ :<args>` |
+| `CHANSERV`, `CS` | `PRIVMSG ChanServ :<args>` |
+| `HOSTSERV`, `HS` | `PRIVMSG HostServ :<args>` |
+| `MEMOSERV`, `MS` | `PRIVMSG MemoServ :<args>` |
+| `OPERSERV`, `OS` | `PRIVMSG OperServ :<args>` |
+
+The alias verb is the first token; everything after it is joined with
+single spaces and becomes the `PRIVMSG` trailing body, so e.g.
+`NICKSERV IDENTIFY hunter2` behaves identically to
+`PRIVMSG NickServ :IDENTIFY hunter2`, and `NS REGISTER pw email` is the
+same as `PRIVMSG NickServ :REGISTER pw email`. A colon-trailing form
+(`NS :IDENTIFY hunter2`) is accepted too. The verbs are matched
+case-insensitively. The alias → service nick table is the single source
+of truth in `packages/irc-core/src/commands/service-aliases.ts`
+(`SHORTCUT_TO_SERVICE`); both the dispatcher rewrite and the service-nick
+routing consult it, so no service-reducer changes were needed.
+
+When no `ServicesStore` is bound, a shortcut behaves exactly like a direct
+`PRIVMSG` to the service nick — it falls through to the normal nick-target
+path (a `401 ERR_NOSUCHNICK` for the unrecognised pseudo-client), never a
+bare `421 ERR_UNKNOWNCOMMAND`.
+
 ---
 
 ## 4. NickServ — nick registration & identification
@@ -142,8 +181,9 @@ policy, and nick-info queries. A registered nick is an account.
 | `REGISTER` | `PRIVMSG NickServ :REGISTER <password> <email>` | Registers the *current* nick. Does **not** auto-identify (no `+r` set). Reply: `Nickname <nick> is now registered.` Already-registered → `Nickname <nick> is already registered.` |
 | `IDENTIFY` | `PRIVMSG NickServ :IDENTIFY [nick] <password>` | One-arg form identifies the current nick; two-arg form identifies a named nick. On success: sets `state.account`, sets user mode **`+r`**, fans `ACCOUNT` to `account-notify` peers, then delivers unread MemoServ memos. Reply: `You are now identified for nick <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:`, `Email:`. Unregistered → `Nick <target> is not registered.` |
+| `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`.
 
@@ -399,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
@@ -432,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
@@ -544,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`. |