@cepseudo/adonis-audit-log

Simple audit logging package for AdonisJS 6.

Features

• Custom audit logs for tracking user actions and business events
• Automatic HTTP request logging via middleware
• Error logging with exception handler integration
• Configurable field sanitization for sensitive data
• Retention settings for log cleanup

Installation

npm install @cepseudo/adonis-audit-log

Configuration

node ace configure @cepseudo/adonis-audit-log

This will:

1. Publish migrations to database/migrations/
2. Publish config to config/audit.ts
3. Register the provider and command in adonisrc.ts

Then run the migrations:

node ace migration:run

Configuration Options

// config/audit.ts
import { defineConfig } from '@cepseudo/adonis-audit-log'

export default defineConfig({
  enabled: true,

  requestLog: {
    enabled: true,
    excludeRoutes: ['/health', '/metrics'],
    excludeMethods: ['OPTIONS'],
    logBody: false,
    logQuery: true,
    sanitizeFields: ['password', 'token', 'secret'],
  },

  errorLog: {
    enabled: true,
    excludeStatusCodes: [404],
    includeStack: true,
  },

  auditLog: {
    enabled: true,
  },

  // Retention in days (0 = unlimited)
  retention: {
    requestLogs: 30,
    errorLogs: 90,
    auditLogs: 0, // Keep forever
  },
})

Usage

Custom Audit Logs

import audit from '@cepseudo/adonis-audit-log/services/main'

// Simple log
await audit.log('user.login', { user_id: 1 })

// With metadata
await audit.log('submission.create', {
  user_id: auth.user.id,
  submission_id: submission.id,
  project_acronym: submission.projectAcronym,
})

// Track changes
await audit.logChange('user.update', {
  userId: auth.user.id,
  targetId: targetUser.id,
  changes: {
    email: { from: '[email protected]', to: '[email protected]' },
  },
})

Request Logging (Middleware)

Add the middleware to your router in start/kernel.ts:

router.use([() => import('@cepseudo/adonis-audit-log/middleware/request_logger')])

Error Logging (Exception Handler)

Integrate with your exception handler in app/exceptions/handler.ts:

import { AuditErrorLogger } from '@cepseudo/adonis-audit-log'

export default class HttpExceptionHandler extends ExceptionHandler {
  async report(error: unknown, ctx: HttpContext) {
    await AuditErrorLogger.log(error, ctx)
    return super.report(error, ctx)
  }
}

Log Cleanup

Delete old logs based on retention configuration:

node ace audit:cleanup

Set retention to 0 for unlimited retention (logs won't be deleted).

Database Schema

The package creates three tables:

audit_logs

• id - Primary key
• action_type - Event type (e.g., 'user.login', 'submission.create')
• metadata - JSON object with additional data
• user_id - Optional reference to users table
• created_at - Timestamp

request_logs

• id - Primary key
• method - HTTP method
• url - Request URL
• route_name - Named route if available
• status_code - HTTP response status
• response_time_ms - Response time in milliseconds
• ip - Client IP address
• user_agent - Browser/client user agent
• user_id - Optional reference to users table
• request_body - Sanitized request body (optional)
• request_query - Query parameters
• created_at - Timestamp

error_logs

• id - Primary key
• error_type - Error class name
• message - Error message
• stack - Stack trace (optional)
• url - URL where error occurred
• method - HTTP method
• status_code - HTTP status returned
• user_id - Optional reference to users table
• context - Additional context (params, query)
• created_at - Timestamp

Development

# Install dependencies
npm install

# Run tests
npm run test

# Run tests without linting
npm run quick:test

# Build
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

License

MIT