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 pokazac stan przez tokens scan albo jawnie zapisac token do tokens.json przez tokens update --from remotes.

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",
            "t2": {
              "value": "SECRET",
              "remote": "r1",
              "org": "edu-tools",
              "repo": "rv-launcher",
              "expires_at": "2026-05-01T12:00:00"
            }
          }
        }
      }
    }
  }
}

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
• nazwe remota, ktora jest identyfikatorem parowania z repo
• opcjonalne org i repo zapamietane z remote URL-a
• opcjonalna date wygasniecia expires_at dla tokena

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 i nazwie remota
• wybiera tylko http i https
• jesli URL ma LOGIN:TOKEN@..., wyciaga login i token
• niczego nie zapisuje do tokens.json

Endpoint jest liczony z:

• scheme
• host
• port

Przy tokens update --from remotes 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 i nazwie remota
• wypisuje tabele tokens

Tabela tokens pokazuje jeden logiczny wiersz na remote tokena. Remote i tokens.json sa laczone po endpoincie serwera oraz kolumnie remote.

Znacznik w token_ref:

• * - token jest w remote i tokens.json, remote/user/token sa zgodne, 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
• proto - protokol endpointu, na przyklad http
• host - host endpointu razem z portem, na przyklad 77.90.8.171:3001
• 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
• valid - forever, lokalne expires_at, invalid, ? albo !
• 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.

valid jest liczone tak:

• forever - API akceptuje token i nie ma lokalnego expires_at
• 2026-05-01T12:00:00 - API akceptuje token i taka data jest zapisana w tokens.json
• invalid - API odrzuca token albo lokalne expires_at jest w przeszlosci
• ? - token nie jest sparowany jako *, wiec nie sprawdzamy uprawnien
• ! - blad sprawdzania API

tokens scan jest read-only. Jezeli token jest tylko w remote, tabela pokaze R i maski ?????/????. Dopiero jawne tokens update --from remotes zapisuje token oraz metadane remote, org i repo do tokens.json.

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
• remote/org/repo przy tokenie, jezeli sa zapisane

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

tokens update --from remotes kopiuje tokeny z remote URL-i repo do tokens.json. tokens update --from store kopiuje wybrany token z tokens.json do remote URL-a repo.

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 update --from remotes
• 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 update --from remotes do jawnego zapisania tokenow z remote'ow w tokens.json
• 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