AfiS-Aktensystem/docs/03-auth-und-rechte.md

Authentifizierung und Berechtigungen

Grundsatz

OAuth klärt, wer jemand ist. Der Bot klärt, was er darf. Das Discord-Zugangstoken des Nutzers wird nach dem Callback verworfen und nie wieder benutzt.

Login-Ablauf

1. Nutzer klickt „Mit Discord anmelden". Auth.js startet OAuth2 mit Scope identify, dazu state und PKCE.
2. Im Callback liest die App nur id, username, global_name, avatar.
3. Die App fragt serverseitig mit dem Bot-Token GET /guilds/{GUILD_ID}/members/{userId}.
   • 404 → Login abgelehnt, Seite „Du bist nicht auf dem AfiS-Discord". Kein Konto anlegen.
   • 200 → Rollen werden übernommen, User wird angelegt oder aktualisiert.
4. Eigene Session in der Datenbank, Cookie mit HttpOnly, Secure, SameSite=Lax, Laufzeit 30 Tage, gleitende Verlängerung.
5. In der Session steht nur userId und sessionId. Rechte werden pro Request aufgelöst.

Im Developer Portal muss das Server Members Intent aktiviert sein, sonst liefert der Bot keine Rollen.

Rechteauflösung

type EffectivePermissions = {
  userId: string
  clearanceLevel: number        // höchste Stufe aller Rollen
  permissions: Set<Permission>  // Vereinigung aller Rollen
  isAdmin: boolean              // aus BOOTSTRAP_ADMIN_IDS oder Recht 'admin'
}

Auflösung aus UserRole × RoleMapping. Ergebnis wird pro Request einmal berechnet und in einem prozesslokalen LRU-Cache (60 s TTL) gehalten. Der Cache wird bei pg_notify member_changed oder role_mapping_changed sofort verworfen.

Rechte-Enum:

case.read case.create case.edit case.close case.reopen case.delete
case.edit_closed          # Änderungen an abgeschlossenen Fällen
entry.create entry.correct
entry.edit_own            # eigene Einträge nachträglich ändern
entry.edit_any            # fremde Einträge ändern, für die Leitung
entry.retract             # Eintrag zurückziehen (kein Löschen)
personnel.read personnel.edit
template.manage roles.manage audit.read export.approve
admin

`entry.edit_own`, `entry.edit_any` und `entry.retract` sind im Auslieferungszustand **keiner
Rolle zugeordnet**. Der Leiter schaltet sie bewusst frei, wenn er sie will.

Notfallzugang

BOOTSTRAP_ADMIN_IDS in der .env enthält eine oder zwei Discord-IDs. Diese Nutzer haben immer Stufe 5 und alle Rechte, unabhängig vom Rollen-Mapping. Ohne das sperrt man sich beim ersten Fehler in der Rollenverwaltung selbst aus.

Zugriffsprüfung auf Akten

Reihenfolge, erste zutreffende Regel gewinnt:

1. Nutzer steht in CaseExclusion → kein Zugriff, egal welche Stufe. Deckt den Fall ab, dass gegen einen hochrangigen Mitarbeiter ermittelt wird.
2. Nutzer ist Admin → Zugriff, wird protokolliert.
3. Nutzer ist Beteiligter (CaseParticipant) → Zugriff.
4. user.clearanceLevel >= case.classification → Zugriff.
5. Sonst kein Zugriff.

Kein Zugriff bedeutet:

• Ist die Stufe als hiddenBelow markiert: 404, die Akte existiert für den Nutzer nicht.
• Sonst: Eintrag in Listen sichtbar, Titel und Inhalt gesperrt, Detailseite zeigt Sperrhinweis.

Schreibende Zugriffe und die eigene Stufe

Die Abschnitte oben regeln das Lesen. Fürs Schreiben gilt zusätzlich:

Niemand legt eine Akte über der eigenen Freigabestufe an. Wer Stufe 2 hat, legt Akten bis Stufe 2 an, nicht bis Stufe 4. Sonst erzeugt man Akten, die man selbst nicht mehr sehen kann, und umgeht nebenbei die Sichtbarkeitsregel.

Ändern und Löschen setzt Lesezugriff voraus. Was jemand nicht sehen darf, darf er nicht anfassen — auch nicht über einen direkten Aufruf der Server Action. Die Prüfung ist dieselbe wie beim Lesen (visibleCaseWhere), plus das nötige Recht.

Die Klassifizierung ist nachträglich änderbar, mit denselben Grenzen:

• die neue Stufe darf die eigene Stufe nicht übersteigen
• die Akte muss vorher lesbar gewesen sein
• es braucht das Recht case.edit
• die Änderung erzeugt einen SYSTEM-Eintrag im Verlauf und einen AuditLog-Eintrag mit alter und neuer Stufe. Eine Herabstufung ist der heikelste Vorgang im ganzen System: sie macht Inhalte für Leute sichtbar, die sie vorher nicht sehen durften, und muss deshalb ohne Nachfragen nachvollziehbar sein.

Für Abschnitte und Verlaufseinträge gilt dasselbe eine Ebene tiefer: minClearance lässt sich nicht über die eigene Stufe heben, und eine Erhöhung wirkt rückwirkend auf alle Versionen (siehe docs/05-akten-und-vorlagen.md).

Ausnahmsweiser Zugang läuft über CaseParticipant: wer als Beteiligter eingetragen ist, liest die Akte unabhängig von seiner Stufe. Das ist der vorgesehene Weg, jemanden gezielt hinzuzuziehen, ohne ihm allgemein eine höhere Stufe zu geben. Beteiligte hinzuzufügen setzt case.edit voraus und wird protokolliert.

Die Gegenprobe bleibt der CaseExclusion: er schlägt jede Stufe und auch den Admin.

Umsetzung in Prisma

Die Prüfung wird nie in JavaScript nachgelagert. lib/access/caseFilter.ts liefert ein wiederverwendbares Where-Fragment:

export function visibleCaseWhere(p: EffectivePermissions): Prisma.CaseWhereInput {
  if (p.isAdmin) return {}
  return {
    AND: [
      { exclusions: { none: { userId: p.userId } } },
      {
        OR: [
          { participants: { some: { userId: p.userId } } },
          { classification: { lte: p.clearanceLevel } },
        ],
      },
    ],
  }
}

Dasselbe Muster für CaseEntry, Attachment, PersonnelFile und die Suche. Trefferzahlen und Paginierung laufen über dieselbe Abfrage, damit sich aus Lücken nichts ableiten lässt.

Für Abschnitte und Schwärzungen gibt es eine zweite Ebene: CaseSection.minClearance. Felder oberhalb der Nutzerstufe werden serverseitig durch einen Platzhalter ersetzt, bevor die Daten den Server verlassen. Nie im Client ausblenden.

Sessions beenden

Der Worker meldet guildMemberRemove oder den Verlust einer AfiS-Rolle. Die App löscht dann alle Sessions des Nutzers und markiert User.isActive = false. Der Datensatz bleibt, damit Autorenangaben in alten Akten gültig bleiben.

Tests, die es geben muss

• Nutzer ohne Guild-Mitgliedschaft kann sich nicht anmelden
• Nutzer mit Stufe 2 bekommt für eine Stufe-4-Akte 404, nicht 403
• Ausgeschlossener Nutzer mit Stufe 5 bekommt 404
• Suche mit Stufe 1 liefert für eine Stufe-3-Akte keinen Treffer und keine veränderte Trefferzahl
• Rollenentzug in Discord beendet laufende Sessions innerhalb von 5 Sekunden
• Nutzer ohne entry.edit_any kann einen fremden Eintrag nicht ändern, auch nicht über einen direkten Aufruf der Server Action
• Nutzer ohne entry.edit_own kann nach Ablauf der Karenzzeit den eigenen Eintrag nicht ändern
• Ein Eintrag, dessen minClearance erhöht wurde, ist auch in der Versionshistorie für niedrigere Stufen nicht lesbar
• Ein DELETE auf CaseEntry verändert nichts, weder über Prisma noch über rohes SQL
• Autor und createdAt bleiben nach einer Änderung unverändert