From 91eb0828e312a67f34e626edac42d0b5ed79cccc Mon Sep 17 00:00:00 2001
From: BibaBot Jarvis <jarvis@biba.bot>
Date: Sun, 15 Mar 2026 23:06:41 +0000
Subject: [PATCH] docs: add role-permission matrix documentation

---
 docs/role-permission-matrix.md | 75 ++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 docs/role-permission-matrix.md

diff --git a/docs/role-permission-matrix.md b/docs/role-permission-matrix.md
new file mode 100644
index 0000000..a9ddf9d
--- /dev/null
+++ b/docs/role-permission-matrix.md
@@ -0,0 +1,75 @@
+# Rollen- und Rechtekonzept
+
+## Rollen
+
+- `user`: Standardrolle fuer alle registrierten Nutzer
+- `moderator`: Operative Moderation (Disputes, Abuse-Faelle)
+- `admin`: Systemadministration und Policy-Overrides
+
+## Prinzipien
+
+- **Least Privilege**: Jede Rolle bekommt nur notwendige Rechte.
+- **Default Deny**: Nicht explizit erlaubte Aktionen sind verboten.
+- **Audit First**: Sensible Aktionen werden protokolliert.
+
+## Berechtigungen nach Bereich
+
+### Auth & Profil
+
+- `user`: eigenes Profil lesen/aendern
+- `moderator`: keine Profilaenderung fuer fremde User
+- `admin`: administrative Sperrung/Entsperrung von Accounts
+
+### Requests / Offers / Deals
+
+- `user`: eigene Requests/Offers erstellen, eigene Deals einsehen
+- `moderator`: Read-Only auf alle Deals bei gemeldeten Vorfaellen
+- `admin`: Read-Only auf alle Deals, Ausnahmeeingriffe nur dokumentiert
+
+### Contacts / Address / PII
+
+- `user`: nur eigene PII und freigegebene Deal-Kontaktdaten
+- `moderator`: keine Vollansicht von PII, nur minimierte Fallsicht
+- `admin`: Zugriff nur fuer Betrieb/Sicherheit, jede Einsicht auditpflichtig
+
+### Disputes
+
+- `user`: Dispute erstellen, Evidenz nachreichen
+- `moderator`: Statuswechsel (`open/evidence/mediation/resolved`), Entscheidungsvorschlag
+- `admin`: Finalentscheid/Override mit Pflichtbegruendung
+
+## Rollenmatrix (Kurzform)
+
+| Aktion | user | moderator | admin |
+|---|---:|---:|---:|
+| Request erstellen | ✅ | ❌ | ❌ |
+| Offer abgeben | ✅ | ❌ | ❌ |
+| Eigenes Profil aendern | ✅ | ✅ (eigenes) | ✅ (eigenes) |
+| Dispute oeffnen | ✅ | ✅ | ✅ |
+| Dispute-Status aendern | ❌ | ✅ | ✅ |
+| Dispute final entscheiden | ❌ | ⚠️ (nur Vorschlag) | ✅ |
+| User sperren | ❌ | ❌ | ✅ |
+
+## Technische Durchsetzung
+
+- JWT enthaelt `role` Claim (`user|moderator|admin`)
+- Serverseitige Middleware `requireRole([...])` fuer Endpunkte
+- Sensible Aktionen schreiben Audit-Eintrag mit:
+  - actorUserId
+  - action
+  - targetType/targetId
+  - reason
+  - timestamp
+
+## Audit-Events (Mindeststandard)
+
+- `USER_SUSPEND`, `USER_UNSUSPEND`
+- `DISPUTE_STATUS_CHANGE`, `DISPUTE_DECISION`
+- `PII_ACCESS_GRANTED`, `PII_ACCESS_VIEWED`
+
+## Definition of Done
+
+- Rollenmodell im Repo dokumentiert
+- Rollen-Claims in API-Security-Konzept referenziert
+- Role-Checks fuer neue Endpunkte verpflichtend
+- Audit-Events fuer Admin/Moderation spezifiziert
\ No newline at end of file