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