@hexabot-ai/api 3.0.0-alpha.3

package/src/user/services/permission.service.ts

@@ -0,0 +1,86 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Cache } from 'cache-manager';
+
+import { PERMISSION_CACHE_KEY } from '@/utils/constants/cache';
+import { Cacheable } from '@/utils/decorators/cacheable.decorator';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import {
+  PermissionDtoConfig,
+  PermissionFull,
+  PermissionTransformerDto,
+} from '../dto/permission.dto';
+import { PermissionOrmEntity } from '../entities/permission.entity';
+import { PermissionRepository } from '../repositories/permission.repository';
+import { PermissionsTree } from '../types/permission.type';
+
+@Injectable()
+export class PermissionService extends BaseOrmService<
+  PermissionOrmEntity,
+  PermissionTransformerDto,
+  PermissionDtoConfig
+> {
+  constructor(
+    readonly repository: PermissionRepository,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Handles permission update events by clearing the permissions cache.
+   *
+   * This method listens to events matching the pattern 'hook:access:*:*' and clears
+   * the permissions cache to ensure fresh data is used for subsequent requests.
+   */
+  @OnEvent('hook:role:*')
+  @OnEvent('hook:permission:*')
+  async handlePermissionUpdateEvent() {
+    await this.cacheManager.del(PERMISSION_CACHE_KEY);
+  }
+
+  /**
+   * Retrieves the permissions tree from the cache or generates it if not present.
+   *
+   * @returns A promise that resolves with the permissions tree.
+   */
+  @Cacheable(PERMISSION_CACHE_KEY)
+  async getPermissions(): Promise<PermissionsTree> {
+    const currentPermissions = await this.findAllAndPopulate();
+
+    return this.buildTree(currentPermissions);
+  }
+
+  /**
+   * Builds a tree structure of permissions based on roles and models.
+   *
+   * @param permissions - Array of permission entities.
+   *
+   * @returns A tree structure mapping roles and models to actions.
+   */
+  buildTree(permissions: PermissionFull[]): PermissionsTree {
+    return permissions.reduce<PermissionsTree>((acc, p) => {
+      const role = p.role?.id;
+      const model = p.model?.identity ?? p.model?.id;
+
+      if (!role || !model) {
+        return acc;
+      }
+
+      acc[role] = acc[role] || {};
+      acc[role][model] = acc[role][model] || [];
+
+      acc[role][model].push(p.action);
+
+      return acc;
+    }, {});
+  }
+}

package/src/user/services/role.service.ts

@@ -0,0 +1,24 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { RoleDtoConfig, RoleTransformerDto } from '../dto/role.dto';
+import { RoleOrmEntity } from '../entities/role.entity';
+import { RoleRepository } from '../repositories/role.repository';
+
+@Injectable()
+export class RoleService extends BaseOrmService<
+  RoleOrmEntity,
+  RoleTransformerDto,
+  RoleDtoConfig
+> {
+  constructor(readonly repository: RoleRepository) {
+    super(repository);
+  }
+}

package/src/user/services/user.service.ts

@@ -0,0 +1,24 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { UserDtoConfig, UserTransformerDto } from '../dto/user.dto';
+import { UserOrmEntity } from '../entities/user.entity';
+import { UserRepository } from '../repositories/user.repository';
+
+@Injectable()
+export class UserService extends BaseOrmService<
+  UserOrmEntity,
+  UserTransformerDto,
+  UserDtoConfig
+> {
+  constructor(readonly repository: UserRepository) {
+    super(repository);
+  }
+}

package/src/user/services/validate-account.service.ts

@@ -0,0 +1,130 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  Inject,
+  Injectable,
+  InternalServerErrorException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { JwtService, JwtSignOptions, JwtVerifyOptions } from '@nestjs/jwt';
+
+import { config } from '@/config';
+import { I18nService } from '@/i18n/services/i18n.service';
+import { LanguageService } from '@/i18n/services/language.service';
+import { LoggerService } from '@/logger/logger.service';
+import { MailerService } from '@/mailer/mailer.service';
+
+import { UserCreateDto } from '../dto/user.dto';
+
+import { UserService } from './user.service';
+
+@Injectable()
+export class ValidateAccountService {
+  public readonly jwtSignOptions: JwtSignOptions = {
+    secret: config.confirm_account.jwtOptions.secret,
+    expiresIn: config.confirm_account.jwtOptions.expiresIn,
+    encoding: 'utf-8',
+  };
+
+  constructor(
+    @Inject(JwtService) private readonly jwtService: JwtService,
+    private readonly userService: UserService,
+    private logger: LoggerService,
+    private readonly i18n: I18nService,
+    private readonly languageService: LanguageService,
+    private readonly mailerService: MailerService,
+  ) {}
+
+  /**
+   * Signs a JWT token containing the user's email.
+   *
+   * @param dto - Object containing the user's email.
+   *
+   * @returns A promise that resolves to the signed JWT token.
+   */
+  async sign(dto: { email: string }) {
+    return await this.jwtService.signAsync(dto, this.jwtSignOptions);
+  }
+
+  /**
+   * Verifies a given JWT token.
+   *
+   * @param token - The JWT token to be verified.
+   *
+   * @returns A promise that resolves to an object containing the user's email.
+   */
+  async verify(token: string): Promise<{ email: string }> {
+    return await this.jwtService.verifyAsync(
+      token,
+      this.jwtSignOptions as JwtVerifyOptions,
+    );
+  }
+
+  /**
+   * Sends an account confirmation email to the user.
+   *
+   * The email includes a confirmation token and user's first name.
+   *
+   * @param dto - An object containing the user's email and first name.
+   */
+  async sendConfirmationEmail(
+    dto: Pick<UserCreateDto, 'email' | 'first_name'>,
+  ) {
+    const confirmationToken = await this.sign({ email: dto.email });
+
+    try {
+      const defaultLanguage = await this.languageService.getDefaultLanguage();
+      await this.mailerService.sendMail({
+        to: dto.email,
+        template: 'account_confirmation.mjml',
+        context: {
+          appName: config.parameters.appName,
+          appUrl: config.uiBaseUrl,
+          token: confirmationToken,
+          first_name: dto.first_name,
+          t: (key: string) => this.i18n.t(key, { lang: defaultLanguage.code }),
+        },
+        subject: this.i18n.t('account_confirmation_subject'),
+      });
+    } catch (e) {
+      this.logger.error(
+        'Could not send email',
+        e.message,
+        e.stack,
+        'ValidateAccount',
+      );
+      throw new InternalServerErrorException('Could not send email');
+    }
+  }
+
+  /**
+   * Confirms a user's account by validating the provided confirmation token.
+   *
+   * If the token is valid, it updates the user's account state to confirmed.
+   * Throws an error if the token is invalid or if any other error occurs.
+   *
+   * @param dto - An object containing the confirmation token.
+   *
+   * @returns An empty object if the account is successfully confirmed.
+   */
+  async confirmAccount(dto: { token: string }) {
+    const decodedToken = await this.verify(dto.token).catch((e) => {
+      throw new UnauthorizedException(e.message);
+    });
+
+    await this.userService.updateOne(
+      { where: { email: decodedToken.email } },
+      { state: true },
+    );
+    try {
+    } catch (_e) {
+      throw new InternalServerErrorException('Could confirm email');
+    }
+
+    return {};
+  }
+}

package/src/user/types/action.type.ts

@@ -0,0 +1,19 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export enum Action {
+  CREATE = 'create',
+  READ = 'read',
+  UPDATE = 'update',
+  DELETE = 'delete',
+}
+
+export enum MethodToAction {
+  POST = 'create',
+  GET = 'read',
+  PATCH = 'update',
+  DELETE = 'delete',
+}

package/src/user/types/index.type.ts

@@ -0,0 +1,7 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export type TRelation = 'role' | 'createdBy';

package/src/user/types/model.type.ts

@@ -0,0 +1,31 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export type TModel =
+  | 'contenttype'
+  | 'content'
+  | 'nlpentity'
+  | 'nlpsampleentity'
+  | 'nlpsample'
+  | 'nlpvalue'
+  | 'setting'
+  | 'attachment'
+  | 'user'
+  | 'role'
+  | 'permission'
+  | 'block'
+  | 'category'
+  | 'label'
+  | 'labelgroup'
+  | 'contextvar'
+  | 'conversation'
+  | 'message'
+  | 'subscriber'
+  | 'language'
+  | 'translation'
+  | 'botstats'
+  | 'menu'
+  | 'model';

package/src/user/types/permission.type.ts

@@ -0,0 +1,12 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Action } from './action.type';
+import { TModel } from './model.type';
+
+type ModelPermissionsPerRole = Record<TModel, Action[]>;
+
+export type PermissionsTree = Record<string, ModelPermissionsPerRole>;

package/src/user/types/user-provider.type.ts

@@ -0,0 +1,10 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export type UserProvider = {
+  strategy: 'local';
+  sub?: string;
+};

package/src/user/user.module.ts

@@ -0,0 +1,93 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { forwardRef, Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
+import { PassportModule } from '@nestjs/passport';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { AttachmentModule } from '@/attachment/attachment.module';
+import { MailerModule } from '@/mailer/mailer.module';
+
+import { LocalAuthController } from './controllers/auth.controller';
+import { ModelController } from './controllers/model.controller';
+import { PermissionController } from './controllers/permission.controller';
+import { RoleController } from './controllers/role.controller';
+import { ReadWriteUserController } from './controllers/user.controller';
+import { InvitationOrmEntity } from './entities/invitation.entity';
+import { ModelOrmEntity } from './entities/model.entity';
+import { PermissionOrmEntity } from './entities/permission.entity';
+import { RoleOrmEntity } from './entities/role.entity';
+import { UserOrmEntity } from './entities/user.entity';
+import { LocalAuthGuard } from './guards/local-auth.guard';
+import { LocalStrategy } from './passport/auth-strategy/local.strategy';
+import { AuthSerializer } from './passport/session.serializer';
+import { InvitationRepository } from './repositories/invitation.repository';
+import { ModelRepository } from './repositories/model.repository';
+import { PermissionRepository } from './repositories/permission.repository';
+import { RoleRepository } from './repositories/role.repository';
+import { UserRepository } from './repositories/user.repository';
+import { ModelSeeder } from './seeds/model.seed';
+import { PermissionSeeder } from './seeds/permission.seed';
+import { RoleSeeder } from './seeds/role.seed';
+import { UserSeeder } from './seeds/user.seed';
+import { AuthService } from './services/auth.service';
+import { InvitationService } from './services/invitation.service';
+import { ModelService } from './services/model.service';
+import { PasswordResetService } from './services/passwordReset.service';
+import { PermissionService } from './services/permission.service';
+import { RoleService } from './services/role.service';
+import { UserService } from './services/user.service';
+import { ValidateAccountService } from './services/validate-account.service';
+
+@Module({
+  imports: [
+    MailerModule,
+    TypeOrmModule.forFeature([
+      UserOrmEntity,
+      ModelOrmEntity,
+      InvitationOrmEntity,
+      RoleOrmEntity,
+      PermissionOrmEntity,
+    ]),
+    PassportModule.register({
+      session: true,
+    }),
+    JwtModule,
+    forwardRef(() => AttachmentModule),
+  ],
+  providers: [
+    PermissionSeeder,
+    PermissionService,
+    ModelService,
+    UserService,
+    RoleService,
+    ModelSeeder,
+    RoleSeeder,
+    UserSeeder,
+    UserRepository,
+    RoleRepository,
+    ModelRepository,
+    PermissionRepository,
+    LocalStrategy,
+    AuthService,
+    LocalAuthGuard,
+    AuthSerializer,
+    InvitationRepository,
+    InvitationService,
+    PasswordResetService,
+    ValidateAccountService,
+  ],
+  controllers: [
+    LocalAuthController,
+    ReadWriteUserController,
+    RoleController,
+    PermissionController,
+    ModelController,
+  ],
+  exports: [UserService, PermissionService, ModelService],
+})
+export class UserModule {}

package/src/user/utilities/bcryptjs.ts

@@ -0,0 +1,12 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { hashSync } from 'bcryptjs';
+
+import { config } from '@/config';
+
+export const hash = (plainPassword: string) =>
+  hashSync(plainPassword, config.authentication.jwtOptions.salt);

package/src/user/utilities/hash.ts

@@ -0,0 +1,10 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createHash } from 'node:crypto';
+
+export const sha256Hash = (value: string) =>
+  createHash('sha256').update(value).digest('base64url');

package/src/utils/constants/cache.ts

@@ -0,0 +1,20 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+// CACHE
+export const SETTING_CACHE_KEY = 'settings';
+
+export const PERMISSION_CACHE_KEY = 'permissions';
+
+export const MENU_CACHE_KEY = 'menu';
+
+export const LANGUAGES_CACHE_KEY = 'languages';
+
+export const DEFAULT_LANGUAGE_CACHE_KEY = 'default_language';
+
+export const ALLOWED_ORIGINS_CACHE_KEY = 'allowed_origins';
+
+export const NLP_MAP_CACHE_KEY = 'nlp_map';

package/src/utils/constants/mock.ts

@@ -0,0 +1,7 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export const NOT_FOUND_ID = '99999999-9999-4999-9999-999999999999';

package/src/utils/constants/nlp.ts

@@ -0,0 +1,7 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export const FALLBACK_DEFAULT_NLU_PENALTY_FACTOR = 0.95;

package/src/utils/constants/session-middleware.ts

@@ -0,0 +1,39 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { RequestHandler } from 'express';
+import session from 'express-session';
+
+import { config } from '@/config';
+
+import { getSessionStore } from './session-store';
+
+let sessionMiddleware: RequestHandler | null = null;
+
+export const getSessionMiddleware = () => {
+  const isProduction = config.env.toLowerCase().includes('prod');
+
+  if (!sessionMiddleware) {
+    sessionMiddleware = session({
+      name: config.session.name,
+      secret: config.session.secret,
+      proxy: config.security.trustProxy,
+      resave: true,
+      saveUninitialized: false,
+      store: getSessionStore(),
+      cookie: {
+        httpOnly: true,
+        secure: config.security.httpsEnabled,
+        path: '/',
+        maxAge: isProduction
+          ? 1000 * 60 * 60 * 24 //prod 24h
+          : 1000 * 60 * 60, //dev 1h
+      },
+    });
+  }
+
+  return sessionMiddleware;
+};

package/src/utils/constants/session-store.ts

@@ -0,0 +1,71 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { TypeormStore } from 'connect-typeorm';
+import session from 'express-session';
+import { DataSource } from 'typeorm';
+
+import { AppInstance } from '@/app.instance';
+import { config } from '@/config';
+import { SessionOrmEntity } from '@/user/entities/session.entity';
+
+const toSeconds = (milliseconds: number): number =>
+  Math.max(1, Math.floor(milliseconds / 1000));
+const logStoreError = (error: Error) => {
+  if (config.env === 'test') {
+    return;
+  }
+  // eslint-disable-next-line no-console
+  console.error('[session-store] TypeORM store error:', error);
+};
+const buildTypeormStore = (): session.Store => {
+  if (!AppInstance.isReady()) {
+    return new session.MemoryStore();
+  }
+
+  if (config.database.type === 'mongodb') {
+    throw new Error(
+      'TypeORM-backed session store is not available for MongoDB',
+    );
+  }
+
+  const app = AppInstance.getApp();
+  const dataSource = app.get(DataSource);
+
+  if (!dataSource.isInitialized) {
+    throw new Error('TypeORM data source is not initialized');
+  }
+
+  const repository = dataSource.getRepository(SessionOrmEntity);
+
+  return new TypeormStore({
+    cleanupLimit: config.session.cleanupLimit,
+    limitSubquery: config.session.limitSubquery,
+    ttl: config.session.ttlSeconds ?? toSeconds(config.session.cookie.maxAge),
+    onError: (_store, error) => logStoreError(error),
+  }).connect(repository);
+};
+
+let sessionStore: session.Store | null = null;
+
+export const getSessionStore = (): session.Store => {
+  if (!sessionStore) {
+    try {
+      sessionStore = buildTypeormStore();
+    } catch (error) {
+      if (config.env !== 'test') {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[session-store] Falling back to in-memory store:',
+          error instanceof Error ? error.message : error,
+        );
+      }
+      sessionStore = new session.MemoryStore();
+    }
+  }
+
+  return sessionStore;
+};

package/src/utils/decorators/cacheable.decorator.ts

@@ -0,0 +1,53 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Cache } from 'cache-manager';
+
+export function Cacheable(cacheKey: string) {
+  return function (
+    target: any,
+    propertyName: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: any[]) {
+      const cache: Cache | undefined = this.cacheManager;
+
+      if (!cache) {
+        throw new Error(
+          'Cannot use Cacheable() decorator without injecting the cache manager.',
+        );
+      }
+
+      // Try to get cached data
+      try {
+        const cachedResult = await cache.get(cacheKey);
+        if (cachedResult) {
+          return cachedResult;
+        }
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`Cache get error for key: ${cacheKey}:`, error);
+      }
+
+      // Call the original method if cache miss
+      const result = await originalMethod.apply(this, args);
+
+      // Set the new result in cache
+      try {
+        await cache.set(cacheKey, result);
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`Cache set error for key: ${cacheKey}:`, error);
+      }
+
+      return result;
+    };
+
+    return descriptor;
+  };
+}