Phase 9: application services and admin completion

Implements PLAN.md Phase 9. internal/appservice reads registration files
(appservice.config_files), matches namespaces the way Synapse does
(anchored at the start), and delivers events to each service as
transactions read from the roomserver's event stream at a cursor kept in
appservice_state. A transaction in flight is recorded, so after a restart
it is resent under the same ID; failures back off from 2s to 5m, and a
successful ping cuts the backoff short.

In the Client-Server API an as_token acts as the service's sender or, with
?user_id=, as any existing user in its namespace. Services register and
log in their users with m.login.application_service; exclusive user and
alias namespaces are refused to everybody else with M_EXCLUSIVE. Unknown
aliases and users in a namespace are asked of the service first. The
ping endpoint reports M_URL_NOT_SET, M_BAD_STATUS, M_CONNECTION_FAILED
and M_CONNECTION_TIMEOUT. Services' own requests, and their users' when
rate_limited is false, skip the rate limiter.

Users can change their password (POST /account/password) and deactivate
their account (POST /account/deactivate), both behind the password.
Deactivation revokes tokens, deletes devices, optionally erases the
profile and leaves every room through a new userapi.AccountObserver.

The admin API is complete: user detail, the admin flag, deactivation and
reactivation, password resets, devices, media quotas
(media.max_user_storage_bytes plus per-user overrides), registration
tokens with use limits and expiry (registration.require_token), server
notices (internal/servernotices, server_notices.*), an editor for the
federation allow/deny lists persisted in server_settings, a delivery view
of the application services, and an audit log of every change.

Migration 0011 adds the registration token, server notice room, media
quota, audit log and appservice cursor tables. Policy lists are now
returned sorted. The Complement entrypoint loads the registrations
Complement mounts in /complement/appservice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/admin-api.md

@@ -44,7 +44,8 @@ The runtime federation switch of PLAN.md section 3.
   "enabled": false,
   "toggleable": true,
   "allowlist": [],
-  "denylist": []
+  "denylist": [],
+  "lists_edited": false
 }
 ```
 
@@ -54,8 +55,28 @@ and answers with the same document. `toggleable` is `false` when
 `PUT` then returns `409` and the panel should grey the switch out rather
 than offer something that will bounce.
 
-Editing the allow and deny lists is Phase 9. They are reported now because
-the dashboard has to show which servers a running Warp will talk to.
+The lists are lower-cased and sorted. `lists_edited` is `true` when they
+were set through `PUT /federation/lists` and replace the config file's.
+
+### `PUT /federation/lists`, `DELETE /federation/lists`
+
+```json
+{"allowlist": ["friend.example"], "denylist": []}
+```
+
+Replaces both lists. They take effect on the next request in either
+direction, and are kept in `server_settings` in place of the config
+file's, across restarts. Both have to be in the body (`[]` for an empty
+one): a panel that sent one and had the other silently kept would be one
+bug away from leaving a server it meant to cut off on the allowlist. A
+name that is not a server name is `400 M_INVALID_PARAM`.
+
+`DELETE` forgets the edited lists and puts the config file's back. Both
+answer with the `GET /federation` document.
+
+Unlike the switch, the lists are editable whatever
+`federation.allow_runtime_toggle` says: they are not a switch the file can
+pin.
 
 ### `GET /federation/destinations`
 
@@ -138,6 +159,259 @@ the admin's own action, not a public sign-up. `username` is normalised
 (lower-cased) like any other localpart. A taken name is
 `400 M_USER_IN_USE`, an unusable one `400 M_INVALID_USERNAME`.
 
+### One user: `/users/{userID}`
+
+`{userID}` is a full user ID of this server, `@alice:warp.example`. A user
+of another server is `400 M_INVALID_PARAM`, one that does not exist
+`404 M_NOT_FOUND`.
+
+`GET /users/{userID}` is the list row plus what it takes a count to know:
+
+```json
+{
+  "user_id": "@alice:warp.example",
+  "display_name": "Alice",
+  "admin": false,
+  "deactivated": false,
+  "created_at_ms": 1760000000000,
+  "devices": 2,
+  "joined_rooms": 5,
+  "media": {"uploads": 12, "bytes": 3145728, "quota_bytes": 104857600, "custom_quota": false}
+}
+```
+
+`joined_rooms` is absent on a server without a signing key, which has no
+rooms. Every change below answers with this document, so the panel can
+redraw from the response.
+
+| Endpoint | Body | What |
+|---|---|---|
+| `PUT /users/{userID}/admin` | `{"admin": true}` | grant or revoke the admin flag |
+| `POST /users/{userID}/deactivate` | `{"erase": false}` (optional) | deactivate the account |
+| `POST /users/{userID}/reactivate` | — | let it log in again |
+| `POST /users/{userID}/password` | `{"password": "...", "logout_devices": true}` | set a new password |
+
+**Deactivation** does what the user's own `POST /account/deactivate` does.
+Every token stops working at once; the devices go, with their keys and
+pushers; the user leaves every room, rejects every invite and withdraws
+every knock. With `erase`, the display name and avatar are cleared first,
+so the leave events carry neither. The name stays taken: a new user with
+the old user's ID would inherit what other servers and clients remember
+about the old one. Deactivating a deactivated account changes nothing.
+
+**Reactivation** gives back the ability to log in, with the old password
+unless a new one is set. Nothing else comes back: the rooms were left and
+the devices are gone.
+
+**A password reset** logs every device out unless `logout_devices` is
+`false`. An admin resetting a password is usually doing it because
+somebody else has the account.
+
+An admin cannot revoke their own admin flag or deactivate themselves
+(`403`). Both are one click from locking the last admin out of the panel,
+and both are easy to do by accident on a table of users. Another admin can
+still do either.
+
+### `GET /users/{userID}/devices`, `DELETE /users/{userID}/devices[/{deviceID}]`
+
+```json
+{"devices": [{"device_id": "QWERTYUIOP", "display_name": "Phone", "created_at_ms": 1760000000000,
+              "last_seen_ms": 1760600000000, "last_seen_ip": "203.0.113.4", "user_agent": "Element/1.11"}]}
+```
+
+`DELETE` on one device logs that session out, taking its keys and pushers
+with it. An unknown device is `404`. On the collection it logs out every
+device. Unlike the client's own device deletion, no password is asked for:
+the admin token is the authority here.
+
+### `GET /users/{userID}/media`, `PUT`/`DELETE /users/{userID}/media/quota`
+
+```json
+{"uploads": 12, "bytes": 3145728, "quota_bytes": 104857600, "custom_quota": false}
+```
+
+What the user has uploaded, against their quota. Every upload counts at
+its own size, even when two are the same bytes and the server keeps one
+copy: a quota is about what a user asked this server to keep.
+`quota_bytes` is the quota in force, `0` for none. `custom_quota` says
+whether it was set for this user or comes from
+`media.max_user_storage_bytes`.
+
+`PUT {"max_bytes": 1073741824}` gives the user a quota of their own (`0`
+for no limit). `DELETE` puts them back on the configured one. A quota below
+what the user already has deletes nothing; it stops further uploads until
+they are back under it.
+
+An upload that would go over is refused as it arrives, with
+`413 M_TOO_LARGE`. Every client already tells the user an upload was too
+big, and that is what it was. Two uploads racing for the last of a quota
+can both get in: a quota bounds what a user keeps, it is not an
+accounting system.
+
+### Registration tokens
+
+Tokens with a use limit and an expiry, for the `m.login.registration_token`
+stage of sign-up. The stage is in the flow when `registration.tokens` is
+non-empty or `registration.require_token` is on. The config file's tokens
+and these are both accepted. The config file's are never listed here:
+they are in the config file, and this would be the one place a secret
+from it is served over HTTP.
+
+```
+GET    /registration_tokens
+POST   /registration_tokens            {"token": "...", "length": 16, "uses_allowed": 5, "expiry_time_ms": 1760000000000}
+GET    /registration_tokens/{token}
+PUT    /registration_tokens/{token}    {"uses_allowed": null, "expiry_time_ms": 1760000000000}
+DELETE /registration_tokens/{token}
+```
+
+A token:
+
+```json
+{
+  "token": "invite-1",
+  "uses_allowed": 5,
+  "completed": 2,
+  "expiry_time_ms": null,
+  "created_at_ms": 1760000000000,
+  "valid": true
+}
+```
+
+`uses_allowed` and `expiry_time_ms` are `null` for no limit. `valid` is
+whether a registration could use the token now. The list also carries
+`"required"`, whether sign-up asks for a token at all. A token made on a
+server that does not ask is never needed.
+
+`POST` with no `token` generates one of `length` characters (16 by
+default) from `A-Za-z0-9`. A chosen token is 1 to 64 of the characters
+`A-Za-z0-9._~-`, the spec's grammar. A taken or malformed one is
+`400 M_INVALID_PARAM`. It answers `201`.
+
+`PUT` changes only the fields in the body; `null` removes a limit. Raising
+`uses_allowed` on a used-up token makes it usable again. `DELETE` does not
+affect accounts registered with the token.
+
+A use is spent when the account is created, not when the stage is passed,
+so an abandoned sign-up costs nothing. Checking and spending are one
+statement, so two sign-ups racing for the last use cannot both have it.
+The one that loses is refused with `403 M_FORBIDDEN` at the end of its
+flow.
+
+### `POST /server_notices`
+
+```json
+{"user_id": "@alice:warp.example", "content": {"msgtype": "m.text", "body": "Maintenance at 22:00 UTC."}}
+```
+
+Sends a message from the server to one of its users, and answers
+`{"room_id": "...", "event_id": "..."}`. Needs `server_notices.enabled`
+and a signing key. Without them it is `409`, the server's configuration
+refusing.
+
+Each user gets one notice room. It is made the first time, by the notices
+user (`server_notices.localpart`, created at startup), and carries the
+`m.server_notice` tag in the user's room account data, so a client can
+show it apart from other rooms. A second notice goes to the same room. A
+user who left is invited back. The user cannot answer: the power levels
+give them none of the levels a message needs. The user does not have to be
+online: the invite and the message wait for them.
+
+`content.body` is required. A missing `msgtype` becomes `m.text`. An
+unknown user is `404`; a deactivated one `403`.
+
+### `GET /appservices`
+
+The registered application services and how delivery to each is going.
+Registrations are files read at startup, so this is a view, not an editor.
+Tokens are never shown.
+
+```json
+{
+  "appservices": [
+    {
+      "id": "telegram",
+      "url": "http://localhost:29317",
+      "sender": "@telegrambot:warp.example",
+      "rate_limited": false,
+      "protocols": [],
+      "namespaces": {
+        "users": [{"regex": "@telegram_.*:warp\\.example", "exclusive": true}],
+        "aliases": [],
+        "rooms": []
+      },
+      "delivery": {
+        "stream_pos": 1204,
+        "behind": 0,
+        "txn_id": 88,
+        "events_delivered": 412,
+        "failures": 0,
+        "last_success_ms": 1760600000000,
+        "last_failure_ms": 0,
+        "retry_at_ms": 0
+      }
+    }
+  ]
+}
+```
+
+`delivery` is absent for a service without a URL, which is sent nothing.
+`behind` is how many stream positions it has still to read: not all of
+them will concern it. While `failures` is above zero the service is being
+backed off, `last_error` says why, and `retry_at_ms` is the next attempt.
+See [appservices.md](appservices.md).
+
+### `GET /audit_log`
+
+```
+GET /audit_log?limit=50&before=1234&actor=@root:warp.example&action=user.deactivate
+```
+
+Every change made through the admin API, newest first:
+
+```json
+{
+  "entries": [
+    {
+      "id": 1235,
+      "ts_ms": 1760600000000,
+      "actor": "@root:warp.example",
+      "action": "user.deactivate",
+      "target": "@mallory:warp.example",
+      "details": {"erase": true}
+    }
+  ],
+  "next_before": 1235
+}
+```
+
+The log is paged by ID, not by offset. It grows at the top while an admin
+reads it, and an offset would shift under them. Pass `next_before` as
+`?before=` for the next page; it is absent on the last one. `actor` and
+`action` filter exactly.
+
+The actions:
+
+| Action | Target | Details |
+|---|---|---|
+| `federation.switch` · `registration.switch` | — | `enabled` |
+| `federation.lists` · `federation.lists_reset` | — | `allowlist`, `denylist` |
+| `federation.destination_reset` | server name | — |
+| `user.create` | user | `admin` |
+| `user.admin` | user | `admin` |
+| `user.deactivate` · `user.reactivate` | user | `erase` |
+| `user.password` | user | `logout_devices` |
+| `user.device_delete` | user | `device_id`, or `all` |
+| `user.media_quota` | user | `max_bytes` (`null` for a reset) |
+| `room.purge` · `room.force_leave` | room | `user_id` |
+| `registration_token.create` · `.update` · `.delete` | token | `uses_allowed`, `expiry_time_ms` |
+| `server_notice.send` | user | `room_id`, `event_id` |
+
+An entry is written after the change has been made. If the write fails,
+that is logged and the request still succeeds: the change has happened,
+and a `500` for something that worked would have the panel retry it. The
+same information is in the server log either way.
+
 ### `GET /rooms`
 
 ```
@@ -259,14 +533,12 @@ configuration is what refuses it.
 
 ## Not here yet
 
-Phase 9 completes the admin API: deactivating users, resetting passwords,
-revoking devices, granting the admin flag, registration token management,
-the federation allow/deny list editor, server notices, media quotas and an
-audit log of admin actions.
+The room endpoints are still the Phase 3 set. Still missing: a room's
+state and recent events, for an operator looking at a report, and a way to
+publish or withdraw a room from the directory without borrowing a member's
+token. Media has quotas but no purge or quarantine yet; see
+[media.md](media.md#known-gaps).
 
-The room endpoints will grow with it: a room's state and its recent events
-for an operator looking at a report, and a way to publish or withdraw a room
-from the directory without borrowing a member's token.
-
-A server started without a signing key has no roomserver, and the four room
-endpoints then answer `503` rather than failing on the first call.
+A server started without a signing key has no roomserver. The four room
+endpoints then answer `503` rather than failing on the first call, and
+server notices answer `409`.