@edirect/audit-instrumentation-express

Express.js auto-instrumentation for the eDirect Audit system. Automatically extracts request context (client IP, origin URL, session ID) from incoming Express requests and injects it into audit events — so you don't have to pass this data manually in every audit() call.

Features

• Automatically captures originIpAddress, originUrl, and optionally sessionId from each request
• Uses async context (cls-hooked) for zero-boilerplate request propagation
• Works as Express middleware or as a passive instrumentation class
• Integrates seamlessly with @edirect/audit-nestjs via the instrumentation option

Installation

pnpm add @edirect/audit-instrumentation-express
# or
npm install @edirect/audit-instrumentation-express

Usage

With @edirect/audit-nestjs (recommended)

Pass InstrumentationExpress to the instrumentation array in your AuditModule config:

import { AuditModule } from '@edirect/audit-nestjs';
import { HttpAxiosExporter } from '@edirect/audit-exporter-http-axios';
import { InstrumentationExpress } from '@edirect/audit-instrumentation-express';

AuditModule.register({
  exporter: (request) =>
    new HttpAxiosExporter({
      basePath: 'https://audit.internal.example.com',
      accessToken: request.headers.authorization,
    }),
  service: 'my-service',
  domain: 'policy',
  tenant: 'th-broker',
  // Auto-populate originIpAddress, originUrl, and sessionId for all audit events
  instrumentation: [
    new InstrumentationExpress({
      sessionId: (req) => req.headers['x-session-id'] as string,
    }),
  ],
})

As standalone Express middleware

import express from 'express';
import { InstrumentationExpress } from '@edirect/audit-instrumentation-express';

const app = express();

// Register the middleware on app startup
new InstrumentationExpress(app, {
  sessionId: (req) => req.cookies?.sessionId,
});

Static helper process()

The process() static method can extract request context without the middleware:

import { InstrumentationExpress } from '@edirect/audit-instrumentation-express';
import { Request } from 'express';

const context = InstrumentationExpress.process(
  { sessionId: (req) => req.headers['x-session-id'] as string },
  req
);
// Returns: { originIpAddress: '1.2.3.4', originUrl: 'https://...', sessionId: '...' }

API

InstrumentationExpress

constructor(app?: Application, options?: InstrumentationExpressOptions)

| Parameter | Type | Description | |-----------|------|-------------| | app | express.Application (optional) | If provided, registers the middleware automatically | | options.sessionId | (req: Request) => string \| undefined | Custom session ID extractor from the request |

static middleware(options?): RequestHandler

Returns an Express middleware function that captures request context into async storage.

static process(options, request): Partial<AuditRequest>

Extracts audit context from an Express request synchronously. Returns an object with originIpAddress, originUrl, and optionally sessionId.

What Gets Auto-Populated

When InstrumentationExpress is used in the audit pipeline, the following fields are automatically filled in audit events:

| Field | Source | |-------|--------| | originIpAddress | Client IP (via request-ip package, respects proxies) | | originUrl | req.protocol + '://' + req.get('host') + req.originalUrl | | sessionId | From custom sessionId extractor (if provided) |