better-auth-audit-logs 0.1.0

package/dist/index.cjs

@@ -0,0 +1,564 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  auditLog: () => auditLog,
+  MemoryStorage: () => MemoryStorage
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/schema.ts
+var import_db = require("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 import_db.mergeSchema(baseSchema, options?.schema);
+}
+function getModelName(options) {
+  return options?.schema?.auditLog?.modelName ?? "audit_log";
+}
+
+// src/hooks/before.ts
+var import_api2 = require("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
+var import_api = require("better-auth/api");
+function extractRequestMeta(request, headers, options) {
+  return {
+    ipAddress: request ? import_api.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: import_api2.createAuthMiddleware(async (ctx) => {
+        try {
+          const session = await import_api2.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
+var import_api3 = require("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: import_api3.createAuthMiddleware(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
+var import_api4 = require("better-auth/api");
+var import_zod = require("zod");
+function createListLogsEndpoint(opts, modelName) {
+  return import_api4.createAuthEndpoint("/audit-log/list", {
+    method: "GET",
+    use: [import_api4.sessionMiddleware],
+    query: import_zod.z.object({
+      userId: import_zod.z.string().optional(),
+      action: import_zod.z.string().optional(),
+      status: import_zod.z.enum(["success", "failed"]).optional(),
+      from: import_zod.z.string().optional(),
+      to: import_zod.z.string().optional(),
+      limit: import_zod.z.coerce.number().min(1).max(500).optional().default(50),
+      offset: import_zod.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 import_api4.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
+var import_api5 = require("better-auth/api");
+function createGetLogEndpoint(opts, modelName) {
+  return import_api5.createAuthEndpoint("/audit-log/:id", { method: "GET", use: [import_api5.sessionMiddleware] }, 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 import_api5.APIError("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 import_api5.APIError("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
+var import_api6 = require("better-auth/api");
+var import_zod2 = require("zod");
+function createInsertLogEndpoint(opts, modelName) {
+  return import_api6.createAuthEndpoint("/audit-log/insert", {
+    method: "POST",
+    use: [import_api6.sessionMiddleware],
+    body: import_zod2.z.object({
+      action: import_zod2.z.string().min(1),
+      status: import_zod2.z.enum(["success", "failed"]).optional().default("success"),
+      severity: import_zod2.z.enum(["low", "medium", "high", "critical"]).optional(),
+      metadata: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.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;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { auditLog } from "./plugin";
+export { MemoryStorage } from "./adapters/memory";
+export type { AuditLogEntry, AuditLogOptions, AuditLogStorage, AuditLogStatus, AuditLogSeverity, StorageReadOptions, StorageReadResult, PIIRedactionOptions, CaptureOptions, PathConfig, RetentionConfig, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,SAAS,CAAC"}