@underpostnet/underpost 2.97.1 → 2.97.5

package/src/api/file/file.service.js

@@ -1,10 +1,110 @@
+/**
+ * File service module for handling file uploads, retrieval, and deletion.
+ * Provides REST API handlers for file operations with MongoDB storage.
+ *
+ * @module src/api/file/file.service.js
+ * @namespace FileServiceServer
+ */
+
 import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { getBearerToken, jwtVerify } from '../../server/auth.js';
 import { loggerFactory } from '../../server/logger.js';
 import crypto from 'crypto';
+import { Types } from 'mongoose';
 
+/**
+ * Logger instance for this module.
+ * @type {Function}
+ * @memberof FileServiceServer
+ * @private
+ */
 const logger = loggerFactory(import.meta);
 
+/**
+ * File Data Transfer Object (DTO) for the service layer.
+ * Provides API-specific transformation methods for file documents including
+ * metadata selection queries and response formatting for REST endpoints.
+ * @namespace FileServiceServer.FileServiceDto
+ * @memberof FileServiceServer
+ */
+const FileServiceDto = {
+  /**
+   * Returns file metadata only (no buffer data).
+   * Used for list responses and API integration.
+   * @function toMetadata
+   * @memberof FileServiceServer.FileServiceDto
+   * @param {Object} file - File document from database.
+   * @returns {Object|null} File metadata object, or null if file is falsy.
+   */
+  toMetadata: (file) => {
+    if (!file) return null;
+    return {
+      _id: file._id,
+      name: file.name || '',
+      mimetype: file.mimetype || 'application/octet-stream',
+      size: file.size || 0,
+      md5: file.md5 || '',
+      cid: file.cid || '',
+      createdAt: file.createdAt,
+      updatedAt: file.updatedAt,
+    };
+  },
+
+  /**
+   * Transforms array of files to metadata only.
+   * @function toMetadataArray
+   * @memberof FileServiceServer.FileServiceDto
+   * @param {Array} files - Array of file documents.
+   * @returns {Array} Array of file metadata objects.
+   */
+  toMetadataArray: (files) => {
+    if (!Array.isArray(files)) return [];
+    return files.map((file) => FileServiceDto.toMetadata(file));
+  },
+
+  /**
+   * Ensures UTF-8 encoding for filenames.
+   * Fixes issues with special characters (e.g., ñ, é, ü).
+   * @function normalizeFilename
+   * @memberof FileServiceServer.FileServiceDto
+   * @param {string} filename - Raw filename from upload.
+   * @returns {string} UTF-8 encoded filename.
+   */
+  normalizeFilename: (filename) => {
+    if (!filename) return '';
+    // Ensure string and normalize to UTF-8
+    let normalized = String(filename);
+    // Replace any incorrectly encoded sequences
+    normalized = Buffer.from(normalized, 'utf8').toString('utf8');
+    return normalized;
+  },
+
+  /**
+   * Get select fields for metadata-only queries.
+   * Excludes the 'data' buffer field.
+   * @function metadataSelect
+   * @memberof FileServiceServer.FileServiceDto
+   * @returns {string} Space-separated list of field names for metadata selection.
+   */
+  metadataSelect: () => {
+    return '_id name mimetype size encoding md5 cid createdAt updatedAt';
+  },
+};
+
+/**
+ * File Factory for file extraction, upload, and creation utilities.
+ * @namespace FileServiceServer.FileFactory
+ * @memberof FileServiceServer
+ */
 const FileFactory = {
+  /**
+   * Extract files from request.
+   * Handles both standard 'file' field and custom fields.
+   * @function filesExtract
+   * @memberof FileServiceServer.FileFactory
+   * @param {Object} req - Express request object with files.
+   * @returns {Array} Array of extracted file objects.
+   */
   filesExtract: (req) => {
     const files = [];
     if (!req.files || Object.keys(req.files).length === 0) {
@@ -13,7 +113,9 @@ const FileFactory = {
 
     // Handle standard 'file' field
     if (Array.isArray(req.files.file)) {
-      for (const file of req.files.file) files.push(file);
+      for (const file of req.files.file) {
+        files.push(file);
+      }
     } else if (req.files.file) {
       files.push(req.files.file);
     }
@@ -38,89 +140,335 @@ const FileFactory = {
 
     return files;
   },
+
+  /**
+   * Upload files to database with UTF-8 encoding.
+   * @async
+   * @function upload
+   * @memberof FileServiceServer.FileFactory
+   * @param {Object} req - Express request object with files.
+   * @param {import('mongoose').Model} File - Mongoose File model.
+   * @returns {Promise<Array>} Array of uploaded file metadata objects.
+   */
   upload: async function (req, File) {
     const results = FileFactory.filesExtract(req);
     let index = -1;
+
     for (let file of results) {
+      // Normalize filename to ensure UTF-8 encoding
+      file.name = FileServiceDto.normalizeFilename(file.name);
+      file.encoding = 'utf-8';
+
+      // Save file to database
       file = await new File(file).save();
       index++;
+
+      // Retrieve metadata-only response
       const [result] = await File.find({
         _id: file._id,
-      }).select({ _id: 1, name: 1, mimetype: 1 });
+      }).select(FileServiceDto.metadataSelect());
+
       results[index] = result;
     }
+
     return results;
   },
+
+  /**
+   * Convert string to hexadecimal.
+   * @function hex
+   * @memberof FileServiceServer.FileFactory
+   * @param {string} [raw=''] - Raw string to convert.
+   * @returns {string} Hexadecimal representation of the string.
+   */
   hex: (raw = '') => {
     return Buffer.from(raw, 'utf8').toString('hex');
-    // reverse hexValue.toString()
   },
+
+  /**
+   * Get MIME type from file path based on extension.
+   * @function getMymeTypeFromPath
+   * @memberof FileServiceServer.FileFactory
+   * @param {string} path - File path or filename with extension.
+   * @returns {string} MIME type string.
+   */
   getMymeTypeFromPath: (path) => {
-    switch (path.split('.').pop()) {
-      case 'png':
-        return 'image/png';
-      case 'jpg':
-        return 'image/jpeg';
-      case 'jpeg':
-        return 'image/jpeg';
-      case 'gif':
-        return 'image/gif';
-      case 'svg':
-        return 'image/svg+xml';
-      default:
-        return 'application/octet-stream';
-    }
+    const ext = String(path || '')
+      .toLowerCase()
+      .split('.')
+      .pop();
+    const mimeTypes = {
+      png: 'image/png',
+      jpg: 'image/jpeg',
+      jpeg: 'image/jpeg',
+      gif: 'image/gif',
+      svg: 'image/svg+xml',
+      webp: 'image/webp',
+      pdf: 'application/pdf',
+      md: 'text/markdown',
+      txt: 'text/plain',
+      json: 'application/json',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
   },
+
+  /**
+   * Create file object with proper encoding.
+   * @function create
+   * @memberof FileServiceServer.FileFactory
+   * @param {Buffer} [data=Buffer.from([])] - File data buffer.
+   * @param {string} [name=''] - File name.
+   * @returns {Object} File object with name, data, size, encoding, mimetype, and md5.
+   */
   create: (data = Buffer.from([]), name = '') => {
+    const normalizedName = FileServiceDto.normalizeFilename(name);
+
     return {
-      name: name,
+      name: normalizedName,
       data: data,
       size: data.length,
-      encoding: '7bit',
+      encoding: 'utf-8',
       tempFilePath: '',
       truncated: false,
-      mimetype: FileFactory.getMymeTypeFromPath(name),
+      mimetype: FileFactory.getMymeTypeFromPath(normalizedName),
       md5: crypto.createHash('md5').update(data).digest('hex'),
       cid: undefined,
     };
   },
 };
 
+/**
+ * File cleanup utilities for preventing orphaned files.
+ * These utilities help maintain database integrity by automatically removing
+ * orphaned file records when references are changed or deleted in documents.
+ * @namespace FileServiceServer.FileCleanup
+ * @memberof FileServiceServer
+ */
+const FileCleanup = {
+  /**
+   * Clean up old file references when document fields are updated.
+   * Deletes old files that are being replaced by new file IDs.
+   * @async
+   * @function cleanupReplacedFiles
+   * @memberof FileServiceServer.FileCleanup
+   * @param {Object} options - Cleanup options.
+   * @param {Object} options.oldDoc - Original document with old file references.
+   * @param {Object} options.newData - New data containing updated file references.
+   * @param {Array<string>} options.fileFields - Array of field names that contain file IDs (e.g., ['fileId', 'mdFileId']).
+   * @param {import('mongoose').Model} options.File - Mongoose File model.
+   * @returns {Promise<Array>} Array of deleted file IDs.
+   */
+  cleanupReplacedFiles: async ({ oldDoc, newData, fileFields, File }) => {
+    const deletedFileIds = [];
+
+    for (const field of fileFields) {
+      const oldFileId = oldDoc[field];
+      const newFileId = newData[field];
+
+      // If field has old file and new data changes or removes it
+      if (oldFileId && newFileId !== undefined && String(oldFileId) !== String(newFileId)) {
+        try {
+          const file = await File.findOne({ _id: oldFileId });
+          if (file) {
+            await File.findByIdAndDelete(oldFileId);
+            deletedFileIds.push(oldFileId);
+            logger.info(`Cleaned up orphaned file: ${oldFileId} from field: ${field}`);
+          }
+        } catch (err) {
+          logger.error(`Failed to cleanup file ${oldFileId} from field ${field}:`, err);
+        }
+      }
+    }
+
+    return deletedFileIds;
+  },
+
+  /**
+   * Delete all files referenced in a document.
+   * Used when deleting an entire document.
+   * This method removes all files associated with the document before
+   * the document itself is deleted, preventing orphaned file records.
+   * @async
+   * @function deleteDocumentFiles
+   * @memberof FileServiceServer.FileCleanup
+   * @param {Object} options - Deletion options.
+   * @param {Object} options.doc - Document containing file references.
+   * @param {Array<string>} options.fileFields - Array of field names that contain file IDs.
+   * @param {import('mongoose').Model} options.File - Mongoose File model.
+   * @returns {Promise<Array>} Array of deleted file IDs.
+   */
+  deleteDocumentFiles: async ({ doc, fileFields, File }) => {
+    const deletedFileIds = [];
+
+    for (const field of fileFields) {
+      const fileId = doc[field];
+
+      if (fileId) {
+        try {
+          const file = await File.findOne({ _id: fileId });
+          if (file) {
+            await File.findByIdAndDelete(fileId);
+            deletedFileIds.push(fileId);
+            logger.info(`Deleted file: ${fileId} from field: ${field}`);
+          }
+        } catch (err) {
+          logger.error(`Failed to delete file ${fileId} from field ${field}:`, err);
+        }
+      }
+    }
+
+    return deletedFileIds;
+  },
+};
+
+/**
+ * File Service for handling REST API file operations.
+ * @namespace FileServiceServer.FileService
+ * @memberof FileServiceServer
+ */
 const FileService = {
+  /**
+   * POST - Upload files.
+   * Returns metadata-only response (no buffer data).
+   * @async
+   * @function post
+   * @memberof FileServiceServer.FileService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Array>} Array of uploaded file metadata objects.
+   */
   post: async (req, res, options) => {
+    // Check that user is authenticated and not a guest
+    if (!req.auth || !req.auth.user || req.auth.user.role === 'guest') {
+      throw new Error('Authentication required. Guest users cannot upload files.');
+    }
+
     /** @type {import('./file.model.js').FileModel} */
     const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
-    return await FileFactory.upload(req, File);
+
+    const uploadedFiles = await FileFactory.upload(req, File);
+    return FileServiceDto.toMetadataArray(uploadedFiles);
   },
+
+  /**
+   * GET - Retrieve files.
+   * Returns metadata-only for regular GET.
+   * Returns buffer data for /blob endpoint.
+   * Authorization: Check if file belongs to a public document or user owns the document.
+   * @async
+   * @function get
+   * @memberof FileServiceServer.FileService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Array|Buffer>} Array of file metadata objects or Buffer for blob endpoint.
+   * @throws {Error} If file not found or user not authorized.
+   */
   get: async (req, res, options) => {
     /** @type {import('./file.model.js').FileModel} */
     const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
+    /** @type {import('../document/document.model.js').DocumentModel} */
+    const Document = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Document;
+    /** @type {import('../user/user.model.js').User} */
+    const User = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.User;
+
+    const isFileAuthorized = async (fileId) => {
+      try {
+        // Find document that references this file
+        const doc = await Document.findOne({
+          $or: [{ fileId: new Types.ObjectId(fileId) }, { mdFileId: new Types.ObjectId(fileId) }],
+        });
 
+        // If file not in any document, allow access
+        if (!doc) return true;
+
+        // If document has 'public' tag, allow all access
+        if (doc.isPublic) return true;
+
+        // Otherwise, user must be authenticated and own the document
+        const token = getBearerToken(req);
+        if (!token) false;
+        const payload = jwtVerify(token, options);
+        const user = await User.findOne({ _id: payload._id }).lean();
+        if (!user) return false;
+        return String(doc.userId) === String(user._id);
+      } catch (err) {
+        console.log(err);
+        logger.error('Authorization check failed:', err);
+        return false;
+      }
+    };
+
+    // Handle blob endpoint - return raw buffer data
     if (req.path.startsWith('/blob') && req.params.id) {
+      // Check authorization
+      const authorized = await isFileAuthorized(req.params.id);
+      if (!authorized) {
+        throw new Error('Unauthorized');
+      }
+
       const file = await File.findOne({ _id: req.params.id });
-      res.set('Content-Type', file.mimetype);
-      return Buffer.from(file.data, 'base64');
+
+      if (!file) {
+        throw new Error('File not found');
+      }
+
+      // Set proper content type and return buffer
+      res.set('Content-Type', file.mimetype || 'application/octet-stream');
+      res.set('Content-Length', file.size || 0);
+      res.set('Content-Disposition', `inline; filename="${encodeURIComponent(file.name)}"`);
+
+      // Return Buffer directly (not JSON)
+      return Buffer.from(file.data);
     }
 
+    // Handle regular GET - return metadata only
     switch (req.params.id) {
-      case 'all':
-        return await File.find();
+      case 'all': {
+        const files = await File.find().select(FileServiceDto.metadataSelect());
+        return FileServiceDto.toMetadataArray(files);
+      }
 
-      default:
-        return await File.find({
+      default: {
+        // Check authorization
+        const authorized = await isFileAuthorized(req.params.id);
+        if (!authorized) {
+          throw new Error('Unauthorized');
+        }
+
+        const files = await File.find({
           _id: req.params.id,
-        });
+        }).select(FileServiceDto.metadataSelect());
+
+        return FileServiceDto.toMetadataArray(files);
+      }
     }
   },
+
+  /**
+   * DELETE - Remove files.
+   * @async
+   * @function delete
+   * @memberof FileServiceServer.FileService
+   * @param {Object} req - Express request object.
+   * @param {Object} res - Express response object.
+   * @param {Object} options - Request options containing host and path.
+   * @returns {Promise<Object>} Deleted file metadata object.
+   * @throws {Error} If file not found.
+   */
   delete: async (req, res, options) => {
     /** @type {import('./file.model.js').FileModel} */
     const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
 
-    switch (req.params.id) {
-      default:
-        return await File.findByIdAndDelete(req.params.id);
+    const result = await File.findByIdAndDelete(req.params.id);
+
+    if (!result) {
+      throw new Error('File not found');
     }
+
+    return FileServiceDto.toMetadata(result);
   },
 };
 
-export { FileService, FileFactory };
+export { FileService, FileFactory, FileServiceDto, FileCleanup };

package/src/api/user/user.model.js

@@ -20,7 +20,28 @@ const UserSchema = new Schema(
     lastLoginDate: { type: Date },
     failedLoginAttempts: { type: Number, default: 0 },
     password: { type: String, trim: true, required: 'Password is required' },
-    username: { type: String, trim: true, unique: true, required: 'Username is required' },
+    username: {
+      type: String,
+      trim: true,
+      unique: true,
+      required: 'Username is required',
+      validate: [
+        {
+          validator: function (username) {
+            // Allow only alphanumeric characters, hyphens, and underscores (URI-safe)
+            return /^[a-zA-Z0-9_-]+$/.test(username);
+          },
+          message: 'Username can only contain letters, numbers, hyphens, and underscores',
+        },
+        {
+          validator: function (username) {
+            // Length validation
+            return username && username.length >= 2 && username.length <= 20;
+          },
+          message: 'Username must be between 2 and 20 characters',
+        },
+      ],
+    },
     role: { type: String, enum: userRoleEnum, default: 'guest' },
     activeSessions: {
       type: [
@@ -60,6 +81,8 @@ const UserSchema = new Schema(
         context: [{ type: String, enum: ['client', 'supplier', 'employee', 'owner'] }],
       },
     ],
+    publicProfile: { type: Boolean, default: false },
+    briefDescription: { type: String, default: 'Uploader' },
   },
   {
     timestamps: true,
@@ -80,6 +103,8 @@ const UserDto = {
         role: 1,
         emailConfirmed: 1,
         profileImageId: 1,
+        publicProfile: 1,
+        briefDescription: 1,
         createdAt: 1,
         updatedAt: 1,
       };
@@ -88,6 +113,18 @@ const UserDto = {
       return { _id: 1 };
     },
   },
+  public: {
+    get: () => {
+      return {
+        _id: 1,
+        username: 1,
+        profileImageId: 1,
+        publicProfile: 1,
+        briefDescription: 1,
+        createdAt: 1,
+      };
+    },
+  },
   auth: {
     payload: (user, jwtid, ip, userAgent, host, path) => {
       const tokenPayload = {