@hexabot-ai/api 3.1.4-alpha.0 → 3.2.1-alpha.0

package/src/audit/controllers/audit-log.controller.ts

@@ -0,0 +1,77 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { AuditLog, AuditLogFull } from '@hexabot-ai/types';
+import { Controller, Get, Query } from '@nestjs/common';
+import { FindManyOptions } from 'typeorm';
+
+import { UuidParam } from '@/utils';
+import { BaseOrmController } from '@/utils/generics/base-orm.controller';
+import { TypeOrmSearchFilterPipe } from '@/utils/pipes/typeorm-search-filter.pipe';
+import { TFilterNestedKeysOfType } from '@/utils/types/filter.types';
+
+import { AuditLogOrmEntity } from '../entities/audit-log.entity';
+import { AuditLogRecordService } from '../services/audit-log-record.service';
+
+export const AUDIT_LOG_ALLOWED_FILTER_FIELDS: TFilterNestedKeysOfType<AuditLogOrmEntity>[] =
+  [
+    'resourceId',
+    'resourceType',
+    'resourceLabel',
+    'operationId',
+    'operationType',
+    'operationStatus',
+    'actorId',
+    'actorType',
+    'actorLabel',
+    'actorIp',
+    'requestId',
+    'requestMethod',
+    'requestPath',
+  ];
+
+@Controller('auditlog')
+export class AuditLogController extends BaseOrmController<AuditLogOrmEntity> {
+  constructor(private readonly auditLogService: AuditLogRecordService) {
+    super(auditLogService);
+  }
+
+  @Get()
+  async findAuditLogs(
+    @Query(
+      new TypeOrmSearchFilterPipe<AuditLogOrmEntity>({
+        allowedFields: AUDIT_LOG_ALLOWED_FILTER_FIELDS,
+        defaultSort: ['createdAt', 'desc'],
+      }),
+    )
+    options: FindManyOptions<AuditLogOrmEntity> = {},
+  ): Promise<AuditLog[] | AuditLogFull[]> {
+    this.auditLogService.assertReadableBackend();
+
+    return await this.find(options);
+  }
+
+  @Get('count')
+  async filterCount(
+    @Query(
+      new TypeOrmSearchFilterPipe<AuditLogOrmEntity>({
+        allowedFields: AUDIT_LOG_ALLOWED_FILTER_FIELDS,
+      }),
+    )
+    options: FindManyOptions<AuditLogOrmEntity> = {},
+  ): Promise<{ count: number }> {
+    this.auditLogService.assertReadableBackend();
+
+    return await this.count(options);
+  }
+
+  @Get(':id')
+  async findAuditLog(@UuidParam('id') id: string): Promise<AuditLog> {
+    this.auditLogService.assertReadableBackend();
+
+    return await this.findOne(id);
+  }
+}

package/src/audit/decorators/audit-label.decorator.ts

@@ -0,0 +1,37 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import 'reflect-metadata';
+
+import { EntityMetadata } from 'typeorm';
+
+const AUDIT_LABEL_METADATA_KEY = Symbol('hexabot:audit-label');
+
+export const AuditLabel = (): PropertyDecorator => {
+  return (target, propertyKey) => {
+    if (typeof propertyKey === 'string') {
+      Reflect.defineMetadata(
+        AUDIT_LABEL_METADATA_KEY,
+        propertyKey,
+        target.constructor,
+      );
+    }
+  };
+};
+
+export const getAuditLabelProperty = (
+  metadata: EntityMetadata,
+): string | undefined => {
+  const target = metadata.target;
+
+  if (typeof target !== 'function') {
+    return undefined;
+  }
+
+  const labelProperty = Reflect.getMetadata(AUDIT_LABEL_METADATA_KEY, target);
+
+  return typeof labelProperty === 'string' ? labelProperty : undefined;
+};

package/src/audit/decorators/audit-log.decorators.ts

@@ -0,0 +1,35 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { AuditLog } from 'nestjs-auditlog';
+
+export const AuditAuthLogin = () =>
+  AuditLog({
+    resource: {
+      type: 'Auth',
+    },
+    operation: {
+      id: 'auth.login',
+      type: 'Login',
+    },
+    resource_id_field_map: '$response.id',
+    actor_id_field_map: '$response.id',
+    actor_type_field_map: '$response.roles',
+  });
+
+export const AuditAuthLogout = () =>
+  AuditLog({
+    resource: {
+      type: 'Auth',
+    },
+    operation: {
+      id: 'auth.logout',
+      type: 'Logout',
+    },
+    resource_id_field_map: 'session.passport.user.id',
+    actor_id_field_map: 'session.passport.user.id',
+    actor_type_field_map: 'user.roles',
+  });

package/src/audit/dto/audit-log.dto.ts

@@ -0,0 +1,125 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { auditLogFullSchema, auditLogSchema } from '@hexabot-ai/types';
+import { PartialType } from '@nestjs/mapped-types';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsIn,
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsString,
+} from 'class-validator';
+
+import { TDto } from '@/utils/types/dto.types';
+
+export class AuditLogCreateDto {
+  @ApiProperty({ description: 'Audited resource identifier', type: String })
+  @IsString()
+  @IsNotEmpty()
+  resourceId: string;
+
+  @ApiProperty({ description: 'Audited resource type', type: String })
+  @IsString()
+  @IsNotEmpty()
+  resourceType: string;
+
+  @ApiPropertyOptional({ description: 'Audited resource display label' })
+  @IsString()
+  @IsOptional()
+  resourceLabel?: string | null;
+
+  @ApiProperty({ description: 'Audited operation identifier', type: String })
+  @IsString()
+  @IsNotEmpty()
+  operationId: string;
+
+  @ApiProperty({ description: 'Audited operation type', type: String })
+  @IsString()
+  @IsNotEmpty()
+  operationType: string;
+
+  @ApiProperty({
+    description: 'Audited operation status',
+    enum: ['UNSPECIFIED', 'SUCCEEDED', 'FAILED'],
+  })
+  @IsIn(['UNSPECIFIED', 'SUCCEEDED', 'FAILED'])
+  operationStatus: 'UNSPECIFIED' | 'SUCCEEDED' | 'FAILED';
+
+  @ApiProperty({ description: 'Actor identifier', type: String })
+  @IsString()
+  @IsNotEmpty()
+  actorId: string;
+
+  @ApiProperty({ description: 'Actor type', type: String })
+  @IsString()
+  @IsNotEmpty()
+  actorType: string;
+
+  @ApiPropertyOptional({ description: 'Actor display label' })
+  @IsString()
+  @IsOptional()
+  actorLabel?: string | null;
+
+  @ApiPropertyOptional({ description: 'Actor IP address', type: String })
+  @IsString()
+  @IsOptional()
+  actorIp?: string | null;
+
+  @ApiPropertyOptional({ description: 'Actor user agent', type: String })
+  @IsString()
+  @IsOptional()
+  actorAgent?: string | null;
+
+  @ApiPropertyOptional({ description: 'Request/correlation ID', type: String })
+  @IsString()
+  @IsOptional()
+  requestId?: string | null;
+
+  @ApiPropertyOptional({ description: 'HTTP method', type: String })
+  @IsString()
+  @IsOptional()
+  requestMethod?: string | null;
+
+  @ApiPropertyOptional({ description: 'HTTP path', type: String })
+  @IsString()
+  @IsOptional()
+  requestPath?: string | null;
+
+  @ApiPropertyOptional({ description: 'Data before the operation' })
+  @IsObject()
+  @IsOptional()
+  dataBefore?: unknown;
+
+  @ApiPropertyOptional({ description: 'Data after the operation' })
+  @IsObject()
+  @IsOptional()
+  dataAfter?: unknown;
+
+  @ApiPropertyOptional({ description: 'Computed data diff' })
+  @IsObject()
+  @IsOptional()
+  dataDiff?: unknown;
+
+  @ApiPropertyOptional({ description: 'Raw SDK audit payload' })
+  @IsObject()
+  @IsOptional()
+  raw?: unknown;
+}
+
+export class AuditLogUpdateDto extends PartialType(AuditLogCreateDto) {}
+
+export type AuditLogDto = TDto<
+  {
+    plain: typeof auditLogSchema;
+    full: typeof auditLogFullSchema;
+  },
+  {
+    create: AuditLogCreateDto;
+    update: AuditLogUpdateDto;
+  }
+>;

package/src/audit/entities/audit-log.entity.ts

@@ -0,0 +1,78 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { auditLogFullSchema, auditLogSchema } from '@hexabot-ai/types';
+import { Column, Entity, Index } from 'typeorm';
+
+import { JsonColumn } from '@/database/decorators/json-column.decorator';
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+
+import { AuditLogDto } from '../dto/audit-log.dto';
+
+@Entity({ name: 'audit_logs' })
+@Index(['resourceType', 'resourceId'])
+@Index(['actorId'])
+@Index(['operationType'])
+@Index(['requestId'])
+export class AuditLogOrmEntity extends BaseOrmEntity<AuditLogDto> {
+  plainCls = auditLogSchema;
+
+  fullCls = auditLogFullSchema;
+
+  @Column({ name: 'resource_id', type: 'text' })
+  resourceId!: string;
+
+  @Column({ name: 'resource_type' })
+  resourceType!: string;
+
+  @Column({ name: 'resource_label', nullable: true, type: 'text' })
+  resourceLabel?: string | null;
+
+  @Column({ name: 'operation_id' })
+  operationId!: string;
+
+  @Column({ name: 'operation_type' })
+  operationType!: string;
+
+  @Column({ name: 'operation_status' })
+  operationStatus!: 'UNSPECIFIED' | 'SUCCEEDED' | 'FAILED';
+
+  @Column({ name: 'actor_id' })
+  actorId!: string;
+
+  @Column({ name: 'actor_type' })
+  actorType!: string;
+
+  @Column({ name: 'actor_label', nullable: true, type: 'text' })
+  actorLabel?: string | null;
+
+  @Column({ name: 'actor_ip', nullable: true, type: 'text' })
+  actorIp?: string | null;
+
+  @Column({ name: 'actor_agent', nullable: true, type: 'text' })
+  actorAgent?: string | null;
+
+  @Column({ name: 'request_id', nullable: true, type: 'text' })
+  requestId?: string | null;
+
+  @Column({ name: 'request_method', nullable: true, type: 'text' })
+  requestMethod?: string | null;
+
+  @Column({ name: 'request_path', nullable: true, type: 'text' })
+  requestPath?: string | null;
+
+  @JsonColumn({ name: 'data_before', nullable: true })
+  dataBefore?: unknown;
+
+  @JsonColumn({ name: 'data_after', nullable: true })
+  dataAfter?: unknown;
+
+  @JsonColumn({ name: 'data_diff', nullable: true })
+  dataDiff?: unknown;
+
+  @JsonColumn({ nullable: true })
+  raw?: unknown;
+}

package/src/audit/exporters/audit-backend.factory.ts

@@ -0,0 +1,74 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import {
+  AuditlogClickHouseExporter,
+  AuditlogOltpGrpcExporter,
+  AuditlogOltpHttpExporter,
+  IAuditLogExporter,
+} from 'nestjs-auditlog';
+
+import { config } from '@/config';
+import { LoggerService } from '@/logger/logger.service';
+
+import { AuditDatabaseExporter } from './audit-database.exporter';
+import { AuditNoopExporter } from './audit-noop.exporter';
+import { AuditSafeExporter } from './audit-safe.exporter';
+
+@Injectable()
+export class AuditBackendFactory {
+  constructor(
+    private readonly databaseExporter: AuditDatabaseExporter,
+    private readonly logger: LoggerService,
+  ) {}
+
+  create(): IAuditLogExporter {
+    const exporter = config.audit.enabled
+      ? this.createConfiguredExporter()
+      : new AuditNoopExporter();
+
+    return new AuditSafeExporter(
+      exporter,
+      config.audit.failClosed,
+      this.logger,
+    );
+  }
+
+  private createConfiguredExporter(): IAuditLogExporter {
+    const { audit } = config;
+
+    switch (audit.backend) {
+      case 'database':
+        return this.databaseExporter;
+      case 'opentelemetry-http':
+        return new AuditlogOltpHttpExporter(
+          audit.serviceName,
+          audit.serviceNamespace,
+          audit.opentelemetry,
+          audit.serviceEnvironmentName,
+        );
+      case 'opentelemetry-grpc':
+        return new AuditlogOltpGrpcExporter(
+          audit.serviceName,
+          audit.serviceNamespace,
+          audit.opentelemetry,
+          audit.serviceEnvironmentName,
+        );
+      case 'clickhouse':
+        return new AuditlogClickHouseExporter({
+          serviceName: audit.serviceName,
+          serviceNamespace: audit.serviceNamespace,
+          serviceEnvironmentName: audit.serviceEnvironmentName,
+          clickHouseUrl: audit.clickhouse.url,
+          databaseName: audit.clickhouse.databaseName,
+          logExpired: audit.clickhouse.logExpired,
+        });
+      default:
+        throw new Error(`Unsupported audit log backend: ${audit.backend}`);
+    }
+  }
+}

package/src/audit/exporters/audit-database.exporter.ts

@@ -0,0 +1,93 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { IAuditLog, IAuditLogExporter } from 'nestjs-auditlog';
+import { DataSource } from 'typeorm';
+
+import { AuditLogOrmEntity } from '../entities/audit-log.entity';
+import { AuditContextService } from '../services/audit-context.service';
+
+const normalizeAuditValue = (
+  value: string | string[] | undefined,
+  fallback: string,
+): string => {
+  if (Array.isArray(value)) {
+    return value.join(',');
+  }
+
+  return value ?? fallback;
+};
+const normalizeAuditLabel = (value: unknown): string | null => {
+  if (Array.isArray(value)) {
+    return value.join(',');
+  }
+
+  return typeof value === 'string' && value.length > 0 ? value : null;
+};
+
+@Injectable()
+export class AuditDatabaseExporter implements IAuditLogExporter {
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly auditContext: AuditContextService,
+  ) {}
+
+  async startup(): Promise<void> {
+    return;
+  }
+
+  async shutdown(): Promise<void> {
+    return;
+  }
+
+  async sendAuditLog(log: IAuditLog): Promise<void> {
+    const context = this.auditContext.getContext();
+    const repository = this.dataSource.getRepository(AuditLogOrmEntity);
+    const actorLabel =
+      normalizeAuditLabel((log.actor as { label?: unknown }).label) ??
+      context.actorLabel ??
+      null;
+    const resourceType = log.resource.type || 'unknown';
+    const resourceLabel =
+      normalizeAuditLabel((log.resource as { label?: unknown }).label) ??
+      (resourceType === 'Auth' ? actorLabel : null);
+    const record = repository.create({
+      resourceId: normalizeAuditValue(log.resource.id, 'unknown'),
+      resourceType,
+      resourceLabel,
+      operationId: normalizeAuditValue(log.operation.id, 'unknown'),
+      operationType: log.operation.type || 'unknown',
+      operationStatus: log.operation.status ?? 'UNSPECIFIED',
+      actorId: normalizeAuditValue(log.actor.id, context.actorId ?? 'system'),
+      actorType: normalizeAuditValue(
+        log.actor.type as unknown as string | string[] | undefined,
+        context.actorType ?? 'system',
+      ),
+      actorLabel,
+      actorIp: log.actor.ip ?? context.ip ?? null,
+      actorAgent: log.actor.agent ?? context.userAgent ?? null,
+      requestId: context.requestId ?? null,
+      requestMethod: context.method ?? null,
+      requestPath: context.path ?? null,
+      dataBefore: log.data_diff?.before ?? null,
+      dataAfter: log.data_diff?.after ?? null,
+      dataDiff: log.data_diff?.diff ?? null,
+      raw: log,
+    });
+
+    await repository.save(record);
+  }
+
+  customLoggerBodyTransformation(log: IAuditLog): string {
+    return JSON.stringify(log);
+  }
+
+  clone(): IAuditLogExporter {
+    return this;
+  }
+}

package/src/audit/exporters/audit-noop.exporter.ts

@@ -0,0 +1,29 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { IAuditLog, IAuditLogExporter } from 'nestjs-auditlog';
+
+export class AuditNoopExporter implements IAuditLogExporter {
+  async startup(): Promise<void> {
+    return;
+  }
+
+  async shutdown(): Promise<void> {
+    return;
+  }
+
+  async sendAuditLog(_log: IAuditLog): Promise<void> {
+    return;
+  }
+
+  customLoggerBodyTransformation(log: IAuditLog): string {
+    return JSON.stringify(log);
+  }
+
+  clone(): IAuditLogExporter {
+    return this;
+  }
+}

package/src/audit/exporters/audit-safe.exporter.ts

@@ -0,0 +1,53 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { IAuditLog, IAuditLogExporter } from 'nestjs-auditlog';
+
+import { LoggerService } from '@/logger/logger.service';
+
+export class AuditSafeExporter implements IAuditLogExporter {
+  constructor(
+    private readonly delegate: IAuditLogExporter,
+    private readonly failClosed: boolean,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async startup(): Promise<void> {
+    await this.runSafely(() => this.delegate.startup());
+  }
+
+  async shutdown(): Promise<void> {
+    await this.runSafely(() => this.delegate.shutdown());
+  }
+
+  async sendAuditLog(log: IAuditLog): Promise<void> {
+    await this.runSafely(() => this.delegate.sendAuditLog(log));
+  }
+
+  customLoggerBodyTransformation(log: IAuditLog): string {
+    return this.delegate.customLoggerBodyTransformation(log);
+  }
+
+  clone(): IAuditLogExporter {
+    return new AuditSafeExporter(
+      this.delegate.clone(),
+      this.failClosed,
+      this.logger,
+    );
+  }
+
+  private async runSafely(action: () => Promise<void>): Promise<void> {
+    try {
+      await action();
+    } catch (error) {
+      if (this.failClosed) {
+        throw error;
+      }
+
+      this.logger.warn('Audit log export failed', error);
+    }
+  }
+}

package/src/audit/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './audit.module';
+
+export * from './controllers/audit-log.controller';
+
+export * from './decorators/audit-log.decorators';
+
+export * from './decorators/audit-label.decorator';
+
+export * from './dto/audit-log.dto';
+
+export * from './entities/audit-log.entity';
+
+export * from './repositories/audit-log.repository';
+
+export * from './services/audit-context.service';
+
+export * from './services/audit-log-record.service';

package/src/audit/interceptors/audit-context.interceptor.ts

@@ -0,0 +1,30 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { Observable } from 'rxjs';
+
+import { AuditContextService } from '../services/audit-context.service';
+
+@Injectable()
+export class AuditContextInterceptor implements NestInterceptor {
+  constructor(private readonly auditContext: AuditContextService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    if (context.getType() === 'http') {
+      const request = context.switchToHttp().getRequest<Request>();
+      this.auditContext.setFromRequest(request);
+    }
+
+    return next.handle();
+  }
+}

package/src/audit/repositories/audit-log.repository.ts

@@ -0,0 +1,23 @@
+/*
+ * 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 { AuditLogOrmEntity } from '../entities/audit-log.entity';
+
+@Injectable()
+export class AuditLogRepository extends BaseOrmRepository<AuditLogOrmEntity> {
+  constructor(
+    @InjectRepository(AuditLogOrmEntity)
+    repository: Repository<AuditLogOrmEntity>,
+  ) {
+    super(repository, []);
+  }
+}