@nestarc/audit-log

Audit logging module for NestJS with automatic Prisma change tracking and append-only PostgreSQL storage.

Requirements

• NestJS 10 or 11
• Prisma 5 or 6
• PostgreSQL

Features

• Automatic CUD tracking via Prisma $extends — create, update, delete, upsert, and batch operations
• Caller transaction aware — automatic tracking participates in caller's $transaction; audit insert is best-effort
• Before/after diffs with deep comparison for JSON fields
• Sensitive field masking — configurable [REDACTED] replacement
• Manual logging API — AuditService.log() for business events (with optional transaction support)
• Query API — AuditService.query() with wildcard filters, pagination
• Decorators — @NoAudit() / @AuditAction() on handlers or controllers
• Custom primary keys — configurable per-model PK field (defaults to id)
• Multi-tenant — optional @nestarc/tenancy integration with fail-closed mode
• Append-only — ships PostgreSQL rules to prevent UPDATE/DELETE on audit records

Quick Start

1. Install

npm install @nestarc/audit-log

2. Create the audit_logs table

import { applyAuditTableSchema } from '@nestarc/audit-log';

// In a migration or setup script:
await applyAuditTableSchema(prisma);

Or use getAuditTableSQL() to get the raw SQL string for your migration tool.

3. Complete NestJS Integration

The library requires two Prisma clients with distinct roles:

• Base client — used by AuditService for writing/querying audit logs
• Extended client — used by your application code for business writes (CUD tracking fires here)

// prisma.service.ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';
import { createAuditExtension } from '@nestarc/audit-log';

const auditExtensionOptions = {
  trackedModels: ['User', 'Invoice', 'Document'],
  sensitiveFields: ['password', 'ssn'],
  // primaryKey: { Order: 'orderNumber' }, // for non-id PKs
};

@Injectable()
export class PrismaService implements OnModuleInit {
  /** Base client — for audit storage (log/query) */
  readonly base = new PrismaClient();

  /** Extended client — use this for all application queries */
  readonly client = this.base.$extends(
    createAuditExtension(auditExtensionOptions),
  );

  async onModuleInit() {
    await this.base.$connect();
  }
}

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

@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

// app.module.ts
import { Module } from '@nestjs/common';
import { AuditLogModule } from '@nestarc/audit-log';
import { PrismaModule } from './prisma.module';
import { PrismaService } from './prisma.service';

@Module({
  imports: [
    PrismaModule,
    AuditLogModule.forRootAsync({
      inject: [PrismaService],
      useFactory: (prisma: PrismaService) => ({
        prisma: prisma.base,
        actorExtractor: (req) => ({
          id: req.user?.id ?? null,
          type: req.user ? 'user' : 'system',
          ip: req.ip,
        }),
        // tenantRequired: true, // fail-closed for multi-tenant deployments
      }),
    }),
  ],
})
export class AppModule {}

// user.service.ts — use prisma.client (extended) for all business writes
@Injectable()
export class UserService {
  constructor(private readonly prisma: PrismaService) {}

  async createUser(data: CreateUserDto) {
    // Automatic audit tracking fires because we use the extended client
    return this.prisma.client.user.create({ data });
  }
}

API

AuditLogModule.forRoot(options) / forRootAsync(options)

Option	Type	Default	Description
prisma	PrismaClient	required	Base Prisma client for audit storage
actorExtractor	(req) => AuditActor	required	Extracts actor from HTTP request
tenantRequired	boolean	false	When true, throws if tenant context is unavailable

AuditService

// Manual logging
await auditService.log({
  action: 'invoice.approved',
  targetId: 'inv-123',
  targetType: 'Invoice',
  metadata: { amount: 5000, currency: 'USD' },
});

// Manual logging inside a transaction
await prisma.base.$transaction(async (tx) => {
  await tx.invoice.update({ where: { id }, data: { status: 'approved' } });
  await auditService.log({ action: 'invoice.approved', targetId: id }, tx);
  // Both roll back together if anything fails
});

// Querying
const result = await auditService.query({
  actorId: 'user-123',
  action: 'invoice.*',     // wildcard support
  targetType: 'Invoice',
  from: new Date('2026-01-01'),
  to: new Date('2026-04-01'),
  limit: 50,
  offset: 0,
});
// -> { entries: AuditEntry[], total: number }

Decorators

Apply to individual handlers or entire controllers:

@NoAudit()      // Skip audit tracking for this route or controller
@AuditAction('user.role.changed')  // Override auto-generated action name

createAuditExtension(options)

Option	Type	Default	Description
trackedModels	string[]	—	Whitelist of Prisma model names to track
ignoredModels	string[]	—	Blacklist (used when trackedModels is not set)
sensitiveFields	string[]	[]	Fields to mask as [REDACTED] in diffs
primaryKey	Record<string, string>	{ *: 'id' }	Map of model name to primary key field name

Schema Utilities

Function	Description
getAuditTableSQL()	Returns raw SQL string for creating audit_logs table + rules + indexes
getAuditTableStatements()	Returns SQL split into individual executable statements
applyAuditTableSchema(prisma)	Executes the schema SQL statement by statement via Prisma

Transaction Model

Path	Caller tx participation	Audit insert
Automatic tracking (extension)	Yes — query(args) joins caller's $transaction	Best-effort — runs after business write, warns on failure
Manual logging (log(input, tx))	Yes — when tx provided	Participates in provided transaction
Manual logging (log(input))	No	Independent write via base client

The automatic extension uses Prisma's query(args) callback, which preserves the caller's transaction context. The audit insert runs separately via the base client and does not block or fail the business operation. If audit insert fails, a warning is logged.

Multi-Tenancy

If @nestarc/tenancy is installed, tenant_id is automatically included in all audit records and query filters.

Scenario	Behavior
Not installed	tenant_id is null, library works normally
Installed, context available	tenant_id auto-injected
Installed, context fails	Warning logged, tenant_id falls back to null
tenantRequired: true + context fails	log() and query() throw an error

Development

Prerequisites

• Node.js 18+
• Docker (for E2E tests)

Setup

npm install
npm run build

Run tests

# Unit tests
npm test

# E2E tests (starts Docker PostgreSQL automatically)
npm run test:e2e:full

# Cleanup
npm run test:e2e:teardown

License

MIT