Audit Logging | Bootspring Docs

Patterns for tracking user actions and system events for compliance and security.

Overview#

Audit logging creates a record of who did what and when. This pattern covers:

Audit log schema design
Logger service implementation
Automatic logging with Prisma middleware
API route auditing
Audit log viewer

Prerequisites#

npm install date-fns

Code Example#

Audit Log Schema#

// prisma/schema.prisma
model AuditLog {
  id          String   @id @default(cuid())
  timestamp   DateTime @default(now())
  userId      String?
  user        User?    @relation(fields: [userId], references: [id])
  action      String   // e.g., "user.create", "post.delete"
  entityType  String   // e.g., "User", "Post"
  entityId    String?
  oldValues   Json?
  newValues   Json?
  metadata    Json?    // IP, user agent, etc.
  status      String   @default("success") // success, failure
  errorMessage String?

  @@index([userId])
  @@index([entityType, entityId])
  @@index([action])
  @@index([timestamp])
}

Audit Logger Service#

// lib/audit/logger.ts
import { prisma } from '@/lib/db'
import { headers } from 'next/headers'

interface AuditContext {
  userId?: string
  ip?: string
  userAgent?: string
}

interface AuditEntry {
  action: string
  entityType: string
  entityId?: string
  oldValues?: Record<string, any>
  newValues?: Record<string, any>
  metadata?: Record<string, any>
  status?: 'success' | 'failure'
  errorMessage?: string
}

export class AuditLogger {
  private context: AuditContext

  constructor(context?: AuditContext) {
    this.context = context ?? {}
  }

  static async fromRequest(): Promise<AuditLogger> {
    const headersList = await headers()
    return new AuditLogger({
      ip: headersList.get('x-forwarded-for') ??
          headersList.get('x-real-ip') ??
          undefined,
      userAgent: headersList.get('user-agent') ?? undefined
    })
  }

  setUser(userId: string): this {
    this.context.userId = userId
    return this
  }

  async log(entry: AuditEntry): Promise<void> {
    await prisma.auditLog.create({
      data: {
        userId: this.context.userId,
        action: entry.action,
        entityType: entry.entityType,
        entityId: entry.entityId,
        oldValues: entry.oldValues,
        newValues: entry.newValues,
        status: entry.status ?? 'success',
        errorMessage: entry.errorMessage,
        metadata: {
          ...entry.metadata,
          ip: this.context.ip,
          userAgent: this.context.userAgent
        }
      }
    })
  }

  async logSuccess(entry: Omit<AuditEntry, 'status'>): Promise<void> {
    await this.log({ ...entry, status: 'success' })
  }

  async logFailure(
    entry: Omit<AuditEntry, 'status'>,
    error?: Error
  ): Promise<void> {
    await this.log({
      ...entry,
      status: 'failure',
      errorMessage: error?.message
    })
  }
}

// Singleton for simple usage
export const auditLog = new AuditLogger()

Audit Wrapper Function#

// lib/audit/decorator.ts
import { AuditLogger } from './logger'

interface AuditOptions {
  action: string
  entityType: string
  getEntityId?: (result: any) => string
  getOldValues?: () => Promise<Record<string, any>>
}

export function withAudit<T extends (...args: any[]) => Promise<any>>(
  fn: T,
  options: AuditOptions,
  getUserId: () => string | undefined
): T {
  return (async (...args: Parameters<T>) => {
    const logger = await AuditLogger.fromRequest()
    const userId = getUserId()

    if (userId) {
      logger.setUser(userId)
    }

    const oldValues = options.getOldValues
      ? await options.getOldValues()
      : undefined

    try {
      const result = await fn(...args)

      await logger.logSuccess({
        action: options.action,
        entityType: options.entityType,
        entityId: options.getEntityId?.(result),
        oldValues,
        newValues: result
      })

      return result
    } catch (error) {
      await logger.logFailure(
        {
          action: options.action,
          entityType: options.entityType,
          oldValues
        },
        error as Error
      )
      throw error
    }
  }) as T
}

// Usage
const createUserWithAudit = withAudit(
  async (data: { email: string; name: string }) => {
    return prisma.user.create({ data })
  },
  {
    action: 'user.create',
    entityType: 'User',
    getEntityId: (user) => user.id
  },
  () => getCurrentUserId()
)

Prisma Middleware for Automatic Auditing#

// lib/audit/prisma-middleware.ts
import { Prisma } from '@prisma/client'
import { prisma } from '@/lib/db'

const AUDITED_MODELS = ['User', 'Post', 'Team', 'Subscription']
const AUDITED_ACTIONS = ['create', 'update', 'delete']

export const auditMiddleware: Prisma.Middleware = async (params, next) => {
  const { model, action, args } = params

  if (!model || !AUDITED_MODELS.includes(model)) {
    return next(params)
  }

  if (!AUDITED_ACTIONS.includes(action)) {
    return next(params)
  }

  // Get old values for update/delete
  let oldValues: any = null
  if ((action === 'update' || action === 'delete') && args.where) {
    oldValues = await (prisma as any)[model.toLowerCase()].findUnique({
      where: args.where
    })
  }

  try {
    const result = await next(params)

    // Log successful operation
    await prisma.auditLog.create({
      data: {
        action: `${model.toLowerCase()}.${action}`,
        entityType: model,
        entityId: result?.id ?? args.where?.id,
        oldValues: oldValues ? JSON.parse(JSON.stringify(oldValues)) : null,
        newValues: action !== 'delete'
          ? JSON.parse(JSON.stringify(result))
          : null,
        status: 'success'
      }
    })

    return result
  } catch (error) {
    // Log failed operation
    await prisma.auditLog.create({
      data: {
        action: `${model.toLowerCase()}.${action}`,
        entityType: model,
        entityId: args.where?.id,
        oldValues: oldValues ? JSON.parse(JSON.stringify(oldValues)) : null,
        status: 'failure',
        errorMessage: error instanceof Error ? error.message : 'Unknown error'
      }
    })

    throw error
  }
}

// Register middleware
// prisma.$use(auditMiddleware)

API Route Auditing#

// lib/audit/route-wrapper.ts
import { NextRequest, NextResponse } from 'next/server'
import { AuditLogger } from './logger'
import { auth } from '@/auth'

type Handler = (req: NextRequest, context?: any) => Promise<NextResponse>

interface AuditRouteOptions {
  action: string
  entityType: string
  getEntityId?: (req: NextRequest, response: any) => string | undefined
}

export function auditedRoute(
  handler: Handler,
  options: AuditRouteOptions
): Handler {
  return async (req: NextRequest, context?: any) => {
    const logger = await AuditLogger.fromRequest()
    const session = await auth()

    if (session?.user?.id) {
      logger.setUser(session.user.id)
    }

    const startTime = Date.now()

    try {
      const response = await handler(req, context)
      const responseData = await response.clone().json().catch(() => null)

      await logger.logSuccess({
        action: options.action,
        entityType: options.entityType,
        entityId: options.getEntityId?.(req, responseData),
        metadata: {
          method: req.method,
          path: req.nextUrl.pathname,
          statusCode: response.status,
          duration: Date.now() - startTime
        }
      })

      return response
    } catch (error) {
      await logger.logFailure(
        {
          action: options.action,
          entityType: options.entityType,
          metadata: {
            method: req.method,
            path: req.nextUrl.pathname,
            duration: Date.now() - startTime
          }
        },
        error as Error
      )

      throw error
    }
  }
}

// Usage in app/api/users/[id]/route.ts
export const DELETE = auditedRoute(
  async (req, { params }) => {
    const user = await prisma.user.delete({
      where: { id: params.id }
    })
    return NextResponse.json({ success: true })
  },
  {
    action: 'user.delete',
    entityType: 'User',
    getEntityId: (req, _) => req.nextUrl.pathname.split('/').pop()
  }
)

Audit Log Viewer#

// app/admin/audit/page.tsx
import { prisma } from '@/lib/db'
import { formatDistanceToNow } from 'date-fns'

interface AuditLogFilters {
  userId?: string
  action?: string
  entityType?: string
  startDate?: Date
  endDate?: Date
}

async function getAuditLogs(filters: AuditLogFilters, page = 1, limit = 50) {
  const where: any = {}

  if (filters.userId) where.userId = filters.userId
  if (filters.action) where.action = { contains: filters.action }
  if (filters.entityType) where.entityType = filters.entityType
  if (filters.startDate || filters.endDate) {
    where.timestamp = {}
    if (filters.startDate) where.timestamp.gte = filters.startDate
    if (filters.endDate) where.timestamp.lte = filters.endDate
  }

  const [logs, total] = await Promise.all([
    prisma.auditLog.findMany({
      where,
      include: { user: { select: { name: true, email: true } } },
      orderBy: { timestamp: 'desc' },
      skip: (page - 1) * limit,
      take: limit
    }),
    prisma.auditLog.count({ where })
  ])

  return { logs, total, pages: Math.ceil(total / limit) }
}

export default async function AuditLogPage({
  searchParams
}: {
  searchParams: { page?: string }
}) {
  const page = parseInt(searchParams.page ?? '1')
  const { logs, total, pages } = await getAuditLogs({}, page)

  return (
    <div className="container py-8">
      <h1 className="text-2xl font-bold mb-6">Audit Logs</h1>

      <table className="w-full">
        <thead>
          <tr className="border-b">
            <th className="text-left py-2">Time</th>
            <th className="text-left py-2">User</th>
            <th className="text-left py-2">Action</th>
            <th className="text-left py-2">Entity</th>
            <th className="text-left py-2">Status</th>
          </tr>
        </thead>
        <tbody>
          {logs.map(log => (
            <tr key={log.id} className="border-b">
              <td className="py-2 text-sm text-gray-600">
                {formatDistanceToNow(log.timestamp, { addSuffix: true })}
              </td>
              <td className="py-2">
                {log.user?.name ?? log.user?.email ?? 'System'}
              </td>
              <td className="py-2">
                <code className="text-sm bg-gray-100 px-1 rounded">
                  {log.action}
                </code>
              </td>
              <td className="py-2">
                {log.entityType}
                {log.entityId && (
                  <span className="text-gray-500 text-sm ml-1">
                    #{log.entityId.slice(0, 8)}
                  </span>
                )}
              </td>
              <td className="py-2">
                <span
                  className={`px-2 py-0.5 rounded text-xs ${
                    log.status === 'success'
                      ? 'bg-green-100 text-green-800'
                      : 'bg-red-100 text-red-800'
                  }`}
                >
                  {log.status}
                </span>
              </td>
            </tr>
          ))}
        </tbody>
      </table>

      <div className="mt-4 text-sm text-gray-600">
        Showing {logs.length} of {total} logs
      </div>
    </div>
  )
}

Usage Instructions#

Create the AuditLog model in your Prisma schema
Use the AuditLogger service for manual logging
Register the Prisma middleware for automatic logging
Wrap API routes with the auditedRoute helper
Build an admin interface to view and search logs

Best Practices#

Log immutably - Never modify or delete audit logs
Include context - Log IP, user agent, and timestamps
Store old values - Capture state before changes
Use consistent actions - Follow a naming convention like entity.action
Index wisely - Add indexes for common query patterns
Retention policies - Archive old logs to reduce storage costs
Secure access - Restrict audit log viewing to admins only

Secrets Management - Track secret access
Monitoring - Application observability
Soft Delete - Keep deleted data for audit
RBAC - Control who can view audit logs