Phase 1: accounts and sessions

Implements PLAN.md Phase 1. A client can now register, log in, manage its
devices and set its profile; an operator can create accounts and flip the
runtime switches. There are still no rooms and no real /sync.

userapi: accounts, argon2id passwords in PHC format, devices, access and
refresh tokens stored as SHA-256 hashes, account data and the admin flag.
Its storage interface is storage.UserStore, implemented once in sqlstore
with `?` placeholders; the postgres driver supplies a rebind function and
unique-violation recognition rather than keeping a second copy of thirty
statements. Timestamps in these tables are int64 milliseconds, the unit the
Client-Server API uses on the wire.

Client-Server API: register (user-interactive auth with m.login.dummy and
optional registration tokens), register/available, token validity, login
with m.login.password, logout, logout/all, refresh, account/whoami,
capabilities, devices/* with password-gated deletion, profile/*, global and
per-room account data.

GET /sync is a deliberate placeholder: it answers a valid token with an
empty but well-formed response and refuses a revoked one. Phase 1 has no
rooms, so that is the whole truth, and it is what makes session revocation
observable. Phase 4 replaces it with the syncapi.

Auth middleware resolves a bearer token (header or the legacy query
parameter) to a device and user, answering an expired token with the soft
logout the spec asks for. Rate limiting is a token bucket per endpoint class
keyed on the client address, returning M_LIMIT_EXCEEDED with retry_after_ms.

adminapi v1 under /_warp/admin/v1: admin-only auth via a normal Matrix
token, GET/PUT /federation and /registration driving internal/settings and
reporting a config-pinned switch as a 409, GET/POST /users, GET /stats.

warp create-account [--admin] creates the first account straight in the
database, so a new install with registration off has a way in.

Complement is wired up for the federation=off profile: an image meeting its
contract, an entrypoint that configures Warp entirely from WARP_*
variables, and a runner that builds, clones and executes the target set
(TestRegistration, TestLogin, TestDeviceManagement). It has not been run
yet -- there is no container runtime on the development machine -- so the
three tests' assertions were read from the Complement sources and pinned as
httptest tests instead, and CI gained a job that runs the real thing.

Also fixes a .gitignore bug from Phase 0: the unanchored `warp` pattern,
meant for the built binary, also matched the directory server/cmd/warp and
silently excluded the entire command package from the repository. The
binary patterns are now anchored to the repository root, and cmd/warp is
committed for the first time.

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

docs/README.md

@@ -3,6 +3,7 @@
 | Document | What |
 |---|---|
 | [configuration.md](configuration.md) | every setting, and its environment variable |
-| [development.md](development.md) | building, testing, adding a migration |
+| [development.md](development.md) | building, testing, Complement, adding a migration |
+| [admin-api.md](admin-api.md) | `/_warp/admin/v1`: the operator API behind the admin panel |
 
 The design and roadmap are in [PLAN.md](../PLAN.md) at the repository root.

docs/admin-api.md

@@ -0,0 +1,137 @@
+# Admin API
+
+Everything under `/_warp/admin/v1` is Warp's own, not Matrix. Clients use
+the Client-Server API; this is the operator's surface and the backend for
+the admin panel (`apps/admin`, PLAN.md section 8.1).
+
+## Authentication
+
+A normal Matrix access token belonging to an account with the admin flag.
+The panel logs in the way any client does, so there is no second credential
+to manage:
+
+```sh
+TOKEN=$(curl -s localhost:8008/_matrix/client/v3/login \
+  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"root"},"password":"..."}' \
+  | jq -r .access_token)
+
+curl localhost:8008/_warp/admin/v1/stats -H "Authorization: Bearer $TOKEN"
+```
+
+The token must be in the `Authorization` header. Unlike the C-S API, the
+`?access_token=` form is not accepted here: an admin token in a URL ends up
+in every access log between the browser and the server.
+
+A valid token without the admin flag gets `403 M_FORBIDDEN` rather than a
+404. The caller is a legitimate user of this server who is not allowed here,
+and pretending the endpoint does not exist only makes the panel harder to
+debug.
+
+Make the first admin from the command line:
+
+```sh
+./bin/warp create-account --username root --admin
+```
+
+## Endpoints
+
+### `GET /federation`, `PUT /federation`
+
+The runtime federation switch of PLAN.md section 3.
+
+```json
+{
+  "enabled": false,
+  "toggleable": true,
+  "allowlist": [],
+  "denylist": []
+}
+```
+
+`PUT {"enabled": true}` takes effect on the next request, with no restart,
+and answers with the same document. `toggleable` is `false` when
+`federation.allow_runtime_toggle` pinned the setting in the config file; a
+`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.
+
+### `GET /registration`, `PUT /registration`
+
+The same shape, without the lists, for open registration.
+
+### `GET /users`
+
+```
+GET /users?search=ali&limit=50&offset=0
+```
+
+Ordered by localpart. `search` matches a substring of the localpart or the
+display name, case-insensitively. `total` is the number of users matching
+the query rather than the number returned, so the panel can page.
+
+```json
+{
+  "users": [
+    {
+      "user_id": "@alice:warp.example",
+      "display_name": "Alice",
+      "admin": false,
+      "deactivated": false,
+      "created_at_ms": 1760000000000
+    }
+  ],
+  "total": 1,
+  "limit": 50,
+  "offset": 0
+}
+```
+
+### `POST /users`
+
+```json
+{"username": "alice", "password": "...", "display_name": "Alice", "admin": false}
+```
+
+`201` with the created user. This is how an operator adds an account to a
+server with registration turned off — which is the normal state of a
+private Warp — so it ignores the registration switch deliberately: it is
+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`.
+
+### `GET /stats`
+
+The dashboard payload.
+
+```json
+{
+  "server_name": "warp.example",
+  "version": "0.0.0-dev",
+  "database": "sqlite",
+  "users": 12,
+  "admins": 1,
+  "deactivated": 0,
+  "devices": 19,
+  "federation_enabled": false,
+  "registration_enabled": false
+}
+```
+
+Room and event counters join it in Phase 3, when there is something to
+count.
+
+## Errors
+
+The same envelope as the Client-Server API — `{"errcode": ..., "error":
+...}` — so the panel needs one error path, not two. `409 M_FORBIDDEN` is
+specific to this API: the request was well formed and the server's own
+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. Rooms arrive with the roomserver in Phase 3.

docs/configuration.md

@@ -40,18 +40,49 @@ List-valued variables are comma-separated. A single `-` clears a list:
 | `database.conn_max_lifetime` | `WARP_DB_CONN_MAX_LIFETIME` | `1h` | |
 | `database.auto_migrate` | `WARP_DB_AUTO_MIGRATE` | `true` | `false` makes startup fail while migrations are pending. |
 | `client_api.cors_allowed_origins` | `WARP_CORS_ALLOWED_ORIGINS` | `["*"]` | The spec expects any origin. |
+| `client_api.trust_x_forwarded_for` | `WARP_TRUST_X_FORWARDED_FOR` | `false` | Only behind a proxy that overwrites the header; the rate limiter keys on the result. |
+| `client_api.access_token_lifetime` | `WARP_ACCESS_TOKEN_LIFETIME` | `0s` | `0` = never expire. With a lifetime, clients may ask for a refresh token at login. |
+| `client_api.refresh_token_lifetime` | `WARP_REFRESH_TOKEN_LIFETIME` | `0s` | `0` = never expire. |
+| `client_api.rate_limit.enabled` | `WARP_RATE_LIMIT_ENABLED` | `true` | |
+| `client_api.rate_limit.default.burst` / `.interval` | — | `30` / `100ms` | Every rate-limited endpoint without its own bucket. |
+| `client_api.rate_limit.login.burst` / `.interval` | — | `10` / `1s` | `/login` and `/refresh`. |
+| `client_api.rate_limit.register.burst` / `.interval` | — | `5` / `2s` | `/register` and `/register/available`. |
 | `federation.enabled` | `WARP_FEDERATION_ENABLED` | `false` | |
 | `federation.allowlist` | `WARP_FEDERATION_ALLOWLIST` | `[]` | Non-empty = federate only with these. |
 | `federation.denylist` | `WARP_FEDERATION_DENYLIST` | `[]` | Always wins over the allowlist. |
 | `federation.allow_runtime_toggle` | `WARP_FEDERATION_ALLOW_RUNTIME_TOGGLE` | `true` | See below. |
 | `registration.enabled` | `WARP_REGISTRATION_ENABLED` | `false` | |
 | `registration.allow_runtime_toggle` | `WARP_REGISTRATION_ALLOW_RUNTIME_TOGGLE` | `true` | |
+| `registration.tokens` | `WARP_REGISTRATION_TOKENS` | `[]` | Non-empty = sign-up also needs one of these, as the `m.login.registration_token` stage. |
 | `logging.level` | `WARP_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error`. |
 | `logging.format` | `WARP_LOG_FORMAT` | `text` | `text` or `json`. |
 | `logging.add_source` | `WARP_LOG_ADD_SOURCE` | `false` | File and line in every record. |
 | `metrics.enabled` | `WARP_METRICS_ENABLED` | `true` | |
 | `metrics.path` | `WARP_METRICS_PATH` | `/metrics` | Served on the same listener. |
 
+The three rate limit buckets share one Go type, so per-bucket environment
+variables would all collide on the same name; they are YAML only.
+`WARP_RATE_LIMIT_ENABLED=false` turns the whole limiter off, which is what a
+test harness wants.
+
+## Rate limiting
+
+Each bucket allows `burst` requests back to back and returns one slot every
+`interval`, keyed per client address. Over the limit is
+`429 M_LIMIT_EXCEEDED` with a `retry_after_ms` the client is expected to
+honour.
+
+Buckets are per endpoint class, so a client hammering `/login` cannot spend
+the budget of `/profile`. The key is the client address and not the user,
+because the limiter runs before the access token is resolved — a limiter
+that had to query the database to find its own key would be a denial of
+service of its own. Behind a reverse proxy, set
+`client_api.trust_x_forwarded_for: true`, or every client shares one bucket.
+
+The admin API under `/_warp/admin/v1` is not rate limited: it needs an admin
+token, and bulk operations from the panel are exactly the traffic a limiter
+would get in the way of.
+
 ## Settings that change at runtime
 
 `federation.enabled` and `registration.enabled` are also stored in the

docs/development.md

@@ -101,13 +101,61 @@ says why.
 
 ## Tests
 
-- Unit tests live next to the code. `internal/setup` holds the HTTP-level
-  tests; they build a whole server on an in-memory SQLite database.
+- Unit tests live next to the code. Each API package holds its own
+  HTTP-level tests, built on a throwaway SQLite database with the real
+  components behind them rather than fakes; `internal/setup` holds the
+  smaller set that goes through the whole wrapped handler, to catch a route
+  that was written but never registered.
 - Storage tests run against every driver that is available:
   SQLite always, PostgreSQL when `WARP_TEST_POSTGRES_DSN` is set.
 - CI runs `gofmt -l`, `go mod tidy` (as a diff check), `go vet`, the tests
   on Linux and Windows, the race detector on Linux, `golangci-lint`, and a
   smoke test that boots the real binary and curls it.
 
-Complement, the official integration suite, is wired up in Phase 1 — there
-is nothing it can test before registration exists.
+## Complement
+
+[Complement](https://github.com/matrix-org/complement) is the official Matrix
+integration suite. It runs a container per homeserver per test and drives it
+over the real HTTP API, which makes its pass count the honest measure of how
+far along the server is — PLAN.md section 9 treats it as the primary progress
+metric.
+
+```sh
+make complement                                   # the current target set
+server/test/complement/run.sh TestLogin           # one test
+COMPLEMENT_DEBUG=1 make complement                # with the container logs
+```
+
+It needs Docker. The script builds the image, clones Complement into
+`.complement/` (ignored by git) and runs the subset for the phases that are
+done — currently `TestRegistration`, `TestLogin` and `TestDeviceManagement`,
+with federation off. Extend `COMPLEMENT_TESTS` in
+[run.sh](../server/test/complement/run.sh) as each phase lands, rather than
+switching to the whole suite: a pass count that drops because a later phase
+is missing is noise.
+
+The image is [server/test/complement/Dockerfile](../server/test/complement/Dockerfile)
+and the deployment is entirely `WARP_*` environment variables — see
+[entrypoint.sh](../server/test/complement/entrypoint.sh). Two things there
+are worth knowing: rate limiting is off, because the whole suite comes from
+one address and would otherwise spend its time reading `M_LIMIT_EXCEEDED`;
+and port 8448 is exposed but nothing listens on it yet. The federation
+profile needs a TLS listener signed by the CA that Complement mounts at
+`/complement/ca`, which arrives with federation in Phase 5.
+
+## Creating the first account
+
+A new install has registration off, so the first account is made from the
+command line against the database directly — no server needs to be running:
+
+```sh
+./bin/warp create-account --username you --admin
+```
+
+It prompts for the password twice. `--password-file` reads it from a file and
+`--password` takes it inline, for scripts that have already thought about the
+shell history. From there, the admin API can turn registration on:
+
+```sh
+curl -X PUT http://localhost:8008/_warp/admin/v1/registration   -H "Authorization: Bearer $TOKEN" -d '{"enabled": true}'
+```