119 lines
5.2 KiB
Markdown
119 lines
5.2 KiB
Markdown
---
|
||
title: "Kanshō – Auth, Identität und Rollen"
|
||
version: "0.1"
|
||
status: "Arbeitsstand"
|
||
date: "2026-08-19"
|
||
product_family: "Jinkendo"
|
||
document_role: "Technical Chapter / Auth / Identity / Roles"
|
||
parent_document: "technische_zielarchitektur.md"
|
||
---
|
||
# Kanshō – Auth, Identität und Rollen
|
||
|
||
Kanonisches Home für Login, Session, Rollen und API-Gates. Fachliche Admin-/Developer-View: `../functional/fachliche_zielarchitektur.md` §2.7. Privacy-Identität: `../functional/guardrails.md`.
|
||
|
||
Mitai-Referenz: `C:\dev\mitai\.claude\docs\jinkendo-foundation\design-principles\AUTH_SESSION_DESIGN_PRINCIPLES.md`, `backend/auth.py`, `frontend/src/context/AuthContext.jsx`.
|
||
|
||
## 1. Fachliche Verantwortung
|
||
|
||
Das Auth-Modul übernimmt:
|
||
|
||
1. Identität (Profil + Passwort).
|
||
2. Session (opaques Token in der Datenbank, Ablauf, Logout).
|
||
3. API-Gates (`require_auth`, `require_admin`).
|
||
4. Passwort-Lifecycle (Hash, Verify, Reset, Registrierung, E-Mail-Verifizierung).
|
||
5. Grobe Rollen: `user` | `admin`.
|
||
|
||
Es übernimmt **nicht**:
|
||
|
||
- Feature-Tiers / Entitlements (eigene Schicht, `platform_extensibility.md` §6).
|
||
- Org-/Vereinsmandanten.
|
||
- OAuth/SSO/JWT (Familien-Vision, nicht Rahmen).
|
||
- Privacy-Pseudonymisierung (→ `privacy_gateway.md`).
|
||
- fachliche Autorisierung auf Reflexionsinhalten jenseits von `profile_id`.
|
||
|
||
Spätere feinere Rollen oder ein Abo ersetzen diese Schicht nicht. Sie hängen **additiv** daran: Session bleibt die Identität, `require_admin` bleibt der grobe Gate, Entitlements bleiben `check_feature_access`. Keine Feature-Limits in `role` und keine Rolle in `tier_id` mischen.
|
||
|
||
## 2. Account-Modell
|
||
|
||
**Status: entschieden**
|
||
|
||
Ein Login (E-Mail) entspricht einem Profil. Kanshō ist keine Multi-Profil-App auf einem Login und keine Vereinsapp.
|
||
|
||
Mehrere Nutzer pro Instanz: ja. Jede Session ist an genau ein `profile_id` gebunden. Alle personenbezogenen Tabellen tragen diese Bindung.
|
||
|
||
Klarnamen, E-Mail und Mapping-Tabellen sind Klasse A (Local Only). Sie verlassen die Trusted Zone nicht als Teil eines External Model Context.
|
||
|
||
## 3. Session-Flow (übernommen)
|
||
|
||
Herkunft: Mitai-Implementierung, als Muster.
|
||
|
||
1. Login mit E-Mail + Passwort, Rate Limit am Login-Endpoint.
|
||
2. Passwortprüfung via bcrypt.
|
||
3. Session-Token (`secrets.token_urlsafe`), Speicherung in `sessions` mit `expires_at`.
|
||
4. Frontend speichert Token lokal und sendet ihn bei API-Calls (Header-Muster Mitai: `X-Auth-Token`).
|
||
5. `require_auth` lädt Session + Profil oder antwortet 401.
|
||
6. Logout invalidiert die Session serverseitig.
|
||
|
||
Session-Dauer: Mitai-Default 30 Tage, profilbezogen konfigurierbar. Für Kanshō **bevorzugte Richtung**, konkreter Default später festzulegen.
|
||
|
||
Registrierung und E-Mail-Verifizierung: Mitai-Muster übernehmen, SMTP-Konfiguration über Server-`.env`.
|
||
|
||
## 4. Rollen
|
||
|
||
| Rolle | Nutzer-PWA | Admin-/Developer View | Status |
|
||
|---|---|---|---|
|
||
| `user` | eigene Reflexionsdaten | nein | entschieden |
|
||
| `admin` | eigenes Nutzerkonto plus Verwaltungs- und Diagnosezugriff | ja | entschieden |
|
||
|
||
Konkretes feineres Rollenmodell (Hauptadmin vs. Entwickler) ist fachlich offen (`produktvision_und_produktidentitaet.md` Entscheidungsstand). Technisch v0.1: zwei Rollen wie Mitai. Weitere Rollen nur nach fachlicher Entscheidung.
|
||
|
||
UI-Guard analog `RequireAdmin.jsx`. Backend-Guard analog `require_admin`. Die UI ist kein Ersatz für den API-Guard.
|
||
|
||
## 5. Bewusst nicht übernehmen (Mitai-Lücke)
|
||
|
||
Mitai dokumentiert eine bekannte Schwäche: ein Profile-Header (`X-Profile-Id`) ohne harte Bindung an die Session ermöglicht IDOR.
|
||
|
||
**Status: verworfen für Kanshō**
|
||
|
||
Regeln:
|
||
|
||
- Die aktive Identität kommt ausschließlich aus der Session.
|
||
- Kein Client-Header darf ein anderes `profile_id` wählen.
|
||
- Jede Query auf personenbezogene Daten filtert mit dem Session-Profil.
|
||
- Tests müssen fremden Ressourcenzugriff ablehnen.
|
||
|
||
Historische Multi-Profil-Endpunkte von Mitai (`/profiles` als Umschalter) werden nicht nachgebaut.
|
||
|
||
## 6. Token-Speicherung im Client
|
||
|
||
Mitai nutzt `localStorage`. Das ist für eine First-Party-PWA akzeptabel, aber XSS-sensitiv.
|
||
|
||
**Status: bevorzugte Richtung** – gleiches Muster wie Mitai für den Rahmen, mit der Maßgabe, später HttpOnly-Cookie vs. localStorage zu bewerten (`security.md`).
|
||
|
||
Keine Secrets, API-Keys oder Identity-Mappings im Frontend-Bundle.
|
||
|
||
## 7. Entscheidungsstand
|
||
|
||
| Thema | Stand | Status |
|
||
|---|---|---|
|
||
| Server-Sessions | opaque Token in DB | entschieden |
|
||
| Rollen | `user` \| `admin` | entschieden |
|
||
| 1 Login = 1 Profil | ja | entschieden |
|
||
| IDOR-Header-Profilwahl | nicht übernehmen | verworfen |
|
||
| JWT/SSO | nicht Rahmen | verworfen für v0.1 |
|
||
| Session-Länge | ~30 Tage | bevorzugte Richtung |
|
||
| Feineres Rollenmodell | später | offen |
|
||
| Token-Ablage Client | localStorage wie Mitai | bevorzugte Richtung |
|
||
|
||
## 8. Offene Fragen
|
||
|
||
1. First-Run-Setup (erster Admin) exakt wie Mitai `SetupScreen`?
|
||
2. Selbst-Registrierung offen oder einladungsgesteuert?
|
||
3. Gemeinsame Jinkendo-Identität später: Migrationspfad von Sessions zu SSO offenhalten, ohne ihn jetzt zu bauen.
|
||
|
||
## 9. Querverweise
|
||
|
||
- Fachlich: `../functional/guardrails.md` §4–5, `../functional/fachliche_zielarchitektur.md` §2.7
|
||
- Technisch: `admin_diagnostics.md`, `security.md`, `privacy_gateway.md`
|
||
- Mitai: `AUTH.md`, `AUTH_SESSION_DESIGN_PRINCIPLES.md`
|