commit 60669d60ec45234aa4c36c9a5aa958907f0c6c89
Author: admin <admin@evilfox.cc>
Date:   Tue Apr 28 15:17:10 2026 +0000

    Загрузить файлы в «/»

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4c162d2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+# 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.