express-audit-logger

A flexible and powerful audit logging middleware for Express applications built with TypeScript. Track user actions, API activity, and system events with customizable storage providers and extensive configuration options.

Features

• Easy to integrate Express middleware
• Automatic HTTP request/response logging
• Sensitive data masking
• Path exclusion patterns
• Response time tracking
• Pluggable storage providers
• Detailed request metadata logging
• Manual logging capability
• Written in TypeScript with full type support

Installation

    npm install express-audit-logger
    # or
    yarn add express-audit-logger

Quick Start

    import express from 'express';
    import { AuditLogger, ConsoleStorageProvider } from 'express-audit-logger';
    
    const app = express();
    
    // Create an audit logger instance
    const auditLogger = new AuditLogger({
      storageProvider: new ConsoleStorageProvider(),
      maskSensitiveData: true,
      sensitiveFields: ['password', 'token'],
      excludePaths: ['/health', '/metrics']
    });
    
    // Use as middleware
    app.use(auditLogger.middleware());
    
    // Example route with manual logging
    app.post('/users', async (req, res) => {
      // Your business logic here
      await auditLogger.log('CREATE_USER', {
        userId: req.body.id,
        email: req.body.email
      });
      res.send({ success: true });
    });

Configuration Options

The AuditLogger constructor accepts an options object with the following properties:

    interface AuditLoggerOptions {
      storageProvider: AuditStorageProvider;  // Required
      excludePaths?: string[];               // Optional
      maskSensitiveData?: boolean;          // Optional
      sensitiveFields?: string[];           // Optional
    }

Storage providers

The library comes with two built-in storage providers

Console Storage Provider

You can use the console storage provider to display your logs on the console

    import { ConsoleStorageProvider } from 'express-audit-logger';

    const logger = new AuditLogger({
      storageProvider: new ConsoleStorageProvider()
    });

File Storage Provider

You can use the file storage provider to save your logs in a file

    import { FileStorageProvider } from 'express-audit-logger';
    
    const logger = new AuditLogger({
      storageProvider: new FileStorageProvider('./audit-logs.txt')
    });

Custom Storage Provider

You can create your own storage provider by implementing the AuditStorageProvider interface:

    import { AuditLog, AuditStorageProvider } from 'express-audit-logger';
    import { MongoClient } from 'mongodb';
    
    class MongoStorageProvider implements AuditStorageProvider {
      private client: MongoClient;
      private collection: string;
    
      constructor(client: MongoClient, collection: string) {
        this.client = client;
        this.collection = collection;
      }
    
      async save(log: AuditLog): Promise<void> {
        await this.client
          .db()
          .collection(this.collection)
          .insertOne(log);
      }
    }

Path Exclusion

Exclude specific paths from being logged:

    const logger = new AuditLogger({
    storageProvider: new ConsoleStorageProvider(),
     excludePaths: [
        '/health',           // Excludes health checks
        '/static',           // Excludes all static files
        '/api/v1/metrics',   // Excludes metrics endpoint
        '/favicon.ico'       // Excludes favicon requests
      ]
    });

Sensitive Data Masking

Mask sensitive information in logs:

    const logger = new AuditLogger({
      storageProvider: new ConsoleStorageProvider(),
      maskSensitiveData: true,
      sensitiveFields: ['password', 'token', 'creditCard']
    });

Log Structure

Each audit log entry contains the following information:

    interface AuditLog {
      timestamp: Date;
      userId?: string;
      action: string;
      resource: string;
      details: Record<string, any>;
      ip?: string;
      userAgent?: string;
      status?: number;
      method?: string;
      path?: string;
    }

Manual Logging

In addition to automatic request logging, you can manually create log entries:

    // Inside an async route handler or middleware
    await auditLogger.log('USER_LOGIN', {
      userId: '123',
      email: '[email protected]',
      loginMethod: 'oauth'
    });

Error Handling

The logger will never throw errors that could interrupt your application flow. All storage errors are caught and logged to console

    try {
      await storageProvider.save(log);
    } catch (error) {
      console.error('Failed to save audit log:', error);
    }

Examples

Basic Setup

Basic express app setup

    import express from 'express';
    import { AuditLogger, ConsoleStorageProvider } from 'express-audit-logger';
    
    const app = express();
    app.use(express.json());
    
    const logger = new AuditLogger({
      storageProvider: new ConsoleStorageProvider()
    });
    
    app.use(logger.middleware());

With Database Storage

You can create use your custom custom storage provider (e.g for MongoDB or PostgresQL)

    import { AuditLogger } from 'express-audit-logger';
    import { MongoStorageProvider } from './mongo-provider';
    import { MongoClient } from 'mongodb';
    
    const client = new MongoClient('mongodb://localhost:27017');
    await client.connect();
    
    const logger = new AuditLogger({
      storageProvider: new MongoStorageProvider(client, 'audit_logs')
    });
    
    app.use(logger.middleware())

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request