A lightweight and customizable audit logger for Node.js apps. Tracks database changes, errors, and user actions with support for external loggers like Winston or Pino.
npm install @kingdiablo/auditorbash
npm install @kingdiablo/auditor
`
You can also install and use your preferred logger and optionally an ORM:
`bash
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.
$3
`ts
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());
`
$3
`ts
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());
`
$3
`ts
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.
$3
`ts
const audit = new Auditor({ framework: 'express', useUI: true });
await audit.Setup();
if (audit.CreateUI) {
const auditUI = await audit.CreateUI();
app.use(auditUI);
}
`
$3
`ts
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');
});
`
$3
`ts
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:
$3
- Login Required: All UI routes require authentication
- Session Management: Uses secure HTTP-only cookies
- Secret Key: Requires a secret key for session validation
$3
- /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)
$3
`ts
// 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
},
});
`
$3
- 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
$3
- Route protection: All sensitive routes require valid session
- Automatic redirects: Unauthorized users redirected to login
- Error handling: Returns 403 Forbidden for unauthorized access
$3
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
$3
`ts
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)
`ts
const audit = new Auditor({ destinations: ['file'] });
await audit.Setup();
audit.SetFileConfig({
folderName: 'logs',
fileName: 'my-audit',
});
`
Default values:
- folderName: audit
- fileName: audit
---
๐ ๏ธ Configuration
`ts
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.
`ts
audit.Log({
type: 'auth',
action: 'login',
status: 'success',
actor: 'admin',
message: 'User logged in successfully.',
meta: { userId: 'abc123' },
});
`
Custom types/actions are supported:
`ts
audit.Log({
type: 'custom_event',
action: 'something_happened',
status: 'info',
message: 'A custom event occurred.',
});
`
---
๐ Manual Error Logging (
LogError)
`ts
try {
// ...some code
} catch (err) {
audit.LogError(err);
}
`
---
๐ Mongoose Schema Auditing (
AuditModel)
`ts
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
$3
`bash
npm install @prisma/client
`
`ts
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)
`ts
// 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)
`ts
// Express
app.use(audit.ErrorLogger());
// Fastify
fastify.setErrorHandler(audit.ErrorLogger());
// Koa
app.use(audit.ErrorLogger());
`
---
๐งโโ๏ธ Log Retention / Rotation
$3
| 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 ) |
---
$3
#### 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
`ts
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
---
$3
#### 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
`ts
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
#### What it does
- Automatically deletes archived logs older than configured days
- Runs during log rotation
#### Setup
`ts
const audit = new Auditor({
maxRetention: 30, // Delete archives older than 30 days
});
``