create-tigra 2.1.5 → 2.3.0

package/template/server/postman/collection.json

@@ -0,0 +1,524 @@
+{
+  "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.",
+    "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",
+      "value": ""
+    },
+    {
+      "key": "refreshToken",
+      "value": ""
+    },
+    {
+      "key": "userId",
+      "value": ""
+    },
+    {
+      "key": "targetUserId",
+      "value": ""
+    }
+  ],
+  "item": [
+    {
+      "name": "Auth",
+      "description": "Authentication endpoints. No auth required for these requests.",
+      "auth": {
+        "type": "noauth"
+      },
+      "item": [
+        {
+          "name": "Register",
+          "request": {
+            "method": "POST",
+            "header": [
+              {
+                "key": "Content-Type",
+                "value": "application/json"
+              }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"email\": \"john.doe@example.com\",\n  \"password\": \"Password123\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\"\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/auth/register",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "register"]
+            },
+            "description": "Register a new user account."
+          },
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "if (pm.response.code === 201) {",
+                  "  const res = pm.response.json();",
+                  "  if (res.data && res.data.user) {",
+                  "    pm.collectionVariables.set('userId', res.data.user.id);",
+                  "  }",
+                  "  // Tokens are set via httpOnly cookies, not in response body",
+                  "}"
+                ]
+              }
+            }
+          ],
+          "response": []
+        },
+        {
+          "name": "Login",
+          "request": {
+            "method": "POST",
+            "header": [
+              {
+                "key": "Content-Type",
+                "value": "application/json"
+              }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"email\": \"john.doe@example.com\",\n  \"password\": \"Password123\"\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/auth/login",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "login"]
+            },
+            "description": "Login with email and password. Tokens are set as httpOnly cookies."
+          },
+          "event": [
+            {
+              "listen": "test",
+              "script": {
+                "type": "text/javascript",
+                "exec": [
+                  "if (pm.response.code === 200) {",
+                  "  const res = pm.response.json();",
+                  "  if (res.data && res.data.user) {",
+                  "    pm.collectionVariables.set('userId', res.data.user.id);",
+                  "  }",
+                  "  // Tokens are set via httpOnly cookies, not in response body",
+                  "}"
+                ]
+              }
+            }
+          ],
+          "response": []
+        },
+        {
+          "name": "Refresh Token",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/auth/refresh",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "refresh"]
+            },
+            "description": "Refresh access token using the refresh_token cookie."
+          },
+          "response": []
+        },
+        {
+          "name": "Logout",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/auth/logout",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "logout"]
+            },
+            "description": "Logout and clear auth cookies."
+          },
+          "response": []
+        },
+        {
+          "name": "Get Me",
+          "request": {
+            "auth": {
+              "type": "bearer",
+              "bearer": [
+                {
+                  "key": "token",
+                  "value": "{{accessToken}}",
+                  "type": "string"
+                }
+              ]
+            },
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/auth/me",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "me"]
+            },
+            "description": "Get the currently authenticated user."
+          },
+          "response": []
+        },
+        {
+          "name": "Get Sessions",
+          "request": {
+            "auth": {
+              "type": "bearer",
+              "bearer": [
+                {
+                  "key": "token",
+                  "value": "{{accessToken}}",
+                  "type": "string"
+                }
+              ]
+            },
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/auth/sessions",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "sessions"]
+            },
+            "description": "Get all active sessions for the current user."
+          },
+          "response": []
+        },
+        {
+          "name": "Logout All Sessions",
+          "request": {
+            "auth": {
+              "type": "bearer",
+              "bearer": [
+                {
+                  "key": "token",
+                  "value": "{{accessToken}}",
+                  "type": "string"
+                }
+              ]
+            },
+            "method": "POST",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/auth/logout-all",
+              "host": ["{{baseUrl}}"],
+              "path": ["auth", "logout-all"]
+            },
+            "description": "Logout from all sessions and invalidate all refresh tokens."
+          },
+          "response": []
+        }
+      ]
+    },
+    {
+      "name": "Users",
+      "description": "User profile and avatar management. All requests require authentication (inherited from collection root).",
+      "item": [
+        {
+          "name": "Update Profile",
+          "request": {
+            "method": "PATCH",
+            "header": [
+              {
+                "key": "Content-Type",
+                "value": "application/json"
+              }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\"\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/users/me",
+              "host": ["{{baseUrl}}"],
+              "path": ["users", "me"]
+            },
+            "description": "Update the current user's profile. At least one field (firstName or lastName) must be provided."
+          },
+          "response": []
+        },
+        {
+          "name": "Change Password",
+          "request": {
+            "method": "PATCH",
+            "header": [
+              {
+                "key": "Content-Type",
+                "value": "application/json"
+              }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"currentPassword\": \"Password123\",\n  \"newPassword\": \"NewPassword456\"\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/users/me/password",
+              "host": ["{{baseUrl}}"],
+              "path": ["users", "me", "password"]
+            },
+            "description": "Change the current user's password. Requires current password verification. Invalidates all sessions after successful change."
+          },
+          "response": []
+        },
+        {
+          "name": "Delete Account",
+          "request": {
+            "method": "DELETE",
+            "header": [
+              {
+                "key": "Content-Type",
+                "value": "application/json"
+              }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"password\": \"Password123\"\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/users/me",
+              "host": ["{{baseUrl}}"],
+              "path": ["users", "me"]
+            },
+            "description": "Soft-delete the current user's account. Requires password confirmation. Account data is permanently purged after 30 days."
+          },
+          "response": []
+        },
+        {
+          "name": "Upload Avatar",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "body": {
+              "mode": "formdata",
+              "formdata": [
+                {
+                  "key": "file",
+                  "type": "file",
+                  "src": "",
+                  "description": "Image file (JPEG, PNG, or WebP, max 10MB)"
+                }
+              ]
+            },
+            "url": {
+              "raw": "{{baseUrl}}/users/avatar",
+              "host": ["{{baseUrl}}"],
+              "path": ["users", "avatar"]
+            },
+            "description": "Upload or replace the current user's avatar. Accepts JPEG, PNG, or WebP. Max 10MB. Image is optimized and converted to WebP."
+          },
+          "response": []
+        },
+        {
+          "name": "Delete Avatar",
+          "request": {
+            "method": "DELETE",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/users/avatar",
+              "host": ["{{baseUrl}}"],
+              "path": ["users", "avatar"]
+            },
+            "description": "Delete the current user's avatar."
+          },
+          "response": []
+        },
+        {
+          "name": "Get Avatar",
+          "request": {
+            "auth": {
+              "type": "noauth"
+            },
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/users/{{userId}}/avatar",
+              "host": ["{{baseUrl}}"],
+              "path": ["users", "{{userId}}", "avatar"]
+            },
+            "description": "Get a user's avatar image by user ID. Public endpoint — no authentication required."
+          },
+          "response": []
+        }
+      ]
+    },
+    {
+      "name": "Admin",
+      "description": "Admin-only endpoints. Requires ADMIN role. Auth inherited from collection root.",
+      "item": [
+        {
+          "name": "User Management",
+          "description": "Manage users by ID. Requires ADMIN role. Set {{targetUserId}} before calling.",
+          "item": [
+            {
+              "name": "Update Profile (by ID)",
+              "request": {
+                "method": "PATCH",
+                "header": [
+                  {
+                    "key": "Content-Type",
+                    "value": "application/json"
+                  }
+                ],
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\"\n}"
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}"]
+                },
+                "description": "Update a user's profile by ID. Requires owner or admin access."
+              },
+              "response": []
+            },
+            {
+              "name": "Change Password (by ID)",
+              "request": {
+                "method": "PATCH",
+                "header": [
+                  {
+                    "key": "Content-Type",
+                    "value": "application/json"
+                  }
+                ],
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"newPassword\": \"NewPassword456\"\n}"
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}/password",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}", "password"]
+                },
+                "description": "Change a user's password by ID. Admin: only newPassword required. Invalidates all target user sessions."
+              },
+              "response": []
+            },
+            {
+              "name": "Delete Account (by ID)",
+              "request": {
+                "method": "DELETE",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}"]
+                },
+                "description": "Soft-delete a user's account by ID. No password required for admin. Invalidates all target user sessions."
+              },
+              "response": []
+            },
+            {
+              "name": "Upload Avatar (by ID)",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "body": {
+                  "mode": "formdata",
+                  "formdata": [
+                    {
+                      "key": "file",
+                      "type": "file",
+                      "src": "",
+                      "description": "Image file (JPEG, PNG, or WebP, max 10MB)"
+                    }
+                  ]
+                },
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}/avatar",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}", "avatar"]
+                },
+                "description": "Upload or replace a user's avatar by ID. Requires admin access. Accepts JPEG, PNG, or WebP."
+              },
+              "response": []
+            },
+            {
+              "name": "Delete Avatar (by ID)",
+              "request": {
+                "method": "DELETE",
+                "header": [],
+                "url": {
+                  "raw": "{{baseUrl}}/users/{{targetUserId}}/avatar",
+                  "host": ["{{baseUrl}}"],
+                  "path": ["users", "{{targetUserId}}", "avatar"]
+                },
+                "description": "Delete a user's avatar by ID. Requires admin access."
+              },
+              "response": []
+            }
+          ]
+        },
+        {
+          "name": "List Blocked IPs",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/admin/blocked-ips",
+              "host": ["{{baseUrl}}"],
+              "path": ["admin", "blocked-ips"]
+            },
+            "description": "List all blocked IP addresses. Returns permanent blocks and active auto-blocks separately."
+          },
+          "response": []
+        },
+        {
+          "name": "Block IP",
+          "request": {
+            "method": "POST",
+            "header": [
+              {
+                "key": "Content-Type",
+                "value": "application/json"
+              }
+            ],
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"ip\": \"1.2.3.4\",\n  \"reason\": \"Spam bot\"\n}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/admin/blocked-ips",
+              "host": ["{{baseUrl}}"],
+              "path": ["admin", "blocked-ips"]
+            },
+            "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."
+          },
+          "response": []
+        },
+        {
+          "name": "Unblock IP",
+          "request": {
+            "method": "DELETE",
+            "header": [],
+            "url": {
+              "raw": "{{baseUrl}}/admin/blocked-ips/1.2.3.4",
+              "host": ["{{baseUrl}}"],
+              "path": ["admin", "blocked-ips", "1.2.3.4"]
+            },
+            "description": "Remove an IP from the permanent block list. Also removes it from auto-blocks if present."
+          },
+          "response": []
+        }
+      ]
+    }
+  ]
+}

package/template/server/postman/environment.json

@@ -0,0 +1,31 @@
+{
+  "id": "{{PROJECT_NAME}}-server-env",
+  "name": "{{PROJECT_DISPLAY_NAME}} Server - Local",
+  "values": [
+    {
+      "key": "baseUrl",
+      "value": "http://localhost:8000/api/v1",
+      "type": "default",
+      "enabled": true
+    },
+    {
+      "key": "accessToken",
+      "value": "",
+      "type": "default",
+      "enabled": true
+    },
+    {
+      "key": "refreshToken",
+      "value": "",
+      "type": "default",
+      "enabled": true
+    },
+    {
+      "key": "userId",
+      "value": "",
+      "type": "default",
+      "enabled": true
+    }
+  ],
+  "_postman_variable_scope": "environment"
+}

package/template/server/prisma/schema.prisma

@@ -18,7 +18,7 @@ model User {
   password      String
   firstName     String
   lastName      String
-  avatarUrl     String?   // SEO-friendly path: /uploads/avatars/{userId}/{firstName-lastName}-avatar.webp
+  avatarUrl     String?   // SEO-friendly path: /uploads/users/{userId}/avatar/{firstName-lastName}-avatar.webp
   role          UserRole  @default(USER)
   isActive      Boolean   @default(true)
   deletedAt     DateTime?
@@ -32,6 +32,7 @@ model User {
 
   refreshTokens RefreshToken[]
   sessions      Session[]
+  blockedIps    BlockedIp[]
 
   // Performance indexes for high-traffic scenarios (10K-100K users/day)
   @@index([role])           // For role-based authorization queries
@@ -75,3 +76,18 @@ model Session {
   @@index([expiresAt])         // For expired session cleanup
   @@map("sessions")
 }
+
+model BlockedIp {
+  id        String   @id @default(uuid())
+  ip        String   @unique @db.VarChar(45)
+  reason    String?  @db.VarChar(500)
+  blockedBy String
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user User @relation(fields: [blockedBy], references: [id])
+
+  @@index([ip])
+  @@map("blocked_ips")
+}

package/template/server/src/app.ts

@@ -1,4 +1,4 @@
-import Fastify, { type FastifyError } from 'fastify';
+import Fastify, { type FastifyError, type FastifyRequest } from 'fastify';
 import cors from '@fastify/cors';
 import helmet from '@fastify/helmet';
 import rateLimit from '@fastify/rate-limit';
@@ -17,8 +17,12 @@ import { isAppError } from '@shared/errors/AppError.js';
 import { successResponse, errorResponse } from '@shared/responses/successResponse.js';
 import { authRoutes } from '@modules/auth/auth.routes.js';
 import { usersRoutes } from '@modules/users/users.routes.js';
+import { adminRoutes } from '@modules/admin/admin.routes.js';
 import { fileStorageService } from '@libs/storage/file-storage.service.js';
-import { registerCleanupJob } from '@libs/cleanup.js';
+import { registerJobs } from '@jobs/index.js';
+import { RATE_LIMIT_ENABLED, getRateLimitRedisStore } from '@config/rate-limit.config.js';
+import { isIpBlocked, recordRateLimitViolation, syncBlockedIpsToRedis } from '@libs/ip-block.js';
+import { ForbiddenError } from '@shared/errors/errors.js';
 import {
   serializerCompiler,
   validatorCompiler,
@@ -71,11 +75,29 @@ export async function buildApp() {
     encodings: ['gzip', 'deflate'],
   });
 
-  await app.register(rateLimit, {
-    global: false,
-    max: 100,
-    timeWindow: '1 minute',
-  });
+  // Rate limiting: Redis-backed when available, in-memory fallback
+  if (RATE_LIMIT_ENABLED) {
+    const redisStore = getRateLimitRedisStore();
+    await app.register(rateLimit, {
+      global: false,
+      max: 100,
+      timeWindow: '1 minute',
+      redis: redisStore,
+      nameSpace: 'rl:',
+      skipOnError: true, // Gracefully degrade if Redis fails mid-request
+      onExceeded: (request: { ip: string }) => {
+        recordRateLimitViolation(request.ip);
+      },
+    });
+  } else {
+    // Register with effectively no limit so per-route configs don't error
+    await app.register(rateLimit, {
+      global: false,
+      max: 1_000_000,
+      timeWindow: '1 minute',
+    });
+    logger.warn('[RATE-LIMIT] Rate limiting is DISABLED (RATE_LIMIT_ENABLED=false)');
+  }
 
   await app.register(cookie, {
     secret: env.COOKIE_SECRET || env.JWT_SECRET,
@@ -95,7 +117,7 @@ export async function buildApp() {
   // File upload handling (multipart/form-data)
   await app.register(multipart, {
     limits: {
-      fileSize: 5 * 1024 * 1024, // 5MB max file size
+      fileSize: env.MAX_FILE_SIZE_MB * 1024 * 1024, // ENV-configurable (default 10MB)
       files: 1, // Only one file per request
     },
   });
@@ -113,6 +135,16 @@ export async function buildApp() {
   // Initialize file storage (create directories)
   await fileStorageService.initialize();
 
+  // --- Sync permanent IP blocks from DB to Redis ---
+  await syncBlockedIpsToRedis();
+
+  // --- IP Block Check (runs before everything else) ---
+  app.addHook('onRequest', async (request: FastifyRequest) => {
+    if (await isIpBlocked(request.ip)) {
+      throw new ForbiddenError('Access denied', 'IP_BLOCKED');
+    }
+  });
+
   // --- Request/Response Logging ---
   const skipLogPaths = new Set(['/api/v1/health', '/api/v1/ready', '/api/v1/live']);
 
@@ -233,9 +265,10 @@ export async function buildApp() {
   // --- Routes ---
   await app.register(authRoutes, { prefix: '/api/v1' });
   await app.register(usersRoutes, { prefix: '/api/v1' });
+  await app.register(adminRoutes, { prefix: '/api/v1' });
 
-  // --- Cleanup Jobs ---
-  await registerCleanupJob(app);
+  // --- Background Jobs ---
+  registerJobs(app);
 
   return app;
 }