Files
tsumugu/docs/reference/Jinkendo_Auth_Session_Scope_Blueprint.md
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

100 KiB
Raw Permalink Blame History

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, der Foundation-Blueprint v0.3 und die technischen Festlegungen v0.3. 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 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, das Quellenregister, das Testregister und die Guardrailabschnitte. 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, Login 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, Onboardingtests 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, Sichtbarkeit 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, Registry 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, Recoveryverbrauch 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, Profilauflösung 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, Operational Auth, Tenant 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, Journalrouter, Ownerfilter, Spaceprüfung 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 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

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.

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.

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:

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.

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.1 Cookievertrag

Ausgabe erst nach erfolgreichem DB-Commit:

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.

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:

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

{
  "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:

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

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: 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 und Onboardingverweigerung: Zustandsmatrix übernehmen, aktive Defaults/Disable-Flags im neuen Aufbau nicht übernehmen.
  • Shinkan Graphsichtbarkeit und Löschpolicy: konkrete Privat-/Club-/Official-Grenzen und Trennung Lesen/Ändern als Parametermatrix übertragen.
  • Shinkan Auth-Hardening: 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 a7ff535b8d6d746d325327d9eb198849ca26f921d58a6ddf588e84eafc0adb7c
shinkan-jinkendo/backend/routers/auth.py 54a2d89dc0deded68678512faefee31da2183eb3bc8416ccc81f14b2f8a7883f
shinkan-jinkendo/backend/account_lifecycle.py 9884b1446de4476038b4f0a46a84f40c12bb2d562526e17ef43865fdafa9e2ae
shinkan-jinkendo/backend/account_onboarding_gate.py 348e863027f097fb7942cb49da06e3bbab540fc76a977fafae1dbd0dfcbe386c
shinkan-jinkendo/backend/tenant_context.py 41048e11fec89981c4cba33d887e9dfb8b4c9e1d7b78a2be6b3f31b2170cd6be
shinkan-jinkendo/backend/capabilities.py b31e0648e4c0709d69835bc52c727873784830fba1f589f3dde6f06e697a799e
shinkan-jinkendo/backend/rights_registry.py 49992f1993b2e0d0e3bc7e50d44862d423bd68907b5a5d7f2f019edb99385555
shinkan-jinkendo/backend/totp_auth.py 00c39c9c1bcf9ed78f6ba71019e025a92101d81df4a5caee4927f784e0128e62
shinkan-jinkendo/backend/tests/test_security_release.py 94f5b353eed18d86159f834a8d831c054280c7aa61c20cf4fd29b900811d15f0
shinkan-jinkendo/backend/tests/test_auth_hardening.py 329eb0ddf1cf636fc56f55220274a14c41ce8e92ce758e31e960dd7cca5a348e
shinkan-jinkendo/backend/tests/test_account_onboarding_gate.py 9d8cda30c838bc24a4d922e347188ce84156faf3b724a306e3541af6e6b13fa3
shinkan-jinkendo/backend/tests/test_exercises_delete_policy.py 594f201c107098397521ff41a25ebb619138ee2c88ca04f6301356575bb201fd
shinkan-jinkendo/backend/tests/test_exercise_progression_graph_visibility.py 0c14fd49ba0df953278ab53bfc2f0fd172035dd3c1fa9bc9841d14522b80bc94
mitai-jinkendo/backend/auth.py 25d666b3f69cac0d18fa7abc969f51b16b889d6b6ff41d6f054d0d39941e8c1b
mitai-jinkendo/backend/routers/profiles.py 8d017775507e24181cdaf966bd9f403572cd3eb91037d3425c3197b40271718e
kairo-jinkendo/backend/tenant_context.py f40b7379cef5449e94a997791f36a48a0340de8cf58e539b908bed5e3cd08df1
kairo-jinkendo/backend/operational_auth.py 765150b8a85e4e2d5802a4365d4b19aa6531c00fcebedc6f2306562dc9b83c36
kairo-jinkendo/backend/services/actor_service_tokens.py c2a66ee02d1e745cedf9f0ce49d442e75bd21727a85c91ce97a78c501fc7c4a9
Kansho/backend/auth.py 53956af1767fa8fbe32d8262b273c14dc2f1f1786dff01ed1c5a8c4fdd41d111
Kansho/backend/journal_store.py d3b825bc977adb25cfd05c37c44dbd5f202c5674cfa571c8a10e50b0b9d4ae88
Kansho/backend/routers/journal.py 9ee1e6fb5434a96e247833a2102151c744eb1e58507db55de158c8f4f91546b9
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.