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/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));
+  }
+}