Triostack Audit SDK

A server-side audit logging middleware for Node.js applications with Express, Fastify, and Koa support. Automatically tracks API requests, user activity, and provides geolocation data.

Features

• Automatic Request Logging: Tracks all HTTP requests with timing and metadata
• Geolocation Support: IP-based geolocation using geoip-lite
• Multi-Framework Support: Express, Fastify, and Koa middleware
• Rich Data Collection: Request/response sizes, status codes, user agents
• Flexible Configuration: Customizable user ID headers and error handling
• Performance Optimized: Non-blocking async logging with timeouts

Installation

npm install triostack-audit-sdk

Quick Start

Express.js

import express from 'express';
import { createAuditServer } from 'triostack-audit-sdk';

const app = express();

// Create audit server
const auditServer = createAuditServer({
  dbUrl: 'https://your-api.com/audit-logs',
  userIdHeader: 'x-user-id', // Optional: custom header for user ID
  enableGeo: true, // Optional: enable geolocation
  onError: (err) => console.error('Audit error:', err) // Optional: error handler
});

// Use middleware
app.use(auditServer.expressMiddleware());

// Your routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.listen(3000);

Fastify

import Fastify from 'fastify';
import { fastifyAuditPlugin } from 'triostack-audit-sdk';

const fastify = Fastify();

// Register audit plugin
await fastify.register(fastifyAuditPlugin, {
  dbUrl: 'https://your-api.com/audit-logs',
  userIdHeader: 'x-user-id',
  enableGeo: true
});

// Your routes
fastify.get('/api/users', async (request, reply) => {
  return { users: [] };
});

await fastify.listen({ port: 3000 });

Koa

import Koa from 'koa';
import { koaAuditMiddleware } from 'triostack-audit-sdk';

const app = new Koa();

// Use middleware
app.use(koaAuditMiddleware({
  dbUrl: 'https://your-api.com/audit-logs',
  userIdHeader: 'x-user-id',
  enableGeo: true
}));

// Your routes
app.use(async (ctx) => {
  ctx.body = { users: [] };
});

app.listen(3000);

Manual Tracking

You can also manually track specific events:

import { createAuditServer } from 'triostack-audit-sdk';

const auditServer = createAuditServer({
  dbUrl: 'https://your-api.com/audit-logs'
});

// Manual tracking
app.post('/api/login', async (req, res) => {
  try {
    const user = await authenticateUser(req.body);
    
    // Track successful login
    await auditServer.track(req, {
      userId: user.id,
      route: '/api/login',
      method: 'POST',
      statusCode: 200,
      duration: 150,
      event: 'user_login',
      metadata: {
        loginMethod: 'email',
        success: true
      }
    });
    
    res.json({ success: true });
  } catch (error) {
    // Track failed login
    await auditServer.track(req, {
      userId: 'anonymous',
      route: '/api/login',
      method: 'POST',
      statusCode: 401,
      duration: 50,
      event: 'user_login_failed',
      metadata: {
        loginMethod: 'email',
        success: false,
        error: error.message
      }
    });
    
    res.status(401).json({ error: 'Invalid credentials' });
  }
});

Configuration Options

createAuditServer(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | dbUrl | string | required | URL where audit logs will be sent | | userIdHeader | string | 'x-user-id' | HTTP header name for user ID | | enableGeo | boolean | true | Enable IP-based geolocation | | onError | function | console.error | Error handler function |

Data Structure

The SDK sends this data structure to your endpoint:

{
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
  timestamp: "2024-08-27T16:09:00.000Z",
  ip: "192.168.1.1",
  city: "New York",
  region: "NY",
  country: "United States",
  latitude: 40.7128,
  longitude: -74.0060,
  userAgent: "Mozilla/5.0...",
  userId: "user123",
  route: "/api/users",
  method: "GET",
  statusCode: 200,
  duration: 45,
  requestSize: 1024,
  responseSize: 2048,
  event: "api_request", // Optional for manual tracking
  metadata: {} // Optional for manual tracking
}

API Endpoint Setup

Your audit endpoint should accept POST requests with the data structure above:

// Example Express endpoint
app.post('/audit-logs', async (req, res) => {
  try {
    const auditData = req.body;
    
    // Validate required fields
    if (!auditData.userId || !auditData.route) {
      return res.status(400).json({
        success: false,
        message: 'Missing required fields'
      });
    }
    
    // Save to database
    await saveToDatabase(auditData);
    
    res.json({ success: true });
  } catch (error) {
    console.error('Audit save error:', error);
    res.status(500).json({ success: false, error: error.message });
  }
});

Error Handling

The SDK includes comprehensive error handling:

const auditServer = createAuditServer({
  dbUrl: 'https://your-api.com/audit-logs',
  onError: (error) => {
    // Custom error handling
    console.error('Audit failed:', error.message);
    
    // Send to error reporting service
    // sendToErrorReporting(error);
    
    // Don't break your application
  }
});

Performance Considerations

• Non-blocking: All audit operations are asynchronous
• Timeouts: 10-second timeout for network requests
• Error isolation: Audit failures won't break your application
• Minimal overhead: Lightweight middleware with minimal performance impact

Browser Support

This is a server-side SDK and does not run in browsers. For client-side tracking, consider using:

• Google Analytics
• Mixpanel
• Amplitude
• Custom client-side tracking

License

MIT