create-tigra 2.6.0 → 2.6.8

package/template/server/src/modules/admin/admin.repo.ts

@@ -0,0 +1,289 @@
+/**
+ * Admin Repository
+ *
+ * Data access layer for admin-specific queries.
+ */
+
+import { prisma, isPrismaNotFound } from '@libs/prisma.js';
+
+import type { UserRole } from '@shared/types/index.js';
+
+// ─── Select Shapes ──────────────────────────────────────────────────────────
+
+const adminUserSelect = {
+  id: true,
+  email: true,
+  firstName: true,
+  lastName: true,
+  role: true,
+  avatarUrl: true,
+  isActive: true,
+  deletedAt: true,
+  failedLoginAttempts: true,
+  lockedUntil: true,
+  createdAt: true,
+  updatedAt: true,
+} as const;
+
+const sessionUserSelect = {
+  id: true,
+  email: true,
+  firstName: true,
+  lastName: true,
+} as const;
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type AdminUser = {
+  id: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  role: UserRole;
+  avatarUrl: string | null;
+  isActive: boolean;
+  deletedAt: Date | null;
+  failedLoginAttempts: number;
+  lockedUntil: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type AdminUserDetail = AdminUser & {
+  sessionCount: number;
+  lastLogin: Date | null;
+};
+
+export type AdminSession = {
+  id: string;
+  userId: string;
+  deviceInfo: string | null;
+  ipAddress: string | null;
+  lastActiveAt: Date;
+  expiresAt: Date;
+  createdAt: Date;
+  user: {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+  };
+};
+
+export type DashboardStats = {
+  totalUsers: number;
+  activeUsers: number;
+  adminCount: number;
+  recentSignups: number;
+  activeSessions: number;
+};
+
+// ─── Repository ─────────────────────────────────────────────────────────────
+
+class AdminRepository {
+  /**
+   * Get paginated list of users with optional filters
+   */
+  async getUsers(params: {
+    page: number;
+    limit: number;
+    search?: string;
+    role?: UserRole;
+    isActive?: boolean;
+    sortBy: 'createdAt' | 'email' | 'firstName';
+    sortOrder: 'asc' | 'desc';
+  }): Promise<{ items: AdminUser[]; totalItems: number }> {
+    const { page, limit, search, role, isActive, sortBy, sortOrder } = params;
+    const offset = (page - 1) * limit;
+
+    const where: Record<string, unknown> = {
+      deletedAt: null,
+    };
+
+    if (search) {
+      where.OR = [
+        { email: { contains: search } },
+        { firstName: { contains: search } },
+        { lastName: { contains: search } },
+      ];
+    }
+
+    if (role) {
+      where.role = role;
+    }
+
+    if (isActive !== undefined) {
+      where.isActive = isActive;
+    }
+
+    const [items, totalItems] = await Promise.all([
+      prisma.user.findMany({
+        where,
+        select: adminUserSelect,
+        orderBy: { [sortBy]: sortOrder },
+        skip: offset,
+        take: limit,
+      }),
+      prisma.user.count({ where }),
+    ]);
+
+    return { items, totalItems };
+  }
+
+  /**
+   * Lightweight user lookup for write operations (existence + role check).
+   * Use getUserDetail() when you need session count and last login.
+   */
+  async findUserById(userId: string): Promise<AdminUser | null> {
+    return prisma.user.findUnique({
+      where: { id: userId, deletedAt: null },
+      select: adminUserSelect,
+    });
+  }
+
+  /**
+   * Get detailed user info including session count and last login
+   */
+  async getUserDetail(userId: string): Promise<AdminUserDetail | null> {
+    const now = new Date();
+
+    const user = await prisma.user.findUnique({
+      where: { id: userId, deletedAt: null },
+      select: {
+        ...adminUserSelect,
+        _count: {
+          select: {
+            sessions: {
+              where: { expiresAt: { gt: now } },
+            },
+          },
+        },
+      },
+    });
+
+    if (!user) return null;
+
+    // Get last login from most recent session
+    const latestSession = await prisma.session.findFirst({
+      where: { userId },
+      orderBy: { lastActiveAt: 'desc' },
+      select: { lastActiveAt: true },
+    });
+
+    const { _count, ...userData } = user;
+
+    return {
+      ...userData,
+      sessionCount: _count.sessions,
+      lastLogin: latestSession?.lastActiveAt ?? null,
+    };
+  }
+
+  /**
+   * Update user active status
+   */
+  async updateUserStatus(userId: string, isActive: boolean): Promise<AdminUser> {
+    return prisma.user.update({
+      where: { id: userId },
+      data: { isActive },
+      select: adminUserSelect,
+    });
+  }
+
+  /**
+   * Update user role
+   */
+  async updateUserRole(userId: string, role: UserRole): Promise<AdminUser> {
+    return prisma.user.update({
+      where: { id: userId },
+      data: { role },
+      select: adminUserSelect,
+    });
+  }
+
+  /**
+   * Get dashboard statistics
+   */
+  async getDashboardStats(): Promise<DashboardStats> {
+    const now = new Date();
+    const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+
+    const [totalUsers, activeUsers, adminCount, recentSignups, activeSessions] =
+      await Promise.all([
+        prisma.user.count({ where: { deletedAt: null } }),
+        prisma.user.count({ where: { deletedAt: null, isActive: true } }),
+        prisma.user.count({ where: { deletedAt: null, role: 'ADMIN' } }),
+        prisma.user.count({
+          where: { deletedAt: null, createdAt: { gte: sevenDaysAgo } },
+        }),
+        prisma.session.count({ where: { expiresAt: { gt: now } } }),
+      ]);
+
+    return { totalUsers, activeUsers, adminCount, recentSignups, activeSessions };
+  }
+
+  /**
+   * Get paginated list of active sessions with user info
+   */
+  async getAllSessions(params: {
+    page: number;
+    limit: number;
+    userId?: string;
+  }): Promise<{ items: AdminSession[]; totalItems: number }> {
+    const { page, limit, userId } = params;
+    const offset = (page - 1) * limit;
+    const now = new Date();
+
+    const where: Record<string, unknown> = {
+      expiresAt: { gt: now },
+    };
+
+    if (userId) {
+      where.userId = userId;
+    }
+
+    const [items, totalItems] = await Promise.all([
+      prisma.session.findMany({
+        where,
+        include: { user: { select: sessionUserSelect } },
+        orderBy: { lastActiveAt: 'desc' },
+        skip: offset,
+        take: limit,
+      }),
+      prisma.session.count({ where }),
+    ]);
+
+    return { items, totalItems };
+  }
+
+  /**
+   * Get session by ID with user info
+   */
+  async getSessionById(sessionId: string): Promise<AdminSession | null> {
+    return prisma.session.findUnique({
+      where: { id: sessionId },
+      include: { user: { select: sessionUserSelect } },
+    });
+  }
+
+  /**
+   * Delete a session (no-op if already deleted)
+   */
+  async deleteSession(sessionId: string): Promise<void> {
+    try {
+      await prisma.session.delete({ where: { id: sessionId } });
+    } catch (error) {
+      if (isPrismaNotFound(error)) return;
+      throw error;
+    }
+  }
+
+  /**
+   * Delete refresh tokens linked to a specific session
+   */
+  async deleteRefreshTokensBySessionId(sessionId: string): Promise<void> {
+    await prisma.refreshToken.deleteMany({ where: { sessionId } });
+  }
+}
+
+export const adminRepository = new AdminRepository();

package/template/server/src/modules/admin/admin.routes.ts

@@ -2,13 +2,24 @@ import type { FastifyInstance } from 'fastify';
 import { authenticate, authorize } from '@libs/auth.js';
 import { RATE_LIMITS } from '@config/rate-limit.config.js';
 import * as adminController from './admin.controller.js';
-import { blockIpSchema, unblockIpParamsSchema } from './admin.schemas.js';
+import {
+  blockIpSchema,
+  unblockIpParamsSchema,
+  getUsersQuerySchema,
+  userIdParamsSchema,
+  updateUserStatusSchema,
+  updateUserRoleSchema,
+  getSessionsQuerySchema,
+  sessionIdParamsSchema,
+} from './admin.schemas.js';
 
 export async function adminRoutes(fastify: FastifyInstance): Promise<void> {
   // All admin routes require authentication + ADMIN role
   fastify.addHook('preValidation', authenticate);
   fastify.addHook('preValidation', authorize('ADMIN'));
 
+  // ─── IP Blocking ────────────────────────────────────────────────────────
+
   /**
    * List blocked IPs
    *
@@ -29,9 +40,7 @@ export async function adminRoutes(fastify: FastifyInstance): Promise<void> {
    * Body: { ip: string }
    */
   fastify.post('/admin/blocked-ips', {
-    schema: {
-      body: blockIpSchema,
-    },
+    schema: { body: blockIpSchema },
     config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
     handler: adminController.blockIpHandler,
   });
@@ -43,10 +52,107 @@ export async function adminRoutes(fastify: FastifyInstance): Promise<void> {
    * Auth: Required (ADMIN)
    */
   fastify.delete('/admin/blocked-ips/:ip', {
-    schema: {
-      params: unblockIpParamsSchema,
-    },
+    schema: { params: unblockIpParamsSchema },
     config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
     handler: adminController.unblockIpHandler,
   });
+
+  // ─── Dashboard Stats ──────────────────────────────────────────────────
+
+  /**
+   * Get dashboard statistics
+   *
+   * GET /api/v1/admin/stats
+   * Auth: Required (ADMIN)
+   * Returns: { totalUsers, activeUsers, adminCount, recentSignups, activeSessions }
+   */
+  fastify.get('/admin/stats', {
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.getDashboardStats,
+  });
+
+  // ─── User Management ─────────────────────────────────────────────────
+
+  /**
+   * List users (paginated, filterable)
+   *
+   * GET /api/v1/admin/users
+   * Auth: Required (ADMIN)
+   * Query: ?page=1&limit=10&search=&role=&isActive=&sortBy=createdAt&sortOrder=desc
+   */
+  fastify.get('/admin/users', {
+    schema: { querystring: getUsersQuerySchema },
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.getUsers,
+  });
+
+  /**
+   * Get user detail
+   *
+   * GET /api/v1/admin/users/:userId
+   * Auth: Required (ADMIN)
+   * Returns: User with sessionCount and lastLogin
+   */
+  fastify.get('/admin/users/:userId', {
+    schema: { params: userIdParamsSchema },
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.getUserDetail,
+  });
+
+  /**
+   * Toggle user active status
+   *
+   * PATCH /api/v1/admin/users/:userId/status
+   * Auth: Required (ADMIN)
+   * Body: { isActive: boolean }
+   * Side effect: deactivating also invalidates all sessions
+   */
+  fastify.patch('/admin/users/:userId/status', {
+    schema: { params: userIdParamsSchema, body: updateUserStatusSchema },
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.updateUserStatus,
+  });
+
+  /**
+   * Change user role
+   *
+   * PATCH /api/v1/admin/users/:userId/role
+   * Auth: Required (ADMIN)
+   * Body: { role: 'USER' | 'ADMIN' }
+   * Side effect: demoting ADMIN also invalidates their sessions
+   * Protection: cannot change your own role
+   */
+  fastify.patch('/admin/users/:userId/role', {
+    schema: { params: userIdParamsSchema, body: updateUserRoleSchema },
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.updateUserRole,
+  });
+
+  // ─── Session Management ───────────────────────────────────────────────
+
+  /**
+   * List active sessions (paginated)
+   *
+   * GET /api/v1/admin/sessions
+   * Auth: Required (ADMIN)
+   * Query: ?page=1&limit=10&userId=
+   */
+  fastify.get('/admin/sessions', {
+    schema: { querystring: getSessionsQuerySchema },
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.getAllSessions,
+  });
+
+  /**
+   * Force-expire a session
+   *
+   * DELETE /api/v1/admin/sessions/:sessionId
+   * Auth: Required (ADMIN)
+   * Side effect: also deletes associated refresh tokens
+   */
+  fastify.delete('/admin/sessions/:sessionId', {
+    schema: { params: sessionIdParamsSchema },
+    config: { rateLimit: RATE_LIMITS.ADMIN_DEFAULT },
+    handler: adminController.forceExpireSession,
+  });
 }

package/template/server/src/modules/admin/admin.schemas.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+// ─── IP Blocking ────────────────────────────────────────────────────────────
+
 export const blockIpSchema = z.object({
   ip: z.union([z.ipv4(), z.ipv6()], { message: 'Invalid IP address' }),
   reason: z.string().max(500).optional(),
@@ -11,3 +13,50 @@ export const unblockIpParamsSchema = z.object({
 
 export type BlockIpInput = z.infer<typeof blockIpSchema>;
 export type UnblockIpParams = z.infer<typeof unblockIpParamsSchema>;
+
+// ─── User Management ────────────────────────────────────────────────────────
+
+export const getUsersQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+  search: z.string().max(100).optional(),
+  role: z.enum(['USER', 'ADMIN']).optional(),
+  isActive: z
+    .enum(['true', 'false'])
+    .transform((v) => v === 'true')
+    .optional(),
+  sortBy: z.enum(['createdAt', 'email', 'firstName']).default('createdAt'),
+  sortOrder: z.enum(['asc', 'desc']).default('desc'),
+});
+
+export const userIdParamsSchema = z.object({
+  userId: z.string().uuid('Invalid user ID'),
+});
+
+export const updateUserStatusSchema = z.object({
+  isActive: z.boolean(),
+});
+
+export const updateUserRoleSchema = z.object({
+  role: z.enum(['USER', 'ADMIN']),
+});
+
+export type GetUsersQuery = z.infer<typeof getUsersQuerySchema>;
+export type UserIdParams = z.infer<typeof userIdParamsSchema>;
+export type UpdateUserStatusInput = z.infer<typeof updateUserStatusSchema>;
+export type UpdateUserRoleInput = z.infer<typeof updateUserRoleSchema>;
+
+// ─── Session Management ─────────────────────────────────────────────────────
+
+export const getSessionsQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+  userId: z.string().uuid('Invalid user ID').optional(),
+});
+
+export const sessionIdParamsSchema = z.object({
+  sessionId: z.string().uuid('Invalid session ID'),
+});
+
+export type GetSessionsQuery = z.infer<typeof getSessionsQuerySchema>;
+export type SessionIdParams = z.infer<typeof sessionIdParamsSchema>;

package/template/server/src/modules/admin/admin.service.ts

@@ -0,0 +1,154 @@
+/**
+ * Admin Service
+ *
+ * Business logic for admin operations.
+ */
+
+import { logger } from '@libs/logger.js';
+import { NotFoundError, ForbiddenError } from '@shared/errors/errors.js';
+import { adminRepository } from './admin.repo.js';
+import { sessionRepository } from '@modules/auth/session.repo.js';
+import { deleteRefreshTokensByUserId } from '@modules/auth/auth.repo.js';
+
+import type { UserRole } from '@shared/types/index.js';
+import type { AdminUser, AdminUserDetail, AdminSession, DashboardStats } from './admin.repo.js';
+
+class AdminService {
+  /**
+   * Get paginated list of users with optional filters
+   */
+  async getUsers(params: {
+    page: number;
+    limit: number;
+    search?: string;
+    role?: UserRole;
+    isActive?: boolean;
+    sortBy: 'createdAt' | 'email' | 'firstName';
+    sortOrder: 'asc' | 'desc';
+  }): Promise<{ items: AdminUser[]; totalItems: number }> {
+    return adminRepository.getUsers(params);
+  }
+
+  /**
+   * Get detailed user info
+   */
+  async getUserDetail(userId: string): Promise<AdminUserDetail> {
+    const user = await adminRepository.getUserDetail(userId);
+
+    if (!user) {
+      throw new NotFoundError('User not found');
+    }
+
+    return user;
+  }
+
+  /**
+   * Toggle user active status.
+   * When deactivating, invalidates all sessions and refresh tokens.
+   */
+  async toggleUserStatus(userId: string, isActive: boolean): Promise<AdminUser> {
+    const user = await adminRepository.findUserById(userId);
+
+    if (!user) {
+      throw new NotFoundError('User not found');
+    }
+
+    const updatedUser = await adminRepository.updateUserStatus(userId, isActive);
+
+    if (!isActive) {
+      // Force-logout: invalidate all sessions and refresh tokens
+      const deletedSessions = await sessionRepository.deleteAllUserSessions(userId);
+      await deleteRefreshTokensByUserId(userId);
+
+      logger.info({
+        msg: 'User deactivated and sessions invalidated',
+        userId,
+        deletedSessions,
+      });
+    } else {
+      logger.info({ msg: 'User activated', userId });
+    }
+
+    return updatedUser;
+  }
+
+  /**
+   * Change user role.
+   * Prevents self-demotion. On demotion from ADMIN, invalidates sessions.
+   */
+  async changeUserRole(
+    userId: string,
+    role: UserRole,
+    adminUserId: string,
+  ): Promise<AdminUser> {
+    if (userId === adminUserId) {
+      throw new ForbiddenError('Cannot change your own role');
+    }
+
+    const user = await adminRepository.findUserById(userId);
+
+    if (!user) {
+      throw new NotFoundError('User not found');
+    }
+
+    const updatedUser = await adminRepository.updateUserRole(userId, role);
+
+    // If demoting from ADMIN to USER, invalidate sessions so new role takes effect
+    if (user.role === 'ADMIN' && role === 'USER') {
+      const deletedSessions = await sessionRepository.deleteAllUserSessions(userId);
+      await deleteRefreshTokensByUserId(userId);
+
+      logger.info({
+        msg: 'User demoted from ADMIN and sessions invalidated',
+        userId,
+        deletedSessions,
+      });
+    } else {
+      logger.info({ msg: 'User role updated', userId, role });
+    }
+
+    return updatedUser;
+  }
+
+  /**
+   * Get dashboard statistics
+   */
+  async getDashboardStats(): Promise<DashboardStats> {
+    return adminRepository.getDashboardStats();
+  }
+
+  /**
+   * Get paginated list of active sessions
+   */
+  async getAllSessions(params: {
+    page: number;
+    limit: number;
+    userId?: string;
+  }): Promise<{ items: AdminSession[]; totalItems: number }> {
+    return adminRepository.getAllSessions(params);
+  }
+
+  /**
+   * Force-expire a specific session.
+   * Deletes the session and any associated refresh tokens.
+   */
+  async forceExpireSession(sessionId: string): Promise<void> {
+    const session = await adminRepository.getSessionById(sessionId);
+
+    if (!session) {
+      throw new NotFoundError('Session not found');
+    }
+
+    // Delete refresh tokens linked to this session first
+    await adminRepository.deleteRefreshTokensBySessionId(sessionId);
+    await adminRepository.deleteSession(sessionId);
+
+    logger.info({
+      msg: 'Session force-expired by admin',
+      sessionId,
+      userId: session.userId,
+    });
+  }
+}
+
+export const adminService = new AdminService();

package/template/server/src/modules/auth/auth.repo.ts

@@ -1,4 +1,4 @@
-import { prisma } from '@libs/prisma.js';
+import { prisma, isPrismaNotFound } from '@libs/prisma.js';
 import type { User, RefreshToken } from '@prisma/client';
 
 export async function findUserByEmail(email: string): Promise<User | null> {
@@ -45,6 +45,7 @@ export async function createUser(data: {
 export async function createRefreshToken(data: {
   token: string;
   userId: string;
+  sessionId?: string;
   expiresAt: Date;
 }): Promise<RefreshToken> {
   return prisma.refreshToken.create({
@@ -64,21 +65,14 @@ export async function deleteRefreshToken(token: string): Promise<void> {
       where: { token },
     });
   } catch (error) {
-    // P2025: Record not found — token was already deleted (e.g. concurrent request)
-    if (
-      error instanceof Error &&
-      'code' in error &&
-      (error as { code: string }).code === 'P2025'
-    ) {
-      return;
-    }
+    if (isPrismaNotFound(error)) return;
     throw error;
   }
 }
 
 export async function rotateRefreshToken(
   oldToken: string,
-  newData: { token: string; userId: string; expiresAt: Date },
+  newData: { token: string; userId: string; sessionId?: string; expiresAt: Date },
 ): Promise<boolean> {
   try {
     await prisma.$transaction([
@@ -87,14 +81,7 @@ export async function rotateRefreshToken(
     ]);
     return true;
   } catch (error) {
-    // P2025: Old token not found — already consumed by a concurrent request
-    if (
-      error instanceof Error &&
-      'code' in error &&
-      (error as { code: string }).code === 'P2025'
-    ) {
-      return false;
-    }
+    if (isPrismaNotFound(error)) return false;
     throw error;
   }
 }