# 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 3 — rooms, local only. Complete.** A client can create a room at any
supported version, invite, join, leave, kick, ban, send messages and state,
redact, name a room with an alias and find one in the public directory. Every
event goes through one pipeline — validate, authorise, resolve, persist,
emit — so a membership change made by `createRoom`, by `/invite` or by a raw
`PUT .../state/m.room.member` is judged by the same authorisation rules.
Nothing talks to another server yet, and every operation that would need to
is refused with a message that says so. There is no `/messages` or real
`/sync`, so a room's history cannot be paged: that is Phase 4. See
[docs/rooms.md](docs/rooms.md).

**Phase 2 — the event core. Complete.** The library every later phase is
built on: canonical JSON, the event model with its hashes and identifiers,
the redaction algorithm, event signing, the room version registry, the
authorisation rules and state resolution v2. Pure library code under
`server/internal/matrix`, verified against the spec's own test vectors.
See [docs/event-core.md](docs/event-core.md).

**Phase 1 — accounts and sessions. Complete.** A client can register, log
in, manage its devices and set its profile.

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 |
| `POST /createRoom` | room versions 3 to 12, presets, `initial_state`, invites, aliases |
| `POST /join/{roomIdOrAlias}` · `POST /rooms/{id}/join`, `/leave` | joining by ID or alias, and leaving or rejecting an invite |
| `POST /rooms/{id}/invite`, `/kick`, `/ban`, `/unban` | membership, decided by the room's power levels |
| `PUT /rooms/{id}/send/{type}/{txn}` | messages, idempotent per transaction ID |
| `GET`/`PUT /rooms/{id}/state[/{type}[/{key}]]` | room state, read whole or one piece at a time |
| `PUT /rooms/{id}/redact/{event}/{txn}` | redactions, applied only when they take effect |
| `GET /rooms/{id}/event/{event}` · `/members` · `/joined_members` · `/aliases` | reading a room |
| `GET /joined_rooms` | the rooms you are in |
| `GET`/`PUT`/`DELETE /directory/room/{alias}` | the alias directory |
| `GET`/`POST /publicRooms` · `GET`/`PUT /directory/list/room/{id}` | the public room directory |
| `GET /sync` | still a placeholder: a well-formed, empty response, because there is no event stream until Phase 4 |
| `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, the room list and detail, purging a
room, removing a user from one, 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`, `TestDeviceManagement` and the Phase 3 room tests.

## 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
    roomserver/         rooms: the input pipeline (docs/rooms.md)
    clientapi/          the Client-Server API handlers
    adminapi/           /_warp/admin/v1
    setup/              wiring: storage, routes, graceful shutdown
    matrix/             the event core (docs/event-core.md)
      canonicaljson/    the canonical JSON encoding
      signing/          ed25519 server keys, Signing JSON
      id/               identifier grammars as they appear in events
      roomversion/      the room version registry
      event/            PDUs: hashes, event IDs, redaction, signing
      auth/             the authorisation rules and power levels
      stateres/         state resolution v2
    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/
```