stem-launcher/doc/tokens.md

Tokens

Plik opisuje 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://t1:SECRET@host/org/repo.git
• lokalny plik ~/dev/workspace/rv/tokens/tokens.json

tokens scan tylko porownuje oba zrodla i niczego nie zapisuje. tokens update --from remotes czyta remote URL-e, zapisuje tokeny do tokens.json i wzbogaca je danymi z API, jezeli token dziala. tokens update --from store zapisuje wybrany token z tokens.json do remote URL-a repo.

Format tokens.json

Aktualny format to version: 3. Glownym rekordem jest token. server, user, valid, scope i remotes sa atrybutami tego tokena.

{
  "version": 3,
  "tokens": [
    {
      "token_id": "t1",
      "value": "SECRET",
      "server": {
        "type": "gitea",
        "endpoint": "http://77.90.8.171:3001",
        "scheme": "http",
        "host": "77.90.8.171",
        "port": 3001
      },
      "user": "u1",
      "valid": "forever",
      "scope": "-----w---",
      "remotes": [
        {
          "name": "r1",
          "org": "edu-tools",
          "repo": "rv-launcher",
          "org_perm": "+++++",
          "repo_perm": "++++"
        }
      ]
    }
  ]
}

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

Pola

Pola synchronizowane z remote URL-a:

• server.endpoint - endpoint serwera, na przyklad http://77.90.8.171:3001
• server.type - typ serwera, na przyklad gitea, github, gitlab, unknown
• token_id - identyfikator z lewej strony URL-a, na przyklad t1 w http://t1:SECRET@...
• value - sekret tokena
• remotes[].name - nazwa remota, na przyklad r1
• remotes[].org - organizacja z URL-a
• remotes[].repo - repo z URL-a

Pola wzbogacane przez API przy tokens update --from remotes:

• user - login wlasciciela tokena odczytany z API
• valid - forever, data expires_at, invalid, ? albo !
• scope - maska scope tokena w kolejnosci aAimnopru
• remotes[].org_perm - maska praw w organizacji
• remotes[].repo_perm - maska praw w repo

Porownanie

Porownanie z git remote -v jest robione po:

server.endpoint + remote.name + token_id + 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 * albo ! kolumny valid, scope, org i repo w raporcie maja wartosc ?, bo launcher nie pokazuje metadanych API dla niesparowanych wpisow.

Maski uprawnien

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

Znaki w org i repo:

• + - 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 update --from remotes

Kopiuje tokeny z remote URL-i repo do tokens.json, zapisuje rekordy w formacie v3 i probuje pobrac pola API: user, valid, scope, org_perm, repo_perm.

./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/tools/rv-launcher
./rvctl tokens update --from remotes --dry-run

--dry-run dziala jak read-only raport i niczego nie zapisuje.

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 stats

Pokazuje kontekst, tabele tokens i podsumowanie statusow endpointow.

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

tokens write

Zapisuje wybrany token z tokens.json do remote URL-a repo.

./rvctl tokens write \
  --repo ~/dev/workspace/rv/series/inf/03 \
  --remote r1 \
  --server http://77.90.8.171:3001 \
  --token-name t1

tokens update --from store

Alias kierunkowy na zapis store -> remote. Uzywa tych samych opcji co tokens write.

./rvctl tokens update --from store --repo PATH --remote r1 --server http://77.90.8.171:3001 --token-name t1