# Użytkownicy, role i uprawnienia {#users-roles-permissions}
SnapOtter dostarcza trzy wbudowane role, 17 szczegółowych uprawnień oraz obsługę ról niestandardowych z opcjonalną kontrolą dostępu per narzędzie. Ta strona omawia pełny model autoryzacji, zakresowanie kluczy API, zarządzanie zespołami i rejestrowanie audytu.
Administratorzy mogą tworzyć użytkowników za pośrednictwem panelu administracyjnego lub punktu końcowego `POST /api/auth/register`. Każdy użytkownik ma nazwę użytkownika, rolę, przypisanie do zespołu oraz opcjonalny adres e-mail.
### Domyślny administrator {#default-admin}
Przy pierwszym uruchomieniu SnapOtter tworzy domyślne konto administratora. Dane uwierzytelniające pochodzą ze zmiennych środowiskowych:
| Zmienna | Domyślnie | Opis |
|---|---|---|
| `DEFAULT_USERNAME` | `admin` | Nazwa użytkownika dla początkowego konta administratora |
Ustaw `AUTH_ENABLED=false`, aby całkowicie wyłączyć uwierzytelnianie. W tym trybie dla wszystkich żądań używany jest syntetyczny anonimowy użytkownik z rolą `admin`. Logowanie nie jest wymagane.
::: warning
Wyłączenie uwierzytelniania przyznaje pełny dostęp administratora każdemu, kto może dotrzeć do instancji. Używaj tego wyłącznie w zaufanych środowiskach.
:::
## Wbudowane role {#built-in-roles}
SnapOtter zawiera trzy wbudowane role. Nie można ich modyfikować ani usuwać.
### Admin {#admin}
Wszystkie 17 uprawnień. Pełna kontrola nad instancją.
Administratorzy z uprawnieniem `security:manage` mogą tworzyć role niestandardowe za pośrednictwem panelu administracyjnego lub API ról. Listowanie ról wymaga `audit:read`.
### Tworzenie roli niestandardowej {#creating-a-custom-role}
```bash
curl -X POST http://localhost:1349/api/v1/roles \
-H "Authorization: Bearer si_..."\
-H "Content-Type: application/json"\
-d '{
"name": "reviewer",
"description": "Can use tools and view all files",
Wszystkie 17 uprawnień można delegować za pośrednictwem ról niestandardowych, ale uprawnienie administracyjne nie czyni tej roli równoważną wbudowanej roli `admin`. Mutacje użytkowników autoryzowane przez `users:manage`, destrukcyjne operacje autoryzowane przez `compliance:manage` i niestandardowe zarządzanie rolami autoryzowane przez `security:manage` są ograniczone bieżącymi uprawnieniami aktora:
- Wbudowane role podążają za `admin` > `editor` > `user`; role niestandardowe znajdują się poniżej ról wbudowanych.
- Uprawnienia celu muszą być zawarte w **efektywnych** uprawnieniach aktora. Dlatego klucz API o ograniczonym zakresie nie może wykonywać uprawnień pominiętych w jego zakresie.
- Dostęp do narzędzi roli docelowej musi być ograniczony dostępem do narzędzi aktora.
- Wyłączone konto jest sprawdzane pod kątem jego pierwotnej roli, gdy ta rola jest rejestrowana jako `disabled:<original-role>`.
- Usunięcie roli niestandardowej wymaga również uprawnień do przypisania wbudowanej funkcji zastępczej `user`; niepełnosprawni członkowie pozostają wyłączeni jako `disabled:user`.
Globalne dane uwierzytelniające i konfiguracja są bardziej rygorystyczne: wydawanie lub unieważnianie tokena SCIM oraz importowanie konfiguracji instancji wymagają wbudowanej roli `admin` z pełnymi skutecznymi uprawnieniami administratora.
### Uprawnienia na poziomie narzędzi {#tool-level-permissions}
Role niestandardowe mogą opcjonalnie ograniczać, do których narzędzi użytkownicy mają dostęp. Dostępne są dwa tryby:
| Tryb | Zachowanie | Wymóg licencji |
|---|---|---|
| `category` | Ograniczenie według modalności (obraz, wideo, audio, dokument, plik) | Brak (za darmo) |
| `tool` | Ograniczenie według identyfikatora poszczególnego narzędzia | Wymaga funkcji enterprise `per_tool_permissions` |
Gdy ustawiony jest tryb `tool`, ale funkcja enterprise nie jest dostępna, SnapOtter degraduje się łagodnie i zezwala na dostęp do wszystkich narzędzi.
```json
{
"name":"image-only",
"permissions":["tools:use","files:own"],
"toolPermissions":{
"mode":"category",
"allowed":["image"]
}
}
```
### Usuwanie roli niestandardowej {#deleting-a-custom-role}
Gdy rola niestandardowa zostanie usunięta, wszyscy przypisani do niej użytkownicy są automatycznie przenoszeni do roli `user`.
## Zespoły {#teams}
Zespoły grupują użytkowników na potrzeby zarządzania przechowywaniem i retencją. Przy pierwszym uruchomieniu tworzony jest zespół `Default`.
| Pole | Typ | Opis |
|---|---|---|
| `name` | string | Unikatowa nazwa zespołu (1-50 znaków) |
| `storageQuota` | number | Limit przechowywania per zespół w bajtach (działa bez enterprise) |
| `retentionHours` | number | Automatyczne usuwanie danych wyjściowych po tylu godzinach (wymaga `team_retention_overrides`, enterprise) |
| `legalHold` | boolean | Zapobiega automatycznemu usuwaniu plików członków zespołu (wymaga `legal_hold`, enterprise) |
::: info
Zespołu `Default` nie można usunąć. Zespołów, które nadal mają członków, nie można usunąć. Najpierw przenieś członków.
:::
## Klucze API {#api-keys}
Użytkownicy mogą generować klucze API do dostępu programowego. Każdy klucz używa prefiksu `si_` i jest wyświetlany tylko raz, w momencie utworzenia.
### Uprawnienia zakresowe {#scoped-permissions}
Klucze API mogą opcjonalnie nieść tablicę `permissions`. Gdy jest ustawiona, efektywne uprawnienia dla żądania stanowią **część wspólną** uprawnień roli użytkownika i uprawnień zakresowych klucza. Oznacza to, że klucz API nigdy nie może eskalować poza własne uprawnienia użytkownika.
```bash
curl -X POST http://localhost:1349/api/v1/api-keys \
-H "Authorization: Bearer si_..."\
-H "Content-Type: application/json"\
-d '{
"name": "CI pipeline key",
"permissions": ["tools:use", "files:own"],
"expiresAt": "2027-01-01T00:00:00Z"
}'
```
### Wygasanie {#expiration}
Klucze akceptują opcjonalny znacznik czasu `expiresAt`. Wygasłe klucze są odrzucane w czasie uwierzytelniania.
## Dziennik audytu {#audit-log}
SnapOtter rejestruje zdarzenia istotne dla bezpieczeństwa w ustrukturyzowanym dzienniku audytu przechowywanym w tabeli bazy danych `audit_log`.
GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z
```
Wymaga uprawnienia `audit:read`. Obsługuje stronicowanie (`page`, `limit`) oraz filtry (`action`, `ip`, `from`, `to`).
### Audytowanie operacji narzędzi {#tool-operation-auditing}
::: warning
Zdarzenia `TOOL_EXECUTED`**nie** są rejestrowane domyślnie. Są opcjonalne poprzez jedną z dwóch ścieżek:
1. Ustaw ustawienie administratora `auditToolOperations` na `true`.
2. Posiadaj aktywną licencję z funkcją `audit_export` (dostępną zarówno w planie team, jak i enterprise).
Bez jednego z tych warunków poszczególne wykonania narzędzi nie są zapisywane w dzienniku audytu.
:::
### Eksportowanie {#exporting}
```
GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
```
Wymaga uprawnienia `audit:read` oraz funkcji enterprise `audit_export` (dostępnej zarówno w planie team, jak i enterprise). Obsługuje formaty CSV i JSON, filtrowane według `action`, `actorId`, `targetType`, `targetId`, `from` oraz `to`.
### Podpisywanie odporne na manipulacje {#tamper-resistant-signing}
Gdy jest włączone, każdy wpis dziennika audytu jest podpisywany kodem HMAC pochodzącym z `DATA_ENCRYPTION_KEY`. Wymaga to:
1. Ustawienia `DATA_ENCRYPTION_KEY` w Twoim środowisku.
Sesje są oparte na plikach cookie, kontrolowane przez `SESSION_DURATION_HOURS` (domyślnie: 168 godzin / 7 dni).
### Zmiany ról unieważniają sesje {#role-changes-invalidate-sessions}
Gdy administrator zmienia rolę użytkownika, wszystkie aktywne sesje tego użytkownika są usuwane. Użytkownik musi zalogować się ponownie, aby przejąć swoje nowe uprawnienia.
### Zabezpieczenia {#safety-guards}
- **Ochrona ostatniego administratora**: ostatniego pozostałego administratora nie można zdegradować do niższej roli. API zwraca błąd, jeśli spróbujesz.
- **Zapobieganie samousunięciu**: administratorzy nie mogą usunąć własnego konta za pośrednictwem API.
