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
• czyta tokens.json
• laczy remote i store w pary po endpoincie serwera
• 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

Zrodla:

repo + tokens.json

Dzialanie:

• skanuje remote URL-e w repo
• czyta wpisy z tokens.json
• laczy oba zrodla po endpoincie serwera
• zapisuje znalezione tokeny do tokens.json
• zapisuje je per endpoint serwera
• wypisuje domyslnie tylko waska tabele items
• z --verbose dopisuje diagnostyczne sekcje context oraz scan

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

Dzieki temu widac, dla ktorego endpointu token jest w remote, a dla ktorego jest tylko w tokens.json.

Kolumny w tabeli items:

• item - numer porownywanego endpointu
• source - repo albo tokens.json
• id - identyfikator miejsca tokena: remote r1 dla repo albo token t1 dla tokens.json
• server - typ serwera, na przyklad gitea
• scheme - schemat URL, na przyklad http
• host - host endpointu, na przyklad 77.90.8.171
• port - port endpointu, na przyklad 3001
• credential - typ wpisu: auth, plain, store albo missing
• repo_user - login odczytany z remote URL-i repo
• store_user - login odczytany z tokens.json
• token - yes albo no, czyli czy dane zrodlo ma token dla endpointu
• sync - * przy zrodle prawdy albo ! przy konflikcie

Tabela nie wypisuje sekretu tokena. Jezeli token jest w remote, id pokazuje nazwe remota, na przyklad r1. Jezeli token jest w tokens.json, id pokazuje nazwe tokenu, na przyklad t1.

Zasada znacznika sync:

• in_sync, store_only, store_ahead - * przy tokens.json
• repo_only, repo_ahead - * przy repo
• diverged - !, bo nie ma jednoznacznego zrodla prawdy

Przyklad:

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

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