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.

```json
{
  "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:

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

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

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

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

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

### `tokens write`

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

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

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