115 lines
3.9 KiB
Markdown
115 lines
3.9 KiB
Markdown
|
# Auth & Session – Designprinzipien (Extraktion)
|
|||
|
|
|
|||
|
|
**Status:** Analyse / Arbeitspapier
|
|||
|
|
**Stand:** 2026-07-04
|
|||
|
|
**Geltungsbereich:** Modul „Auth & Session“ — gemeinsame Mitai-Basis in Shinkan
|
|||
|
|
|
|||
|
|
**Serie:** Designprinzipien für Produktfamilie · Shinkan Dokument 4 von 15
|
|||
|
|
**Mitai-Vergleich:** [AUTH_SESSION_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/AUTH_SESSION_DESIGN_PRINCIPLES.md) (#5)
|
|||
|
|
|
|||
|
|
**Kernkomponenten:**
|
|||
|
|
|
|||
|
|
| Bereich | Pfade |
|
|||
|
|
|---------|-------|
|
|||
|
|
| Auth-Kern | `backend/auth.py` |
|
|||
|
|
| Router | `backend/routers/auth.py`, `profiles.py` |
|
|||
|
|
| Frontend | `frontend/src/context/AuthContext.jsx`, `frontend/src/api/client.js` |
|
|||
|
|
| Account-Lifecycle | `backend/account_lifecycle.py` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Modul
|
|||
|
|
|
|||
|
|
**Auth & Session**
|
|||
|
|
|
|||
|
|
Token-basierte Server-Sessions (`sessions`-Tabelle), bcrypt-Passwörter, FastAPI-Dependencies `require_auth` / `require_admin`. Geteilter Code mit Mitai (App-Familie).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Fachliche Verantwortung
|
|||
|
|
|
|||
|
|
1. **Login/Logout/Session-Lebensdauer**
|
|||
|
|
2. **Passwort-Hashing** (bcrypt, Legacy-SHA256-Upgrade)
|
|||
|
|
3. **Auth-Dependencies** für Router
|
|||
|
|
4. **Account-States** (Verifizierung, Onboarding-Gates)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Designprinzipien
|
|||
|
|
|
|||
|
|
### 1. Server-Side Sessions mit Token
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `X-Auth-Token` Header → Lookup in `sessions` mit Ablaufzeit. |
|
|||
|
|
| **Begründung** | Widerrufbar; kein JWT-Drift zwischen Apps. |
|
|||
|
|
| **Quelle** | `auth.py` `get_session`, `require_auth` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** (Familien-Standard) |
|
|||
|
|
| **Einschränkung** | Kein Refresh-Token-Rotation-Modell. |
|
|||
|
|
|
|||
|
|
### 2. `require_auth` als separater Depends-Parameter
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `session: dict = Depends(require_auth)` — nie in Header-Default eingebettet. |
|
|||
|
|
| **Begründung** | Bekannter FastAPI-Footgun führt zu ungeschützten Endpoints. |
|
|||
|
|
| **Quelle** | `CLAUDE.md` Kritische Regeln |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | Code-Review/Lint erzwingt das nicht automatisch. |
|
|||
|
|
|
|||
|
|
### 3. Profile-ID immer aus Session
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `profile_id` aus `session['profile_id']`, nie aus Client-Header als Autorität. |
|
|||
|
|
| **Begründung** | IDOR-Vermeidung. |
|
|||
|
|
| **Quelle** | Architektur-Regeln; Shinkan ergänzt `TenantContext.profile_id` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | Mitai-Dokument nennt Profile-Header-Schwäche — in Shinkan prüfen ob analog. |
|
|||
|
|
|
|||
|
|
### 4. bcrypt für alle Passwort-Operationen
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `hash_pin` / `verify_pin` mit bcrypt; SHA256 nur Legacy-Verify + Upgrade. |
|
|||
|
|
| **Begründung** | Familien-konsistente Kryptografie. |
|
|||
|
|
| **Quelle** | `auth.py` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | — |
|
|||
|
|
|
|||
|
|
### 5. Portal-Rollen vs. Vereinsrollen trennen
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `profiles.role` (admin/superadmin/user) ≠ `club_member_roles` im Verein. |
|
|||
|
|
| **Begründung** | Shinkan-Mandantenmodell; Plattform-Admin ≠ Vereins-Trainer. |
|
|||
|
|
| **Quelle** | `club_tenancy.py`; `TenantContext.global_role` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | UI muss beide Ebenen korrekt anzeigen. |
|
|||
|
|
|
|||
|
|
### 6. Account-Lifecycle als Capability-Voraussetzung
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `min_account_state` auf Capabilities (z. B. verifiziertes Mitglied). |
|
|||
|
|
| **Begründung** | Gates vor sensiblen Aktionen ohne Sonderchecks in Routern. |
|
|||
|
|
| **Quelle** | `account_lifecycle.py`; `capabilities.py` |
|
|||
|
|
| **Tragfähigkeit** | **mittel** |
|
|||
|
|
| **Einschränkung** | Nicht alle Flows nutzen Lifecycle einheitlich. |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Nicht übernehmen
|
|||
|
|
|
|||
|
|
1. **Auth-Parameter in Header-Defaults vermischen** — dokumentierter Anti-Pattern.
|
|||
|
|
2. **Client-gesteuerte `profile_id`** für Autorisierung.
|
|||
|
|
3. **Shinkan-spezifische Mandantenlogik in `auth.py`** — gehört in `tenant_context.py`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Verwandte Dokumentation
|
|||
|
|
|
|||
|
|
- [ACCESS_LAYER_DESIGN_PRINCIPLES.md](./ACCESS_LAYER_DESIGN_PRINCIPLES.md)
|
|||
|
|
- Mitai: [AUTH_SESSION_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/AUTH_SESSION_DESIGN_PRINCIPLES.md)
|
|||
|
|
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)
|