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>

server/test/complement/Dockerfile

@@ -0,0 +1,60 @@
+# Warp as a Complement homeserver image.
+#
+# Complement (https://github.com/matrix-org/complement) is the official
+# Matrix integration suite: it runs one container per homeserver per test and
+# drives it over the real HTTP API. Its image contract is short, and this
+# file exists to meet it:
+#
+#   - EXPOSE 8008 (client) and 8448 (federation).
+#   - Take the server name from the SERVER_NAME environment variable.
+#   - Keep storage inside the container.
+#   - Survive the entrypoint being run more than once.
+#   - Answer GET /_matrix/client/versions with a 200.
+#
+# Build it from the repository root, because the build context is the Go
+# module one directory up:
+#
+#   docker build -t complement-warp -f server/test/complement/Dockerfile .
+#
+# Federation (port 8448, served over TLS with a certificate signed by the CA
+# Complement mounts at /complement/ca) arrives in Phase 5. Until then this
+# image is for the federation=off profile: the C-S tests. The port is still
+# exposed, because Complement expects it to be.
+
+FROM golang:1.26-alpine AS build
+
+# The workspace file is not copied, so the build must not look for one.
+ENV GOWORK=off
+ENV CGO_ENABLED=0
+
+WORKDIR /src
+
+# Dependencies first, so that editing Go sources does not re-download them.
+COPY server/go.mod server/go.sum ./
+RUN go mod download
+
+COPY server/ ./
+RUN go build -trimpath -o /out/warp ./cmd/warp
+
+FROM alpine:3.21
+
+# curl is what the health check uses; ca-certificates is for the outbound
+# federation requests of Phase 5.
+RUN apk add --no-cache ca-certificates curl
+
+COPY --from=build /out/warp /usr/local/bin/warp
+COPY server/test/complement/entrypoint.sh /usr/local/bin/warp-complement
+RUN chmod +x /usr/local/bin/warp-complement
+
+# Everything mutable lives here: the SQLite database and the signing key.
+VOLUME /data
+
+EXPOSE 8008 8448
+
+# Complement waits for the container to become healthy before it starts a
+# test, so the interval is short and the retries generous: a cold start has
+# to run the migrations first.
+HEALTHCHECK --interval=1s --timeout=2s --start-period=1s --retries=60 \
+	CMD curl -fsS http://localhost:8008/healthz || exit 1
+
+ENTRYPOINT ["/usr/local/bin/warp-complement"]

server/test/complement/README.md

@@ -1,13 +1,67 @@
 # Complement
 
 [Complement](https://github.com/matrix-org/complement) is the official
-Matrix integration suite and the project's primary progress metric.
+Matrix integration suite and this project's primary progress metric
+(PLAN.md section 9). It runs one container per homeserver per test and
+drives it over the real HTTP API.
 
-It is wired up in Phase 1, once registration and login exist — before that
-there is nothing for it to test. Two profiles are planned, per PLAN.md
-section 9: `federation=off` (Client-Server tests only) and
-`federation=on`.
+```sh
+make complement                          # the current target set
+bash run.sh TestLogin                    # one test
+COMPLEMENT_DEBUG=1 make complement       # with the container logs
+```
 
-What will live here: the Dockerfile Complement boots, the image entrypoint
-that generates a signing key and a config per test homeserver, and the
-list of tests expected to pass.
+Needs Docker. [run.sh](run.sh) builds the image, clones Complement into
+`.complement/` at the repository root (git-ignored) and runs the subset for
+the phases that are done.
+
+## Files
+
+| | |
+|---|---|
+| [Dockerfile](Dockerfile) | the homeserver image, built from the repository root |
+| [entrypoint.sh](entrypoint.sh) | the deployment, entirely `WARP_*` environment variables |
+| [run.sh](run.sh) | build, clone, run |
+
+## Profiles
+
+**`federation=off`** — what runs today. Only the Client-Server tests;
+`WARP_FEDERATION_ENABLED=false`, port 8448 exposed but unserved.
+
+**`federation=on`** — Phase 5. It needs a TLS listener on 8448 with a
+certificate signed by the CA that Complement mounts at `/complement/ca`,
+which is the first thing to add here when federation lands.
+
+## The test set
+
+`COMPLEMENT_TESTS` in `run.sh` lists what is expected to pass. Phase 1:
+
+- `TestRegistration`
+- `TestLogin`
+- `TestDeviceManagement`
+
+Extend it as each phase lands rather than switching to the whole suite: a
+pass count that drops because a later phase is missing is noise, not
+information.
+
+Two notes on the environment, both in `entrypoint.sh`:
+
+- **Rate limiting is off.** The whole suite comes from the one address the
+  test runner has, so the limiter would spend the run returning
+  `M_LIMIT_EXCEEDED` and tell us nothing about the server. Synapse's own
+  Complement image does the same.
+- **Registration is on**, because the tests create their own users.
+
+## Tests that need later phases
+
+Some subtests of the three above reach for endpoints that are not Phase 1
+work. `TestDeviceManagement` calls `/sync` after creating a session, and
+`TestLogout` checks that a revoked token cannot sync. Phase 1 answers
+`/sync` with an empty but well-formed response for exactly that reason —
+there are no rooms yet, so an empty sync is the complete truth, and it makes
+token revocation observable. Phase 4 replaces it with the real syncapi.
+
+The shared-secret registration subtests of `TestRegistration` probe
+`/_synapse/admin/v1/register` and skip themselves when it 404s, which it
+does here: that endpoint is Synapse's, and `warp create-account` covers the
+same need.

server/test/complement/entrypoint.sh

@@ -0,0 +1,50 @@
+#!/bin/sh
+# Start Warp the way Complement needs it.
+#
+# There is no configuration file: every setting Warp has can come from a
+# WARP_* environment variable, so the whole deployment is the few lines
+# below. Complement may run this entrypoint more than once against the same
+# container, so everything here is idempotent.
+set -eu
+
+DATA_DIR="${WARP_DATA_DIR:-/data}"
+mkdir -p "$DATA_DIR"
+
+# Complement names the homeservers hs1, hs2, ... and passes the name in.
+export WARP_SERVER_NAME="${SERVER_NAME:-hs1}"
+
+export WARP_PRIVATE_KEY="$DATA_DIR/signing.key"
+export WARP_DB_DRIVER=sqlite
+export WARP_DB_CONNECTION_STRING="file:$DATA_DIR/warp.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(10000)&_pragma=foreign_keys(1)"
+export WARP_DB_AUTO_MIGRATE=true
+
+export WARP_LISTEN_ADDRESS=":8008"
+
+# The suite registers and logs in constantly, all from the one address the
+# test runner has. Rate limiting would turn that into a wall of
+# M_LIMIT_EXCEEDED and tell us nothing about the server. Synapse's own
+# Complement image does the same.
+export WARP_RATE_LIMIT_ENABLED=false
+
+# Open registration: the tests create their own users.
+export WARP_REGISTRATION_ENABLED=true
+
+# Federation stays off unless the profile asks for it. Phase 5 adds the
+# TLS listener on 8448 that the federation profile needs; until then this
+# image only serves the Client-Server API.
+export WARP_FEDERATION_ENABLED="${WARP_FEDERATION_ENABLED:-false}"
+
+# Complement captures the container's output, so text at debug level is the
+# most useful thing to have when a test fails.
+export WARP_LOG_LEVEL="${WARP_LOG_LEVEL:-debug}"
+export WARP_LOG_FORMAT="${WARP_LOG_FORMAT:-text}"
+
+if [ ! -f "$WARP_PRIVATE_KEY" ]; then
+	warp generate-keys --output "$WARP_PRIVATE_KEY"
+fi
+
+# Migrations also run on boot, but doing them here keeps a schema failure
+# out of the request path and makes it obvious in the container log.
+warp migrate
+
+exec warp serve

server/test/complement/run.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Run Complement against a freshly built Warp image.
+#
+#   server/test/complement/run.sh                 # the Phase 1 test set
+#   server/test/complement/run.sh TestLogin       # one test
+#   COMPLEMENT_TESTS='Test.*' server/test/complement/run.sh
+#
+# Complement is a separate Go module, so it has to be checked out and run on
+# its own. This script keeps that checkout in a cache directory rather than
+# vendoring it: it is a test harness we track, not a dependency we pin.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+
+: "${COMPLEMENT_REPO:=https://github.com/matrix-org/complement.git}"
+: "${COMPLEMENT_REF:=main}"
+: "${COMPLEMENT_DIR:=${REPO_ROOT}/.complement}"
+: "${COMPLEMENT_IMAGE:=complement-warp}"
+
+# The Phase 1 target set, from PLAN.md section 7. Add to it as phases land
+# rather than switching to the whole suite: a pass count that goes down
+# because a later phase is missing is noise.
+: "${COMPLEMENT_TESTS:=TestRegistration|TestLogin|TestDeviceManagement}"
+
+if [[ $# -gt 0 ]]; then
+	COMPLEMENT_TESTS="$(IFS='|'; echo "$*")"
+fi
+
+docker="${DOCKER:-docker}"
+if ! command -v "$docker" >/dev/null 2>&1; then
+	echo "complement: $docker is not installed; Complement needs a container runtime" >&2
+	exit 1
+fi
+
+echo "complement: building $COMPLEMENT_IMAGE"
+"$docker" build -t "$COMPLEMENT_IMAGE" -f "${REPO_ROOT}/server/test/complement/Dockerfile" "$REPO_ROOT"
+
+if [[ ! -d "$COMPLEMENT_DIR" ]]; then
+	echo "complement: cloning $COMPLEMENT_REPO into $COMPLEMENT_DIR"
+	git clone --depth 1 --branch "$COMPLEMENT_REF" "$COMPLEMENT_REPO" "$COMPLEMENT_DIR"
+else
+	git -C "$COMPLEMENT_DIR" fetch --depth 1 origin "$COMPLEMENT_REF"
+	git -C "$COMPLEMENT_DIR" checkout -q FETCH_HEAD
+fi
+
+echo "complement: running '${COMPLEMENT_TESTS}' with federation off"
+cd "$COMPLEMENT_DIR"
+
+# COMPLEMENT_SPAWN_HS_TIMEOUT_SECS is generous because the first container
+# of a run has to apply the migrations on a cold SQLite file.
+COMPLEMENT_BASE_IMAGE="$COMPLEMENT_IMAGE" \
+	COMPLEMENT_SPAWN_HS_TIMEOUT_SECS="${COMPLEMENT_SPAWN_HS_TIMEOUT_SECS:-60}" \
+	COMPLEMENT_DEBUG="${COMPLEMENT_DEBUG:-0}" \
+	go test -count=1 -v -timeout 20m -run "^(${COMPLEMENT_TESTS})$" ./tests/csapi/...