@hexabot-ai/api 3.2.2-alpha.1 → 3.2.2-alpha.10

package/src/mcp/decorators/mcp-permission.decorator.ts

@@ -0,0 +1,23 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { SetMetadata } from '@nestjs/common';
+
+import { Action } from '@/user/types/action.type';
+import { TModel } from '@/user/types/model.type';
+
+export const MCP_PERMISSION_METADATA_KEY = 'mcp:hexabot-permission';
+
+export type McpPermissionMetadata = {
+  model: TModel;
+  action: Action;
+};
+
+export const McpPermission = (model: TModel, action: Action): MethodDecorator =>
+  SetMetadata(MCP_PERMISSION_METADATA_KEY, {
+    model,
+    action,
+  } satisfies McpPermissionMetadata);

package/src/mcp/dto/mcp-token.dto.ts

@@ -0,0 +1,48 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { mcpTokenFullSchema, mcpTokenSchema } from '@hexabot-ai/types';
+import { ApiProperty, ApiPropertyOptional, PartialType } from '@nestjs/swagger';
+import {
+  IsDateString,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+import { TDto } from '@/utils/types/dto.types';
+
+export class McpTokenCreateDto {
+  @ApiProperty({
+    description: 'Human-readable MCP token name',
+    type: String,
+  })
+  @IsNotEmpty()
+  @IsString()
+  name!: string;
+
+  @ApiPropertyOptional({
+    description: 'Optional token expiry date',
+    type: String,
+    format: 'date-time',
+  })
+  @IsOptional()
+  @IsDateString()
+  expiresAt?: string | null;
+}
+
+export class McpTokenUpdateDto extends PartialType(McpTokenCreateDto) {}
+
+export type McpTokenDto = TDto<
+  {
+    plain: typeof mcpTokenSchema;
+    full: typeof mcpTokenFullSchema;
+  },
+  {
+    create: McpTokenCreateDto;
+    update: McpTokenUpdateDto;
+  }
+>;

package/src/mcp/entities/mcp-token.entity.ts

@@ -0,0 +1,60 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { mcpTokenFullSchema, mcpTokenSchema } from '@hexabot-ai/types';
+import {
+  Column,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  RelationId,
+} from 'typeorm';
+
+import { DatetimeColumn } from '@/database';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+import { UserOrmEntity } from '@/user/entities/user.entity';
+import { AsRelation } from '@/utils/decorators/relation-ref.decorator';
+
+import { McpTokenDto } from '../dto/mcp-token.dto';
+
+@Entity({ name: 'mcp_tokens' })
+@Index(['tokenHash'], { unique: true })
+@Index(['owner'])
+export class McpTokenOrmEntity extends BaseOrmEntity<McpTokenDto> {
+  plainCls = mcpTokenSchema;
+
+  fullCls = mcpTokenFullSchema;
+
+  @Column()
+  name!: string;
+
+  @Column({ name: 'token_hash', type: 'text' })
+  tokenHash!: string;
+
+  @Column({ name: 'token_prefix', length: 32 })
+  tokenPrefix!: string;
+
+  @ManyToOne(() => UserOrmEntity, {
+    nullable: false,
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn({ name: 'owner_id' })
+  @AsRelation()
+  owner!: UserOrmEntity;
+
+  @RelationId((token: McpTokenOrmEntity) => token.owner)
+  private readonly ownerId!: string;
+
+  @DatetimeColumn({ name: 'expires_at', nullable: true })
+  expiresAt!: Date | null;
+
+  @DatetimeColumn({ name: 'last_used_at', nullable: true })
+  lastUsedAt!: Date | null;
+
+  @DatetimeColumn({ name: 'revoked_at', nullable: true })
+  revokedAt!: Date | null;
+}

package/src/mcp/guards/hexabot-mcp-token.guard.ts

@@ -0,0 +1,55 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { Request } from 'express';
+
+import { McpTokenService } from '../services/mcp-token.service';
+import { HexabotMcpRequest } from '../types';
+
+@Injectable()
+export class HexabotMcpTokenGuard implements CanActivate {
+  constructor(private readonly moduleRef: ModuleRef) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<HexabotMcpRequest>();
+    const token = this.extractTokenFromHeader(request);
+
+    if (!token) {
+      throw new UnauthorizedException('MCP bearer token is required');
+    }
+
+    const { user, tokenId } =
+      await this.getMcpTokenService().authenticateBearerToken(token);
+
+    request.hexabotUser = user;
+    request.user = user;
+    request.mcpTokenId = tokenId;
+
+    return true;
+  }
+
+  private extractTokenFromHeader(request: Request): string | undefined {
+    const authHeader = request.headers.authorization;
+    if (!authHeader) {
+      return undefined;
+    }
+
+    const [type, token] = authHeader.split(' ');
+
+    return type === 'Bearer' ? token : undefined;
+  }
+
+  private getMcpTokenService(): McpTokenService {
+    return this.moduleRef.get(McpTokenService, { strict: false });
+  }
+}

package/src/mcp/guards/mcp-permission.guard.ts

@@ -0,0 +1,61 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+
+import {
+  MCP_PERMISSION_METADATA_KEY,
+  McpPermissionMetadata,
+} from '@/mcp/decorators/mcp-permission.decorator';
+import { PermissionService } from '@/user/services/permission.service';
+
+import { HexabotMcpRequest } from '../types';
+
+@Injectable()
+export class McpPermissionGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly permissionService: PermissionService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const permission = this.reflector.getAllAndOverride<McpPermissionMetadata>(
+      MCP_PERMISSION_METADATA_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!permission) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<HexabotMcpRequest>();
+    const user = request.hexabotUser ?? request.user;
+    const roleIds = Array.isArray(user?.roles) ? user.roles : [];
+
+    if (roleIds.length === 0) {
+      throw new ForbiddenException('MCP tool requires a Hexabot role');
+    }
+
+    const permissions = await this.permissionService.getPermissions();
+    const hasPermission = roleIds.some((roleId) =>
+      permissions[roleId]?.[permission.model]?.includes(permission.action),
+    );
+
+    if (!hasPermission) {
+      throw new ForbiddenException(
+        `MCP tool requires ${permission.action} permission on ${permission.model}`,
+      );
+    }
+
+    return true;
+  }
+}

package/src/mcp/mcp-api.module.ts

@@ -0,0 +1,61 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { randomUUID } from 'crypto';
+
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { McpModule, McpTransportType } from '@rekog/mcp-nest';
+
+import { ActionsModule } from '@/actions/actions.module';
+import { BindingsModule } from '@/bindings/bindings.module';
+import { CmsModule } from '@/cms/cms.module';
+import { config } from '@/config';
+import { UserModule } from '@/user/user.module';
+import { WorkflowModule } from '@/workflow/workflow.module';
+
+import { McpTokenController } from './controllers/mcp-token.controller';
+import { McpTokenOrmEntity } from './entities/mcp-token.entity';
+import { HexabotMcpTokenGuard } from './guards/hexabot-mcp-token.guard';
+import { McpPermissionGuard } from './guards/mcp-permission.guard';
+import { McpTokenRepository } from './repositories/mcp-token.repository';
+import { McpTokenService } from './services/mcp-token.service';
+import { HexabotMcpTools } from './tools/hexabot-mcp.tools';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([McpTokenOrmEntity]),
+    McpModule.forRoot({
+      name: config.mcp.serverName,
+      title: config.mcp.serverTitle,
+      version: config.mcp.serverVersion,
+      description: config.mcp.serverDescription,
+      instructions: config.mcp.serverInstructions,
+      transport: McpTransportType.STREAMABLE_HTTP,
+      mcpEndpoint: 'mcp',
+      guards: [HexabotMcpTokenGuard],
+      streamableHttp: {
+        enableJsonResponse: false,
+        sessionIdGenerator: () => randomUUID(),
+        statelessMode: false,
+      },
+    }),
+    ActionsModule,
+    BindingsModule,
+    CmsModule,
+    UserModule,
+    WorkflowModule,
+  ],
+  providers: [
+    HexabotMcpTokenGuard,
+    McpPermissionGuard,
+    McpTokenRepository,
+    McpTokenService,
+    HexabotMcpTools,
+  ],
+  controllers: [McpTokenController],
+})
+export class McpApiModule {}

package/src/mcp/repositories/mcp-token.repository.ts

@@ -0,0 +1,34 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import { McpTokenOrmEntity } from '../entities/mcp-token.entity';
+
+@Injectable()
+export class McpTokenRepository extends BaseOrmRepository<McpTokenOrmEntity> {
+  constructor(
+    @InjectRepository(McpTokenOrmEntity)
+    repository: Repository<McpTokenOrmEntity>,
+  ) {
+    super(repository, ['owner']);
+  }
+
+  async findOneByHash(tokenHash: string): Promise<McpTokenOrmEntity | null> {
+    return await this.repository.findOne({
+      where: { tokenHash },
+      relations: ['owner', 'owner.roles'],
+    });
+  }
+
+  async touchLastUsedAt(id: string, lastUsedAt = new Date()): Promise<void> {
+    await this.repository.update(id, { lastUsedAt });
+  }
+}

package/src/mcp/services/mcp-token.service.ts

@@ -0,0 +1,138 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { createHash, randomBytes } from 'crypto';
+
+import type { McpToken, User } from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { FindManyOptions } from 'typeorm';
+
+import { UserOrmEntity } from '@/user/entities/user.entity';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { McpTokenCreateDto } from '../dto/mcp-token.dto';
+import { McpTokenOrmEntity } from '../entities/mcp-token.entity';
+import { McpTokenRepository } from '../repositories/mcp-token.repository';
+
+export const MCP_PERSONAL_TOKEN_PREFIX = 'hbt_mcp_';
+
+@Injectable()
+export class McpTokenService extends BaseOrmService<McpTokenOrmEntity> {
+  constructor(readonly repository: McpTokenRepository) {
+    super(repository);
+  }
+
+  async createPersonalToken(
+    ownerId: string,
+    dto: McpTokenCreateDto,
+  ): Promise<{ token: string; record: McpToken }> {
+    const token = this.generateToken();
+    const expiresAt = this.parseOptionalExpiry(dto.expiresAt);
+    const record = await this.repository.create({
+      name: dto.name,
+      owner: ownerId,
+      tokenHash: this.hashToken(token),
+      tokenPrefix: this.getTokenPrefix(token),
+      expiresAt,
+      lastUsedAt: null,
+      revokedAt: null,
+    } as any);
+
+    return { token, record };
+  }
+
+  async findOwnedTokens(ownerId: string): Promise<McpToken[]> {
+    return await this.repository.find({
+      where: { owner: { id: ownerId } },
+      order: { createdAt: 'DESC' },
+    } as FindManyOptions<McpTokenOrmEntity>);
+  }
+
+  async revokeOwnedToken(ownerId: string, id: string): Promise<McpToken> {
+    const token = await this.repository.findOne({
+      where: { id, owner: { id: ownerId } },
+    } as any);
+
+    if (!token) {
+      throw new NotFoundException(`MCP token ${id} not found`);
+    }
+
+    return await this.repository.updateOne(
+      {
+        where: { id, owner: { id: ownerId } },
+      } as any,
+      { revokedAt: new Date() } as any,
+    );
+  }
+
+  async authenticateBearerToken(
+    token: string,
+  ): Promise<{ user: User; tokenId: string }> {
+    if (!token.startsWith(MCP_PERSONAL_TOKEN_PREFIX)) {
+      throw new UnauthorizedException('Invalid MCP token');
+    }
+
+    const record = await this.repository.findOneByHash(this.hashToken(token));
+
+    if (!record) {
+      throw new UnauthorizedException('Invalid MCP token');
+    }
+
+    if (record.revokedAt) {
+      throw new UnauthorizedException('MCP token has been revoked');
+    }
+
+    if (record.expiresAt && record.expiresAt <= new Date()) {
+      throw new UnauthorizedException('MCP token has expired');
+    }
+
+    const owner = record.owner as UserOrmEntity | undefined;
+    if (!owner?.state) {
+      throw new UnauthorizedException('MCP token owner is inactive');
+    }
+
+    await this.repository.touchLastUsedAt(record.id);
+
+    return {
+      user: owner.toPlainCls() as User,
+      tokenId: record.id,
+    };
+  }
+
+  private generateToken(): string {
+    return `${MCP_PERSONAL_TOKEN_PREFIX}${randomBytes(32).toString('base64url')}`;
+  }
+
+  private hashToken(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+
+  private getTokenPrefix(token: string): string {
+    return token.slice(0, MCP_PERSONAL_TOKEN_PREFIX.length + 8);
+  }
+
+  private parseOptionalExpiry(value?: string | null): Date | null {
+    if (!value) {
+      return null;
+    }
+
+    const expiresAt = new Date(value);
+    if (Number.isNaN(expiresAt.getTime())) {
+      throw new BadRequestException('Invalid MCP token expiry date');
+    }
+
+    if (expiresAt <= new Date()) {
+      throw new BadRequestException('MCP token expiry must be in the future');
+    }
+
+    return expiresAt;
+  }
+}