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/test/authorization-coverage.e2e-spec.ts

@@ -0,0 +1,102 @@
+import { Test } from '@nestjs/testing';
+import {
+  DiscoveryModule,
+  DiscoveryService,
+  MetadataScanner,
+  Reflector,
+} from '@nestjs/core';
+import { PATH_METADATA } from '@nestjs/common/constants';
+import { AppModule } from '../src/app.module';
+import { IS_PUBLIC_KEY } from '../src/auth/decorators/public.decorator';
+import { ROLES_KEY } from '../src/auth/decorators/roles.decorator';
+import { REQUIRE_PERMISSION_KEY } from '../src/auth/decorators/require-permission.decorator';
+import { PERMISSION_CATALOG } from '../src/auth/permissions/permission-catalog';
+
+// Routes intentionally left without a role/permission check: they act on the
+// caller's own data (notifications) or are the auth bootstrap endpoint that
+// every authenticated user must be able to reach regardless of permissions.
+const ALLOWLIST = new Set([
+  'NotificationsController.findAll',
+  'NotificationsController.markRead',
+  'AuthController.me',
+]);
+
+describe('Authorization coverage (e2e)', () => {
+  // TODO(RBAC migration): re-enable once every controller carries
+  // @RequirePermission (Phase 2 of the RBAC rollout). Right now most GET
+  // routes have no @Roles/@RequirePermission at all (authenticated-only),
+  // which this test correctly flags — that's the known, tracked starting
+  // state, not a regression to fix here.
+  it.skip('every non-public route requires a role or a catalog-valid permission', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule, DiscoveryModule],
+    }).compile();
+
+    const discovery = moduleRef.get(DiscoveryService);
+    const reflector = moduleRef.get(Reflector);
+    const scanner = moduleRef.get(MetadataScanner);
+    const catalogKeys = new Set<string>(
+      PERMISSION_CATALOG.map((entry) => entry.key),
+    );
+
+    const uncoveredRoutes: string[] = [];
+    const invalidPermissionKeys: string[] = [];
+
+    for (const wrapper of discovery.getControllers()) {
+      const instance = wrapper.instance as object | undefined;
+      if (!instance) {
+        continue;
+      }
+      const constructor = instance.constructor;
+      const controllerName = constructor.name;
+      const prototype = Object.getPrototypeOf(instance) as object;
+      const isPublicClass =
+        reflector.get<boolean>(IS_PUBLIC_KEY, constructor) === true;
+
+      for (const methodName of scanner.getAllMethodNames(prototype)) {
+        const handler = (prototype as Record<string, () => unknown>)[
+          methodName
+        ];
+        const isRouteHandler =
+          Reflect.getMetadata(PATH_METADATA, handler) !== undefined;
+        if (!isRouteHandler) {
+          continue;
+        }
+        const routeKey = `${controllerName}.${methodName}`;
+        const isPublicMethod =
+          reflector.get<boolean>(IS_PUBLIC_KEY, handler) === true;
+        if (isPublicClass || isPublicMethod || ALLOWLIST.has(routeKey)) {
+          continue;
+        }
+
+        const roles = reflector.getAllAndOverride<unknown[]>(ROLES_KEY, [
+          handler,
+          constructor,
+        ]);
+        const permissions = reflector.getAllAndOverride<string[]>(
+          REQUIRE_PERMISSION_KEY,
+          [handler, constructor],
+        );
+
+        const hasRoles = Array.isArray(roles) && roles.length > 0;
+        const hasPermissions =
+          Array.isArray(permissions) && permissions.length > 0;
+        if (!hasRoles && !hasPermissions) {
+          uncoveredRoutes.push(routeKey);
+        }
+        if (hasPermissions) {
+          for (const key of permissions) {
+            if (!catalogKeys.has(key)) {
+              invalidPermissionKeys.push(`${routeKey} -> ${key}`);
+            }
+          }
+        }
+      }
+    }
+
+    expect(uncoveredRoutes).toEqual([]);
+    expect(invalidPermissionKeys).toEqual([]);
+
+    await moduleRef.close();
+  });
+});