Kansho/docs/architecture/technical/auth_identity_and_roles.md

title	version	status	date	product_family	document_role	parent_document
Kanshō – Auth, Identität und Rollen	0.1	Arbeitsstand	2026-08-19	Jinkendo	Technical Chapter / Auth / Identity / Roles	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