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` jest read-only i niczego nie zapisuje

## 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 poswiadczenia z URL-a git remota, ale zostawia remote
- `tokens remove both r1` usuwa rekord ze store i poswiadczenia z URL-a git remota

## 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`.

```json
{
  "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 scan` porownuje git remote i `tokens.json` po:

```text
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`:

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

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:

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

Jesli remote ma byc bez sekretu, a token ma zostac tylko w `tokens.json`:

```bash
./rvctl tokens remove remote r1
git remote add r1 http://77.90.8.171:3001/edu-tools/rv-launcher.git
```

Jesli trzeba ponownie wpisac sekret ze store do remota:

```bash
./rvctl tokens sync store r1
```

## Komendy

### `tokens scan`

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

```bash
./rvctl tokens scan
./rvctl tokens scan --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 `scan`: `list` odpowiada na pytanie "co jest zapisane tutaj", a
`scan` odpowiada na pytanie "czy store i remote sa zgodne".

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

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

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

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

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

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

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

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

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