🛡️ Auditor

this is a lightweight, type-safe, and framework-agnostic backend auditing system for Node.js — not just another logger.

It enables structured auditing of:

• Request and response activity
• Application-level events (e.g. user logins, deletions)
• Errors and exceptions
• Database operations with Mongoose and Prisma
• Optional remote logging via BetterStack
• Optional UI dashboard for inspecting audit logs

Auditor helps provide observability, traceability, and accountability for your backend services.

📦 Installation

npm install @kingdiablo/auditor

You can also install and use your preferred logger and optionally an ORM:

npm install winston mongoose

ℹ️ Quick Start (v0.3.0+)

Note: After creating an Auditor instance, you must call .Setup() before using any middleware or logging features.

Express

import { Auditor } from '@kingdiablo/auditor';
import express from 'express';

const audit = new Auditor({ framework: 'express' });
await audit.Setup();
const app = express();
app.use(audit.RequestLogger());
app.use(audit.ErrorLogger());

Fastify

import { Auditor } from '@kingdiablo/auditor';
import Fastify from 'fastify';

const audit = new Auditor({ framework: 'fastify' });
await audit.Setup();
const fastify = Fastify();
fastify.addHook('onRequest', audit.RequestLogger().onRequest);
fastify.addHook('onResponse', audit.RequestLogger().onResponse);
fastify.setErrorHandler(audit.ErrorLogger());

Koa

import { Auditor } from '@kingdiablo/auditor';
import Koa from 'koa';

const audit = new Auditor({ framework: 'koa' });
await audit.Setup();
const app = new Koa();
app.use(audit.RequestLogger());
app.use(audit.ErrorLogger());

🖥️ Using the Audit UI (Express, Fastify, and Koa)

Auditor provides an optional self-hosted UI to view and explore audit logs. To enable it, set useUI: true. Dependencies are downloaded at runtime — no CDN used.

Express UI Setup

const audit = new Auditor({ framework: 'express', useUI: true });
await audit.Setup();

if (audit.CreateUI) {
	const auditUI = await audit.CreateUI();
	app.use(auditUI);
}

Fastify UI Setup

const audit = new Auditor({ framework: 'fastify', useUI: true });
await audit.Setup();

const auditUI = await audit.CreateUI();
fastify.register(auditUI);

fastify.listen(3000, () => {
	console.log('Server running on http://localhost:3000');
});

Koa UI Setup

const audit = new Auditor({ framework: 'koa', useUI: true });
await audit.Setup();

const auditUI = await audit.CreateUI();
app.use(auditUI);

app.listen(3000, () => {
	console.log('Server running on http://localhost:3000');
});

The UI will be available at /audit-ui and logs can be fetched from /audit-log.

🔐 UI Security Features

The audit UI includes built-in security measures to protect sensitive audit logs:

Authentication System

• Login Required: All UI routes require authentication
• Session Management: Uses secure HTTP-only cookies
• Secret Key: Requires a secret key for session validation

Available Routes

• /auth-ui - Login page (unauthenticated)
• /login - Authentication endpoint (POST)
• /logout - Session termination
• /audit-ui - Main dashboard (authenticated only)
• /audit-log - API endpoint for logs (authenticated only)

Security Configuration

// Configure UI security when creating the audit instance
const audit = new Auditor({
	framework: 'express',
	useUI: true,
	// Security credentials
	uiCredentials: {
		username: 'admin', // Default: 'admin'
		password: 'securepass', // Default: 'admin'
		secret: 'your-secret-key', // Required for session validation
	},
});

Session Security

• HTTP-only cookies: Prevents XSS attacks
• SameSite=strict: CSRF protection
• Secure flag: HTTPS enforcement (configurable)
• Session timeout: 1 hour expiration
• Base64 encoding: Credentials are encoded but not encrypted

Access Control

• Route protection: All sensitive routes require valid session
• Automatic redirects: Unauthorized users redirected to login
• Error handling: Returns 403 Forbidden for unauthorized access

Security Best Practices

1. Change default credentials: Always update from default 'admin/admin'
2. Use strong secrets: Generate cryptographically secure secret keys
3. HTTPS in production: Enable secure cookies in production
4. Environment variables: Store credentials in environment variables
5. Regular rotation: Change credentials periodically

Example Secure Setup

const audit = new Auditor({
	framework: 'express',
	useUI: true,
	uiCredentials: {
		username: process.env.AUDIT_USERNAME || 'admin',
		password: process.env.AUDIT_PASSWORD || 'admin',
		secret: process.env.AUDIT_SECRET || 'default-secret-change-me',
	},
});

📄 Configuring File Logging (SetFileConfig)

const audit = new Auditor({ destinations: ['file'] });
await audit.Setup();

audit.SetFileConfig({
	folderName: 'logs',
	fileName: 'my-audit',
});

Default values:

• folderName: audit
• fileName: audit

🛠️ Configuration

const audit = new Auditor({
	logger: myLogger,
	destinations: ['console', 'file', 'remote'],
	dbType: 'mongoose',
	useTimeStamp: true,
	splitFiles: true,
	framework: 'fastify',
	useUI: true,
	remote: {
		provider: 'betterstack',
		apiKey: process.env.BETTERSTACK_API_KEY,
		sourceId: process.env.BETTERSTACK_SOURCE_ID,
	},
});
await audit.Setup();

🚀 Features

• Multi-framework support
• Request/error middleware
• File-based JSON logging
• Remote logging via BetterStack
• Database audit logging (Mongoose + Prisma)
• Manual structured business event logging
• Split file logging per log type
• Pluggable logger support (Winston, Pino, Console)
• Optional system error capture
• Optional UI dashboard

⚙ Configuration Options

| Option | Type | Default | Description | | --------------------- | --------- | ------------- | ------------------------------------------------- | | logger | any | console | Custom logger instance (Winston, Pino, etc) | | destinations | string[] | ['console'] | Where to write logs (console, file, remote) | | dbType | string | 'none' | 'mongoose' or 'prisma' | | useTimeStamp | boolean | true | Adds timestamps to logs | | splitFiles | boolean | false | Split logs into separate files | | framework | string | 'express' | 'express', 'fastify', 'koa' | | captureSystemErrors | boolean | false | Capture uncaught exceptions/signals | | useUI | boolean | false | Serve the frontend dashboard | | remote | object | undefined | Configuration for BetterStack |

💵 Business Event Logging (Log)

Use Log to track user actions and meaningful server events.

⚠️ Auditor cannot automatically track user-level actions — you must log them explicitly.

audit.Log({
	type: 'auth',
	action: 'login',
	status: 'success',
	actor: 'admin',
	message: 'User logged in successfully.',
	meta: { userId: 'abc123' },
});

Custom types/actions are supported:

audit.Log({
	type: 'custom_event',
	action: 'something_happened',
	status: 'info',
	message: 'A custom event occurred.',
});

🚠 Manual Error Logging (LogError)

try {
	// ...some code
} catch (err) {
	audit.LogError(err);
}

💄 Mongoose Schema Auditing (AuditModel)

import mongoose from 'mongoose';
import { Auditor } from '@kingdiablo/auditor';

const audit = new Auditor({ dbType: 'mongoose' });
await audit.Setup();

const userSchema = new mongoose.Schema({
	// schema fields...
});

audit.AuditModel(userSchema);

✨ Prisma Database Auditing Support

Setup

npm install @prisma/client

import { Auditor } from '@kingdiablo/auditor';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();
const audit = new Auditor({ dbType: 'prisma' });
await audit.Setup();
audit.AuditModel(prisma);

🔄 Request Logger Middleware (RequestLogger)

// Express
app.use(audit.RequestLogger());

// Fastify
fastify.addHook('onRequest', audit.RequestLogger().onRequest);
fastify.addHook('onResponse', audit.RequestLogger().onResponse);

// Koa
app.use(audit.RequestLogger());

⚠️ Error Logger Middleware (ErrorLogger)

// Express
app.use(audit.ErrorLogger());

// Fastify
fastify.setErrorHandler(audit.ErrorLogger());

// Koa
app.use(audit.ErrorLogger());

🧝‍♂️ Log Retention / Rotation

📌 Quick Overview

| Feature | Setup Required | Default State | Usage | | --------------------------------- | -------------- | ------------- | ------------------------------------------------------- | | Log Retention & File Rotation | ✅ Optional | Disabled | Automatic cleanup of old logs | | Log File Splitting | ✅ Optional | Disabled | Separate logs by type | | Archive Cleanup | ✅ Automatic | Automatic | Auto-cleanup old archives (if max retention is active ) |

🔧 1. Log Retention & File Rotation

What it does

• Automatically rotates log files when they exceed size limits
• Archives old logs to /logs/archive/
• Cleans up archives older than configured days

Setup

import { Auditor } from '@kingdiablo/auditor';

const audit = new Auditor({
	destinations: ['file'],
	maxRetention: 7, // Keep logs for 7 days
	splitFiles: true, // Enable file splitting
});

await audit.Setup();
audit.SetFileConfig({
	folderName: 'logs',
	fileName: 'my-app',
});

Usage

• Logs will auto-rotate when > 5MB
• Archives stored in logs/archive/
• Cleanup runs daily at midnight

📁 2. Log File Splitting

What it does

• Splits logs into separate files by type:

  • request.log - HTTP requests
  • error.log - Errors/exceptions
  • db.log - Database operations
  • audit.log - General audit events

Setup

const audit = new Auditor({
	destinations: ['file'],
	splitFiles: true, // Enable splitting
});

await audit.Setup();

File Structure

logs/
├── my-app-request.log
├── my-app-error.log
├── my-app-db.log
├── my-app-audit.log
└── archive/
    ├── my-app_2024-01-15_12-00-00.log
    └── ...

🧹 3. Archive Cleanup

What it does

• Automatically deletes archived logs older than configured days
• Runs during log rotation

Setup

const audit = new Auditor({
	maxRetention: 30, // Delete archives older than 30 days
});

📋 Changelog

See the CHANGELOG.md for full release notes.

📤 Remote Logging

See the REMOTE_LOGGING.md for setup and usage.

📜 License

MIT

🙌 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.