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:

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:

// 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.