---
name: onyva-login
description: Integriert den zentralen Onyva Dev Login (OIDC/SSO) in ein bestehendes Projekt. Nutze diesen Skill wenn jemand "onyva login integrieren", "auth integrieren" oder "/onyva-login" schreibt.
---

Deine Aufgabe ist es, den zentralen Onyva Dev Login (OIDC/SSO-Server unter `https://login.onyva.dev`) in das aktuelle Projekt zu integrieren.

## Vorgehen

1. **Analysiere das Projekt zuerst** — Lies relevante Dateien (Framework, Routing, vorhandene Auth-Logik, Env-Konfiguration), bevor du Code schreibst.

2. **Frage nach fehlenden Infos** — Du brauchst:
   - `OIDC_CLIENT_ID` und `OIDC_CLIENT_SECRET` (aus dem Admin-Panel von login.onyva.dev)
   - `OIDC_REDIRECT_URI` (wohin der Auth-Server nach dem Login zurückleitet — muss im Admin-Panel eingetragen sein)
   - `OIDC_LOGOUT_REDIRECT_URI` (wohin nach dem zentralen Logout weitergeleitet wird)
   - Falls noch nicht bekannt: welche Routen geschützt sein sollen und welche öffentlich bleiben

3. **Implementiere die Integration** nach den technischen Vorgaben unten.

4. **Passe `.env.example`** (oder äquivalente Konfiguration) mit allen nötigen Variablen an.

---

## Technische Vorgaben

### Auth-Server

- Issuer / Basis-URL: `https://login.onyva.dev`
- Discovery: `https://login.onyva.dev/.well-known/openid-configuration`

| Endpunkt | Methode | Zweck |
|---|---|---|
| `/oauth/authorize` | GET | Login starten |
| `/oauth/token` | POST | Code gegen Tokens tauschen |
| `/oauth/userinfo` | GET | Nutzerinfos per Bearer Token |
| `/oauth/jwks.json` | GET | Public Keys (RS256) |
| `/logout` | GET | Zentrales Logout |

### Login starten

Generiere `state` (≥16 Zeichen, zufällig) und `code_verifier` (PKCE), speichere beide serverseitig in der Session. Dann Weiterleitung zu:

```
GET https://login.onyva.dev/oauth/authorize
  ?response_type=code
  &client_id={OIDC_CLIENT_ID}
  &redirect_uri={OIDC_REDIRECT_URI}
  &scope=openid profile email
  &state={state}
  &code_challenge={BASE64URL(SHA256(code_verifier))}
  &code_challenge_method=S256
```

**Wichtig:** `state` muss nachweislich in der URL stehen — ohne `state` kein `state` im Callback.

### Callback verarbeiten

```python
# Pseudocode — an das Framework anpassen
def callback(request):
    # 1. State validieren
    if request.params.get("state") != session.pop("oauth_state", None):
        return error("State mismatch")

    # 2. Sonderfall: Auth deaktiviert
    if "auth_disabled" in request.params:
        session["user"] = {"auth_disabled": True}
        return redirect("/")

    # 3. Token-Tausch (application/x-www-form-urlencoded, kein JSON)
    resp = http_post("https://login.onyva.dev/oauth/token", data={
        "grant_type": "authorization_code",
        "code": request.params["code"],
        "redirect_uri": OIDC_REDIRECT_URI,
        "client_id": OIDC_CLIENT_ID,
        "client_secret": OIDC_CLIENT_SECRET,
        "code_verifier": session.pop("pkce_verifier"),
    })
    tokens = resp.json()

    # 4. Claims aus id_token lesen
    claims = decode_jwt(tokens["id_token"])  # Verifikation optional für interne Nutzung
    session["user"] = {
        "sub":       claims["sub"],        # "user:42"
        "email":     claims["email"],
        "name":      claims["name"],
        "user_type": claims["user_type"],  # "employee" | "customer"
        "app_roles": claims["app_roles"],  # ["admin"] | ["editor"] | ["viewer"] | []
    }
    return redirect("/")
```

Nach erfolgreichem Callback niemals auf `/auth/*` zurückleiten — `return_to` immer auf `/` oder eine echte App-Seite normalisieren.

### JWT Claims

```json
{
  "sub":       "user:42",
  "email":     "nutzer@onyva.de",
  "name":      "Max Mustermann",
  "user_type": "employee",
  "app_roles": ["admin"],
  "iss":       "https://login.onyva.dev",
  "aud":       "mein-client-id",
  "exp":       1700000000
}
```

### Logout

```python
def logout(request):
    session.clear()
    return redirect(
        f"https://login.onyva.dev/logout"
        f"?post_logout_redirect_uri={urllib.parse.quote(OIDC_LOGOUT_REDIRECT_URI)}"
    )
```

`post_logout_redirect_uri` muss absolut sein (`https://...`). Der Auth-Server löscht die zentrale Session — der Nutzer ist danach auf allen Onyva-Apps ausgeloggt.

### Auth-Mode-Verhalten

| auth_mode | Auth-Server-Verhalten | Client-Verhalten |
|---|---|---|
| `required` | 403 wenn keine Mitgliedschaft | Fehlermeldung anzeigen |
| `optional` | Code für jeden angemeldeten Nutzer; `app_roles` ggf. leer | App entscheidet selbst |
| `disabled` | Sofort zurück mit `?auth_disabled=1` | Kein Login-Dialog, alle Funktionen offen |

### AUTH_ENABLED=false (Entwicklungsmodus)

```python
def require_auth(request):
    if not AUTH_ENABLED:
        return {"sub": "user:0", "email": "dev@local", "name": "Dev", "user_type": "employee", "app_roles": ["admin"]}
    # ... normaler Flow
```

### Env-Variablen

```env
OIDC_ISSUER=https://login.onyva.dev
OIDC_CLIENT_ID=           # aus Admin-Panel
OIDC_CLIENT_SECRET=       # aus Admin-Panel
OIDC_REDIRECT_URI=        # muss exakt im Admin-Panel stehen; bei /api-Prefix: https://app.example.com/api/auth/callback
OIDC_LOGOUT_REDIRECT_URI= # z.B. https://app.example.com/
AUTH_ENABLED=true
```

## Wichtige Fallstricke

- **State ist Pflicht** — wird er nicht mitgeschickt, kommt er nicht zurück und der Callback schlägt fehl
- **Redirect URI exakt** — `/api/auth/callback` ≠ `/auth/callback`; im Admin-Panel muss genau dieselbe URL stehen
- **Token-Endpunkt: Form, kein JSON** — `Content-Type: application/x-www-form-urlencoded`
- **Session-Middleware** — bei Starlette/FastAPI: `itsdangerous` als Dependency erforderlich
- **Öffentliche Routen ausdrücklich ausnehmen** — Upload-Links, Webhooks, Health-Checks müssen vom Auth Guard ausgeschlossen bleiben
- **Kein Redirect auf Auth-Routen** — `return_to` niemals auf `/auth/*` setzen

## Schnellcheckliste

- [ ] Env-Variablen konfiguriert und `.env.example` aktualisiert
- [ ] Redirect URI im Admin-Panel von login.onyva.dev eingetragen
- [ ] Login-Route: `state` + PKCE generiert, in Session gespeichert, in Authorize-URL enthalten
- [ ] Callback-Route: `state` validiert, Token-Tausch, Claims in Session
- [ ] Logout-Route: lokale Session gelöscht, Weiterleitung zu zentralem Logout
- [ ] Auth Guard für geschützte Routen
- [ ] Öffentliche Routen explizit ausgenommen
- [ ] `AUTH_ENABLED=false` Bypass für Entwicklung
- [ ] `auth_disabled=1` Callback-Fall abgedeckt