better-auth-audit-logs 0.1.0

package/dist/index.js

@@ -0,0 +1,522 @@
+// src/schema.ts
+import { mergeSchema } from "better-auth/db";
+var baseSchema = {
+  auditLog: {
+    modelName: "audit_log",
+    fields: {
+      userId: {
+        type: "string",
+        required: false,
+        references: {
+          model: "user",
+          field: "id",
+          onDelete: "set null"
+        },
+        index: true
+      },
+      action: {
+        type: "string",
+        required: true,
+        sortable: true,
+        index: true
+      },
+      status: {
+        type: "string",
+        required: true,
+        sortable: true
+      },
+      severity: {
+        type: "string",
+        required: true,
+        sortable: true
+      },
+      ipAddress: {
+        type: "string",
+        required: false
+      },
+      userAgent: {
+        type: "string",
+        required: false,
+        returned: false
+      },
+      metadata: {
+        type: "string",
+        required: false
+      },
+      createdAt: {
+        type: "date",
+        required: true,
+        sortable: true,
+        index: true,
+        defaultValue: () => new Date
+      }
+    }
+  }
+};
+function buildSchema(options) {
+  return mergeSchema(baseSchema, options?.schema);
+}
+function getModelName(options) {
+  return options?.schema?.auditLog?.modelName ?? "audit_log";
+}
+
+// src/hooks/before.ts
+import { createAuthMiddleware, getSessionFromCtx } from "better-auth/api";
+
+// src/utils/normalize-path.ts
+function normalizePath(path) {
+  return path.replace(/^\//, "").replace(/\//g, ":");
+}
+// src/utils/severity.ts
+var CRITICAL = ["ban-user", "impersonate-user"];
+var HIGH = [
+  "delete-user",
+  "delete-account",
+  "revoke-sessions",
+  "revoke-other-sessions"
+];
+var MEDIUM = [
+  "sign-in",
+  "sign-out",
+  "revoke-session",
+  "two-factor",
+  "change-password",
+  "reset-password"
+];
+function inferSeverity(action, status) {
+  if (CRITICAL.some((p) => action.includes(p)))
+    return "critical";
+  if (HIGH.some((p) => action.includes(p)))
+    return "high";
+  if (MEDIUM.some((p) => action.includes(p)))
+    return status === "failed" ? "high" : "medium";
+  return "low";
+}
+// src/utils/request-meta.ts
+import { getIp } from "better-auth/api";
+function extractRequestMeta(request, headers, options) {
+  return {
+    ipAddress: request ? getIp(request, options) ?? null : null,
+    userAgent: headers?.get("user-agent") ?? null
+  };
+}
+// src/utils/sanitize.ts
+var DEFAULT_PII_FIELDS = [
+  "password",
+  "newPassword",
+  "currentPassword",
+  "token",
+  "secret",
+  "apiKey",
+  "refreshToken",
+  "accessToken",
+  "code",
+  "backupCode",
+  "otp"
+];
+async function sha256(value) {
+  const encoded = new TextEncoder().encode(value);
+  const buffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function redactPII(data, config) {
+  if (!config.enabled)
+    return data;
+  const fields = config.fields ?? DEFAULT_PII_FIELDS;
+  const strategy = config.strategy ?? "mask";
+  const result = { ...data };
+  for (const field of fields) {
+    if (!(field in result) || result[field] == null)
+      continue;
+    if (strategy === "remove") {
+      delete result[field];
+    } else if (strategy === "hash") {
+      result[field] = await sha256(String(result[field]));
+    } else {
+      result[field] = "[REDACTED]";
+    }
+  }
+  return result;
+}
+// src/internal.ts
+async function buildLogEntry(path, status, params) {
+  const action = normalizePath(path);
+  const severity = params.pathConfig?.severity ?? inferSeverity(action, status);
+  const captureOpts = {
+    ...params.options.capture,
+    ...params.pathConfig?.capture
+  };
+  const { ipAddress, userAgent } = extractRequestMeta(captureOpts.ipAddress !== false ? params.request : undefined, captureOpts.userAgent !== false ? params.headers : undefined, params.authOptions);
+  let metadata = params.metadata ?? {};
+  if (params.options.piiRedaction.enabled) {
+    metadata = await redactPII(metadata, params.options.piiRedaction);
+  }
+  return {
+    userId: params.userId,
+    action,
+    status,
+    severity,
+    ipAddress,
+    userAgent,
+    metadata,
+    createdAt: new Date
+  };
+}
+async function buildLogEntryFromAction(action, status, params) {
+  const severity = inferSeverity(action, status);
+  const { ipAddress, userAgent } = extractRequestMeta(params.options.capture.ipAddress !== false ? params.request : undefined, params.options.capture.userAgent !== false ? params.headers : undefined, params.authOptions);
+  let metadata = params.metadata ?? {};
+  if (params.options.piiRedaction.enabled) {
+    metadata = await redactPII(metadata, params.options.piiRedaction);
+  }
+  return {
+    userId: params.userId,
+    action,
+    status,
+    severity,
+    ipAddress,
+    userAgent,
+    metadata,
+    createdAt: new Date
+  };
+}
+async function writeEntry(ctx, entry, opts, modelName) {
+  let finalEntry = entry;
+  if (opts.beforeLog) {
+    const modified = await opts.beforeLog(finalEntry);
+    if (modified === null)
+      return;
+    finalEntry = modified;
+  }
+  const doWrite = async () => {
+    let written;
+    if (opts.storage) {
+      written = { id: crypto.randomUUID(), ...finalEntry };
+      await opts.storage.write(written);
+    } else {
+      const record = await ctx.context.adapter.create({
+        model: modelName,
+        data: {
+          ...finalEntry,
+          metadata: JSON.stringify(finalEntry.metadata)
+        }
+      });
+      written = { ...record, metadata: finalEntry.metadata };
+    }
+    if (opts.afterLog)
+      await opts.afterLog(written);
+  };
+  if (opts.nonBlocking) {
+    ctx.context.runInBackground(doWrite().catch((err) => ctx.context.logger?.error("[audit-log] write failed", err)));
+  } else {
+    await doWrite();
+  }
+}
+
+// src/hooks/before.ts
+var BEFORE_PATHS = [
+  "/sign-out",
+  "/delete-user",
+  "/revoke-session",
+  "/revoke-sessions",
+  "/revoke-other-sessions"
+];
+function createBeforeHooks(opts, modelName) {
+  return [
+    {
+      matcher: (context) => !!context.path && BEFORE_PATHS.some((p) => context.path.startsWith(p)) && opts.shouldCapture(context.path),
+      handler: createAuthMiddleware(async (ctx) => {
+        try {
+          const session = await getSessionFromCtx(ctx);
+          const path = ctx.path;
+          const pathConfig = opts.getPathConfig(path);
+          const entry = await buildLogEntry(path, "success", {
+            userId: session?.user?.id ?? null,
+            request: ctx.request,
+            headers: ctx.headers,
+            pathConfig,
+            options: opts,
+            authOptions: ctx.context.options
+          });
+          await writeEntry(ctx, entry, opts, modelName);
+        } catch (err) {
+          ctx.context.logger?.error("[audit-log] before hook failed", err);
+        }
+      })
+    }
+  ];
+}
+// src/hooks/after.ts
+import { createAuthMiddleware as createAuthMiddleware2 } from "better-auth/api";
+function createAfterHooks(opts, modelName) {
+  return [
+    {
+      matcher: (context) => !!context.path && !BEFORE_PATHS.some((p) => context.path.startsWith(p)) && opts.shouldCapture(context.path),
+      handler: createAuthMiddleware2(async (ctx) => {
+        try {
+          const path = ctx.path;
+          const isError = ctx.context.returned instanceof Error;
+          const status = isError ? "failed" : "success";
+          const user = ctx.context.newSession?.user ?? ctx.context.session?.user;
+          const pathConfig = opts.getPathConfig(path);
+          const metadata = {};
+          if (opts.capture.requestBody && ctx.body) {
+            metadata.requestBody = ctx.body;
+          }
+          if (isError) {
+            const err = ctx.context.returned;
+            metadata.error = {
+              message: err.message,
+              ...err.status !== undefined && { status: err.status },
+              ...err.code !== undefined && { code: err.code }
+            };
+          }
+          const entry = await buildLogEntry(path, status, {
+            userId: user?.id ?? null,
+            request: ctx.request,
+            headers: ctx.headers,
+            metadata,
+            pathConfig,
+            options: opts,
+            authOptions: ctx.context.options
+          });
+          await writeEntry(ctx, entry, opts, modelName);
+        } catch (err) {
+          ctx.context.logger?.error("[audit-log] after hook failed", err);
+        }
+      })
+    }
+  ];
+}
+// src/endpoints/list-logs.ts
+import { createAuthEndpoint, sessionMiddleware, APIError } from "better-auth/api";
+import { z } from "zod";
+function createListLogsEndpoint(opts, modelName) {
+  return createAuthEndpoint("/audit-log/list", {
+    method: "GET",
+    use: [sessionMiddleware],
+    query: z.object({
+      userId: z.string().optional(),
+      action: z.string().optional(),
+      status: z.enum(["success", "failed"]).optional(),
+      from: z.string().optional(),
+      to: z.string().optional(),
+      limit: z.coerce.number().min(1).max(500).optional().default(50),
+      offset: z.coerce.number().min(0).optional().default(0)
+    })
+  }, async (ctx) => {
+    const session = ctx.context.session;
+    const targetUserId = ctx.query.userId ?? session.user.id;
+    if (targetUserId !== session.user.id) {
+      throw new APIError("FORBIDDEN", {
+        message: "Cannot query other users' audit logs"
+      });
+    }
+    const fromDate = ctx.query.from ? new Date(ctx.query.from) : undefined;
+    const toDate = ctx.query.to ? new Date(ctx.query.to) : undefined;
+    if (opts.storage?.read) {
+      const readOpts = {
+        userId: targetUserId,
+        action: ctx.query.action,
+        status: ctx.query.status,
+        from: fromDate,
+        to: toDate,
+        limit: ctx.query.limit,
+        offset: ctx.query.offset
+      };
+      const result = await opts.storage.read(readOpts);
+      return ctx.json(result);
+    }
+    const where = [{ field: "userId", value: targetUserId }];
+    if (ctx.query.action) {
+      where.push({ field: "action", value: ctx.query.action });
+    }
+    if (ctx.query.status) {
+      where.push({ field: "status", value: ctx.query.status });
+    }
+    if (fromDate) {
+      where.push({ field: "createdAt", operator: "gte", value: fromDate });
+    }
+    if (toDate) {
+      where.push({ field: "createdAt", operator: "lte", value: toDate });
+    }
+    const [entries, total] = await Promise.all([
+      ctx.context.adapter.findMany({
+        model: modelName,
+        where,
+        sortBy: { field: "createdAt", direction: "desc" },
+        limit: ctx.query.limit,
+        offset: ctx.query.offset
+      }),
+      ctx.context.adapter.count({ model: modelName, where })
+    ]);
+    const parsed = entries.map((e) => ({
+      ...e,
+      metadata: typeof e["metadata"] === "string" ? JSON.parse(e["metadata"]) : e["metadata"] ?? {}
+    }));
+    return ctx.json({ entries: parsed, total });
+  });
+}
+// src/endpoints/get-log.ts
+import { createAuthEndpoint as createAuthEndpoint2, sessionMiddleware as sessionMiddleware2, APIError as APIError2 } from "better-auth/api";
+function createGetLogEndpoint(opts, modelName) {
+  return createAuthEndpoint2("/audit-log/:id", { method: "GET", use: [sessionMiddleware2] }, async (ctx) => {
+    const { id } = ctx.params;
+    const session = ctx.context.session;
+    if (opts.storage?.readById) {
+      const entry2 = await opts.storage.readById(id);
+      if (!entry2 || entry2.userId !== session.user.id) {
+        throw new APIError2("NOT_FOUND", {
+          message: "Audit log entry not found"
+        });
+      }
+      return ctx.json(entry2);
+    }
+    const record = await ctx.context.adapter.findOne({
+      model: modelName,
+      where: [
+        { field: "id", value: id },
+        { field: "userId", value: session.user.id }
+      ]
+    });
+    if (!record) {
+      throw new APIError2("NOT_FOUND", {
+        message: "Audit log entry not found"
+      });
+    }
+    const entry = {
+      ...record,
+      metadata: typeof record["metadata"] === "string" ? JSON.parse(record["metadata"]) : record["metadata"] ?? {}
+    };
+    return ctx.json(entry);
+  });
+}
+// src/endpoints/insert-log.ts
+import { createAuthEndpoint as createAuthEndpoint3, sessionMiddleware as sessionMiddleware3 } from "better-auth/api";
+import { z as z2 } from "zod";
+function createInsertLogEndpoint(opts, modelName) {
+  return createAuthEndpoint3("/audit-log/insert", {
+    method: "POST",
+    use: [sessionMiddleware3],
+    body: z2.object({
+      action: z2.string().min(1),
+      status: z2.enum(["success", "failed"]).optional().default("success"),
+      severity: z2.enum(["low", "medium", "high", "critical"]).optional(),
+      metadata: z2.record(z2.string(), z2.unknown()).optional().default({})
+    })
+  }, async (ctx) => {
+    const session = ctx.context.session;
+    const { action, status, severity, metadata } = ctx.body;
+    const entry = await buildLogEntryFromAction(action, status, {
+      userId: session.user.id,
+      request: ctx.request,
+      headers: ctx.headers,
+      metadata,
+      options: opts,
+      authOptions: ctx.context.options
+    });
+    if (severity) {
+      entry.severity = severity;
+    }
+    await writeEntry(ctx, entry, opts, modelName);
+    return ctx.json({ success: true });
+  });
+}
+// src/plugin.ts
+function resolveOptions(options) {
+  const pathsMap = new Map;
+  const hasPaths = (options?.paths?.length ?? 0) > 0;
+  for (const p of options?.paths ?? []) {
+    if (typeof p === "string") {
+      pathsMap.set(p, undefined);
+    } else {
+      pathsMap.set(p.path, p.config);
+    }
+  }
+  return {
+    enabled: options?.enabled ?? true,
+    nonBlocking: options?.nonBlocking ?? false,
+    storage: options?.storage,
+    capture: {
+      ipAddress: options?.capture?.ipAddress ?? true,
+      userAgent: options?.capture?.userAgent ?? true,
+      requestBody: options?.capture?.requestBody ?? false
+    },
+    piiRedaction: {
+      enabled: options?.piiRedaction?.enabled ?? false,
+      fields: options?.piiRedaction?.fields,
+      strategy: options?.piiRedaction?.strategy ?? "mask"
+    },
+    retention: options?.retention,
+    beforeLog: options?.beforeLog,
+    afterLog: options?.afterLog,
+    shouldCapture: (path) => !hasPaths || pathsMap.has(path),
+    getPathConfig: (path) => pathsMap.get(path)
+  };
+}
+function auditLog(options) {
+  const schema = buildSchema(options);
+  const modelName = getModelName(options);
+  const resolved = resolveOptions(options);
+  const beforeHooks = resolved.enabled ? createBeforeHooks(resolved, modelName) : [];
+  const afterHooks = resolved.enabled ? createAfterHooks(resolved, modelName) : [];
+  return {
+    id: "audit-log",
+    schema,
+    hooks: {
+      before: beforeHooks,
+      after: afterHooks
+    },
+    endpoints: {
+      listAuditLogs: createListLogsEndpoint(resolved, modelName),
+      getAuditLog: createGetLogEndpoint(resolved, modelName),
+      insertAuditLog: createInsertLogEndpoint(resolved, modelName)
+    },
+    rateLimit: [
+      {
+        pathMatcher: (path) => path.startsWith("/audit-log/"),
+        window: 60,
+        max: 60
+      }
+    ]
+  };
+}
+// src/adapters/memory.ts
+class MemoryStorage {
+  entries = [];
+  async write(entry) {
+    this.entries.push(entry);
+  }
+  async read(opts) {
+    let filtered = this.entries.filter((e) => {
+      if (opts.userId !== undefined && e.userId !== opts.userId)
+        return false;
+      if (opts.action !== undefined && e.action !== opts.action)
+        return false;
+      if (opts.status !== undefined && e.status !== opts.status)
+        return false;
+      if (opts.from !== undefined && e.createdAt < opts.from)
+        return false;
+      if (opts.to !== undefined && e.createdAt > opts.to)
+        return false;
+      return true;
+    });
+    const total = filtered.length;
+    filtered = filtered.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime()).slice(opts.offset, opts.offset + opts.limit);
+    return { entries: filtered, total };
+  }
+  async readById(id) {
+    return this.entries.find((e) => e.id === id) ?? null;
+  }
+  async deleteOlderThan(date) {
+    const before = this.entries.length;
+    const retained = this.entries.filter((e) => e.createdAt >= date);
+    this.entries.length = 0;
+    this.entries.push(...retained);
+    return before - this.entries.length;
+  }
+}
+export {
+  auditLog,
+  MemoryStorage
+};

package/dist/internal.d.ts

@@ -0,0 +1,16 @@
+import type { GenericEndpointContext } from "@better-auth/core";
+import type { AuditLogEntry, AuditLogStatus, PathConfig, ResolvedOptions } from "./types";
+interface BuildParams {
+    userId: string | null;
+    request: Request | undefined;
+    headers: Headers | undefined;
+    metadata?: Record<string, unknown>;
+    pathConfig?: PathConfig;
+    options: ResolvedOptions;
+    authOptions: GenericEndpointContext["context"]["options"];
+}
+export declare function buildLogEntry(path: string, status: AuditLogStatus, params: BuildParams): Promise<Omit<AuditLogEntry, "id">>;
+export declare function buildLogEntryFromAction(action: string, status: AuditLogStatus, params: Omit<BuildParams, "pathConfig">): Promise<Omit<AuditLogEntry, "id">>;
+export declare function writeEntry(ctx: GenericEndpointContext, entry: Omit<AuditLogEntry, "id">, opts: ResolvedOptions, modelName: string): Promise<void>;
+export {};
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,eAAe,EAChB,MAAM,SAAS,CAAC;AAQjB,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC;CAC3D;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CA+BpC;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CAwBpC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,EAChC,IAAI,EAAE,eAAe,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAuCf"}