nestjs-audit-trail

A small, storage-agnostic audit trail module for NestJS.

If you need a reliable record of who did what, when, and what changed - without coupling your app to a specific database or ORM - this is for you.

Records are SHA256-hashed and can be chained for tamper-evidence. You bring your own persistence layer.

Install

npm install nestjs-audit-trail

Quick start

1. Implement IAuditStorage (or use an adapter from a separate package).
2. Register the module and the interceptor.
3. Mark handlers with @Audit({ action, entity }).

// app.module.ts
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import {
  AuditTrailModule,
  AuditInterceptor,
  type IAuditStorage,
} from 'nestjs-audit-trail';

const myStorage: IAuditStorage = {
  save: async (record) => {
    // persist to your DB, queue, or object store
  },
  getLastHash: async () => null, // optional, for chain linking
};

@Module({
  imports: [
    AuditTrailModule.forRoot({
      storage: myStorage,
      correlationIdHeader: 'x-correlation-id', // optional
    }),
  ],
  providers: [{ provide: APP_INTERCEPTOR, useClass: AuditInterceptor }],
})
export class AppModule {}

// user.controller.ts
import { Controller, Post, Body } from '@nestjs/common';
import { Audit } from 'nestjs-audit-trail';

@Controller('users')
export class UserController {
  @Post()
  @Audit({ action: 'CREATE', entity: 'User' })
  create(@Body() body: CreateUserDto) {
    return this.userService.create(body);
  }
}

The interceptor reads action and entity from @Audit, and fills actorId (from x-actor-id or request.user.id), correlationId (from the configured header), payloadBefore (request body), and payloadAfter (handler result). Records are hashed and saved via your storage.

Storage interface

All persistence is behind this contract. The core does not implement storage.

import type { AuditRecord, IAuditStorage } from 'nestjs-audit-trail';

const adapter: IAuditStorage = {
  async save(record: AuditRecord): Promise<void> {
    // Persist record (e.g. insert into table, send to queue, write to S3).
  },

  // Optional: return the hash of the last saved record for chain linking.
  async getLastHash(): Promise<string | null> {
    return null;
  },
};

AuditRecord is a plain type: action, entity, actorId, correlationId, payloadBefore, payloadAfter, metadata, hash, createdAt, previousHash?. No ORM decorators; you map it to your schema.

Building custom storage adapters

Adapters live in separate packages (e.g. @nestjs-audit-trail/typeorm, @nestjs-audit-trail/prisma). Your adapter only needs to implement IAuditStorage.

1. Create a new package that depends on nestjs-audit-trail and your persistence layer.
2. Implement IAuditStorage: in save(), map AuditRecord to your model and persist; optionally implement getLastHash() by reading the latest row and returning its hash.
3. Export a ready-to-use storage instance or factory (e.g. a function that takes a data source and returns IAuditStorage).
4. In the app, install the adapter and pass its storage to AuditTrailModule.forRoot({ storage }).

The core stays free of ORM/database imports; only NestJS and Node crypto are used.

Domain examples

Same library, different domains: use @Audit with actions and entities that match your domain. Pass a storage implementation that fits your stack (SQL, NoSQL, queue, object store).

Healthcare (e.g. PHI / HIPAA-style audit)

Audit access and changes to patient and clinical data. Use a storage backend that meets your retention and access rules.

@Controller('patients')
export class PatientController {
  @Get(':id/records')
  @Audit({ action: 'READ', entity: 'PatientRecord' })
  getRecords(@Param('id') id: string) {
    return this.patientService.getRecords(id);
  }

  @Patch(':id')
  @Audit({ action: 'UPDATE', entity: 'Patient' })
  updatePatient(@Param('id') id: string, @Body() dto: UpdatePatientDto) {
    return this.patientService.update(id, dto);
  }

  @Post(':id/prescriptions')
  @Audit({ action: 'CREATE', entity: 'Prescription' })
  createPrescription(
    @Param('id') id: string,
    @Body() dto: CreatePrescriptionDto,
  ) {
    return this.patientService.addPrescription(id, dto);
  }
}

Ecommerce (orders, inventory, payments)

Audit order lifecycle, inventory changes, and payment events for support and disputes.

@Controller('orders')
export class OrderController {
  @Post()
  @Audit({ action: 'CREATE', entity: 'Order' })
  create(@Body() dto: CreateOrderDto) {
    return this.orderService.create(dto);
  }

  @Patch(':id/status')
  @Audit({ action: 'UPDATE', entity: 'Order' })
  updateStatus(@Param('id') id: string, @Body() body: { status: string }) {
    return this.orderService.setStatus(id, body.status);
  }
}

@Controller('inventory')
export class InventoryController {
  @Patch(':sku')
  @Audit({ action: 'UPDATE', entity: 'Inventory' })
  adjust(@Param('sku') sku: string, @Body() dto: AdjustInventoryDto) {
    return this.inventoryService.adjust(sku, dto);
  }
}

Fintech (transactions, KYC, accounts)

Audit transactions, KYC updates, and account changes for regulatory and operational traceability.

@Controller('transactions')
export class TransactionController {
  @Post('transfer')
  @Audit({ action: 'CREATE', entity: 'Transfer' })
  transfer(@Body() dto: TransferDto) {
    return this.transferService.execute(dto);
  }
}

@Controller('accounts')
export class AccountController {
  @Patch(':id')
  @Audit({ action: 'UPDATE', entity: 'Account' })
  updateAccount(@Param('id') id: string, @Body() dto: UpdateAccountDto) {
    return this.accountService.update(id, dto);
  }
}

@Controller('kyc')
export class KycController {
  @Post('submit')
  @Audit({ action: 'SUBMIT', entity: 'KycApplication' })
  submit(@Body() dto: KycDto) {
    return this.kycService.submit(dto);
  }

  @Patch(':id/approve')
  @Audit({ action: 'APPROVE', entity: 'KycApplication' })
  approve(@Param('id') id: string) {
    return this.kycService.approve(id);
  }
}

Education (enrollments, grades, courses)

Audit enrollment and grade changes for academic integrity and admin audits.

@Controller('enrollments')
export class EnrollmentController {
  @Post()
  @Audit({ action: 'CREATE', entity: 'Enrollment' })
  enroll(@Body() dto: EnrollDto) {
    return this.enrollmentService.enroll(dto);
  }

  @Delete(':id')
  @Audit({ action: 'DELETE', entity: 'Enrollment' })
  withdraw(@Param('id') id: string) {
    return this.enrollmentService.withdraw(id);
  }
}

@Controller('grades')
export class GradeController {
  @Put(':enrollmentId')
  @Audit({ action: 'UPDATE', entity: 'Grade' })
  setGrade(@Param('enrollmentId') id: string, @Body() dto: GradeDto) {
    return this.gradeService.setGrade(id, dto);
  }
}

@Controller('courses')
export class CourseController {
  @Post()
  @Audit({ action: 'CREATE', entity: 'Course' })
  create(@Body() dto: CreateCourseDto) {
    return this.courseService.create(dto);
  }
}

In every case you use the same @Audit({ action, entity }) and one IAuditStorage implementation; only the semantics (and your storage backend) change per domain.

Manual recording

You can skip the interceptor and record from services:

import { AuditService } from 'nestjs-audit-trail';

@Injectable()
export class MyService {
  constructor(private readonly audit: AuditService) {}

  async doSomething(actorId: string, correlationId: string) {
    const before = { count: 0 };
    // ... work ...
    const after = { count: 1 };
    await this.audit.record({
      action: 'UPDATE',
      entity: 'Counter',
      actorId,
      correlationId,
      payloadBefore: before,
      payloadAfter: after,
    });
  }
}

Configuration

| Option | Required | Default | Description | | --------------------- | -------- | -------------------- | ------------------------------------ | | storage | Yes | — | Your IAuditStorage implementation. | | correlationIdHeader | No | 'x-correlation-id' | Request header used for correlation. |

Set x-actor-id on the request (or ensure request.user.id is set) so each record has an actor. The core uses deterministic SHA256 hashing and optional chaining via getLastHash(); no database or ORM is required.

License

MIT