stem-launcher/doc/tokens.md

Tokens

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:

{
  "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

Komendy

tokens scan

Kierunek:

repo -> tokens.json

Dzialanie:

• skanuje remote URL-e w repo
• zapisuje znalezione tokeny do tokens.json
• zapisuje je per endpoint serwera
• wypisuje wynik jako waskie tabele TSV: context, scan oraz items

Tabela items porownuje dwa zrodla dla tego samego endpointu. Ten sam item moze miec dwa wiersze:

• source=repo - stan remote URL-i w repo
• source=tokens.json - stan lokalnego store tokenow

Kolumny w tabeli items:

• item - numer porownywanego endpointu
• source - repo albo tokens.json
• endpoint - serwer bez sekretu, na przyklad http://77.90.8.171:3001
• remote - nazwa remote, na przyklad r1; tylko dla source=repo
• kind - auth, plain, store albo missing
• user - login odczytany z URL albo ze store
• token - remote dla tokenu w URL albo nazwa tokenu ze store, na przyklad t1
• result - added, existing, present, no_credentials albo missing
• status - relacja repo do tokens.json, na przyklad in_sync albo store_ahead

Przyklad:

./rvctl tokens scan
./rvctl 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:

./rvctl tokens read
./rvctl tokens read --server http://77.90.8.171:3001
./rvctl tokens read --show-secrets

tokens stats

Pokazuje statystyki per endpoint serwera i porownuje dwa zrodla:

• endpointy znalezione w remote URL-ach repo
• endpointy zapisane w tokens.json

Wynik ma ten sam model porownania co tokens scan, ale nie zapisuje zmian:

• liczbe endpointow w repo
• liczbe endpointow w store
• laczna unie endpointow
• statusy zgodnosci, na przyklad in_sync, store_ahead, repo_ahead
• tabele items, w ktorej repo i tokens.json sa osobnymi wierszami tego samego itemu

Przyklad:

./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03

tokens write

Kierunek:

tokens.json -> repo

Dzialanie:

• bierze token z tokens.json
• wybiera endpoint, usera i token
• wpisuje dane auth do wybranego remota repo

Przyklad:

./rvctl 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:

./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
./rvctl 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