# Matrix QR login helper service

Small Go service that mints Matrix `m.login.token` login tokens using an existing access token, renders Element-style `matrix:` QR codes, and exchanges tokens for new sessions. It targets homeservers that implement `POST /_matrix/client/v1/login/get_token` (Matrix spec v1.7+, formerly MSC3882).

## Configuration (environment)

| Variable | Default | Description |
| --- | --- | --- |
| `MATRIX_HOMESERVER` | `https://jb.evilfox.cc` | Homeserver base URL (no trailing slash required). |
| `SERVER_PORT` | `8080` | HTTP listen port. |
| `TOKEN_USES` | `1` | Default `uses` hint for your own API (Matrix may ignore it). |
| `TOKEN_EXPIRY_SECONDS` | `300` | Default `expiry` hint for your own API (Matrix may ignore it). |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` (structured JSON logs via `log/slog`). |
| `MATRIX_USE_UNSTABLE_MSC3882` | `false` | If `true`, call `POST /_matrix/client/unstable/org.matrix.msc3882/login/token` instead of the stable v1 route. |

## HTTP API

- `GET /health` — JSON `{"status":"ok"}`.
- `POST /generate-token` — Provide `Authorization: Bearer <user_access_token>` and/or JSON `{"access_token":"...","uses":1,"expiry":300}`. Returns `multipart/mixed`: first part `application/json` (`{"token":"..."}`), second part `image/png` QR.
- `POST /login` — JSON `{"token":"<login_token>","device_name":"optional"}`. Returns Matrix `LoginResponse` JSON on success.
- `GET /qr/<token>` — Renders the same QR as PNG (`image/png`). URL-encode the token in the path when it contains reserved characters.

QR payload format:

`matrix:?action=login&token=<token>&server=<MATRIX_HOMESERVER>`

Logs intentionally avoid printing login tokens or access tokens.

## Run locally

```bash
go mod download
go run ./cmd/server
```

Or:

```bash
make run
```

## Build and test

```bash
make build
make test
```

## Docker

```bash
make docker-build
docker compose up
```

## Security notes

This repository focuses on wiring, HTTP clients, QR rendering, and operational concerns. **Authorization, abuse prevention, token storage, and homeserver UIA handling are intentionally left as TODOs in code** for you to implement against your threat model.

Synapse often requires interactive authentication (UIA) for `login/get_token`; if the homeserver responds with `401` and a UIA payload, this service surfaces that as an error until you add a full UIA client flow.

## Layout

- `cmd/server` — process entrypoint and graceful shutdown.
- `internal/` — HTTP server, configuration, QR helpers, deeplink builder.
- `pkg/matrixclient` — Matrix Client-Server HTTP client (`GenerateToken`, `LoginWithToken`, `RevokeToken` stub).
- `pkg/models` — Shared JSON models.