# Jinkendo – Auth, Session & Scope Blueprint **Phase 3.3 · v0.1 · 16.10.2026 · Grundlage: Application Foundation v0.3** ## 1. Geltung, Ergebnis und Nachweis Dieser Blueprint konkretisiert die beschlossenen Auth-, Identitäts- und Datenraumverträge für die spätere Umsetzung in Phase 3.4. Er verwendet produktlokale Konten, PostgreSQL-Sessions, FastAPI-Abhängigkeiten und zentrale Zugriffsregeln. Es entstehen weder ein neuer zentraler Dienst noch eine gemeinsame Tenant-Fachdatenbank. Bestehende Anwendungen werden durch diesen Auftrag nicht geändert. Maßgeblich sind die [technische Referenzarchitektur v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), der [Foundation-Blueprint v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md) und die [technischen Festlegungen v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md). Dieser Text ergänzt deren Ports; er ersetzt die Foundation nicht. Die vom Auftraggeber beschlossenen ADR-01 bis ADR-14 gelten weiter. Besonders relevant sind ADR-02/03/04/05/06/08/11/12/13/14. Der [Phase-2-Registertext](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md) enthält historische Empfehlungs-/Freigabeformulierungen; daraus wird keine erneute Grundsatzfreigabe abgeleitet. ADR-15/16 werden hier nicht entschieden. **Nachweisstatus:** V = vorgeschlagene technische Ausgestaltung; I = vorhandene, statisch nachgelesene Implementierungsreferenz; T = tatsächlich bestandener Test mit Stand, Umgebung und Umfang; K = noch nicht integrierte oder getestete Kombination. Dieser Blueprint ist **V/K**. Seine Code- und SQL-Ausschnitte sind Spezifikationen, keine ausgeführte Implementierung. Referenzdateien und vorhandene Testassertionen sind I. In dieser Phase wurden keine Anwendungstests ausgeführt; es wird kein T-Nachweis und keine Produktionsreife behauptet. ### 1.1 Verbindliche Verträge und technische Defaults | Verbindlicher Architekturvertrag | Technischer Default dieses Blueprints | |---|---| | Identität ausschließlich aus geprüftem Credential und aktuellem lokalem Konto; keine Clientrolle als Autorität | Opaque Browser-Session, 32 Zufallsbytes, SHA-256-Verifier in PostgreSQL | | Server prüft Ablauf, Widerruf und Kontostatus; MFA-Zwischenzustände öffnen keine Fach-API | 30 Minuten Inaktivität, 12 Stunden absolute Laufzeit, explizite Rotation nach 15 Minuten aktiver Nutzung | | Browser-Cookie HttpOnly/Secure, begrenzte Cookiegeltung und wirksamer CSRF-/Origin-Schutz | `__Host-jinkendo-session`, `Path=/`, kein `Domain`, `SameSite=Lax`; Synchronizer-Token | | Datenraumgrenze, Mitgliedschaft, Capability und Objektregel müssen zusammen erfüllt sein | Explizites Headerpaar `X-Scope-Kind` / `X-Scope-Id`; lokale Registry statt zusätzlichem Policyframework | | Fail closed; Autorisierung und Änderung teilen dieselbe Transaktion; auditpflichtige Änderung samt Audit atomar | Synchrone FastAPI-Services und Psycopg-3-UoW gemäß Foundation | | Privilegierte Betreiberaktionen benötigen MFA, sichere Recovery und Audit | Shinkan-TOTP-Verfahren, Replayzähler, fünf Minuten MFA-Frische, lokal verschlüsseltes Faktor-Secret | | Release-Gate vor Produktion, menschliche Freigabe und eindeutige getestete/ausgelieferte Version | Foundation R1 bevorzugt; kontrollierte getrennte Builds R2 weiterhin zulässig | Zahlen, Dateianordnung und konkrete Bibliotheksadapter sind begründbar anpassbare Ausgangswerte. Schutzwirkungen und veröffentlichte Schnittstellen dürfen dabei nicht stillschweigend entfallen. Anpassung und zugehöriger Testnachweis gehören in den konkreten Produktauftrag; hierfür entsteht kein zusätzlicher ADR- oder Freigabezyklus. `SameSite=None`, ein breites Cookie-Domainattribut oder ein Autorisierungs-Bypass sind keine bloße Timeoutanpassung. ## 2. Gezielte Wiederverwendung und Quellenbasis Ausgangspunkt sind die [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json), das [Quellenregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), das [Testregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl) und die [Guardrailabschnitte](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/guardrails_source_register.jsonl). Nachgelesen wurden die betroffenen Mechanismen und ausgewählte Tests; keine vollständige Repository-Neuanalyse und keine neue Produktreifebewertung. | Referenz / Phase-3.1-Anker | Vorhandener Mechanismus I | Konkrete Übernahme und erforderliche Anpassung V/K | |---|---|---| | Shinkan, KI-SHK-11; [Sessionprüfung](C:/Dev/shinkan-jinkendo/backend/auth.py:74), [Login](C:/Dev/shinkan-jinkendo/backend/routers/auth.py:150) | Kryptografischer Zufall, Sessionzwecke, bcrypt-Prüfung mit Dummyvergleich, begrenzte Sessions, Widerruf | Zustandsablauf übernehmen. Cookie-Transport, gehashte Sessionverifier, Idle-/Absolutfrist, Rotation und eine atomare Abschlussprüfung ergänzen. Aktuelle Header-/Klartextspeicherung nicht kopieren. | | Shinkan, KI-SHK-11; [Kontozustände](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py:26), [Onboardingtests](C:/Dev/shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py:15) | Unbestätigt, bestätigt ohne Verein, aktives Mitglied; eigene Onboardingpfade | Zustände und gezielte Freigaben als lokaler Policyadapter. Fehlender Zustand wird niemals implizit `active_member`; Clubmitgliedschaft wird keine Voraussetzung einer reinen persönlichen App. | | Shinkan, [Tenantauflösung](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:201), [Sichtbarkeit](C:/Dev/shinkan-jinkendo/backend/tenant_context.py:57) | Aktive Mitgliedschaften und zentrale privat/Verein/offiziell-Regeln | Mitgliedschaftsprüfung und gemeinsame Listen-/Objektprädikate übernehmen. `min(club_ids)` und `invalid_header_policy="ignore"` nicht übernehmen. Plattform-Sonderleserechte bleiben eine ausdrücklich produktlokale Regel. | | Shinkan, KI-SHK-03; [Capabilities](C:/Dev/shinkan-jinkendo/backend/capabilities.py:39), [Registry](C:/Dev/shinkan-jinkendo/backend/rights_registry.py:20) | Capabilitydefinitionen, Rollenbezug, Kontostatus und getrennte Features | Kleiner Registrierungstyp und zentrale Entscheidung. Neue Pfade erzwingen immer; kein `CAPABILITY_ENFORCE=0`. Doppelte IDs stoppen den Aufbau; Runtime synchronisiert keine Rechte per DDL/Upsert. | | Shinkan, [TOTP](C:/Dev/shinkan-jinkendo/backend/totp_auth.py:24), [Recoveryverbrauch](C:/Dev/shinkan-jinkendo/backend/routers/auth.py:303) | TOTP-Zeitfenster und bedingtes `UPDATE … used_at IS NULL RETURNING` | Algorithmus und atomaren Einmalverbrauch übernehmen. Akzeptierten TOTP-Zähler zurückgeben und atomar speichern; stärkere Recoverycodes, verschlüsseltes Faktor-Secret und verpflichtende Betreiber-MFA ergänzen. | | Mitai, KI-MIT-04/06; [Auth](C:/Dev/mitai-jinkendo/backend/auth.py:43), [Profilauflösung](C:/Dev/mitai-jinkendo/backend/routers/profiles.py:20) | Konto-/Profilbindung im Sessionjoin; daneben ungeprüfter Profilheader/Erstprofilfallback | Konto=Profil bleibt als Adapter möglich. `get_pid`, allgemeine Profilverwaltung mit bloßem Login und volle Sessions in Medien-/SSE-URLs werden ausdrücklich nicht übernommen. | | Kairo, KI-KAI-03/04/06; [Actor-Token](C:/Dev/kairo-jinkendo/backend/services/actor_service_tokens.py:76), [Operational Auth](C:/Dev/kairo-jinkendo/backend/operational_auth.py:30), [Tenant](C:/Dev/kairo-jinkendo/backend/tenant_context.py:91) | Hashspeicherung, Actor/Tenant-Bindung und getrennte technische Authentifizierung; aktuelle Mitgliedschaftsprüfung | Spätere Machine-Ports an diesem Mechanismus ausrichten. Leere Rechte ergeben keine Standard-Manage-Rechte, Ablauf ist Pflicht, aktuelle Actor-/Delegationspolicy begrenzt den Token. Kein Sessiontoken im RequestContext. | | Kanshō, KI-KAN-03/04; [Auth](C:/Dev/Kansho/backend/auth.py:31), [Journalrouter](C:/Dev/Kansho/backend/routers/journal.py:185), [Ownerfilter](C:/Dev/Kansho/backend/journal_store.py:80), [Spaceprüfung](C:/Dev/Kansho/backend/journal_store.py:124) | Identität aus Session; persönlicher Raum und Objektzugriff über `profile_id`; fremde/unsichtbare Räume verweigert | Ownergebundene Abfragen und Weitergabe des geprüften Profils übernehmen. Reflection Space bleibt fachlicher Unterraum eines persönlichen Zugriffskontexts; sein Name „Beruf“ macht ihn nicht zu einem Organisationsmandanten. | Relevante registrierte Shinkan-Guardrails: `GR-SHK-0015-0063` Portalrollen, `GR-SHK-0015-0072` Vereinsrollen und `GR-SHK-0015-0103` eigene Kontofunktionen/Onboarding. Diese Quellen unterscheiden Zielbeschreibung und Code. Die [Kanshō-Privacy-Invariante](C:/Dev/Kansho/docs/architecture/functional/guardrails.md:81) bleibt erhalten: Identität lokal, externe KI nur über das Privacy Gateway. Eine erfolgreiche Authentifizierung erlaubt keinen direkten Export persönlicher Kontexte an Modelle. Die folgenden Entscheidungen schließen gezielt die Adapterlücken. Es wird kein Produkt vollständig kopiert und kein neuer universeller Sicherheitskern entwickelt. ## 3. Komponenten und Einbindung in die Foundation ```text Browser → Same-Origin-Proxy → FastAPI BrowserBoundary → PrincipalResolver → ScopeResolver → Fachservice/UoW → AccessPolicy → Repository → Audit (dieselbe Transaktion) Auth-Router → SessionService / MfaService → AuthRepository / AccountAdapter → PasswordVerifier / FactorSecretCipher ``` | Komponente / bevorzugter Ort | Verantwortung | Darf nicht | |---|---|---| | `core/context.py`, `core/ports.py` | Unveränderliche Verträge, Ports; keine DB- oder Routerimporte | Passwörter, Cookie-/Bearerwerte oder persönliche Inhalte tragen | | `api/browser_boundary.py` | Cookie-/Headermehrdeutigkeit, Origin, Fetch Metadata, CSRF-Transport, Content-Type | Mitgliedschaft durch einen Header behaupten | | `modules/auth/router.py`, `schemas.py` | Explizite DTOs und Cookieausgabe erst nach Servicecommit | In Dependencies per `yield` nachträglich committen | | `modules/auth/service.py`, `repository.py` | Login, Sessionzustand, Rotation, Widerruf, begrenzte Authflows | Fehlversuchszähler durch anschließendes Exception-Rollback verlieren | | `modules/auth/mfa.py`, `credentials.py` | Shinkan-TOTP, Replay-/Recoveryprüfung, bcrypt, lokale Secretverschlüsselung | Eigene Verschlüsselung oder einen „Admin ohne MFA“-Runtimepfad ergänzen | | `modules/access/scope.py`, `policy.py`, `registry.py` | Lokale Konto-/Scope-/Rollen-/Objektregeln; gemeinsame Sichtbarkeitsprädikate | Universelle Tenant-Fachdatenbank oder generischen ACL-Editor auf Vorrat bauen | | `api/dependencies.py` | Ports aus `app.state.providers` beziehen, Context konstruieren | Globale mutable Profil-ID, DB-Verbindung oder Allow-all-Fallback halten | | Produktadapter | Bestehende Konto-, Profil-, Mitgliedschafts- und Objektmodelle abbilden | Andere Repositories zur Laufzeit importieren | | Frontend `shared/session`, `shared/api` | Session-/Scopezustand, CSRF im Speicher, epoch/Abort, ein Transportclient | Sessioncredential in Web Storage oder einen API-/KI-Cache schreiben | `create_app(settings, providers)` registriert explizit Browserboundary, Problemhandler und Router. `bootstrap` verdrahtet echte Adapter. Import bleibt ohne DB-/Netzkontakt möglich. Fehlende Pflichtadapter verhindern Readiness und lassen geschützte Pfade mit 503 geschlossen; kein Testfake in Runtime. Ein persönliches Produkt benötigt keinen Organisationsadapter: nicht registrierte Scopearten werden verweigert. `BrowserBoundary` bietet `require_request(request)` für Host/Origin/Customheader/Content-Type und `require_session_csrf(request, principal)` bzw. `require_flow_csrf(request, flow)` für unsichere Methoden. Die jeweilige Route hat genau einen Credentialzweck; diese Methoden versuchen keinen alternativen Authtransport. Sichere Reads prüfen keinen CSRF-Wert. Login-/MFA-Flows nutzen eigene Dependencies statt der folgenden Sessiondependency. Die Foundation-UoW liefert eine begrenzte Psycopg-3-Verbindung. Repository und Policy erhalten genau dieses `tx`; keine versteckten `get_db()`-Aufrufe. Schema/Seeds laufen über den expliziten Migrationsweg mit anderer DB-Rolle. Rechte-Registrierungen werden bei der Konstruktion unveränderlich; Duplicate-IDs und Routen mit unbekannter Capability sind Aufbaufehler. ## 4. Identitäts- und RequestContext-Vertrag Die folgenden Typen präzisieren die Foundation-Verträge. IDs bleiben außen opaque Strings; bestehende numerische Profil-/Club-IDs können Adapter kanonisch als String abbilden. Keine zufällige Gleichsetzung von IDs verschiedener Produkte. ```python from dataclasses import dataclass from datetime import datetime from typing import Literal, Protocol from fastapi import Request ScopeKind = Literal["personal", "club", "organization"] @dataclass(frozen=True, slots=True) class ScopeRef: kind: ScopeKind scope_id: str @dataclass(frozen=True, slots=True) class ScopeSelection: kind: ScopeKind scope_id: str @dataclass(frozen=True, slots=True) class Principal: kind: Literal["human", "machine"] subject_id: str actor_id: str | None credential_id: str # interne Session-/Credential-ID, kein Secret credential_generation: int auth_time: datetime mfa_verified_at: datetime | None session_mode: Literal["full", "onboarding", "machine"] @dataclass(frozen=True, slots=True) class RequestContext: request_id: str principal: Principal scope: ScopeRef | None # None nur für explizit scopefreie Operationen @dataclass(frozen=True, slots=True) class ResourceRef: kind: str # registrierter Objekttyp resource_id: str class Tx(Protocol): """Foundation-Transaktionshandle; SQL nur in Repositoryadaptern.""" class PrincipalResolver(Protocol): def resolve(self, request: Request) -> Principal: ... class ScopeResolver(Protocol): def resolve(self, principal: Principal, selection: ScopeSelection) -> ScopeRef: ... def require_current(self, context: RequestContext, tx: Tx) -> None: ... class AccessPolicy(Protocol): def require(self, context: RequestContext, capability: str, resource: ResourceRef | None, tx: Tx) -> None: ... ``` Die Resolver führen kurze lokale Lese-/Sessionaktivitätstransaktionen aus und schließen sie vor dem Fachservice. Der Context ist deren verifizierter Snapshot, **keine dauerhaft gültige Berechtigung**. `AccessPolicy.require` prüft im Fachservice erneut Credential, Generation, Konto, Scope und Rechte mit demselben `tx` wie der Objektzugriff. Erst diese Prüfung autorisiert die konkrete Operation. Rollen und Capabilities werden aus aktuellem serverseitigem Zustand geladen; UI-Capabilitylisten sind reine Darstellungshilfen. Für Menschen gilt `actor_id=None`, sofern das Produkt keinen echten Human-Actor benötigt. Für Maschinen ist `subject_id` die lokale technische Identität und `actor_id` erforderlich; kein erfundenes Benutzerkonto. Browser-MFA-Zwischenflows erzeugen überhaupt keinen Principal. `request_id` stammt aus dem Foundation-Vertrag; beliebige Clientstrings werden nicht unvalidiert geloggt. ### 4.1 FastAPI-Anschluss des geschützten Fachpfads Illustration V/K für `api/dependencies.py` und einen Fachrouter. Die hier verwendeten Adaptermethoden werden in Abschnitt 3/6/9 beschrieben; `scope_selection_from_headers` validiert das strikte Headerpaar und liefert eine `ScopeSelection`. Der RequestContext enthält keine Connection; der Service öffnet seine eigene UoW und wiederholt dort die aktuelle Accessprüfung. ```python from typing import Annotated from fastapi import APIRouter, Depends, Request from pydantic import BaseModel, ConfigDict, Field from app.core.context import Principal, RequestContext def browser_principal(request: Request) -> Principal: providers = request.app.state.providers providers.browser_boundary.require_request(request) principal = providers.principal_resolver.resolve(request) providers.browser_boundary.require_session_csrf(request, principal) return principal def scoped_context( request: Request, principal: Annotated[Principal, Depends(browser_principal)], ) -> RequestContext: providers = request.app.state.providers selection = providers.scope_selection_from_headers(request.headers) scope = providers.scope_resolver.resolve(principal, selection) return RequestContext(request.state.request_id, principal, scope) class RenameInput(BaseModel): model_config = ConfigDict(extra="forbid", strict=True) title: str = Field(min_length=1, max_length=200) expected_version: int = Field(ge=1) class RecordOutput(BaseModel): id: str title: str version: int router = APIRouter(prefix="/api/v1/personal/records") @router.patch("/{record_id}", response_model=RecordOutput) def rename_record( record_id: str, body: RenameInput, request: Request, context: Annotated[RequestContext, Depends(scoped_context)], ): return request.app.state.providers.record_service.rename_record( context, record_id, body, ) ``` Das Beispiel baut kein neues Fachmodul. Es zeigt die unmittelbar zu verwendende DI-Form. Scopefreie Kontooperationen erhalten eine eigene `account_context`-Dependency mit `scope=None` und fester Self-Policy; dieselbe Funktion darf nicht automatisch scoped Fachrouten versorgen. Responseklassen im späteren Fachmodul werden konsistent benannt; `RecordView` im Servicebeispiel meint dessen explizites Ausgabe-DTO. ### 4.2 Konto- und Profilautorität Der lokale AccountAdapter liefert mindestens `subject_id`, `status`, `security_epoch`, `email_verified`, `password_hash`, `password_revision` und eine explizite Zuordnung zum eigenen Profil sowie zur Betreiberrolle. `status ∈ {enabled, disabled, deleted}`; unbekannt/fehlend verweigert. Passwort oder Faktor-Secret verlassen den Credentialadapter nicht. Für den Neuaufbau ist ein lokales Konto zugleich der Eigentümer des persönlichen Scopes (`scope_id=subject_id`). Mitais Bestandsvariante darf `subject_id=profile_id` abbilden. Ein Produkt mit getrenntem Login-/Personenprofil führt eine eindeutige serverseitige Zuordnung; kein Raten nach E-Mail oder erstem Datensatz. Mehrprofildelegation wird erst mit ausdrücklichem Fachvertrag ergänzt. `email_verified` und aktive Clubmitgliedschaft sind zusätzliche Policybedingungen. Shinkans `unverified → verified_pending_club → active_member` bleibt im Clubadapter. Ein aktiver Club in A gibt keine Berechtigung in B. Ein persönliches Produkt darf nach seiner expliziten Accountpolicy `active_personal` verwenden. Unbekannte Zustände oder fehlende Policydefinitionen ergeben keine aktive Mitgliedschaft. Die Plattformrolle ersetzt weder die Kontosperre noch die Verifikation einer persönlichen Eigentümerschaft. Unbestätigte Konten dürfen eine Session im Modus `onboarding` erhalten. Deren feste Allowlist umfasst nur Sessionanzeige, Logout, eigenen Kontostatus, Passwortänderung sowie tatsächlich registrierte Verifikations-/Beitrittsfunktionen. Fach-API, Export, persönliche KI und Organisationsdaten bleiben geschlossen. Nach Freigabe wird der Modus serverseitig bei Rotation neu bestimmt; der Client kann ihn nicht wählen. ## 5. Lokale Datenstrukturen und Invarianten Die Strukturen sind ein Schemaauftrag für den später ausdrücklich benannten Zielaufbau. Bestehende Produkte bleiben unverändert. Vorhandene äquivalente Kontotabellen werden über Adapter genutzt; keine doppelte Identitätsquelle. Die nachfolgenden Tabellen gehören zur jeweiligen Produktdatenbank und enthalten keine familienweiten Fachdaten. ### 5.1 Kontodatensatz und Session Neue lokale `auth_accounts`: `id UUID PK`, `email_norm TEXT UNIQUE NOT NULL`, `password_hash TEXT NOT NULL`, `password_revision BIGINT NOT NULL DEFAULT 1`, `status TEXT NOT NULL CHECK IN ('enabled','disabled','deleted')`, `email_verified BOOLEAN NOT NULL DEFAULT false`, `security_epoch BIGINT NOT NULL DEFAULT 1`, `platform_role TEXT NOT NULL DEFAULT 'user' CHECK IN ('user','operator')`, `created_at/updated_at TIMESTAMPTZ NOT NULL`. Ein Anzeigename ist ein explizites eigenes DTO-Feld, keine Identitätsautorität. Bei Profiladapter ersetzt dessen Tabelle diesen Datensatz; Fremdschlüssel werden entsprechend lokal angepasst. Konkrete Sessionstruktur für diesen Neuanlagenfall: ```sql CREATE TABLE auth_sessions ( id UUID PRIMARY KEY, subject_id UUID NOT NULL REFERENCES auth_accounts(id), token_hash BYTEA NOT NULL UNIQUE CHECK (octet_length(token_hash) = 32), generation BIGINT NOT NULL DEFAULT 1 CHECK (generation > 0), account_epoch BIGINT NOT NULL, mode TEXT NOT NULL CHECK (mode IN ('full', 'onboarding')), csrf_secret TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL, auth_time TIMESTAMPTZ NOT NULL, last_seen_at TIMESTAMPTZ NOT NULL, rotated_at TIMESTAMPTZ NOT NULL, idle_expires_at TIMESTAMPTZ NOT NULL, absolute_expires_at TIMESTAMPTZ NOT NULL, mfa_verified_at TIMESTAMPTZ, mfa_method TEXT CHECK (mfa_method IN ('totp', 'recovery')), mfa_failed_attempts INTEGER NOT NULL DEFAULT 0, revoked_at TIMESTAMPTZ, CHECK (idle_expires_at <= absolute_expires_at), CHECK (mfa_failed_attempts >= 0), CHECK ((mfa_verified_at IS NULL) = (mfa_method IS NULL)), CHECK (absolute_expires_at > created_at) ); CREATE INDEX auth_sessions_subject_idx ON auth_sessions(subject_id); ``` Cookieinhalt: `secrets.token_urlsafe(32)`, kanonisch 43 ASCII-Zeichen. DB-`token_hash`: `sha256(raw.encode('ascii')).digest()`. Nur diese zufälligen hochentropischen Secrets werden mit einem schnellen Hash verifiziert; Passwörter verwenden weiterhin bcrypt. Eine vollständig kompromittierte schreibbare Datenbank ist dadurch nicht abgesichert. Die Hashspeicherung begrenzt die Wiederverwendung bei bloßem Auslesen des Sessionspeichers. [Begrenzte externe Gegenprüfung: OWASP Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#server-side-session-token-storage). `csrf_secret` sind unabhängige 32 Zufallsbytes in URL-safe-Darstellung. Es darf serverseitig wieder auslesbar gespeichert werden, weil es ohne Sessioncookie keine Authentifizierung ermöglicht. Es gehört trotzdem weder in Logs noch in Fach-DTOs. Kein Sessiontoken im DB-Klartext, Response-JSON, RequestContext, Audit oder Browser-Web-Storage. Alle Zeitpunkte sind UTC; Ablaufentscheidungen nutzen die DB-Uhr, keine Clientzeit. ### 5.2 Zweckgebundene Authflows Separate Tabelle `auth_flows` mit `id UUID PK`, `token_hash BYTEA UNIQUE NOT NULL` (32 Bytes), `csrf_secret TEXT NOT NULL`, `purpose ∈ {login_prepare,mfa_login,mfa_enroll}`, `subject_id UUID NULL FK`, `account_epoch BIGINT NULL`, `password_revision BIGINT NULL`, `password_verified_at TIMESTAMPTZ NULL`, `failed_attempts INTEGER NOT NULL DEFAULT 0`, `expires_at TIMESTAMPTZ NOT NULL`, `consumed_at TIMESTAMPTZ NULL`, `initiating_session_id UUID NULL FK auth_sessions(id)`, `pending_factor_ciphertext TEXT NULL`, `factor_key_id TEXT NULL`. Bei `login_prepare` ist kein Subject gebunden; bei MFA-Zwecken sind Subject, Epoch, Passwortrevision und Prüfzeit Pflicht. DB-Checks erzwingen diese Zuordnung. Ein Pending-Secret existiert nur bei `mfa_enroll`. Das Flowcredential lebt in `__Host-jinkendo-preauth`, ebenfalls nur als Hash gespeichert. Es kann niemals über `PrincipalResolver` eine Session ersetzen. Endpunkte erlauben jeweils genau die in Abschnitt 8/11 genannten Zwecke. Ablauf: Loginvorbereitung 10 Minuten, MFA-Login 5 Minuten, erste MFA-Einrichtung 10 Minuten, jeweils ohne Verlängerung durch Fehlversuche. Übergänge ersetzen Flowtoken und CSRF; alte Flows werden atomar verbraucht. Verifikations-/Passwortresettokens erhalten bei späterem Bedarf eigene Zwecke und Resolver, niemals den Sessionresolver. ### 5.3 MFA, Fehlversuche und Widerruf `auth_mfa_factors`: `subject_id UUID PK/FK`, `secret_ciphertext TEXT NOT NULL`, `key_id TEXT NOT NULL`, `enabled_at TIMESTAMPTZ NOT NULL`, `last_accepted_counter BIGINT NOT NULL DEFAULT -1`. `auth_recovery_codes`: `id UUID PK`, `subject_id UUID FK NOT NULL`, `code_hash BYTEA UNIQUE NOT NULL`, `created_at TIMESTAMPTZ NOT NULL`, `used_at TIMESTAMPTZ NULL`. Pro Ausgabe acht unabhängige Codes aus je 16 Zufallsbytes; Anzeige einmalig in lesbaren Hexgruppen, normalisiert nur definierte Bindestriche entfernen und ASCII-Hex kleinschreiben. Keine freie Entfernung beliebiger Zeichen. SHA-256 über den normalisierten hochentropischen Code; kein vier Byte langes Shinkan-Original übernehmen. Gemeinsame lokale Tabelle `auth_attempt_windows`: `bucket_key BYTEA`, `bucket_kind TEXT`, `window_start TIMESTAMPTZ`, `attempts INTEGER`, PK über die ersten drei Felder. Schlüssel aus HMAC-SHA-256 mit eigenem lokal bereitgestellten `AUTH_RATE_KEY`; keine E-Mail im Bucketschlüssel oder Log. Zwei unabhängige Buckets je Versuch: normalisierte Loginadresse und vertrauenswürdig ermittelte Quell-IP. Fehlende IP verwendet einen gemeinsamen begrenzten Bucket. `window_start` ist der Beginn eines festen 15-Minuten-UTC-Fensters aus der DB-Uhr. Zähler werden atomar per Upsert erhöht und der zurückgegebene Wert gegen das Limit geprüft; auch eine limitüberschreitende Verweigerung wird committed. Alle Worker verwenden dieselbe Produkt-DB, kein Redisdienst nötig. Defaults: 8 Anmeldeversuche/Loginadresse/15 Minuten, 30 Anmeldeversuche/IP/15 Minuten; begrenzte Fenster statt dauerhafter Kontosperre. Unbekannte Adressen erhalten denselben Kontobucket. Jeder Versuch reserviert vor Passwortprüfung atomar je einen Budgetplatz; auch Erfolge setzen das Fenster nicht zurück. Die beiden Buckets werden in sortierter Reihenfolge unter derselben kurzen Transaktion aktualisiert; bei Überschreitung bleibt die Verweigerung wirksam. Loginprepare ebenfalls IP-begrenzt (30/15 Minuten). MFA-Flow maximal fünf Fehlversuche; zusätzlich Konto-/IP-Buckets über mehrere neue Flows hinweg. Details der Fenster sind Defaults, wirksame Begrenzung und persistenter Fehlversuch sind Pflicht. Sessionablauf ist unabhängig vom Aufräumen. Lokaler Wartungsbefehl entfernt abgelaufene/verbrauchte Flows und alte Buckets; widerrufene Sessions nach dem benötigten kurzen Diagnosefenster. Default: Flows/Buckets spätestens am Folgetag, Sessionmetadaten sieben Tage nach Ablauf/Widerruf; Auditfristen bleiben produktbezogen. Wartung läuft über vorhandene Betriebswege, kein neuer zentraler Scheduler. ## 6. Browsergrenze: Cookie, Origin und CSRF ### 6.1 Cookievertrag Ausgabe erst nach erfolgreichem DB-Commit: ```python response.set_cookie( key="__Host-jinkendo-session", value=issued.raw_cookie, # Secret bleibt nur in diesem internen Ausgabeobjekt httponly=True, secure=True, samesite="lax", path="/", max_age=issued.remaining_absolute_seconds, ) ``` Kein `Domain`, kein JWT-/Rolleninhalt, keine Session in URL. Das Preauth-Cookie nutzt dieselben Attribute mit seiner kürzeren Restlaufzeit. Cookie-Max-Age kann die serverseitige Idlefrist nicht verlängern. Löschen bei erfolgreichem Logout erfolgt mit identischem Namen/Path/SameSite/Secure und `Max-Age=0`. **401-Responses löschen oder überschreiben niemals Cookies:** Eine verspätete Antwort darf eine inzwischen erneuerte Session nicht im Browser entfernen. Neue Apps laufen auch lokal hinter einem HTTPS-Proxy; Tests verwenden eine HTTPS-Basis-URL. Kein `Secure=False`-Produktionsschalter. Mehrere Produkte auf demselben Host benötigen unterschiedliche feste Produkt-Cookienamen und weiterhin Same-Origin-Routing; bevorzugt erhält jede App ihren eigenen Host. Verschiedene localhost-Ports trennen Cookies nicht. Familienweite Domaincookies sind ausdrücklich ausgeschlossen. ### 6.2 Konkrete Requestprüfung Für Browser-JSON-API gilt: 1. `Host` gegen konfigurierte Hostliste prüfen. `PUBLIC_ORIGIN` ist ein explizites Scheme/Host/Port-Tupel ohne Pfad, in Produktion HTTPS. Nicht aus beliebigem `Host` oder `X-Forwarded-Host` rekonstruieren. Forwarded-IP/Proto nur von ausdrücklich konfigurierten Proxyadressen/-netzen; „jede private IP ist vertrauenswürdig“ wird nicht aus Shinkan übernommen. 2. Browser-JSON-Aufrufe verlangen `X-Jinkendo-Client: browser-v1`, auch `/auth/bootstrap` und Sessionanzeige. Kein Cross-Origin-CORS für diese API; insbesondere keine Credentialsfreigabe für fremde Origins und kein `*`. Gleiches Origin im Entwicklungsproxy erhalten. 3. Falls `Sec-Fetch-Site` vorhanden: nur `same-origin` akzeptieren. `same-site` ist für einen fremden Geschwisterhost nicht ausreichend. Fehlt der Header, bleibt die Prüfung aus 2/4/5 erforderlich. 4. Alle unsicheren Methoden (`POST`, `PUT`, `PATCH`, `DELETE`, andere unbekannte Methoden) verlangen `Origin == PUBLIC_ORIGIN`. Falls Origin fehlt, darf ausschließlich ein streng geparstes Referer-Origin exakt passen. `Origin: null`, mehrere/mehrdeutige Werte oder beide Quellen fehlend: 403. Bei vorhandenem Origin gibt es keinen Referer-Fallback bei Abweichung. Für sichere JSON-Reads einen vorhandenen fremden Origin ebenfalls ablehnen. 5. Unsichere Requests verlangen `X-CSRF-Token`, maximal 128 ASCII-Zeichen, konstantzeitlich mit dem **zum verwendeten Credential gehörenden** `csrf_secret` verglichen. Sessionendpunkte verwenden Session-CSRF, Login-/MFA-Flowendpunkte Flow-CSRF. Keine freie Wahl zwischen beiden. 6. JSON-Mutationen akzeptieren nur `application/json` (optionaler Charsetparameter); keine Form-/`text/plain`-Fallbacks. Authbodies maximal 4 KiB. Ein später registrierter Upload prüft Origin/CSRF ebenfalls vor Verarbeitung; Multipart hebt den Schutz nicht auf. `GET /auth/bootstrap` erstellt nur einen begrenzten Voranmeldeflow; es ändert keine Konten oder Fachobjekte und ersetzt keine gültige Session. Ein passender, noch gültiger Preauthflow wird wiederverwendet, damit mehrere Tabs ihn nicht gegenseitig überschreiben. Der Response enthält den Flow-CSRF-Wert im JSON. Ein fremder Browser-Origin kann den benötigten Customheader nicht ohne CORS-Preflight senden und erhält keine CORS-Freigabe. Session-CSRF kommt nur über die geschützte Sessionanzeige an den Same-Origin-Client, bleibt im JS-Speicher und wird bei Rotation neu ausgegeben. Es gibt kein zweites lesbares CSRF-Cookie. Das ist die kleine zustandsbehaftete Synchronizer-Variante, passend zum bereits vorhandenen Sessionspeicher. CSRF wird pro Credentialgeneration erneuert; keine Rotation pro Fachrequest und kein eigenes Signaturprotokoll. Origin und SameSite wirken ergänzend. [Begrenzte Gegenprüfung: OWASP CSRF, Synchronizer-Token und Originprüfung](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html). Bei ungültigem Credential liefert ein geschützter Sessionendpunkt nach der allgemeinen Originprüfung 401; bei gültigem Credential und falschem CSRF 403. DB-/Adapterausfall bleibt 503. Diese Reihenfolge verhindert, dass ein ausgelaufenes Konto nur wegen eines alten CSRF-Werts als weiter angemeldet erscheint. Alle Auth-/persönlichen Responses einschließlich Fehler: `Cache-Control: no-store`, kein CDN-/PWA-Fachdatencache, `Referrer-Policy: no-referrer`. Cookie-, Authorization- und CSRF-Header sowie Passwort-/Codebodies werden am Proxy und in der App redigiert. Same-Origin-SSE/Medien verwenden Cookies ohne volle Session in der URL; fremde Medien benötigen gegebenenfalls separate begrenzte Grants nach ADR-03, kein Sessionalias. Für den ersten Foundation-Slice lädt der zentrale Fetchclient persönliche Bilder/Downloads mit Cookie **und Scopeheadern**; erzeugte Blob-URLs werden bei Scopewechsel/Logout widerrufen. Ein späterer SSE-Client verwendet bei diesem Scopevertrag `fetch`/ReadableStream statt eines nativen EventSource-Aufrufs ohne Scopeheader. Native Medien-/Rangeadapter dürfen erst bei konkretem Bedarf eine ausdrücklich validierte Scopehint-Variante erhalten; ein Objektpfad oder URLhint ist weiterhin keine Autorität. Es gibt keine pauschale CSRF-/Scopeausnahme für alle Medienrouten. ## 7. Sessionablauf, Erneuerung und Logout ### 7.1 Sessionzustände und Gültigkeit Eine Session ist nur gültig, wenn gleichzeitig gilt: ```text Hash des einen korrekt geformten Sessioncookies findet genau eine Zeile AND revoked_at IS NULL AND DB-Zeit < idle_expires_at AND DB-Zeit < absolute_expires_at AND Account existiert, status = enabled AND session.account_epoch = account.security_epoch AND Sessionmodus ist bekannt und für die Operation zugelassen ``` Gleichheit mit einer Ablaufgrenze bedeutet bereits abgelaufen. Fehlende Spalte, unbekannter Zweck, gelöschtes Profil oder inkonsistente Zuordnung wird nicht durch Defaults geheilt. Für Fachoperationen wiederholt die Policy diese Prüfung einschließlich `credential_generation`. Rollen werden nicht für zwölf Stunden in der Session eingefroren. Sessionanzeige, Readiness und automatische Erneuerungsversuche zählen nicht als Aktivität. Ein erfolgreich authentifizierter Fachrequest oder ausdrücklich ausgeführter Scopewechsel aktualisiert in einer kurzen Transaktion `last_seen_at` und `idle_expires_at=min(DB-Zeit+30 Minuten, absolute_expires_at)`. Die bestehende Frist wird zuvor unter Zeilensperre geprüft; abgelaufene Sessions können nicht wiederbelebt werden. Auch ein authentifizierter, später fachlich verweigerter Request kann so Aktivität zählen. Das behauptet keine Erkennung menschlicher Aktivität; Background-Polling darf deshalb nicht als Keepalive für die Session konzipiert werden. Neu erzeugte Session: Idlefrist 30 Minuten, Absolutfrist zwölf Stunden, Generation 1. Mehrere Geräte erhalten getrennte Sessions. Browser schließen ist kein verlässlicher Widerruf. Serverseitiger Ablauf/Widerruf bleibt ausschlaggebend, unabhängig von Cookieanzeige und Frontendtimer. ### 7.2 Login und atomare Erstellung 1. Browser holt Bootstrap, sendet Login mit Flowcookie, Origin, Customheader und Flow-CSRF. 2. Service validiert DTO, IP-/Kontobudget und zweckgebundenen Flow. Loginadresse wird getrimmt und einheitlich kleingeschrieben; keine providerabhängige Punkt-/Plusadressänderung. E-Mail-Validator verweigert Steuerzeichen. Bestehende Normalisierung wird im Produktadapter konsistent gehalten. 3. Credentialadapter liest Kontosnapshot. Passwortvergleich erfolgt mit bcrypt und bei unbekanntem Konto mit einem festen bcrypt-Dummyhash gleicher Kosten. Kein Netzaufruf, keine lang gehaltene Fachtransaktion während des teuren Vergleichs. 4. Abschlusstransaktion sperrt Konto und Flow, prüft erneut Status, `password_revision`, `security_epoch`, Flowzweck und Frist gegen den zuvor geprüften Snapshot. Passwortreset/Sperre zwischen Vergleich und Abschluss verhindert den Login. Fehlversuch und Limits werden **committed**, erst anschließend als 401/429 ausgegeben. Keine Exception innerhalb der UoW, die diese Zähler zurückrollt. 5. Bei aktiviertem Faktor: Preauthflow atomar zu `mfa_login` ersetzen, frisches Flowcookie setzen; noch keine Session. Bei Betreiberkonto ohne eingerichteten Faktor: nur `mfa_enroll` nach geprüftem Passwort. Bei normalem Konto ohne Faktor: passende `full`-/`onboarding`-Session, CSRF und Pflichtaudit in derselben Transaktion anlegen, Vorflow verbrauchen. 6. Response-DTO validieren, committen, dann Cookie setzen und minimales Session-/Flow-DTO zurückgeben. Sessionrawtoken erscheint nie im JSON. Ein bereits angemeldeter Browser muss vor einem Login als andere Person ausloggen; kein stiller Kontowechsel mit persönlichen Altzuständen (409 `already_authenticated`). Passwortadapter verwendet das vorhandene bcrypt-Muster, für neue Hashes Kostenfaktor 12 als Default. Neue Passwörter mindestens 15 Zeichen und höchstens 72 UTF-8-Bytes; kein Abschneiden, Trimmen oder Normalisieren des Passworts. Die Bytegrenze wird vor bcrypt validiert, auch bei Login, und verständlich im UI gezeigt. Ein Reset/Wechsel erfüllt denselben Vertrag. Im Neuaufbau keine SHA-256-Passworthashes. Ein später ausdrücklich beauftragter Bestandsadapter darf vorhandene Legacyhashes gezielt verifizieren und atomar auf bcrypt heben; das wird keine allgemeine Fallbackverifikation beliebiger Hashformate. Unbekannte Adresse, falsches Passwort und gesperrtes/gelöschtes Konto liefern beim Login dieselbe 401-Antwort `invalid_credentials`. Verifikation eines bekannten Kontos wird erst nach korrektem Passwort im eingeschränkten Modus sichtbar. 429 nennt eine begrenzte Wartezeit, keine Kontoexistenz. Fehlversuchszähler, Flow und Faktorprüfung funktionieren workerübergreifend; reine In-Memory-Limiter reichen hierfür nicht. ### 7.3 Erneuerung und Rotation `POST /api/v1/auth/session/renew` verlangt aktuelle Session und Session-CSRF. Unter Konto-/Sessionsperre werden Status, Epoch, Generation und Fristen geprüft; dann `token_hash`, `csrf_secret`, `generation+=1` und `rotated_at` atomar ersetzt. Die logische Session-ID bleibt gleich. Das alte Credential ist nach Commit sofort ungültig; keine akzeptierte Vorgängerversion und kein stiller Grace-Login. Absolute Frist, `auth_time` und `mfa_verified_at` bleiben erhalten. Erneuerung allein verlängert die Idlefrist nicht. Der Modus wird aus aktueller Accountpolicy neu ermittelt, eine Kontosperre oder MFA-Pflicht dabei nicht umgangen. Der Frontendclient rotiert nach 15 Minuten nur, wenn ohnehin eine Nutzeraktion/Fachanfrage ansteht. Aktive Operationen pro Browser werden für Login/Rotation/Step-up/Logout durch einen gleich benannten Web Lock serialisiert. Browser ohne Web Locks verwenden eine gewählte Tabkoordination; bei Konflikt ist erneute Anmeldung der sichere Fallback, keine schwächere Serverregel. Der Server bleibt unabhängig davon korrekt: zwei Erneuerungen mit derselben Generation lassen genau eine gewinnen; die andere erhält 401 ohne Cookieänderung. Inaktive Tabs beziehen über Sessionanzeige den aktuellen CSRF-Wert, bevor sie wieder schreiben. Vor einer eigenen Rotation pausiert der Client neue Fachmutationen und wartet laufende Mutationen ab. Danach erhöht er seine epoch, übernimmt den bestätigten Sessionzustand und invalidiert ausstehende Loader. Normale nicht idempotente Fachwrites werden nach 401, Timeout oder Rotation nie automatisch wiederholt. Bei verlorenem Rotationsresponse darf ein einmaliger sicherer Session-GET klären, ob der Browser bereits das neue Cookie hat. Ist kein gültiges Credential vorhanden, erfolgt Login. Kein „altes Token wieder aktivieren“ zur Komfortrettung. ### 7.4 Logout, globaler Widerruf und Kontoveränderung `POST /auth/logout`: Originprüfung immer; bei gültiger Session zusätzlich deren CSRF. In einer Transaktion Session widerrufen und Audit schreiben; danach Cookie löschen, 204. Bereits fehlende/ungültige Session: nach Origin-/Customheaderprüfung 204 und Cookie löschen, ohne Account-/Scopezustand offenzulegen. Ein noch gültiges Cookie mit falschem CSRF bleibt 403 und wird nicht gelöscht. Eine vor konkurrierender Rotation bereits verifizierte Logoutanfrage darf die logische Session-ID trotz inzwischen höherer Generation widerrufen, wenn ihr ursprünglicher CSRF zur verifizierten Generation passte. Dieser eng begrenzte Widerrufspfad gewährt keine Fachrechte. Kommt ein alter Token erst nach Rotation an, ist er unbekannt; der Client klärt den aktuellen Zustand unter seinem Authlock und wiederholt gegebenenfalls Logout mit aktuellem Cookie/CSRF. Ein verspätet gesetztes Cookie einer bereits widerrufenen Session bleibt serverseitig wirkungslos. Kein Rotationspfad kann eine widerrufene Zeile reaktivieren. `POST /auth/logout-all`: aktuelle Session/CSRF, Konto exklusiv sperren, `security_epoch+=1`, alle Sessions und gebundenen Authflows widerrufen/verbrauchen, Audit atomar. Aktuelles Cookie löschen, 204. Kein MFA-Zwang zum Beenden eigener Sessions. Eine DB-/Auditstörung liefert 503: Das UI darf lokal persönliche Daten leeren, aber keinen bestätigten serverseitigen Widerruf behaupten. Es zeigt den fehlgeschlagenen Logout und ermöglicht Wiederholung. Passwortwechsel/-reset, Kontodeaktivierung/-löschung sowie MFA-Reset/-Deaktivierung erhöhen in derselben Transaktion die Epoch und widerrufen alle Sessions/Flows. Passwortwechsel erhöht zusätzlich `password_revision`. Der Default ist danach erneuter Login, keine verdeckte neue Vollsession. Mitgliedschafts-/Rollenentzug braucht keinen globalen Logout: aktuelle Scope-/Policyprüfungen greifen unmittelbar; eine Betreiberrollenerhöhung widerruft dagegen Sessions und erzwingt vollständigen Login mit MFA. Verifikations- und Onboardingänderungen eröffnen keine Rechte durch einen Clientreload; der Sessionmodus wird bei kontrollierter Rotation aktualisiert. ## 8. API-Vertrag und Fehler Alle Pfade beginnen mit `/api/v1`. Input-DTOs verwenden Pydantic 2 mit `extra='forbid'`, strikte Stringgrenzen und expliziten Ausgabemodellen. Keine Ausgabe ganzer Konto-/Sessionzeilen. `session_id` wird nur bei einem später benötigten Geräteverwaltungsendpunkt angezeigt, nicht als Browsercredential verwendet. | Methode / Authpfad | Input / Credential und CSRF | Erfolgsverhalten | |---|---|---| | `GET /auth/bootstrap` | Browser-Customheader; optional vorhandenes Preauthcookie | 200 `{state, csrf_token, expires_at}`; begrenzten Flow erzeugen oder gültigen wiederverwenden; Preauthcookie. `state`: `login_prepare`, `mfa_login` oder `mfa_enroll`. | | `POST /auth/login` | `{email,password}`; `login_prepare` + Flow-CSRF | 200 `SessionView` und Sessioncookie oder 202 `FlowView` und frisches Preauthcookie; keine Mischantwort mit Volltoken | | `POST /auth/mfa/verify` | `{code, method}`; `mfa_login` + Flow-CSRF; `method=totp|recovery` | 200 `SessionView`; Flow einmalig verbraucht, Sessioncookie, Preauthcookie löschen | | `GET /auth/session` | Sessioncookie, Browser-Customheader | 200 `SessionView`, keine Fristverlängerung, kein `Set-Cookie`; ungültig 401 | | `POST /auth/session/renew` | `{}`; Session + Session-CSRF | 200 neues `SessionView`, rotiertes Cookie | | `POST /auth/logout` | `{}`; Session-CSRF bei gültiger Session | 204 nach serverseitigem Widerruf bzw. bereits fehlender Session | | `POST /auth/logout-all` | `{}`; Session + Session-CSRF | 204; Epoch erhöht, alle Sessions/Flows ungültig | | `GET /auth/scopes` | Session, Browser-Customheader | 200 `{items, next_cursor}` mit ausschließlich aktuell auswählbaren Scopes; kein implizit gewählter Raum | | `POST /auth/session/scope` | `{kind,scope_id}`; Session + Session-CSRF | 200 `{scope:{kind,scope_id}}`; frische Auflösungs-/Policyprüfung und Scopewechsel-Audit; setzt keinen globalen autoritativen Sessiontenant | | `GET /auth/me` | Session; feste Self-Capability, scopefrei | 200 explizites eigenes Kontostatus-DTO; keine beliebige `profile_id` | | `POST /auth/password/change` | `{current_password,new_password}`; Session + Session-CSRF; bei Faktorpflicht frische MFA | 204 nach Vergleich/Revisionsprüfung und atomarem Widerruf aller Sessions; Cookie löschen | MFA-Verwaltungsendpunkte und deren enge Zwecke stehen vollständig in Abschnitt 11. Kein allgemeiner `/profiles/{id}`-AuthCRUD, kein öffentliches Erstadministrations-Signup. Normale Registrierung, Einladungen, Mailversand und Passwortresetversand bleiben konkrete Produktfunktionen; ihre Session-/Widerrufshooks sind hier festgelegt. Eine App ohne diese Funktionen registriert auch keine scheinbar funktionierenden Endpunkte. `SessionView` enthält ausschließlich: ```json { "principal": {"kind": "human", "subject_id": "opaque-local-id"}, "account_state": "active_personal", "session_mode": "full", "auth_time": "2026-10-16T08:00:00Z", "mfa_verified_at": null, "idle_expires_at": "2026-10-16T08:30:00Z", "absolute_expires_at": "2026-10-16T20:00:00Z", "generation": 1, "csrf_token": "opaque-csrf-value" } ``` `FlowView={state,csrf_token,expires_at}` entspricht dem Bootstrapformat. Ein Flowzustand im Response ist kein Principal. `/auth/scopes` listet `ScopeView={kind,scope_id,display_name}`. Ein späteres Fachmodul kann ein separates Capability-DTO für den gewählten Raum anbieten; es ersetzt keine Policyprüfung. | HTTP / stabiler Problemcode | Bedeutung / Clientverhalten | |---|---| | 401 `authentication_required`, `session_invalid` | Kein gültiger Principal; aktueller UI-Kontext wird beendet. Keine automatische Cookieänderung. | | 401 `invalid_credentials`, `challenge_invalid` | Login-/Flowfehler; Loginansicht verarbeitet selbst, kein globaler Logout einer anderen laufenden Session. | | 403 `origin_forbidden`, `csrf_invalid`, `account_not_ready`, `capability_denied`, `scope_forbidden`, `mfa_required` | Request verweigert; ändert keine Identität. Bei `mfa_required` gezielte Step-up-Ansicht. | | 404 `not_found` | Objekt fremd, unsichtbar oder nicht vorhanden; gleiche sichere Antwort. Keine Bestätigung fremder Profile/Räume. | | 409 `already_authenticated`, `version_conflict` | Bewusste Kontowechsel-/Objektversionsentscheidung nötig; kein automatischer Write-Retry. | | 422 `validation_failed`, `scope_required` | DTO/Scopepaar fehlt oder ist syntaktisch falsch. Keine Tokens/Passwörter in `errors`. | | 422 `scope_not_allowed`, `ambiguous_credentials`, `unsupported_auth_header` | Unerwartete Scopeheader bzw. mehrdeutige/nicht unterstützte Authquelle; kein Fallback. | | 403 `browser_header_required`; 413 `payload_too_large`; 415 `unsupported_media_type` | Browserheader fehlt bzw. Body-/Medientypgrenze verletzt; vor Verarbeitung verweigert. | | 429 `auth_rate_limited` | Begrenzter Retry-After; keine Umgehung durch neuen Worker/Flow. | | 503 `auth_unavailable`, `policy_unavailable` | DB, Schlüssel oder Pflichtadapter fehlt/gestört; kein Logout und keine Zugriffserlaubnis daraus ableiten. | RFC-9457-Problemformat gemäß Foundation: `type,title,status,detail,instance,code,request_id`, optional sichere `errors`. `detail` bleibt allgemein; keine fremde ID, SQL-, Faktor-, Provider- oder Secretinformationen. Zunächst syntaktische Browsergrenze/Origin, dann Credential, dann dessen CSRF, dann Konto-/Scope-/Objektpolicy. Unbekannte fremde Objekte werden erst nach Prüfung des aktuellen eigenen Kontextes als 404 behandelt; ein fehlendes eigenes Recht kann vorher 403 ergeben. ## 9. Datenraumauflösung, Rollen und Objektberechtigung ### 9.1 Auswahl ist keine Autorität Fachrouten mit Datenraum verlangen **beide** Header `X-Scope-Kind` und `X-Scope-Id`; Whitelist der registrierten Arten, kanonische begrenzte IDs (maximal 128 Zeichen), keine mehrfachen Headerwerte. Ein fehlendes/halbes/ungültiges Paar: 422. Keine Auswahl bei mehreren Vereinen: 422 `scope_required`; kein erster, kleinster oder zuvor unvalidiert gespeicherter Verein. Scopefreie Kontorouten erzeugen `scope=None` über eine ausdrücklich eigene Dependency und akzeptieren keine scopeabhängigen Fachoperationen. Mitgesendete Scopeheader werden dort mit 422 `scope_not_allowed` verweigert; der Transportclient hängt sie nur an als scoped registrierte Fachaufrufe, nicht pauschal an Authrequests. Ein manipulierter Header darf höchstens einen Auswahlversuch auslösen. Server prüft anhand des Principal: | Scopeart | Verifizierte Bedingung | Bewusst erhaltene Produktvariante | |---|---|---| | `personal` | Scope-ID entspricht dem serverseitig zugeordneten eigenen Profil/Account; Konto nutzbar | Mitai Konto=Profil; Kanshō zusätzliche Reflection-/Journalräume stets darunter mit Ownerfilter | | `club` | Club existiert/aktiv, Mitgliedschaft des Subjects ist aktuell aktiv; Rollen nur aus dieser Mitgliedschaft | Shinkan Club-/Bibliothekssicht und gezieltes Onboarding | | `organization` | Produktorganisation aktiv; aktuelle aktive Mitgliedschaft bzw. ausdrücklich definierte technische Delegation | Kairo-Vertrauensraum kann allen aktiven Mitgliedern tenantweite Lesesicht geben; selektive Beteiligung nur bei realem Fachbedarf | Kairo und Shinkan dürfen vor Scopewahl eigene Konto-/Einrichtungsseiten anzeigen (`scope=None`). Daraus folgt kein Fachzugriff ohne Raum. „Kein Scope“ bedeutet niemals „alle Tenants“. Ein persönliches Produkt kann den einzigen vom Server als **eigenen** gelieferten Personal-Scope im UI vorauswählen; die Fachanfrage trägt ihn dennoch ausdrücklich. Dies ist keine freie Profilwahl und kein SQL-Erstprofilfallback. ### 9.2 Capabilityvertrag Lokale immutable `CapabilityDefinition`: `id`, `module`, `allowed_scope_kinds` (inklusive ausdrücklichem scopefreiem Fall), `mutating`, `allowed_account_states`, `allowed_session_modes`, `requires_mfa`, `max_mfa_age_seconds`, `object_policy`. Nur tatsächlich implementierte Funktionen registrieren. Unknown Capability, fehlender Objekttyp oder nicht registrierte Regel: verweigern; Routenregistrierung mit solcher Lücke stoppt zusätzlich den Appaufbau. Rollen sind Bündel von Capabilities, keine universelle Rangzahl. Portal-/Betreiberrollen und Club-/Organisationsrollen bleiben getrennt. Mehrere Rollen **innerhalb derselben aktiven Mitgliedschaft** können Rechte vereinigen; Rechte aus Club A werden nie in B vereinigt. Die Eigentümerregel ist eine eigene Objektbedingung. Ein Produktfeature/Abonnement wird erst nach Zugriff durch die getrennte Foundation-`EntitlementPolicy` geprüft; ein bezahltes Feature erzeugt kein Leserecht auf fremde Daten. Beispielmatrix für den ersten vertikalen Slice; fachliche Bezeichnungen ersetzt das Zielprodukt durch seine tatsächlichen Funktionen: | Capability | Scope / Objektregel | Serverrechte | |---|---|---| | `account.read_self`, `account.password.change` | Scopefrei, Subject ausschließlich selbst | Eigener bekannter Kontostatus; Passwortänderung mit aktuellem Passwort und ggf. MFA | | `personal.record.read/update` | `personal`, Objekt gehört eigenem Profil | `full`, explizit aktiver persönlicher Kontostatus; Betreiberrolle allein genügt nicht | | `club.library.read` | `club`, zentrale Shinkan-Sichtbarkeit | Aktive Mitgliedschaft, lokale registrierte Leserolle | | `club.library.update` | `club`, Clubobjekt im gewählten Club | Aktive Mitgliedschaft mit expliziter Pflege-Capability; private/offizielle Objekte haben eigene Änderungsregeln | | `organization.record.read` | `organization`, gleiche Org-ID | Aktive Mitgliedschaft plus lokale Leserolle; Vertrauensraummodell ist ausdrücklich produktlokal | | `operator.account.disable` | Scopefrei, explizite Operatorfunktion | Aktuelle Betreiberzuordnung, verpflichtende frische MFA, Pflichtaudit; kein allgemeines Datenleserecht | Diese Matrix vergibt noch keine neuen Produktrollen. Im Zielaufbau werden nur benötigte Zeilen registriert und getestet. Eine noch fehlende Orgfunktion bleibt unregistriert/geschlossen. ### 9.3 Gemeinsame Sichtbarkeit und Transaktion Shinkans zentrale SQL-Prädikate werden in einen lokalen `VisibilityPolicy`-/Repositoryadapter überführt. Listen, Detail, Suche, Counts, Export, Downloads und referenzierte Kindobjekte verwenden dieselbe Sichtbarkeitssemantik. Die Policy unterscheidet Lesen und Ändern. Shinkans `official` bedeutet für die entsprechende Bibliothek sichtbarer Inhalt; daraus entsteht kein familienweiter öffentlicher Datenraum und kein Schreibrecht auf offizielle Inhalte. Der Bestand erlaubt Plattformrollen an bestimmten Bibliotheksobjekten erweiterte private/Club-Lesesicht. Diese I-Regel wird nicht auf persönliche Mitai-/Kanshō-Daten übertragen. Ein neuer produktbezogener Sonderlesepfad muss eine eigene Capability, Zweckbindung und Audit besitzen; für den persönlichen Standardadapter existiert er nicht. Fachservice-Muster, V/K, mit denselben Verträgen wie Foundation B2: ```python def rename_record(self, ctx, record_id, command): with self.uow.transaction() as tx: self.access.require( ctx, "personal.record.update", ResourceRef("personal.record", record_id), tx, ) row = self.records.rename_owned( tx, ctx.scope, ctx.principal.subject_id, record_id, command.expected_version, command.title, ) result = RecordView.model_validate(row) self.audit.changed(tx, ctx, "record.renamed", record_id) return result ``` `rename_owned` akzeptiert keinen Besitzer aus dem Body. Es filtert im SQL nach ID **und** geprüftem Scope/Eigentümer sowie erwarteter Version. Policy lädt das sichtbare Objekt unter derselben Transaktion; fremd/unsichtbar ergibt 404. Erst bei einem sichtbaren Objekt ist eine abweichende Version 409. Der Runtimecode fragt keine fremde Zeile zur Unterscheidung nach. Eltern-/Kindzuordnungen werden ebenfalls scoped geladen. Kombinierte Foreign Keys wie `(parent_id,scope_id)` verhindern bei organisatorischen Daten falsche Cross-Scope-Verknüpfungen; persönliche Tabellen verwenden entsprechend `(parent_id,owner_id)`. Bulk-/Exportpfade dürfen Filter nicht erst nach dem Laden anwenden. Scope-/Ownerwerte sind bei normalem Update unveränderlich; Verschieben/Teilen ist ein eigener Fachanwendungsfall und kein Payloadfeld von `update`. ### 9.4 Gleichzeitiger Entzug und Änderung Im Default bleibt PostgreSQL bei `READ COMMITTED`; ein definierter Sperrvertrag verhindert das klassische „vor Transaktion geprüft, danach trotzdem geschrieben“: 1. Accountzeile gemeinsam sperren, Status/Epoch aktuell prüfen. 2. Sessionzeile gemeinsam sperren, Generation/Fristen/Widerruf aktuell prüfen. Bei Sessionmutation exklusiv sperren. Subject-/Credentialbezug muss dem Context entsprechen. 3. Bei Club/Org den lokalen Raum-/Berechtigungsanker und die Mitgliedschaft gemeinsam sperren und neu prüfen; danach relevante Rollen/Grants lesen. Der Mitgliedschafts-/Rollenwiderruf sperrt dieselben Anker exklusiv, bevor er ändert. Auch entfernte Mitgliedschaftszeilen werden nicht durch einen fehlenden Join als Freigabe interpretiert. 4. Betroffene Objektzeile für Writes exklusiv, für konsistente Reads gemeinsam sperren; scoped ändern/lesen und DTO erzeugen; Audit vor Commit. Globale Reihenfolge: Account → Session → Raumanker → Mitgliedschaft → Objekt; mehrere gleichartige IDs sortiert. Logout-all/Kontosperre nimmt Account exklusiv, dann Sessions. Produktadapter dokumentieren den tatsächlichen Raumanker, beispielsweise vorhandene Club-/Orgzeile; es braucht keine generische zentrale Guardtabelle. Rollenänderungen dürfen nicht nur eine Grant-Kindzeile ändern und diese Sperre umgehen. Eine Upgrade-Sperre wird im jeweiligen Änderungsservice von Beginn an exklusiv angefordert. Ein bereits autorisierter Write kann vor dem konkurrierenden Widerruf committen; dann wird der Widerruf danach wirksam. Hat der Widerruf zuerst committed, kann der Write nicht mehr unter dem alten Zustand committen. Derselbe Vertrag gilt für Kontosperre, Mitgliedschaftsentzug und Sessionwiderruf. DB-Locktimeouts liefern einen sicheren Fehler und keinen ungeprüften Retry. Kein externer Netzaufruf, Passwortvergleich oder Dateistream während dieser gesperrten Fachtransaktion. RLS folgt weiterhin ADR-06: eingeschränkte Runtime-Rolle, tenantkonsistente Constraints und belegte App-Policyabdeckung; vertrauliche Mehrraumprodukte prüfen zusätzliche RLS-Ausprägung ausdrücklich. Wenn vorhanden, nur transaktionslokaler DB-Kontext und Tests gegen Poolwiederverwendung. RLS ersetzt keine Capability-/Objektpolicy, und dieser Blueprint behauptet keinen bereits getesteten RLS-Adapter. ## 10. Sichere Scopewechsel im Browser `POST /auth/session/scope` bestätigt ausschließlich die gewünschte, aktuell erlaubte Auswahl. **Die Session speichert keinen globalen autoritativen aktiven Tenant.** Eine letzte UI-Präferenz darf später lokal gespeichert werden, muss jedoch vor Wiederverwendung erneut aufgelöst werden. Verschiedene Tabs können verschiedene berechtigte Räume verwenden, ohne einander im Backend umzulenken. Ablauf eines Wechsels A → B: 1. Frontend blockiert neue Mutationen aus A, behandelt ungespeicherte Änderungen und erhöht seine lokale epoch. Alle Loader/Requests aus A werden abgebrochen; persönliche Listen, Detailansichten, Fehlermeldungen und Caches werden geleert. 2. Bestätigungsrequest mit aktuellem Session-CSRF und explizitem Ziel B. Service prüft Konto, Session, Mitgliedschaft und Auswahl neu; Audit `scope.selected` mit Actor-/Scope-IDs in derselben Transaktion. 3. Erst bei Erfolg erhält der Store den bestätigten Scope B. Neue Fachrequests tragen exakt dieses Headerpaar. Scheitert die Auswahl, bleibt die Fachansicht geschlossen; keine heimliche Rückkehr auf einen anderen Verein. 4. Jede Antwort und jeder Fehler trägt clientseitig beim Start eingefangene epoch/Subject/Scope/Generation. Weicht sie beim Eintreffen ab, wird die Antwort verworfen. Das gilt ausdrücklich auch für alte 401/403/503 und abgebrochene Loader. Ein Abort macht keinen bereits angekommenen Serverwrite rückgängig. Ein solcher Request kann ausschließlich im unveränderlich mitgesendeten Scope A arbeiten, nie nachträglich in B. Der Browser startet ihn nicht automatisch erneut. Für unklare Writeergebnisse gelten die Foundationregeln zu Idempotenz/Objektversionen. UI-epoch ist Schutz vor alten Anzeigen, keine Backendberechtigung. Logout/Kontowechsel erhöht die epoch und leert Zustand ebenfalls; ein kleiner BroadcastChannel verteilt nur „Session geändert/abgemeldet“, keine Credentials, CSRF-Werte oder persönlichen Inhalte. Andere Tabs prüfen ihre Session neu. Ein aktueller 401 des Fachclients beendet den lokalen Sessionzustand; 403/503 tun das nicht. Fehler von Login-/Flowendpunkten werden lokal verarbeitet. Bei später benötigtem SSE/WebSocket bleibt der Verbindungs-Scope unveränderlich; Wechsel schließt und öffnet neu. Handshake prüft Cookie/Origin/Scope, jedes ausgehende persönliche Ereignis erneut aktuelle Zugriffslage (alternativ kontrollierte kurze Batches mit sofortigem Widerrufssignal). Keine stundenlange Berechtigung aus dem Handshake und keine während des Streams gehaltene DB-Transaktion. Solche Transporte werden erst bei realer Funktion implementiert und separat negativ getestet. ## 11. Privilegierte Zugriffe und MFA ### 11.1 Bevorzugter Faktor und sichere Secretablage Shinkans TOTP-Verfahren wird lokal übernommen: 20 Zufallsbytes, Base32, HMAC-SHA-1, sechs ASCII-Ziffern, 30-Sekunden-Schritt, Fenster ±1. Der Prüfer wird so angepasst, dass er den **akzeptierten Counter** statt nur `True` zurückgibt. Unter Faktorsperre gilt `accepted_counter > last_accepted_counter`; Update des Counters, Verbrauch des Flows und Sessionerstellung/Step-up erfolgen atomar. Auch derselbe Code gegen zwei verschiedene Challenges kann nur einmal gewinnen. Der erste Einrichtungsnachweis speichert den Counter bereits. [RFC 6238, Abschnitt 5.2](https://www.rfc-editor.org/rfc/rfc6238#section-5.2) verlangt, einen bereits erfolgreich verwendeten OTP nicht nochmals zu akzeptieren. Faktor-Secret wird mit einem lokalen `FactorSecretCipher` verschlüsselt. Bevorzugter kleiner Adapter: `cryptography.fernet.Fernet`; authentifizierte Verschlüsselung statt eigener Kryptografie. Diese zusätzliche lokale Bibliothek löst allein die wieder lesbare Secretablage, führt keinen Dienst ein und wird im Ziel-Lockfile gepinnt. Ein bereits vorhandener gleichwertiger Produktadapter hat Vorrang nach Schnittstellenprüfung. `MFA_ACTIVE_KEY_ID` und die Key-ID→Fernet-Key-Zuordnung werden ausdrücklich über gemountete Secrets bereitgestellt; keine DB-/Passwort-/Dev-Fallbackschlüssel. Nur `key_id` und Ciphertext stehen in DB/Backups. Neue Verschlüsselungen verwenden den aktiven Key; alte Key-IDs bleiben während einer kontrollierten lokalen Neuverschlüsselung lesbar. Fehlender/ungültiger Key verhindert MFA-Readiness und liefert im MFA-Pfad 503, keine Passwort-only-Ausnahme. Schlüsselmaterial niemals ausgeben. Verschlüsselte Backups und zugehörige Schlüssel benötigen die produktbezogene Recoveryvorsorge aus der Foundation. ### 11.2 MFA-Endpunkte und Zweckbindung Alle POSTs sind JSON mit der allgemeinen Browser-/Originprüfung. `EnrollmentView={otpauth_uri,secret,expires_at}` enthält ein einmal ausgegebenes Faktor-Secret; ausschließlich Einrichtungsansicht, `no-store`, keine Telemetrie. Ein verlorener Einrichtungsresponse erfordert Neustart mit neuem Secret. `RecoveryView={codes:[...]}` wird ebenfalls nur einmal ausgegeben. | Methode / Pfad unter `/api/v1/auth` | Erlaubter Zustand / Nachweis | Verhalten | |---|---|---| | `POST /mfa/enrollment/start` `{}` | Nur `mfa_enroll`-Flow + Flow-CSRF nach Betreiberlogin; keine gültige Vollsession | 200 EnrollmentView; genau ein Pending-Secret erzeugen. Bereits aktiver Faktor: 409. | | `POST /mfa/enrollment/confirm` `{code}` | Nur derselbe `mfa_enroll`-Flow + Flow-CSRF; Pending-Secret vorhanden, keine gültige Vollsession | TOTP prüfen, Faktor+Counter, Recoveryhashes und Audit atomar. Vorhandene Sessions/Flows widerrufen, Epoch erhöhen; nach geprüftem Passwort+Faktor neue Session. 200 `{session:SessionView,recovery_codes:[...]}`, frisches Cookie, Preauthcookie löschen. | | `POST /session/mfa/enrollment/start` `{current_password}` | Nur aktuelle Vollsession + Session-CSRF und aktuelles Passwort für erstmalige freiwillige Einrichtung | 200 EnrollmentView; Pending-Flow an Konto/Session/Epoch/Passwortrevision binden, Ablauf 10 Minuten. Bereits aktiver Faktor: 409. | | `POST /session/mfa/enrollment/confirm` `{code}` | Nur initiierende Vollsession + Session-CSRF; gebundener Pending-Flow vorhanden | Gleicher atomarer Abschluss wie beim Betreiberflow; 200 `{session:SessionView,recovery_codes:[...]}`, neue Session-ID und Cookie; alte Sessions/Flows ungültig | | `POST /mfa/verify` `{code,method}` | Nur `mfa_login`-Flow + dessen CSRF | 200 SessionView nach TOTP oder einmaligem Recoverycode, Flowverbrauch, Audit; bereits gültige Vollsession: 409, kein stiller Kontowechsel | | `POST /mfa/step-up` `{current_password,code,method}` | Aktuelle Vollsession + Session-CSRF; aktiver Faktor | Passwort erneut prüfen, aktuelle Revision/Epoch prüfen; TOTP/Recovery atomar verbrauchen. `auth_time`/`mfa_verified_at` auf DB-Zeit, Sessioncredential/CSRF rotieren; Absolute-Frist nicht verlängern. 200 SessionView. | | `POST /mfa/recovery-codes/replace` `{current_password}` | Vollsession, Session-CSRF, frische echte TOTP-MFA (siehe unten), aktuelles Passwort | Alte Codes löschen, neue Hashes/Audit atomar; 200 RecoveryView. Keine Anzeige bereits ausgegebener Codes. | | `POST /mfa/disable` `{current_password}` | Normales Konto, Vollsession/Session-CSRF, frische echte TOTP-MFA, aktuelles Passwort | Faktor/Codes löschen, Epoch erhöhen, alle Sessions/Flows widerrufen, Audit; 204/Cookie löschen. Für Betreiberrolle 403 `mfa_required`. | Die Sessionvariante der Einrichtung verwendet **kein** alternativ akzeptiertes Preauthcredential. Pending-Enrollmentdaten liegen in einer `mfa_enroll`-Flowzeile, gebunden an `subject_id`, Epoch, Passwortrevision und die initiierende `session_id` über `initiating_session_id` aus Abschnitt 5. Start ersetzt alte Pending-Enrollments dieses Kontos. Confirm prüft die noch gültige initiierende Session und den gleichen Faktorentwurf. Der Flow wird nicht über einen vom Client frei gesetzten Subjectwert gefunden. Nach Erfolg hat die neue Session eine neue ID und die im Flow gespeicherte Prüfzeit des bestätigten Passworts als `auth_time`; eine neue zwölfstündige Absolutfrist ist nach diesem vollständigen Neunachweis zulässig. Beim Preauth-Start wird das Pending-Secret auf dem bereits legitimierten, weiterhin gültigen `mfa_enroll`-Flow ersetzt; dessen Ablauf wird nicht verlängert und er wird dabei nicht selbst verbraucht. Andere offene Enrollmentflows dieses Kontos werden geschlossen. Beim Session-Start entsteht eine neue an die initiierende Session gebundene Zeile; ihr internes zufälliges Token wird nicht als zweites Browsercredential ausgegeben. Confirm findet sie über Session/Subject/Zweck. Ein partieller Unique-Index über `subject_id` für unverbrauchte `mfa_enroll`-Zeilen und Kontosperre beim Start sichern die Eindeutigkeit. Ein abgelaufener Vorgänger wird vor Neuanlage als verbraucht markiert. Die getrennten Endpointpaare verhindern ein automatisches Wechseln zwischen Session- und Flow-CSRF. Die in Abschnitt 5 definierte Spalte `auth_sessions.mfa_method` hält die Herkunft des MFA-Nachweises fest. Principal/SessionView benötigen dafür kein zusätzliches öffentliches Vertrauensfeld: der aktuelle Access-/MFA-Service liest es aus der Zeile. Ein Recoverycode kann Login und Step-up ermöglichen; der Nachweis wird als `recovery` auditiert. Faktoren deaktivieren oder Recoverycodes ersetzen verlangt `mfa_method='totp'` innerhalb des Fünfminutenfensters. Betreiberaktionen können mit Recovery nach Passwortnachweis stattfinden und werden besonders auditiert; ein Recoverycode allein erlaubt keinen Faktorwechsel und keine neue Codeausgabe. Bei falschem Code werden Zähler committed, ab dem fünften Fehlversuch der Flow verbraucht. Bei Step-up ohne Flow gilt dieselbe Grenze pro Session plus Konto-/IP-Limit; dafür dient `auth_sessions.mfa_failed_attempts` aus Abschnitt 5. Fünf Fehler widerrufen diese Session, erfolgreiche Verifikation setzt den Zähler zurück. Keine unbegrenzten Fehlversuche durch neue Challenges. Codes werden exakt nach gewähltem `method` geparst; kein „TOTP schlägt fehl, dann dieselbe Eingabe als Recovery probieren“. ### 11.3 Betreiber, Reauth und Recoverygrenze Jede privilegierte Betreiberfunktion ist ausdrücklich registriert, benötigt eine aktuelle Betreiberzuordnung, `full`-Session, vorhandenen aktiven Faktor und MFA-Nachweis jünger als fünf Minuten. Ein normaler Login mit Faktor darf das Frischefenster erfüllen. `auth_time` allein ersetzt MFA nicht; `/session/renew` erneuert die MFA-Zeit nicht. Auch ein Betreiber darf persönliche Daten anderer Konten nicht über Standard-Personal-Policies lesen. Eine spätere fachlich benötigte Support-/Exportfunktion wäre ein gesonderter, eng begrenzter und auditierter Produktpfad. Fehlt Betreiber-MFA, darf nach richtigem Passwort nur der Einrichtungsflow öffnen. Kein optionales `REQUIRE_ADMIN_TOTP=0`, keine Ausnahme wegen leerer DB. Neue Betreiberrolle macht alte Sessions ungültig und erzwingt diese Reihenfolge. Die Ersteinrichtung erfolgt gemäß ADR-05 über eine lokale administrative CLI: explizit ausgewähltes Konto, Passwort verdeckt eingeben, atomare Einmaligkeit unter DB-Advisory-Lock; keine offene „erster Registrierer wird Admin“-Route. CLI erstellt nur ein zur MFA-Einrichtung verpflichtetes Betreiberkonto. Normale Accounts erzeugt ein separater ausdrücklich autorisierter Einladungs-/Produktweg. Bei Faktorverlust nutzt die Person Passwort plus unbenutzten Recoverycode. Sind alle Faktoren/Codes verloren, ist **keine anonyme Online-Faktorresetroute** vorhanden. Der vorhandene lokale Betriebszugang erlaubt einen ausdrücklich adressierten Recoverybefehl mit verdeckter Passwortneuvergabe, Reset von Faktor/Codes, Epoch-Erhöhung, Widerruf aller Sessions/Flows und Pflichtaudit. Danach erneut MFA-Einrichtung. Dieser Betriebsweg ist kein Bestandteil der Web-API und erhält keine Runtime-Superuserrechte. Eine passende begrenzte Betriebs-/Recoveryrolle wird bei Umsetzung verwendet. Der geprobte Testfall ist Pflicht vor privilegierter Nutzung; in dieser Phase wurde er nicht ausgeführt. ## 12. Maschinenidentitäten und spätere SSO-Anbindung ### 12.1 Technische Identitäten: Port vorbereiten, keine Infrastruktur bauen Die Browserrouten akzeptieren ausschließlich ihr Sessioncookie. Sie akzeptieren weder `X-Profile-Id` als Autorität noch Header-/URL-Sessions. Ein eigener späterer Operational-Router darf `Authorization: Bearer` verwenden. Mehrere Credentials auf einer solchen Route (z. B. Browsercookie plus Bearer oder mehrere Authorizationwerte) werden als mehrdeutig verweigert; keine Prioritätswahl, kein Zusammenmischen von Berechtigungen. Browser-JSON-Routen verweigern unerwartete zusätzliche Authheader ebenfalls. Minimale spätere Adapterverträge, noch keine Tabellen oder Tokenverwaltungsendpunkte auf Vorrat: ```python class MachineCredentialVerifier(Protocol): def resolve(self, raw_bearer: str) -> Principal: ... class MachineAuthority(Protocol): def require_current(self, context: RequestContext, capability: str, resource: ResourceRef | None, tx: Tx) -> None: ... @dataclass(frozen=True, slots=True) class VerifiedExternalIdentity: issuer: str subject: str auth_time: datetime methods: frozenset[str] class ExternalIdentityLinker(Protocol): def resolve_local_subject(self, identity: VerifiedExternalIdentity, tx: Tx) -> str: ... ``` Ein echter späterer Machine-Adapter verwendet Kairos Hash-/Actor-/Tenantmuster mit folgenden verbindlichen Grenzen: eigener Actor und Credential-ID, explizit nicht leere Capabilitymenge, endlicher Ablauf und Widerruf; Scope fest an das Credential gebunden; effektives Recht = Tokenallowlist ∩ aktuelle Actorpolicy ∩ gegebenenfalls aktuelle Delegation. Delegierte menschliche Rechte entfallen bei Sperre/Entzug. Clientheader können den Credentialscope nicht erweitern. Aktueller Actor, Organisation und Token müssen aktiv sein. Langzeit-Claims allein genügen nicht. Maschinenwrites benutzen dieselben Fachservices/UoW, Objektfilter und das Pflichtaudit mit Actor, Credential-ID, Scope und Ressource. Keine direkten DB-Writes, Browser-MFA-Ausnahmen oder Übernahme menschlicher Cookies durch Agenten. Toolallowlists und ggf. Kostenkontrolle bleiben zusätzliche Grenzen. Ohne implementierten Adapter wird der Operational-Router nicht exponiert. Die hier benannten Ports sind eine technische Naht; es werden in Phase 3.3 weder Actor-Tabellen noch ein MCP-/Tokenausgabedienst entwickelt. Spätere relevante Fälle sind in der Testmatrix als bedingte Adaptertests gekennzeichnet. ### 12.2 SSO später: externe Identität lokal verknüpfen Bei einem tatsächlich beauftragten SSO-Adapter entsteht `VerifiedExternalIdentity` nur nach vollständiger serverseitiger Prüfung des gewählten Protokolls (bei OIDC u. a. Issuer, Audience, Signatur, Ablauf, State, Nonce und PKCE). Dieser Blueprint implementiert kein OIDC-Protokoll. Der Linker ordnet das eindeutige Paar `(issuer,subject)` einem lokalen Konto zu; keine automatische Verknüpfung allein wegen gleicher E-Mail, keine Übernahme fremder Tenant-/Adminclaims. Nach erfolgreicher Verknüpfung gelten lokaler Kontostatus, Scope-/Objektpolicy und die produktlokale Cookie-Session unverändert. Ein externer MFA-Claim wird erst nach expliziter Adaptervertrauensregel akzeptiert; standardmäßig entsteht daraus kein lokaler Betreiber-MFA-Nachweis. Kein familienweites Cookie, keine gemeinsame Sessiontabelle, keine Tenant-Fachdatenmigration und kein bereits versprochenes globales Logout. Es wird jetzt weder ein Identity Provider ausgewählt noch ein SSO-Dienst gebaut; dies blockiert die lokale Implementierung nicht. ## 13. Fail-Closed-Verhalten, Audit und Anti-Patterns ### 13.1 Entscheidungsreihenfolge der AccessPolicy `require(context, capability, resource, tx)` führt in fester Reihenfolge aus: 1. Registrierte Capability und passende Principalart feststellen. `machine` ist bei reinem Browseradapter immer verboten. 2. Aktuellen Konto-/Credentialzustand und Sessionmodus prüfen; bei Widerruf/Sperre/Generationwechsel 401, bei nicht ausreichendem Onboardingstatus 403. Zwischenflow kann diesen Pfad nie erreichen. 3. Vorgeschriebenen Scope und dessen aktuelle Eigentums-/Mitgliedschaftsgrenze gemäß Sperrvertrag prüfen; fremde Auswahl 403. Keine Scopeauswahl bei Raumfreiheit als Hintertür verwenden. 4. Rollen/Capabilities nur aus diesem aktuellen Kontext bestimmen. Bei Betreiberfunktion zusätzlich Faktoraktivität, MFA-Herkunft und Frische prüfen. Kein Rollenrang oder `is_admin`-Shortcut überspringt die Objektregel. 5. Falls Objekt erforderlich: ausschließlich scoped/sichtbar laden; unsichtbar/fremd/fehlend 404; konkrete Lese-/Schreibregel durchsetzen. Auch alle referenzierten Eltern/Quellen prüfen. 6. Fachoperation durchführen, gegebenenfalls getrennte Entitlementprüfung, sichere DTO-Ausgabe und erforderliches Audit in derselben UoW; Commit vor Response. Ein technischer Ausfall der aktuellen Policyauflösung wird 503, nicht „leere Rollen, dann Standardrecht“ oder Allow. Ein unbekannter Kontostatus wird verweigert und intern diagnostiziert. Runtime-Flags `AUTH_DISABLED`, `CAPABILITY_ENFORCE=0`, „Probe erlaubt“ und `X-Admin` existieren in der neuen Implementierung nicht. Testfakes entstehen ausschließlich in Tests und sind im Produktionsprovideraufbau nicht auswählbar. ### 13.2 Audit und Datensparsamkeit Pflicht-Ereignisse: Session erstellt/rotiert/widerrufen, Logout-all, Passwortänderung/-reset, Kontosperre/-reaktivierung, Betreiberrollenänderung, Scopewahl, MFA eingerichtet/verwendet/deaktiviert/zurückgesetzt, Recoverycode verbraucht/ersetzt und jede privilegierte Änderung. Audit trägt Foundationfelder: Ereignis-ID, UTC-Zeit, Request-ID, Subject-/Actor-ID, Credential-ID, Aktion, Scope, Objekttyp/-ID, Ergebnis und begrenzten Reasoncode. Keine E-Mail, Passwörter, Cookie-/CSRF-/Recovery-/Faktorwerte oder private Texte. Failed-Login-Ereignisse verwenden den nicht rückrechenbaren Rate-Bucketbezug statt der eingegebenen Adresse; aufbewahrte Securitylogs bleiben zugriffsbeschränkt und produktbezogen befristet. Zustandsänderung und Pflichtaudit committen gemeinsam. Fehlender Auditadapter verhindert die kritische Aktion. Fehlversuchszähler/Challengefehler werden in einer eigenen kurzen Authtransaktion samt Ereignis committed, bevor der Service ein Fehlerergebnis zurückgibt. Das ist bewusst anders als eine Exception, die dieselbe UoW zurückrollt. Allgemeine Origin-/CSRF-Verweigerungen nutzen begrenztes strukturiertes Securitylogging; ein Logausfall darf die verweigerte Anfrage nicht erlauben. Weder Produkt-DB-Inhalte noch Principal/RequestContext gehen ungefiltert an KI-Provider oder globale Diagnose-Widgets. Für spätere persönliche KI gilt nach erfolgreicher Objektberechtigung weiterhin Kanshōs Privacy Gateway. Auth ist keine Ausnahme von dieser Egressgrenze. ### 13.3 Ausdrücklich zu vermeidende Muster | Anti-Pattern | Geforderte Umsetzung | |---|---| | Mitai `get_pid(X-Profile-Id)` oder `ORDER BY created LIMIT 1` | Eigenes Profil ausschließlich aus geprüftem lokalen Konto; fremde Auswahl verweigern | | Eingeloggtes Konto reicht für beliebigen Profil-CRUD/Export | Self-Endpunkt oder ausdrückliche Capability plus scoped Objektregel und explizite DTOs | | Shinkan `min(club_ids)`, ungültigen Header ignorieren, fehlender Kontostatus gilt als aktiv | Auswahl erforderlich; fehlerhaft/fremd verweigern; bekannter serverseitiger Zustand Pflicht | | UI blendet Button aus, Backend macht ungeprüft weiter | Serverseitige gemeinsame Policy für jede Route/Objektoperation | | Sessionrolle bleibt bis Cookieablauf gültig | Kontostatus, Mitgliedschaft und effektive Rechte aktuell prüfen; Sperrvertrag bei Transaktionen | | Volltoken in JSON, URL, LocalStorage, SSE-Query oder Context | HttpOnly-Cookie; getrennte zweckgebundene Grants nur bei echtem Bedarf | | Cookie-SameSite ersetzt CSRF oder `Origin.endswith('jinkendo.de')` | Credentialgebundener CSRF-Wert und exakte konfigurierte Originprüfung | | Beliebige private Proxy-IP legitimiert Forwarded-Header | Explizite tatsächliche Proxyallowlist; untrusted Header verwerfen | | MFA-Challenge gilt schon als Session; Betreiber-MFA nur per Flag | Getrennte Flowtabelle/Resolver, feste Endpointzwecke, Operator-MFA verpflichtend | | TOTP nur als `bool`, Recoverycode mehrfach einlösbar | Atomar gespeicherter akzeptierter Counter bzw. bedingtes einmaliges Update | | Zufallsarme Recoverycodes oder DB-Passwort als Faktorschlüssel | 128-Bit-Recoverysecrets, separater lokal bereitgestellter Verschlüsselungsschlüssel | | Kairo leere Tokenrechte → breite Defaultrechte; unbegrenzte Laufzeit | Explizite enge Rechte, Ablauf, aktuelle Actor-/Delegationsbegrenzung | | Ein globaler Sessiontenant lenkt nach Scopewechsel alte Requests um | Unveränderlicher Scope pro Anfrage; serverseitige Prüfung und UI-epoch | | Audit oder Membershipprüfung öffnet eigene Connection im Fachwrite | Gemeinsames `tx`, Rollback bei Pflichtfehler, Commit vor Erfolg | | Nach 401/Timeout einen Write automatisch erneut senden | Ergebnis klären; gegebenenfalls explizite Idempotenz/Version des Fachmoduls | | Kontolöschung oder Passwortreset lässt MFA-/Resetflows gültig | Epoch erhöhen, alle Sessions und Authflows atomar widerrufen/verbrauchen | | Gleiche E-Mail in zwei Apps wird SSO-Autorität | Später explizit geprüfte `(issuer,subject)`-Verknüpfung zum lokalen Konto | Cookieparser muss doppelte Werte des sicherheitsrelevanten Cookienamens im rohen Cookieheader erkennen und verweigern; kein stilles Last-value-wins des Frameworkdicts. Session-/Flowcredential muss dem kanonischen Format entsprechen, leere/zu lange/nicht ASCII-/CSV-Werte ergeben 401. Mehrdeutige Authquellen werden vor Fachlogik verweigert (422 `ambiguous_credentials`). Nicht unterstützte Legacy-Profil-/Sessionheader (`X-Profile-Id`, `X-Auth-Token`, `X-Actor-Token`) werden auf den neuen Browserrouten mit 422 `unsupported_auth_header` zurückgewiesen, statt als unsichtbare Nebenautorität weiterzuleben. Diese beiden Codes ergänzen die Fehlerliste in Abschnitt 8. ## 14. Automatisierte Sicherheits- und Negativtests Dies ist ein konkreter Testauftrag für Phase 3.4, kein Bericht bestandener Tests. Alle hier als Pflicht bezeichneten Fälle müssen im späteren Zielaufbau tatsächlich gesammelt und ausgeführt werden. Unitfakes prüfen reine Zustandsregeln; DB-Rennen und Filterinvarianten werden gegen isoliertes echtes PostgreSQL mit begrenzter Runtime-Rolle geprüft. Keine synthetischen Schreibtests gegen vorhandene Anwendungen oder produktive Datenbanken. ### 14.1 Testdaten und Harness Fixture: Personen A/B; A aktiv in Club/Org 1 und 2 mit unterschiedlichen Rollen, B nur in 2; Person C deaktiviert; ein unbestätigtes Konto; ein bestätigtes Konto ohne Club; Operator O mit Faktor; Operator N ohne Faktor. Je ein persönliches Objekt von A/B, Organisationsobjekte in 1/2, privates/eigenes/fremdes, Club- und offizielles Bibliotheksobjekt, Eltern-/Kindreferenzen sowie eine Reihe Export-/Medienressourcen. Alle IDs und Texte synthetisch. Nicht implementierte Produktarten sind statt dieser Fachfixtures durch „Scopeart nicht registriert“ abgedeckt. Testapp über dieselbe `create_app`-Factory. Time/Clockadapter für reine Algorithmen; DB-Ablaufprüfungen setzen Fristspalten deterministisch relativ zur DB-Uhr. HTTP-Clients verwenden `https://test.invalid`, passende Origin-/Custom-/CSRF-Header und echte Cookiejars. Fixtures setzen keinen Allow-all-Schalter. Zwei DB-Verbindungen/Worker und explizite Barrieren steuern Rennen; keine zufälligen Sleeps als Beweis. Poolgrenze klein halten und Connections nach jedem Fehler zurückgeben. ### 14.2 Pflichtmatrix des Browser-/Personal-Kerns | ID / bevorzugte Testdatei | Automatisierter Fall | Zwingende Assertions | |---|---|---| | S01 `test_auth_sessions.py` | Login korrekt, falsch, unbekannt, Konto gesperrt/gelöscht | Nur korrekter aktiver Account erhält Cookie; generische 401 bei Fehlfällen; kein Sessiontoken im JSON/Log/DB-Klartext; bcrypt-Dummyweg aufgerufen | | S02 | Passwort über 72 UTF-8-Bytes, Unicodegrenze, leeres/fehlendes Passwort, zusätzliche Rollenfelder | 422 vor bcrypt bei Bytegrenze; kein Abschneiden; `extra='forbid'`; kein Rechtewechsel | | S03 | Idle-/Absolutfrist vor, auf, nach DB-Zeitgrenze | Ab Grenze 401; Cookie-Max-Age/Clientzeit ändern nichts; abgelaufene Session wird nicht reaktiviert | | S04 | Erfolgreiche Fachaktivität, Session-GET und Renewal | Nur definierte Aktivität schiebt Idlefrist; nie über Absolutfrist; Pollingkonzept ohne Keepalive | | S05 | Rotation | Genau ein neuer Hash/CSRF und höhere Generation; alter Cookie/CSRF scheitert; `auth_time`, MFA-Zeit und Absolutfrist bleiben gleich | | S06 | Logout / zweimal Logout / falscher CSRF | Widerruf nach Commit; zweimal 204; falscher CSRF bei gültiger Session 403 ohne Widerruf; Cookie korrekt gelöscht | | S07 | Logout-all, Passwortwechsel, Kontosperre, Faktorreset | Alle Geräte-Sessions und Authflows ungültig; Epoch erhöht; Passwortrevision nur bei Passwortänderung; kein wiederverwendbarer Zwischenflow | | S08 | Passwortwechsel ohne/falsches aktuelles Passwort | Verweigert, Hash/Epoch unverändert; korrektes Passwort bewirkt atomaren Widerruf, keine verdeckte neue Session | | B01 `test_auth_boundary.py` | Set-Cookie bei Login/Rotation/Logout | HttpOnly, Secure, SameSite=Lax, Path=/, kein Domain; Sessionwert nie JS-DTO; HTTPS-Browsertest liest Cookie nicht via `document.cookie` | | B02 | Fremder Origin, Geschwisterhost, Suffixtrick, null, fehlende Origin+Referer, doppelter Origin | 403 vor Mutation; exakt passender Referer nur bei fehlendem Origin erlaubt; vorhandener falscher Origin nicht überstimmt | | B03 | CSRF fehlt/falsch/von anderer Session/von anderer Generation | 403 bei gültigem Credential, keine Mutation; korrekter eigener Wert erlaubt den autorisierten Pfad | | B04 | Login-CSRF, Preauth als Vollsession, Session-CSRF auf Flowroute | Ohne korrekt gebundenen Vorflow verweigert; kein Fachzugriff mit MFA-/Loginpreparecookie; kein Wechsel zwischen CSRF-Quellen | | B05 | Fehlender Customheader, Cross-Origin-Preflight, Form-/textplain-POST, übergroßer Body | Verweigert (Header 403, Medientyp 415, Body 413); keine Credentials-CORS-Freigabe, keine Fach-/Authmutation | | B06 | Doppelcookie, falsches Tokenformat, Querytoken, Profilheader, Cookie+Bearer | Kein Last-value-wins oder Authfallback; 401/422 gemäß Abschnitt 13; Session aus URL niemals akzeptiert | | B07 | Gefälschte Forwarded-IP/Host von untrusted Peer | Keine Umgehung von Origin-/Rateprüfung; nur ausdrücklich konfigurierter Proxy beeinflusst Client-IP | | B08 | Auth-DB/Policy/Schlüssel/Audit nicht verfügbar | 503 bei Pflichtabhängigkeit; keine Allow-Antwort, keine Cookieausgabe vor Commit; keine internen Details im Problem | | A01 `test_account_lifecycle.py` | Unverified / pending Club / aktiver Personalaccount / unbekannter Zustand | Onboarding-Allowlist korrekt; keine Fachfreigabe für eingeschränkte Session; persönliche App benötigt keinen Club; fehlender Status verweigert | | A02 | Gleichzeitiges Erstoperator-Provisionieren | Genau ein autorisierter CLI-Bootstrap gewinnt; kein offener Web-Erstadminweg; Operator ohne Faktor erhält nur Enrollmentflow | | P01 `test_access_isolation.py` | Eigenes/fremdes persönliches Objekt in GET/Liste/Count/Suche/Export/Update/Delete/Medien | Eigene Daten erlaubt nach Capability; fremde 404 oder aus Listen entfernt; keine B-Inhalte/Counts/Dateien; kein Besitzer aus Body/Profilheader akzeptiert | | P02 | Objektversion, fremde Eltern-ID, fremde Quellen-ID, Scope-/Owneränderung im Body | Unsichtbares Ziel 404 vor Versionstest, sichtbarer Konflikt 409; Cross-Owner-FK/Policy verhindert Einfügen; keine Mutation/kein Erfolgsaudit | | P03 | Capability unbekannt, doppelt registriert, fehlende Objektpolicy, nicht registrierter Scope | Aufbaufehler bei Registry-/Routendefekt; verbleibender Laufzeitpfad verweigert; keine Standardrechte | | P04 | Kein/malformiertes Headerpaar, Personal-Scope von B, Scope auf scopefreier Fachoperation | 422/403 gemäß Vertrag; keine Erstprofil-/Erstclubwahl und kein scopefreier Fachzugriff | | P05 | Betreiber O auf persönlichem Objekt von B | Standardpersonalpolicy verweigert trotz Betreiberrolle und MFA | | R01 `test_auth_races.py` | Passwortprüfung pausiert; danach Passwortreset/Kontosperre; Loginabschluss | Kein Sessioncommit mit altem Snapshot; Revisions-/Epochprüfung greift | | R02 | Zwei Renewals derselben Generation | Genau ein Erfolg; Verlierer 401 ohne Set-Cookie; kein altes Credential gültig; UI verarbeitet nicht zwei Identitäten | | R03 | Logout und Rotation in beiden Sperrreihenfolgen | Nach bestätigtem Widerruf keine gültige Session; spätes Cookie kann keine widerrufene Zeile beleben; in-flight Logout kann logische Session widerrufen | | R04 | Logout-all/Kontosperre gegen Fachwrite, beide Commitreihenfolgen | Write vor Widerruf oder Verweigerung nach Widerruf; kein nach Widerruf autorisierter Commit; Audit passend, keine Teiländerung | | R05 | Auditfehler und Commitfehler bei Login/Scopewahl/privilegierter Änderung | Alles rollt zurück; kein Success/Cookie vor Commit; Connections werden freigegeben | | R06 | Mehrere Authworker, parallele Fehlversuche, Rollbackfallen | Atomare Rate-/Fehlversuchszähler und Challengeverbrauch; 429/gesperrter Flow bleibt trotz Fehlerresponse gespeichert | | F01 `shared/session.test.js` | A→B, A→Logout und Kontowechsel mit verspätetem Erfolg/401/403/503 | Keine Altansicht/Altfehlermeldung; alte 401 beendet keine neue Session; aktueller 401 beendet, 403/503 nicht | | F02 | Abgebrochener Write, verlorene Rotation, Cross-Tab-Renewal | Kein automatischer Fachwrite-Retry; sicherer Session-GET kann Status klären; Authmutationen serialisiert; unklarer Zustand bleibt geschlossen | | E01 `tests/e2e/auth.spec.js` | Browsercookie, Reload, CSRF, Logout, Back-Navigation | Session bleibt HttpOnly, CSRF nur Speicher, kein persönlicher Browser-/PWA-Cache, nach Logout keine alten Inhalte; echte Browserattribute geprüft | 413/415 und Headerfehler sind ergänzende stabile Problemcodes `payload_too_large`, `unsupported_media_type`, `browser_header_required`. Sie werden wie alle übrigen Fehler über den Foundation-Problemhandler ausgegeben, ohne angeforderten Body zu spiegeln. ### 14.3 MFA-Pflichtmatrix | ID / `test_mfa_security.py` | Automatisierter Fall | Zwingende Assertions | |---|---|---| | M01 | Deterministische RFC-TOTP-Vektoren, Zeitfenster ±1, Nicht-ASCII-/falsche Eingabe | Korrekte Algorithmenwerte; bei sechs Stellen die letzten sechs Stellen des passenden RFC-Achtstellenvektors; außerhalb Fenster oder nicht exakt sechs ASCII-Ziffern verweigert | | M02 | Derselbe TOTP mehrfach und gleichzeitig gegen zwei Challenges | Genau ein Commit; `last_accepted_counter` steigt atomar; Replay auch innerhalb Zeitfenster verweigert | | M03 | Fünf falsche Codes, danach richtiger; neue Flows/andere Worker | Flow dauerhaft verbraucht bzw. Session widerrufen; Konto-/IP-Limits nicht umgangen; Fehlerzähler trotz 401 committed | | M04 | Recoverycode zweimal/gleichzeitig, normalisierte/falsch formatierte Codes | Genau ein Verbrauch; nur definierte Normalisierung; Hash statt Code in DB; kein Code im Log | | M05 | MFA-Flow abgelaufen, anderer Subject, nach Epoch-/Passwortänderung | Keine Vollsession, keine Wiederbelebung; Zweck-/Bindungsprüfung atomar | | M06 | Operator ohne Faktor / vorhandene alte Passwortsession / Betreiberrollenerhöhung | Nur Enrollment; Fach-/Opszugriff verweigert; alte Session widerrufen; keine Runtime-Flagumgehung | | M07 | Enrollment bestätigt, Counter verbraucht, Responseverlust/Neustart | Faktor/Codes/Session/Audit atomar; einmalige Secretausgabe; verlorene Pending-Ausgabe nur mit neuem Secret; keine alte Pending-Bindung verwendbar | | M08 | MFA-Frist exakt fünf Minuten, Renewal, Step-up mit falschem/richtigem Passwort | Ab Frist `mfa_required`; Renewal frischt nicht auf; vollständiger Step-up rotiert Credential/CSRF und erhält Absolutfrist | | M09 | Recovery-Login, Codeersatz/Disable ohne echten frischen TOTP, Operator-Disable | Login nach Passwort+Recovery möglich; Faktor-/Codeverwaltung verweigert; Betreiber kann MFA nicht abschalten | | M10 | Ciphertext verändert, Key fehlt/rotiert, alter Key während Übergang | 503/keine MFA-Ausnahme bei Defekt; kontrollierte Neuverschlüsselung erhält Faktor; keinerlei Key-/Secretwert im Fehler | | M11 | Lokale Recovery mit vollständigem Faktorverlust | Alle Sessions/Flows ungültig; Reset auditiert; danach nur erneute MFA-Einrichtung; Webresetroute nicht vorhanden | ### 14.4 Bedingte Adaptertests bei tatsächlichem Funktionsumfang Diese Fälle werden Pflicht, sobald der Zielauftrag die betreffende Funktion registriert. Fehlt sie, prüft der Kern ausdrücklich die Nichtverfügbarkeit; keine als „bestanden“ verkaufte Skip-Suite. | ID / Bereich | Pflichtfälle bei Integration | |---|---| | O01 Club/Org | Mitglied in 1/2, unterschiedliche Rollen; Reader in 2 erhält keine Writerrechte aus 1; Mitgliedschaft inaktiv/gelöscht, Raum deaktiviert, Auswahl fremd; keine Mehrclubfallbacks | | O02 Sichtbarkeit | Shinkan-Matrix privat eigen/fremd, Club passend/fremd, official; Leserecht erzeugt kein Änderungsrecht; Listen/Details/Graphreferenzen/Export/Medien gleich; lokale Plattformausnahme nicht auf persönliche Daten übertragen | | O03 Entzugrennen | Mitgliedschaft, organisationsweite Rolle und einzelne Rollenzuordnung gegen Objektwrite; beide Commitreihenfolgen nach Abschnitt 9.4; Grantänderung sperrt gemeinsamen Raumanker | | O04 Parent-/Poolgrenze | Cross-Tenant-Eltern/Kind-FK, Bulkimport, Export; falls RLS: zwei Scopes auf wiederverwendeter Connection und fehlender Transaktionskontext dürfen nichts freigeben | | X01 Maschine | Abgelaufen/widerrufen, falscher Tenant, Actor deaktiviert, Delegation entzogen, leere Rechte, zusätzliche nicht erlaubte Capability, Cookie+Bearer; Tokenrechte ∩ aktuelle Policy; vollständiges Writeaudit | | X02 externer Login | Ohne Adapter keine externe Identität akzeptieren; bei späterem SSO zusätzlich falscher Issuer/Audience/State/Nonce/PKCE, Account-Link per fremder gleicher E-Mail und unerlaubter MFA-Claim verweigert | | X03 Streaming | Cookie/Origin beim Start, Ereignisse nach Rechteentzug/Logout, Scopewechsel, kein URL-Sessiontoken, keine DB-Verbindung über Verbindungsdauer gehalten | ### 14.5 Konkreter Anschluss an vorhandene Tests I - [Shinkan Sessionprofil-Test](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py:37): prüft mit Dependencyoverride, dass `/api/profile` nur das Sessionprofil verwendet. Für die Foundation auf echte Cookie-/Principalabhängigkeit übertragen und Profilheader-/Cross-Profile-Fälle ergänzen; der Bestandstest allein beweist die neue Cookieintegration nicht. - [Shinkan Kontostatus-/Rollentests](C:/Dev/shinkan-jinkendo/backend/tests/test_account_capabilities.py:14) und [Onboardingverweigerung](C:/Dev/shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py:15): Zustandsmatrix übernehmen, aktive Defaults/Disable-Flags im neuen Aufbau nicht übernehmen. - [Shinkan Graphsichtbarkeit](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py:26) und [Löschpolicy](C:/Dev/shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py:65): konkrete Privat-/Club-/Official-Grenzen und Trennung Lesen/Ändern als Parametermatrix übertragen. - [Shinkan Auth-Hardening](C:/Dev/shinkan-jinkendo/backend/tests/test_auth_hardening.py:23): TOTP, erforderliches aktuelles Passwort, Steuerzeichen und Tokenformate liefern Ausgangsfälle. Die vorhandene TOTP-Assertion ersetzt weder RFC-Vektoren noch DB-Replay-/Recoveryrennen; diese kommen gemäß M01–M11 hinzu. Die Testquellen wurden gelesen, nicht ausgeführt. Anpassung erfolgt im späteren Zielrepository; keine pauschalen Imports alter `main.py`-Apps und keine umfassenden Testläufe im Bestand. ## 15. Konkreter Implementierungsauftrag für Cursor – Phase 3.4 **Dieser Abschnitt ist ein später ausführbarer Auftrag. Er wird in Phase 3.3 nicht ausgeführt.** Zielrepository und tatsächliche Fachfunktionen benennt der Implementierungsauftrag. Fehlt diese Zielangabe, keine bestehende App als vermeintliche Foundation umbauen. Innerhalb des benannten Zielauftrags gelten die folgenden Defaults ohne neue Grundsatz-/Freigabefragen. 1. **Foundationstand prüfen.** A/B/C v0.3 verwenden; Composition Root, UoW, Problems, Settings und Frontendepoch beibehalten. Nur das benannte Zielrepository ändern, keine Quellproduktimporte zur Laufzeit. Vorhandene äquivalente Account-/DB-/Kryptografieadapter gezielt an die Verträge anschließen; kein Frameworkwechsel. 2. **Lokales Profil konkretisieren.** Wenn der Auftrag kein abweichendes Datenraummodell nennt: geschlossenes persönliches Produkt, Konto=Person, eigener Personal-Scope, lokaler administrativer Kontoprovisionierungsweg, keine öffentliche Registrierung. Club/Org erst bei tatsächlichem Fachbedarf über die beschriebenen Adapter. Keine Tenant-, Actor-, SSO- oder ACL-Editorstruktur auf Vorrat. Ein lokales Provisionierungskommando hält die ausdrücklich bestätigte Konto-/Adressprüfung fest; es darf unbekannte Webregistrierungen nicht als verifiziert kennzeichnen. 3. **Registry und Contracts implementieren.** Contexttypen aus Abschnitt 4; Session-/Scope-/Accessports produktlokal; feste Capabilitydefinitionen für tatsächlich vorhandene Routen. Alle geschützten Fachrouten benötigen Contextdependency und Servicepolicy. Eine automatisierte Routenprüfung scheitert bei nicht als öffentlich, scopefrei oder scoped klassifizierter API-Route; reine Middleware ist kein Ersatz. 4. **Schema atomar migrieren.** Lokales Accountmodell anbinden; Session-/Flow-/Faktor-/Recovery-/Rate-Strukturen aus Abschnitt 5 einschließlich der in Abschnitt 11 konkretisierten Felder anlegen. `auth_flows.initiating_session_id` und MFA-Herkunft/-Fehlversuchszähler vollständig berücksichtigen. Runtime braucht weder Owner-/DDL- noch BYPASSRLS-Rechte. Keine Migration gegen produktive DB in Tests. 5. **Browserboundary und Credentialadapter bauen.** HTTPS-Cookies, kein Domain, strikt begrenzte Proxy-/Hostkonfiguration, Origin/Referer, Fetch Metadata, Customheader, Credentialgebundener CSRF, Form-/Duplicate-/Legacy-Abwehr; Secretlogging redigieren. bcrypt und Shinkan-Dummyvergleich verwenden; 72-Byte-Grenze vor Hashaufruf. Faktoren lokal mit dem benannten Cipheradapter schützen, Key-ID-Readiness prüfen. Konfiguration bei unbekannter Umgebung/fehlendem Pflichtsecret verweigern. 6. **SessionService und MFA abschließen.** Endpunkte und DTOs aus Abschnitt 8/11 implementieren. Passwortvergleich vor Abschlusstransaktion, Revisionsprüfung darin. Fehlerresultate erst nach persistierten Fehlversuchen ausgeben; Cookies ausschließlich nach erfolgreichem Commit. Epoch-, Zweck-, Replay- und Recoveryverbrauch vollständig abdecken. Keine faktorlose Betreiber-Vollsession. Lokale Bootstrap-/Recoverykommandos gegen isolierte Test-DB prüfen. 7. **Scope-/Objektadapter integrieren.** Eigentümerbindung für den persönlichen Slice; bei Club/Org Shinkan/Kairo-Referenzen gezielt übertragen. Explizite Auswahl, gemeinsame Listen-/Objektprädikate, scoped SQL und Eltern-/Kindconstraints, frische Accessprüfung in Fach-UoW. Sperrvertrag für alle entsprechenden Entzugs-/Rollenänderungen implementieren, nicht nur für Leser. 8. **Frontend anschließen.** Ein Same-Origin-Client, Cookiecredentials, JSON-Customheader, richtiger Session-/Flow-CSRF. CSRF nur Speicher. Authmutationlock, bewusstes Scopewechselverfahren, epoch/Abort/Cacheleerung, kein automatischer Write-Retry; Login-/MFAfehler lokal behandeln. Keine neue globale Statebibliothek ohne konkreten Bedarf. 9. **Pflichttests ausführen.** Abschnitt 14: Kern und MFA vollständig; bedingte Adapterfälle für tatsächlich registrierte Funktionen. Gewählte Testbefehle und Pfade im Zielprojekt konsistent machen, reale Testcollection kontrollieren, isoliertes PostgreSQL samt Runtime-Rolle nachweisen. Ein absichtlich roter erforderlicher Securitytest muss das Gate blockieren; keine Skip- oder Exitcode-Unterdrückung. Kein Test gegen laufende Kunden-/Bestandscontainer. 10. **Lieferstand konkret belegen.** Commit, Lockfiles, OpenAPI, Testbefehle/-umgebung, tatsächlich ausgeführte Test-IDs/-Ergebnisse sowie noch nicht integrierte Adapter knapp dokumentieren. Fehlende Adapter bleiben sichtbar geschlossen. Nur bestandenes Verhalten als T markieren. Der Blueprintstatus V/K wird nicht durch Vorhandensein von Testdateien automatisch geändert. Die normale Gitea-Folge bleibt `develop → Development → Tests → bewusste menschliche Freigabe → main → Produktion`. Vor Produktion müssen die erforderlichen Auth-/Scope-/MFA-Gates wirksam bestanden sein und getesteter sowie ausgelieferter Quell-/Build-/Artefaktstand eindeutig zusammenpassen. R1 „Build once, deploy many“ bleibt bevorzugt; R2 kontrollierte reproduzierbare getrennte Builds bleibt erlaubt, mit Qualifikation des konkreten Produktionskandidaten vor dessen Einsatz. Keine neue CI/CD-Infrastruktur, kein Test ausschließlich nach Produktionsdeploy als Ersatz. Die spätere menschliche Produktionsfreigabe ist bestehender Betriebskontrakt, keine zusätzliche Blueprint-Freigabeschleife. ## 16. Prüfstand dieser Lieferung und Grenzen In Phase 3.3 entstanden ausschließlich dieser vollständige Blueprint und seine darin eingebetteten Schnittstellen-, Schema- und Testspezifikationen. Produkt-Repositories, Foundation v0.3 und ältere Dokumentversionen wurden nicht bearbeitet. Es gab keine Codeimplementierung, Paketinstallation, Migration, produktive DB-/Credentialnutzung, SSO-Einrichtung oder Anwendungstestläufe. Dokumentprüfung umfasst lokale Linkziele, Python-Syntax der illustrativen Ausschnitte, Abdeckung der zwölf beauftragten Themen und Konsistenz der Session-/Scope-/MFA-/Fehlerverträge. Das ist kein T-Nachweis für die geplante Anwendung. Der untenstehende Quellstand dokumentiert die gezielt verwendeten lokalen Dateien; eine Git-HEAD-Angabe allein behauptet keinen sauberen Checkout. Die Hashes beschreiben die tatsächlich gelesenen Dateiinhalte. Es erfolgt keine erneute Produktreifebewertung. Externe Gegenprüfung war auf drei Primärquellen begrenzt: OWASP Session Management (Hashspeicherung), OWASP CSRF (Synchronizer/Origin) und RFC 6238 (TOTP-Replay). Sie dient der Prüfung kritischer Details und ersetzt weder die Jinkendo-Referenzen noch eine umfassende neue Recherche. ### 16.1 Lokaler Quellstand Lesestand 16.10.2026; SHA-256 jeweils über die vollständige Quelldatei, nicht nur den zitierten Ausschnitt. - `shinkan-jinkendo`: Git-HEAD `f10c28e5cdcef52cc44e953a8494b4bbe35b77fe` - `mitai-jinkendo`: Git-HEAD `95453d548a2113555cd7e8f01fbbf267cbe34f3f` - `kairo-jinkendo`: Git-HEAD `ea0aa18b8dd9a55f663a996d74e63b7e3ee0dc16` - `Kansho`: Git-HEAD `89d149684eab9211d6ef21181d018de097a61783` | Gelesene Implementierungs-/Testquelle | SHA-256 | |---|---| | [shinkan-jinkendo/backend/auth.py](C:/Dev/shinkan-jinkendo/backend/auth.py) | `a7ff535b8d6d746d325327d9eb198849ca26f921d58a6ddf588e84eafc0adb7c` | | [shinkan-jinkendo/backend/routers/auth.py](C:/Dev/shinkan-jinkendo/backend/routers/auth.py) | `54a2d89dc0deded68678512faefee31da2183eb3bc8416ccc81f14b2f8a7883f` | | [shinkan-jinkendo/backend/account_lifecycle.py](C:/Dev/shinkan-jinkendo/backend/account_lifecycle.py) | `9884b1446de4476038b4f0a46a84f40c12bb2d562526e17ef43865fdafa9e2ae` | | [shinkan-jinkendo/backend/account_onboarding_gate.py](C:/Dev/shinkan-jinkendo/backend/account_onboarding_gate.py) | `348e863027f097fb7942cb49da06e3bbab540fc76a977fafae1dbd0dfcbe386c` | | [shinkan-jinkendo/backend/tenant_context.py](C:/Dev/shinkan-jinkendo/backend/tenant_context.py) | `41048e11fec89981c4cba33d887e9dfb8b4c9e1d7b78a2be6b3f31b2170cd6be` | | [shinkan-jinkendo/backend/capabilities.py](C:/Dev/shinkan-jinkendo/backend/capabilities.py) | `b31e0648e4c0709d69835bc52c727873784830fba1f589f3dde6f06e697a799e` | | [shinkan-jinkendo/backend/rights_registry.py](C:/Dev/shinkan-jinkendo/backend/rights_registry.py) | `49992f1993b2e0d0e3bc7e50d44862d423bd68907b5a5d7f2f019edb99385555` | | [shinkan-jinkendo/backend/totp_auth.py](C:/Dev/shinkan-jinkendo/backend/totp_auth.py) | `00c39c9c1bcf9ed78f6ba71019e025a92101d81df4a5caee4927f784e0128e62` | | [shinkan-jinkendo/backend/tests/test_security_release.py](C:/Dev/shinkan-jinkendo/backend/tests/test_security_release.py) | `94f5b353eed18d86159f834a8d831c054280c7aa61c20cf4fd29b900811d15f0` | | [shinkan-jinkendo/backend/tests/test_auth_hardening.py](C:/Dev/shinkan-jinkendo/backend/tests/test_auth_hardening.py) | `329eb0ddf1cf636fc56f55220274a14c41ce8e92ce758e31e960dd7cca5a348e` | | [shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py](C:/Dev/shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py) | `9d8cda30c838bc24a4d922e347188ce84156faf3b724a306e3541af6e6b13fa3` | | [shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py](C:/Dev/shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py) | `594f201c107098397521ff41a25ebb619138ee2c88ca04f6301356575bb201fd` | | [shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py](C:/Dev/shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py) | `0c14fd49ba0df953278ab53bfc2f0fd172035dd3c1fa9bc9841d14522b80bc94` | | [mitai-jinkendo/backend/auth.py](C:/Dev/mitai-jinkendo/backend/auth.py) | `25d666b3f69cac0d18fa7abc969f51b16b889d6b6ff41d6f054d0d39941e8c1b` | | [mitai-jinkendo/backend/routers/profiles.py](C:/Dev/mitai-jinkendo/backend/routers/profiles.py) | `8d017775507e24181cdaf966bd9f403572cd3eb91037d3425c3197b40271718e` | | [kairo-jinkendo/backend/tenant_context.py](C:/Dev/kairo-jinkendo/backend/tenant_context.py) | `f40b7379cef5449e94a997791f36a48a0340de8cf58e539b908bed5e3cd08df1` | | [kairo-jinkendo/backend/operational_auth.py](C:/Dev/kairo-jinkendo/backend/operational_auth.py) | `765150b8a85e4e2d5802a4365d4b19aa6531c00fcebedc6f2306562dc9b83c36` | | [kairo-jinkendo/backend/services/actor_service_tokens.py](C:/Dev/kairo-jinkendo/backend/services/actor_service_tokens.py) | `c2a66ee02d1e745cedf9f0ce49d442e75bd21727a85c91ce97a78c501fc7c4a9` | | [Kansho/backend/auth.py](C:/Dev/Kansho/backend/auth.py) | `53956af1767fa8fbe32d8262b273c14dc2f1f1786dff01ed1c5a8c4fdd41d111` | | [Kansho/backend/journal_store.py](C:/Dev/Kansho/backend/journal_store.py) | `d3b825bc977adb25cfd05c37c44dbd5f202c5674cfa571c8a10e50b0b9d4ae88` | | [Kansho/backend/routers/journal.py](C:/Dev/Kansho/backend/routers/journal.py) | `9ee1e6fb5434a96e247833a2102151c744eb1e58507db55de158c8f4f91546b9` | | [Kansho/docs/architecture/functional/guardrails.md](C:/Dev/Kansho/docs/architecture/functional/guardrails.md) | `deadd95b5019fe807026616f6ff74a2467d9d951702c032573d59f27c125dc4b` | **Ende des Phase-3.3-Auftrags. Die tatsächliche Implementierung beginnt erst mit dem gesonderten Phase-3.4-Auftrag.**