create-blitzpack 0.1.0

package/template/apps/api/src/hooks/auth.ts

@@ -0,0 +1,122 @@
+import { ForbiddenError, UnauthorizedError } from '@repo/packages-utils/errors';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  name: string;
+  role: string;
+  session?: {
+    id: string;
+  };
+}
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    user?: AuthUser;
+  }
+}
+
+export async function requireAuth(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  try {
+    const session = await request.server.auth.api.getSession({
+      headers: request.headers as unknown as Headers,
+    });
+
+    if (!session?.user) {
+      throw new UnauthorizedError('Authentication required');
+    }
+
+    // Fetch user from database to check ban status and get latest role
+    const user = await request.server.prisma.user.findUnique({
+      where: { id: session.user.id },
+      select: {
+        id: true,
+        email: true,
+        name: true,
+        role: true,
+        banned: true,
+        banReason: true,
+        banExpires: true,
+      },
+    });
+
+    if (!user) {
+      request.log.warn(
+        {
+          userId: session.user.id,
+        },
+        'User not found in database'
+      );
+      throw new UnauthorizedError('User not found');
+    }
+
+    // Check if user is banned
+    if (user.banned) {
+      // Check if ban has expired
+      if (user.banExpires && new Date() > user.banExpires) {
+        // Automatically unban user
+        await request.server.prisma.user.update({
+          where: { id: user.id },
+          data: {
+            banned: false,
+            banReason: null,
+            banExpires: null,
+          },
+        });
+        request.log.info({ userId: user.id }, 'User ban expired and removed');
+      } else {
+        request.log.warn(
+          {
+            userId: user.id,
+            banReason: user.banReason,
+          },
+          'Banned user attempted to access system'
+        );
+        throw new ForbiddenError('Your account has been banned', {
+          reason: user.banReason,
+          expiresAt: user.banExpires?.toISOString(),
+        });
+      }
+    }
+
+    request.user = {
+      id: user.id,
+      email: user.email,
+      name: user.name ?? '',
+      role: user.role,
+      session: session.session
+        ? {
+            id: session.session.id,
+          }
+        : undefined,
+    };
+  } catch (error) {
+    if (error instanceof UnauthorizedError || error instanceof ForbiddenError) {
+      throw error;
+    }
+    request.log.error(error, 'Auth hook error');
+    throw new UnauthorizedError('Invalid or expired session');
+  }
+}
+
+export function requireRole(roles: string[]) {
+  return async (
+    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', {
+        required: roles,
+        current: request.user.role,
+      });
+    }
+  };
+}

package/template/apps/api/src/plugins/auth.ts

@@ -0,0 +1,198 @@
+import { betterAuth } from 'better-auth';
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+import { admin } from 'better-auth/plugins';
+import type { FastifyPluginAsync, FastifyRequest } from 'fastify';
+import fp from 'fastify-plugin';
+
+import { loadEnv } from '@/config/env.js';
+import { RATE_LIMIT_CONFIG } from '@/config/rate-limit.js';
+import { type PrismaClient } from '@/generated/client/client.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    auth: ReturnType<typeof betterAuth>;
+  }
+}
+
+const authPlugin: FastifyPluginAsync = async (app) => {
+  const env = loadEnv();
+
+  const socialProviders: Record<string, unknown> = {};
+
+  if (env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET) {
+    socialProviders.google = {
+      clientId: env.GOOGLE_CLIENT_ID,
+      clientSecret: env.GOOGLE_CLIENT_SECRET,
+    };
+  }
+
+  if (env.GITHUB_CLIENT_ID && env.GITHUB_CLIENT_SECRET) {
+    socialProviders.github = {
+      clientId: env.GITHUB_CLIENT_ID,
+      clientSecret: env.GITHUB_CLIENT_SECRET,
+    };
+  }
+
+  app.log.info(
+    `[+] OAuth configured with providers: ${Object.keys(socialProviders).join(', ')}`
+  );
+
+  const auth = betterAuth({
+    database: prismaAdapter(app.prisma as unknown as PrismaClient, {
+      provider: 'postgresql',
+    }),
+    baseURL: env.BETTER_AUTH_URL,
+    secret: env.BETTER_AUTH_SECRET,
+    emailAndPassword: {
+      enabled: true,
+      requireEmailVerification: false,
+      sendEmailVerificationOnSignUp: true,
+      autoSignInAfterVerification: true,
+      resetPasswordTokenExpiresIn: 3600,
+      sendResetPassword: async ({ user, token }) => {
+        const resetUrl = `${env.FRONTEND_URL}/reset-password?token=${token}`;
+        await app.emailService.sendPasswordResetEmail(user.email, resetUrl);
+      },
+    },
+    emailVerification: {
+      sendOnSignUp: true,
+      autoSignInAfterVerification: true,
+      sendVerificationEmail: async ({ user, url }) => {
+        const urlObj = new URL(url);
+        urlObj.searchParams.set('callbackURL', env.FRONTEND_URL);
+        await app.emailService.sendVerificationEmail(
+          user.email,
+          urlObj.toString()
+        );
+      },
+    },
+    session: {
+      expiresIn: 60 * 60 * 24 * 7, // 7 days
+      updateAge: 60 * 60 * 24, // Update every 24 hours
+      cookieCache: {
+        enabled: true,
+        maxAge: 60 * 60 * 24 * 30, // 30 days
+      },
+    },
+    advanced: {
+      // IMPORTANT: For cross-domain deployments
+      // useSecureCookies forces secure cookies even in development
+      useSecureCookies: env.NODE_ENV === 'production',
+      database: {
+        generateId: () =>
+          `auth-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      },
+      redirectURLs: {
+        onError: env.FRONTEND_URL,
+        afterSignIn: env.FRONTEND_URL,
+      },
+    },
+    trustedOrigins: [env.FRONTEND_URL],
+    socialProviders,
+    plugins: [
+      admin({
+        defaultRole: 'user',
+        adminRoles: ['admin', 'super_admin'],
+      }),
+    ],
+  });
+
+  app.decorate('auth', auth);
+
+  app.all(
+    '/api/auth/*',
+    {
+      config: {
+        rateLimit: {
+          max: RATE_LIMIT_CONFIG.routes.auth.max,
+          timeWindow: RATE_LIMIT_CONFIG.routes.auth.timeWindow,
+        },
+      },
+    },
+    async (request, reply) => {
+      try {
+        // Convert Fastify request to Web Request for Better Auth
+        const webRequest = await toWebRequest(request);
+
+        // Handle the request with Better Auth
+        const response = await auth.handler(webRequest);
+
+        // Set status
+        reply.status(response.status);
+
+        // Process headers and modify Set-Cookie for cross-domain
+        response.headers.forEach((value, key) => {
+          if (key.toLowerCase() === 'set-cookie') {
+            // For cross-domain cookie support, we need to modify cookie attributes
+            // Better Auth sets cookies, but we need to ensure SameSite=None for cross-domain
+            const cookieValue = value;
+
+            if (env.NODE_ENV === 'production') {
+              let modifiedCookie = cookieValue;
+
+              if (!modifiedCookie.includes('Secure')) {
+                modifiedCookie += '; Secure';
+              }
+
+              if (modifiedCookie.includes('SameSite=Lax')) {
+                modifiedCookie = modifiedCookie.replace(
+                  'SameSite=Lax',
+                  'SameSite=None'
+                );
+              } else if (!modifiedCookie.includes('SameSite=')) {
+                modifiedCookie += '; SameSite=None';
+              }
+
+              reply.header(key, modifiedCookie);
+            } else {
+              reply.header(key, cookieValue);
+            }
+          } else {
+            reply.header(key, value);
+          }
+        });
+
+        const body = await response.text();
+        return reply.send(body);
+      } catch (error) {
+        app.log.error(error, 'Better Auth handler error');
+        return reply.status(500).send({
+          statusCode: 500,
+          error: 'Internal Server Error',
+          message: 'Authentication error occurred',
+        });
+      }
+    }
+  );
+
+  app.log.info('[+] Better Auth configured');
+};
+
+async function toWebRequest(request: FastifyRequest): Promise<Request> {
+  const url = new URL(request.url, `${request.protocol}://${request.hostname}`);
+
+  const headers = new Headers();
+  Object.entries(request.headers).forEach(([key, value]) => {
+    if (value) {
+      const headerValue = Array.isArray(value)
+        ? value.join(', ')
+        : String(value);
+      headers.set(key, headerValue);
+    }
+  });
+
+  let body: string | null = null;
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    if (request.body) {
+      body = JSON.stringify(request.body);
+    }
+  }
+
+  return new Request(url.toString(), {
+    method: request.method,
+    headers,
+    body,
+  });
+}
+
+export default fp(authPlugin);

package/template/apps/api/src/plugins/database.ts

@@ -0,0 +1,45 @@
+import 'dotenv-flow/config';
+
+import { PrismaPg } from '@prisma/adapter-pg';
+import { type FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+import { Pool } from 'pg';
+
+import { loadEnv } from '@/config/env';
+import { PrismaClient } from '@/generated/client/client.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    prisma: PrismaClient;
+    pgPool: Pool;
+  }
+}
+
+const databasePlugin: FastifyPluginAsync = async (app) => {
+  const env = loadEnv();
+
+  const pool = new Pool({ connectionString: env.DATABASE_URL });
+  const adapter = new PrismaPg(pool);
+
+  const prisma = new PrismaClient({
+    adapter,
+    log:
+      env.LOG_LEVEL === 'verbose'
+        ? ['query', 'info', 'warn', 'error']
+        : ['warn', 'error'],
+  });
+
+  await prisma.$connect();
+  app.log.info('[+] Database connected successfully');
+
+  app.decorate('prisma', prisma);
+  app.decorate('pgPool', pool);
+
+  app.addHook('onClose', async (instance) => {
+    instance.log.info('[-] Disconnecting from database...');
+    await instance.prisma.$disconnect();
+    await instance.pgPool.end();
+  });
+};
+
+export default fp(databasePlugin);

package/template/apps/api/src/plugins/logger.ts

@@ -0,0 +1,33 @@
+import type { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+
+import { LoggerService } from '@/common/logger.service';
+import { loadEnv } from '@/config/env';
+
+const env = loadEnv();
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    logger: LoggerService;
+  }
+  interface FastifyRequest {
+    logger: LoggerService;
+  }
+}
+
+const loggerPlugin: FastifyPluginAsync = async (app) => {
+  const logger = new LoggerService(app.log);
+  logger.setContext('FastifyApp');
+
+  app.decorate('logger', logger);
+
+  app.addHook('onRequest', async (request) => {
+    request.logger = new LoggerService(request.log);
+  });
+
+  app.log.info(
+    `[+] Logger service configured with verbosity: ${env.LOG_LEVEL}`
+  );
+};
+
+export default fp(loggerPlugin);

package/template/apps/api/src/plugins/multipart.ts

@@ -0,0 +1,16 @@
+import multipart from '@fastify/multipart';
+import type { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+
+import { MAX_FILE_SIZE } from '@/utils/file-validation';
+
+const multipartPlugin: FastifyPluginAsync = async (app) => {
+  await app.register(multipart, {
+    limits: {
+      fileSize: MAX_FILE_SIZE,
+      files: 1, // Allow 1 file per request (can be increased)
+    },
+  });
+};
+
+export default fp(multipartPlugin);

package/template/apps/api/src/plugins/scalar.ts

@@ -0,0 +1,20 @@
+import apiReference from '@scalar/fastify-api-reference';
+import type { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+
+const scalarPlugin: FastifyPluginAsync = async (app) => {
+  await app.register(apiReference, {
+    routePrefix: '/docs',
+    configuration: {
+      theme: 'purple',
+      darkMode: true,
+      layout: 'modern',
+      showSidebar: true,
+      searchHotKey: 'k',
+    },
+  });
+
+  app.log.info('[+] Scalar docs available at /docs');
+};
+
+export default fp(scalarPlugin);

package/template/apps/api/src/plugins/schedule.ts

@@ -0,0 +1,52 @@
+import fastifySchedule from '@fastify/schedule';
+import type { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+import { SimpleIntervalJob, Task } from 'toad-scheduler';
+
+const schedulePlugin: FastifyPluginAsync = async (app) => {
+  // Register the schedule plugin
+  await app.register(fastifySchedule);
+
+  // Session cleanup task - runs every day at 3 AM (86400 seconds = 24 hours)
+  const sessionCleanupTask = new Task('session-cleanup', async () => {
+    const logger = app.logger.child('SessionCleanupTask');
+    logger.info('Starting expired session cleanup');
+
+    try {
+      const result = await app.prisma.session.deleteMany({
+        where: {
+          expiresAt: {
+            lt: new Date(),
+          },
+        },
+      });
+
+      logger.info('Expired sessions cleaned up successfully', {
+        deletedCount: result.count,
+      });
+    } catch (error) {
+      logger.error(
+        'Failed to cleanup expired sessions',
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  });
+
+  // Create a job that runs every 24 hours
+  const job = new SimpleIntervalJob(
+    { days: 1, runImmediately: false },
+    sessionCleanupTask
+  );
+
+  // Add the job to the scheduler
+  app.scheduler.addSimpleIntervalJob(job);
+
+  app.log.info('[+] Scheduled tasks configured');
+
+  app.addHook('onClose', async (instance) => {
+    instance.log.info('[-] Stopping scheduled tasks...');
+    instance.scheduler.stop();
+  });
+};
+
+export default fp(schedulePlugin);

package/template/apps/api/src/plugins/services.ts

@@ -0,0 +1,66 @@
+import type { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+
+import type { Env } from '@/config/env';
+import { loadEnv } from '@/config/env';
+import { AccountsService } from '@/services/accounts.service';
+import { AuthorizationService } from '@/services/authorization.service';
+import { EmailService } from '@/services/email.service';
+import { FileStorageService } from '@/services/file-storage.service';
+import { PasswordService } from '@/services/password.service';
+import { SessionsService } from '@/services/sessions.service';
+import { StatsService } from '@/services/stats.service';
+import { UploadsService } from '@/services/uploads.service';
+import { UsersService } from '@/services/users.service';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    env: Env;
+    authorizationService: AuthorizationService;
+    usersService: UsersService;
+    sessionsService: SessionsService;
+    passwordService: PasswordService;
+    emailService: EmailService;
+    fileStorageService: FileStorageService;
+    uploadsService: UploadsService;
+    accountsService: AccountsService;
+    statsService: StatsService;
+  }
+}
+
+const servicesPlugin: FastifyPluginAsync = async (app) => {
+  const env = loadEnv();
+
+  const authorizationService = new AuthorizationService(app.logger);
+  const emailService = new EmailService(env, app.logger, app.prisma);
+  const fileStorageService = new FileStorageService(env, app.logger);
+  const usersService = new UsersService(
+    app.prisma,
+    app.logger,
+    authorizationService
+  );
+  const sessionsService = new SessionsService(app.prisma, authorizationService);
+  const passwordService = new PasswordService(app.prisma, sessionsService);
+  const uploadsService = new UploadsService(
+    app.prisma,
+    fileStorageService,
+    app.logger
+  );
+  const accountsService = new AccountsService(app.prisma, app.logger);
+  const statsService = new StatsService(app.prisma, app.logger);
+
+  app.decorate('env', env);
+  app.decorate('authorizationService', authorizationService);
+  app.decorate('emailService', emailService);
+  app.decorate('fileStorageService', fileStorageService);
+  app.decorate('usersService', usersService);
+  app.decorate('sessionsService', sessionsService);
+  app.decorate('passwordService', passwordService);
+  app.decorate('uploadsService', uploadsService);
+  app.decorate('accountsService', accountsService);
+  app.decorate('statsService', statsService);
+
+  app.log.info('[+] Services configured');
+};
+
+export default fp(servicesPlugin);

package/template/apps/api/src/plugins/swagger.ts

@@ -0,0 +1,56 @@
+import swagger from '@fastify/swagger';
+import type { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+import {
+  jsonSchemaTransform,
+  type ZodTypeProvider,
+} from 'fastify-type-provider-zod';
+
+import { loadEnv } from '@/config/env';
+
+const swaggerPlugin: FastifyPluginAsync = async (app) => {
+  const env = loadEnv();
+
+  await app.withTypeProvider<ZodTypeProvider>().register(swagger, {
+    openapi: {
+      info: {
+        title: 'API',
+        description: 'Production-ready TypeScript API built with Fastify',
+        version: '1.0.0',
+      },
+      servers: [
+        {
+          url: env.API_URL,
+          description: `${env.NODE_ENV.charAt(0).toUpperCase() + env.NODE_ENV.slice(1)} server`,
+        },
+      ],
+      components: {
+        securitySchemes: {
+          cookieAuth: {
+            type: 'apiKey',
+            in: 'cookie',
+            name: 'better-auth.session_token',
+          },
+        },
+      },
+      security: [
+        {
+          cookieAuth: [],
+        },
+      ],
+      tags: [
+        { name: 'Health', description: 'Health check endpoints' },
+        { name: 'Users', description: 'User management endpoints' },
+        {
+          name: 'Auth',
+          description: 'Authentication endpoints (handled by Better Auth)',
+        },
+        { name: 'Sessions', description: 'Session management endpoints' },
+        { name: 'Password', description: 'Password management endpoints' },
+      ],
+    },
+    transform: jsonSchemaTransform,
+  });
+};
+
+export default fp(swaggerPlugin);

package/template/apps/api/src/routes/accounts.ts

@@ -0,0 +1,91 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { ZodTypeProvider } from 'fastify-type-provider-zod';
+import { z } from 'zod';
+
+import { requireAuth } from '@/hooks/auth';
+
+const accountsRoutes: FastifyPluginAsync = async (app) => {
+  const server = app.withTypeProvider<ZodTypeProvider>();
+
+  server.get(
+    '/accounts',
+    {
+      schema: {
+        description: 'Get all connected accounts for the authenticated user',
+        tags: ['Accounts'],
+        response: {
+          200: z.object({
+            userId: z.string(),
+            hasPassword: z.boolean(),
+            connectedAccounts: z.array(
+              z.object({
+                providerId: z.string(),
+                accountId: z.string(),
+                connectedAt: z.date(),
+                scope: z.string().optional(),
+              })
+            ),
+          }),
+        },
+      },
+      preHandler: requireAuth,
+    },
+    async (request) => {
+      const userId = request.user!.id;
+      return app.accountsService.getUserAccounts(userId);
+    }
+  );
+
+  server.delete(
+    '/accounts/:providerId',
+    {
+      schema: {
+        description: 'Unlink an OAuth provider from the user account',
+        tags: ['Accounts'],
+        params: z.object({
+          providerId: z.enum(['google', 'github']),
+        }),
+        response: {
+          200: z.object({
+            success: z.boolean(),
+          }),
+        },
+      },
+      preHandler: requireAuth,
+    },
+    async (request) => {
+      const userId = request.user!.id;
+      const { providerId } = request.params;
+      const result = await app.accountsService.unlinkAccount(
+        userId,
+        providerId
+      );
+
+      return result;
+    }
+  );
+
+  server.get(
+    '/accounts/can-change-password',
+    {
+      schema: {
+        description:
+          'Check if user can change password (has password set via credential provider)',
+        tags: ['Accounts'],
+        response: {
+          200: z.object({
+            canChangePassword: z.boolean(),
+          }),
+        },
+      },
+      preHandler: requireAuth,
+    },
+    async (request) => {
+      const userId = request.user!.id;
+      const canChange = await app.accountsService.canChangePassword(userId);
+      return { canChangePassword: canChange };
+    }
+  );
+};
+
+export default accountsRoutes;