Add endpoint-aware token management commands

2026-04-26 10:26:00 +02:00
parent a0930de5e1
commit f76334e5c2
4 changed files with 930 additions and 34 deletions
@@ -0,0 +1,231 @@
+# Tokens
+
+## Authors
+
+Mateusz Pabiszczak, 2026
+
+## Status
+
+Draft
+
+Plik opisuje aktualny model pracy z tokenami w launcherze.
+
+## Zrodlo prawdy
+
+Sa dwa miejsca, w ktorych moga byc zapisane tokeny:
+
+- remote URL-e w repo, na przyklad `http://LOGIN:TOKEN@host/org/repo.git`
+- lokalny plik `~/dev/workspace/rv/tokens/tokens.json`
+
+Jesli remote URL zawiera `LOGIN:TOKEN@...`, to remote jest zrodlem prawdy.
+Launcher moze wtedy zeskanowac repo i zapisac ten token do `tokens.json`.
+
+Jesli remote nie ma tokena, `tokens.json` moze byc uzyty jako lokalny store
+przy operacjach `tokens write` i `tokens update --from store`.
+
+## Format `tokens.json`
+
+Tokeny sa trzymane per endpoint serwera, a dopiero pod nim per user i token:
+
+```json
+{
+  "version": 2,
+  "servers": {
+    "http://77.90.8.171:3001": {
+      "type": "gitea",
+      "scheme": "http",
+      "host": "77.90.8.171",
+      "port": 3001,
+      "users": {
+        "u1": {
+          "tokens": {
+            "t1": "SECRET"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+To pozwala odroznic:
+
+- typ serwera, na przyklad `gitea`, `github`, `gitlab`, `unknown`
+- endpoint, czyli `scheme + host + port`
+- uzytkownikow na danym serwerze
+- wiele tokenow dla jednego usera
+
+## Skanowanie remota
+
+Przy `tokens scan` launcher:
+
+- czyta wszystkie remote URL-e w repo
+- wybiera tylko `http` i `https`
+- jesli URL ma `LOGIN:TOKEN@...`, wyciaga login i token
+- zapisuje je pod odpowiednim endpointem w `tokens.json`
+
+Endpoint jest liczony z:
+
+- scheme
+- host
+- port
+
+Przy skanowaniu launcher zapisuje tez metadane serwera:
+
+- `type`
+- `scheme`
+- `host`
+- `port`
+
+## Migracja starego pliku
+
+Jesli istnieje stary plik:
+
+```text
+~/dev/workspace/rv/tokens/gitea_tokens.json
+```
+
+launcher przemigruje go do:
+
+```text
+~/dev/workspace/rv/tokens/tokens.json
+```
+
+Jesli plik ma jeszcze stary format `users -> tokens`, launcher zamieni go na
+nowy format `servers -> users -> tokens`.
+
+## Komendy
+
+### `tokens scan`
+
+Kierunek:
+
+```text
+repo -> tokens.json
+```
+
+Dzialanie:
+
+- skanuje remote URL-e w repo
+- zapisuje znalezione tokeny do `tokens.json`
+- zapisuje je per endpoint serwera
+
+Przyklad:
+
+```bash
+python3 workspace.py tokens scan
+python3 workspace.py tokens scan --repo ~/dev/workspace/rv/series/inf/03
+```
+
+### `tokens read`
+
+Pokazuje szczegolowa zawartosc `tokens.json`.
+
+Wynik zawiera:
+
+- endpoint
+- type
+- scheme
+- host
+- port
+- users
+- tokens
+
+Oraz liste userow i nazw tokenow dla kazdego endpointu.
+
+Przyklad:
+
+```bash
+python3 workspace.py tokens read
+python3 workspace.py tokens read --server http://77.90.8.171:3001
+python3 workspace.py tokens read --show-secrets
+```
+
+### `tokens stats`
+
+Pokazuje statystyki per endpoint serwera.
+
+Wynik ma ten sam model co `tokens read`, ale w formie zbiorczej:
+
+- endpoint
+- type
+- scheme
+- host
+- port
+- users
+- tokens
+
+Przyklad:
+
+```bash
+python3 workspace.py tokens stats
+```
+
+### `tokens write`
+
+Kierunek:
+
+```text
+tokens.json -> repo
+```
+
+Dzialanie:
+
+- bierze token z `tokens.json`
+- wybiera endpoint, usera i token
+- wpisuje dane auth do wybranego remota repo
+
+Przyklad:
+
+```bash
+python3 workspace.py tokens write \
+  --repo ~/dev/workspace/rv/series/inf/03 \
+  --remote r1 \
+  --server http://77.90.8.171:3001 \
+  --user u1 \
+  --token-name t1
+```
+
+### `tokens update`
+
+Uruchamia synchronizacje w zadanym kierunku.
+
+Dozwolone kierunki:
+
+- `tokens update --from remotes`
+- `tokens update --from store`
+
+Przyklad:
+
+```bash
+python3 workspace.py tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
+python3 workspace.py tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
+```
+
+## Konflikty
+
+Domyslnie launcher nie zgaduje przy konflikcie.
+
+Jesli:
+
+- token jest w repo, ale nie ma go w `tokens.json`
+  uzyj `tokens scan`
+- token jest w `tokens.json`, ale nie ma go w repo
+  uzyj `tokens write`
+- token jest i tu, i tu, ale wartosci sa rozne
+  wybierz kierunek jawnie przez `tokens update --from ...`
+
+Przy `tokens write` i `tokens update --from store` mozna uzyc:
+
+- `--replace`
+- `--dry-run`
+
+## Rekomendacja
+
+Najbezpieczniejszy model pracy:
+
+- `tokens scan` do zczytywania danych z remote'ow
+- `tokens read` do podgladu store
+- `tokens stats` do zbiorczego przegladu per endpoint
+- `tokens write` do jawnego wpisania auth do remota
+- `tokens update --from ...` tylko z jawnym kierunkiem