create-tigra 2.2.0 → 2.3.0

package/template/server/src/libs/storage/file-storage.service.ts

@@ -2,6 +2,7 @@
  * File Storage Service
  *
  * Handles local file system operations for user-uploaded files.
+ * Directory structure: uploads/users/{userId}/<media-type>/
  */
 
 import fs from 'fs/promises';
@@ -13,24 +14,39 @@ import { generateAvatarFilename } from './filename-sanitizer.js';
 /**
  * File Storage Service
  *
- * Manages local file storage with user-specific directories and SEO-friendly naming.
+ * Manages local file storage with per-user directories and SEO-friendly naming.
+ * All user media lives under uploads/users/{userId}/ for easy per-user cleanup.
  */
 class FileStorageService {
   private readonly uploadDir: string;
-  private readonly avatarsDir: string;
+  private readonly usersDir: string;
 
   constructor() {
     // Base upload directory: server/uploads
     this.uploadDir = path.join(process.cwd(), 'uploads');
-    // Avatars subdirectory: server/uploads/avatars
-    this.avatarsDir = path.join(this.uploadDir, 'avatars');
+    // Users media directory: server/uploads/users
+    this.usersDir = path.join(this.uploadDir, 'users');
+  }
+
+  /**
+   * Gets the base directory for a user's media
+   */
+  private getUserDir(userId: string): string {
+    return path.join(this.usersDir, userId);
+  }
+
+  /**
+   * Gets the avatar directory for a user
+   */
+  private getUserAvatarDir(userId: string): string {
+    return path.join(this.getUserDir(userId), 'avatar');
   }
 
   /**
    * Saves an avatar image to user-specific directory
    *
    * Process:
-   * 1. Create user directory if it doesn't exist
+   * 1. Create user avatar directory if it doesn't exist
    * 2. Generate SEO-friendly filename
    * 3. Save buffer to file (overwrites existing avatar)
    * 4. Return filename and public URL
@@ -50,7 +66,7 @@ class FileStorageService {
    *   'Doe'
    * );
    * // filename: "john-doe-avatar.webp"
-   * // url: "/uploads/avatars/{userId}/john-doe-avatar.webp"
+   * // url: "/uploads/users/{userId}/avatar/john-doe-avatar.webp"
    * ```
    */
   async saveAvatar(
@@ -61,18 +77,18 @@ class FileStorageService {
   ): Promise<{ filename: string; url: string }> {
     try {
       // Ensure user's avatar directory exists
-      const userDir = path.join(this.avatarsDir, userId);
-      await this.ensureDirectoryExists(userDir);
+      const avatarDir = this.getUserAvatarDir(userId);
+      await this.ensureDirectoryExists(avatarDir);
 
       // Generate SEO-friendly filename
       const filename = generateAvatarFilename(firstName, lastName, 'webp');
-      const filePath = path.join(userDir, filename);
+      const filePath = path.join(avatarDir, filename);
 
       // Write file to disk (overwrites existing)
       await fs.writeFile(filePath, buffer);
 
       // Generate public URL
-      const url = `/uploads/avatars/${userId}/${filename}`;
+      const url = `/uploads/users/${userId}/avatar/${filename}`;
 
       logger.info({
         msg: 'Avatar saved successfully',
@@ -101,17 +117,17 @@ class FileStorageService {
    */
   async deleteAvatar(userId: string): Promise<void> {
     try {
-      const userDir = path.join(this.avatarsDir, userId);
+      const avatarDir = this.getUserAvatarDir(userId);
 
       // Check if directory exists
-      const exists = await this.directoryExists(userDir);
+      const exists = await this.directoryExists(avatarDir);
       if (!exists) {
         logger.info({ msg: 'Avatar directory does not exist, nothing to delete', userId });
         return;
       }
 
-      // Delete entire user directory and contents
-      await fs.rm(userDir, { recursive: true, force: true });
+      // Delete avatar directory and contents
+      await fs.rm(avatarDir, { recursive: true, force: true });
 
       logger.info({ msg: 'Avatar deleted successfully', userId });
     } catch (error) {
@@ -120,6 +136,37 @@ class FileStorageService {
     }
   }
 
+  /**
+   * Deletes all media for a user (entire user directory)
+   *
+   * Used by the cleanup job when permanently purging deleted accounts.
+   * No-op if the user directory doesn't exist.
+   *
+   * @param userId - User's unique ID
+   *
+   * @example
+   * ```typescript
+   * await fileStorageService.deleteUserMedia(userId);
+   * ```
+   */
+  async deleteUserMedia(userId: string): Promise<void> {
+    try {
+      const userDir = this.getUserDir(userId);
+
+      const exists = await this.directoryExists(userDir);
+      if (!exists) {
+        return;
+      }
+
+      await fs.rm(userDir, { recursive: true, force: true });
+
+      logger.info({ msg: 'User media deleted successfully', userId });
+    } catch (error) {
+      logger.error({ err: error, msg: 'Failed to delete user media', userId });
+      throw new InternalError('Failed to delete user media', 'FILE_DELETE_FAILED');
+    }
+  }
+
   /**
    * Gets the full file system path for an avatar
    *
@@ -128,7 +175,7 @@ class FileStorageService {
    * @returns Absolute file path
    */
   getAvatarPath(userId: string, filename: string): string {
-    return path.join(this.avatarsDir, userId, filename);
+    return path.join(this.getUserAvatarDir(userId), filename);
   }
 
   /**
@@ -139,7 +186,7 @@ class FileStorageService {
    * @returns Public URL path
    */
   getAvatarUrl(userId: string, filename: string): string {
-    return `/uploads/avatars/${userId}/${filename}`;
+    return `/uploads/users/${userId}/avatar/${filename}`;
   }
 
   /**
@@ -192,13 +239,13 @@ class FileStorageService {
   /**
    * Initializes the upload directory structure
    *
-   * Creates base uploads directory and avatars subdirectory if they don't exist.
+   * Creates base uploads directory and users subdirectory if they don't exist.
    * Should be called at application startup.
    */
   async initialize(): Promise<void> {
     try {
       await this.ensureDirectoryExists(this.uploadDir);
-      await this.ensureDirectoryExists(this.avatarsDir);
+      await this.ensureDirectoryExists(this.usersDir);
       logger.info({ msg: 'File storage initialized', uploadDir: this.uploadDir });
     } catch (error) {
       logger.error({ err: error, msg: 'Failed to initialize file storage' });

package/template/server/src/libs/storage/file-validator.ts

@@ -43,14 +43,6 @@ export function validateImageFile(file: MultipartFile): void {
     throw new ValidationError('No file was uploaded', 'FILE_REQUIRED');
   }
 
-  // Validate file size
-  if (!file.file.bytesRead) {
-    throw new ValidationError('Uploaded file is empty', 'FILE_EMPTY');
-  }
-
-  // Note: file.file.bytesRead might not be available until the stream is consumed
-  // For proper size validation, we'll need to check this during buffer reading
-
   // Validate MIME type
   const mimeType = file.mimetype;
   if (!(FILE_UPLOAD_CONSTANTS.ALLOWED_MIME_TYPES as readonly string[]).includes(mimeType)) {

package/template/server/src/modules/admin/admin.controller.ts

@@ -5,7 +5,8 @@ import { ValidationError } from '@shared/errors/errors.js';
 import { blockIp, unblockIp, getBlockedIps } from '@libs/ip-block.js';
 
 const blockIpSchema = z.object({
-  ip: z.string().ip({ message: 'Invalid IP address' }),
+  ip: z.union([z.ipv4(), z.ipv6()], { message: 'Invalid IP address' }),
+  reason: z.string().max(500).optional(),
 });
 
 type BlockIpBody = z.infer<typeof blockIpSchema>;
@@ -27,8 +28,8 @@ export async function blockIpHandler(
   if (!parsed.success) {
     throw new ValidationError(parsed.error.issues[0]?.message ?? 'Invalid IP address', 'INVALID_IP');
   }
-  await blockIp(parsed.data.ip);
-  reply.status(201).send(successResponse('IP blocked successfully', { ip: parsed.data.ip }));
+  const blocked = await blockIp(parsed.data.ip, request.user.userId, parsed.data.reason);
+  reply.status(201).send(successResponse('IP blocked successfully', blocked));
 }
 
 export async function unblockIpHandler(

package/template/server/src/modules/auth/auth.repo.ts

@@ -6,6 +6,24 @@ export async function findUserByEmail(email: string) {
   });
 }
 
+export async function findDeletedUserByEmail(email: string) {
+  return prisma.user.findFirst({
+    where: { email, deletedAt: { not: null } },
+  });
+}
+
+export async function restoreUser(userId: string): Promise<void> {
+  await prisma.user.update({
+    where: { id: userId },
+    data: {
+      deletedAt: null,
+      isActive: true,
+      failedLoginAttempts: 0,
+      lockedUntil: null,
+    },
+  });
+}
+
 export async function findUserById(id: string) {
   return prisma.user.findUnique({
     where: { id, deletedAt: null },

package/template/server/src/modules/auth/auth.service.ts

@@ -78,6 +78,15 @@ export async function register(
     throw new ConflictError('Email already registered', 'EMAIL_ALREADY_EXISTS');
   }
 
+  // Check if a soft-deleted account exists with this email — direct them to login to restore
+  const deletedUser = await authRepo.findDeletedUserByEmail(input.email);
+  if (deletedUser) {
+    throw new ConflictError(
+      'An account with this email was recently deleted. Log in to restore it.',
+      'EMAIL_ALREADY_EXISTS',
+    );
+  }
+
   const hashedPassword = await hashPassword(input.password);
 
   const user = await authRepo.createUser({
@@ -119,40 +128,57 @@ export async function login(
   deviceInfo?: string,
   ipAddress?: string,
 ): Promise<AuthResult> {
-  const user = await authRepo.findUserByEmail(input.email);
-  if (!user) {
-    throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
-  }
+  let user = await authRepo.findUserByEmail(input.email);
 
-  // Generic error for disabled accounts — prevent info leakage
-  if (!user.isActive) {
-    throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
-  }
+  // If no active user found, check for a soft-deleted account that can be restored
+  if (!user) {
+    const deletedUser = await authRepo.findDeletedUserByEmail(input.email);
+    if (!deletedUser) {
+      throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
+    }
 
-  // Check account lockout
-  if (user.lockedUntil && user.lockedUntil > new Date()) {
-    throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
-  }
+    // Verify password before restoring — don't restore on wrong password
+    const validPassword = await verifyPassword(input.password, deletedUser.password);
+    if (!validPassword) {
+      throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
+    }
 
-  const valid = await verifyPassword(input.password, user.password);
+    // Restore account: clears deletedAt, sets isActive = true, resets lockout
+    await authRepo.restoreUser(deletedUser.id);
+    user = { ...deletedUser, deletedAt: null, isActive: true, failedLoginAttempts: 0, lockedUntil: null };
+  } else {
+    // Normal login flow for active accounts
 
-  if (!valid) {
-    // Increment failed attempts
-    const newAttempts = user.failedLoginAttempts + 1;
-    await authRepo.incrementFailedAttempts(user.id);
+    // Generic error for disabled accounts — prevent info leakage
+    if (!user.isActive) {
+      throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
+    }
 
-    // Check if we need to lock the account
-    const lockDuration = getLockoutDuration(newAttempts);
-    if (lockDuration) {
-      await authRepo.setAccountLock(user.id, new Date(Date.now() + lockDuration));
+    // Check account lockout
+    if (user.lockedUntil && user.lockedUntil > new Date()) {
+      throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
     }
 
-    throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
-  }
+    const valid = await verifyPassword(input.password, user.password);
+
+    if (!valid) {
+      // Increment failed attempts
+      const newAttempts = user.failedLoginAttempts + 1;
+      await authRepo.incrementFailedAttempts(user.id);
+
+      // Check if we need to lock the account
+      const lockDuration = getLockoutDuration(newAttempts);
+      if (lockDuration) {
+        await authRepo.setAccountLock(user.id, new Date(Date.now() + lockDuration));
+      }
+
+      throw new UnauthorizedError('Invalid email or password', 'INVALID_CREDENTIALS');
+    }
 
-  // Successful login — reset failed attempts
-  if (user.failedLoginAttempts > 0 || user.lockedUntil) {
-    await authRepo.resetFailedAttempts(user.id);
+    // Successful login — reset failed attempts
+    if (user.failedLoginAttempts > 0 || user.lockedUntil) {
+      await authRepo.resetFailedAttempts(user.id);
+    }
   }
 
   const accessToken = signAccessToken({

package/template/server/src/modules/users/users.controller.ts

@@ -10,7 +10,8 @@ import { usersService } from './users.service.js';
 import { validateImageFile, validateFileSize } from '@libs/storage/file-validator.js';
 import { successResponse } from '@shared/responses/successResponse.js';
 import { clearAuthCookies } from '@libs/cookies.js';
-import type { GetUserAvatarParams, UpdateProfileInput, ChangePasswordInput, DeleteAccountInput } from './users.schemas.js';
+import { ChangePasswordSchema, AdminChangePasswordSchema, DeleteAccountSchema } from './users.schemas.js';
+import type { GetUserAvatarParams, UpdateProfileInput } from './users.schemas.js';
 import type { AuthenticatedRequest } from '@shared/types/index.js';
 import { logger } from '@libs/logger.js';
 import { BadRequestError } from '@shared/errors/errors.js';
@@ -48,8 +49,8 @@ class UsersController {
     // Validate file size
     validateFileSize(buffer);
 
-    // Get authenticated user ID
-    const userId = request.user.userId;
+    // Get target user ID (set by resolveMe or resolveTargetUser middleware)
+    const userId = request.targetUserId!;
 
     logger.info({
       msg: 'Avatar upload request',
@@ -79,8 +80,8 @@ class UsersController {
    * @param reply - Fastify reply
    */
   async deleteAvatar(request: AuthenticatedRequest, reply: FastifyReply): Promise<void> {
-    // Get authenticated user ID
-    const userId = request.user.userId;
+    // Get target user ID (set by resolveMe or resolveTargetUser middleware)
+    const userId = request.targetUserId!;
 
     logger.info({ msg: 'Avatar delete request', userId });
 
@@ -126,14 +127,15 @@ class UsersController {
    * @param reply - Fastify reply
    */
   async updateProfile(
-    request: FastifyRequest<{ Body: UpdateProfileInput }>,
+    request: FastifyRequest,
     reply: FastifyReply
   ): Promise<void> {
-    const userId = request.user.userId;
+    const userId = request.targetUserId!;
+    const body = request.body as UpdateProfileInput;
 
     logger.info({ msg: 'Update profile request', userId });
 
-    const updatedUser = await usersService.updateProfile(userId, request.body);
+    const updatedUser = await usersService.updateProfile(userId, body);
 
     return reply.send(successResponse('Profile updated successfully', updatedUser));
   }
@@ -148,14 +150,21 @@ class UsersController {
    * @param reply - Fastify reply
    */
   async changePassword(
-    request: FastifyRequest<{ Body: ChangePasswordInput }>,
+    request: FastifyRequest,
     reply: FastifyReply
   ): Promise<void> {
-    const userId = request.user.userId;
-
-    logger.info({ msg: 'Change password request', userId });
-
-    await usersService.changePassword(userId, request.body);
+    const userId = request.targetUserId!;
+    const isAdminAction = request.isAdminAction ?? false;
+
+    if (isAdminAction) {
+      const parsed = AdminChangePasswordSchema.parse(request.body);
+      logger.info({ msg: 'Admin change password request', targetUserId: userId, adminUserId: request.user.userId });
+      await usersService.changePassword(userId, parsed, true);
+    } else {
+      const parsed = ChangePasswordSchema.parse(request.body);
+      logger.info({ msg: 'Change password request', userId });
+      await usersService.changePassword(userId, parsed, false);
+    }
 
     return reply.send(successResponse('Password changed successfully', null));
   }
@@ -170,16 +179,25 @@ class UsersController {
    * @param reply - Fastify reply
    */
   async deleteAccount(
-    request: FastifyRequest<{ Body: DeleteAccountInput }>,
+    request: FastifyRequest,
     reply: FastifyReply
   ): Promise<void> {
-    const userId = request.user.userId;
-
-    logger.info({ msg: 'Delete account request', userId });
-
-    await usersService.deleteAccount(userId, request.body.password);
+    const userId = request.targetUserId!;
+    const isAdminAction = request.isAdminAction ?? false;
+
+    if (isAdminAction) {
+      logger.info({ msg: 'Admin delete account request', targetUserId: userId, adminUserId: request.user.userId });
+      await usersService.deleteAccount(userId, '', true);
+    } else {
+      const parsed = DeleteAccountSchema.parse(request.body);
+      logger.info({ msg: 'Delete account request', userId });
+      await usersService.deleteAccount(userId, parsed.password, false);
+    }
 
-    clearAuthCookies(reply);
+    // Only clear cookies if the user is deleting their OWN account
+    if (!isAdminAction) {
+      clearAuthCookies(reply);
+    }
 
     return reply.send(successResponse('Account deleted successfully', null));
   }

package/template/server/src/modules/users/users.routes.ts

@@ -8,11 +8,12 @@ import type { FastifyInstance } from 'fastify';
 import { usersController } from './users.controller.js';
 import {
   GetUserAvatarSchema,
+  UserIdParamSchema,
   UpdateProfileSchema,
   ChangePasswordSchema,
   DeleteAccountSchema,
 } from './users.schemas.js';
-import { authenticate } from '@libs/auth.js';
+import { authenticate, resolveMe, resolveTargetUser } from '@libs/auth.js';
 import { RATE_LIMITS } from '@config/rate-limit.config.js';
 
 /**
@@ -25,6 +26,11 @@ import { RATE_LIMITS } from '@config/rate-limit.config.js';
  * - POST   /users/avatar          - Upload avatar (authenticated)
  * - DELETE /users/avatar          - Delete avatar (authenticated)
  * - GET    /users/:userId/avatar  - Get avatar (public)
+ * - PATCH  /users/:userId         - Update profile (owner or admin)
+ * - PATCH  /users/:userId/password - Change password (owner or admin)
+ * - DELETE /users/:userId         - Delete account (owner or admin)
+ * - POST   /users/:userId/avatar  - Upload avatar (owner or admin)
+ * - DELETE /users/:userId/avatar  - Delete avatar (owner or admin)
  *
  * @param fastify - Fastify instance
  */
@@ -42,7 +48,7 @@ export async function usersRoutes(fastify: FastifyInstance): Promise<void> {
   fastify.patch(
     '/users/me',
     {
-      preValidation: [authenticate],
+      preValidation: [authenticate, resolveMe],
       schema: {
         body: UpdateProfileSchema,
       },
@@ -64,7 +70,7 @@ export async function usersRoutes(fastify: FastifyInstance): Promise<void> {
   fastify.patch(
     '/users/me/password',
     {
-      preValidation: [authenticate],
+      preValidation: [authenticate, resolveMe],
       schema: {
         body: ChangePasswordSchema,
       },
@@ -86,7 +92,7 @@ export async function usersRoutes(fastify: FastifyInstance): Promise<void> {
   fastify.delete(
     '/users/me',
     {
-      preValidation: [authenticate],
+      preValidation: [authenticate, resolveMe],
       schema: {
         body: DeleteAccountSchema,
       },
@@ -111,7 +117,7 @@ export async function usersRoutes(fastify: FastifyInstance): Promise<void> {
   fastify.post(
     '/users/avatar',
     {
-      preValidation: [authenticate],
+      preValidation: [authenticate, resolveMe],
       config: {
         rateLimit: RATE_LIMITS.USERS_UPLOAD_AVATAR,
       },
@@ -129,7 +135,7 @@ export async function usersRoutes(fastify: FastifyInstance): Promise<void> {
   fastify.delete(
     '/users/avatar',
     {
-      preValidation: [authenticate],
+      preValidation: [authenticate, resolveMe],
       config: {
         rateLimit: RATE_LIMITS.USERS_DELETE_AVATAR,
       },
@@ -156,4 +162,119 @@ export async function usersRoutes(fastify: FastifyInstance): Promise<void> {
     },
     usersController.getAvatar.bind(usersController)
   );
+
+  // --- /users/:userId variants (owner or admin) ---
+
+  /**
+   * Update profile (by user ID)
+   *
+   * PATCH /api/v1/users/:userId
+   * Body: { firstName?, lastName? }
+   * Auth: Required (owner or admin)
+   * Rate limit: 10 requests per minute
+   */
+  fastify.patch(
+    '/users/:userId',
+    {
+      preValidation: [authenticate, resolveTargetUser],
+      schema: {
+        params: UserIdParamSchema,
+        body: UpdateProfileSchema,
+      },
+      config: {
+        rateLimit: RATE_LIMITS.USERS_UPDATE_PROFILE,
+      },
+    },
+    usersController.updateProfile.bind(usersController)
+  );
+
+  /**
+   * Change password (by user ID)
+   *
+   * PATCH /api/v1/users/:userId/password
+   * Body (owner): { currentPassword, newPassword }
+   * Body (admin): { newPassword }
+   * Auth: Required (owner or admin)
+   * Rate limit: 5 requests per minute
+   */
+  fastify.patch(
+    '/users/:userId/password',
+    {
+      preValidation: [authenticate, resolveTargetUser],
+      schema: {
+        params: UserIdParamSchema,
+      },
+      config: {
+        rateLimit: RATE_LIMITS.USERS_CHANGE_PASSWORD,
+      },
+    },
+    usersController.changePassword.bind(usersController)
+  );
+
+  /**
+   * Delete account (by user ID)
+   *
+   * DELETE /api/v1/users/:userId
+   * Body (owner): { password }
+   * Body (admin): empty
+   * Auth: Required (owner or admin)
+   * Rate limit: 3 requests per minute
+   */
+  fastify.delete(
+    '/users/:userId',
+    {
+      preValidation: [authenticate, resolveTargetUser],
+      schema: {
+        params: UserIdParamSchema,
+      },
+      config: {
+        rateLimit: RATE_LIMITS.USERS_DELETE_ACCOUNT,
+      },
+    },
+    usersController.deleteAccount.bind(usersController)
+  );
+
+  /**
+   * Upload avatar (by user ID)
+   *
+   * POST /api/v1/users/:userId/avatar
+   * Content-Type: multipart/form-data
+   * Body: { file: File }
+   * Auth: Required (owner or admin)
+   * Rate limit: 5 requests per minute
+   */
+  fastify.post(
+    '/users/:userId/avatar',
+    {
+      preValidation: [authenticate, resolveTargetUser],
+      schema: {
+        params: UserIdParamSchema,
+      },
+      config: {
+        rateLimit: RATE_LIMITS.USERS_UPLOAD_AVATAR,
+      },
+    },
+    usersController.uploadAvatar.bind(usersController)
+  );
+
+  /**
+   * Delete avatar (by user ID)
+   *
+   * DELETE /api/v1/users/:userId/avatar
+   * Auth: Required (owner or admin)
+   * Rate limit: 10 requests per minute
+   */
+  fastify.delete(
+    '/users/:userId/avatar',
+    {
+      preValidation: [authenticate, resolveTargetUser],
+      schema: {
+        params: UserIdParamSchema,
+      },
+      config: {
+        rateLimit: RATE_LIMITS.USERS_DELETE_AVATAR,
+      },
+    },
+    usersController.deleteAvatar.bind(usersController)
+  );
 }