create-tigra 2.1.5 → 2.3.0

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'),

package/template/server/src/config/rate-limit.config.ts

@@ -0,0 +1,114 @@
+/**
+ * Rate Limiting Configuration
+ *
+ * Single source of truth for all rate limit values.
+ * Routes import from here instead of hardcoding limits.
+ *
+ * ENV controls:
+ * - RATE_LIMIT_ENABLED: master switch (default: true)
+ * - RATE_LIMIT_MULTIPLIER: multiply all max values (default: 1, set 10 for dev)
+ * - RATE_LIMIT_AUTH_LOGIN_MAX: override login max
+ * - RATE_LIMIT_AUTH_REGISTER_MAX: override register max
+ */
+
+import { env } from '@config/env.js';
+import { getRedis } from '@libs/redis.js';
+import { logger } from '@libs/logger.js';
+import type { Redis } from 'ioredis';
+
+// ─── Global settings ───────────────────────────────────────────
+
+export const RATE_LIMIT_ENABLED = env.RATE_LIMIT_ENABLED;
+
+const MULTIPLIER = env.RATE_LIMIT_MULTIPLIER;
+
+/**
+ * Apply the global multiplier to a max value.
+ * Ensures minimum of 1 if rate limiting is enabled.
+ */
+function applyMultiplier(max: number): number {
+  return Math.max(1, Math.round(max * MULTIPLIER));
+}
+
+// ─── Per-route configs ─────────────────────────────────────────
+
+export const RATE_LIMITS = {
+  // Auth routes
+  AUTH_REGISTER: {
+    max: applyMultiplier(env.RATE_LIMIT_AUTH_REGISTER_MAX ?? 5),
+    timeWindow: '1 hour',
+  },
+  AUTH_LOGIN: {
+    max: applyMultiplier(env.RATE_LIMIT_AUTH_LOGIN_MAX ?? 10),
+    timeWindow: '15 minutes',
+  },
+  AUTH_LOGOUT: {
+    max: applyMultiplier(50),
+    timeWindow: '15 minutes',
+  },
+  AUTH_REFRESH: {
+    max: applyMultiplier(20),
+    timeWindow: '15 minutes',
+  },
+  AUTH_ME: {
+    max: applyMultiplier(60),
+    timeWindow: '1 minute',
+  },
+  AUTH_SESSIONS: {
+    max: applyMultiplier(30),
+    timeWindow: '1 minute',
+  },
+  AUTH_LOGOUT_ALL: {
+    max: applyMultiplier(10),
+    timeWindow: '15 minutes',
+  },
+
+  // Users — profile management
+  USERS_UPDATE_PROFILE: {
+    max: applyMultiplier(10),
+    timeWindow: '1 minute',
+  },
+  USERS_CHANGE_PASSWORD: {
+    max: applyMultiplier(5),
+    timeWindow: '1 minute',
+  },
+  USERS_DELETE_ACCOUNT: {
+    max: applyMultiplier(3),
+    timeWindow: '1 minute',
+  },
+
+  // Users — avatar management
+  USERS_UPLOAD_AVATAR: {
+    max: applyMultiplier(5),
+    timeWindow: '1 minute',
+  },
+  USERS_DELETE_AVATAR: {
+    max: applyMultiplier(10),
+    timeWindow: '1 minute',
+  },
+  USERS_GET_AVATAR: {
+    max: applyMultiplier(100),
+    timeWindow: '1 minute',
+  },
+
+  // Admin routes
+  ADMIN_DEFAULT: {
+    max: applyMultiplier(30),
+    timeWindow: '1 minute',
+  },
+} as const;
+
+// ─── Redis store helper ────────────────────────────────────────
+
+/**
+ * Returns the Redis instance for @fastify/rate-limit's `redis` option.
+ * Returns undefined if Redis is not available (falls back to in-memory).
+ */
+export function getRateLimitRedisStore(): Redis | undefined {
+  try {
+    return getRedis();
+  } catch {
+    logger.warn('[RATE-LIMIT] Redis unavailable, falling back to in-memory store');
+    return undefined;
+  }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Cleanup Deleted Accounts Job
+ *
+ * Permanently purges soft-deleted user accounts after a 30-day retention period.
+ * Deletes all user media from disk and hard-deletes the user record (cascades to
+ * refresh tokens and sessions via onDelete: Cascade).
+ *
+ * Runs once daily.
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { prisma } from '@libs/prisma.js';
+import { logger } from '@libs/logger.js';
+import { fileStorageService } from '@libs/storage/file-storage.service.js';
+
+const INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const RETENTION_DAYS = 30;
+
+export function startCleanupDeletedAccountsJob(app: FastifyInstance): void {
+  const intervalId = setInterval(async () => {
+    try {
+      const cutoffDate = new Date();
+      cutoffDate.setDate(cutoffDate.getDate() - RETENTION_DAYS);
+
+      // Find users soft-deleted more than 30 days ago
+      const usersToDelete = await prisma.user.findMany({
+        where: {
+          deletedAt: {
+            not: null,
+            lt: cutoffDate,
+          },
+        },
+        select: {
+          id: true,
+        },
+      });
+
+      if (usersToDelete.length === 0) {
+        return;
+      }
+
+      logger.info(
+        { count: usersToDelete.length },
+        'Starting purge of soft-deleted accounts',
+      );
+
+      let purgedCount = 0;
+
+      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)
+          await prisma.user.delete({
+            where: { id: user.id },
+          });
+
+          purgedCount++;
+        } catch (error) {
+          logger.error(
+            { err: error, userId: user.id },
+            'Failed to purge deleted account',
+          );
+        }
+      }
+
+      logger.info(
+        { purgedCount, totalFound: usersToDelete.length },
+        'Deleted accounts purge complete',
+      );
+    } catch (error) {
+      logger.error({ err: error }, 'Failed to run deleted accounts cleanup');
+    }
+  }, INTERVAL_MS);
+
+  app.addHook('onClose', async () => {
+    clearInterval(intervalId);
+  });
+}

package/template/server/src/{libs/cleanup.ts → jobs/cleanup-expired-auth.job.ts}

@@ -1,10 +1,17 @@
+/**
+ * Cleanup Expired Auth Records Job
+ *
+ * Periodically removes expired refresh tokens and sessions from the database.
+ * Runs every hour.
+ */
+
 import type { FastifyInstance } from 'fastify';
 import { prisma } from '@libs/prisma.js';
 import { logger } from '@libs/logger.js';
 
-const CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 
-export async function registerCleanupJob(app: FastifyInstance): Promise<void> {
+export function startCleanupExpiredAuthJob(app: FastifyInstance): void {
   const intervalId = setInterval(async () => {
     try {
       const now = new Date();
@@ -26,9 +33,8 @@ export async function registerCleanupJob(app: FastifyInstance): Promise<void> {
     } catch (error) {
       logger.error({ err: error }, 'Failed to clean up expired auth records');
     }
-  }, CLEANUP_INTERVAL_MS);
+  }, INTERVAL_MS);
 
-  // Clear interval on server shutdown
   app.addHook('onClose', async () => {
     clearInterval(intervalId);
   });

package/template/server/src/jobs/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Jobs Registry
+ *
+ * Registers all background jobs with the Fastify instance.
+ * Each job manages its own interval and cleanup via onClose hook.
+ */
+
+import type { FastifyInstance } from 'fastify';
+import { startCleanupExpiredAuthJob } from './cleanup-expired-auth.job.js';
+import { startCleanupDeletedAccountsJob } from './cleanup-deleted-accounts.job.js';
+
+/**
+ * Registers all background jobs
+ *
+ * @param app - Fastify instance (used for onClose cleanup hooks)
+ */
+export function registerJobs(app: FastifyInstance): void {
+  startCleanupExpiredAuthJob(app);
+  startCleanupDeletedAccountsJob(app);
+}

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

@@ -2,7 +2,7 @@ import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
 import { v4 as uuidv4 } from 'uuid';
 import { env } from '@config/env.js';
 import { prisma } from '@libs/prisma.js';
-import { UnauthorizedError, ForbiddenError } from '@shared/errors/errors.js';
+import { UnauthorizedError, ForbiddenError, BadRequestError } from '@shared/errors/errors.js';
 import type { JwtPayload, UserRole } from '@shared/types/index.js';
 
 let app: FastifyInstance | null = null;
@@ -97,3 +97,47 @@ export function authorize(...roles: UserRole[]) {
   };
 }
 
+/**
+ * Middleware: resolves targetUserId from the authenticated user's JWT.
+ * Used for /users/me routes.
+ * Must run AFTER authenticate.
+ */
+export async function resolveMe(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  request.targetUserId = request.user.userId;
+  request.isAdminAction = false;
+}
+
+/**
+ * Middleware: resolves targetUserId from :userId param.
+ * Allows access if the authenticated user is the owner OR has ADMIN role.
+ * Must run AFTER authenticate.
+ *
+ * Sets:
+ * - request.targetUserId: the resolved user ID from params
+ * - request.isAdminAction: true if admin is acting on a different user
+ */
+export async function resolveTargetUser(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  const params = request.params as { userId?: string };
+  const targetUserId = params.userId;
+
+  if (!targetUserId) {
+    throw new BadRequestError('Missing userId parameter', 'MISSING_USER_ID');
+  }
+
+  const isOwner = request.user.userId === targetUserId;
+  const isAdmin = request.user.role === 'ADMIN';
+
+  if (!isOwner && !isAdmin) {
+    throw new ForbiddenError('You do not have permission to perform this action');
+  }
+
+  request.targetUserId = targetUserId;
+  request.isAdminAction = !isOwner && isAdmin;
+}
+

package/template/server/src/libs/ip-block.ts

@@ -0,0 +1,206 @@
+/**
+ * IP Blocking Service
+ *
+ * Two-tier IP blocking:
+ * - Permanent blocks: DB (source of truth) + Redis SET (hot cache). Admin-managed via API.
+ * - Auto-blocks: Redis ZSET with expiry timestamps (triggered by excessive rate-limit violations)
+ *
+ * Design decisions:
+ * - DB is the source of truth for permanent blocks — survives Redis restarts
+ * - Redis is the hot cache — all runtime checks hit Redis only (O(1))
+ * - On server boot, syncBlockedIpsToRedis() loads all permanent blocks from DB into Redis
+ * - Fails open: if Redis is down, requests are NOT blocked (availability > security for rate limiting)
+ * - Lazy cleanup: expired auto-blocks are removed on check, no separate cleanup job needed
+ */
+
+import { prisma } from '@libs/prisma.js';
+import { getRedis } from '@libs/redis.js';
+import { logger } from '@libs/logger.js';
+import { ConflictError } from '@shared/errors/errors.js';
+
+// Redis keys
+const BLOCKED_IPS_KEY = 'blocked_ips';
+const AUTO_BLOCKED_KEY = 'auto_blocked_ips';
+const VIOLATION_PREFIX = 'rl_violations:';
+
+// Auto-block thresholds
+const AUTO_BLOCK_THRESHOLD = 10;         // violations before auto-block
+const AUTO_BLOCK_WINDOW_SECONDS = 300;   // 5-minute sliding window
+const AUTO_BLOCK_DURATION_SECONDS = 3600; // block for 1 hour
+
+/**
+ * Sync all permanent blocked IPs from DB to Redis.
+ * Called once during server startup.
+ */
+export async function syncBlockedIpsToRedis(): Promise<void> {
+  try {
+    const blockedIps = await prisma.blockedIp.findMany({ select: { ip: true } });
+
+    const redis = getRedis();
+
+    // Clear stale Redis state and repopulate from DB
+    await redis.del(BLOCKED_IPS_KEY);
+
+    if (blockedIps.length > 0) {
+      await redis.sadd(BLOCKED_IPS_KEY, ...blockedIps.map((b) => b.ip));
+    }
+
+    logger.info(`[IP-BLOCK] Synced ${blockedIps.length} blocked IPs from DB to Redis`);
+  } catch (error) {
+    logger.warn('[IP-BLOCK] Failed to sync blocked IPs from DB to Redis — permanent blocks may not be enforced until next restart');
+    logger.debug(error);
+  }
+}
+
+/**
+ * Check if an IP is blocked (permanent or auto-blocked).
+ *
+ * @param ip - IP address to check
+ * @returns true if blocked, false otherwise (including Redis failures)
+ */
+export async function isIpBlocked(ip: string): Promise<boolean> {
+  try {
+    const redis = getRedis();
+
+    // Check permanent block list
+    const permanent = await redis.sismember(BLOCKED_IPS_KEY, ip);
+    if (permanent === 1) return true;
+
+    // Check auto-block list (score = expiry Unix timestamp)
+    const score = await redis.zscore(AUTO_BLOCKED_KEY, ip);
+    if (score) {
+      const expiresAt = Number(score);
+      if (expiresAt > Date.now() / 1000) return true;
+
+      // Expired — clean up lazily
+      await redis.zrem(AUTO_BLOCKED_KEY, ip);
+    }
+
+    return false;
+  } catch {
+    // Fail open: if Redis is down, don't block
+    logger.warn('[IP-BLOCK] Redis unavailable, skipping IP block check');
+    return false;
+  }
+}
+
+/**
+ * Block an IP permanently. Writes to DB (source of truth) + Redis (hot cache).
+ *
+ * @param ip - IP address to block
+ * @param blockedBy - Admin user ID who initiated the block
+ * @param reason - Optional reason for the block
+ */
+export async function blockIp(
+  ip: string,
+  blockedBy: string,
+  reason?: string,
+): Promise<{ id: string; ip: string; reason: string | null; blockedBy: string; createdAt: Date }> {
+  // Write to DB (source of truth)
+  const existing = await prisma.blockedIp.findUnique({ where: { ip } });
+  if (existing) {
+    throw new ConflictError('IP is already blocked', 'IP_ALREADY_BLOCKED');
+  }
+
+  const blocked = await prisma.blockedIp.create({
+    data: { ip, blockedBy, reason: reason ?? null },
+  });
+
+  // Sync to Redis cache
+  try {
+    const redis = getRedis();
+    await redis.sadd(BLOCKED_IPS_KEY, ip);
+  } catch {
+    logger.warn({ ip }, '[IP-BLOCK] Failed to sync block to Redis — will be synced on next restart');
+  }
+
+  logger.info({ ip, blockedBy, reason }, '[IP-BLOCK] IP permanently blocked');
+  return blocked;
+}
+
+/**
+ * Unblock an IP. Removes from DB + Redis + auto-block list.
+ *
+ * @param ip - IP address to unblock
+ */
+export async function unblockIp(ip: string): Promise<void> {
+  // Remove from DB
+  await prisma.blockedIp.deleteMany({ where: { ip } });
+
+  // Remove from Redis (both permanent and auto-block)
+  try {
+    const redis = getRedis();
+    await redis.srem(BLOCKED_IPS_KEY, ip);
+    await redis.zrem(AUTO_BLOCKED_KEY, ip);
+  } catch {
+    logger.warn({ ip }, '[IP-BLOCK] Failed to sync unblock to Redis — will be synced on next restart');
+  }
+
+  logger.info({ ip }, '[IP-BLOCK] IP unblocked');
+}
+
+/**
+ * List all currently blocked IPs (permanent from DB + active auto-blocks from Redis).
+ */
+export async function getBlockedIps(): Promise<{
+  permanent: { id: string; ip: string; reason: string | null; blockedBy: string; createdAt: Date }[];
+  autoBlocked: string[];
+}> {
+  // Permanent blocks from DB (source of truth)
+  const permanent = await prisma.blockedIp.findMany({
+    select: { id: true, ip: true, reason: true, blockedBy: true, createdAt: true },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  // Auto-blocks from Redis
+  let autoBlocked: string[] = [];
+  try {
+    const redis = getRedis();
+    const nowSeconds = Date.now() / 1000;
+    autoBlocked = await redis.zrangebyscore(AUTO_BLOCKED_KEY, nowSeconds, '+inf');
+  } catch {
+    logger.warn('[IP-BLOCK] Redis unavailable, cannot retrieve auto-blocked IPs');
+  }
+
+  return { permanent, autoBlocked };
+}
+
+/**
+ * Record a rate-limit violation for an IP.
+ *
+ * If the IP exceeds AUTO_BLOCK_THRESHOLD violations within
+ * AUTO_BLOCK_WINDOW_SECONDS, it gets auto-blocked for
+ * AUTO_BLOCK_DURATION_SECONDS.
+ *
+ * Called from the rate-limit `onExceeded` callback.
+ *
+ * @param ip - IP address that violated rate limit
+ */
+export async function recordRateLimitViolation(ip: string): Promise<void> {
+  try {
+    const redis = getRedis();
+    const key = `${VIOLATION_PREFIX}${ip}`;
+
+    const count = await redis.incr(key);
+
+    // Set TTL on first violation (sliding window)
+    if (count === 1) {
+      await redis.expire(key, AUTO_BLOCK_WINDOW_SECONDS);
+    }
+
+    if (count >= AUTO_BLOCK_THRESHOLD) {
+      // Auto-block: add to ZSET with expiry timestamp as score
+      const expiresAt = Math.floor(Date.now() / 1000) + AUTO_BLOCK_DURATION_SECONDS;
+      await redis.zadd(AUTO_BLOCKED_KEY, expiresAt, ip);
+      await redis.del(key); // Reset violation counter
+
+      logger.warn(
+        { ip, violations: count, blockedForSeconds: AUTO_BLOCK_DURATION_SECONDS },
+        '[IP-BLOCK] Auto-blocked IP due to excessive rate-limit violations',
+      );
+    }
+  } catch {
+    // Non-critical: don't break the request if violation tracking fails
+    logger.warn('[IP-BLOCK] Failed to record rate-limit violation');
+  }
+}

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

@@ -29,7 +29,7 @@ function getStatusColor(statusCode: number): string {
 }
 
 function formatDuration(ms: number): string {
-  if (ms < 1) return `${(ms * 1000).toFixed(0)}μs`;
+  if (ms < 1) return `${(ms * 1000).toFixed(0)}us`;
   if (ms < 1000) return `${ms.toFixed(0)}ms`;
   return `${(ms / 1000).toFixed(2)}s`;
 }