68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
# 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.
|