Audit Log

Copy codenpm install convex-audit-log

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import auditLog from "convex-audit-log/convex.config.js";

const app = defineApp();
app.use(auditLog);

export default app;

Copy code// convex/auditLog.ts
import { AuditLog } from "convex-audit-log";
import { components } from "./_generated/api";

export const auditLog = new AuditLog(components.auditLog, {
  // Optional: Configure PII fields to automatically redact
  piiFields: ["email", "phone", "ssn", "password"],
});

Copy codeimport { mutation } from "./_generated/server";
import { auditLog } from "./auditLog";

export const updateUserProfile = mutation({
  args: { userId: v.id("users"), name: v.string(), email: v.string() },
  handler: async (ctx, args) => {
    // Get current state
    const before = await ctx.db.get(args.userId);

    // Perform the update
    await ctx.db.patch(args.userId, { name: args.name, email: args.email });

    // Get new state
    const after = await ctx.db.get(args.userId);

    // Log the change with automatic diff
    await auditLog.logChange(ctx, {
      action: "user.profile.updated",
      actorId: ctx.auth.getUserIdentity()?.subject,
      resourceType: "users",
      resourceId: args.userId,
      before,
      after,
      generateDiff: true,
      severity: "info",
    });

    return after;
  },
});

Copy codeimport { query } from "./_generated/server";
import { auditLog } from "./auditLog";

// Get all changes to a specific document
export const getDocumentHistory = query({
  args: { documentId: v.string() },
  handler: async (ctx, args) => {
    return await auditLog.queryByResource(ctx, {
      resourceType: "documents",
      resourceId: args.documentId,
      limit: 50,
    });
  },
});

// Get all actions by a specific user
export const getUserActivity = query({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return await auditLog.queryByActor(ctx, {
      actorId: args.userId,
      limit: 50,
    });
  },
});

// Watch for critical security events
export const watchSecurityEvents = query({
  handler: async (ctx) => {
    return await auditLog.watchCritical(ctx, {
      severity: ["warning", "error", "critical"],
      limit: 20,
    });
  },
});

Copy codeawait auditLog.log(ctx, {
  action: "user.login",
  actorId: userId,
  severity: "info",
  metadata: { method: "password" },
  tags: ["authentication"],
});

Copy codeawait auditLog.logChange(ctx, {
  action: "document.updated",
  actorId: userId,
  resourceType: "documents",
  resourceId: docId,
  before: { title: "Old Title" },
  after: { title: "New Title" },
  generateDiff: true, // Automatically generate diff
  severity: "info",
});

Copy codeawait auditLog.logBulk(ctx, [
  { action: "document.created", severity: "info", ... },
  { action: "notification.sent", severity: "info", ... },
]);

Copy codeconst history = await auditLog.queryByResource(ctx, {
  resourceType: "documents",
  resourceId: docId,
  limit: 50,
  fromTimestamp: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last 7 days
});

Copy codeconst activity = await auditLog.queryByActor(ctx, {
  actorId: userId,
  limit: 50,
  actions: ["user.login", "user.logout"], // Optional filter
});

Copy codeconst results = await auditLog.search(ctx, {
  filters: {
    severity: ["warning", "error", "critical"],
    actions: ["user.login.failed"],
    fromTimestamp: Date.now() - 24 * 60 * 60 * 1000,
    tags: ["security"],
  },
  pagination: { limit: 100 },
});

Copy codeconst criticalEvents = await auditLog.watchCritical(ctx, {
  severity: ["error", "critical"],
  limit: 20,
});

Copy codeconst stats = await auditLog.getStats(ctx, {
  fromTimestamp: Date.now() - 24 * 60 * 60 * 1000,
});
// Returns: { totalCount, bySeverity, topActions, topActors }

Copy codeconst anomalies = await auditLog.detectAnomalies(ctx, [
  { action: "user.login.failed", threshold: 5, windowMinutes: 5 },
  { action: "record.deleted", threshold: 50, windowMinutes: 60 },
]);

Copy codeconst report = await auditLog.generateReport(ctx, {
  startDate: startOfMonth,
  endDate: endOfMonth,
  format: "csv", // or "json"
  includeFields: ["timestamp", "action", "actorId", "resourceType"],
  groupBy: "action",
});

Copy codeconst deletedCount = await auditLog.cleanup(ctx, {
  olderThanDays: 90,
  preserveSeverity: ["critical"], // Keep critical events forever
  batchSize: 100,
});

Copy codeimport {
  useAuditLogByResource,
  useWatchCriticalEvents,
  useAuditLogStats,
  formatTimestamp,
  getSeverityColor,
} from "convex-audit-log/react";
import { api } from "../convex/_generated/api";

function DocumentHistory({ documentId }: { documentId: string }) {
  const logs = useAuditLogByResource(api.auditLog.queryByResource, {
    resourceType: "documents",
    resourceId: documentId,
    limit: 20,
  });

  if (!logs) return <div>Loading...</div>;

  return (
    <ul>
      {logs.map((log) => (
        <li key={log._id} style={{ borderLeftColor: getSeverityColor(log.severity) }}>
          <strong>{log.action}</strong>
          <span>{formatTimestamp(log.timestamp)}</span>
        </li>
      ))}
    </ul>
  );
}

Copy codeimport { AuditActions } from "convex-audit-log";

await auditLog.log(ctx, {
  action: AuditActions.USER_LOGIN,
  // ...
});

Copy code// convex/auditLog.ts
import { exposeAuditLogApi } from "convex-audit-log";
import { components } from "./_generated/api";

export const {
  queryByResource,
  queryByActor,
  getStats,
  watchCritical,
} = exposeAuditLogApi(components.auditLog, {
  auth: async (ctx, operation) => {
    const userId = await getAuthUserId(ctx);
    if (!userId && operation.type !== "read") {
      throw new Error("Unauthorized");
    }
    return userId;
  },
});

Copy codeimport { test } from "vitest";
import { convexTest } from "convex-test";
import auditLogComponent from "convex-audit-log/test";
import schema from "./schema";

test("audit logging", async () => {
  const t = convexTest(schema);
  auditLogComponent.register(t);

  await t.run(async (ctx) => {
    // Test your audit log functionality
  });
});

Copy codenpm install
npm run dev