stem-launcher/doc/tokens.md

# Tokens

`rvctl` obsługuje tokeny Gitea w dwóch miejscach:

- `tokens.json` - lokalny store sekretów i metadanych tokenów
- `.git/config` - git remotes w konkretnym repo

Rekord w `tokens.json` zawiera token, endpoint serwera, login oraz docelowe
`org/repo`. Git remote służy tylko do operacji Git (`fetch`, `push`) albo do
pierwszego wczytania tokena do store.

Bez `--repo` komendy tokenów działają na repo `rv-launcher`. Dla kart pracy albo
innych repo podaj `--repo PATH`.

## Szybki przepływ

Startujemy od git remota z tokenem w URL-u:

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

Sprawdzamy, co jest zapisane w remote i store:

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

Kopiujemy token z remota do `tokens.json`:

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

Pobieramy z API metadane tokena:

```bash
./rvctl tokens update r1
```

Sprawdzamy zgodność remote i store:

```bash
./rvctl tokens cmp
```

Po poprawnej synchronizacji `compare`/`cmp` powinien pokazać `*` przy `r1`.

Jeśli chcesz sprawdzić, czy store da się odtworzyć z remota, usuń tylko rekord
ze store i wczytaj go ponownie z git remota:

```bash
./rvctl tokens rm store r1
./rvctl tokens sync remote r1
./rvctl tokens update r1
./rvctl tokens cmp
```

Po `sync remote` metadane API są ustawiane na `?`, dlatego `update` jest zawsze
kolejnym krokiem.

## Dwa Źródła

`rvctl` rozróżnia dwa miejsca:

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

Komendy zapisujące store same tworzą katalog nadrzędny, jeżeli go nie ma.
Katalog `tokens` dostaje prawa `700`, a plik `tokens.json` prawa `600`.

Kierunki są jawne:

- `sync remote r1` czyta git remote i zapisuje rekord do `tokens.json`
- `sync store r1` czyta `tokens.json` i zapisuje auth do git remota
- `update r1` nie synchronizuje sekretu, tylko odświeża metadane z API
- `remove remote r1` albo `rm remote r1` usuwa git remote
- `remove store r1` albo `rm store r1` usuwa rekord z `tokens.json`

## Listowanie

`list` pokazuje źródła bez porównywania:

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

Znaczenie:

- `store` - rekordy zapisane w `tokens.json`
- `remote` - git remotes zapisane w `.git/config`
- `both` - oba źródła jako osobne wiersze

Dla innego repo podaj `--repo`:

```bash
./rvctl tokens list remote --repo ~/dev/workspace/rv/series/inf/03
```

## Synchronizacja

### Remote -> Store

Użyj, gdy token jest w git remote i chcesz go zapisać w store:

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

Ta komenda kopiuje sekret, usera, endpoint, org i repo z URL-a remota do
`tokens.json`. Nie pyta API o uprawnienia, więc zawsze zeruje metadane API:
`valid` ustawia na `?`, maski `scope`, `org_perm` i `repo_perm` ustawia na `?`,
a `expires_at` usuwa. Realne uprawnienia wpisuje dopiero:

```bash
./rvctl tokens update r1
```

### Store -> Remote

Użyj, gdy token jest już w `tokens.json`, a chcesz utworzyć albo odświeżyć git
remote:

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

Jeśli remote `r1` nie istnieje, `rvctl` buduje URL z pól `server.endpoint`,
`org` i `repo` w `tokens.json`, na przykład:

```text
http://77.90.8.171:3001/edu-tools/rv-launcher.git
```

Jeżeli w repo istnieje tylko `origin` wskazujący ten sam URL, `sync store r1`
automatycznie przemianuje `origin` na `r1`, a potem wpisze credentials.

Opcjonalnie można podać URL ręcznie:

```bash
./rvctl tokens sync store r1 --url http://77.90.8.171:3001/edu-tools/rv-launcher.git
```

Jeśli remote ma już inne credentials, użyj:

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

## Aktualizacja Metadanych

Po zapisaniu tokena w store odśwież jego metadane z API:

```bash
./rvctl tokens update r1
```

`update` zapisuje w `tokens.json`:

- `valid`
- `scope`
- `org_perm`
- `repo_perm`

Ta komenda nie zmienia git remota i nie kopiuje sekretu.

## Porównanie

`compare` sprawdza zgodność store i remote. Skrót: `cmp`.

```bash
./rvctl tokens compare
./rvctl tokens cmp
```

Marker w kolumnie `token_ref`:

- `*` - store i remote są zgodne
- `S` - token jest tylko w store
- `R` - token jest tylko w remote
- `!` - wpis jest sparowany, ale token jest `invalid` albo wystąpił błąd API

Gdy marker to `S`, token nie jest błędny. To znaczy tylko, że nie ma
odpowiadającego git remota.

## Store-only

Po pierwszej konfiguracji wygodny tryb pracy to trzymanie tokena tylko w
`tokens.json`.

```bash
./rvctl tokens rm remote r1
./rvctl tokens list store
./rvctl tokens cmp
```

Wtedy `compare`/`cmp` pokazuje `S`, a `list store` nadal pokazuje znane metadane
tokenu. Gdy trzeba wykonać operacje git przez remote, odtwórz remote:

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

Po operacji można go znowu usunąć:

```bash
./rvctl tokens rm remote r1
```

## Usuwanie

Usuwaj tylko to miejsce, które naprawdę chcesz wyczyścić:

```bash
./rvctl tokens rm remote r1
./rvctl tokens rm store r1
./rvctl tokens rm both r1
```

Znaczenie:

- `remove remote` / `rm remote` usuwa git remote i sekret z `.git/config`, ale zostawia store
- `remove store` / `rm store` usuwa rekord z `tokens.json`, ale nie dotyka git remota
- `remove both` / `rm both` usuwa oba miejsca

## Inne Repo

Domyślnie komendy tokenów pracują na repo zawierającym `rvctl`. Dla kart pracy
albo innych repo podaj `--repo`.

```bash
./rvctl tokens list remote --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens compare --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03
```

Store tokenów nadal pozostaje jeden:

```text
~/dev/workspace/rv/tokens/tokens.json
```

## Pozostałe Komendy

### `tokens read`

Pokazuje zawartość `tokens.json`.

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

### `tokens add`

Dodaje szkielet rekordu do `tokens.json`. `REMOTE_ID` musi odpowiadać nazwie
git remote. Przełączniki są opcjonalne; jeśli ich nie podasz, `rvctl` zapisuje
puste wartości do późniejszego uzupełnienia. Wyjątkiem jest `server`, który
domyślnie pochodzi z `workspace.json`.

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

Najczęściej pusty szkielet ma sens wtedy, gdy chcesz ręcznie wpisać token w
`tokens.json`. `sync store r1` nie użyje pustego tokena. Najpierw trzeba
uzupełnić co najmniej `value` i `user`. Jeśli remote ma być tworzony bez `--url`,
potrzebne są też `org` i `repo`.

### `tokens stats`

Pokazuje kontekst, tabelę `tokens` i podsumowanie statusów endpointów.

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

## Uprawnienia

W `tokens.json` uprawnienia są zapisane jako mapy klucz-wartość. W tabelach CLI
są pokazywane jako zwarte maski.

Nagłówki 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

Wartości w `scope`:

- `w` - read/write
- `r` - read
- `-` - no access
- `?` - nie wczytano
- `!` - błąd wczytania

Gitea może zwrócić globalny scope `all` zamiast listy `write:*`. Launcher
rozwija wtedy `all` do pełnej maski `wwwwwwwww`. Scope `public-only` jest
flagą ograniczenia widoczności 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

Wartości w `org_perm` i `repo_perm`:

- `+` - flaga włączona
- `-` - flaga wyłączona
- `?` - nie wczytano
- `!` - błąd wczytania

## Model Danych

`tokens.json` ma format `version: 3`. Głównym rekordem jest jeden remote-token.
Pole `id` jest obowiązkowe i musi być takie samo jak nazwa git remote, np.
`r1` albo `r1a`.

Pola synchronizowane z git remote:

- `id` - nazwa git remote, np. `r1`
- `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 wygaśnięcia, `invalid`, `?` albo `!`
- `scope` - mapa scope tokena
- `org_perm` - mapa praw użytkownika w organizacji
- `repo_perm` - mapa praw użytkownika w repo

`tokens sync remote r1` nadpisuje pola z git remota i oznacza te metadane jako
nieznane. To celowe: po zmianie sekretu, usera albo repo stare metadane API nie
są już wiarygodne.

Minimalny przykład:

```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"
    }
  ]
}
```

Przykład po `tokens update r1` może dodatkowo zawierać:

```json
{
  "valid": "forever",
  "scope": {
    "a": "w",
    "A": "w",
    "i": "w",
    "m": "w",
    "n": "w",
    "o": "w",
    "p": "w",
    "r": "w",
    "u": "w"
  },
  "org_perm": {
    "o": "+",
    "a": "+",
    "w": "+",
    "r": "+",
    "c": "+"
  },
  "repo_perm": {
    "o": "+",
    "a": "+",
    "w": "+",
    "r": "+"
  }
}
```

Pełny schemat pliku jest w `doc/tokens.schema.json`.