@rikology/adonisjs-audit-trail

Production-grade, tamper-evident audit trail for AdonisJS v7.

Capture who changed what, when, and from where — automatically for Lucid models and explicitly for domain events — into an append-only, hash-chained trail you can cryptographically verify. Built for compliance workloads (SOC 2, GDPR, HIPAA-style) where the audit log itself must be trustworthy.

Why this package?

Most AdonisJS auditing solutions stop at "who changed this row". @rikology/adonisjs-audit-trail is designed for environments where the log is evidence:

• Tamper-evident by default — every record is linked into a per-stream SHA-256 hash chain; modification breaks every successor.
• Never blocks the request path — asynchronous, batched pipeline with configurable delivery guarantees.
• Pluggable storage — SQL, NDJSON stream, HTTP collector, or fanout.
• Compliance-aware — field-level redaction, retention policies, GDPR crypto-shredding, multi-tenancy.
• Native v7 integration — provider, configure flow, middleware, transformer stub, and Ace commands.

Table of contents

• Requirements
• Quick start
• Features
• Documentation
• Demo app
• Benchmarks
• Contributing
• Security
• License

Requirements

• Node.js >= 24
• AdonisJS v7 (@adonisjs/core@^7)
• TypeScript 5.9+

Quick start

1. Install

node ace add @rikology/adonisjs-audit-trail

Or with your package manager of choice:

npm install @rikology/adonisjs-audit-trail
pnpm add @rikology/adonisjs-audit-trail
yarn add @rikology/adonisjs-audit-trail

The configure command publishes config/audit.ts, migrations, the audit transformer, and registers the provider, commands, and middleware.

For CI or other non-interactive environments, pass flags to skip the prompts:

node ace configure @rikology/adonisjs-audit-trail --outbox --no-multi-tenant --immutability

2. Run migrations

node ace migration:run

3. Add the mixin to a model

import { compose } from '@adonisjs/core/helpers'
import { BaseModel } from '@adonisjs/lucid/orm'
import { Auditable } from '@rikology/adonisjs-audit-trail/auditable'

export default class Invoice extends compose(BaseModel, Auditable) {
  static auditConfig = {
    redact: ['iban'],
    tags: ['billing'],
  }

  // ... columns
}

Every create, update, delete, and restore now produces an immutable audit record automatically.

4. Log explicit domain events

import audit from '@rikology/adonisjs-audit-trail/services/main'

await audit.log('invoice.approved').on(invoice).withMeta({ level: 2 }).commit()

5. Query the trail

import Audit from '@rikology/adonisjs-audit-trail/models/audit'

const trail = await Audit.forModel(invoice).orderBy('seq', 'desc').cursorPaginate(20)

6. Verify integrity

node ace audit:verify

Exit code is non-zero when a chain break is detected, so it can be wired into CI/cron.

Features

• Automatic model auditing via a Lucid mixin.
• Explicit domain events via a fluent API.
• Tamper-evident SHA-256 hash chains with node ace audit:verify.
• Asynchronous, batched write pipeline that never blocks the request path.
• Three delivery guarantees: best-effort, request-coupled, and transactional-outbox.
• Pluggable stores: SQL (Lucid), NDJSON stream, HTTP collector, or fanout.
• PII-aware redaction, masking, hashing, and crypto-shredding support.
• Multi-tenancy with tenant-scoped chains and queries.
• Type-safe end-to-end with generated event-name unions and v7 transformers.

Documentation

• Configuration reference — every config option, env variable, and typed event names.
• Guarantee modes — choosing between best-effort, request-coupled, and transactional-outbox.
• Tamper evidence & verification — how the hash chain works and what to do if verification fails.
• Redaction & GDPR — masking, hashing, and crypto-shredding sensitive fields.
• Retention & pruning — archive and prune old events safely.
• Multi-tenancy — tenant-scoped streams and queries.
• Stores — built-in storage drivers and custom store authoring.
• Operations guide — partitioning, role grants, DLQ monitoring, and cron verification.
• Recipes: Inertia audit viewer
• Recipes: SIEM shipping
• Threat model
• Upgrade policy
• Architecture — design rationale and prior-art analysis.

Demo app

See examples/demo for a runnable AdonisJS v7 API that shows the Lucid mixin, request context middleware, explicit domain events, redaction, and audit:verify.

Benchmarks

Run locally with:

npm run bench
BENCH_DB=postgres npm run bench

| Metric | Target | Observed (SQLite, MBP M1 Pro) | | -------------------------------------- | ----------------- | ------------------------------------- | | Enqueue overhead per model.save() | < 0.2 ms p99 | ~0.075 ms p99 | | Flush throughput (Postgres, batch 200) | >= 5,000 events/s | run BENCH_DB=postgres npm run bench |

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, the development workflow, and conventions. Please also read the Code of Conduct.

Security

If you discover a security vulnerability, please do not open a public issue. Follow the disclosure process in SECURITY.md.

License

MIT © Rikology