GO-Matrix-QR/README.md

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

go mod download
go run ./cmd/server

Or:

make run

Build and test

make build
make test

Docker

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.