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

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, []);
+  }
+}

package/src/audit/services/audit-context.service.ts

@@ -0,0 +1,123 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { User } from '@hexabot-ai/types';
+import { Injectable } from '@nestjs/common';
+import { Request } from 'express';
+import { ClsService } from 'nestjs-cls';
+
+import {
+  AuditClsStore,
+  AuditRequestContext,
+} from '../types/audit-context.type';
+import {
+  resolveRequestId,
+  resolveRequestIp,
+  resolveRequestPath,
+  resolveUserAgent,
+} from '../utils/request-context';
+
+@Injectable()
+export class AuditContextService {
+  constructor(private readonly cls: ClsService<AuditClsStore>) {}
+
+  setContext(context: AuditRequestContext): void {
+    if (!this.cls.isActive()) {
+      return;
+    }
+
+    this.cls.set('audit', {
+      ...(this.cls.get('audit') ?? {}),
+      ...context,
+    });
+  }
+
+  setFromRequest(req: Request): void {
+    const user = req.user as
+      | (User & { id?: string; roles?: string[] })
+      | undefined;
+    const sessionUser = req.session?.passport?.user;
+    const actorId = user?.id ?? sessionUser?.id;
+    const actorType = Array.isArray(user?.roles)
+      ? user.roles.join(',')
+      : user
+        ? 'user'
+        : undefined;
+    const actorLabel = this.resolveActorLabel(user, sessionUser, actorId);
+
+    this.setContext({
+      requestId: resolveRequestId(req),
+      actorId,
+      actorType,
+      actorLabel,
+      ip: resolveRequestIp(req),
+      userAgent: resolveUserAgent(req),
+      method: req.method,
+      path: resolveRequestPath(req),
+    });
+  }
+
+  private resolveActorLabel(
+    user:
+      | (User & {
+          id?: string;
+          username?: string;
+          firstName?: string;
+          lastName?: string;
+        })
+      | undefined,
+    sessionUser:
+      | {
+          id?: string;
+          first_name?: string;
+          last_name?: string;
+        }
+      | undefined,
+    actorId?: string,
+  ): string | undefined {
+    const username = this.normalizeLabelPart(user?.username);
+    const fullName = this.joinName(
+      user?.firstName ?? sessionUser?.first_name,
+      user?.lastName ?? sessionUser?.last_name,
+    );
+
+    if (fullName && username) {
+      return `${fullName} (${username})`;
+    }
+
+    return username ?? fullName ?? actorId;
+  }
+
+  private joinName(
+    firstName?: string | null,
+    lastName?: string | null,
+  ): string | undefined {
+    const value = [firstName, lastName]
+      .map((part) => this.normalizeLabelPart(part))
+      .filter(Boolean)
+      .join(' ');
+
+    return value.length > 0 ? value : undefined;
+  }
+
+  private normalizeLabelPart(value?: string | null): string | undefined {
+    if (typeof value !== 'string') {
+      return undefined;
+    }
+
+    const trimmed = value.trim();
+
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  getContext(): AuditRequestContext {
+    if (!this.cls.isActive()) {
+      return {};
+    }
+
+    return this.cls.get('audit') ?? {};
+  }
+}

package/src/audit/services/audit-log-record.service.ts

@@ -0,0 +1,97 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { AuditLog } from '@hexabot-ai/types';
+import { Injectable, ServiceUnavailableException } from '@nestjs/common';
+import {
+  And,
+  Equal,
+  FindManyOptions,
+  FindOperator,
+  FindOptionsWhere,
+  In,
+  Not,
+} from 'typeorm';
+
+import { config } from '@/config';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { AuditLogOrmEntity } from '../entities/audit-log.entity';
+import { AuditLogRepository } from '../repositories/audit-log.repository';
+
+const HIDDEN_AUDIT_RESOURCE_TYPES = ['AuditLog', 'Stats'];
+
+@Injectable()
+export class AuditLogRecordService extends BaseOrmService<AuditLogOrmEntity> {
+  constructor(readonly repository: AuditLogRepository) {
+    super(repository);
+  }
+
+  assertReadableBackend(): void {
+    if (config.audit.backend !== 'database') {
+      throw new ServiceUnavailableException(
+        'Audit log records are not stored locally for the configured backend.',
+      );
+    }
+  }
+
+  override async find(
+    options: FindManyOptions<AuditLogOrmEntity> = {},
+  ): Promise<AuditLog[]> {
+    return await super.find(this.applyVisibilityFilter(options));
+  }
+
+  override async count(
+    options: FindManyOptions<AuditLogOrmEntity> = {},
+  ): Promise<number> {
+    return await super.count(this.applyVisibilityFilter(options));
+  }
+
+  private applyVisibilityFilter(
+    options: FindManyOptions<AuditLogOrmEntity>,
+  ): FindManyOptions<AuditLogOrmEntity> {
+    return {
+      ...options,
+      where: this.applyVisibilityWhere(options.where),
+    };
+  }
+
+  private applyVisibilityWhere(
+    where?: FindManyOptions<AuditLogOrmEntity>['where'],
+  ): FindManyOptions<AuditLogOrmEntity>['where'] {
+    if (Array.isArray(where)) {
+      return where.map((clause) => this.applyVisibilityClause(clause));
+    }
+
+    return this.applyVisibilityClause(where ?? {});
+  }
+
+  private applyVisibilityClause(
+    clause: FindOptionsWhere<AuditLogOrmEntity>,
+  ): FindOptionsWhere<AuditLogOrmEntity> {
+    return {
+      ...clause,
+      resourceType: this.mergeResourceTypeVisibility(clause.resourceType),
+    };
+  }
+
+  private mergeResourceTypeVisibility(
+    resourceType?: FindOptionsWhere<AuditLogOrmEntity>['resourceType'],
+  ) {
+    const visibleResourceTypes = Not(In(HIDDEN_AUDIT_RESOURCE_TYPES));
+
+    if (resourceType === undefined) {
+      return visibleResourceTypes;
+    }
+
+    const existingFilter =
+      resourceType instanceof FindOperator
+        ? resourceType
+        : Equal(resourceType as string);
+
+    return And(existingFilter, visibleResourceTypes);
+  }
+}

package/src/audit/subscribers/audit-log.subscriber.ts

@@ -0,0 +1,322 @@
+/*
+ * 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 {
+  AuditLogService as SdkAuditLogService,
+  IAuditLog,
+} from 'nestjs-auditlog';
+import {
+  DataSource,
+  EntityMetadata,
+  EntitySubscriberInterface,
+  EventSubscriber,
+  InsertEvent,
+  ObjectLiteral,
+  RemoveEvent,
+  UpdateEvent,
+} from 'typeorm';
+
+import { config } from '@/config';
+
+import { getAuditLabelProperty } from '../decorators/audit-label.decorator';
+import { AuditContextService } from '../services/audit-context.service';
+
+type AuditOperation = 'Create' | 'Update' | 'Remove';
+type LabeledAuditLog = IAuditLog & {
+  resource: IAuditLog['resource'] & { label?: string };
+  actor: IAuditLog['actor'] & { label?: string };
+};
+
+const INTERNAL_TABLES = new Set([
+  'audit_logs',
+  'migrations',
+  'sessions',
+  'stats',
+]);
+const UNKNOWN_VALUE = 'unknown';
+
+@Injectable()
+@EventSubscriber()
+export class AuditLogSubscriber implements EntitySubscriberInterface {
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly auditLogService: SdkAuditLogService,
+    private readonly auditContext: AuditContextService,
+  ) {
+    this.registerAsSubscriber();
+  }
+
+  private registerAsSubscriber(): void {
+    const alreadyRegistered = this.dataSource.subscribers.some(
+      (subscriber) => subscriber === this,
+    );
+    if (!alreadyRegistered) {
+      this.dataSource.subscribers.push(this);
+    }
+  }
+
+  private shouldSkip(metadata: EntityMetadata): boolean {
+    return !config.audit.enabled || INTERNAL_TABLES.has(metadata.tableName);
+  }
+
+  async afterInsert(event: InsertEvent<ObjectLiteral>): Promise<void> {
+    await this.record('Create', event, undefined, event.entity);
+  }
+
+  async afterUpdate(event: UpdateEvent<ObjectLiteral>): Promise<void> {
+    await this.record(
+      'Update',
+      event,
+      event.databaseEntity,
+      event.entity as ObjectLiteral | undefined,
+    );
+  }
+
+  async afterRemove(event: RemoveEvent<ObjectLiteral>): Promise<void> {
+    await this.record(
+      'Remove',
+      event,
+      event.databaseEntity ?? event.entity,
+      undefined,
+    );
+  }
+
+  private async record(
+    operation: AuditOperation,
+    event:
+      | InsertEvent<ObjectLiteral>
+      | UpdateEvent<ObjectLiteral>
+      | RemoveEvent<ObjectLiteral>,
+    before?: ObjectLiteral,
+    after?: ObjectLiteral,
+  ): Promise<void> {
+    if (this.shouldSkip(event.metadata)) {
+      return;
+    }
+
+    const beforeData = this.toAuditData(event.metadata, before);
+    const afterData = this.toAuditData(event.metadata, after);
+    const resourceLabel =
+      this.getResourceLabel(event.metadata, afterData) ??
+      this.getResourceLabel(event.metadata, beforeData);
+    const auditLog = this.buildAuditLog(
+      operation,
+      event,
+      beforeData,
+      afterData,
+      resourceLabel,
+    );
+
+    await this.auditLogService.sendAuditLog(auditLog);
+  }
+
+  private buildAuditLog(
+    operation: AuditOperation,
+    event:
+      | InsertEvent<ObjectLiteral>
+      | UpdateEvent<ObjectLiteral>
+      | RemoveEvent<ObjectLiteral>,
+    before?: Record<string, unknown>,
+    after?: Record<string, unknown>,
+    resourceLabel?: string,
+  ): IAuditLog {
+    const context = this.auditContext.getContext();
+    const resourceId =
+      this.getResourceId(event, before) ?? this.getResourceId(event, after);
+    const entityName = this.getEntityName(event.metadata);
+    const auditLog: LabeledAuditLog = {
+      resource: {
+        id: resourceId ?? UNKNOWN_VALUE,
+        type: entityName,
+        ...(resourceLabel ? { label: resourceLabel } : {}),
+      },
+      operation: {
+        id: `typeorm.${entityName}.${operation.toLowerCase()}`,
+        type: operation,
+        status: 'SUCCEEDED',
+      },
+      actor: {
+        id: context.actorId ?? 'system',
+        type: context.actorType ?? 'system',
+        ...(context.actorLabel ? { label: context.actorLabel } : {}),
+        ip: context.ip,
+        agent: context.userAgent,
+      },
+      data_diff: {
+        before: before ?? null,
+        after: after ?? null,
+        diff: this.diff(before, after),
+      },
+    };
+
+    return auditLog;
+  }
+
+  private getEntityName(metadata: EntityMetadata): string {
+    return (metadata.targetName || metadata.name || metadata.tableName).replace(
+      /OrmEntity$/,
+      '',
+    );
+  }
+
+  private getResourceId(
+    event:
+      | InsertEvent<ObjectLiteral>
+      | UpdateEvent<ObjectLiteral>
+      | RemoveEvent<ObjectLiteral>,
+    data?: Record<string, unknown>,
+  ): string | undefined {
+    const eventId = 'entityId' in event ? event.entityId : undefined;
+
+    if (typeof eventId === 'string') {
+      return eventId;
+    }
+
+    if (eventId && typeof eventId === 'object') {
+      return JSON.stringify(eventId);
+    }
+
+    const primaryColumn = event.metadata.primaryColumns[0]?.propertyName;
+    const primaryValue = primaryColumn ? data?.[primaryColumn] : undefined;
+
+    return primaryValue === undefined ? undefined : String(primaryValue);
+  }
+
+  private getResourceLabel(
+    metadata: EntityMetadata,
+    data?: Record<string, unknown>,
+  ): string | undefined {
+    const labelProperty = getAuditLabelProperty(metadata);
+    if (!labelProperty) {
+      return undefined;
+    }
+
+    return this.toLabel(data?.[labelProperty]);
+  }
+
+  private toLabel(value: unknown): string | undefined {
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+
+      return trimmed.length > 0 ? trimmed : undefined;
+    }
+
+    if (
+      typeof value === 'number' ||
+      typeof value === 'boolean' ||
+      typeof value === 'bigint'
+    ) {
+      return String(value);
+    }
+
+    return undefined;
+  }
+
+  private toAuditData(
+    metadata: EntityMetadata,
+    entity?: ObjectLiteral,
+  ): Record<string, unknown> | undefined {
+    if (!entity) {
+      return undefined;
+    }
+
+    const result: Record<string, unknown> = {};
+
+    for (const column of metadata.columns) {
+      const value = column.getEntityValue(entity);
+      if (value !== undefined) {
+        result[column.propertyName] = this.normalizeValue(
+          column.propertyName,
+          value,
+        );
+      }
+    }
+
+    for (const relation of metadata.relations) {
+      const value = relation.getEntityValue(entity);
+      if (value !== undefined) {
+        result[relation.propertyName] = this.normalizeValue(
+          relation.propertyName,
+          value,
+        );
+      }
+    }
+
+    return this.cloneJson(result);
+  }
+
+  private normalizeValue(field: string, value: unknown): unknown {
+    if (this.isMaskedField(field)) {
+      return '[REDACTED]';
+    }
+
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((entry) => this.normalizeValue(field, entry));
+    }
+
+    if (value && typeof value === 'object') {
+      const record = value as Record<string, unknown>;
+      if (typeof record.id === 'string') {
+        return record.id;
+      }
+
+      return Object.fromEntries(
+        Object.entries(record).map(([key, entry]) => [
+          key,
+          this.normalizeValue(key, entry),
+        ]),
+      );
+    }
+
+    return value;
+  }
+
+  private isMaskedField(field: string): boolean {
+    const normalized = field.toLowerCase();
+
+    return config.audit.maskFields.some(
+      (maskedField) => maskedField.toLowerCase() === normalized,
+    );
+  }
+
+  private diff(
+    before?: Record<string, unknown>,
+    after?: Record<string, unknown>,
+  ): Record<string, { before: unknown; after: unknown }> | null {
+    if (!before && !after) {
+      return null;
+    }
+
+    const keys = new Set([
+      ...Object.keys(before ?? {}),
+      ...Object.keys(after ?? {}),
+    ]);
+    const changes: Record<string, { before: unknown; after: unknown }> = {};
+
+    for (const key of keys) {
+      const previousValue = before?.[key];
+      const nextValue = after?.[key];
+      if (JSON.stringify(previousValue) !== JSON.stringify(nextValue)) {
+        changes[key] = {
+          before: previousValue ?? null,
+          after: nextValue ?? null,
+        };
+      }
+    }
+
+    return Object.keys(changes).length ? changes : null;
+  }
+
+  private cloneJson(value: Record<string, unknown>): Record<string, unknown> {
+    return JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
+  }
+}

package/src/audit/types/audit-context.type.ts

@@ -0,0 +1,20 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export type AuditRequestContext = {
+  requestId?: string;
+  actorId?: string;
+  actorType?: string;
+  actorLabel?: string;
+  ip?: string;
+  userAgent?: string;
+  method?: string;
+  path?: string;
+};
+
+export type AuditClsStore = {
+  audit?: AuditRequestContext;
+};

package/src/audit/utils/request-context.ts

@@ -0,0 +1,44 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { randomUUID } from 'crypto';
+
+import { Request } from 'express';
+
+const getHeaderValue = (
+  value: string | string[] | undefined,
+): string | undefined => {
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+
+  return value;
+};
+
+export const resolveRequestId = (req: Request): string => {
+  return (
+    getHeaderValue(req.headers['x-request-id']) ??
+    getHeaderValue(req.headers['x-correlation-id']) ??
+    randomUUID()
+  );
+};
+
+export const resolveRequestIp = (req: Request): string | undefined => {
+  const forwardedFor = getHeaderValue(req.headers['x-forwarded-for']);
+  if (forwardedFor) {
+    return forwardedFor.split(',')[0].trim();
+  }
+
+  return req.ip ?? req.socket?.remoteAddress;
+};
+
+export const resolveUserAgent = (req: Request): string | undefined => {
+  return getHeaderValue(req.headers['user-agent']);
+};
+
+export const resolveRequestPath = (req: Request): string | undefined => {
+  return req.originalUrl ?? req.url;
+};