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

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

Status: abgeschlossen
Stand: 2026-07-04 (final)
Branch: develop · Prod-Deploy auf main erfolgt und stabil

---

1. Scope und Einordnung

AP0.2 liefert die Auth-, Identity-, Tenant- und Actor-Grundlage für Kairo. Gegenüber dem ursprünglichen Foundation-Dokument (Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md) wurde der für AP0.3 vorgesehene Auth-/TenantContext-Teil bereits in AP0.2 umgesetzt.

Anforderung (AP0.2 / erweitert)	Status
Tenant, User, Membership	✓
Actor (human, agent, working_group, external_system)	✓
Server-Sessions, Login/Logout	✓
TenantContext + Tenant-Wechsel	✓
Portal-Rolle vs. Tenant-Rolle getrennt	✓
Seed für Admin (Env + Erstregistrierung + Dev-Seed)	✓
Audit bei Auth-Aktionen	✓
Frontend Login/Register (minimal)	✓
Idempotentes Data-Seed-System	✓ (Erweiterung)

Bewusst nicht in AP0.2: Capabilities/Rights Registry, Rate-Limiting, Tenant-Admin-API, Passwort-Reset.

---

2. Umgesetzte Artefakte

Backend – Schema & Migrationen

Datei	Zweck
backend/migrations/002_auth_identity_tenant_actor.sql	User, Session, Tenant, Membership, Actor, Audit
backend/migrations/003_data_seeds_tracking.sql	Tabelle data_seeds für Seed-Tracking
backend/run_migrations.py	Schema-Migrationen (schema_migrations)
backend/run_seeds.py	Data-Seeds (Checksum, Dev-Seeds bei jedem Start)
backend/entrypoint.sh	Migrationen + Seeds vor Uvicorn-Start

Backend – Domäne & Services

Datei	Zweck
backend/auth.py	bcrypt, Sessions, require_auth, require_portal_admin
backend/tenant_context.py	TenantContext, get_tenant_context, require_tenant_context
backend/bootstrap.py	Env-Bootstrap (KAIRO_BOOTSTRAP_*)
backend/services/registration.py	Erstregistrierung, provision_system_admin
backend/services/dev_admin.py	Dev-Admin sicherstellen (nur Nicht-Prod)
backend/services/actors.py	Actor-Erzeugung, Human-Lookup
backend/services/audit.py	Audit-Log

Backend – API

Datei	Zweck
backend/routers/auth.py	Login, Logout, Register, Setup-Status
backend/routers/me.py	/api/me, /api/me/context, Tenant-Wechsel
backend/main.py	Router, Startup (Fallback ohne Entrypoint)

Data-Seeds

Seed	Umgebung	Zweck
seed_001_cleanup_pytest_artifacts.dev.sql	Dev	Entfernt *@example.com, verwaiste Test-Tenants
seed_002_bootstrap_admin.py	Dev + Prod	Admin aus KAIRO_BOOTSTRAP_* wenn DB leer
seed_003_ensure_dev_admin.dev.py	Dev	Stellt lars@stommer.com als Portal-Admin sicher

Doku: docs/MIGRATIONS.md

Frontend

Datei	Zweck
frontend/src/App.jsx	Login/Register-Tabs, Session-Anzeige, Setup-Status
frontend/src/app.css	Auth-UI, Tabs, Hinweise

Tests

Datei	Abdeckung
test_auth.py	Login, Logout, Session, /api/me, Context, Tenant-Wechsel
test_tenant_actor.py	Actor-Typen, Portal- vs. Tenant-Rolle
test_registration.py	Erstregistrierung, Setup-Status
test_seeds.py	Seed-Runner, Cleanup, Dev-Admin
test_migrations.py	Migrationen 001–003, Idempotenz

Infrastruktur & Doku

Datei	Zweck
docker-compose.dev-env.yml, docker-compose.yml	Postgres pro Stack, Bootstrap/Session-Env, Healthcheck
backend/Dockerfile	Entrypoint für Startup-Reihenfolge
.gitea/workflows/deploy-dev.yml	Deploy Dev + Logs bei Fehler
.gitea/workflows/test.yml	pytest + Seed-Cleanup nach CI
README.md, docs/DEPLOYMENT.md	Local Dev, Auth, DB-Volume-Wechsel

Version: APP_VERSION = 0.2.0-ap0.2, DB_SCHEMA_VERSION = 003

---

3. Datenmodell (Migration 002)

• users — E-Mail, bcrypt-Hash, portal_role (user | admin)
• sessions — opaque Token, user_id, active_tenant_id, Ablauf
• tenants — Slug (unique), Name, aktiv
• tenant_memberships — tenant_role (owner | admin | member)
• actors — human, agent, working_group, external_system; Human verknüpft mit user_id
• audit_log — Auth-Ereignisse (JSONB-Details)

---

4. API-Endpunkte

Endpoint	Methode	Auth	Beschreibung
/api/auth/setup-status	GET	—	registration_open, has_users, user_count
/api/auth/register	POST	—	Erster User → Portal-Admin (nur leere DB)
/api/auth/login	POST	—	E-Mail + Passwort → Session-Token
/api/auth/logout	POST	X-Auth-Token	Session löschen
/api/me	GET	X-Auth-Token	User + Tenant-Liste
/api/me/context	GET	X-Auth-Token	TenantContext (Tenant + Human Actor)
/api/me/context/required	GET	X-Auth-Token	Wie Context, 403 ohne aktiven Tenant
/api/me/tenant	POST	X-Auth-Token	Aktiven Tenant wechseln (nur Memberships)

OpenAPI (Dev): /api/docs

---

5. Auth-Fluss

POST /api/auth/login { email, password }
  → bcrypt verify
  → INSERT sessions (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 (user_id aus DB, nie aus Client-Body)

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

Ersteinrichtung (Priorität):

1. Dev: Seed seed_003 — lars@stommer.com (Portal-Admin, bei jedem Start)
2. Prod/Dev: Seed seed_002 — KAIRO_BOOTSTRAP_* wenn DB leer
3. UI: POST /api/auth/register — nur wenn user_count == 0

---

6. TenantContext

require_auth → session (user_id, active_tenant_id, portal_role)
  → tenant_memberships + tenants (nur aktiv)
  → human actor: actors WHERE tenant_id + user_id + type = human
  → TenantContext(portal_role, tenant_role, tenant, actor)

Tenant-Wechsel: POST /api/me/tenant { tenant_id } — nur bei gültiger Membership.

---

7. Deployment & Betrieb

	Development	Production
Verzeichnis	/home/lars/docker/kairo-dev	/home/lars/docker/kairo
Ports	3097 / 8097	3004 / 8004
Postgres	Eigener Container + Volume pro Stack	Eigener Container + Volume
Dev-Seeds	Ja (Cleanup + Dev-Admin)	Nein (.dev.* übersprungen)
Admin-Zugang	lars@stommer.com (Seed)	KAIRO_BOOTSTRAP_* in .env

Startup-Reihenfolge: Entrypoint → Schema-Migrationen → Data-Seeds → Uvicorn.

DB-Zugangsdaten ändern: Volume neu anlegen (docker compose down -v) — siehe docs/DEPLOYMENT.md.

Verifikation (2026-07-04): Dev und Prod stabil nach Deploy; Dev-DB-Wechsel mit frischem Volume erfolgreich.

---

8. Tests & CI

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

Bereich	Status
pytest-backend (Dev/Prod im Container)	✓
compose-smoke (PR, isolierte Ports)	✓
k6 Health-Baseline	✓
Playwright smoke	✓
Seed-Cleanup nach pytest (Dev)	✓

Hinweis Betrieb: pytest gegen deployte Instanz erzeugt *@example.com-User. Dev-Seed räumt auf; auf Prod bleiben Test-User bestehen (Cleanup-Seed läuft dort nicht). Prod-DB bei Bedarf manuell prüfen.

---

9. Abweichungen von Designprinzipien

Thema	Kairo AP0.2	Begründung
Mitai profiles	users + separate actors	User ≠ Actor, kein Multi-Profil-Legacy
Passwort-Hash	nur bcrypt	Grüne Wiese
Query-Token / SSE	nicht implementiert	Später
Capabilities in TenantContext	fehlen	AP0.3
Zentrale Postgres-Instanz	je Stack eigener Container	Isolation wie Shinkan/Mitai

Eingehalten: Server-Sessions, X-Auth-Token, Depends(require_auth), Portal- vs. Tenant-Rolle, TenantContext-Schicht, nummerierte Migrationen.

---

10. Offene Punkte (nach AP0.2)

1. Rate-Limiting / Passwort-Policy für Login
2. Passwort-Reset + Session-Invalidierung
3. Tenant-/User-Verwaltung per API (Admin-Routen)
4. Prod-pytest-Cleanup — optional Seed für *@example.com auch in Prod
5. Frontend — produktive Shell statt Debug-JSON (UX, AP0.3+)

---

11. Empfehlung AP0.3

Gemäß Foundation-Dokument:

• Capability / Rights Registry (DB + Runtime-Sync)
• require_capability() als FastAPI-Dependency
• TenantContext um capabilities: list[str] erweitern
• Keine Feature-Limits / Billing in Sprint 0

---

12. Referenzen

• Assignment-Kontext: docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md § AP0.2
• Vorgänger: docs/sprints/Sprint0_AP0_1_Completion_Report_v0.1.md
• Migrationen/Seeds: docs/MIGRATIONS.md
• Deployment: docs/DEPLOYMENT.md

---

Abgeschlossen im Rahmen Sprint 0 – AP0.2. Ersetzt Sprint0_AP0_2_Completion_Report_v0.1.md.