Implement admin users and roles management

- Add user CRUD: list, create (via Better Auth), update role/status, remove from port
- Add role CRUD: create, update permissions, delete with system role protection
- Full permissions matrix UI with accordion groups and per-action checkboxes
- Validators, services, API routes, and UI components following existing patterns

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/app/api/v1/admin/roles/[id]/route.ts

@@ -1,28 +1,49 @@
 import { NextResponse } from 'next/server';
-import { eq } from 'drizzle-orm';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
-import { db } from '@/lib/db';
-import { roles } from '@/lib/db/schema';
-import { errorResponse, NotFoundError } from '@/lib/errors';
+import { parseBody } from '@/lib/api/route-helpers';
+import { getRole, updateRole, deleteRole } from '@/lib/services/roles.service';
+import { updateRoleSchema } from '@/lib/validators/roles';
+import { errorResponse } from '@/lib/errors';
 
 export const GET = withAuth(
   withPermission('admin', 'manage_users', async (_req, _ctx, params) => {
     try {
-      const { id } = params;
-      if (!id) {
-        throw new NotFoundError('Role');
-      }
-
-      const role = await db.query.roles.findFirst({
-        where: eq(roles.id, id),
-      });
-
-      if (!role) {
-        throw new NotFoundError('Role');
-      }
-
-      return NextResponse.json({ data: role });
+      const data = await getRole(params.id!);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_users', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateRoleSchema);
+      const data = await updateRole(params.id!, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx, params) => {
+    try {
+      await deleteRole(params.id!, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ success: true });
     } catch (error) {
       return errorResponse(error);
     }

src/app/api/v1/admin/roles/route.ts

@@ -1,19 +1,35 @@
 import { NextResponse } from 'next/server';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
-import { db } from '@/lib/db';
+import { parseBody } from '@/lib/api/route-helpers';
+import { listRoles, createRole } from '@/lib/services/roles.service';
+import { createRoleSchema } from '@/lib/validators/roles';
 import { errorResponse } from '@/lib/errors';
 
 export const GET = withAuth(
-  withPermission('admin', 'manage_users', async (_req, _ctx) => {
+  withPermission('admin', 'manage_users', async () => {
     try {
-      const data = await db.query.roles.findMany({
-        orderBy: (roles, { asc }) => [asc(roles.name)],
-      });
-
+      const data = await listRoles();
       return NextResponse.json({ data });
     } catch (error) {
       return errorResponse(error);
     }
   }),
 );
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_users', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createRoleSchema);
+      const data = await createRole(body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/users/[id]/route.ts

@@ -0,0 +1,51 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { getUser, updateUser, removeUserFromPort } from '@/lib/services/users.service';
+import { updateUserSchema } from '@/lib/validators/users';
+import { errorResponse } from '@/lib/errors';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx, params) => {
+    try {
+      const data = await getUser(params.id!, ctx.portId);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_users', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateUserSchema);
+      const data = await updateUser(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx, params) => {
+    try {
+      await removeUserFromPort(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/users/route.ts

@@ -1,40 +1,35 @@
 import { NextResponse } from 'next/server';
-import { eq } from 'drizzle-orm';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
-import { db } from '@/lib/db';
-import { userPortRoles, userProfiles, roles } from '@/lib/db/schema';
+import { parseBody } from '@/lib/api/route-helpers';
+import { listUsers, createUser } from '@/lib/services/users.service';
+import { createUserSchema } from '@/lib/validators/users';
 import { errorResponse } from '@/lib/errors';
 
 export const GET = withAuth(
   withPermission('admin', 'manage_users', async (_req, ctx) => {
     try {
-      const rows = await db
-        .select({
-          userId: userPortRoles.userId,
-          displayName: userProfiles.displayName,
-          isActive: userProfiles.isActive,
-          lastLoginAt: userProfiles.lastLoginAt,
-          roleId: roles.id,
-          roleName: roles.name,
-        })
-        .from(userPortRoles)
-        .innerJoin(userProfiles, eq(userPortRoles.userId, userProfiles.userId))
-        .innerJoin(roles, eq(userPortRoles.roleId, roles.id))
-        .where(eq(userPortRoles.portId, ctx.portId))
-        .orderBy(userProfiles.displayName);
-
-      const data = rows.map((row) => ({
-        userId: row.userId,
-        displayName: row.displayName,
-        isActive: row.isActive,
-        lastLoginAt: row.lastLoginAt,
-        role: { id: row.roleId, name: row.roleName },
-      }));
-
+      const data = await listUsers(ctx.portId);
       return NextResponse.json({ data });
     } catch (error) {
       return errorResponse(error);
     }
   }),
 );
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_users', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createUserSchema);
+      const data = await createUser(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);