Audit

About

payload-audit attaches `afterChange` and `afterDelete` hooks to every collection in your Payload config and writes an immutable `audit-logs` entry for each create, update, and delete. One line of configuration covers all collections, with an opt-out list (`disabledCollections`) for anything you do not want audited. Payload's own internal collections (`payload-jobs`, `payload-preferences`, `payload-migrations`, and so on) are excluded by default to avoid noise and feedback loops. The generated `audit-logs` collection denies create, update, and delete through the API. Entries are only written internally by the plugin with `overrideAccess`, so the trail cannot be edited or removed by users. Each entry records the actor (with an email and name snapshot that survives later user deletion), the document id and title, the action type, the IP address, and the user agent. Upload-enabled collections get dedicated `file_upload` and `file_delete` actions instead of generic create and delete. The plugin targets the logging and accountability requirements of frameworks like NIS-2, CRA, GDPR, HIPAA, PCI-DSS 4.0, ISO/IEC 27001, and SOC 2. Optional forensic metadata captures the auth strategy, HTTP method, request path, and a non-reversible token fingerprint (`<prefix8>:<sha256(rest)>`) so you can correlate every action performed with a stolen credential without persisting the raw token. Delegation and impersonation follow RFC 8693 `act` semantics, recording who acted on behalf of whom via `onBehalfOf` and a nested `delegationChain`. Retention is enforced by a Payload scheduled task registered when you set `maxAge` (days) or `maxEntries` (count), with a configurable cron and queue, or a `disableSchedule` flag for manual triggering. Multi-tenant mode adds a `tenant` relationship to each entry, auto-detects the tenant field on your collections, and interoperates with `@payloadcms/plugin-multi-tenant`. The exported helpers `writeAuditLog`, `resolveDelegation`, `extractTenant`, `resolveDocTitle`, and `pruneAuditLogs` let you emit and manage entries from custom hooks and scripts, and a `skipAuditLog` request-context flag suppresses the automatic entry when you write a more specific one yourself. Requires Payload 3.x with the MongoDB adapter.

Package info

Package name

@trieb.work/payload-audit

Latest version

1.3.0

Unpacked size

227 kB

License

MIT

Weekly downloads

645

Last publish

Sep 9, 2026