Warp/README.md

# Warp

A [Matrix](https://spec.matrix.org) homeserver written from scratch in Go,
plus a family of first-party clients. Federation is optional and can be
switched on and off at runtime.

The full design and roadmap live in [PLAN.md](PLAN.md). This README covers
what exists today.

## Status

**Phase 1 — accounts and sessions. Complete.** A client can register, log
in, manage its devices and set its profile. There are no rooms and no real
`/sync` yet: those are Phases 3 and 4.

Client-Server API:

| | |
|---|---|
| `POST /register`, `GET /register/available` | sign-up, with `m.login.dummy` and optional registration tokens |
| `GET`, `POST /login` · `POST /logout`, `/logout/all` · `POST /refresh` | sessions, with `m.login.password` and refresh tokens |
| `GET /account/whoami` · `GET /capabilities` | who am I, and what this build can do |
| `GET /devices`, `GET`/`PUT`/`DELETE /devices/{id}` · `POST /delete_devices` | device management; deletion re-asks for the password |
| `GET /profile/{user}` and its `displayname` / `avatar_url` sub-resources | profiles — reads are public, writes are your own |
| `GET`/`PUT /user/{user}/account_data/{type}` and the per-room variant | account data, stored and returned byte for byte |
| `GET /sync` | a placeholder: an empty, well-formed response, because there is nothing to sync yet |
| `GET /_matrix/client/versions` · `/.well-known/matrix/client` | discovery |
| `/.well-known/matrix/server` | server discovery — **only while federation is on** |
| `GET /healthz` · `GET /metrics` | liveness with a database ping, and Prometheus |
| anything else under `/_matrix/` | `404 M_UNRECOGNIZED`, as the spec requires |

Admin API under `/_warp/admin/v1`: the federation and registration
switches, user listing and creation, and the dashboard counters. See
[docs/admin-api.md](docs/admin-api.md).

Also in place: argon2id passwords, hashed access and refresh tokens,
per-endpoint rate limiting, YAML + environment configuration, structured
logging, graceful shutdown, the storage interfaces with a working SQLite and
PostgreSQL driver (and a PocketBase stub), the embedded migration runner and
the runtime settings service.

Complement, the official integration suite, is wired up for the
federation-off profile: `make complement` runs `TestRegistration`,
`TestLogin` and `TestDeviceManagement`.

## Quick start

Requires Go 1.26 or newer. No cgo, no C compiler, no database server: the
default SQLite driver is pure Go.

```sh
cp warp.yaml.example warp.yaml
# edit global.server_name

make build
./bin/warp generate-keys
./bin/warp create-account --username you --admin
./bin/warp serve
```

Then:

```sh
curl localhost:8008/healthz
curl localhost:8008/_matrix/client/versions
```

Registration is off in a fresh install, which is why the first account is
made from the command line. Turn it on from the admin API when you want
others to sign up.

Without `make`, the same from the `server` directory:

```sh
go build -o ../bin/warp ./cmd/warp
```

## Configuration

One YAML file, every field overridable from the environment. See
[warp.yaml.example](warp.yaml.example) — each setting lists its `WARP_*`
variable. With no config file at all the server runs on defaults plus the
environment, which is how the container image is meant to be used:

```sh
docker build -t warp .
docker run -p 8008:8008 -v warp-data:/data -e WARP_SERVER_NAME=warp.example warp
```

An unknown field in the config file is an error, not a warning: a typo in a
security-relevant setting should never be silently ignored.

## Commands

| Command | What it does |
|---|---|
| `warp serve` | run the homeserver |
| `warp migrate [--status]` | apply (or list) pending database migrations |
| `warp generate-keys [--output path] [--key-id id]` | create the ed25519 signing key |
| `warp create-account --username name [--admin]` | create a local account, straight in the database |
| `warp version` | version and compiled-in storage drivers |

`create-account` talks to the database rather than to a running server, so
the first account on a new install can be made before anything is listening
and without turning registration on. It prompts for the password twice;
`--password-file` and `--password` are there for scripts.

The signing key is written as a single line, the same format Synapse uses:
`ed25519 <key-id> <unpadded-base64-seed>`. `generate-keys` refuses to
overwrite an existing key — losing it would invalidate every event this
server has ever signed.

## Federation switch

Federation is off in a fresh install. While it is off, the federation
surface does not answer at all; `/.well-known/matrix/server` returns
`404 M_UNRECOGNIZED`, exactly as it would on a server that has no
federation API.

The switch is stored in the `server_settings` table and cached in memory,
so flipping it takes effect on the next request without a restart. In
Phase 0 the only thing behind the gate is the delegation document; the
outbound queue, key fetcher and remote media fetch join it in Phase 5. Set
`federation.allow_runtime_toggle: false` to pin the switch to the config
file.

## Development

```sh
make test          # unit tests (SQLite)
make lint          # golangci-lint
make check         # vet + test, what CI runs
make cover         # coverage.html
make complement    # the Complement subset for the phases that are done (needs Docker)

# the storage tests against PostgreSQL as well
WARP_TEST_POSTGRES_DSN='postgres://warp:warp@localhost/warp_test?sslmode=disable' make test-postgres
```

`make test-race` needs cgo and therefore a C toolchain; CI runs it on
Linux.

## Layout

```
server/                 the homeserver (Go module)
  cmd/warp/             the binary: serve, migrate, generate-keys, create-account, version
  internal/
    config/             YAML + env configuration
    logging/  metrics/  slog and Prometheus setup
    httputil/           Matrix error envelope, CORS, router, middleware
    ratelimit/          per-endpoint token buckets
    federation/         the federation gate and allow/deny policy
    settings/           runtime settings service (the switches)
    userapi/            accounts, passwords, devices, tokens, account data
    clientapi/          the Client-Server API handlers
    adminapi/           /_warp/admin/v1
    setup/              wiring: storage, routes, graceful shutdown
    matrix/signing/     ed25519 server keys
    storage/            interfaces + driver registry
      migrations/       embedded migration runner
      sqlstore/         shared database/sql implementation
      sqlite/ postgres/ pocketbase/
  test/complement/      the Complement homeserver image and runner
apps/                   clients: ui, admin, web, desktop, mobile (Phase 1+)
docs/
```