Registry / auth-security / better-auth-audit-logs

better-auth-audit-logs

JSON →
library0.3.0jsnpmunverified

This package, `better-auth-audit-logs`, provides a plug-in for the `better-auth` authentication library, designed to automatically capture and store authentication lifecycle events. It is currently at version 0.3.0 and appears to have a fairly active release cadence, with several minor versions released recently. Key features include automatic logging of auth events (like sign-in, sign-up, password changes) with associated metadata such as IP address and user agent, support for custom storage backends (Prisma, Drizzle, MongoDB examples are provided), and PII redaction capabilities. It differentiates itself by offering a zero-config setup for automatic event capture when integrated with `better-auth`, and exposing query endpoints for retrieving logs, including the ability to insert custom audit entries for non-auth related administrative actions. It relies on `better-auth` for its core functionality and `zod` for schema validation.

npm install better-auth-audit-logs
INSTALL
IMPORT
SIG · BETTER-AUTH-AUDIT-
B
better-auth-audit-logs
auth-securityjavascriptv0.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

auditLog
import { auditLog } from 'better-auth-audit-logs';
const { auditLog } = require('better-auth-audit-logs');
This is the primary server-side plugin factory for integrating with `better-auth`.
auditLogClient
import { auditLogClient } from 'better-auth-audit-logs/client';
import { auditLogClient } from 'better-auth-audit-logs';
The client-side plugin has a distinct import path to avoid bundling server-side code in browser environments.
AuditLogSchema
import type { AuditLogSchema } from 'better-auth-audit-logs';
Type import for the audit log entry structure. Available for both server and client contexts.

This quickstart demonstrates how to integrate the audit log plugin into a `better-auth` server instance and how to use its client-side capabilities to list existing logs and manually insert custom audit events.

import { betterAuth } from 'better-auth'; import { auditLog } from 'better-auth-audit-logs'; // Initialize Better Auth with the audit log plugin export const auth = betterAuth({ plugins: [auditLog()], // Assuming other Better Auth configurations here, e.g., adapters // adapter: someAdapter(...), }); // In a separate script or CLI for database migrations: // Make sure to have `@better-auth/cli` installed. // Run `npx @better-auth/cli generate` // This command will generate database migrations for the `auditLog` table. // Subsequently, run your database migration command (e.g., `npx prisma migrate dev` for Prisma). // Example of client-side usage (e.g., in a React component or API handler) import { createAuthClient } from 'better-auth/client'; import { auditLogClient } from 'better-auth-audit-logs/client'; const authClient = createAuthClient({ plugins: [auditLogClient()], }); async function fetchAuditLogs() { try { const { data } = await authClient.auditLog.listAuditLogs({ query: { status: 'failed', limit: 5, action: 'sign-in:email' }, }); console.log('Recent failed sign-ins:', data); await authClient.auditLog.insertAuditLog({ action: 'admin:user-delete', status: 'success', severity: 'high', metadata: { deletedUserId: 'user-xyz', adminId: 'admin-abc' }, }); console.log('Manually logged an admin action.'); } catch (error) { console.error('Error fetching or inserting audit logs:', error); } } // Call the function, typically triggered by a user action or on mount // fetchAuditLogs();
Debug
Known issues
breakingThe default `modelName` for the audit log table changed from `audit_log` to `auditLog` to improve compatibility with Prisma adapters.
fix
If you are using a non-Prisma adapter and have an existing `audit_log` table, explicitly set `schema.auditLog.modelName: "audit_log"` in your plugin configuration to maintain compatibility.
affects: >=0.2.0
gotchaRequires `better-auth >= 1.0.0` and `typescript >= 5`. Older versions of `better-auth` are not compatible and will likely lead to runtime errors due to API mismatches.
fix
Ensure your `better-auth` and `typescript` peer dependencies are up-to-date by running `npm install better-auth@latest typescript@^5`.
affects: >=0.1.0
gotchaThe audit log plugin adds an `auditLog` table to your database. You must run `npx @better-auth/cli generate` after installing to create the necessary migrations for your database adapter.
fix
After installing the plugin, execute `npx @better-auth/cli generate` and then apply the generated migrations using your ORM's migration tool (e.g., `npx prisma migrate dev`).
affects: >=0.1.0
gotchaThe client-side `auditLogClient` plugin must be imported from `better-auth-audit-logs/client`.
fix
Always use `import { auditLogClient } from 'better-auth-audit-logs/client';` for client-side functionality. Importing from the main package path will lead to bundling issues or runtime errors in browser environments.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Cannot find module 'better-auth-audit-logs/client'
Incorrect import path for the client-side plugin, or missing package installation.
fix
Ensure `better-auth-audit-logs` is installed and the client plugin is imported as `import { auditLogClient } from 'better-auth-audit-logs/client';`.
Error: 'auditLog' table not found or column missing in database.
Database migrations for the audit log schema have not been generated or applied.
fix
Run `npx @better-auth/cli generate` to create the migration files, then apply them using your ORM's migration command (e.g., `npx prisma migrate dev`).
TypeError: Cannot read properties of undefined (reading 'auditLog') on authClient
The `auditLogClient()` plugin was not correctly registered with `createAuthClient`.
fix
Ensure `auditLogClient()` is included in the `plugins` array when calling `createAuthClient({ plugins: [auditLogClient()] })`.
ZodError: Validation failed: Expected string, received undefined at 'action'
When manually inserting an audit log, a required field (like `action`, `status`, `severity`) was omitted or provided with an incorrect type.
fix
Review the `insertAuditLog` call and ensure all required fields are present and conform to the expected schema (e.g., `action: 'some-action'`, `status: 'success'`, `severity: 'low'`).
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies
better-authrequiredCore authentication library this package extends.
zodrequiredSchema validation for audit log entries.
typescriptrequiredType definitions are heavily utilized and `typescript >= 5` is required.
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
better-auth-audit-logs — npm install better-auth-audit-logs · libregistry