Lars
6c7c24e887
All checks were successful
Deploy Development / deploy (push) Successful in 48s
Test Suite / pytest-backend (push) Successful in 45s
Test Suite / lint-backend (push) Successful in 1s
Test Suite / build-frontend (push) Successful in 15s
Test Suite / k6 /health Baseline (push) Successful in 34s
Test Suite / playwright-tests (push) Successful in 1m35s
Document cross-app architecture patterns, Mitai alignment, and family entitlement standards. Documentation only; no runtime changes. Co-authored-by: Cursor <cursoragent@cursor.com>
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)
|