Registry / auth-security / better-auth-audit

better-auth-audit

library1.0.2jsnpmunverified

Audit log plugin for Better Auth, providing comprehensive tracking of authentication events such as sign-ins, sign-ups, password changes, and admin actions. Version 1.0.2, released with weekly cadence, supports automatic event capture, configurable storage backends, and query APIs. Differentiators include zero-config setup, typed audit events via Zod schemas, and seamless integration with Better Auth's middleware. Requires better-auth >=1.2.0 and zod >=3.0.0. Fully typed with TypeScript declarations.

auth-security observability

npm install better-auth-audit

package ↗homepage ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-AUDIT

better-auth-audit

auth-securityjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

auditLog

✓ import { auditLog } from 'better-auth-audit'

✗ const auditLog = require('better-auth-audit')

ESM-only; named export.

AuditLogOptions

✓ import type { AuditLogOptions } from 'better-auth-audit'

✗ import { AuditLogOptions } from 'better-auth-audit'

TypeScript only; use import type for type-only.

getAuditLogs

✓ import { getAuditLogs } from 'better-auth-audit'

✗ import { auditLog } from 'better-auth-audit'

Different function for querying logs.

Configures the audit log plugin with Better Auth, then fetches audit logs for a specific user.

import { betterAuth } from 'better-auth'; import { auditLog } from 'better-auth-audit'; export const auth = betterAuth({ plugins: [ auditLog({ storage: 'database', // or 'memory' events: ['signIn', 'signUp', 'signOut', 'passwordReset', 'adminAction'], excludePaths: ['/api/health'] }) ] }); // Later, fetch logs const { getAuditLogs } = await import('better-auth-audit'); const logs = await getAuditLogs({ userId: 'user_123', limit: 10 });

Debug

Known issues

breakingVersion 1.0.0 renamed 'eventTypes' option to 'events'. Old option is ignored.

fix

Use 'events' instead of 'eventTypes' in plugin options.

affects: >=1.0.0 <1.0.0

deprecatedThe 'memory' storage backend is deprecated and will be removed in v2.0.

fix

Migrate to 'database' storage with a persistent adapter.

affects: >=1.0.0 <2.0.0

gotchaIf you exclude paths using excludePaths, the plugin will not emit events for those paths. Common mistake: forgetting to include paths like '/api/auth/callback'

fix

Review your excluded paths and ensure authentication callback paths are not excluded.

affects: >=0.0.0

gotchaThe audit log schema uses Zod, so you must install zod even if you don't directly import it.

fix

Ensure zod is in your dependencies.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'auditLog')

Forgetting to import the plugin's named export correctly or using an older version where the export was different.

fix

Update to >=1.0.0 and use named import: import { auditLog } from 'better-auth-audit';

Error: Plugin 'auditLog' is not a valid Better Auth plugin.

The plugin may not be properly initialized or the version of better-auth is incompatible.

fix

Check that better-auth version is ^1.2.0 and that you passed the plugin inside the plugins array.

ZodError: [ { code: 'invalid_type', expected: 'string', received: 'undefined' } ]

Missing required fields in a custom audit event or misconfigured options.

fix

Ensure all required fields (actorId, action, resource) are provided when emitting custom events.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

better-authrequiredpeer dependency: core auth framework

zodrequiredpeer dependency: schema validation for audit events

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/better-auth-audit ↗

homepagehttps://better-auth.com ↗