convex-audit-log 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,93 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+/**
+ * Severity levels for audit events.
+ * - info: Regular operations (login, profile update)
+ * - warning: Potentially concerning actions (password change, permission change)
+ * - error: Failed operations or errors
+ * - critical: Security-sensitive events (unauthorized access attempts, data breaches)
+ */
+export const vSeverity = v.union(
+  v.literal("info"),
+  v.literal("warning"),
+  v.literal("error"),
+  v.literal("critical")
+);
+
+export type Severity = "info" | "warning" | "error" | "critical";
+
+export default defineSchema({
+  /**
+   * Main audit log table storing all audit events.
+   */
+  auditLogs: defineTable({
+    // Core event data
+    action: v.string(),
+    actorId: v.optional(v.string()),
+    timestamp: v.number(),
+
+    // Resource tracking
+    resourceType: v.optional(v.string()),
+    resourceId: v.optional(v.string()),
+
+    // Event metadata
+    metadata: v.optional(v.any()),
+    severity: vSeverity,
+
+    // Context information
+    ipAddress: v.optional(v.string()),
+    userAgent: v.optional(v.string()),
+    sessionId: v.optional(v.string()),
+
+    // Compliance tags
+    tags: v.optional(v.array(v.string())),
+
+    // Change tracking
+    before: v.optional(v.any()),
+    after: v.optional(v.any()),
+    diff: v.optional(v.string()),
+
+    // Retention category for cleanup policies
+    retentionCategory: v.optional(v.string()),
+  })
+    // Query by action type with time ordering
+    .index("by_action_timestamp", ["action", "timestamp"])
+    // Query by actor (user) with time ordering
+    .index("by_actor_timestamp", ["actorId", "timestamp"])
+    // Query by resource with time ordering
+    .index("by_resource", ["resourceType", "resourceId", "timestamp"])
+    // Query by severity level with time ordering
+    .index("by_severity_timestamp", ["severity", "timestamp"])
+    // Query by timestamp for time-range queries
+    .index("by_timestamp", ["timestamp"])
+    // Query by retention category for cleanup
+    .index("by_retention_timestamp", ["retentionCategory", "timestamp"]),
+
+  /**
+   * Configuration table for component settings.
+   * Contains a single document with global configuration.
+   */
+  config: defineTable({
+    // Retention settings
+    defaultRetentionDays: v.number(),
+    criticalRetentionDays: v.number(),
+
+    // PII redaction settings
+    piiFieldsToRedact: v.array(v.string()),
+
+    // Sampling settings (for high-volume apps)
+    samplingEnabled: v.boolean(),
+    samplingRate: v.number(), // 0.0 to 1.0
+
+    // Custom retention categories
+    customRetention: v.optional(
+      v.array(
+        v.object({
+          category: v.string(),
+          retentionDays: v.number(),
+        })
+      )
+    ),
+  }),
+});

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import schema from "./schema.js";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/component/shared.ts

@@ -0,0 +1,167 @@
+import { v } from "convex/values";
+import type { Infer } from "convex/values";
+
+/**
+ * Severity levels for audit events.
+ */
+export const vSeverity = v.union(
+  v.literal("info"),
+  v.literal("warning"),
+  v.literal("error"),
+  v.literal("critical")
+);
+
+/**
+ * Base audit event validator (without timestamp - added automatically).
+ */
+export const vAuditEventInput = v.object({
+  action: v.string(),
+  actorId: v.optional(v.string()),
+  resourceType: v.optional(v.string()),
+  resourceId: v.optional(v.string()),
+  metadata: v.optional(v.any()),
+  severity: vSeverity,
+  ipAddress: v.optional(v.string()),
+  userAgent: v.optional(v.string()),
+  sessionId: v.optional(v.string()),
+  tags: v.optional(v.array(v.string())),
+  retentionCategory: v.optional(v.string()),
+});
+
+/**
+ * Change tracking event validator.
+ */
+export const vChangeEventInput = v.object({
+  action: v.string(),
+  actorId: v.optional(v.string()),
+  resourceType: v.string(),
+  resourceId: v.string(),
+  before: v.optional(v.any()),
+  after: v.optional(v.any()),
+  generateDiff: v.optional(v.boolean()),
+  severity: v.optional(vSeverity),
+  ipAddress: v.optional(v.string()),
+  userAgent: v.optional(v.string()),
+  sessionId: v.optional(v.string()),
+  tags: v.optional(v.array(v.string())),
+  retentionCategory: v.optional(v.string()),
+});
+
+/**
+ * Query filters validator.
+ */
+export const vQueryFilters = v.object({
+  severity: v.optional(v.array(vSeverity)),
+  actions: v.optional(v.array(v.string())),
+  resourceTypes: v.optional(v.array(v.string())),
+  actorIds: v.optional(v.array(v.string())),
+  fromTimestamp: v.optional(v.number()),
+  toTimestamp: v.optional(v.number()),
+  tags: v.optional(v.array(v.string())),
+});
+
+/**
+ * Pagination validator.
+ */
+export const vPagination = v.object({
+  cursor: v.optional(v.string()),
+  limit: v.number(),
+});
+
+/**
+ * Report format validator.
+ */
+export const vReportFormat = v.union(
+  v.literal("json"),
+  v.literal("csv")
+);
+
+/**
+ * Anomaly pattern validator.
+ */
+export const vAnomalyPattern = v.object({
+  action: v.string(),
+  threshold: v.number(),
+  windowMinutes: v.number(),
+});
+
+/**
+ * Cleanup options validator.
+ */
+export const vCleanupOptions = v.object({
+  olderThanDays: v.optional(v.number()),
+  preserveSeverity: v.optional(v.array(vSeverity)),
+  retentionCategory: v.optional(v.string()),
+  batchSize: v.optional(v.number()),
+});
+
+/**
+ * Configuration options validator.
+ */
+export const vConfigOptions = v.object({
+  defaultRetentionDays: v.optional(v.number()),
+  criticalRetentionDays: v.optional(v.number()),
+  piiFieldsToRedact: v.optional(v.array(v.string())),
+  samplingEnabled: v.optional(v.boolean()),
+  samplingRate: v.optional(v.number()),
+  customRetention: v.optional(
+    v.array(
+      v.object({
+        category: v.string(),
+        retentionDays: v.number(),
+      })
+    )
+  ),
+});
+
+export type Severity = Infer<typeof vSeverity>;
+export type AuditEventInput = Infer<typeof vAuditEventInput>;
+export type ChangeEventInput = Infer<typeof vChangeEventInput>;
+export type QueryFilters = Infer<typeof vQueryFilters>;
+export type Pagination = Infer<typeof vPagination>;
+export type ReportFormat = Infer<typeof vReportFormat>;
+export type AnomalyPattern = Infer<typeof vAnomalyPattern>;
+export type CleanupOptions = Infer<typeof vCleanupOptions>;
+export type ConfigOptions = Infer<typeof vConfigOptions>;
+
+/**
+ * Full audit event with generated fields.
+ */
+export type AuditEvent = AuditEventInput & {
+  _id: string;
+  _creationTime: number;
+  timestamp: number;
+  before?: unknown;
+  after?: unknown;
+  diff?: string;
+};
+
+/**
+ * Paginated result type.
+ */
+export type PaginatedResult<T> = {
+  items: T[];
+  cursor: string | null;
+  hasMore: boolean;
+};
+
+/**
+ * Anomaly detection result.
+ */
+export type Anomaly = {
+  action: string;
+  count: number;
+  threshold: number;
+  windowMinutes: number;
+  detectedAt: number;
+};
+
+/**
+ * Report result type.
+ */
+export type Report = {
+  format: ReportFormat;
+  data: string;
+  generatedAt: number;
+  recordCount: number;
+};

package/src/react/index.ts

@@ -0,0 +1,305 @@
+"use client";
+
+import { useQuery } from "convex/react";
+import type { FunctionReference } from "convex/server";
+
+export type Severity = "info" | "warning" | "error" | "critical";
+
+export interface AuditLogEntry {
+  _id: string;
+  _creationTime: number;
+  action: string;
+  actorId?: string;
+  timestamp: number;
+  resourceType?: string;
+  resourceId?: string;
+  metadata?: unknown;
+  severity: Severity;
+  ipAddress?: string;
+  userAgent?: string;
+  sessionId?: string;
+  tags?: string[];
+  before?: unknown;
+  after?: unknown;
+  diff?: string;
+  retentionCategory?: string;
+}
+
+export interface AuditLogStats {
+  totalCount: number;
+  bySeverity: {
+    info: number;
+    warning: number;
+    error: number;
+    critical: number;
+  };
+  topActions: { action: string; count: number }[];
+  topActors: { actorId: string; count: number }[];
+}
+
+export interface Anomaly {
+  action: string;
+  count: number;
+  threshold: number;
+  windowMinutes: number;
+  detectedAt: number;
+}
+
+/**
+ * Hook to query audit logs by resource.
+ * Provides real-time updates when the audit log changes.
+ *
+ * @example
+ * ```tsx
+ * import { useAuditLogByResource } 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}>
+ *           {log.action} by {log.actorId} at {new Date(log.timestamp).toLocaleString()}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useAuditLogByResource(
+  queryRef: FunctionReference<
+    "query",
+    "public",
+    { resourceType: string; resourceId: string; limit?: number; fromTimestamp?: number },
+    AuditLogEntry[]
+  >,
+  args: {
+    resourceType: string;
+    resourceId: string;
+    limit?: number;
+    fromTimestamp?: number;
+  }
+): AuditLogEntry[] | undefined {
+  return useQuery(queryRef, args);
+}
+
+/**
+ * Hook to query audit logs by actor (user).
+ *
+ * @example
+ * ```tsx
+ * import { useAuditLogByActor } from "convex-audit-log/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function UserActivity({ userId }: { userId: string }) {
+ *   const logs = useAuditLogByActor(api.auditLog.queryByActor, {
+ *     actorId: userId,
+ *     limit: 50,
+ *   });
+ *
+ *   if (!logs) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {logs.map((log) => (
+ *         <li key={log._id}>{log.action}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useAuditLogByActor(
+  queryRef: FunctionReference<
+    "query",
+    "public",
+    { actorId: string; limit?: number; fromTimestamp?: number; actions?: string[] },
+    AuditLogEntry[]
+  >,
+  args: {
+    actorId: string;
+    limit?: number;
+    fromTimestamp?: number;
+    actions?: string[];
+  }
+): AuditLogEntry[] | undefined {
+  return useQuery(queryRef, args);
+}
+
+/**
+ * Hook to watch critical events in real-time.
+ *
+ * @example
+ * ```tsx
+ * import { useWatchCriticalEvents } from "convex-audit-log/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function SecurityAlerts() {
+ *   const criticalEvents = useWatchCriticalEvents(api.auditLog.watchCritical, {
+ *     limit: 10,
+ *   });
+ *
+ *   if (!criticalEvents) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div className="alerts">
+ *       {criticalEvents.map((event) => (
+ *         <div key={event._id} className={`alert alert-${event.severity}`}>
+ *           {event.action}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useWatchCriticalEvents(
+  queryRef: FunctionReference<
+    "query",
+    "public",
+    { severity?: Severity[]; limit?: number },
+    AuditLogEntry[]
+  >,
+  args?: {
+    severity?: Severity[];
+    limit?: number;
+  }
+): AuditLogEntry[] | undefined {
+  return useQuery(queryRef, args ?? {});
+}
+
+/**
+ * Hook to get audit log statistics.
+ *
+ * @example
+ * ```tsx
+ * import { useAuditLogStats } from "convex-audit-log/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function Dashboard() {
+ *   const stats = useAuditLogStats(api.auditLog.getStats, {
+ *     fromTimestamp: Date.now() - 24 * 60 * 60 * 1000, // Last 24 hours
+ *   });
+ *
+ *   if (!stats) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>Total Events: {stats.totalCount}</h2>
+ *       <div>Critical: {stats.bySeverity.critical}</div>
+ *       <div>Errors: {stats.bySeverity.error}</div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAuditLogStats(
+  queryRef: FunctionReference<
+    "query",
+    "public",
+    { fromTimestamp?: number; toTimestamp?: number },
+    AuditLogStats
+  >,
+  args?: {
+    fromTimestamp?: number;
+    toTimestamp?: number;
+  }
+): AuditLogStats | undefined {
+  return useQuery(queryRef, args ?? {});
+}
+
+/**
+ * Hook to detect anomalies in real-time.
+ *
+ * @example
+ * ```tsx
+ * import { useAnomalyDetection } from "convex-audit-log/react";
+ * import { api } from "../convex/_generated/api";
+ *
+ * function AnomalyMonitor() {
+ *   const anomalies = useAnomalyDetection(api.auditLog.detectAnomalies, {
+ *     patterns: [
+ *       { action: "user.login.failed", threshold: 5, windowMinutes: 5 },
+ *       { action: "record.deleted", threshold: 10, windowMinutes: 1 },
+ *     ],
+ *   });
+ *
+ *   if (!anomalies) return <div>Loading...</div>;
+ *   if (anomalies.length === 0) return <div>No anomalies detected</div>;
+ *
+ *   return (
+ *     <div className="anomalies">
+ *       {anomalies.map((anomaly, i) => (
+ *         <div key={i} className="anomaly-alert">
+ *           {anomaly.action}: {anomaly.count} events in {anomaly.windowMinutes} minutes
+ *           (threshold: {anomaly.threshold})
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAnomalyDetection(
+  queryRef: FunctionReference<
+    "query",
+    "public",
+    { patterns: { action: string; threshold: number; windowMinutes: number }[] },
+    Anomaly[]
+  >,
+  args: {
+    patterns: { action: string; threshold: number; windowMinutes: number }[];
+  }
+): Anomaly[] | undefined {
+  return useQuery(queryRef, args);
+}
+
+/**
+ * Formats a timestamp to a human-readable string.
+ */
+export function formatTimestamp(timestamp: number): string {
+  return new Date(timestamp).toLocaleString();
+}
+
+/**
+ * Returns a CSS class name based on severity.
+ */
+export function getSeverityClass(severity: Severity): string {
+  switch (severity) {
+    case "critical":
+      return "audit-severity-critical";
+    case "error":
+      return "audit-severity-error";
+    case "warning":
+      return "audit-severity-warning";
+    case "info":
+    default:
+      return "audit-severity-info";
+  }
+}
+
+/**
+ * Returns a color based on severity (for inline styles).
+ */
+export function getSeverityColor(severity: Severity): string {
+  switch (severity) {
+    case "critical":
+      return "#dc2626"; // red-600
+    case "error":
+      return "#ea580c"; // orange-600
+    case "warning":
+      return "#ca8a04"; // yellow-600
+    case "info":
+    default:
+      return "#2563eb"; // blue-600
+  }
+}

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "auditLog",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };