Initial commit: stats-gateway gRPC service + dashboard + CLI

2026-05-05 21:04:32 +05:00
commit 4059e94759
44 changed files with 2513 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Auth для Tunnel-метода
+
+Bearer JWT (HS256), HMAC signing secret в `/etc/stats-gateway/jwt.key`.
+
+## Claims
+
+- `sub` — client-id (`bergamot-laptop`, `bergamot-phone`, ...)
+- `scope` — `tunnel` (только этот scope разрешён для Tunnel-метода)
+- `iat`, `exp` — стандартные UNIX timestamps
+- `jti` — random hex для аудита/revocation
+
+## Выпуск нового токена
+
+На gitea-узле от пользователя с доступом к `jwt.key`:
+
+    sudo -u stats /usr/local/bin/stats-issue-token --sub <client-id> --days <N>
+
+(Helper-скрипт `issue-token.sh` устанавливается на сервер в Task 11 как Go-binary `stats-issue-token`.)
+
+Локальный путь во время разработки — `experiments/grpc-tunnel/issue-token.sh`. Семантика идентична Go-варианту.
+
+## Revocation
+
+Опции (по убыванию агрессивности):
+
+1. **Polite revocation** (один client) — добавить `jti` отзываемого токена в `/etc/stats-gateway/revoked.txt`
+   (формат: один jti на строку, `#` в начале строки — комментарий). Сервис подгружает на каждом запросе.
+2. **Mass revocation** (все клиенты) — `openssl rand -hex 32 > /etc/stats-gateway/jwt.key`,
+   `systemctl restart stats-gateway`. Затем переиздать токены живым клиентам и раздать оффлайн.
+
+Polite revocation реализуется в Task 11 (через `LoadRevokedFile`). Для старта — только rotation.
+
+## Ротация secret
+
+Раз в год минимум. Перед сменой:
+1. Выпустить новые токены клиентам с новым ключом (НЕ deploy ещё на сервер)
+2. Раздать токены оффлайн (мессенджер, не plain SMS)
+3. Заменить ключ на сервере, restart
+4. Старые токены немедленно невалидны
+
+## Storage клиентского токена
+
+На клиенте — `~/.psp/token` mode 600. CLI читает только этот файл (см. `psp-stats-cli connect --token-file`).
+Не коммитить токены в репозитории, не передавать через email/Slack без e2e.