create-tigra 1.1.0 → 2.0.1

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

@@ -0,0 +1,211 @@
+/**
+ * File Storage Service
+ *
+ * Handles local file system operations for user-uploaded files.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { logger } from '@libs/logger.js';
+import { InternalError } from '@shared/errors/errors.js';
+import { generateAvatarFilename } from './filename-sanitizer.js';
+
+/**
+ * File Storage Service
+ *
+ * Manages local file storage with user-specific directories and SEO-friendly naming.
+ */
+class FileStorageService {
+  private readonly uploadDir: string;
+  private readonly avatarsDir: 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');
+  }
+
+  /**
+   * Saves an avatar image to user-specific directory
+   *
+   * Process:
+   * 1. Create user 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
+   *
+   * @param userId - User's unique ID
+   * @param buffer - Optimized image buffer
+   * @param firstName - User's first name (for SEO filename)
+   * @param lastName - User's last name (for SEO filename)
+   * @returns Filename and URL of saved avatar
+   *
+   * @example
+   * ```typescript
+   * const { filename, url } = await fileStorageService.saveAvatar(
+   *   userId,
+   *   imageBuffer,
+   *   'John',
+   *   'Doe'
+   * );
+   * // filename: "john-doe-avatar.webp"
+   * // url: "/uploads/avatars/{userId}/john-doe-avatar.webp"
+   * ```
+   */
+  async saveAvatar(
+    userId: string,
+    buffer: Buffer,
+    firstName: string,
+    lastName: string
+  ): Promise<{ filename: string; url: string }> {
+    try {
+      // Ensure user's avatar directory exists
+      const userDir = path.join(this.avatarsDir, userId);
+      await this.ensureDirectoryExists(userDir);
+
+      // Generate SEO-friendly filename
+      const filename = generateAvatarFilename(firstName, lastName, 'webp');
+      const filePath = path.join(userDir, filename);
+
+      // Write file to disk (overwrites existing)
+      await fs.writeFile(filePath, buffer);
+
+      // Generate public URL
+      const url = `/uploads/avatars/${userId}/${filename}`;
+
+      logger.info({
+        msg: 'Avatar saved successfully',
+        userId,
+        filename,
+        fileSize: buffer.length,
+      });
+
+      return { filename, url };
+    } catch (error) {
+      logger.error({ err: error, msg: 'Failed to save avatar', userId });
+      throw new InternalError('Failed to save avatar file', 'FILE_SAVE_FAILED');
+    }
+  }
+
+  /**
+   * Deletes a user's avatar directory and all contents
+   *
+   * @param userId - User's unique ID
+   * @throws InternalError if deletion fails
+   *
+   * @example
+   * ```typescript
+   * await fileStorageService.deleteAvatar(userId);
+   * ```
+   */
+  async deleteAvatar(userId: string): Promise<void> {
+    try {
+      const userDir = path.join(this.avatarsDir, userId);
+
+      // Check if directory exists
+      const exists = await this.directoryExists(userDir);
+      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 });
+
+      logger.info({ msg: 'Avatar deleted successfully', userId });
+    } catch (error) {
+      logger.error({ err: error, msg: 'Failed to delete avatar', userId });
+      throw new InternalError('Failed to delete avatar file', 'FILE_DELETE_FAILED');
+    }
+  }
+
+  /**
+   * Gets the full file system path for an avatar
+   *
+   * @param userId - User's unique ID
+   * @param filename - Avatar filename
+   * @returns Absolute file path
+   */
+  getAvatarPath(userId: string, filename: string): string {
+    return path.join(this.avatarsDir, userId, filename);
+  }
+
+  /**
+   * Gets the public URL for an avatar
+   *
+   * @param userId - User's unique ID
+   * @param filename - Avatar filename
+   * @returns Public URL path
+   */
+  getAvatarUrl(userId: string, filename: string): string {
+    return `/uploads/avatars/${userId}/${filename}`;
+  }
+
+  /**
+   * Checks if a file exists
+   *
+   * @param filePath - Full file path
+   * @returns True if file exists
+   */
+  async fileExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Ensures a directory exists, creates it if not
+   *
+   * @param dirPath - Directory path
+   * @private
+   */
+  private async ensureDirectoryExists(dirPath: string): Promise<void> {
+    try {
+      await fs.access(dirPath);
+    } catch {
+      // Directory doesn't exist, create it
+      await fs.mkdir(dirPath, { recursive: true });
+      logger.info({ msg: 'Created directory', dirPath });
+    }
+  }
+
+  /**
+   * Checks if a directory exists
+   *
+   * @param dirPath - Directory path
+   * @returns True if directory exists
+   * @private
+   */
+  private async directoryExists(dirPath: string): Promise<boolean> {
+    try {
+      const stats = await fs.stat(dirPath);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Initializes the upload directory structure
+   *
+   * Creates base uploads directory and avatars 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);
+      logger.info({ msg: 'File storage initialized', uploadDir: this.uploadDir });
+    } catch (error) {
+      logger.error({ err: error, msg: 'Failed to initialize file storage' });
+      throw new InternalError('Failed to initialize file storage', 'STORAGE_INIT_FAILED');
+    }
+  }
+}
+
+// Export singleton instance
+export const fileStorageService = new FileStorageService();

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

@@ -0,0 +1,97 @@
+/**
+ * File Upload Validator
+ *
+ * Validates uploaded files for security and compliance with upload constraints.
+ */
+
+import type { MultipartFile } from '@fastify/multipart';
+import { ValidationError } from '@shared/errors/errors.js';
+import path from 'path';
+
+/**
+ * File upload constants and constraints
+ */
+export const FILE_UPLOAD_CONSTANTS = {
+  MAX_FILE_SIZE: 5 * 1024 * 1024, // 5MB in bytes
+  ALLOWED_MIME_TYPES: ['image/jpeg', 'image/png', 'image/webp'] as const,
+  ALLOWED_EXTENSIONS: ['.jpg', '.jpeg', '.png', '.webp'] as const,
+  AVATAR_MAX_DIMENSION: 512, // pixels
+} as const;
+
+/**
+ * Validates an uploaded image file
+ *
+ * Checks:
+ * - File size within limits
+ * - MIME type is allowed
+ * - File extension is allowed (prevents disguised files)
+ * - File is not executable
+ *
+ * @param file - Fastify multipart file object
+ * @throws ValidationError if file is invalid
+ *
+ * @example
+ * ```typescript
+ * const file = await request.file();
+ * validateImageFile(file); // Throws if invalid
+ * ```
+ */
+export function validateImageFile(file: MultipartFile): void {
+  // Validate file exists
+  if (!file) {
+    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)) {
+    throw new ValidationError(
+      `Invalid file type. Allowed types: ${FILE_UPLOAD_CONSTANTS.ALLOWED_MIME_TYPES.join(', ')}`,
+      'INVALID_FILE_TYPE'
+    );
+  }
+
+  // Validate file extension (prevents MIME type spoofing)
+  const extension = path.extname(file.filename).toLowerCase();
+  if (!(FILE_UPLOAD_CONSTANTS.ALLOWED_EXTENSIONS as readonly string[]).includes(extension)) {
+    throw new ValidationError(
+      `Invalid file extension. Allowed extensions: ${FILE_UPLOAD_CONSTANTS.ALLOWED_EXTENSIONS.join(', ')}`,
+      'INVALID_FILE_EXTENSION'
+    );
+  }
+
+  // Prevent executable files (extra security layer)
+  const dangerousExtensions = ['.exe', '.sh', '.bat', '.cmd', '.com', '.pif', '.scr', '.vbs', '.js'];
+  const lowerFilename = file.filename.toLowerCase();
+  if (dangerousExtensions.some((ext) => lowerFilename.endsWith(ext))) {
+    throw new ValidationError('Executable files are not allowed', 'DANGEROUS_FILE');
+  }
+}
+
+/**
+ * Validates file buffer size
+ *
+ * @param buffer - File buffer
+ * @throws ValidationError if buffer exceeds max size
+ */
+export function validateFileSize(buffer: Buffer): void {
+  if (buffer.length === 0) {
+    throw new ValidationError('Uploaded file is empty', 'FILE_EMPTY');
+  }
+
+  if (buffer.length > FILE_UPLOAD_CONSTANTS.MAX_FILE_SIZE) {
+    const maxSizeMB = FILE_UPLOAD_CONSTANTS.MAX_FILE_SIZE / (1024 * 1024);
+    throw new ValidationError(
+      `File size exceeds maximum allowed size of ${maxSizeMB}MB`,
+      'FILE_TOO_LARGE'
+    );
+  }
+}

package/template/server/src/libs/storage/filename-sanitizer.ts

@@ -0,0 +1,71 @@
+/**
+ * Filename Sanitizer Utility
+ *
+ * Generates SEO-friendly, URL-safe filenames from user names.
+ * Supports international characters including Georgian letters.
+ */
+
+/**
+ * Sanitizes text for use in filenames
+ *
+ * Rules:
+ * - Convert to lowercase
+ * - Replace spaces with hyphens
+ * - Keep only: a-z, 0-9, hyphens, Georgian letters (ა-ჰ), common diacritics (à-ÿ)
+ * - Replace multiple consecutive hyphens with single hyphen
+ * - Remove leading/trailing hyphens
+ *
+ * @param text - Text to sanitize
+ * @returns Sanitized filename-safe string
+ *
+ * @example
+ * sanitizeForFilename("John Doe") // "john-doe"
+ * sanitizeForFilename("მარიამ გელაშვილი") // "მარიამ-გელაშვილი"
+ * sanitizeForFilename("José García-López") // "jose-garcia-lopez"
+ * sanitizeForFilename("Anna  Marie O'Brien") // "anna-marie-obrien"
+ */
+export function sanitizeForFilename(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      .trim()
+      // Replace spaces with hyphens
+      .replace(/\s+/g, '-')
+      // Keep only: a-z, 0-9, hyphens, Georgian letters (ა-ჰ), common diacritics (à-ÿ)
+      .replace(/[^a-z0-9\-ა-ჰà-ÿ]/g, '')
+      // Replace multiple consecutive hyphens with single hyphen
+      .replace(/-+/g, '-')
+      // Remove leading/trailing hyphens
+      .replace(/^-|-$/g, '')
+  );
+}
+
+/**
+ * Generates an SEO-friendly avatar filename based on user's name
+ *
+ * Format: {firstName}-{lastName}-avatar.{extension}
+ *
+ * @param firstName - User's first name
+ * @param lastName - User's last name
+ * @param extension - File extension (default: 'webp')
+ * @returns SEO-friendly filename
+ *
+ * @example
+ * generateAvatarFilename("John", "Doe") // "john-doe-avatar.webp"
+ * generateAvatarFilename("მარიამ", "გელაშვილი") // "მარიამ-გელაშვილი-avatar.webp"
+ * generateAvatarFilename("José", "García", "jpg") // "jose-garcia-avatar.jpg"
+ */
+export function generateAvatarFilename(
+  firstName: string,
+  lastName: string,
+  extension: string = 'webp'
+): string {
+  const sanitizedFirst = sanitizeForFilename(firstName);
+  const sanitizedLast = sanitizeForFilename(lastName);
+
+  // Handle edge case where sanitization results in empty string
+  const first = sanitizedFirst || 'user';
+  const last = sanitizedLast || 'avatar';
+
+  return `${first}-${last}-avatar.${extension}`;
+}

package/template/server/src/libs/storage/image-optimizer.service.ts

@@ -0,0 +1,144 @@
+/**
+ * Image Optimization Service
+ *
+ * Handles image processing, optimization, and validation using Sharp.
+ */
+
+import sharp from 'sharp';
+import { FILE_UPLOAD_CONSTANTS } from './file-validator.js';
+import { ValidationError, InternalError } from '@shared/errors/errors.js';
+import { logger } from '@libs/logger.js';
+
+/**
+ * Image Optimizer Service
+ *
+ * Provides methods for optimizing and validating images for avatar uploads.
+ */
+class ImageOptimizerService {
+  /**
+   * Optimizes an image for avatar use
+   *
+   * Process:
+   * 1. Resize to max 512x512 (preserves aspect ratio)
+   * 2. Convert to WebP format for best compression
+   * 3. Compress to ~85% quality
+   * 4. Strip EXIF metadata for privacy
+   *
+   * @param buffer - Original image buffer
+   * @returns Optimized image buffer in WebP format
+   * @throws ValidationError if image is invalid
+   * @throws InternalError if optimization fails
+   *
+   * @example
+   * ```typescript
+   * const optimized = await imageOptimizerService.optimizeAvatar(imageBuffer);
+   * ```
+   */
+  async optimizeAvatar(buffer: Buffer): Promise<Buffer> {
+    try {
+      // Validate that buffer contains a valid image
+      const metadata = await sharp(buffer).metadata();
+
+      if (!metadata.width || !metadata.height) {
+        throw new ValidationError('Unable to read image dimensions', 'INVALID_IMAGE');
+      }
+
+      logger.info({
+        msg: 'Optimizing avatar image',
+        originalFormat: metadata.format,
+        originalSize: buffer.length,
+        originalDimensions: `${metadata.width}x${metadata.height}`,
+      });
+
+      // Optimize image
+      const optimized = await sharp(buffer)
+        // Resize to max 512x512, preserve aspect ratio
+        .resize(FILE_UPLOAD_CONSTANTS.AVATAR_MAX_DIMENSION, FILE_UPLOAD_CONSTANTS.AVATAR_MAX_DIMENSION, {
+          fit: 'inside', // Preserve aspect ratio, fit within bounds
+          withoutEnlargement: true, // Don't upscale smaller images
+        })
+        // Convert to WebP with quality optimization
+        .webp({
+          quality: 85, // Balance between quality and file size
+          effort: 4, // Compression effort (0-6, higher = better compression but slower)
+        })
+        // Strip EXIF metadata for privacy
+        .withMetadata({
+          exif: {},
+          icc: undefined,
+        })
+        .toBuffer();
+
+      logger.info({
+        msg: 'Avatar optimization complete',
+        optimizedSize: optimized.length,
+        compressionRatio: `${((1 - optimized.length / buffer.length) * 100).toFixed(1)}%`,
+      });
+
+      return optimized;
+    } catch (error) {
+      // Handle Sharp-specific errors
+      if (error instanceof Error) {
+        if (error.message.includes('Input buffer contains unsupported image format')) {
+          throw new ValidationError('Image format is not supported', 'UNSUPPORTED_IMAGE_FORMAT');
+        }
+
+        if (error.message.includes('Input file is missing')) {
+          throw new ValidationError('Invalid image data', 'INVALID_IMAGE');
+        }
+      }
+
+      // Re-throw ValidationError as-is
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+
+      // Wrap unexpected errors
+      logger.error({ err: error, msg: 'Image optimization failed' });
+      throw new InternalError('Failed to optimize image', 'IMAGE_OPTIMIZATION_FAILED');
+    }
+  }
+
+  /**
+   * Validates that a buffer contains a valid image
+   *
+   * @param buffer - Buffer to validate
+   * @returns True if buffer is a valid image
+   * @throws ValidationError if buffer is invalid
+   *
+   * @example
+   * ```typescript
+   * await imageOptimizerService.validateImageBuffer(buffer);
+   * ```
+   */
+  async validateImageBuffer(buffer: Buffer): Promise<boolean> {
+    try {
+      const metadata = await sharp(buffer).metadata();
+
+      if (!metadata.format || !metadata.width || !metadata.height) {
+        throw new ValidationError('Buffer does not contain a valid image', 'INVALID_IMAGE');
+      }
+
+      // Check if format is supported
+      const supportedFormats = ['jpeg', 'png', 'webp', 'gif'];
+      if (!supportedFormats.includes(metadata.format)) {
+        throw new ValidationError(
+          `Image format '${metadata.format}' is not supported`,
+          'UNSUPPORTED_IMAGE_FORMAT'
+        );
+      }
+
+      return true;
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        throw error;
+      }
+
+      logger.error({ err: error, msg: 'Image validation failed' });
+      throw new ValidationError('Unable to validate image', 'INVALID_IMAGE');
+    }
+  }
+}
+
+// Export singleton instance
+export const imageOptimizerService = new ImageOptimizerService();