Immutable Audit Logs in Node.js with AsyncLocalStorage

In financial and campaign management systems like Curved Lab, tracking who changed what, when, and from where is a non-negotiable security requirement. However, typical audit implementations suffer from severe architectural rot: developers pass userId, ipAddress, and userAgent down through ten layers of business logic, polluting function signatures from HTTP controllers all the way to deep database helpers.

To establish enterprise-grade audit logging without cluttering our domain services, we leveraged Node.js's native AsyncLocalStorage combined with Mongoose post-save lifecycle hooks. Here is how we engineered an invisible, tamper-evident audit trail.

Context Propagation Without Argument Drilling

AsyncLocalStorage allows storing state throughout the lifecycle of an asynchronous execution chain—similar to thread-local storage in Java or C#. When an HTTP request reaches our Express gateway, middleware intercepts the authenticated session, IP address, and request ID, wrapping the downstream request execution inside a scoped context store.

Any deep database repository or service executed within this promise chain can query the ambient context on demand without receiving it as an argument.

Capturing Delta Diffs Automatically

Rather than manually calling auditLog.create() after every database update, our Mongoose schema plugins register pre-save and post-save hooks. During pre('save'), the hook inspects this.modifiedPaths() and snapshots both the original values and the incoming mutations.

Once the document commits successfully, the post('save') hook captures the active context from AsyncLocalStorage, builds a cryptographically hashed delta record, and writes it directly to an append-only audit collection. If an internal cron job or background worker performs a mutation outside an HTTP context, the store defaults gracefully to a system identity.

Security Safeguards: Tamper-Evident Records

• Append-Only Database Permissions: The MongoDB database role assigned to the application is restricted from issuing update or delete commands against the audit collection. Once an entry is written, it cannot be modified or purged by application code.
• Cryptographic Hash Chaining: Each audit entry contains a SHA-256 hash incorporating the hash of the preceding record and the current delta, creating a verifiable blockchain-style integrity log that immediately reveals unauthorized tampering.
• Zero Boilerplate: New developers joining the team write standard Mongoose operations without ever having to remember to log audit trails—the architecture handles compliance invisibly.