stem-launcher/doc/tokens.md

# Tokens

Plik opisuje aktualny 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://LOGIN:TOKEN@host/org/repo.git`
- lokalny plik `~/dev/workspace/rv/tokens/tokens.json`

Jesli remote URL zawiera `LOGIN:TOKEN@...`, to remote jest zrodlem prawdy.
Launcher moze wtedy zeskanowac repo i zapisac ten token do `tokens.json`.

Jesli remote nie ma tokena, `tokens.json` moze byc uzyty jako lokalny store
przy operacjach `tokens write` i `tokens update --from store`.

## Format `tokens.json`

Tokeny sa trzymane per endpoint serwera, a dopiero pod nim per user i token:

```json
{
  "version": 2,
  "servers": {
    "http://77.90.8.171:3001": {
      "type": "gitea",
      "scheme": "http",
      "host": "77.90.8.171",
      "port": 3001,
      "users": {
        "u1": {
          "tokens": {
            "t1": "SECRET",
            "t2": {
              "value": "SECRET",
              "expires_at": "2026-05-01T12:00:00"
            }
          }
        }
      }
    }
  }
}
```

To pozwala odroznic:

- typ serwera, na przyklad `gitea`, `github`, `gitlab`, `unknown`
- endpoint, czyli `scheme + host + port`
- uzytkownikow na danym serwerze
- wiele tokenow dla jednego usera
- opcjonalna date wygasniecia `expires_at` dla tokena

## Skanowanie remota

Przy `tokens scan` launcher:

- czyta wszystkie remote URL-e w repo
- czyta `tokens.json`
- laczy remote i store w pary po endpoincie serwera
- wybiera tylko `http` i `https`
- jesli URL ma `LOGIN:TOKEN@...`, wyciaga login i token
- zapisuje je pod odpowiednim endpointem w `tokens.json`

Endpoint jest liczony z:

- scheme
- host
- port

Przy skanowaniu launcher zapisuje tez metadane serwera:

- `type`
- `scheme`
- `host`
- `port`

## Komendy

### `tokens scan`

Zrodla:

```text
repo + tokens.json
```

Dzialanie:

- skanuje remote URL-e w repo
- czyta wpisy z `tokens.json`
- laczy oba zrodla po endpoincie serwera
- zapisuje znalezione tokeny do `tokens.json`
- zapisuje je per endpoint serwera
- wypisuje tabele `tokens`

Tabela `tokens` pokazuje jeden logiczny wiersz na token. Remote i `tokens.json`
sa laczone po endpoincie, userze i wartosci tokena.

Znacznik w `token_ref`:

- `*` - token jest w remote i `tokens.json`, uprawnienia zostaly wczytane
- `R` - token jest tylko w remote
- `S` - token jest tylko w `tokens.json`
- `!` - blad wczytania uprawnien dla sparowanego tokena

Kolumny w tabeli `tokens`:

- `item` - numer wiersza tokena
- `server` - typ serwera, na przyklad `gitea`
- `proto` - protokol endpointu, na przyklad `http`
- `host` - host endpointu razem z portem, na przyklad `77.90.8.171:3001`
- `org` - organizacja z remote URL
- `repo` - repo z remote URL
- `user` - login wlasciciela tokena
- `remote` - nazwa remota, na przyklad `r1`
- `token_ref` - nazwa tokena z markerem po prawej stronie
- `token` - zamaskowana wartosc tokena
- `valid` - `forever`, lokalne `expires_at`, `invalid`, `?` albo `!`
- `scope` - maska scope tokena `awrop`
- `org` - maska praw w organizacji `oawrc`
- `repo` - maska praw w repo `oawr`

Maski uprawnien:

- `+` - flaga wlaczona
- `-` - flaga wylaczona
- `?` - nie wczytano, na przyklad dla `R` albo `S`
- `!` - blad wczytania

Tabela nie wypisuje sekretu tokena wprost. Kolumna `token` pokazuje skrot, na
przyklad `e59cc...13be`.

`valid` jest liczone tak:

- `forever` - API akceptuje token i nie ma lokalnego `expires_at`
- `2026-05-01T12:00:00` - API akceptuje token i taka data jest zapisana w `tokens.json`
- `invalid` - API odrzuca token albo lokalne `expires_at` jest w przeszlosci
- `?` - token nie jest sparowany jako `*`, wiec nie sprawdzamy uprawnien
- `!` - blad sprawdzania API

Przyklad:

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

### `tokens read`

Pokazuje szczegolowa zawartosc `tokens.json`.

Wynik zawiera:

- endpoint
- type
- scheme
- host
- port
- users
- tokens

Oraz liste userow i nazw tokenow dla kazdego endpointu.

Przyklad:

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

### `tokens stats`

Pokazuje statystyki per endpoint serwera i porownuje dwa zrodla:

- endpointy znalezione w remote URL-ach repo
- endpointy zapisane w `tokens.json`

Wynik ma ten sam model porownania co `tokens scan`, ale nie zapisuje zmian:

- liczbe endpointow w repo
- liczbe endpointow w store
- laczna unie endpointow
- statusy zgodnosci, na przyklad `in_sync`, `store_ahead`, `repo_ahead`
- tabele `tokens`

Przyklad:

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

### `tokens write`

Kierunek:

```text
tokens.json -> repo
```

Dzialanie:

- bierze token z `tokens.json`
- wybiera endpoint, usera i token
- wpisuje dane auth do wybranego remota repo

Przyklad:

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

### `tokens update`

Uruchamia synchronizacje w zadanym kierunku.

Dozwolone kierunki:

- `tokens update --from remotes`
- `tokens update --from store`

Przyklad:

```bash
./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
```

## Konflikty

Domyslnie launcher nie zgaduje przy konflikcie.

Jesli:

- token jest w repo, ale nie ma go w `tokens.json`
  uzyj `tokens scan`
- token jest w `tokens.json`, ale nie ma go w repo
  uzyj `tokens write`
- token jest i tu, i tu, ale wartosci sa rozne
  wybierz kierunek jawnie przez `tokens update --from ...`

Przy `tokens write` i `tokens update --from store` mozna uzyc:

- `--replace`
- `--dry-run`

## Rekomendacja

Najbezpieczniejszy model pracy:

- `tokens scan` do zczytywania danych z remote'ow
- `tokens read` do podgladu store
- `tokens stats` do zbiorczego przegladu per endpoint
- `tokens write` do jawnego wpisania auth do remota
- `tokens update --from ...` tylko z jawnym kierunkiem