Merge pull request #517 from Hexastack/refactor/avatar-upload

Refactor Subscriber/User Avatar Upload/Download

api/src/attachment/attachment.module.ts

@@ -1,15 +1,19 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
-import { Module } from '@nestjs/common';
+import { existsSync, mkdirSync } from 'fs';
+
+import { Module, OnApplicationBootstrap } from '@nestjs/common';
 import { MongooseModule } from '@nestjs/mongoose';
 import { PassportModule } from '@nestjs/passport';
 
+import { config } from '@/config';
+
 import { AttachmentController } from './controllers/attachment.controller';
 import { AttachmentRepository } from './repositories/attachment.repository';
 import { AttachmentModel } from './schemas/attachment.schema';
@@ -26,4 +30,14 @@ import { AttachmentService } from './services/attachment.service';
   controllers: [AttachmentController],
   exports: [AttachmentService],
 })
-export class AttachmentModule {}
+export class AttachmentModule implements OnApplicationBootstrap {
+  onApplicationBootstrap() {
+    // Ensure the directories exists
+    if (!existsSync(config.parameters.uploadDir)) {
+      mkdirSync(config.parameters.uploadDir, { recursive: true });
+    }
+    if (!existsSync(config.parameters.avatarDir)) {
+      mkdirSync(config.parameters.avatarDir, { recursive: true });
+    }
+  }
+}

api/src/attachment/services/attachment.service.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -7,7 +7,7 @@
  */
 
 import fs, { createReadStream, promises as fsPromises } from 'fs';
-import path, { join } from 'path';
+import { join, resolve } from 'path';
 import { Readable } from 'stream';
 
 import {
@@ -73,6 +73,7 @@ export class AttachmentService extends BaseService<Attachment> {
   /**
    * Downloads a user's profile picture either from a 3rd party storage system or from a local directory based on configuration.
    *
+   * @deprecated Use AttachmentService.download() instead
    * @param foreign_id The unique identifier of the user, used to locate the profile picture.
    * @returns A `StreamableFile` containing the user's profile picture.
    */
@@ -87,7 +88,9 @@ export class AttachmentService extends BaseService<Attachment> {
         throw new NotFoundException('Profile picture not found');
       }
     } else {
-      const path = join(config.parameters.avatarDir, `${foreign_id}.jpeg`);
+      const path = resolve(
+        join(config.parameters.avatarDir, `${foreign_id}.jpeg`),
+      );
       if (fs.existsSync(path)) {
         const picturetream = createReadStream(path);
         return new StreamableFile(picturetream);
@@ -100,6 +103,7 @@ export class AttachmentService extends BaseService<Attachment> {
   /**
    * Uploads a profile picture to either 3rd party storage system or locally based on the configuration.
    *
+   * @deprecated use store() method instead
    * @param res - The response object from which the profile picture will be buffered or piped.
    * @param filename - The filename
    */
@@ -127,14 +131,9 @@ export class AttachmentService extends BaseService<Attachment> {
       }
     } else {
       // Save profile picture locally
-      const dirPath = path.join(config.parameters.avatarDir, filename);
+      const dirPath = resolve(join(config.parameters.avatarDir, filename));
 
       try {
-        // Ensure the directory exists
-        await fs.promises.mkdir(config.parameters.avatarDir, {
-          recursive: true,
-        });
-
         if (Buffer.isBuffer(data)) {
           await fs.promises.writeFile(dirPath, data);
         } else {
@@ -157,6 +156,7 @@ export class AttachmentService extends BaseService<Attachment> {
    * Uploads files to the server. If a storage plugin is configured it uploads files accordingly.
    * Otherwise, uploads files to the local directory.
    *
+   * @deprecated use store() instead
    * @param files - An array of files to upload.
    * @returns A promise that resolves to an array of uploaded attachments.
    */
@@ -192,23 +192,25 @@ export class AttachmentService extends BaseService<Attachment> {
    * Otherwise, uploads files to the local directory.
    *
    * @param file - The file
+   * @param metadata - The attachment metadata informations.
+   * @param rootDir - The root directory where attachment shoud be located.
    * @returns A promise that resolves to an array of uploaded attachments.
    */
   async store(
     file: Buffer | Readable | Express.Multer.File,
     metadata: AttachmentMetadataDto,
+    rootDir = config.parameters.uploadDir,
   ): Promise<Attachment> {
     if (this.getStoragePlugin()) {
-      const storedDto = await this.getStoragePlugin().store(file, metadata);
+      const storedDto = await this.getStoragePlugin().store(
+        file,
+        metadata,
+        rootDir,
+      );
       return await this.create(storedDto);
     } else {
-      const dirPath = path.join(config.parameters.uploadDir);
       const uniqueFilename = generateUniqueFilename(metadata.name);
-      const filePath = path.resolve(dirPath, sanitizeFilename(uniqueFilename));
-
-      if (!filePath.startsWith(dirPath)) {
-        throw new Error('Invalid file path');
-      }
+      const filePath = resolve(join(rootDir, sanitizeFilename(uniqueFilename)));
 
       if (Buffer.isBuffer(file)) {
         await fsPromises.writeFile(filePath, file);
@@ -222,7 +224,7 @@ export class AttachmentService extends BaseService<Attachment> {
       } else {
         if (file.path) {
           // For example, if the file is an instance of `Express.Multer.File` (diskStorage case)
-          const srcFilePath = path.resolve(file.path);
+          const srcFilePath = resolve(file.path);
           await fsPromises.copyFile(srcFilePath, filePath);
           await fsPromises.unlink(srcFilePath);
         } else {
@@ -230,7 +232,7 @@ export class AttachmentService extends BaseService<Attachment> {
         }
       }
 
-      const location = filePath.replace(dirPath, '');
+      const location = filePath.replace(rootDir, '');
       return await this.create({
         ...metadata,
         location,
@@ -241,19 +243,23 @@ export class AttachmentService extends BaseService<Attachment> {
   /**
    * Downloads an attachment identified by the provided parameters.
    *
-   * @param  attachment - The attachment to download.
+   * @param attachment - The attachment to download.
+   * @param rootDir - The root directory where attachment shoud be located.
    * @returns A promise that resolves to a StreamableFile representing the downloaded attachment.
    */
-  async download(attachment: Attachment) {
+  async download(
+    attachment: Attachment,
+    rootDir = config.parameters.uploadDir,
+  ) {
     if (this.getStoragePlugin()) {
       return await this.getStoragePlugin().download(attachment);
     } else {
-      if (!fileExists(attachment.location)) {
+      const path = resolve(join(rootDir, attachment.location));
+
+      if (!fileExists(path)) {
         throw new NotFoundException('No file was found');
       }
 
-      const path = join(config.parameters.uploadDir, attachment.location);
-
       const disposition = `attachment; filename="${encodeURIComponent(
         attachment.name,
       )}"`;
@@ -272,18 +278,24 @@ export class AttachmentService extends BaseService<Attachment> {
   /**
    * Downloads an attachment identified by the provided parameters as a Buffer.
    *
-   * @param  attachment - The attachment to download.
+   * @param attachment - The attachment to download.
+   * @param rootDir - Root folder path where the attachment should be located.
    * @returns A promise that resolves to a Buffer representing the downloaded attachment.
    */
-  async readAsBuffer(attachment: Attachment): Promise<Buffer> {
+  async readAsBuffer(
+    attachment: Attachment,
+    rootDir = config.parameters.uploadDir,
+  ): Promise<Buffer> {
     if (this.getStoragePlugin()) {
       return await this.getStoragePlugin().readAsBuffer(attachment);
     } else {
-      if (!fileExists(attachment.location)) {
+      const path = resolve(join(rootDir, attachment.location));
+
+      if (!fileExists(path)) {
         throw new NotFoundException('No file was found');
       }
-      const filePath = join(config.parameters.uploadDir, attachment.location);
-      return await fs.promises.readFile(filePath); // Reads the file content as a Buffer
+
+      return await fs.promises.readFile(path); // Reads the file content as a Buffer
     }
   }
 }

api/src/attachment/utilities/index.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -7,7 +7,7 @@
  */
 
 import { createReadStream, existsSync } from 'fs';
-import { extname, join } from 'path';
+import { extname } from 'path';
 
 import { Logger, StreamableFile } from '@nestjs/common';
 import { StreamableFileOptions } from '@nestjs/common/file-stream/interfaces/streamable-options.interface';
@@ -29,20 +29,18 @@ export const isMime = (type: string): boolean => {
 
 /**
  * Checks if a file exists in the specified upload directory.
- * @param location The relative location of the file.
- * @returns Whether the file exists.
+ * @param filePath The relative location of the file.
+ * @returns True if the file exists.
  */
-export const fileExists = (location: string): boolean => {
+export const fileExists = (filePath: string): boolean => {
   // bypass test env
   if (config.env === 'test') {
     return true;
   }
   try {
-    const dirPath = config.parameters.uploadDir;
-    const fileLocation = join(dirPath, location);
-    return existsSync(fileLocation);
+    return existsSync(filePath);
   } catch (e) {
-    new Logger(`Attachment Model : Unable to locate file: ${location}`);
+    new Logger(`Attachment Model : Unable to locate file: ${filePath}`);
     return false;
   }
 };

api/src/chat/controllers/subscriber.controller.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -19,9 +19,10 @@ import {
 } from '@nestjs/common';
 import { CsrfCheck } from '@tekuconcept/nestjs-csrf';
 
+import { AttachmentService } from '@/attachment/services/attachment.service';
+import { config } from '@/config';
 import { CsrfInterceptor } from '@/interceptors/csrf.interceptor';
 import { LoggerService } from '@/logger/logger.service';
-import { Roles } from '@/utils/decorators/roles.decorator';
 import { BaseController } from '@/utils/generics/base-controller';
 import { generateInitialsAvatar } from '@/utils/helpers/avatar';
 import { PageQueryDto } from '@/utils/pagination/pagination-query.dto';
@@ -49,11 +50,21 @@ export class SubscriberController extends BaseController<
 > {
   constructor(
     private readonly subscriberService: SubscriberService,
+    private readonly attachmentService: AttachmentService,
     private readonly logger: LoggerService,
   ) {
     super(subscriberService);
   }
 
+  /**
+   * Retrieves a paginated list of subscribers based on provided query parameters.
+   * Supports filtering, pagination, and population of related fields.
+   *
+   * @param pageQuery - The pagination and sorting options.
+   * @param populate - List of fields to populate in the response.
+   * @param filters - Search filters to apply on the Subscriber model.
+   * @returns A promise containing the paginated and optionally populated list of subscribers.
+   */
   @Get()
   async findPage(
     @Query(PageQueryPipe) pageQuery: PageQueryDto<Subscriber>,
@@ -79,8 +90,10 @@ export class SubscriberController extends BaseController<
   }
 
   /**
-   * Counts the filtered number of subscribers.
-   * @returns A promise that resolves to an object representing the filtered number of subscribers.
+   * Retrieves the count of subscribers that match the provided search filters.
+   *
+   * @param filters - Optional search filters to apply on the Subscriber model.
+   * @returns A promise containing the count of subscribers matching the filters.
    */
   @Get('count')
   async filterCount(
@@ -100,6 +113,14 @@ export class SubscriberController extends BaseController<
     return await this.count(filters);
   }
 
+  /**
+   * Retrieves a single subscriber by their unique ID.
+   * Supports optional population of related fields.
+   *
+   * @param id - The unique identifier of the subscriber to retrieve.
+   * @param populate - An optional list of related fields to populate in the response.
+   * @returns The subscriber document, populated if requested.
+   */
   @Get(':id')
   async findOne(
     @Param('id') id: string,
@@ -116,23 +137,36 @@ export class SubscriberController extends BaseController<
     return doc;
   }
 
-  @Roles('public')
-  @Get(':foreign_id/profile_pic')
-  async findProfilePic(
-    @Param('foreign_id') foreign_id: string,
-  ): Promise<StreamableFile> {
+  /**
+   * Retrieves the profile picture (avatar) of a subscriber by their unique ID.
+   * If no avatar is set, generates an initials-based avatar.
+   *
+   * @param id - The unique identifier of the subscriber whose profile picture is to be retrieved.
+   * @returns A streamable file containing the avatar image.
+   */
+  @Get(':id/profile_pic')
+  async getAvatar(@Param('id') id: string): Promise<StreamableFile> {
+    const subscriber = await this.subscriberService.findOneAndPopulate(id);
+
+    if (!subscriber) {
+      throw new NotFoundException(`Subscriber with ID ${id} not found`);
+    }
+
     try {
-      const pic = await this.subscriberService.findProfilePic(foreign_id);
-      return pic;
-    } catch (e) {
-      const [subscriber] = await this.subscriberService.find({ foreign_id });
-      if (subscriber) {
-        return generateInitialsAvatar(subscriber);
-      } else {
-        throw new NotFoundException(
-          `Subscriber with ID ${foreign_id} not found`,
-        );
+      if (!subscriber.avatar) {
+        throw new Error('User has no avatar');
       }
+
+      return await this.attachmentService.download(
+        subscriber.avatar,
+        config.parameters.avatarDir,
+      );
+    } catch (err) {
+      this.logger.verbose(
+        'Subscriber has no avatar, generating initials avatar ...',
+        err,
+      );
+      return await generateInitialsAvatar(subscriber);
     }
   }
 

api/src/chat/services/subscriber.service.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -9,9 +9,7 @@
 import {
   Injectable,
   InternalServerErrorException,
-  NotFoundException,
   Optional,
-  StreamableFile,
 } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 
@@ -139,22 +137,6 @@ export class SubscriberService extends BaseService<
     return await this.repository.handOverByForeignIdQuery(foreignId, userId);
   }
 
-  /**
-   * Retrieves the profile picture of a subscriber based on the foreign ID.
-   *
-   * @param foreign_id - The foreign ID of the subscriber.
-   *
-   * @returns A streamable file representing the profile picture.
-   */
-  async findProfilePic(foreign_id: string): Promise<StreamableFile> {
-    try {
-      return await this.attachmentService.downloadProfilePic(foreign_id);
-    } catch (err) {
-      this.logger.error('Error downloading profile picture', err);
-      throw new NotFoundException('Profile picture not found');
-    }
-  }
-
   /**
    * Apply updates on end-user such as :
    * - Assign labels to specific end-user

api/src/config/index.ts

@@ -105,12 +105,12 @@ export const config: Config = {
     from: process.env.EMAIL_SMTP_FROM || 'noreply@example.com',
   },
   parameters: {
-    uploadDir: process.env.UPLOAD_DIR
-      ? join(process.cwd(), process.env.UPLOAD_DIR)
-      : join(process.cwd(), 'uploads'),
-    avatarDir: process.env.AVATAR_DIR
-      ? join(process.cwd(), process.env.AVATAR_DIR)
-      : join(process.cwd(), 'avatars'),
+    uploadDir: join(process.cwd(), process.env.UPLOAD_DIR || '/uploads'),
+    avatarDir: join(
+      process.cwd(),
+      process.env.UPLOAD_DIR || '/uploads',
+      '/avatars',
+    ),
     storageMode: 'disk',
     maxUploadSize: process.env.UPLOAD_MAX_SIZE_IN_BYTES
       ? Number(process.env.UPLOAD_MAX_SIZE_IN_BYTES)

api/src/migration/migration.service.ts

@@ -53,7 +53,7 @@ export class MigrationService implements OnApplicationBootstrap {
     if (mongoose.connection.readyState !== 1) {
       await this.connect();
     }
-    this.logger.log('Mongoose connection established');
+    this.logger.log('Mongoose connection established!');
 
     if (!this.isCLI && config.mongo.autoMigrate) {
       this.logger.log('Executing migrations ...');

api/src/migration/migrations/1735836154221-v-2-2-0.migration.ts

@@ -0,0 +1,274 @@
+/*
+ * Copyright © 2025 Hexastack. All rights reserved.
+ *
+ * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
+ * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
+ * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
+ */
+
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+
+import mongoose from 'mongoose';
+
+import attachmentSchema, {
+  Attachment,
+} from '@/attachment/schemas/attachment.schema';
+import subscriberSchema, { Subscriber } from '@/chat/schemas/subscriber.schema';
+import { config } from '@/config';
+import userSchema, { User } from '@/user/schemas/user.schema';
+import { moveFile, moveFiles } from '@/utils/helpers/fs';
+
+import { MigrationServices } from '../types';
+
+/**
+ * Updates subscriber documents with their corresponding avatar attachments
+ * and moves avatar files to a new directory.
+ *
+ * @returns Resolves when the migration process is complete.
+ */
+const populateSubscriberAvatar = async ({ logger }: MigrationServices) => {
+  const AttachmentModel = mongoose.model<Attachment>(
+    Attachment.name,
+    attachmentSchema,
+  );
+  const SubscriberModel = mongoose.model<Subscriber>(
+    Subscriber.name,
+    subscriberSchema,
+  );
+
+  const cursor = SubscriberModel.find().cursor();
+
+  for await (const subscriber of cursor) {
+    const foreignId = subscriber.foreign_id;
+    if (!foreignId) {
+      logger.debug(`No foreign id found for subscriber ${subscriber._id}`);
+      continue;
+    }
+
+    const attachment = await AttachmentModel.findOne({
+      name: RegExp(`^${foreignId}.jpe?g$`),
+    });
+
+    if (attachment) {
+      await SubscriberModel.updateOne(
+        { _id: subscriber._id },
+        { $set: { avatar: attachment._id } },
+      );
+      logger.log(
+        `Subscriber ${subscriber._id} avatar attachment successfully updated for  `,
+      );
+
+      const src = resolve(
+        join(config.parameters.uploadDir, attachment.location),
+      );
+      if (existsSync(src)) {
+        try {
+          const dst = resolve(
+            join(config.parameters.avatarDir, attachment.location),
+          );
+          await moveFile(src, dst);
+          logger.log(
+            `Subscriber ${subscriber._id} avatar file successfully moved to the new "avatars" folder`,
+          );
+        } catch (err) {
+          logger.error(err);
+          logger.warn(`Unable to move subscriber ${subscriber._id} avatar!`);
+        }
+      } else {
+        logger.warn(
+          `Subscriber ${subscriber._id} avatar attachment file was not found!`,
+        );
+      }
+    } else {
+      logger.warn(
+        `No avatar attachment found for subscriber ${subscriber._id}`,
+      );
+    }
+  }
+};
+
+/**
+ * Reverts what the previous function does
+ *
+ * @returns Resolves when the migration process is complete.
+ */
+const unpopulateSubscriberAvatar = async ({ logger }: MigrationServices) => {
+  const AttachmentModel = mongoose.model<Attachment>(
+    Attachment.name,
+    attachmentSchema,
+  );
+  const SubscriberModel = mongoose.model<Subscriber>(
+    Subscriber.name,
+    subscriberSchema,
+  );
+
+  // Rollback logic: unset the "avatar" field in all subscriber documents
+  const cursor = SubscriberModel.find({ avatar: { $exists: true } }).cursor();
+
+  for await (const subscriber of cursor) {
+    if (subscriber.avatar) {
+      const attachment = await AttachmentModel.findOne({
+        _id: subscriber.avatar,
+      });
+
+      if (attachment) {
+        // Move file to the old folder
+        const src = resolve(
+          join(config.parameters.avatarDir, attachment.location),
+        );
+        if (existsSync(src)) {
+          try {
+            const dst = resolve(
+              join(config.parameters.uploadDir, attachment.location),
+            );
+            await moveFile(src, dst);
+            logger.log(
+              `Avatar attachment successfully moved back to the old "avatars" folder`,
+            );
+          } catch (err) {
+            logger.error(err);
+            logger.warn(
+              `Unable to move back subscriber ${subscriber._id} avatar to the old folder!`,
+            );
+          }
+        } else {
+          logger.warn('Avatar attachment file was not found!');
+        }
+
+        // Reset avatar to null
+        await SubscriberModel.updateOne(
+          { _id: subscriber._id },
+          { $set: { avatar: null } },
+        );
+        logger.log(
+          `Avatar attachment successfully updated for subscriber ${subscriber._id}`,
+        );
+      } else {
+        logger.warn(
+          `No avatar attachment found for subscriber ${subscriber._id}`,
+        );
+      }
+    }
+  }
+};
+
+/**
+ * Migrates and updates the paths of old folder "avatars" files for subscribers and users.
+ *
+ * @returns Resolves when the migration process is complete.
+ */
+const updateOldAvatarsPath = async ({ logger }: MigrationServices) => {
+  // Make sure the old folder is moved
+  const oldPath = join(process.cwd(), process.env.AVATAR_DIR || '/avatars');
+  if (existsSync(oldPath)) {
+    logger.verbose(
+      `Moving subscriber avatar files from ${oldPath} to ${config.parameters.avatarDir} ...`,
+    );
+    try {
+      await moveFiles(oldPath, config.parameters.avatarDir);
+      logger.log('Avatars folder successfully moved to its new location ...');
+    } catch (err) {
+      logger.error(err);
+      logger.error('Unable to move files from the old "avatars" folder');
+    }
+  } else {
+    logger.log(`No old avatars folder found: ${oldPath}`);
+  }
+
+  // Move users avatars to the "uploads/avatars" folder
+  const AttachmentModel = mongoose.model<Attachment>(
+    Attachment.name,
+    attachmentSchema,
+  );
+  const UserModel = mongoose.model<User>(User.name, userSchema);
+
+  const cursor = UserModel.find().cursor();
+
+  for await (const user of cursor) {
+    try {
+      if (user.avatar) {
+        const avatar = await AttachmentModel.findOne({ _id: user.avatar });
+        if (avatar) {
+          const src = resolve(
+            join(config.parameters.uploadDir, avatar.location),
+          );
+          const dst = resolve(
+            join(config.parameters.avatarDir, avatar.location),
+          );
+          logger.verbose(`Moving user avatar file from ${src} to ${dst} ...`);
+          await moveFile(src, dst);
+        }
+      }
+    } catch (err) {
+      logger.error(err);
+      logger.error('Unable to move user avatar to the new folder');
+    }
+  }
+};
+
+/**
+ * Reverts what the previous function does
+ *
+ * @returns Resolves when the migration process is complete.
+ */
+const restoreOldAvatarsPath = async ({ logger }: MigrationServices) => {
+  // Move users avatars to the "/app/avatars" folder
+  const AttachmentModel = mongoose.model<Attachment>(
+    Attachment.name,
+    attachmentSchema,
+  );
+  const UserModel = mongoose.model<User>(User.name, userSchema);
+
+  const cursor = UserModel.find().cursor();
+
+  for await (const user of cursor) {
+    try {
+      if (user.avatar) {
+        const avatar = await AttachmentModel.findOne({ _id: user.avatar });
+        if (avatar) {
+          const src = resolve(
+            join(config.parameters.avatarDir, avatar.location),
+          );
+          const dst = resolve(
+            join(config.parameters.uploadDir, avatar.location),
+          );
+          logger.verbose(`Moving user avatar file from ${src} to ${dst} ...`);
+          await moveFile(src, dst);
+        }
+      }
+    } catch (err) {
+      logger.error(err);
+      logger.error('Unable to move user avatar to the new folder');
+    }
+  }
+
+  //
+  const oldPath = resolve(
+    join(process.cwd(), process.env.AVATAR_DIR || '/avatars'),
+  );
+  if (existsSync(config.parameters.avatarDir)) {
+    try {
+      await moveFiles(config.parameters.avatarDir, oldPath);
+      logger.log('Avatars folder successfully moved to the old location ...');
+    } catch (err) {
+      logger.error(err);
+      logger.log('Unable to move avatar files to the old folder ...');
+    }
+  } else {
+    logger.log('No avatars folder found ...');
+  }
+};
+
+module.exports = {
+  async up(services: MigrationServices) {
+    await populateSubscriberAvatar(services);
+    await updateOldAvatarsPath(services);
+    return true;
+  },
+  async down(services: MigrationServices) {
+    await unpopulateSubscriberAvatar(services);
+    await restoreOldAvatarsPath(services);
+    return true;
+  },
+};

api/src/plugins/base-storage-plugin.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -28,20 +28,28 @@ export abstract class BaseStoragePlugin extends BasePlugin {
     super(name, pluginService);
   }
 
-  abstract fileExists(attachment: Attachment): Promise<boolean>;
+  /** @deprecated use download() instead */
+  fileExists?(attachment: Attachment): Promise<boolean>;
 
-  abstract upload(file: Express.Multer.File): Promise<AttachmentCreateDto>;
+  /** @deprecated use store() instead */
+  upload?(file: Express.Multer.File): Promise<AttachmentCreateDto>;
 
-  abstract uploadAvatar(file: Express.Multer.File): Promise<any>;
+  /** @deprecated use store() instead */
+  uploadAvatar?(file: Express.Multer.File): Promise<any>;
 
-  abstract download(attachment: Attachment): Promise<StreamableFile>;
+  abstract download(
+    attachment: Attachment,
+    rootLocation?: string,
+  ): Promise<StreamableFile>;
 
-  abstract downloadProfilePic(name: string): Promise<StreamableFile>;
+  /** @deprecated use download() instead */
+  downloadProfilePic?(name: string): Promise<StreamableFile>;
 
   readAsBuffer?(attachment: Attachment): Promise<Buffer>;
 
   store?(
     file: Buffer | Readable | Express.Multer.File,
     metadata: AttachmentMetadataDto,
+    rootDir?: string,
   ): Promise<Attachment>;
 }

api/src/user/controllers/user.controller.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -21,13 +21,17 @@ import {
   Req,
   Session,
   UnauthorizedException,
+  UploadedFile,
   UseInterceptors,
 } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
 import { CsrfCheck } from '@tekuconcept/nestjs-csrf';
 import { Request } from 'express';
 import { Session as ExpressSession } from 'express-session';
+import { diskStorage, memoryStorage } from 'multer';
 
 import { AttachmentService } from '@/attachment/services/attachment.service';
+import { config } from '@/config';
 import { CsrfInterceptor } from '@/interceptors/csrf.interceptor';
 import { LoggerService } from '@/logger/logger.service';
 import { Roles } from '@/utils/decorators/roles.decorator';
@@ -83,7 +87,7 @@ export class ReadOnlyUserController extends BaseController<
    */
   @Roles('public')
   @Get('bot/profile_pic')
-  async botProfilePic(@Query('color') color: string) {
+  async getBotAvatar(@Query('color') color: string) {
     return await getBotAvatar(color);
   }
 
@@ -94,19 +98,28 @@ export class ReadOnlyUserController extends BaseController<
    *
    * @returns A promise that resolves to the user's avatar or an avatar generated from initials if not found.
    */
-  @Roles('public')
   @Get(':id/profile_pic')
-  async UserProfilePic(@Param('id') id: string) {
+  async getAvatar(@Param('id') id: string) {
+    const user = await this.userService.findOneAndPopulate(id);
+    if (!user) {
+      throw new NotFoundException(`user with ID ${id} not found`);
+    }
+
     try {
-      const res = await this.userService.userProfilePic(id);
-      return res;
-    } catch (e) {
-      const user = await this.userService.findOne(id);
-      if (user) {
-        return await generateInitialsAvatar(user);
-      } else {
-        throw new NotFoundException(`user with ID ${id} not found`);
+      if (!user.avatar) {
+        throw new Error('User has no avatar');
       }
+
+      return await this.attachmentService.download(
+        user.avatar,
+        config.parameters.avatarDir,
+      );
+    } catch (err) {
+      this.logger.verbose(
+        'User has no avatar, generating initials avatar ...',
+        err,
+      );
+      return await generateInitialsAvatar(user);
     }
   }
 
@@ -251,17 +264,54 @@ export class ReadWriteUserController extends ReadOnlyUserController {
    * @returns A promise that resolves to the updated user.
    */
   @CsrfCheck(true)
+  @UseInterceptors(
+    FileInterceptor('avatar', {
+      limits: {
+        fileSize: config.parameters.maxUploadSize,
+      },
+      storage: (() => {
+        if (config.parameters.storageMode === 'memory') {
+          return memoryStorage();
+        } else {
+          return diskStorage({});
+        }
+      })(),
+    }),
+  )
   @Patch('edit/:id')
   async updateOne(
     @Req() req: Request,
     @Param('id') id: string,
     @Body() userUpdate: UserEditProfileDto,
+    @UploadedFile() avatarFile?: Express.Multer.File,
   ) {
     if (!('id' in req.user && req.user.id) || req.user.id !== id) {
-      throw new UnauthorizedException();
+      throw new ForbiddenException();
     }
 
-    const result = await this.userService.updateOne(req.user.id, userUpdate);
+    // Upload Avatar if provided
+    const avatar = avatarFile
+      ? await this.attachmentService.store(
+          avatarFile,
+          {
+            name: avatarFile.originalname,
+            size: avatarFile.size,
+            type: avatarFile.mimetype,
+          },
+          config.parameters.avatarDir,
+        )
+      : undefined;
+
+    const result = await this.userService.updateOne(
+      req.user.id,
+      avatar
+        ? {
+            ...userUpdate,
+            avatar: avatar.id,
+          }
+        : userUpdate,
+    );
+
     if (!result) {
       this.logger.warn(`Unable to update User by id ${id}`);
       throw new NotFoundException(`User with ID ${id} not found`);

api/src/user/dto/user.dto.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -14,12 +14,12 @@ import {
   PartialType,
 } from '@nestjs/swagger';
 import {
-  IsEmail,
-  IsNotEmpty,
-  IsString,
   IsArray,
   IsBoolean,
+  IsEmail,
+  IsNotEmpty,
   IsOptional,
+  IsString,
 } from 'class-validator';
 
 import { IsObjectId } from '@/utils/validation-rules/is-object-id';
@@ -66,6 +66,7 @@ export class UserCreateDto {
 export class UserEditProfileDto extends OmitType(PartialType(UserCreateDto), [
   'username',
   'roles',
+  'avatar',
 ]) {
   @ApiPropertyOptional({ description: 'User language', type: String })
   @IsOptional()

api/src/user/guards/ability.guard.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -53,9 +53,18 @@ export class Ability implements CanActivate {
 
     if (user?.roles?.length) {
       if (
-        ['/auth/logout', '/logout', '/auth/me', '/channel', '/i18n'].includes(
-          _parsedUrl.pathname,
-        )
+        [
+          // Allow access to all routes available for authenticated users
+          '/auth/logout',
+          '/logout',
+          '/auth/me',
+          '/channel',
+          '/i18n',
+          // Allow to update own profile
+          `/user/edit/${user.id}`,
+          // Allow access to own avatar
+          `/user/${user.id}/profile_pic`,
+        ].includes(_parsedUrl.pathname)
       ) {
         return true;
       }

api/src/user/services/user.service.ts

@@ -1,17 +1,13 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
-import { join } from 'path';
+import { Injectable } from '@nestjs/common';
 
-import { Injectable, NotFoundException, StreamableFile } from '@nestjs/common';
-
-import { getStreamableFile } from '@/attachment/utilities';
-import { config } from '@/config';
 import { BaseService } from '@/utils/generics/base-service';
 
 import { UserRepository } from '../repositories/user.repository';
@@ -22,33 +18,4 @@ export class UserService extends BaseService<User, UserPopulate, UserFull> {
   constructor(readonly repository: UserRepository) {
     super(repository);
   }
-
-  /**
-   * Retrieves the user's profile picture as a streamable file.
-   *
-   * @param id - The ID of the user whose profile picture is requested.
-   *
-   * @returns A promise that resolves with the streamable file of the user's profile picture.
-   */
-  async userProfilePic(id: string): Promise<StreamableFile> {
-    const user = await this.findOneAndPopulate(id);
-    if (user) {
-      const attachment = user.avatar;
-      const path = join(config.parameters.uploadDir, attachment.location);
-      const disposition = `attachment; filename="${encodeURIComponent(
-        attachment.name,
-      )}"`;
-
-      return getStreamableFile({
-        path,
-        options: {
-          type: attachment.type,
-          length: attachment.size,
-          disposition,
-        },
-      });
-    } else {
-      throw new NotFoundException('Profile Not found');
-    }
-  }
 }

api/src/utils/helpers/fs.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright © 2025 Hexastack. All rights reserved.
+ *
+ * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
+ * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
+ * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
+ */
+
+import fs from 'fs';
+import { basename, join, resolve } from 'path';
+
+export async function moveFile(
+  sourcePath: string,
+  destinationPath: string,
+  overwrite: boolean = true,
+): Promise<string> {
+  // Check if the file exists at the destination
+  try {
+    if (overwrite) {
+      await fs.promises.unlink(destinationPath); // Remove existing file if overwrite is true
+    } else {
+      await fs.promises.access(destinationPath);
+      throw new Error(`File already exists at destination: ${destinationPath}`);
+    }
+  } catch {
+    // Ignore if file does not exist
+  }
+
+  // Move the file
+  await fs.promises.copyFile(sourcePath, destinationPath);
+  await fs.promises.unlink(sourcePath);
+  return destinationPath;
+}
+
+/**
+ * Moves all files from a source folder to a destination folder.
+ * @param sourceFolder - The folder containing the files to move.
+ * @param destinationFolder - The folder where the files should be moved.
+ * @param overwrite - Whether to overwrite files if they already exist at the destination (default: false).
+ * @returns A promise that resolves when all files have been moved.
+ */
+export async function moveFiles(
+  sourceFolder: string,
+  destinationFolder: string,
+  overwrite: boolean = true,
+): Promise<void> {
+  // Read the contents of the source folder
+  const files = await fs.promises.readdir(sourceFolder);
+
+  // Filter only files (skip directories)
+  const filePaths = [];
+  for (const file of files) {
+    const filePath = join(sourceFolder, file);
+    const stat = await fs.promises.stat(filePath);
+    if (stat.isFile()) {
+      filePaths.push(filePath);
+    }
+  }
+
+  // Move each file to the destination folder
+  for (const filePath of filePaths) {
+    const fileName = basename(filePath);
+    const destination = resolve(join(destinationFolder, fileName));
+    await moveFile(filePath, destination, overwrite);
+  }
+}