create-tigra 1.1.0 → 2.0.1

package/template/server/src/app.ts

@@ -1,71 +1,243 @@
-/**
- * Fastify Application Configuration
- *
- * Main entry point for configuring the Fastify instance, plugins,
- * middleware, hooks, and global error handling.
- *
- * @see /mnt/project/02-general-rules.md
- * @see /mnt/project/06-response-handling.md
- * @see /mnt/project/08-observability.md
- * @see /mnt/project/11-rate-limiting-v2.md
- */
-
-import fastify from 'fastify';
-import { env } from './config/env.js';
-import logger from './libs/logger.js';
-
-// Extracted Modules
-import { setupErrorHandler } from './libs/error-handler.js';
-import { registerSecurityPlugins } from './plugins/security.plugin.js';
-import { registerRateLimit } from './plugins/rate-limit.plugin.js';
-import { registerRequestHooks } from './hooks/request-timing.hook.js';
-import { authenticateMiddleware } from './libs/auth/authenticate.middleware.js';
-import { healthRoutes } from './routes/health.routes.js';
-
-// Routes & RBAC
-import { authRoutes } from './modules/auth/auth.routes.js';
-import { resourceRoutes } from './modules/resources/resources.routes.js';
-import { adminRoutes } from './modules/admin/admin.routes.js';
-import {
-    requireRole,
-    requireAdmin,
-    requireUser,
-    requireAny,
-} from './libs/auth/rbac.middleware.js';
-
-/**
- * Configure and build the Fastify application
- */
-const buildApp = async () => {
-    const app = fastify({
-        loggerInstance: logger,
-        disableRequestLogging: true, // Custom logging handled by hooks
-    });
-
-    // 1. Plugins
-    await registerSecurityPlugins(app);
-    await registerRateLimit(app);
-
-    // 2. Decorators
-    app.decorate('authenticate', authenticateMiddleware);
-    app.decorate('requireRole', requireRole);
-    app.decorate('requireAdmin', requireAdmin);
-    app.decorate('requireUser', requireUser);
-    app.decorate('requireAny', requireAny);
-
-    // 3. Hooks
-    registerRequestHooks(app);
-
-    // 4. Error Handler
-    app.setErrorHandler(setupErrorHandler);
-
-    // 5. Routes
-    await app.register(healthRoutes);
-    await app.register(authRoutes, { prefix: `${env.API_PREFIX}/auth` });
-    await app.register(resourceRoutes, { prefix: `${env.API_PREFIX}/resources` });
-    await app.register(adminRoutes, { prefix: `${env.API_PREFIX}/admin` });
-
-    return app;
-};
-
-export default buildApp;
+import Fastify, { type FastifyError } from 'fastify';
+import cors from '@fastify/cors';
+import helmet from '@fastify/helmet';
+import rateLimit from '@fastify/rate-limit';
+import cookie from '@fastify/cookie';
+import jwt from '@fastify/jwt';
+import compress from '@fastify/compress';
+import multipart from '@fastify/multipart';
+import fastifyStatic from '@fastify/static';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { env } from '@config/env.js';
+import { logger } from '@libs/logger.js';
+import { markRequestStart, logRequestLine } from '@libs/requestLogger.js';
+import { initAuth } from '@libs/auth.js';
+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 { fileStorageService } from '@libs/storage/file-storage.service.js';
+import { registerCleanupJob } from '@libs/cleanup.js';
+import {
+  serializerCompiler,
+  validatorCompiler,
+  type ZodTypeProvider,
+} from 'fastify-type-provider-zod';
+
+// Import types to register Fastify augmentations
+import type {} from '@shared/types/index.js';
+
+export async function buildApp() {
+  const app = Fastify({
+    logger: false,
+    // Trust proxy headers (X-Forwarded-For) for accurate client IP behind Nginx/load balancer
+    trustProxy: env.NODE_ENV === 'production',
+    // Graceful shutdown configuration
+    forceCloseConnections: true, // Force close idle connections on shutdown
+    requestTimeout: 30000, // 30s request timeout
+    connectionTimeout: 60000, // 60s connection timeout
+    keepAliveTimeout: 5000, // 5s keep-alive timeout
+    // Request body size limits (prevent DoS attacks)
+    bodyLimit: 1048576, // 1MB default limit (1024 * 1024)
+  }).withTypeProvider<ZodTypeProvider>();
+
+  // Set Zod validator and serializer
+  app.setValidatorCompiler(validatorCompiler);
+  app.setSerializerCompiler(serializerCompiler);
+
+  // --- Plugins ---
+  // CORS: Allow all origins in development, specific origin(s) in production
+  const corsOrigin = env.NODE_ENV === 'development'
+    ? true
+    : env.CORS_ORIGIN?.includes(',')
+      ? env.CORS_ORIGIN.split(',').map((o) => o.trim())
+      : env.CORS_ORIGIN;
+
+  await app.register(cors, {
+    origin: corsOrigin,
+    credentials: true,
+  });
+
+  // Enhanced security headers for production
+  await app.register(helmet, {
+    global: true,
+  });
+
+  // Response compression (gzip/brotli) for performance
+  await app.register(compress, {
+    global: true,
+    threshold: 1024, // Only compress responses > 1KB
+    encodings: ['gzip', 'deflate'],
+  });
+
+  await app.register(rateLimit, {
+    global: false,
+    max: 100,
+    timeWindow: '1 minute',
+  });
+
+  await app.register(cookie, {
+    secret: env.COOKIE_SECRET || env.JWT_SECRET,
+  });
+
+  await app.register(jwt, {
+    secret: env.JWT_SECRET,
+    cookie: {
+      cookieName: 'access_token',
+      signed: false,
+    },
+  });
+
+  // Initialize auth helpers after JWT plugin is registered
+  initAuth(app);
+
+  // File upload handling (multipart/form-data)
+  await app.register(multipart, {
+    limits: {
+      fileSize: 5 * 1024 * 1024, // 5MB max file size
+      files: 1, // Only one file per request
+    },
+  });
+
+  // Static file serving for uploads
+  // Get __dirname equivalent in ES modules
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  await app.register(fastifyStatic, {
+    root: path.join(__dirname, '..', 'uploads'),
+    prefix: '/uploads/',
+  });
+
+  // Initialize file storage (create directories)
+  await fileStorageService.initialize();
+
+  // --- Request/Response Logging ---
+  const skipLogPaths = new Set(['/api/v1/health', '/api/v1/ready', '/api/v1/live']);
+
+  app.addHook('preHandler', async (request) => {
+    const pathname = request.url.split('?')[0];
+    if (!skipLogPaths.has(pathname)) {
+      markRequestStart(request);
+    }
+  });
+
+  app.addHook('onResponse', async (request, reply) => {
+    const pathname = request.url.split('?')[0];
+    if (!skipLogPaths.has(pathname)) {
+      logRequestLine(request, reply);
+    }
+  });
+
+  // --- Global Error Handler (must be set before routes) ---
+  app.setErrorHandler((error: FastifyError, request, reply) => {
+    // AppError — our typed errors (use duck-type check to avoid instanceof issues)
+    if (isAppError(error)) {
+      return reply.status(error.statusCode).send(errorResponse(error.code, error.message));
+    }
+
+    // Zod validation error
+    if (error.name === 'ZodError') {
+      return reply.status(422).send(errorResponse('VALIDATION_FAILED', 'Validation failed'));
+    }
+
+    // Fastify validation error
+    if (error.validation) {
+      return reply.status(400).send(
+        errorResponse(
+          'BAD_REQUEST',
+          error.message || 'Invalid request',
+        ),
+      );
+    }
+
+    // Fastify plugin errors (file size, rate limiting, etc.)
+    // These have statusCode properties but aren't AppError instances
+    if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+      // Map common Fastify error codes to user-friendly messages
+      const errorCodeMap: Record<number, { code: string; message: string }> = {
+        413: { code: 'FILE_TOO_LARGE', message: 'File size exceeds the maximum allowed limit' },
+        429: { code: 'RATE_LIMIT_EXCEEDED', message: 'Too many requests. Please try again later' },
+      };
+
+      const errorInfo = errorCodeMap[error.statusCode] || {
+        code: 'BAD_REQUEST',
+        message: error.message || 'Bad request',
+      };
+
+      return reply.status(error.statusCode).send(errorResponse(errorInfo.code, errorInfo.message));
+    }
+
+    // Unexpected error — log and return generic 500
+    const requestId = request.id || 'unknown';
+    logger.error(
+      {
+        err: error,
+        requestId,
+        url: request.url,
+        method: request.method,
+        stack: error.stack,
+      },
+      `Unhandled error [${requestId}]: ${error.message}`,
+    );
+
+    return reply.status(500).send(errorResponse('INTERNAL_ERROR', 'Internal server error'));
+  });
+
+  // --- Monitoring & Health Checks ---
+  const { performHealthCheck, checkReadiness, checkLiveness } = await import('@libs/monitoring.js');
+
+  // Comprehensive health check (DB + Redis + Memory + Uptime)
+  app.get('/api/v1/health', async (_request, reply) => {
+    const health = await performHealthCheck();
+
+    const statusCode = health.status === 'healthy' ? 200 : health.status === 'degraded' ? 200 : 503;
+
+    return reply.status(statusCode).send(
+      successResponse(
+        health.status === 'healthy'
+          ? 'All systems operational'
+          : health.status === 'degraded'
+            ? 'Some systems degraded'
+            : 'System unhealthy',
+        health,
+      ),
+    );
+  });
+
+  // Readiness probe (for load balancers / K8s)
+  app.get('/api/v1/ready', async (_request, reply) => {
+    const ready = await checkReadiness();
+    const statusCode = ready ? 200 : 503;
+    return reply.status(statusCode).send(
+      successResponse(ready ? 'Service is ready' : 'Service not ready', {
+        ready,
+        timestamp: new Date().toISOString(),
+      })
+    );
+  });
+
+  // Liveness probe (for container orchestration)
+  app.get('/api/v1/live', (_request, reply) => {
+    const alive = checkLiveness();
+    const statusCode = alive ? 200 : 503;
+    return reply.status(statusCode).send(
+      successResponse(alive ? 'Service is alive' : 'Service not alive', {
+        alive,
+        timestamp: new Date().toISOString(),
+      })
+    );
+  });
+
+  // --- Routes ---
+  await app.register(authRoutes, { prefix: '/api/v1' });
+  await app.register(usersRoutes, { prefix: '/api/v1' });
+
+  // --- Cleanup Jobs ---
+  await registerCleanupJob(app);
+
+  return app;
+}
+
+export default buildApp;

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

@@ -1,94 +1,67 @@
-/**
- * Environment Configuration
- * 
- * Validates and exports typed environment variables using Zod.
- * Ensures all required variables are present at startup.
- */
-
-import { z } from 'zod';
-
-/**
- * Environment variable schema
- * 
- * All required variables from .env.example
- */
-const envSchema = z.object({
-    // Server Configuration
-    NODE_ENV: z
-        .enum(['development', 'production', 'test'])
-        .default('development'),
-    PORT: z.coerce.number().int().min(1).max(65535).default(3000),
-    API_PREFIX: z.string().default('/api/v1'),
-    LOG_LEVEL: z
-        .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
-        .default('info'),
-
-    // Database Configuration
-    DATABASE_URL: z.string().url().min(1),
-
-    // Redis Configuration
-    REDIS_HOST: z.string().default('localhost'),
-    REDIS_PORT: z.coerce.number().int().min(1).max(65535).default(6379),
-    REDIS_PASSWORD: z.string().optional(),
-    REDIS_DB: z.coerce.number().int().min(0).max(15).default(0),
-
-    // JWT Configuration
-    JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
-    JWT_ACCESS_EXPIRATION: z.string().default('15m'),
-    JWT_REFRESH_EXPIRATION: z.string().default('7d'),
-    JWT_ISSUER: z.string().default('{{PROJECT_NAME}}'),
-
-    // CORS Configuration
-    CORS_ALLOWED_ORIGINS: z.string().default('http://localhost:5173'),
-
-
-
-    // File Upload Configuration
-    MAX_FILE_SIZE: z.coerce.number().int().positive().default(10485760), // 10MB
-    ALLOWED_FILE_TYPES: z
-        .string()
-        .default('image/jpeg,image/png,image/webp,application/pdf'),
-    UPLOAD_DIR: z.string().default('./uploads'),
-
-    // Rate Limiting Configuration
-    RATE_LIMIT_MAX: z.coerce.number().int().positive().default(100),
-    RATE_LIMIT_WINDOW: z.coerce.number().int().positive().default(900000), // 15 minutes
-
-    // Development Tools
-    PRISMA_QUERY_LOG: z
-        .string()
-        .transform((val) => val === 'true')
-        .optional(),
-    SLOW_QUERY_THRESHOLD: z.coerce.number().int().positive().default(1000),
-});
-
-/**
- * Validate environment variables
- * 
- * Throws error if validation fails, preventing server startup
- * with invalid configuration.
- */
-const parseEnv = () => {
-    try {
-        return envSchema.parse(process.env);
-    } catch (error) {
-        if (error instanceof z.ZodError) {
-            console.error('Environment validation failed:');
-            console.error(JSON.stringify(error.errors, null, 2));
-            process.exit(1);
-        }
-        throw error;
-    }
-};
-
-/**
- * Typed environment configuration
- * 
- * Use this instead of process.env for type safety
- */
-export const env = parseEnv();
-
-/**
- * Type for environment variables
- */
-export type Env = z.infer<typeof envSchema>;
+import { z } from 'zod';
+import dotenv from 'dotenv';
+
+// Suppress dotenv's informational logs
+process.env.DOTENV_CONFIG_QUIET = 'true';
+dotenv.config();
+
+const envSchema = z.object({
+  // --- Application ---
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().int().min(1).max(65535).default(8000),
+  HOST: z.string().default('0.0.0.0'),
+
+  // --- Database (MySQL 8.0+) ---
+  DATABASE_URL: z.string().min(1, 'DATABASE_URL is required'),
+  DATABASE_POOL_MIN: z.coerce.number().int().min(1).default(2),
+  DATABASE_POOL_MAX: z.coerce.number().int().min(1).max(1000).default(10),
+
+  // --- Redis ---
+  REDIS_URL: z.string().default('redis://localhost:6379'),
+  REDIS_MAX_RETRIES: z.coerce.number().int().min(0).default(3),
+  REDIS_CONNECT_TIMEOUT: z.coerce.number().int().min(1000).default(10000), // ms
+
+  // --- JWT Authentication ---
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
+  JWT_ACCESS_EXPIRY: z.string().default('15m'),
+  JWT_REFRESH_EXPIRY: z.string().default('7d'),
+
+  // --- Cookie ---
+  // Separate secret for cookie signing (defaults to JWT_SECRET if not set)
+  COOKIE_SECRET: z.string().min(32, 'COOKIE_SECRET must be at least 32 characters').optional(),
+
+  // --- CORS ---
+  // In development: CORS_ORIGIN is optional (allows all origins)
+  // In production: REQUIRED for security
+  // Supports comma-separated multiple origins: "https://a.com,https://b.com"
+  CORS_ORIGIN: z.string().optional(),
+
+  // --- Logging ---
+  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+
+  // --- Error Tracking (Optional) ---
+  SENTRY_DSN: z.string().url().optional(),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  const formatted = parsed.error.issues
+    .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
+    .join('\n');
+
+  // eslint-disable-next-line no-console
+  console.error(`\nEnvironment validation failed:\n${formatted}\n`);
+  process.exit(1);
+}
+
+// Validate CORS_ORIGIN in production
+if (parsed.data.NODE_ENV === 'production' && !parsed.data.CORS_ORIGIN) {
+  // eslint-disable-next-line no-console
+  console.error('\nCORS_ORIGIN is required in production for security\n');
+  process.exit(1);
+}
+
+export const env = parsed.data;
+
+export type Env = z.infer<typeof envSchema>;

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

@@ -0,0 +1,88 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { v4 as uuidv4 } from 'uuid';
+import { env } from '@config/env.js';
+import { UnauthorizedError, ForbiddenError } from '@shared/errors/errors.js';
+import type { JwtPayload, UserRole } from '@shared/types/index.js';
+
+let app: FastifyInstance | null = null;
+
+export function initAuth(fastify: FastifyInstance): void {
+  app = fastify;
+}
+
+function getApp(): FastifyInstance {
+  if (!app) {
+    throw new Error('Auth not initialized. Call initAuth(fastify) before using auth helpers.');
+  }
+  return app;
+}
+
+export function signAccessToken(payload: JwtPayload): string {
+  return getApp().jwt.sign(
+    { userId: payload.userId, role: payload.role },
+    { expiresIn: env.JWT_ACCESS_EXPIRY },
+  );
+}
+
+export function generateRefreshToken(): string {
+  return uuidv4();
+}
+
+export function parseDurationMs(duration: string, fallbackMs: number): number {
+  const match = duration.match(/^(\d+)([smhd])$/);
+  if (!match) return fallbackMs;
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  const multipliers: Record<string, number> = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+
+  return value * multipliers[unit];
+}
+
+export function getRefreshTokenExpiresAt(): Date {
+  const ms = parseDurationMs(env.JWT_REFRESH_EXPIRY, 7 * 24 * 60 * 60 * 1000);
+  return new Date(Date.now() + ms);
+}
+
+export async function authenticate(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  try {
+    await request.jwtVerify();
+  } catch {
+    throw new UnauthorizedError('Invalid or expired token');
+  }
+}
+
+export async function optionalAuth(
+  request: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  try {
+    await request.jwtVerify();
+  } catch {
+    // Not authenticated — that's okay for optional auth
+  }
+}
+
+export function authorize(...roles: UserRole[]) {
+  return async function authorizeHandler(
+    request: FastifyRequest,
+    _reply: FastifyReply,
+  ): Promise<void> {
+    if (!request.user) {
+      throw new UnauthorizedError('Authentication required');
+    }
+
+    if (!roles.includes(request.user.role)) {
+      throw new ForbiddenError('Insufficient permissions');
+    }
+  };
+}
+

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

@@ -0,0 +1,35 @@
+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
+
+export async function registerCleanupJob(app: FastifyInstance): Promise<void> {
+  const intervalId = setInterval(async () => {
+    try {
+      const now = new Date();
+
+      const deletedTokens = await prisma.refreshToken.deleteMany({
+        where: { expiresAt: { lt: now } },
+      });
+
+      const deletedSessions = await prisma.session.deleteMany({
+        where: { expiresAt: { lt: now } },
+      });
+
+      if (deletedTokens.count > 0 || deletedSessions.count > 0) {
+        logger.info(
+          { deletedTokens: deletedTokens.count, deletedSessions: deletedSessions.count },
+          'Expired auth records cleaned up',
+        );
+      }
+    } catch (error) {
+      logger.error({ err: error }, 'Failed to clean up expired auth records');
+    }
+  }, CLEANUP_INTERVAL_MS);
+
+  // Clear interval on server shutdown
+  app.addHook('onClose', async () => {
+    clearInterval(intervalId);
+  });
+}

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

@@ -0,0 +1,46 @@
+import type { FastifyReply } from 'fastify';
+import { env } from '@config/env.js';
+import { parseDurationMs } from '@libs/auth.js';
+
+const isProduction = env.NODE_ENV === 'production';
+
+const ACCESS_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_ACCESS_EXPIRY, 15 * 60 * 1000);
+const REFRESH_TOKEN_MAX_AGE_MS = parseDurationMs(env.JWT_REFRESH_EXPIRY, 7 * 24 * 60 * 60 * 1000);
+
+export function setAuthCookies(
+  reply: FastifyReply,
+  accessToken: string,
+  refreshToken: string,
+): void {
+  reply.setCookie('access_token', accessToken, {
+    httpOnly: true,
+    secure: isProduction,
+    sameSite: 'strict',
+    path: '/',
+    maxAge: Math.floor(ACCESS_TOKEN_MAX_AGE_MS / 1000), // setCookie expects seconds
+  });
+
+  reply.setCookie('refresh_token', refreshToken, {
+    httpOnly: true,
+    secure: isProduction,
+    sameSite: 'strict',
+    path: '/api/v1/auth',
+    maxAge: Math.floor(REFRESH_TOKEN_MAX_AGE_MS / 1000),
+  });
+}
+
+export function clearAuthCookies(reply: FastifyReply): void {
+  reply.clearCookie('access_token', {
+    httpOnly: true,
+    secure: isProduction,
+    sameSite: 'strict',
+    path: '/',
+  });
+
+  reply.clearCookie('refresh_token', {
+    httpOnly: true,
+    secure: isProduction,
+    sameSite: 'strict',
+    path: '/api/v1/auth',
+  });
+}