feat: RBAC Rollen & Rechte (Phase 1 - Datenmodell, Roles-Verwaltung, Guard-Infrastruktur)

Replaces the fixed 5-value Role enum with a database-driven Role/Permission
model: admins can create custom roles with a precise per-resource/action
permission set (83-key code-owned catalog), instead of being locked to
ADMIN/BEEKEEPER/STAFF/READONLY/API_CLIENT.

- New Role/Permission/RolePermission tables; legacy Role enum renamed to
  LegacyRole and kept as User.legacyRole so all existing @Roles() call
  sites keep working unchanged during the migration.
- New RolesController/RolesService (CRUD, permission-set editing,
  deactivate/reactivate) with lockout-prevention invariants: system roles
  (ADMIN) can't be edited or deactivated, and a role still assigned to
  users can't be deactivated.
- New PermissionResolverService (30s-cached, DB-fresh per user) and
  PermissionsGuard + @RequirePermission(), registered as an additional
  APP_GUARD alongside the legacy RolesGuard so both systems run
  side-by-side until controllers are migrated in Phase 2.
- PermissionCatalogSyncService seeds any new catalog entries into the DB
  on boot, so future features only touch the TS catalog.
- New GET /auth/me returns the caller's role and effective permissions.
- Migration hand-written (destructive column rename) with grants derived
  from a fresh grep of every existing @Roles() call site, verified
  against 5 controllers read in full for STAFF's exact write boundary.
- test/roles.e2e-spec.ts covers the new endpoints and invariants end to
  end; test/authorization-coverage.e2e-spec.ts added but skipped until
  Phase 2 gives every controller a @RequirePermission.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

ApiCore-Backend/src/auth/auth.controller.ts

@@ -1,6 +1,7 @@
 import {
   Body,
   Controller,
+  Get,
   HttpCode,
   HttpStatus,
   Post,
@@ -8,13 +9,15 @@ import {
   Res,
   UnauthorizedException,
 } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
 import { Throttle } from '@nestjs/throttler';
 import type { Request, Response } from 'express';
 import { Public } from './decorators/public.decorator';
+import { CurrentUser } from './decorators/current-user.decorator';
+import type { AuthenticatedUser } from './types/authenticated-user';
 import { LoginDto } from './dto/login.dto';
 import { AccessTokenDto } from './dto/access-token.dto';
-import { AuthService } from './auth.service';
+import { AuthService, CurrentUserProfile } from './auth.service';
 import { parseDurationToMs } from './util/duration';
 
 const REFRESH_TOKEN_COOKIE = 'refreshToken';
@@ -96,4 +99,10 @@ export class AuthController {
     await this.authService.logout(this.extractRefreshToken(req));
     this.clearRefreshTokenCookie(res);
   }
+
+  @ApiBearerAuth()
+  @Get('me')
+  me(@CurrentUser() user: AuthenticatedUser): Promise<CurrentUserProfile> {
+    return this.authService.getCurrentUserProfile(user.id);
+  }
 }

ApiCore-Backend/src/auth/auth.service.spec.ts

@@ -18,11 +18,12 @@ describe('AuthService', () => {
   };
   let jwtService: { sign: jest.Mock };
   let auditLog: { record: jest.Mock };
+  let permissionResolver: { getPermissions: jest.Mock };
 
   const activeUser = {
     id: 'user-1',
     email: '[email protected]',
-    role: 'STAFF',
+    legacyRole: 'STAFF',
     isActive: true,
     passwordHash: '',
   };
@@ -40,12 +41,16 @@ describe('AuthService', () => {
     };
     jwtService = { sign: jest.fn().mockReturnValue('signed.jwt.token') };
     auditLog = { record: jest.fn().mockResolvedValue(undefined) };
+    permissionResolver = {
+      getPermissions: jest.fn().mockResolvedValue(new Set()),
+    };
 
     authService = new AuthService(
       usersService as unknown as UsersService,
       prisma as unknown as PrismaService,
       jwtService as never,
       auditLog as unknown as AuditLogService,
+      permissionResolver as never,
     );
   });
 

ApiCore-Backend/src/auth/auth.service.ts

@@ -5,6 +5,7 @@ import * as crypto from 'node:crypto';
 import { PrismaService } from '../prisma/prisma.service';
 import { UsersService } from '../users/users.service';
 import { AuditLogService } from '../audit/audit-log.service';
+import { PermissionResolverService } from './permissions/permission-resolver.service';
 import { AuthenticatedUser } from './types/authenticated-user';
 import { parseDurationToMs } from './util/duration';
 
@@ -13,6 +14,16 @@ interface AuthTokens {
   refreshToken: string;
 }
 
+export interface CurrentUserProfile {
+  id: string;
+  email: string;
+  name: string;
+  role: string;
+  roleKey: string;
+  roleName: string;
+  permissions: string[];
+}
+
 const REFRESH_TOKEN_BYTES = 40;
 
 @Injectable()
@@ -22,8 +33,26 @@ export class AuthService {
     private readonly prisma: PrismaService,
     private readonly jwtService: JwtService,
     private readonly auditLog: AuditLogService,
+    private readonly permissionResolver: PermissionResolverService,
   ) {}
 
+  async getCurrentUserProfile(userId: string): Promise<CurrentUserProfile> {
+    const user = await this.prisma.user.findUniqueOrThrow({
+      where: { id: userId },
+      include: { role: { select: { key: true, name: true } } },
+    });
+    const permissions = await this.permissionResolver.getPermissions(userId);
+    return {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      role: user.legacyRole,
+      roleKey: user.role.key,
+      roleName: user.role.name,
+      permissions: Array.from(permissions),
+    };
+  }
+
   private hashRefreshToken(token: string): string {
     return crypto.createHash('sha256').update(token).digest('hex');
   }
@@ -77,7 +106,7 @@ export class AuthService {
     const authenticatedUser: AuthenticatedUser = {
       id: user.id,
       email: user.email,
-      role: user.role,
+      role: user.legacyRole,
     };
     const accessToken = this.signAccessToken(authenticatedUser);
     const refreshToken = await this.issueRefreshToken(user.id);
@@ -109,7 +138,7 @@ export class AuthService {
     const authenticatedUser: AuthenticatedUser = {
       id: user.id,
       email: user.email,
-      role: user.role,
+      role: user.legacyRole,
     };
     const accessToken = this.signAccessToken(authenticatedUser);
     const newRefreshToken = await this.issueRefreshToken(user.id);

ApiCore-Backend/src/auth/decorators/require-permission.decorator.ts

@@ -0,0 +1,11 @@
+import { SetMetadata } from '@nestjs/common';
+import { PermissionKey } from '../permissions/permission-catalog';
+
+export const REQUIRE_PERMISSION_KEY = 'require-permission';
+
+/**
+ * Grants access if the caller holds ANY of the given permission keys
+ * (OR semantics, matching the legacy @Roles(...) behaviour it replaces).
+ */
+export const RequirePermission = (...keys: PermissionKey[]) =>
+  SetMetadata(REQUIRE_PERMISSION_KEY, keys);

ApiCore-Backend/src/auth/decorators/roles.decorator.ts

@@ -1,5 +1,5 @@
 import { SetMetadata } from '@nestjs/common';
-import { Role } from '../../../generated/prisma';
+import { LegacyRole as Role } from '../../../generated/prisma';
 
 export const ROLES_KEY = 'roles';
 export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

ApiCore-Backend/src/auth/guards/permissions.guard.ts

@@ -0,0 +1,39 @@
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { REQUIRE_PERMISSION_KEY } from '../decorators/require-permission.decorator';
+import { PermissionKey } from '../permissions/permission-catalog';
+import { PermissionResolverService } from '../permissions/permission-resolver.service';
+import { AuthenticatedUser } from '../types/authenticated-user';
+
+interface RequestWithUser {
+  user?: AuthenticatedUser;
+}
+
+/**
+ * Runs alongside the legacy RolesGuard during the RBAC migration: routes
+ * without @RequirePermission are untouched here (still governed solely by
+ * @Roles), routes with it are enforced against the caller's live
+ * permission set. Both guards must pass for a request to proceed.
+ */
+@Injectable()
+export class PermissionsGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly permissionResolver: PermissionResolverService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const requiredPermissions = this.reflector.getAllAndOverride<
+      PermissionKey[]
+    >(REQUIRE_PERMISSION_KEY, [context.getHandler(), context.getClass()]);
+    if (!requiredPermissions || requiredPermissions.length === 0) {
+      return true;
+    }
+    const request = context.switchToHttp().getRequest<RequestWithUser>();
+    const user = request.user;
+    if (!user) {
+      return false;
+    }
+    return this.permissionResolver.hasAny(user.id, requiredPermissions);
+  }
+}

ApiCore-Backend/src/auth/guards/roles.guard.spec.ts

@@ -1,7 +1,7 @@
 import { ExecutionContext } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { RolesGuard } from './roles.guard';
-import { Role } from '../../../generated/prisma';
+import { LegacyRole as Role } from '../../../generated/prisma';
 
 function createContext(user: { role: Role } | undefined): ExecutionContext {
   return {

ApiCore-Backend/src/auth/guards/roles.guard.ts

@@ -1,6 +1,6 @@
 import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
-import { Role } from '../../../generated/prisma';
+import { LegacyRole as Role } from '../../../generated/prisma';
 import { ROLES_KEY } from '../decorators/roles.decorator';
 import { AuthenticatedUser } from '../types/authenticated-user';
 

ApiCore-Backend/src/auth/permissions/permission-catalog-sync.service.ts

@@ -0,0 +1,51 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { PrismaService } from '../../prisma/prisma.service';
+import { PERMISSION_CATALOG } from './permission-catalog';
+
+/**
+ * Keeps the Permission table in step with the code-owned PERMISSION_CATALOG
+ * so a future feature only needs to add an entry to the catalog file, not
+ * hand-write a migration to seed it too. Runs once on boot: inserts any
+ * catalog entry missing from the database. Never deletes a Permission row
+ * that fell out of the catalog (only warns) — a role's grants must not
+ * silently disappear because of a typo or a reordered catalog edit.
+ */
+@Injectable()
+export class PermissionCatalogSyncService implements OnModuleInit {
+  private readonly logger = new Logger(PermissionCatalogSyncService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  async onModuleInit(): Promise<void> {
+    const existing = await this.prisma.permission.findMany({
+      select: { key: true },
+    });
+    const existingKeys = new Set(existing.map((permission) => permission.key));
+
+    const missing = PERMISSION_CATALOG.filter(
+      (entry) => !existingKeys.has(entry.key),
+    );
+    for (const entry of missing) {
+      await this.prisma.permission.create({ data: entry });
+    }
+    if (missing.length > 0) {
+      this.logger.log(
+        `Synced ${missing.length} new permission(s) from the code catalog: ${missing
+          .map((entry) => entry.key)
+          .join(', ')}`,
+      );
+    }
+
+    const catalogKeys = new Set(PERMISSION_CATALOG.map((entry) => entry.key));
+    const orphaned = existing.filter(
+      (permission) => !catalogKeys.has(permission.key),
+    );
+    if (orphaned.length > 0) {
+      this.logger.warn(
+        `${orphaned.length} permission(s) exist in the database but not in the code catalog (left untouched): ${orphaned
+          .map((permission) => permission.key)
+          .join(', ')}`,
+      );
+    }
+  }
+}

ApiCore-Backend/src/auth/permissions/permission-catalog.ts

@@ -0,0 +1,266 @@
+export interface PermissionCatalogEntry {
+  key: string;
+  resource: string;
+  action: string;
+  labelDe: string;
+  groupDe: string;
+  sortOrder: number;
+}
+
+function group(
+  groupDe: string,
+  resource: string,
+  actions: [action: string, labelDe: string][],
+  startOrder: number,
+): PermissionCatalogEntry[] {
+  return actions.map(([action, labelDe], index) => ({
+    key: `${resource}:${action}`,
+    resource,
+    action,
+    labelDe,
+    groupDe,
+    sortOrder: startOrder + index,
+  }));
+}
+
+export const PERMISSION_CATALOG = [
+  ...group(
+    'Bienenstände',
+    'apiaries',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['deactivate', 'Deaktivieren'],
+    ],
+    100,
+  ),
+  ...group(
+    'Völker',
+    'colonies',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['deactivate', 'Deaktivieren'],
+      ['manage-lifecycle', 'Umsetzen/Teilen/Vereinigen/Auflösen'],
+    ],
+    200,
+  ),
+  ...group(
+    'Königinnen',
+    'queens',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['assign', 'Volk zuweisen'],
+      ['evaluate', 'Bewerten'],
+    ],
+    300,
+  ),
+  ...group(
+    'Durchsichten',
+    'inspections',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    400,
+  ),
+  ...group(
+    'Aufgaben',
+    'tasks',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['complete', 'Erledigen'],
+    ],
+    500,
+  ),
+  ...group(
+    'Wiederkehrende Aufgaben',
+    'task-templates',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['deactivate', 'Deaktivieren'],
+    ],
+    600,
+  ),
+  ...group(
+    'Varroa',
+    'varroa',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    700,
+  ),
+  ...group(
+    'Schwarmkontrolle',
+    'swarm-control',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    800,
+  ),
+  ...group(
+    'Behandlungen',
+    'treatments',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    900,
+  ),
+  ...group(
+    'Fütterungen',
+    'feedings',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    1000,
+  ),
+  ...group(
+    'Ernten',
+    'harvests',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    1100,
+  ),
+  ...group(
+    'Schleuderungen',
+    'extractions',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    1200,
+  ),
+  ...group(
+    'Honigchargen',
+    'honey-batches',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['relocate', 'Umlagern'],
+      ['measure', 'Messwerte erfassen'],
+    ],
+    1300,
+  ),
+  ...group(
+    'Lager',
+    'storage',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['move', 'Bewegung buchen'],
+    ],
+    1400,
+  ),
+  ...group(
+    'Produkte',
+    'products',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    1500,
+  ),
+  ...group(
+    'Abfüllungen',
+    'bottling',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    1600,
+  ),
+  ...group(
+    'Inventar',
+    'equipment',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+    ],
+    1700,
+  ),
+  ...group(
+    'Dokumente',
+    'documents',
+    [
+      ['read', 'Ansehen'],
+      ['upload', 'Hochladen'],
+      ['delete', 'Löschen'],
+    ],
+    1800,
+  ),
+  ...group(
+    'Webhooks',
+    'webhooks',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['delete', 'Löschen'],
+    ],
+    1900,
+  ),
+  ...group(
+    'Automatisierungen',
+    'automation',
+    [
+      ['read', 'Ansehen'],
+      ['update', 'Bearbeiten'],
+    ],
+    2000,
+  ),
+  ...group('Import', 'import', [['execute', 'Ausführen']], 2100),
+  ...group('Export', 'export', [['read', 'Ansehen']], 2200),
+  ...group(
+    'Benutzer',
+    'users',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['deactivate', 'Deaktivieren'],
+    ],
+    2300,
+  ),
+  ...group(
+    'Rollen & Rechte',
+    'roles',
+    [
+      ['read', 'Ansehen'],
+      ['create', 'Anlegen'],
+      ['update', 'Bearbeiten'],
+      ['deactivate', 'Deaktivieren'],
+    ],
+    2400,
+  ),
+  ...group('Audit-Log', 'audit', [['read', 'Ansehen']], 2500),
+  ...group('Kalender', 'calendar', [['read', 'Ansehen']], 2600),
+  ...group('Dashboard', 'dashboard', [['read', 'Ansehen']], 2700),
+  ...group('Statistik', 'statistics', [['read', 'Ansehen']], 2800),
+  ...group('Suche', 'search', [['read', 'Ansehen']], 2900),
+  ...group('QR-Codes', 'qr', [['read', 'Ansehen']], 3000),
+] as const satisfies readonly PermissionCatalogEntry[];
+
+export type PermissionKey = (typeof PERMISSION_CATALOG)[number]['key'];

ApiCore-Backend/src/auth/permissions/permission-resolver.service.ts

@@ -0,0 +1,78 @@
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from '../../prisma/prisma.service';
+import { PermissionKey } from './permission-catalog';
+
+interface CacheEntry {
+  permissions: ReadonlySet<string>;
+  expiresAt: number;
+}
+
+const CACHE_TTL_MS = 30_000;
+
+/**
+ * Resolves a user's effective permission set fresh from the database on
+ * every request (not embedded in the JWT, so revoking a role or editing a
+ * role's grants takes effect without forcing a re-login), with a short TTL
+ * cache to keep that from becoming a query-per-request cost. Call
+ * invalidateUser/invalidateAll after any write to Role, Permission,
+ * RolePermission, or User.roleId so the change is visible immediately
+ * instead of waiting out the cache window.
+ */
+@Injectable()
+export class PermissionResolverService {
+  private readonly cache = new Map<string, CacheEntry>();
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  async getPermissions(userId: string): Promise<ReadonlySet<string>> {
+    const cached = this.cache.get(userId);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.permissions;
+    }
+    const permissions = await this.loadPermissions(userId);
+    this.cache.set(userId, {
+      permissions,
+      expiresAt: Date.now() + CACHE_TTL_MS,
+    });
+    return permissions;
+  }
+
+  async hasAny(
+    userId: string,
+    keys: readonly PermissionKey[],
+  ): Promise<boolean> {
+    if (keys.length === 0) {
+      return true;
+    }
+    const permissions = await this.getPermissions(userId);
+    return keys.some((key) => permissions.has(key));
+  }
+
+  invalidateUser(userId: string): void {
+    this.cache.delete(userId);
+  }
+
+  invalidateAll(): void {
+    this.cache.clear();
+  }
+
+  private async loadPermissions(userId: string): Promise<ReadonlySet<string>> {
+    const user = await this.prisma.user.findUnique({
+      where: { id: userId },
+      select: {
+        role: {
+          select: {
+            status: true,
+            permissions: {
+              select: { permission: { select: { key: true } } },
+            },
+          },
+        },
+      },
+    });
+    if (!user || user.role.status !== 'ACTIVE') {
+      return new Set();
+    }
+    return new Set(user.role.permissions.map((grant) => grant.permission.key));
+  }
+}

ApiCore-Backend/src/auth/permissions/permissions.module.ts

@@ -0,0 +1,10 @@
+import { Global, Module } from '@nestjs/common';
+import { PermissionCatalogSyncService } from './permission-catalog-sync.service';
+import { PermissionResolverService } from './permission-resolver.service';
+
+@Global()
+@Module({
+  providers: [PermissionResolverService, PermissionCatalogSyncService],
+  exports: [PermissionResolverService],
+})
+export class PermissionsModule {}

ApiCore-Backend/src/auth/types/authenticated-user.ts

@@ -1,4 +1,4 @@
-import { Role } from '../../../generated/prisma';
+import { LegacyRole as Role } from '../../../generated/prisma';
 
 export interface AuthenticatedUser {
   id: string;