@airdraft/plugin-audit-log

Wide-event audit logging plugin for Airdraft. Captures every CMS operation — including actor, collection, slug, HTTP method, status, duration, and per-field validation errors — and routes them to configurable persisters.

Installation

npm install @airdraft/plugin-audit-log

Usage

import { defineConfig } from '@airdraft/core'
import { withAuditLog } from '@airdraft/plugin-audit-log'

export const airdraft = defineConfig({
  adapter,
  collections,
  plugins: [
    withAuditLog({ logFilePath: './logs/audit.log' }),
  ],
})

Options

| Option | Type | Default | Description | |---|---|---|---| | logFilePath? | string | — | Path to an NDJSON audit log file. Also enables the GET /audit route on the handler. | | persist? | AuditPersister | consolePersister (or filePersister if logFilePath is set) | Custom persister function. |

GET /audit endpoint

When logFilePath is set, a /audit route is added to the CMS handler:

GET /api/cms/audit?limit=50&offset=0
→ { events: AuditEvent[], total: number }

Persisters

consolePersister

Logs each event as a compact JSON line to stdout (default).

import { consolePersister } from '@airdraft/plugin-audit-log'
withAuditLog({ persist: consolePersister })

filePersister(filePath)

Appends events as NDJSON to a file. Compatible with jq, grep, and log shippers (Loki, Datadog, etc.).

import { filePersister } from '@airdraft/plugin-audit-log'
withAuditLog({ persist: filePersister('./logs/audit.log') })

compositePersister(...persisters)

Calls multiple persisters in sequence — useful for logging to both console and file simultaneously.

import { compositePersister, consolePersister, filePersister } from '@airdraft/plugin-audit-log'

withAuditLog({
  persist: compositePersister(
    consolePersister,
    filePersister('./logs/audit.log'),
  ),
})

mongodbPersister(collection)

Inserts events into a MongoDB collection. Pass any object with an insertOne method — compatible with the official mongodb driver. No mongodb peer dependency is required.

import { MongoClient } from 'mongodb'
import { mongodbPersister } from '@airdraft/plugin-audit-log'

const db = new MongoClient(process.env.MONGODB_URI!).db('mydb')
withAuditLog({ persist: mongodbPersister(db.collection('auditLogs')) })

The MongoInsertableCollection interface is exported for use in custom adapters:

import type { MongoInsertableCollection } from '@airdraft/plugin-audit-log'

AuditEvent shape

interface AuditEvent {
  id: string           // unique event ID
  timestamp: string    // ISO-8601
  method: string       // 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
  path: string         // request path, e.g. '/posts/hello-world'
  action: string       // e.g. 'entry.create', 'media.upload', 'schema.update'
  collection?: string
  slug?: string
  statusCode: number
  durationMs: number
  actor?: string       // raw API key / bearer token
  error?: {
    message: string
    code: string
    details?: Array<{ field: string; message: string }>  // per-field validation errors
  }
}

Exports

| Export | Description | |---|---| | withAuditLog(options?) | Creates the audit log plugin | | consolePersister | Default stdout persister | | filePersister(filePath) | NDJSON file persister | | compositePersister(...persisters) | Fan-out persister | | mongodbPersister(collection) | MongoDB insert persister | | AuditPersister | Type: (event: AuditEvent) => void \| Promise<void> | | AuditLogOptions | Options type for withAuditLog | | MongoInsertableCollection | Duck-typed interface for the MongoDB persister |

Changelog

See CHANGELOG.md.