stem-launcher/doc/tokens.md

Tokens

Plik opisuje model pracy z tokenami w launcherze.

Zrodlo prawdy

Sa dwa miejsca, w ktorych moga byc zapisane dane dostepowe:

• remote URL w repo, na przyklad http://u1:SECRET@host/org/repo.git
• lokalny plik ~/dev/workspace/rv/tokens/tokens.json

tokens scan tylko porownuje oba miejsca i niczego nie zapisuje. tokens sync remote r1 czyta remote r1 i zapisuje jego dane w tokens.json. tokens sync store r1 zapisuje rekord r1 z tokens.json do git remote r1. tokens update r1 nie synchronizuje sekretu; tylko pobiera z API metadane tokenu: valid, scope, org_perm i repo_perm.

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

Format tokens.json

Aktualny format to version: 3. Glownym rekordem jest 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": "+"
      }
    }
  ]
}

Schemat JSON jest w pliku doc/tokens.schema.json.

Pola

Pola synchronizowane z remote URL-a:

• id - nazwa git remote, np. r1; to jest klucz rekordu w tokens.json
• server.endpoint - endpoint serwera, na przyklad http://77.90.8.171:3001
• server.type - typ serwera, na przyklad 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 wzbogacane przez API przy tokens update r1:

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

Porownanie

Porownanie z git remote -v jest robione po:

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

Znacznik w kolumnie token_ref:

• * - remote i tokens.json sa zgodne
• R - wpis istnieje tylko w remote URL-u
• S - wpis istnieje tylko w tokens.json
• ! - remote i tokens.json sa zgodne, ale zapisany token jest invalid albo ma blad walidacji

Bez zgodnego wpisu kolumny valid, scope, org i repo w raporcie maja wartosc ?, bo launcher nie pokazuje metadanych API dla niesparowanych wpisow.

Uprawnienia

W tokens.json uprawnienia sa zapisane jako mapy klucz-wartosc. W tabeli CLI sa pokazywane skrocone 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

Znaki w scope:

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

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

Znaki w org_perm i repo_perm:

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

Komendy

tokens scan

Read-only. Czyta remote URL-e i tokens.json, a potem wypisuje tabele tokens. Nie tworzy i nie modyfikuje tokens.json.

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

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 juz 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. Bez --repo zapisuje do repo zawierajacego rvctl.

./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens sync store r1 --repo PATH --replace

tokens remove store|remote|both REMOTE_ID

Usuwa rekord REMOTE_ID z tokens.json, git remote albo oba miejsca. Domyslnym repo dla remote i both jest repo, w ktorym lezy rvctl. Inne repo mozna wskazac przez --repo PATH.

./rvctl tokens remove store r1
./rvctl tokens remove remote r1
./rvctl tokens remove both r1
./rvctl tokens remove remote r1 --repo ~/dev/workspace/rv/series/inf/03

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.

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

Komendy zgodnosci

Stare komendy nadal dzialaja, ale sa mniej jednoznaczne:

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