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/apiaries.e2e-spec.ts

@@ -34,7 +34,8 @@ describe('Apiaries (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
@@ -43,7 +44,8 @@ describe('Apiaries (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/audit-log.e2e-spec.ts

@@ -30,7 +30,13 @@ describe('Audit log (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const admin = await prisma.user.create({
-      data: { email: adminEmail, passwordHash, name: 'Admin', role: 'ADMIN' },
+      data: {
+        email: adminEmail,
+        passwordHash,
+        name: 'Admin',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
+      },
     });
     adminId = admin.id;
     const beekeeper = await prisma.user.create({
@@ -38,7 +44,8 @@ describe('Audit log (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/auth-throttle.e2e-spec.ts

@@ -20,7 +20,13 @@ describe('Auth login throttling (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const user = await prisma.user.create({
-      data: { email, passwordHash, name: 'Throttle E2E User', role: 'STAFF' },
+      data: {
+        email,
+        passwordHash,
+        name: 'Throttle E2E User',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     userId = user.id;
   });

ApiCore-Backend/test/auth.e2e-spec.ts

@@ -19,7 +19,13 @@ describe('Auth (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const user = await prisma.user.create({
-      data: { email, passwordHash, name: 'Auth E2E User', role: 'ADMIN' },
+      data: {
+        email,
+        passwordHash,
+        name: 'Auth E2E User',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
+      },
     });
     userId = user.id;
   });

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

ApiCore-Backend/test/automation.e2e-spec.ts

@@ -38,7 +38,8 @@ describe('Automation rules (e2e)', () => {
         email: adminEmail,
         passwordHash,
         name: 'Automation E2E Admin',
-        role: 'ADMIN',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
       },
     });
     adminId = admin.id;
@@ -47,7 +48,8 @@ describe('Automation rules (e2e)', () => {
         email: staffEmail,
         passwordHash,
         name: 'Automation E2E Staff',
-        role: 'STAFF',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
       },
     });
     staffId = staff.id;

ApiCore-Backend/test/bottling.e2e-spec.ts

@@ -41,7 +41,8 @@ describe('Bottling (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/calendar.e2e-spec.ts

@@ -32,7 +32,8 @@ describe('Calendar (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/colonies.e2e-spec.ts

@@ -46,12 +46,19 @@ describe('Colonies (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
 

ApiCore-Backend/test/dashboard.e2e-spec.ts

@@ -37,7 +37,8 @@ describe('Dashboard (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/documents.e2e-spec.ts

@@ -41,7 +41,8 @@ describe('Documents (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Documents E2E Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
@@ -50,7 +51,8 @@ describe('Documents (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Documents E2E Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/equipment.e2e-spec.ts

@@ -34,12 +34,19 @@ describe('Equipment (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/export.e2e-spec.ts

@@ -29,7 +29,8 @@ describe('Export (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/extractions.e2e-spec.ts

@@ -36,12 +36,19 @@ describe('Extractions (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/feedings.e2e-spec.ts

@@ -36,7 +36,13 @@ describe('Feedings (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     const readonly = await prisma.user.create({
@@ -44,7 +50,8 @@ describe('Feedings (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/harvests.e2e-spec.ts

@@ -33,7 +33,13 @@ describe('Harvests (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     const readonly = await prisma.user.create({
@@ -41,7 +47,8 @@ describe('Harvests (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/honey-batches.e2e-spec.ts

@@ -53,12 +53,19 @@ describe('Honey batches (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/import.e2e-spec.ts

@@ -49,7 +49,8 @@ describe('Import (e2e)', () => {
         email: adminEmail,
         passwordHash,
         name: 'Import E2E Admin',
-        role: 'ADMIN',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
       },
     });
     adminId = admin.id;
@@ -58,7 +59,8 @@ describe('Import (e2e)', () => {
         email: staffEmail,
         passwordHash,
         name: 'Import E2E Staff',
-        role: 'STAFF',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
       },
     });
     staffId = staff.id;

ApiCore-Backend/test/inspections.e2e-spec.ts

@@ -37,7 +37,13 @@ describe('Inspections (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     const readonly = await prisma.user.create({
@@ -45,7 +51,8 @@ describe('Inspections (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/notifications.e2e-spec.ts

@@ -34,12 +34,19 @@ describe('Notifications (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/products.e2e-spec.ts

@@ -34,12 +34,19 @@ describe('Products (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/public.e2e-spec.ts

@@ -42,7 +42,8 @@ describe('Public batch origin page (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/qr.e2e-spec.ts

@@ -26,7 +26,8 @@ describe('QR codes (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/queens.e2e-spec.ts

@@ -33,7 +33,8 @@ describe('Queens (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/roles.e2e-spec.ts

@@ -0,0 +1,242 @@
+import { INestApplication } from '@nestjs/common';
+import * as bcrypt from 'bcryptjs';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { PrismaService } from '../src/prisma/prisma.service';
+import { createTestApp } from './utils/create-test-app';
+import { login } from './utils/api';
+
+interface RoleBody {
+  id: string;
+  key: string;
+  name: string;
+  isSystem: boolean;
+  status: string;
+  userCount: number;
+  permissionKeys: string[];
+}
+
+interface MeBody {
+  id: string;
+  email: string;
+  role: string;
+  roleKey: string;
+  permissions: string[];
+}
+
+describe('Roles (e2e)', () => {
+  let app: INestApplication<App>;
+  let prisma: PrismaService;
+  const adminEmail = `roles-e2e-admin-${Date.now()}@example.com`;
+  const staffEmail = `roles-e2e-staff-${Date.now()}@example.com`;
+  const password = 'SuperSecret123!';
+  let adminId: string;
+  let staffId: string;
+  let adminToken: string;
+  let staffToken: string;
+  let adminRoleId: string;
+  let staffRoleId: string;
+  let createdRoleId: string;
+
+  beforeAll(async () => {
+    app = await createTestApp();
+    prisma = app.get(PrismaService);
+
+    const adminRole = await prisma.role.findUniqueOrThrow({
+      where: { key: 'ADMIN' },
+    });
+    const staffRole = await prisma.role.findUniqueOrThrow({
+      where: { key: 'STAFF' },
+    });
+    adminRoleId = adminRole.id;
+    staffRoleId = staffRole.id;
+
+    const passwordHash = await bcrypt.hash(password, 12);
+    const admin = await prisma.user.create({
+      data: {
+        email: adminEmail,
+        passwordHash,
+        name: 'Roles E2E Admin',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
+      },
+    });
+    adminId = admin.id;
+    const staff = await prisma.user.create({
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Roles E2E Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
+    });
+    staffId = staff.id;
+
+    adminToken = (await login(app, adminEmail, password)).accessToken;
+    staffToken = (await login(app, staffEmail, password)).accessToken;
+  });
+
+  afterAll(async () => {
+    if (createdRoleId) {
+      await prisma.rolePermission.deleteMany({
+        where: { roleId: createdRoleId },
+      });
+      await prisma.role.delete({ where: { id: createdRoleId } });
+    }
+    const userIds = [adminId, staffId];
+    await prisma.refreshToken.deleteMany({
+      where: { userId: { in: userIds } },
+    });
+    await prisma.auditLog.deleteMany({ where: { userId: { in: userIds } } });
+    await prisma.user.deleteMany({ where: { id: { in: userIds } } });
+    await app.close();
+  });
+
+  it('rejects a caller without roles:read from listing roles', () => {
+    return request(app.getHttpServer())
+      .get('/api/v1/roles')
+      .set('Authorization', `Bearer ${staffToken}`)
+      .expect(403);
+  });
+
+  it('lets an admin list the seeded system roles', async () => {
+    const response = await request(app.getHttpServer())
+      .get('/api/v1/roles')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(200);
+    const roles = response.body as RoleBody[];
+    const keys = roles.map((role) => role.key);
+    expect(keys).toEqual(
+      expect.arrayContaining([
+        'ADMIN',
+        'BEEKEEPER',
+        'STAFF',
+        'READONLY',
+        'API_CLIENT',
+      ]),
+    );
+    const admin = roles.find((role) => role.key === 'ADMIN');
+    expect(admin?.isSystem).toBe(true);
+    expect(admin?.permissionKeys.length).toBe(83);
+  });
+
+  it('exposes the full permission catalog', async () => {
+    const response = await request(app.getHttpServer())
+      .get('/api/v1/roles/permission-catalog')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(200);
+    expect((response.body as unknown[]).length).toBe(83);
+  });
+
+  it('lets an admin create a role with a chosen permission set', async () => {
+    const response = await request(app.getHttpServer())
+      .post('/api/v1/roles')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        key: 'INSPECTOR_E2E',
+        name: 'Inspector (e2e)',
+        description: 'Read-only inspections role for e2e coverage',
+        permissionKeys: ['inspections:read', 'colonies:read'],
+      })
+      .expect(201);
+    const created = response.body as RoleBody;
+    createdRoleId = created.id;
+    expect(created.permissionKeys.sort()).toEqual(
+      ['colonies:read', 'inspections:read'].sort(),
+    );
+  });
+
+  it('rejects creating a role with a duplicate key', () => {
+    return request(app.getHttpServer())
+      .post('/api/v1/roles')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        key: 'INSPECTOR_E2E',
+        name: 'Duplicate',
+        permissionKeys: ['colonies:read'],
+      })
+      .expect(409);
+  });
+
+  it('rejects an unknown permission key', () => {
+    return request(app.getHttpServer())
+      .post('/api/v1/roles')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        key: 'BOGUS_E2E',
+        name: 'Bogus',
+        permissionKeys: ['not-a-real-permission'],
+      })
+      .expect(400);
+  });
+
+  it('lets an admin update a role permission set', async () => {
+    const response = await request(app.getHttpServer())
+      .patch(`/api/v1/roles/${createdRoleId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ permissionKeys: ['tasks:read'] })
+      .expect(200);
+    const updated = response.body as RoleBody;
+    expect(updated.permissionKeys).toEqual(['tasks:read']);
+  });
+
+  it('blocks editing the system ADMIN role', () => {
+    return request(app.getHttpServer())
+      .patch(`/api/v1/roles/${adminRoleId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ name: 'Renamed' })
+      .expect(403);
+  });
+
+  it('blocks deactivating the system ADMIN role', () => {
+    return request(app.getHttpServer())
+      .post(`/api/v1/roles/${adminRoleId}/deactivate`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(403);
+  });
+
+  it('blocks deactivating a role that still has users assigned', () => {
+    return request(app.getHttpServer())
+      .post(`/api/v1/roles/${staffRoleId}/deactivate`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(409);
+  });
+
+  it('deactivates and reactivates an unused custom role', async () => {
+    const deactivated = await request(app.getHttpServer())
+      .post(`/api/v1/roles/${createdRoleId}/deactivate`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(201);
+    expect((deactivated.body as RoleBody).status).toBe('INACTIVE');
+
+    const reactivated = await request(app.getHttpServer())
+      .post(`/api/v1/roles/${createdRoleId}/reactivate`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(201);
+    expect((reactivated.body as RoleBody).status).toBe('ACTIVE');
+  });
+
+  it("reflects the caller's role and effective permissions on /auth/me", async () => {
+    const adminMe = await request(app.getHttpServer())
+      .get('/api/v1/auth/me')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .expect(200);
+    const adminProfile = adminMe.body as MeBody;
+    expect(adminProfile.roleKey).toBe('ADMIN');
+    expect(adminProfile.permissions.length).toBe(83);
+
+    const staffMe = await request(app.getHttpServer())
+      .get('/api/v1/auth/me')
+      .set('Authorization', `Bearer ${staffToken}`)
+      .expect(200);
+    const staffProfile = staffMe.body as MeBody;
+    expect(staffProfile.roleKey).toBe('STAFF');
+    expect(staffProfile.permissions).toEqual(
+      expect.arrayContaining(['colonies:read', 'tasks:create']),
+    );
+    expect(staffProfile.permissions).not.toEqual(
+      expect.arrayContaining(['storage:create', 'users:read']),
+    );
+  });
+});

ApiCore-Backend/test/search.e2e-spec.ts

@@ -39,7 +39,8 @@ describe('Search and filters (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/statistics.e2e-spec.ts

@@ -60,7 +60,8 @@ describe('Statistics (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/storage.e2e-spec.ts

@@ -33,12 +33,19 @@ describe('Storage (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/swarm-control.e2e-spec.ts

@@ -36,12 +36,19 @@ describe('Swarm control checks (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/task-templates.e2e-spec.ts

@@ -31,7 +31,8 @@ describe('TaskTemplates (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;

ApiCore-Backend/test/tasks.e2e-spec.ts

@@ -30,7 +30,13 @@ describe('Tasks (e2e)', () => {
 
     const passwordHash = await bcrypt.hash(password, 12);
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     const readonly = await prisma.user.create({
@@ -38,7 +44,8 @@ describe('Tasks (e2e)', () => {
         email: readonlyEmail,
         passwordHash,
         name: 'Readonly',
-        role: 'READONLY',
+        legacyRole: 'READONLY',
+        role: { connect: { key: 'READONLY' } },
       },
     });
     readonlyId = readonly.id;

ApiCore-Backend/test/treatments.e2e-spec.ts

@@ -35,12 +35,19 @@ describe('Treatments (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/users.e2e-spec.ts

@@ -28,7 +28,8 @@ describe('Users (e2e)', () => {
         email: adminEmail,
         passwordHash,
         name: 'Users E2E Admin',
-        role: 'ADMIN',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
       },
     });
     adminId = admin.id;
@@ -37,7 +38,8 @@ describe('Users (e2e)', () => {
         email: staffEmail,
         passwordHash,
         name: 'Users E2E Staff',
-        role: 'STAFF',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
       },
     });
     staffId = staff.id;

ApiCore-Backend/test/varroa.e2e-spec.ts

@@ -35,12 +35,19 @@ describe('Varroa measurements (e2e)', () => {
         email: beekeeperEmail,
         passwordHash,
         name: 'Beekeeper',
-        role: 'BEEKEEPER',
+        legacyRole: 'BEEKEEPER',
+        role: { connect: { key: 'BEEKEEPER' } },
       },
     });
     beekeeperId = beekeeper.id;
     const staff = await prisma.user.create({
-      data: { email: staffEmail, passwordHash, name: 'Staff', role: 'STAFF' },
+      data: {
+        email: staffEmail,
+        passwordHash,
+        name: 'Staff',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
+      },
     });
     staffId = staff.id;
     beekeeperToken = (await login(app, beekeeperEmail, password)).accessToken;

ApiCore-Backend/test/webhooks.e2e-spec.ts

@@ -48,7 +48,8 @@ describe('Webhooks (e2e)', () => {
         email: adminEmail,
         passwordHash,
         name: 'Webhooks E2E Admin',
-        role: 'ADMIN',
+        legacyRole: 'ADMIN',
+        role: { connect: { key: 'ADMIN' } },
       },
     });
     adminId = admin.id;
@@ -57,7 +58,8 @@ describe('Webhooks (e2e)', () => {
         email: staffEmail,
         passwordHash,
         name: 'Webhooks E2E Staff',
-        role: 'STAFF',
+        legacyRole: 'STAFF',
+        role: { connect: { key: 'STAFF' } },
       },
     });
     staffId = staff.id;