Kairo-Jinkendo/docs/sprints/Sprint0_AP0_2_Completion_Report_v0.1.md

AP0.2 – Abschlussbericht Auth, Identity, Tenant & Actor Foundation

Status: abgeschlossen (Implementierung)
Stand: 2026-07-04
Branch: develop (noch nicht auf main gemergt)

---

1. Umgesetzte Dateien

Datei	Zweck
backend/migrations/002_auth_identity_tenant_actor.sql	Schema User, Session, Tenant, Membership, Actor, Audit
backend/auth.py	bcrypt, Sessions, login/logout, require_auth, require_portal_admin
backend/tenant_context.py	TenantContext, get_tenant_context, require_tenant_context
backend/bootstrap.py	Env-basierter Admin/Tenant/ Actor-Seed
backend/services/audit.py	Audit-Log für Auth-Aktionen
backend/services/actors.py	Actor-Erzeugung + Human-Lookup
backend/routers/auth.py	Login/Logout
backend/routers/me.py	/api/me, /api/me/context, Tenant-Wechsel
backend/main.py	Router, Bootstrap nach Migrationen
backend/tests/conftest.py	DB-Fixtures
backend/tests/factories.py	Testdaten
backend/tests/test_auth.py	Login, Logout, Session, Context
backend/tests/test_tenant_actor.py	Actor-Typen, Rollen-Trennung
backend/version.py	0.2.0-ap0.2, Schema 002
docker-compose.dev-env.yml, docker-compose.yml	Bootstrap/Session-Env
.env.example, README.md	Doku

---

2. Neue Migrationen

• 002_auth_identity_tenant_actor.sql
  • users — E-Mail, bcrypt-Hash, portal_role (user | admin)
  • sessions — Token, user_id, active_tenant_id, Ablauf
  • tenants — Slug, Name, aktiv
  • tenant_memberships — tenant_role (owner | admin | member)
  • actors — human, agent, working_group, external_system
  • audit_log — Auth-Ereignisse

---

3. Neue Endpoints

Endpoint	Methode	Auth
/api/auth/login	POST	—
/api/auth/logout	POST	X-Auth-Token
/api/me	GET	X-Auth-Token
/api/me/context	GET	X-Auth-Token
/api/me/context/required	GET	X-Auth-Token + aktiver Tenant
/api/me/tenant	POST	X-Auth-Token

OpenAPI: /api/docs (Dev)

---

4. Auth-Fluss

POST /api/auth/login { email, password }
  → bcrypt verify
  → INSERT sessions (opaque token, expires_at, active_tenant_id = erste Membership)
  → audit: auth.login
  → Response: { token, expires_at, user }

Request mit Header X-Auth-Token
  → get_session(token) JOIN users
  → require_auth → session dict (user_id aus DB, nie aus Client-Header)

POST /api/auth/logout
  → DELETE session
  → audit: auth.logout

---

5. TenantContext-Auflösung

require_auth → session (user_id, active_tenant_id, portal_role, …)
  → tenant_memberships + tenants prüfen (nur aktive)
  → human actor: actors WHERE tenant_id + user_id + type=human
  → TenantContext(
       portal_role,          # Plattform
       tenant_role,          # Mandant
       tenant_id/slug/name,
       actor_id/type
     )

Tenant-Wechsel: POST /api/me/tenant aktualisiert sessions.active_tenant_id nur bei gültiger Membership.

---

6. Tests und Testergebnis

Testdatei	Abdeckung
test_auth.py	Login, Logout, Session ungültig, /api/me, Context, Tenant-Wechsel verweigert
test_tenant_actor.py	Human↔User, Agent/WG/External ohne User, Portal- vs. Tenant-Rolle
test_migrations.py	Migration 002 erkannt + idempotent

Lokal ausführen (Backend-Container):

docker compose -f docker-compose.dev-env.yml exec backend pip install -r requirements-dev.txt
docker compose -f docker-compose.dev-env.yml exec backend python -m pytest tests -ra -vv

(In dieser Session kein Docker lokal — Verifikation über CI nach Push auf develop.)

---

7. Abweichungen von den Designprinzipien

Prinzip	Abweichung	Begründung
Mitai profiles	Kairo nutzt users	Klarere Trennung User ≠ Actor; kein Multi-Profil-Legacy
Legacy SHA256-Upgrade	nur bcrypt	Grüne Wiese AP0.2
require_auth_flexible (Query-Token)	nicht implementiert	Nicht AP0.2-Scope; SSE/Download später
Account-Lifecycle-Gates	fehlen	AP0.3+
Capabilities in TenantContext	leer / nicht modelliert	Bewusst Nicht-Scope

Eingehalten: Server-Sessions, X-Auth-Token, Depends(require_auth) separat, user_id aus Session, Portal- vs. Tenant-Rolle getrennt, TenantContext als eigene Schicht.

---

8. Offene Entscheidungen

1. Passwort-Policy / Rate-Limiting für Login — noch nicht implementiert.
2. Session-Invalidierung bei Passwort-Reset (Feature kommt später).
3. Tenant-Erstellung via API — aktuell nur Bootstrap/DB; Admin-API in späterem AP.
4. Frontend Auth-UI — AP0.2 backend-only; SPA-Anbindung folgt.
5. Prod-Bootstrap — KAIRO_BOOTSTRAP_* in Prod .env setzen oder einmalig manuell seeden.

---

9. Empfehlung für AP0.3

Laut Foundation-Dokument ursprünglich „Capabilities & Rights Registry“ — der User-Auftrag kombinierte Auth+Tenant bereits in AP0.2.

AP0.3 Vorschlag:

• Capability/Rights Registry (DB + Sync)
• require_capability() Dependency
• TenantContext um capabilities: list[str] erweitern
• Keine Feature-Limits / Billing
• Optional: Frontend Login-Form + Token-Speicherung

---

Erstellt im Rahmen Sprint 0 – AP0.2.