create-tigra 2.1.5 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {

package/template/server/.env.example

@@ -39,6 +39,29 @@ REDIS_MAX_RETRIES=3
 # Connection timeout in milliseconds
 REDIS_CONNECT_TIMEOUT=10000
 
+# ===================================================================
+# RATE LIMITING
+# ===================================================================
+
+# Master switch to enable/disable rate limiting (default: true)
+# Set to false in development to disable all rate limits
+RATE_LIMIT_ENABLED=true
+
+# Multiply all rate limit max values by this factor (default: 1)
+# Set to 10 in development for 10x headroom, or 0.5 for tighter limits
+RATE_LIMIT_MULTIPLIER=1
+
+# Optional: Override specific critical route limits (uses defaults if not set)
+# RATE_LIMIT_AUTH_LOGIN_MAX=10
+# RATE_LIMIT_AUTH_REGISTER_MAX=5
+
+# ===================================================================
+# FILE UPLOAD
+# ===================================================================
+
+# Maximum file upload size in MB (default: 10)
+MAX_FILE_SIZE_MB=10
+
 # ===================================================================
 # DOCKER PORTS (auto-generated, unique per project)
 # ===================================================================

package/template/server/.env.example.production

@@ -39,6 +39,27 @@ REDIS_URL="redis://:REDIS_PASSWORD@redis.internal:6379"
 REDIS_MAX_RETRIES=5
 REDIS_CONNECT_TIMEOUT=5000
 
+# ===================================================================
+# RATE LIMITING
+# ===================================================================
+
+# Always enabled in production
+RATE_LIMIT_ENABLED=true
+
+# Production: keep at 1 (default limits are tuned for production)
+RATE_LIMIT_MULTIPLIER=1
+
+# Tight limits for sensitive auth routes in production
+RATE_LIMIT_AUTH_LOGIN_MAX=10
+RATE_LIMIT_AUTH_REGISTER_MAX=5
+
+# ===================================================================
+# FILE UPLOAD
+# ===================================================================
+
+# Maximum file upload size in MB
+MAX_FILE_SIZE_MB=10
+
 # ===================================================================
 # JWT AUTHENTICATION
 # ===================================================================

package/template/server/postman/collection.json

@@ -0,0 +1,415 @@
+{
+  "info": {
+    "name": "Tigra Server API",
+    "_postman_id": "tigra-server-collection",
+    "description": "API collection for the Tigra server template.\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": ""
+    }
+  ],
+  "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": "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}"
+            },
+            "url": {
+              "raw": "{{baseUrl}}/admin/blocked-ips",
+              "host": ["{{baseUrl}}"],
+              "path": ["admin", "blocked-ips"]
+            },
+            "description": "Permanently block an IP address. Blocked IPs receive 403 IP_BLOCKED on all requests."
+          },
+          "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": "tigra-server-env",
+  "name": "Tigra 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/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 } 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,13 @@ export async function buildApp() {
   // Initialize file storage (create directories)
   await fileStorageService.initialize();
 
+  // --- 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 +262,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;
 }

package/template/server/src/config/env.ts

@@ -21,6 +21,15 @@ const envSchema = z.object({
   REDIS_MAX_RETRIES: z.coerce.number().int().min(0).default(3),
   REDIS_CONNECT_TIMEOUT: z.coerce.number().int().min(1000).default(10000), // ms
 
+  // --- Rate Limiting ---
+  RATE_LIMIT_ENABLED: z.coerce.boolean().default(true),
+  RATE_LIMIT_MULTIPLIER: z.coerce.number().min(0.1).max(100).default(1),
+  RATE_LIMIT_AUTH_LOGIN_MAX: z.coerce.number().int().min(1).optional(),
+  RATE_LIMIT_AUTH_REGISTER_MAX: z.coerce.number().int().min(1).optional(),
+
+  // --- File Upload ---
+  MAX_FILE_SIZE_MB: z.coerce.number().min(1).max(100).default(10),
+
   // --- JWT Authentication ---
   JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
   JWT_ACCESS_EXPIRY: z.string().default('15m'),