helpyourneighbour/docs/roles-and-permissions.md

# 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 (implementiert in `backend/middleware/role.middleware.js`)
- 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

## Implementierung

Die Rollen werden in der Datenbank als `role`-Feld im `users`-Table gespeichert. Die Middleware `requireRole` prüft, ob der eingeloggte Benutzer die benötigte Rolle besitzt.

### Beispiel für eine geschützte Route:

```javascript
const express = require('express');
const router = express.Router();
const { requireRole } = require('../middleware/role.middleware');

// Nur Admins dürfen diese Route aufrufen
router.delete('/users/:userId', requireRole(['admin']), async (req, res) => {
  // ...
});
```

### Beispiel für eine Middleware zur Rollenprüfung:

```javascript
// backend/middleware/role.middleware.js
const requireRole = (allowedRoles) => {
  return (req, res, next) => {
    const userRole = req.user.role; // aus JWT
    if (!allowedRoles.includes(userRole)) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    next();
  };
};

module.exports = { requireRole };
```