---
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`