Audit Log

The audit_logs collection in MongoDB is the canonical record of "who did what, when." Every workspace mutation that crosses an RBAC boundary should produce an entry.

Schema#

interface AuditLog {
  _id: ObjectId;
  eventType: string;               // e.g. "webinars.bulk-invite", "user_role_changed", "rate_limit_exceeded"
  userId?: string | ObjectId;      // Clerk userId for human actions; ObjectId for system actions
  ip: string;                      // from x-forwarded-for, or "webhook" / "system"
  userAgent: string;
  resource?: string;               // e.g. "webinar:matters-2026-spring", "collection:whitepaper_leads"
  action?: string;                 // typically mirrors eventType for query convenience
  result: "success" | "failure";
  metadata?: Record<string, any>;  // shape-specific
  timestamp: Date;                 // when the event happened
}

Defined in types/auth.ts; collection accessed via getDb().collection<AuditLog>("audit_logs").

Writers#

• auditMutation(opts, req) from @/lib/security/api-guards — the ergonomic helper used by workspace mutation routes.
• logAuditEvent(event) from @/lib/security/audit — the underlying primitive.

Failures are swallowed. Audit logging is best-effort and must never break the handler — if Mongo's down, we don't want every mutation to 500 because the audit write timed out.

Critical event types#

These auto-trigger a console alert in sendSecurityAlert(). Future: wire to Slack + email.

The full list is CRITICAL_EVENTS in lib/security/audit.ts.

Query patterns#

Recent events for a specific user#

import { getAuditLogs } from "@/lib/security/audit";

const events = await getAuditLogs({
  userId: "user_2abc…",
  limit: 50,
});

Recent rate-limit breaches#

const breaches = await getAuditLogs({
  eventType: "rate_limit_exceeded",
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
});

All actions on a specific resource#

There's no resource filter helper today; query directly:

const db = await getDb();
const events = await db
  .collection<AuditLog>("audit_logs")
  .find({ resource: "webinar:matters-2026-spring" })
  .sort({ timestamp: -1 })
  .limit(100)
  .toArray();

If you find yourself wanting this query often, add a resource parameter to getAuditLogs.

Retention#

No retention runs automatically. A cleanupOldAuditLogs() helper exists in lib/security/audit.ts (deletes entries older than 90 days), but nothing schedules it, so the collection grows unbounded in practice. Recommendation for production:

• Set a TTL index on timestamp with a 365-day expiry for most event types.
• Archive permission_escalation_attempt and user_role_changed to cold storage indefinitely (legal / compliance).

db.audit_logs.createIndex(
  { timestamp: 1 },
  { expireAfterSeconds: 365 * 24 * 60 * 60 }
);

Performance#

The audit_logs collection is append-only in the happy path. Indexes worth having:

• { userId: 1, timestamp: -1 } — user history queries.
• { eventType: 1, timestamp: -1 } — alert dashboards.
• { resource: 1, timestamp: -1 } — per-resource audit trail.
• TTL on timestamp (see retention above).

Today no indexes are created automatically. Tracked in PROD_CHECKLIST.md.

Read access#

Currently the audit log is read by the workspace /system module (super_admin only). If a new role needs read access, scope it tightly — these logs contain PII (registrant emails, WordPress page slugs that may reveal product features pre-launch, etc.).