gwoe-antragspruefer/docs/reference/zugriffsrechte.md

# Zugriffsrechte & User-Status

Abgeleitet direkt aus dem Code (`app/main.py`, `app/auth.py`, Templates). Stand des Generats: 2026-04-20.

## Drei User-Status

| Status | Signal | Guard im Code |
|---|---|---|
| **Gast** (`anonymous`) | Kein gültiger `access_token`-Cookie | — |
| **Registriert** (`authenticated`) | Gültiger Keycloak-JWT, Rolle beliebig | `Depends(require_auth)` |
| **Admin** | Keycloak-JWT mit Rolle `admin` oder `gwoe-admin` | `Depends(require_admin)` |

Zwei Sonder-Modi:

- **Dev-Modus** (`AUTH_ENABLED=false` in .env): jede Anfrage wird als Anonymous+Admin ausgegeben, sämtliche Guards fallen. Nur lokal, nie in Prod. Siehe ADR 0005.
- **Approval-pending**: Nutzer:innen, die über `/api/auth/register` angelegt sind aber noch nicht von einem Admin via `/api/auth/approve-user` freigeschaltet wurden, können sich einloggen, aber keine `require_auth`-Features nutzen (Keycloak verweigert Token-Ausgabe). Siehe `docs/how-to/keycloak-setup.md`.

## Endpoint × Status-Matrix (63 Routes)

### Admin-only (5)

Nur Nutzer:innen mit Rolle `admin`/`gwoe-admin` erreichen diese:

| Methode | Pfad | Zweck |
|---|---|---|
| POST | `/api/batch-analyze` | Batch-Bewertung starten |
| POST | `/api/programme/index` | Wahlprogramm indexieren |
| POST | `/api/auth/approve-user` | User-Freischaltung |
| GET | `/api/auth/pending-users` | Liste offener Freischaltungs-Anträge |
| DELETE | `/api/assessment/delete` | Bewertung löschen (für Re-Analyse) |

### Authenticated (8)

Jede:r eingeloggte:r Nutzer:in:

| Methode | Pfad | Zweck |
|---|---|---|
| POST | `/analyze` | Freitext-Upload bewerten |
| POST | `/api/analyze-drucksache` | Antrag aus Landtag bewerten |
| POST | `/api/bookmark` | Merklisten-Eintrag toggeln |
| POST | `/api/comment` | Kommentar anlegen |
| DELETE | `/api/comment/{id}` | Eigenen Kommentar löschen |
| POST | `/api/subscriptions` | E-Mail-Abo anlegen |
| DELETE | `/api/subscriptions/{id}` | E-Mail-Abo löschen |
| POST | `/api/vote` | Antrag-Bewertung votieren |

### Optional-User (5)

Funktionieren auch ohne Login, aber personalisieren mit User-Daten wenn eingeloggt:

| Methode | Pfad | Verhalten |
|---|---|---|
| GET | `/api/auth/me` | Gibt Auth-Status zurück |
| GET | `/api/bookmarks` | Liste eigener Bookmarks (wenn eingeloggt), sonst `[]` |
| GET | `/api/comments?drucksache=X` | Öffentliche + eigene Kommentare |
| GET | `/api/subscriptions` | Eigene Abos |
| GET | `/api/votes?drucksache=X` | Alle Votes + eigenes Vote-Flag |

### Public (45)

Alle Lese-Endpoints und statische Seiten sind offen. Darunter u.a.:

- **Seiten:** `/`, `/antrag/{ds}`, `/classic`, `/auswertungen`, `/methodik`, `/quellen`, `/impressum`, `/datenschutz`, `/health`, `/v2/{merkliste,tags,cluster,neu,batch}`
- **API-Listen:** `/api/assessments`, `/api/assessment`, `/api/clusters`, `/api/bundeslaender`, `/api/programme`, `/api/search`, `/api/search-landtag`, `/api/feed.xml`, `/api/wahlprogramm-cite`
- **Auswertungen:** `/api/auswertungen/{matrix,zeitreihe,themen-matrix,export.csv,export.json}`
- **Auth-Flow:** `/api/auth/login`, `/api/auth/register`, `/api/auth/callback`, `/api/auth/login-url`, `/api/auth/refresh`, `/unsubscribe/{sub}/{token}`
- **Jobs:** `/api/analyze-drucksache`-Ergebnisse via `/status/{job_id}`, `/result/{job_id}`, `/result/{job_id}/pdf`, `/api/queue/status`

Das heißt: **Lesen und Navigieren braucht keinen Account**. Erst Aktionen (Merken, Kommentieren, Bewerten, neue Analyse starten) erfordern Login.

## UI-Sichtbarkeit — was sieht wer

### v2-Frontend (`/`, `/antrag/*`, `/v2/*`)

| UI-Element | Gast | Registriert | Admin |
|---|:-:|:-:|:-:|
| Sidebar-Gruppe „Lesen" (Durchsuchen / Merkliste / Tags / Cluster) | ✓ | ✓ | ✓ |
| Sidebar-Gruppe „Prüfen" (Neuer Antrag / Batch-Analyse) | ✓ Links | ✓ funktional | ✓ funktional |
| Sidebar-Gruppe „Daten" (Auswertungen / Export / Feed) | ✓ | ✓ | ✓ |
| Sidebar-Gruppe „Administration" (Freischaltungen / Queue / Abos) | — | — | ✓ (via `{% if is_admin %}` in `base.html:61`) |
| Topbar „Klassische Ansicht" + Theme-Toggle | ✓ | ✓ | ✓ |
| `/v2/merkliste` Bookmark-Liste | Login-CTA | eigene Liste | eigene Liste |
| Bookmark-Stern auf Antragsdetail | Login-CTA | ✓ | ✓ |
| Kommentar-Form | Login-CTA | ✓ | ✓ |
| Vote-Buttons | Login-CTA | ✓ | ✓ |
| Re-Analyze-Button | — | ✓ (nach Ablauf) | ✓ jederzeit |
| Delete-Assessment-Button | — | — | ✓ |

### Classic-Frontend (`/classic`)

| UI-Element | Gast | Registriert | Admin |
|---|:-:|:-:|:-:|
| Listenansicht + Detail | ✓ | ✓ | ✓ |
| Hamburger → Anmelden/Registrieren | ✓ (öffnet Modal) | — | — |
| Hamburger → Auswertungen / Quellen / Methodik | ✓ | ✓ | ✓ |
| Merkliste-Tab | ✓ (localStorage, gerätegebunden) | ✓ (synced mit Server) | ✓ |
| Kommentare anlegen | Login-CTA | ✓ | ✓ |
| Admin-Tab | — | — | ✓ (Freischaltungen, Queue, Batch) |

## Login-/Auth-Flows

Zwei Varianten koexistieren:

### Direct Access Grant (Default in v2 + `/classic`-Modal)

1. User klickt „Anmelden" → Modal öffnet
2. POST `/api/auth/login` mit `username`+`password`
3. Server ruft Keycloak `grant_type=password` gegen Client `gwoe-antragspruefer`
4. Setzt `access_token` (HttpOnly-Cookie) + `rt` (Refresh-Token, Path `/api/auth/refresh`)
5. Modal schließt, UI refreshed via `/api/auth/me`

**Voraussetzung:** Keycloak-Client `gwoe-antragspruefer` hat `directAccessGrantsEnabled: true` (ist gesetzt seit 2026-04-20).

### OIDC Redirect (Fallback)

`/api/auth/login-url` → Keycloak-Login-Seite → `/api/auth/callback` → Cookie gesetzt → Redirect auf `/`.

Wurde mit der Direct-Access-Variante überflüssig, bleibt für Notfall erhalten.

## Admin-Rollen definieren

Im Keycloak-Admin:

1. Realm `collaboration` → **Roles** → Rolle `admin` anlegen (oder `gwoe-admin`)
2. User → dem jeweiligen Nutzer die Rolle zuweisen
3. Code prüft in `auth.py:220`: `"admin" in roles or "gwoe-admin" in roles`

Kein Fein-Granular-Rollen-Modell vorgesehen — `admin` ist alles-oder-nichts.

## Dev-Bypass

In `.env`: `AUTH_ENABLED=false` setzt alle Guards auf Bypass. `require_auth` gibt `Dev-Modus`-User zurück (`sub=anonymous`, `roles=[]`), `require_admin` gibt `roles=["admin"]`. Nur für lokale Entwicklung ohne Keycloak-Stack. In Prod immer auf `true`.

## Änderung gegenüber alter Doku

`docs/reference/api.md` hatte eine stale „Auth"-Spalte mit „Keycloak (geplant)". Diese Doku ersetzt sie inhaltlich — das api.md könnte zusammengelegt oder auf diese Seite verlinken.

## Wartungshinweis

Diese Doku wird nicht automatisch generiert. Bei neuen Routes / Guards manuell nachpflegen oder via `docs/reference/scan-zugriffsrechte.py` (TODO: hat bisher keiner geschrieben) regenerieren.