create-tigra 2.6.0 → 2.6.8

package/template/server/postman/collection.json

@@ -2,38 +2,28 @@
   "info": {
     "name": "{{PROJECT_DISPLAY_NAME}} API",
     "_postman_id": "{{PROJECT_NAME}}-server-collection",
-    "description": "API collection for {{PROJECT_DISPLAY_NAME}}.\n\nAll authenticated requests inherit Bearer Token auth from the collection root.\nLogin/Register requests auto-set tokens via test scripts.",
+    "description": "API collection for {{PROJECT_DISPLAY_NAME}}.\n\nAuthentication is cookie-based (httpOnly). After Login or Register, Postman's cookie jar automatically stores access_token and refresh_token cookies. All subsequent requests send these cookies automatically — no manual token management needed.",
     "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
   },
-  "auth": {
-    "type": "bearer",
-    "bearer": [
-      {
-        "key": "token",
-        "value": "{{accessToken}}",
-        "type": "string"
-      }
-    ]
-  },
   "variable": [
     {
       "key": "baseUrl",
       "value": "http://localhost:8000/api/v1"
     },
     {
-      "key": "accessToken",
+      "key": "userId",
       "value": ""
     },
     {
-      "key": "refreshToken",
+      "key": "targetUserId",
       "value": ""
     },
     {
-      "key": "userId",
+      "key": "sessionId",
       "value": ""
     },
     {
-      "key": "targetUserId",
+      "key": "blockedIp",
       "value": ""
     }
   ],
@@ -156,16 +146,6 @@
         {
           "name": "Get Me",
           "request": {
-            "auth": {
-              "type": "bearer",
-              "bearer": [
-                {
-                  "key": "token",
-                  "value": "{{accessToken}}",
-                  "type": "string"
-                }
-              ]
-            },
             "method": "GET",
             "header": [],
             "url": {
@@ -173,23 +153,13 @@
               "host": ["{{baseUrl}}"],
               "path": ["auth", "me"]
             },
-            "description": "Get the currently authenticated user."
+            "description": "Get the currently authenticated user. Auth via httpOnly access_token cookie (sent automatically after login)."
           },
           "response": []
         },
         {
           "name": "Get Sessions",
           "request": {
-            "auth": {
-              "type": "bearer",
-              "bearer": [
-                {
-                  "key": "token",
-                  "value": "{{accessToken}}",
-                  "type": "string"
-                }
-              ]
-            },
             "method": "GET",
             "header": [],
             "url": {
@@ -197,23 +167,13 @@
               "host": ["{{baseUrl}}"],
               "path": ["auth", "sessions"]
             },
-            "description": "Get all active sessions for the current user."
+            "description": "Get all active sessions for the current user. Auth via httpOnly access_token cookie."
           },
           "response": []
         },
         {
           "name": "Logout All Sessions",
           "request": {
-            "auth": {
-              "type": "bearer",
-              "bearer": [
-                {
-                  "key": "token",
-                  "value": "{{accessToken}}",
-                  "type": "string"
-                }
-              ]
-            },
             "method": "POST",
             "header": [],
             "url": {
@@ -221,7 +181,7 @@
               "host": ["{{baseUrl}}"],
               "path": ["auth", "logout-all"]
             },
-            "description": "Logout from all sessions and invalidate all refresh tokens."
+            "description": "Logout from all sessions and invalidate all refresh tokens. Auth via httpOnly access_token cookie."
           },
           "response": []
         }
@@ -502,6 +462,22 @@
             },
             "description": "Permanently block an IP address. Persisted to database and cached in Redis. Blocked IPs receive 403 IP_BLOCKED on all requests. Optional reason field for audit trail."
           },
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "if (pm.response.code === 200 || pm.response.code === 201) {",
+                  "  const body = JSON.parse(pm.request.body.raw);",
+                  "  if (body && body.ip) {",
+                  "    pm.collectionVariables.set('blockedIp', body.ip);",
+                  "  }",
+                  "}"
+                ]
+              }
+            }
+          ],
           "response": []
         },
         {
@@ -510,13 +486,155 @@
             "method": "DELETE",
             "header": [],
             "url": {
-              "raw": "{{baseUrl}}/admin/blocked-ips/1.2.3.4",
+              "raw": "{{baseUrl}}/admin/blocked-ips/{{blockedIp}}",
               "host": ["{{baseUrl}}"],
-              "path": ["admin", "blocked-ips", "1.2.3.4"]
+              "path": ["admin", "blocked-ips", "{{blockedIp}}"]
             },
             "description": "Remove an IP from the permanent block list. Also removes it from auto-blocks if present."
           },
           "response": []
+        },
+        {
+          "name": "Dashboard Stats",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/admin/stats",
+              "host": ["{{baseUrl}}"],
+              "path": ["admin", "stats"]
+            },
+            "description": "Get dashboard statistics: total users, active users, admin count, recent signups (7 days), active sessions."
+          },
+          "response": []
+        },
+        {
+          "name": "Users",
+          "description": "Admin user listing, detail, status, and role management.",
+          "item": [
+            {
+              "name": "List Users",
+              "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/admin/users?page=1&limit=10",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["admin", "users"],
+                  "query": [
+                    { "key": "page", "value": "1" },
+                    { "key": "limit", "value": "10" },
+                    { "key": "search", "value": "", "disabled": true },
+                    { "key": "role", "value": "USER", "disabled": true },
+                    { "key": "isActive", "value": "true", "disabled": true },
+                    { "key": "sortBy", "value": "createdAt", "disabled": true },
+                    { "key": "sortOrder", "value": "desc", "disabled": true }
+                  ]
+                },
+                "description": "Get paginated list of users. Supports search (email, firstName, lastName), role filter, isActive filter, and sorting."
+              },
+              "response": []
+            },
+            {
+              "name": "Get User Detail",
+              "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/admin/users/{{targetUserId}}",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["admin", "users", "{{targetUserId}}"]
+                },
+                "description": "Get detailed user info including active session count and last login timestamp."
+              },
+              "response": []
+            },
+            {
+              "name": "Toggle User Status",
+              "request": {
+                "method": "PATCH",
+                "header": [
+                  {
+                    "key": "Content-Type",
+                    "value": "application/json"
+                  }
+                ],
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"isActive\": false\n}"
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/admin/users/{{targetUserId}}/status",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["admin", "users", "{{targetUserId}}", "status"]
+                },
+                "description": "Activate or deactivate a user. Deactivating also invalidates all their sessions and refresh tokens."
+              },
+              "response": []
+            },
+            {
+              "name": "Change User Role",
+              "request": {
+                "method": "PATCH",
+                "header": [
+                  {
+                    "key": "Content-Type",
+                    "value": "application/json"
+                  }
+                ],
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"role\": \"ADMIN\"\n}"
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/admin/users/{{targetUserId}}/role",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["admin", "users", "{{targetUserId}}", "role"]
+                },
+                "description": "Change a user's role. Cannot change your own role (self-protection). Demoting from ADMIN invalidates their sessions."
+              },
+              "response": []
+            }
+          ]
+        },
+        {
+          "name": "Sessions",
+          "description": "Admin session management. View and force-expire active sessions.",
+          "item": [
+            {
+              "name": "List Sessions",
+              "request": {
+                "method": "GET",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/admin/sessions?page=1&limit=10",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["admin", "sessions"],
+                  "query": [
+                    { "key": "page", "value": "1" },
+                    { "key": "limit", "value": "10" },
+                    { "key": "userId", "value": "", "disabled": true }
+                  ]
+                },
+                "description": "Get paginated list of all active sessions. Optionally filter by userId. Includes user info (id, email, name) for each session."
+              },
+              "response": []
+            },
+            {
+              "name": "Force Expire Session",
+              "request": {
+                "method": "DELETE",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/admin/sessions/{{sessionId}}",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["admin", "sessions", "{{sessionId}}"]
+                },
+                "description": "Force-expire a specific session. Also deletes associated refresh tokens."
+              },
+              "response": []
+            }
+          ]
         }
       ]
     }

package/template/server/prisma/schema.prisma

@@ -46,6 +46,7 @@ model RefreshToken {
   id        String   @id @default(uuid())
   token     String   @unique @db.VarChar(500)
   userId    String
+  sessionId String?  // Links token to its session for direct lookup on logout
   expiresAt DateTime
   createdAt DateTime @default(now())
 
@@ -56,6 +57,7 @@ model RefreshToken {
   @@index([token])
   @@index([userId, expiresAt]) // Compound index for efficient token cleanup queries
   @@index([expiresAt])         // For expired token cleanup cron jobs
+  @@index([sessionId])         // For deleting tokens by session (admin force-expire)
   @@map("refresh_tokens")
 }
 

package/template/server/src/jobs/cleanup-deleted-accounts.job.ts

@@ -48,14 +48,24 @@ export function startCleanupDeletedAccountsJob(app: FastifyInstance): void {
 
       for (const user of usersToDelete) {
         try {
-          // Delete all user media from disk (no-op if dir doesn't exist)
-          await fileStorageService.deleteUserMedia(user.id);
-
-          // Hard delete user record (cascades to RefreshToken + Session)
+          // Hard delete user record first (cascades to RefreshToken + Session).
+          // DB deletion is the critical operation — if it succeeds but file cleanup
+          // fails, we only have orphaned files (harmless, cleanable later).
+          // The reverse (files deleted, DB intact) would leave a dangling user record.
           await prisma.user.delete({
             where: { id: user.id },
           });
 
+          // Delete all user media from disk (no-op if dir doesn't exist)
+          try {
+            await fileStorageService.deleteUserMedia(user.id);
+          } catch (fileError) {
+            logger.warn(
+              { err: fileError, userId: user.id },
+              'User record purged but file cleanup failed — orphaned files may remain',
+            );
+          }
+
           purgedCount++;
         } catch (error) {
           logger.error(

package/template/server/src/libs/prisma.ts

@@ -50,6 +50,19 @@ if (env.NODE_ENV !== 'production') {
   globalForPrisma.prisma = prisma;
 }
 
+/**
+ * Check if a caught error is Prisma's "record not found" error (P2025).
+ * Use in delete/update operations where the record may have already been
+ * removed by a concurrent request or cleanup job.
+ */
+export function isPrismaNotFound(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error as { code: string }).code === 'P2025'
+  );
+}
+
 export async function testDatabaseConnection(): Promise<boolean> {
   try {
     await prisma.$queryRaw`SELECT 1`;

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

@@ -1,10 +1,23 @@
 import type { FastifyRequest, FastifyReply } from 'fastify';
 import { successResponse } from '@shared/responses/successResponse.js';
+import { paginatedResponse } from '@shared/responses/paginatedResponse.js';
 import { ValidationError } from '@shared/errors/errors.js';
 import { blockIp, unblockIp, getBlockedIps } from '@libs/ip-block.js';
-import { blockIpSchema } from './admin.schemas.js';
+import { adminService } from './admin.service.js';
+import {
+  blockIpSchema,
+  getUsersQuerySchema,
+  userIdParamsSchema,
+  updateUserStatusSchema,
+  updateUserRoleSchema,
+  getSessionsQuerySchema,
+  sessionIdParamsSchema,
+} from './admin.schemas.js';
 
 import type { BlockIpInput, UnblockIpParams } from './admin.schemas.js';
+import type { GetUsersQuery, UserIdParams, UpdateUserStatusInput, UpdateUserRoleInput, GetSessionsQuery, SessionIdParams } from './admin.schemas.js';
+
+// ─── IP Blocking ────────────────────────────────────────────────────────────
 
 export async function listBlockedIps(
   _request: FastifyRequest,
@@ -34,3 +47,119 @@ export async function unblockIpHandler(
   await unblockIp(ip);
   reply.send(successResponse('IP unblocked successfully', { ip }));
 }
+
+// ─── Dashboard Stats ────────────────────────────────────────────────────────
+
+export async function getDashboardStats(
+  _request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const stats = await adminService.getDashboardStats();
+  reply.send(successResponse('Dashboard stats retrieved', stats));
+}
+
+// ─── User Management ────────────────────────────────────────────────────────
+
+export async function getUsers(
+  request: FastifyRequest<{ Querystring: GetUsersQuery }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const parsed = getUsersQuerySchema.safeParse(request.query);
+  if (!parsed.success) {
+    throw new ValidationError(parsed.error.issues[0]?.message ?? 'Invalid query parameters');
+  }
+
+  const { page, limit } = parsed.data;
+  const { items, totalItems } = await adminService.getUsers(parsed.data);
+
+  reply.send(paginatedResponse('Users retrieved', items, page, limit, totalItems));
+}
+
+export async function getUserDetail(
+  request: FastifyRequest<{ Params: UserIdParams }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const parsed = userIdParamsSchema.safeParse(request.params);
+  if (!parsed.success) {
+    throw new ValidationError(parsed.error.issues[0]?.message ?? 'Invalid user ID');
+  }
+
+  const user = await adminService.getUserDetail(parsed.data.userId);
+  reply.send(successResponse('User details retrieved', user));
+}
+
+export async function updateUserStatus(
+  request: FastifyRequest<{ Params: UserIdParams; Body: UpdateUserStatusInput }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const paramsParsed = userIdParamsSchema.safeParse(request.params);
+  if (!paramsParsed.success) {
+    throw new ValidationError(paramsParsed.error.issues[0]?.message ?? 'Invalid user ID');
+  }
+
+  const bodyParsed = updateUserStatusSchema.safeParse(request.body);
+  if (!bodyParsed.success) {
+    throw new ValidationError(bodyParsed.error.issues[0]?.message ?? 'Invalid status');
+  }
+
+  const user = await adminService.toggleUserStatus(
+    paramsParsed.data.userId,
+    bodyParsed.data.isActive,
+  );
+
+  const action = bodyParsed.data.isActive ? 'activated' : 'deactivated';
+  reply.send(successResponse(`User ${action} successfully`, user));
+}
+
+export async function updateUserRole(
+  request: FastifyRequest<{ Params: UserIdParams; Body: UpdateUserRoleInput }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const paramsParsed = userIdParamsSchema.safeParse(request.params);
+  if (!paramsParsed.success) {
+    throw new ValidationError(paramsParsed.error.issues[0]?.message ?? 'Invalid user ID');
+  }
+
+  const bodyParsed = updateUserRoleSchema.safeParse(request.body);
+  if (!bodyParsed.success) {
+    throw new ValidationError(bodyParsed.error.issues[0]?.message ?? 'Invalid role');
+  }
+
+  const user = await adminService.changeUserRole(
+    paramsParsed.data.userId,
+    bodyParsed.data.role,
+    request.user.userId,
+  );
+
+  reply.send(successResponse('User role updated successfully', user));
+}
+
+// ─── Session Management ─────────────────────────────────────────────────────
+
+export async function getAllSessions(
+  request: FastifyRequest<{ Querystring: GetSessionsQuery }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const parsed = getSessionsQuerySchema.safeParse(request.query);
+  if (!parsed.success) {
+    throw new ValidationError(parsed.error.issues[0]?.message ?? 'Invalid query parameters');
+  }
+
+  const { page, limit } = parsed.data;
+  const { items, totalItems } = await adminService.getAllSessions(parsed.data);
+
+  reply.send(paginatedResponse('Sessions retrieved', items, page, limit, totalItems));
+}
+
+export async function forceExpireSession(
+  request: FastifyRequest<{ Params: SessionIdParams }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const parsed = sessionIdParamsSchema.safeParse(request.params);
+  if (!parsed.success) {
+    throw new ValidationError(parsed.error.issues[0]?.message ?? 'Invalid session ID');
+  }
+
+  await adminService.forceExpireSession(parsed.data.sessionId);
+  reply.send(successResponse('Session expired successfully', null));
+}