stem-launcher/doc/tokens.md

Tokens

Ten dokument opisuje model tokenow uzywany przez rvctl.

Zasada

tokens.json synchronizujemy z repo rv-launcher. Remoty kart pracy i repo odpowiedzi sa generowane jako pochodne konfiguracji launchera, a nie jako osobne zrodla prawdy dla tokenow.

W praktyce oznacza to:

• r1 w repo rv-launcher jest miejscem startowym do pobrania tokena z remote
• tokens.json jest lokalnym store sekretow i metadanych tokenow
• karty pracy dostaja remote na podstawie ustawien launchera i komend typu submission
• tokens scan i tokens compare sa read-only i niczego nie zapisuja

Zrodlo Prawdy

Sa dwa miejsca, ktore rvctl potrafi porownac:

• git remote w repo rv-launcher, np. http://u1:SECRET@host/org/repo.git
• lokalny plik ~/dev/workspace/rv/tokens/tokens.json

Kierunek jest jawny:

• tokens list store pokazuje tylko rekordy w tokens.json
• tokens list remote pokazuje tylko git remotes
• tokens sync remote r1 czyta git remote r1 i zapisuje rekord do tokens.json
• tokens sync store r1 czyta tokens.json i zapisuje auth do git remote r1
• tokens update r1 nie synchronizuje sekretu, tylko pobiera metadane z API
• tokens remove store r1 usuwa rekord z tokens.json
• tokens remove remote r1 usuwa git remote
• tokens remove both r1 usuwa rekord ze store i git remote

Format tokens.json

Aktualny format to version: 3. Glownym rekordem jest jeden remote-token. Pole id jest obowiazkowe i musi byc takie samo jak nazwa git remote, np. r1 albo r1a.

{
  "version": 3,
  "tokens": [
    {
      "id": "r1",
      "value": "SECRET",
      "server": {
        "type": "gitea",
        "endpoint": "http://77.90.8.171:3001",
        "scheme": "http",
        "host": "77.90.8.171",
        "port": 3001
      },
      "user": "u1",
      "org": "edu-tools",
      "repo": "rv-launcher",
      "valid": "forever",
      "scope": {
        "a": "-",
        "A": "-",
        "i": "-",
        "m": "-",
        "n": "-",
        "o": "-",
        "p": "-",
        "r": "w",
        "u": "-"
      },
      "org_perm": {
        "o": "+",
        "a": "+",
        "w": "+",
        "r": "+",
        "c": "+"
      },
      "repo_perm": {
        "o": "+",
        "a": "+",
        "w": "+",
        "r": "+"
      }
    }
  ]
}

Pelny schemat jest w doc/tokens.schema.json.

Pola

Pola synchronizowane z git remote:

• id - nazwa git remote, np. r1; to jest klucz rekordu
• server.endpoint - endpoint serwera, np. http://77.90.8.171:3001
• server.type - typ serwera, np. gitea, github, gitlab, unknown
• user - login z URL-a, czyli lewa strona http://u1:SECRET@...
• value - sekret tokena
• org - organizacja z URL-a
• repo - repo z URL-a

Pola pobierane z API przez tokens update r1:

• valid - forever, data wygasniecia, invalid, ? albo !
• scope - mapa scope tokena
• org_perm - mapa praw uzytkownika w organizacji
• repo_perm - mapa praw uzytkownika w repo

Porownanie

tokens compare porownuje git remote i tokens.json po:

server.endpoint + id + user + value + org + repo

Znacznik w kolumnie token_ref:

• * - remote i tokens.json sa zgodne
• R - wpis istnieje tylko w git remote
• S - wpis istnieje tylko w tokens.json
• ! - wpis jest sparowany, ale token jest invalid albo ma blad sprawdzania

Dla niesparowanych wpisow rvctl pokazuje ? w kolumnach valid, scope, org i repo, bo metadane API sa wiarygodne dopiero dla rekordu ze store.

Uprawnienia

W tokens.json uprawnienia sa zapisane jako mapy klucz-wartosc. W tabeli CLI sa pokazywane jako zwarte maski.

Naglowki masek:

• scope: aAimnopru
• org: oawrc-
• repo: oawr--

Kategorie scope:

• a - activitypub
• A - admin
• i - issue
• m - misc
• n - notification
• o - organization
• p - package
• r - repository
• u - user

Wartosci w scope:

• w - read/write
• r - read
• - - no access
• ? - nie wczytano
• ! - blad wczytania

Gitea moze zwrocic globalny scope all zamiast listy write:*. Launcher rozwija wtedy all do pelnej maski wwwwwwwww. Scope public-only jest flaga ograniczenia widocznosci API i nie zmienia kategorii w tej masce.

Kategorie org_perm:

• o - owner
• a - admin
• w - write
• r - read
• c - create repository

Kategorie repo_perm:

• o - owner
• a - admin
• w - write
• r - read

Wartosci w org_perm i repo_perm:

• + - flaga wlaczona
• - - flaga wylaczona
• ? - nie wczytano
• ! - blad wczytania

Typowy Flow

W repo rv-launcher:

git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
./rvctl tokens scan
./rvctl tokens compare
./rvctl tokens sync remote r1
./rvctl tokens update r1
./rvctl tokens compare

Po sync remote sekret jest w tokens.json. Po update rvctl dopisuje valid, scope, org_perm i repo_perm.

Jesli chcesz tylko zobaczyc jedno zrodlo, bez porownywania:

./rvctl tokens list remote
./rvctl tokens list store
./rvctl tokens list both

Jesli token ma zostac tylko w tokens.json, usun git remote:

./rvctl tokens remove remote r1

Jesli trzeba ponownie utworzyc remote z sekretem ze store:

./rvctl tokens sync store r1

Komendy

tokens scan

Read-only. Czyta git remotes i wypisuje diagnostyczna tabele URL-i: auth, plain i unsupported. Nie porownuje ich z tokens.json. Bez --repo czyta repo zawierajace rvctl.

./rvctl tokens scan
./rvctl tokens scan --repo ~/dev/workspace/rv/tools/rv-launcher

tokens compare

Read-only. Czyta git remote i tokens.json, laczy wpisy w pary i wypisuje tabele tokens. Nie tworzy i nie modyfikuje tokens.json. Bez --repo czyta repo zawierajace rvctl.

./rvctl tokens compare
./rvctl tokens compare --repo ~/dev/workspace/rv/tools/rv-launcher

tokens list store|remote|both

Read-only. Wypisuje jedno zrodlo bez porownywania go z drugim. To odroznia list od compare: list odpowiada na pytanie "co jest zapisane tutaj", a compare odpowiada na pytanie "czy store i remote sa zgodne".

./rvctl tokens list store
./rvctl tokens list remote
./rvctl tokens list both
./rvctl tokens list remote --repo ~/dev/workspace/rv/tools/rv-launcher

Przelaczniki:

• --repo PATH - repo, z ktorego listowane sa git remotes; bez tej opcji uzywane jest repo zawierajace rvctl
• --server ENDPOINT - ogranicza wynik do jednego endpointu

tokens sync remote REMOTE_ID

Kopiuje dane dostepowe z git remote do tokens.json. Nie pobiera metadanych z API. Bez --repo czyta repo zawierajace rvctl.

./rvctl tokens sync remote r1
./rvctl tokens sync remote r1 --repo ~/dev/workspace/rv/tools/rv-launcher

tokens update REMOTE_ID

Pobiera z API metadane dla rekordu REMOTE_ID zapisanego w tokens.json. Nie zmienia git remote URL-a i nie kopiuje sekretu z remote.

./rvctl tokens update r1
./rvctl tokens update r1 --dry-run

tokens sync store REMOTE_ID

Zapisuje dane z rekordu REMOTE_ID w tokens.json do git remote o tej samej nazwie. Jesli remote jeszcze nie istnieje, URL jest budowany z pol server.endpoint, org i repo w tokens.json. Bez --repo zapisuje do repo zawierajacego rvctl.

./rvctl tokens sync store r1
./rvctl tokens sync store r1 --replace

tokens remove store|remote|both REMOTE_ID

Usuwa rekord ze store, git remote albo oba miejsca. Bez --repo operacje remote i both dzialaja na repo zawierajacym rvctl.

./rvctl tokens remove store r1
./rvctl tokens remove remote r1
./rvctl tokens remove both r1

Przelaczniki:

• --server ENDPOINT - rozroznia rekord w tokens.json, jezeli ten sam id wystepuje dla wielu serwerow
• --repo PATH - repo, z ktorego usuwany jest git remote
• --dry-run - pokazuje plan bez usuwania

tokens read

Pokazuje zawartosc tokens.json.

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

tokens add

Dodaje pusty szkielet rekordu do tokens.json. REMOTE_ID musi odpowiadac nazwie git remote.

./rvctl tokens add r1
./rvctl tokens add r1 --server http://77.90.8.171:3001 --user u1 --org edu-tools --repo rv-launcher

tokens sync store r1 nie uzyje pustego tokena. Najpierw trzeba uzupelnic value i user.

tokens stats

Pokazuje kontekst, tabele tokens i podsumowanie statusow endpointow. Bez --repo czyta repo zawierajace rvctl.

./rvctl tokens stats
./rvctl tokens stats --repo ~/dev/workspace/rv/tools/rv-launcher

Komendy zgodnosci

Stare komendy nadal dzialaja, ale w nowych instrukcjach preferujemy jawne sync remote, sync store i update REMOTE_ID.

./rvctl tokens update --from remotes --repo PATH
./rvctl tokens update --from store --repo PATH --remote r1 --server http://77.90.8.171:3001
./rvctl tokens write --repo PATH --remote r1 --server http://77.90.8.171:3001