serverless-ircd 0.7.0 → 0.8.0

package/docs/Services.md

@@ -0,0 +1,546 @@
+# IRC Services Reference
+
+Operator and contributor reference for ServerlessIRCd's integrated IRC
+services — **NickServ**, **ChanServ**, **HostServ**, **OperServ**, and
+**MemoServ**. These ship as part of the daemon itself: there is no separate
+services process, no pseudo-server, and no server-to-server (S2S) link.
+
+> **Migration caveat (read first).** The integrated-services design is
+> **not binary-compatible with Atheme or Anope.** There is no S2S protocol,
+> so an existing Atheme/Anope services process cannot connect to
+> ServerlessIRCd, and existing services databases cannot be imported.
+> Operators migrating from a services-aware network must **re-register
+> nicks and channels** against the ServerlessIRCd `ServicesStore`. See
+> [§12 Migration notes](#12-migration-notes-from-athemeanope).
+
+Cross-reference: `docs/PlanExtensions.md` §6 (architecture decision and
+services scope), `PLAN.md` §1 (S2S is an explicit non-goal), the
+`ServicesStore` port in `packages/irc-core/src/ports.ts`, and the
+per-service reducers in `packages/irc-core/src/commands/`.
+
+**Acceptance criterion (TICKET-131):** a new contributor can register a
+NickServ account and a ChanServ channel end-to-end following only this doc.
+See the [walkthrough in §13](#13-end-to-end-walkthrough).
+
+---
+
+## 1. Architecture: integrated services (not pseudo-servers)
+
+Two designs exist in the wild:
+
+- **Pseudo-client services (the Atheme / Anope model).** A separate process
+  connects to the ircd as one or more virtual IRC clients named `NickServ`
+  and so on; users interact via `PRIVMSG NickServ :REGISTER …`. The link
+  between ircd and services speaks a server-to-server protocol (TS6 / P10 /
+  IRCv3 S2S).
+- **Integrated services (this project).** Service names are reserved nicks
+  recognized by the daemon at `PRIVMSG` time and routed to dedicated pure
+  reducers backed by a `ServicesStore` port. **No S2S, no separate process,
+  no pseudo-client connection.**
+
+ServerlessIRCd chose **integrated services**. The rationale (full detail in
+`docs/PlanExtensions.md` §6.1):
+
+- S2S is an explicit `PLAN.md` §1 non-goal, and the pseudo-client model
+  requires it.
+- 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.
+- The serverless substrates (Cloudflare Durable Objects, AWS DynamoDB)
+  handle persistence natively; a separate long-running services process
+  would defeat the deployment model.
+
+**Trade-off:** integrated services are not binary-compatible with existing
+Atheme/Anope modules. Operators migrating from a services-aware network
+must re-register nicks and channels.
+
+---
+
+## 2. How services are enabled
+
+Services are present on a deployment **iff** a `ServicesStore` is injected
+into the actor's `Ctx.services`. Each adapter constructs and binds one when
+its services backing store is configured:
+
+| Adapter | Services backend | Wired when |
+|---------|------------------|------------|
+| **Cloudflare** | D1 (`nickserv_accounts`, `chanserv_channels`, …) | the `ACCOUNTS_DB` D1 binding is set — `loadD1ServicesStore()` in `packages/cf-adapter/src/d1-services-store.ts`, invoked from the connection Durable Object |
+| **AWS** | DynamoDB (single services table, partitioned) | a services table name is supplied — `loadDynamoServicesStore()` in `packages/aws-adapter/src/dynamo-services-store.ts` |
+| **in-memory / local CLI / tests** | `InMemoryServicesStore` (`Map`s) | always, for the local CLI and unit tests |
+
+Both D1 and DynamoDB backends are **write-behind**: the store loads a
+snapshot once per cold start into a synchronously-readable cache (reducers
+must stay pure and free of IO), and flushes writes back to the durable
+table. A redeploy/reconnect rehydrates from the persisted snapshot, so
+registrations and channel access lists survive.
+
+If no store is bound, every services command replies:
+```
+:NickServ!NickServ@services NOTICE <nick> :Services are not available on this server.
+```
+
+### Config knobs (`packages/irc-core/src/config.ts`)
+
+- **`servicesEnabled`** (`boolean`, optional) — currently gates only the
+  `ACCOUNTEXTBAN=a` ISUPPORT token advertised by `005`. It does **not**
+  gate the reducers; those are live whenever a store is injected.
+- **`nickEnforceGraceMs`** (`integer ≥ 0`, optional) — grace period, in
+  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`).
+
+---
+
+## 3. Conventions
+
+Every service command is sent as a `PRIVMSG` whose target is the service
+nick and whose trailing parameter is the subcommand and arguments:
+
+```
+PRIVMSG <Service> :<subcommand> [args…]
+```
+
+All service replies are `NOTICE`s from a fixed hostmask independent of the
+deployment's `serverName`:
+
+```
+:<Service>!<Service>@services NOTICE <nick> :<text>
+```
+
+Notable conventions:
+
+- **`PRIVMSG` only.** Services are routed only for `PRIVMSG`. A `NOTICE`
+  or `TAGMSG` to a service nick is not intercepted and falls through to the
+  normal nick-target path.
+- **Identification is the `+r` user mode.** A connection is "identified"
+  when NickServ `IDENTIFY` (or a SASL login) has set `state.account`. Many
+  commands require this.
+- **Case-folding.** All nicks, accounts, and channel keys in the store are
+  **rfc1459 case-folded** (advertised via `005 CASEMAPPING=rfc1459`);
+  display spellings are preserved on returned records.
+- **Numerics vs NOTICEs.** Services emit **no** success/error numerics of
+  their own — feedback is always a `NOTICE` from the pseudo-client. The
+  only numeric emissions tied to services are enforcement/gate codes:
+  `519` (ChanServ `+R` JOIN gate), `432` (OperServ JUPE), `404` (ChanServ
+  `+R`/`+M` send gates), `472` (services-only channel-mode letters).
+
+---
+
+## 4. NickServ — nick registration & identification
+
+Source: `packages/irc-core/src/commands/nickserv.ts`. Wire nick `NickServ`.
+
+NickServ owns nick registration, identification (`+r`), nick-enforcement
+policy, and nick-info queries. A registered nick is an account.
+
+### Commands
+
+| Command | Syntax | Notes |
+|---|---|---|
+| `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.` |
+| `SET ENFORCE` | `PRIVMSG NickServ :SET ENFORCE none|ghost|kill` | Requires identify as the owning account. See enforcement below. |
+
+Help / unknown command: `Available commands: REGISTER, IDENTIFY, DROP, INFO, SET`.
+
+### Nick enforcement
+
+`SET ENFORCE <policy>` decides what happens when an **unidentified** client
+uses a registered nick (checked at welcome completion and on every `NICK`
+change):
+
+- `none` (default) — warning NOTICE only:
+  `This nickname is registered and protected. If it is yours, IDENTIFY; otherwise choose another.`
+- `ghost` — force-disconnect the unidentified client after the grace period
+  (`nickEnforceGraceMs`, default 30 s); `0` makes it immediate.
+- `kill` — force-disconnect **immediately** with reason
+  `Nick enforced by NickServ`.
+
+> **Note on `IDENTIFY` vs SASL.** Both set `state.account` and the `+r`
+> user mode and broadcast `ACCOUNT`. They differ in what else runs: SASL
+> success additionally seeds persisted read-markers and replays persisted
+> away state; NickServ `IDENTIFY` additionally delivers unread memos. The
+> two paths are otherwise equivalent account-setting entry points.
+
+---
+
+## 5. ChanServ — channel registration & access
+
+Source: `packages/irc-core/src/commands/chanserv.ts`. Wire nick `ChanServ`.
+ChanServ-emitted `MODE` lines use hostmask `ChanServ!ChanServ@services`.
+
+ChanServ owns channel registration, founder/set management, the access list
+(SOP/AOP/HOP/VOP via `ACCESS` and shorthand), configurable level
+thresholds, and the `+r`/`+R`/`+M` channel modes.
+
+### Registration & info
+
+| Command | Syntax | Notes |
+|---|---|---|
+| `REGISTER` | `PRIVMSG ChanServ :REGISTER <#channel>` | Requires identify (founder = `state.account`). Sets channel mode **`+r`**. Reply: `Channel <channel> is now registered.` |
+| `DROP` | `PRIVMSG ChanServ :DROP <#channel>` | Founder-only. Clears `+r`/`+R`/`+M`. Reply: `Channel <channel> has been dropped.` |
+| `INFO` | `PRIVMSG ChanServ :INFO <#channel>` | Replies: `Channel:`, `Founder:`. |
+
+### `SET` (founder-only)
+
+All `SET` subcommands require the caller be identified as the channel
+founder.
+
+| Subcommand | Syntax | Effect |
+|---|---|---|
+| `FOUNDER` | `SET FOUNDER <#channel> <account>` | Transfers founder to a registered nick. |
+| `MLOCK` | `SET MLOCK <#channel> <modestring>` | Mode lock. Allowed letters: `i t n m s p r R M k l o v b` (optional leading `+`/`-`). An op later unsetting a positively-locked boolean letter triggers ChanServ to reassert it (`:ChanServ!ChanServ@services MODE <chan> +<letters>`). `*` or absent clears the lock. |
+| `RESTRICTED` | `SET RESTRICTED <#channel> ON|OFF` | Toggles channel mode **`+R`** (block unidentified). |
+| `KEEPTOPIC` | `SET KEEPTOPIC <#channel> ON|OFF` | Persists the topic; restores it when the channel is recreated after going empty. |
+
+### Access list (SOP / AOP / HOP / VOP)
+
+`ACCESS <#channel> ADD|DEL <account>` and the shorthand verbs
+`SOP`/`AOP`/`HOP`/`VOP` (each `ADD|DEL|LIST`) map an account to a privilege
+level. `ADD`/`DEL` are founder-only; `LIST` is read-only.
+
+Default shorthand levels and the auto-prefix they grant on `JOIN`:
+
+| Verb | Level | Auto-prefix on JOIN |
+|---|---|---|
+| `SOP` | 10 | `@` (op) |
+| `AOP` | 5 (`AUTOOP`) | `@` (op) |
+| `HOP` | 4 (`AUTOHALFOP`) | (halfop, where represented) |
+| `VOP` | 3 (`AUTOVOICE`) | `+` (voice) |
+
+A level **≥ `AUTOOP`** grants op; **≥ `AUTOVOICE`** grants voice; below
+that, no prefix. The channel **founder** always receives `@` on join. The
+auto-prefix is broadcast as `:ChanServ!ChanServ@services MODE <chan> +o|+v <nick>`
+so all clients update their display. (The first joiner to an empty channel
+gets `@` by RFC 2812, bypassing ChanServ.)
+
+### `LEVELS` (founder-only for `SET`/`RESET`)
+
+`LEVELS <#channel> SET|LIST|RESET` redefines the numeric threshold each
+auto-prefix op requires (`AUTOOP`, `AUTOHALFOP`, `AUTOVOICE`). `LIST` is
+read-only and falls back to the defaults when no override is set.
+
+### Channel modes introduced by ChanServ
+
+| Mode | Meaning | Set by |
+|---|---|---|
+| `+r` | Channel is registered | ChanServ `REGISTER` |
+| `+R` | Block join/message from unidentified nicks | `SET RESTRICTED ON` |
+| `+M` | Moderated-identified: only identified (or op/voice) may speak | (cleared on `DROP`; not directly set by a ChanServ command) |
+
+These three letters are **services-only**: a user `MODE` attempt to set
+them returns `472 ERR_UNKNOWNMODE`. Their enforcement:
+
+- `+R` **JOIN gate:** unidentified joiner →
+  `519 ERR_ALLMUSTREGISTER <chan> :You must register with NickServ to join this channel`.
+- `+R` / `+M` **PRIVMSG gate:** unidentified sender (and, for `+M`, any
+  non-op/non-voice) → `404 ERR_CANNOTSENDTOCHAN`.
+
+---
+
+## 6. HostServ — virtual hosts
+
+Source: `packages/irc-core/src/commands/hostserv.ts`. Wire nick `HostServ`.
+
+HostServ manages per-account virtual hosts (vhosts), layered on the
+existing cloak machinery. Toggling a vhost mutates the connection's host
+and broadcasts an IRCv3 `CHGHOST` (`chghost` cap) to every shared-channel
+peer.
+
+| Command | Syntax | Gating | Notes |
+|---|---|---|---|
+| `ON` | `PRIVMSG HostServ :ON` | identified | Activates the account's assigned vhost; `CHGHOST` broadcast. Reply: `Your vhost is now active.` |
+| `OFF` | `PRIVMSG HostServ :OFF` | identified | Restores the real (cloaked) host; `CHGHOST` broadcast. Reply: `Your vhost has been disabled.` |
+| `REQUEST` | `PRIVMSG HostServ :REQUEST <vhost>` | identified | Behaviour depends on `hostservAutoApproveVhosts` (see below). Auto-approve mode: records the vhost immediately; reply `Vhost <vhost> has been requested and approved.` Queue mode: records a pending request; reply `Vhost <vhost> is pending oper approval.` The vhost must match a DNS-shape grammar (labels ≤63 chars, ≤253 total). |
+| `SET` | `PRIVMSG HostServ :SET <account> <vhost>` | **oper-only** | Records a vhost directly against a registered nick. `*` clears. Not an oper → `You must be an oper to use SET.` |
+| `APPROVE` (alias `ACTIVATE`) | `PRIVMSG HostServ :APPROVE <account>` | **oper-only** | Activates the pending vhost request recorded via queue-mode `REQUEST`. Calls `setVhost` and replies `Vhost <vhost> for <account> has been approved and activated.` A best-effort NOTICE is sent to the requester via `SendToNick` when they are online, telling them to run `/msg HostServ ON` to apply the vhost to their active connection. |
+| `REJECT` | `PRIVMSG HostServ :REJECT <account>` | **oper-only** | Drops the pending vhost request without activating it. Replies `Vhost request for <account> has been rejected.` and best-effort NOTICEs the requester via `SendToNick` when they are online. |
+| `LIST` | `PRIVMSG HostServ :LIST` | **oper-only** | Enumerates every pending request as `<account>: <vhost>` NOTICE lines. Empty queue → `No pending vhost requests.` |
+
+### Approval mode (`hostservAutoApproveVhosts`)
+
+The `ServerConfig.hostservAutoApproveVhosts` knob (boolean, default
+`false`) selects how `REQUEST <vhost>` is handled:
+
+- **`true` (auto-approve):** the legacy behaviour. `REQUEST`
+  records the vhost against the account immediately via `setVhost`. The
+  user can then `/msg HostServ ON` to apply it. `APPROVE`/`REJECT`/`LIST`
+  are still wired but only relevant for any pre-existing pending requests.
+- **`false` (default — oper queue):** `REQUEST` records a **pending**
+  request via `ServicesStore.requestVhost` and replies that the request
+  is pending oper approval. The vhost is NOT activated and no `CHGHOST`
+  is emitted until an oper runs `APPROVE <account>`. `REJECT <account>`
+  drops the request; `LIST` enumerates the queue.
+
+The queue + the oper commands are available in either mode; only
+`REQUEST`'s routing through them is gated on the knob. The default
+(`false`) matches the Atheme/Anope convention of requiring oper review
+for vhosts; set `true` to restore the legacy self-service auto-approve.
+
+> **Pending-request delivery note.** When an oper `APPROVE`s or `REJECT`s
+> a pending request and the requester is online, HostServ delivers a
+> NOTICE via the actor layer's `SendToNick` (silently dropped when the
+> requester is offline). The actual `CHGHOST` application on the
+> requester's live connection is **not** done from the oper's reducer —
+> the pure reducer model forbids cross-connection state mutation — so
+> the requester must run `/msg HostServ ON` themselves to apply an
+> approved vhost to their active connection. The NOTICE tells them so.
+
+---
+
+## 7. OperServ — network bans, jupes, raw (oper-only)
+
+Source: `packages/irc-core/src/commands/operserv.ts`. Wire nick `OperServ`.
+
+> **Routing.** `PRIVMSG OperServ` is routed to the OperServ reducer in the
+> actor's target routing (alongside NickServ, ChanServ, HostServ, and
+> MemoServ). A client `PRIVMSG OperServ :<command>` reaches the reducer
+> instead of falling through to the nick-target path. Interception is
+> **PRIVMSG-only**: `NOTICE`/`TAGMSG OperServ` are not intercepted and fall
+> through to the normal user-target path, matching the other four services.
+>
+> **Enforcement hooks** (unchanged) are wired through the registration
+> reducer:
+> - **AKILL** — checked at welcome completion against the connecting
+>   hostmask; a match disconnects with reason `AKILL: network-wide ban`
+>   after a `NOTICE` from `OperServ!OperServ@services`.
+> - **JUPE** — checked on every `NICK` attempt; a juped nick is rejected
+>   with `432 ERR_ERRONEUSNICKNAME`.
+>
+> The command surface below (AKILL/JUPE/RAW management) is oper-gated and
+> now reachable by clients via `PRIVMSG OperServ`. A non-oper receives
+> `Permission denied — oper privileges required.` with no state change.
+
+Command surface (oper-only, reachable via `PRIVMSG OperServ`):
+
+| Command | Syntax | Notes |
+|---|---|---|
+| `AKILL ADD` | `PRIVMSG OperServ :AKILL ADD <mask> <reason>` | Records a network-wide ban; matched at connect time. Re-adding a mask replaces the reason. |
+| `AKILL DEL` | `PRIVMSG OperServ :AKILL DEL <mask>` | Removes a mask. |
+| `AKILL LIST` | `PRIVMSG OperServ :AKILL LIST` | Lists `<mask> — <reason>`. |
+| `JUPE` | `PRIVMSG OperServ :JUPE <nick> [reason]` | Blocks a nick/server name locally. |
+| `UNJUPE` | `PRIVMSG OperServ :UNJUPE <nick>` | Removes a jupe. |
+| `RAW` | `PRIVMSG OperServ :RAW <line>` | Emits a raw IRC line (recovery use only). Oper-only and logged. |
+
+Every subcommand requires oper privileges; non-opers get
+`Permission denied — oper privileges required.` with no state change.
+
+---
+
+## 8. MemoServ — offline messages
+
+Source: `packages/irc-core/src/commands/memoserv.ts`. Wire nick `MemoServ`.
+
+MemoServ queues messages for a registered nick and delivers them when the
+recipient next identifies (NickServ `IDENTIFY`) or logs in via SASL. All
+commands require identification. Memos are delivered as
+`:MemoServ!MemoServ@services NOTICE <nick> :[Memo #<id> from <from>] <body>`.
+
+| Command | Syntax | Notes |
+|---|---|---|
+| `SEND` | `PRIVMSG MemoServ :SEND <nick> <message>` | Records a memo against the recipient's account (recipient must be a registered nick). The body may contain spaces. Queued; delivered on the recipient's next identify/SASL login. |
+| `LIST` | `PRIVMSG MemoServ :LIST` | Lists **unread** memos: `#<id> <from>: <body>`. |
+| `READ` | `PRIVMSG MemoServ :READ <n>` | Displays memo `#n` and marks it read. |
+| `DEL` | `PRIVMSG MemoServ :DEL <n>` | Deletes memo `#n`. |
+
+---
+
+## 9. The `ServicesStore` port
+
+The services side effects are absorbed by a single synchronous port in
+`packages/irc-core/src/ports.ts` (synchronous because reducers are pure and
+free of IO; adapters pre-load a snapshot and flush writes asynchronously).
+The reference implementation `InMemoryServicesStore` ships in the same
+file; D1 and DynamoDB backends live in their adapter packages.
+
+Method groups (signatures abbreviated; see `ports.ts` for canonical forms):
+
+- **NickServ** — `registerNick`, `verifyNick`, `dropNick`, `isRegisteredNick`,
+  `setNickEnforce`/`getNickEnforce`, `getNick`.
+- **ChanServ (registration)** — `registerChannel`, `dropChannel`,
+  `getChannelFounder`, `setChannelAccess`/`getChannelAccess`/`listChannelAccess`.
+- **ChanServ (levels)** — `getChannelLevel`/`setChannelLevel`/
+  `listChannelLevels`/`resetChannelLevels`.
+- **ChanServ (record)** — `getChannel`, `setChannelFounder`,
+  `setChannelMlock`/`getChannelMlock`, `setChannelRestricted`,
+  `setChannelKeepTopic`, `setChannelTopic`/`getChannelTopic`.
+- **HostServ** — `setVhost`/`getVhost`, plus the pending-vhost queue
+  (`requestVhost`/`getPendingVhost`/`listPendingVhosts`/`approveVhost`/
+  `rejectVhost`) consumed by queue-mode `REQUEST` and the oper
+  `APPROVE`/`REJECT`/`LIST` commands.
+- **MemoServ** — `recordMemo`, `listMemos`, `markMemoRead`, `deleteMemo`.
+- **OperServ** — `addAkill`/`removeAkill`/`listAkills`/`matchAkill`,
+  `addJupe`/`removeJupe`/`isJuped`/`getJupe`/`listJupes`.
+- **Read-marker (IRCv3 `draft/read-marker`)** — `getLastReadMarker`/
+  `setLastReadMarker`/`listReadMarkers`.
+
+Password comparison is constant-time. All nick/account/channel keys are
+rfc1459 case-folded.
+
+---
+
+## 10. Admin tooling & seeding accounts
+
+Two seed scripts ship under `tools/` for **SASL accounts** (the
+scrypt-hashed `accounts`/`Accounts` store used by `AUTHENTICATE PLAIN`):
+
+- `tools/seed-cf-accounts.ts` — writes to a Cloudflare D1 `accounts` table
+  via `wrangler d1 execute`, scrypt-hashing each password.
+- `tools/seed-aws-accounts.ts` — writes to a DynamoDB `Accounts` table via
+  the AWS SDK, scrypt-hashing each password.
+
+Both accept `--accounts alice:s3cret bob:pw …` or `--file accounts.txt`
+(newline-delimited `username:password`).
+
+```
+# Cloudflare
+node --import tsx tools/seed-cf-accounts.ts \
+  --database serverless-ircd-accounts-staging --env staging --remote \
+  --accounts alice:s3cret
+
+# AWS
+node --import tsx tools/seed-aws-accounts.ts \
+  --table StagingAccounts --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.
+
+Operators can manage AKILL/JUPE entries via `PRIVMSG OperServ` (oper-only,
+see [§7](#7-operserv--network-bans-jupes-raw-oper-only)), or pre-populate
+them by writing directly into the `ServicesStore` backing tables.
+
+---
+
+## 11. Security characteristics & known gaps
+
+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`
+  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
+  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
+  (`hostservAutoApproveVhosts: false`) queues every request for oper
+  review via the `APPROVE`/`REJECT`/`LIST` commands (see [§6](#6-hostserv--virtual-hosts)).
+  Set `hostservAutoApproveVhosts: true` to restore the legacy
+  self-service auto-approve, where any identified user can self-assign a
+  DNS-shape vhost.
+- **OperServ management is oper-gated** — every `PRIVMSG OperServ`
+  subcommand (AKILL/JUPE/RAW) requires oper privileges; non-opers receive
+  `Permission denied — oper privileges required.` with no state change
+  (see [§7](#7-operserv--network-bans-jupes-raw-oper-only)).
+- **Memo bodies** are stored and replayed verbatim; no size cap beyond the
+  general IRC line-length budget applied at the wire.
+- **`+r` user mode** is set by NickServ `IDENTIFY` and SASL; it is not set
+  by the legacy `PASS <nick>:<password>` form (that path is tracked
+  separately).
+
+---
+
+## 12. Migration notes (from Atheme/Anope)
+
+- **No S2S, no services process.** An existing Atheme/Anope instance cannot
+  attach to ServerlessIRCd. Plan to **re-register** nicks and channels.
+- **Re-register nicks** with `PRIVMSG NickServ :REGISTER <password> <email>`
+  on the new server. There is no import path from Atheme/Anope databases.
+- **Re-register channels** with `ChanServ REGISTER` from the identified
+  founder, then re-create the access list via `ACCESS`/`SOP`/`AOP`/`HOP`/
+  `VOP`. MLOCK, RESTRICTED, and KEEPTOPIC must be re-applied with `SET`.
+- **OperServ parity is complete.** AKILL (connect-time enforcement) and
+  JUPE (nick-time enforcement) are live, and the AKILL/JUPE/RAW management
+  commands are client-reachable via `PRIVMSG OperServ` (oper-only, see
+  [§7](#7-operserv--network-bans-jupes-raw-oper-only)).
+- **HostServ vhost approval.** The default
+  (`hostservAutoApproveVhosts: false`) matches the Atheme/Anope
+  convention: `REQUEST` queues for oper `APPROVE`/`REJECT`/`LIST`
+  (see [§6](#6-hostserv--virtual-hosts)). Set `hostservAutoApproveVhosts: true`
+  to restore self-service auto-approve.
+- **Out of scope** (will not migrate): `BotServ` (channel bots are a
+  runtime cost serverless deployments should not absorb — run your own bot
+  as an ordinary client) and `StatServ` (covered by `STATS` and the
+  observability stack). Grouped/linked nicks and fantasy commands are also
+  out of scope for this pass.
+
+---
+
+## 13. End-to-end walkthrough
+
+This satisfies the TICKET-131 acceptance criterion: register a NickServ
+account and a ChanServ channel using only this doc. Connect to a
+services-enabled deployment with any IRC client and register first:
+
+```
+NICK alice
+USER alice 0 * :Alice
+PRIVMSG NickServ :REGISTER hunter2 alice@example.com
+```
+```
+:NickServ!NickServ@services NOTICE alice :Nickname alice is now registered.
+```
+
+The nick is registered but not yet identified. Identify to receive the `+r`
+user mode (required before registering a channel or sending memos):
+
+```
+PRIVMSG NickServ :IDENTIFY alice hunter2
+```
+```
+:NickServ!NickServ@services NOTICE alice :You are now identified for nick alice.
+```
+
+Now register a channel (you are the founder):
+
+```
+JOIN #mychannel
+PRIVMSG ChanServ :REGISTER #mychannel
+```
+```
+:ChanServ!ChanServ@services NOTICE alice :Channel #mychannel is now registered.
+:ChanServ!ChanServ@services MODE #mychannel +r
+```
+
+Add a friend (who has already registered their nick `bob`) to the access
+list as an auto-op, lock the topic, and restrict the channel to identified
+users:
+
+```
+PRIVMSG ChanServ :AOP #mychannel ADD bob
+PRIVMSG ChanServ :SET KEEPTOPIC #mychannel ON
+PRIVMSG ChanServ :SET RESTRICTED #mychannel ON
+```
+```
+:ChanServ!ChanServ@services NOTICE alice :Bob added to the access list for #mychannel at level 5.
+:ChanServ!ChanServ@services NOTICE alice :Keep-topic for #mychannel is now set to ON.
+:ChanServ!ChanServ@services NOTICE alice :Restricted (block unidentified) for #mychannel is now set to ON.
+```
+
+When `bob` later identifies and joins, ChanServ auto-ops them:
+
+```
+:ChanServ!ChanServ@services MODE #mychannel +o bob
+```
+
+That completes the core nick + channel registration flow. From here, the
+per-service references in §4–§8 cover every shipped command.