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 };
```

## Integrationstests

Um sicherzustellen, dass die Rollenkontrolle korrekt funktioniert, wurden Integrationstests hinzugefügt. Diese Tests überprüfen:

1. Ob nicht-authentifizierte Nutzer auf geschützte Endpunkte keinen Zugriff erhalten
2. Ob Nutzer mit falscher Rolle auf geschützte Endpunkte keinen Zugriff erhalten
3. Ob Nutzer mit korrekter Rolle auf geschützte Endpunkte Zugriff erhalten

Die Tests befinden sich in `test/roles.test.js`.