@soamee/audit-log

Registro de auditoría para NestJS y Prisma. Incluye consultas REST paginadas, el helper withAudit, escritura directa con logFromService, el decorador @Audited y retención configurable.

Instalación y modelo Prisma

npm install @soamee/audit-log

El paquete declara como peer dependencies NestJS, Prisma, Swagger, class-validator, class-transformer y reflect-metadata; deben estar instaladas en la aplicación. @nestjs/schedule es opcional y sólo hace falta para la retención automática (véase Retención).

1. Copia prisma-snippet.prisma dentro de tu prisma/schema.prisma. Añade también la relación inversa al modelo de usuario:

   model User {
     id        String     @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
     auditLogs AuditLog[]
   }

   El snippet usa PostgreSQL (gen_random_uuid() y @db.Uuid). Adapta los IDs al proveedor de tu base de datos y añade al enum AuditOperation todas las operaciones que vaya a escribir la aplicación.

2. Genera y aplica una migración, y regenera Prisma Client:

   npx prisma migrate dev --name add_audit_log
   npx prisma generate

   En despliegues aplica la migración ya versionada con npx prisma migrate deploy, no con migrate dev.

Configuración de NestJS

Importa la integración desde el subpath público @soamee/audit-log/nestjs. El módulo necesita un proveedor visible con el token exacto DATABASE_SERVICE, cuyo valor exponga el Prisma Client (en particular auditLog.create, count, findMany y deleteMany). Una forma inequívoca es exportar el alias desde el módulo que posee el cliente:

// database.module.ts
import { Global, Module } from '@nestjs/common';

@Global()
@Module({
  providers: [
    DatabaseService,
    { provide: 'DATABASE_SERVICE', useExisting: DatabaseService },
  ],
  exports: [DatabaseService, 'DATABASE_SERVICE'],
})
export class DatabaseModule {}

// app.module.ts
import { Module } from '@nestjs/common';
import { AuditLogModule } from '@soamee/audit-log/nestjs';

@Module({
  imports: [
    DatabaseModule,
    AuditLogModule.forRoot({
      allowedEntities: ['User', 'Invoice'],
      retentionDays: 90,
    }),
  ],
})
export class AppModule {}

AuditLogModule es global, exporta AuditLogService, registra el interceptor global y, salvo que se desactive, publica el controlador en audit-logs.

Escribir auditorías

Los helpers se inyectan desde la misma integración:

import { Injectable } from '@nestjs/common';
import { AuditLogService } from '@soamee/audit-log/nestjs';

@Injectable()
export class UsersService {
  constructor(
    private readonly audit: AuditLogService,
    private readonly db: DatabaseService,
  ) {}

  update(userId: string, targetId: string, dto: UpdateUserDto) {
    return this.audit.withAudit({
      userId,
      entity: 'User',
      entityId: targetId,
      operation: 'UPDATE',
      payload: dto,
      metadata: { source: 'admin' },
      message: 'Usuario actualizado',
      operationFn: () => this.db.user.update({
        where: { id: targetId },
        data: dto,
      }),
    });
  }

  async recordImport(actorId: string) {
    await this.audit.logFromService({
      userId: actorId,
      entity: 'User',
      operation: 'CREATE',
      status: 'SUCCESS',
      metadata: { source: 'csv-import' },
      message: 'Importación terminada',
    });
  }
}

En controladores, @Audited obtiene por defecto el actor de req.user.id, el ID de req.params.id, el cuerpo como payload, y captura IP, user-agent, método y ruta:

import { Audited } from '@soamee/audit-log/nestjs';

@Audited({
  entity: 'Invoice',
  operation: 'UPDATE',
  message: 'Factura aprobada',
  entityId: (req) => req.params.invoiceId,
  getUserId: (req) => req.user.subject,
  getMetadata: (req) => ({ requestId: req.headers['x-request-id'] }),
})
@Patch(':invoiceId/approve')
approve() { /* ... */ }

Si no hay ID de usuario, el interceptor deja ejecutar el endpoint pero no crea una auditoría. @Audited registra el resultado al terminar la respuesta; para control estricto del momento de escritura usa withAudit o logFromService.

Opciones de AuditLogModuleOptions

| Opción | Tipo | Predeterminado | Descripción | | --- | --- | --- | --- | | allowedEntities | string[] | Obligatoria, sin valor implícito | Lista blanca de entidades admitidas por las consultas. | | permissionCheck | (user: any) => boolean | user?.permissions?.canSeeLogs === true | Autoriza el acceso a cualquiera de los endpoints de lectura. | | userSelect | { [campo: string]: boolean } | { id: true, email: true, role: true } | Selección Prisma de la relación user devuelta en consultas. | | enableController | boolean | true | Registra o no el controlador REST incluido. | | enableSorting | boolean | true | Si es false, se ignora sort y se usa el orden predeterminado. | | sortableFields | string[] | ['createdAt', 'entity', 'entityId', 'operation', 'status'] | Lista blanca de campos ordenables; un campo ajeno produce HTTP 400. | | nullableUserId | boolean | false | Documenta que el modelo acepta acciones de sistema; el esquema Prisma debe adaptarse también. | | retentionDays | number | undefined (desactivada; 0 también la desactiva) | Elimina registros anteriores a ese número de días. | | retentionCron | string | '0 3 * * *' | Expresión cron del proceso de retención. Sólo se usa si retentionDays > 0. | | prismaModelName | string | 'auditLog' | Propiedad del cliente Prisma que representa el modelo. | | routePrefix | string | 'audit-logs' | Ruta del controlador, por ejemplo api/audit-logs. | | controllerVersion | string | sin versión | Metadato de versión NestJS, por ejemplo '1'. | | responseEnhancer | (result, moduleRef) => Promise<any> | sin transformación | Hook asíncrono para añadir filtros u otros datos a cada respuesta del controlador. |

Ejemplo de permisos y respuesta personalizados:

AuditLogModule.forRoot({
  allowedEntities: ['User', 'Invoice'],
  permissionCheck: (user) => user?.roles?.includes('AUDITOR') === true,
  userSelect: { id: true, displayName: true },
  sortableFields: ['createdAt', 'operation'],
  responseEnhancer: async (result, moduleRef) => ({
    ...result,
    filters: await moduleRef.get(AuditFiltersService).getFilters(),
  }),
})

La función de permisos debe ser síncrona y recibe req.user; si devuelve false, el servicio responde 403. Si necesitas permisos asíncronos o guards específicos, usa enableController: false y crea un controlador propio que llame a AuditLogService (ten en cuenta que sus métodos de lectura vuelven a aplicar permissionCheck).

Consultas, filtros y paginación

El controlador ofrece:

GET /audit-logs
GET /audit-logs/entities/:entity
GET /audit-logs/entities/:entity/:entityId

Parámetros: searchTerm (máximo 200 caracteres), entity, entityId UUID v4, operation, status (SUCCESS, FAIL o UNAUTHORIZED), userId UUID v4, dateFrom/dateTo ISO 8601, page (desde 1, por defecto 1), y take (1–100, por defecto 10). searchTerm busca sin distinguir mayúsculas en entidad, mensaje, error y email; sólo busca entityId cuando el término es un UUID. entity siempre se valida contra allowedEntities.

sort acepta pares campo:dirección separados por comas, por ejemplo ?sort=createdAt:desc,entity:asc. Una dirección distinta de asc se interpreta como desc. Sin sort, el orden es createdAt:desc. La lista blanca se controla con sortableFields; con enableSorting: false, sort se ignora.

La respuesta normal tiene este formato (un responseEnhancer puede ampliarlo):

{
  "data": [{ "id": "…", "entity": "User", "user": { "id": "…" } }],
  "meta": {
    "page": 1,
    "take": 10,
    "itemCount": 23,
    "pageCount": 3,
    "hasPreviousPage": false,
    "hasNextPage": true
  }
}

Seguridad, fallos y consistencia

Datos sensibles: payload, metadata, mensajes, errores y el cuerpo que captura @Audited pueden contener contraseñas, tokens, datos personales o secretos. Redáctalos o selecciona únicamente campos permitidos antes de registrar; limita el acceso, cifra y define una retención acorde a la ley.

withAudit no crea una transacción Prisma que abarque la operación y la auditoría. Primero ejecuta operationFn y luego escribe el éxito: si esa escritura falla, el helper entra en la rama de error, intenta escribir un registro FAIL y finalmente propaga el error de persistencia, aunque la operación de negocio ya podría haberse confirmado. En el camino de error de la operación, un fallo al guardar la auditoría sólo se registra en el logger y se vuelve a lanzar el error original. logFromService sí propaga directamente un fallo de persistencia. @Audited, en cambio, registra el fallo y deja continuar la respuesta/error original. Decide explícitamente si tu política debe ser fail-open o fail-closed; para atomicidad real, implementa ambas escrituras con el mismo cliente de transacción y una estrategia propia.

Retención

Para usar retentionDays, el valor debe ser positivo, el modelo debe exponer createdAt y deleteMany, y la identidad de base de datos necesita permiso de borrado. Instala versiones compatibles de @nestjs/schedule (y su dependencia cron) e importa ScheduleModule.forRoot() una sola vez en la aplicación. Configura y monitoriza el job de limpieza conforme a tu política de conservación y haz copia de seguridad cuando sea obligatorio. Valores 0, negativos o undefined no habilitan la retención.

Resolución de problemas

Los query params fallan o siguen siendo strings (ValidationPipe)

El DTO usa transformación de tipos y validadores. Instala class-transformer y class-validator, y activa transformación global:

app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));

Sin transform: true, page y take pueden no convertirse a número. Revisa también los límites, fechas ISO y que entityId/userId sean UUID v4.

La ruta o la versión no coincide

routePrefix sustituye audit-logs; no incluye automáticamente el prefijo global de app.setGlobalPrefix(). controllerVersion sólo tiene efecto al habilitar el versionado de Nest, por ejemplo app.enableVersioning({ type: VersioningType.URI }). Evita duplicar v1: usa routePrefix: 'audit-logs', controllerVersion: '1' con versionado URI, o una ruta literal como routePrefix: 'v1/audit-logs' sin controllerVersion.

Cannot read properties of undefined al acceder al modelo Prisma

Prisma suele convertir model AuditLog en prisma.auditLog. Si el modelo se llama de otra forma o el servicio lo expone bajo otro nombre, configura prismaModelName con la propiedad exacta y asegúrate de que DATABASE_SERVICE la expone. Regenera el cliente después de cambiar el schema.

La relación user falla o hay acciones sin usuario

Para acciones del sistema cambia en Prisma tanto user a User? como userId a String?, crea y aplica una migración, y configura nullableUserId: true. logFromService acepta entonces userId: null. withAudit y @Audited están orientados a actores autenticados; para acciones sin actor usa logFromService. Ajusta userSelect si tu modelo User no tiene email o role; de lo contrario Prisma rechazará la consulta.

Licencia

MIT