Rollen & Capabilities

Diese Seite beschreibt das Rollen- und Berechtigungsmodell auf technischer Ebene. Sie richtet sich an Entwickler. Die nutzerorientierte Variante steht unter Rollen & Berechtigungen.

Zwei Rollen-Achsen — eine Rolle pro Nutzer

KanzleiSynchron unterscheidet zwei Achsen (backend/api/src/auth.rs), und ein Nutzer hat genau eine Rolle:

• Mandanten-Rollen — Nutzer eines Mandanten. Die App: Importe, Einstellungen, Team, Perioden, Ausnahmen.
• Ops-Rollen — KS-internes Personal. Zugriff nur über /ops/** (die mandantenübergreifende Konsole), keine Mandanten-Nutzer.

super_admin ist nur die /ops-Konsole und hat keine Upload-/App-Fähigkeit; merchant_admin ist die App. Um beide Ebenen zu nutzen, brauchen Sie zwei getrennte Konten.

Registrierung & Erststart

Es werden keine Standard-Zugangsdaten ausgeliefert. Nutzer registrieren sich selbst unter /sign-up:

• Bei einem frischen Deploy wird die erste Registrierung automatisch zu merchant_admin auf dem Standard-Mandanten befördert (kein SQL nötig, damit Onboarding + App funktionieren). Sie erhält nie automatisch super_admin.
• Jede spätere Registrierung startet als pending (null Rechte): von allem außer /me und /auth ausgeschlossen, mit 403 "Your account is awaiting activation by a tenant administrator". Der Onboarding-Schritt Loslegen erfordert merchant_admin.

Einen Pending-Nutzer befördern Sie entweder in der App (ein bestehender Admin über Einstellungen → Team) oder per Betreiber-Befehl auf dem VPS:

sudo ./ks-setup-helper.sh --grant-admin <email> [--grant-role merchant_admin|super_admin]

Standardrolle ist merchant_admin; mit --grant-role super_admin wird die /ops-Konsole gewährt. --dry-run zeigt eine Vorschau, ohne die DB zu verändern.

Mandanten-Rollen

Die Mandanten-Ebene hat diese Rollen: owner, merchant_admin (= Admin), accountant (= Mitglied), reviewer, viewer und pending. Das Einladungsformular unter /settings/team (frontend/src/app/(app)/settings/team/page.tsx) bietet die zuweisbare Teilmenge an:

Rollen-Schlüssel	Anzeigename	Darf
merchant_admin	Kanzlei-Admin	Team einladen/sperren, Mandanteneinstellungen ändern, Löschung (Erasure) auslösen. Admin / Eigentümer eines Mandanten.
reviewer	Sachbearbeiter / Mitarbeiter	Tägliche Arbeit: Importe, Abstimmung, Ausnahmen. Kein Team-Management, keine Einstellungsänderung.
viewer	Betrachter	Nur lesend.
pending	Pending	Selbst registriert, null Rechte bis zur Beförderung.

Capability-Helfer (Frontend)

Das Frontend gated Admin-Oberflächen über frontend/src/lib/role-capabilities.ts statt über harte Rollen-Vergleiche:

Helfer	Erlaubt für
canViewAdmin(r)	super_admin, support, compliance_officer, read_only, merchant_admin
canMutateTenant(r)	super_admin, merchant_admin
canManageTeam(r)	super_admin, merchant_admin
canRunErasure(r)	super_admin, compliance_officer, merchant_admin

Zusätzlich liefert /me ein capabilities: string[]-Array. Ops-Nutzer haben role: null und ein separates ops_role, weshalb rollenbasierte Gates für sie fail-closed sind; verwende daher hasCapability(caps, cap) mit den Konstanten aus OPS_CAPS / TENANT_CAPS.

Interne Ops-Rollen (Backend)

Vier abgestufte interne Rollen ersetzen das frühere breite internal_ops (backend/api/src/auth.rs, Sprint 10 §13.2). merchant_admin bleibt als Migrationspfad in allen Ops-Gates zugelassen.

Rolle	Mandanten	DPR / Erasure	Issues	Mutieren?
super_admin	ja	ja	ja	ja
support	lesen	nein	ja	Issues
compliance_officer	lesen	ja	lesen	DPR
read_only	lesen	lesen	lesen	nein

Die Backend-Gates dazu:

• require_super_admin — super_admin (plus merchant_admin für Kompatibilität).
• require_support — super_admin oder support.
• require_compliance — super_admin oder compliance_officer (DPR-Akten, DSGVO-Art.-17-Löschung).
• require_read_only_ok — alle Ops-Rollen dürfen lesende GETs; read_only scheitert an den mutierenden Gates.

OPS_ROLES umfasst super_admin, support, compliance_officer, read_only und das aus Kompatibilitätsgründen geführte internal_ops.

Vier-Augen-Prinzip

Der Periodenabschluss erfordert, dass eine andere Person abschließt als die, die die Periode angelegt hat. Daraus folgt: Ein Mandant braucht mindestens zwei Nutzer mit Zugriff, sonst lässt sich der Abschluss nicht durchführen. Mehr dazu unter Rollen & Berechtigungen.