Kairo-Jinkendo/docs/reference/design-principles/shinkan/AUTH_SESSION_DESIGN_PRINCIPLES.md

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 (#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
• Mitai: AUTH_SESSION_DESIGN_PRINCIPLES.md
• DESIGN_PRINCIPLES_INDEX.md