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 tabele tokens

Tabela tokens pokazuje jeden logiczny wiersz na token. Remote i tokens.json sa laczone po endpoincie, userze i wartosci tokena.

Znacznik w token_ref:

• * - token jest w remote i tokens.json, uprawnienia zostaly wczytane
• R - token jest tylko w remote
• S - token jest tylko w tokens.json
• ! - blad wczytania uprawnien dla sparowanego tokena

Kolumny w tabeli tokens:

• item - numer wiersza tokena
• server - typ serwera, na przyklad gitea
• host - host endpointu, na przyklad 77.90.8.171
• org - organizacja z remote URL
• repo - repo z remote URL
• user - login wlasciciela tokena
• remote - nazwa remota, na przyklad r1
• token_ref - nazwa tokena z markerem po prawej stronie
• token - zamaskowana wartosc tokena
• scope - maska scope tokena awrop
• org - maska praw w organizacji oawrc
• repo - maska praw w repo oawr

Maski uprawnien:

• + - flaga wlaczona
• - - flaga wylaczona
• ? - nie wczytano, na przyklad dla R albo S
• ! - blad wczytania

Tabela nie wypisuje sekretu tokena wprost. Kolumna token pokazuje skrot, na przyklad e59cc...13be.

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 tokens

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