@86d-app/audit-log

The Modern Foundation for Commerce

X · LinkedIn

This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

Documentation: 86d.app/docs/modules/audit-log

Audit Log Module

Records admin actions, system events, and API key usage for security auditing, compliance, and accountability. Other modules can record audit entries through the exported controller interface.

Installation

npm install @86d-app/audit-log

Usage

import auditLog from "@86d-app/audit-log";

const module = auditLog({
  retentionDays: 90, // auto-purge entries older than 90 days
});

Configuration

Option	Type	Default	Description
retentionDays	number	0	Days to retain audit entries before auto-purge. 0 disables auto-purge.

Admin Endpoints

Method	Path	Description
GET	/admin/audit-log/entries	List audit entries (filterable by action, resource, actor, date range)
GET	/admin/audit-log/entries/:id	Get a single audit entry
GET	/admin/audit-log/resource/:resource/:resourceId	Get audit history for a specific resource
GET	/admin/audit-log/actor/:actorId	Get audit history for a specific actor
GET	/admin/audit-log/summary	Get aggregate activity summary
POST	/admin/audit-log/purge	Purge entries older than a specified date

Store Endpoints

Method	Path	Description
GET	/audit-log/my-activity	Get the authenticated user's own audit history (paginated via take/skip query params). Requires an active session.

Controller API

The AuditLogController interface is exported for use by other modules to record audit entries.

interface AuditLogController {
  log(params: CreateAuditEntryParams): Promise<AuditEntry>;
  getById(id: string): Promise<AuditEntry | null>;
  list(params?: AuditListParams): Promise<{ entries: AuditEntry[]; total: number }>;
  listForResource(resource: string, resourceId: string, params?: { take?: number; skip?: number }): Promise<AuditEntry[]>;
  listForActor(actorId: string, params?: { take?: number; skip?: number }): Promise<AuditEntry[]>;
  getSummary(params?: { dateFrom?: Date; dateTo?: Date }): Promise<AuditSummary>;
  purge(olderThan: Date): Promise<number>;
}

Types

type AuditAction =
  | "create" | "update" | "delete"
  | "bulk_create" | "bulk_update" | "bulk_delete"
  | "login" | "logout"
  | "export" | "import"
  | "settings_change" | "status_change" | "custom";

type ActorType = "admin" | "system" | "api_key";

interface AuditEntry {
  id: string;
  action: AuditAction;
  resource: string;
  resourceId?: string;
  actorId?: string;
  actorEmail?: string;
  actorType: ActorType;
  description: string;
  changes?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
  ipAddress?: string;
  userAgent?: string;
  createdAt: Date;
}

interface AuditSummary {
  totalEntries: number;
  entriesByAction: Record<string, number>;
  entriesByResource: Record<string, number>;
  recentActors: Array<{ actorId: string; actorEmail?: string; count: number }>;
}

Notes

• The /audit-log/my-activity store endpoint lets authenticated customers view their own audit trail.
• Other modules should use AuditLogController.log() to record audit entries through inter-module contracts.
• Date range filtering is performed in-memory since ModuleDataService does not support range queries.
• The summary endpoint returns counts grouped by action, resource, and the top 10 most active actors.
• Purging deletes entries one by one; use retention policies for automatic cleanup.