@checodo/better-auth-audit-log 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1478 @@
+import { t as AUDIT_LOG_ERROR_CODES } from "./error-codes-B9Frh9bu.js";
+import { mergeSchema } from "better-auth/db";
+import { getCurrentAdapter, queueAfterTransactionHook, runWithAdapter, tryGetCurrentAuthEndpointContext } from "@better-auth/core/context";
+import { isAPIError } from "@better-auth/core/utils/is-api-error";
+import { APIError, createAuthEndpoint, createAuthMiddleware, getSessionFromCtx, sessionMiddleware } from "better-auth/api";
+import { getIP } from "@better-auth/core/utils/ip";
+import * as z from "zod";
+// package.json
+var version = "0.1.0";
+// src/utils/method.ts
+/**
+* How a user signed in or up, from the endpoint that did it:
+* `/sign-in/email` → `email`, `/callback/github` → `github`,
+* `/magic-link/verify` → `magic-link`, `/two-factor/verify-totp` → `two-factor`.
+*/
+function signInMethod(path, params, body) {
+	const provider = params?.id ?? params?.providerId;
+	if (typeof provider === "string" && provider) return provider;
+	if (!path) return null;
+	if (path === "/sign-in/social" && typeof body?.provider === "string") return body.provider;
+	const [first, second] = path.split("/").filter(Boolean);
+	if ((first === "sign-in" || first === "sign-up") && second) return second;
+	return first ?? null;
+}
+// src/hooks/database.ts
+/** Endpoints that verify an email address (not OAuth sign-ins, which rewrite the flag). */
+const VERIFY_EMAIL_PATHS = /* @__PURE__ */ new Set(["/verify-email", "/email-otp/verify-email"]);
+/**
+* How long a new user's id is remembered, so the account created with the
+* user (same request, milliseconds later) isn't recorded as a link.
+*/
+const NEW_USER_TTL = 1e4;
+/**
+* The user an update is for, as far as the request tells: the target of
+* the admin plugin's `updateUser`, otherwise the signed-in user (the
+* two-factor plugin changes the user's own setting).
+*/
+function updatedUserId(context) {
+	if (context.path === "/admin/update-user") {
+		const userId = context.body?.userId;
+		return typeof userId === "string" ? userId : null;
+	}
+	return context.context.session?.user.id ?? null;
+}
+/**
+* Events about users and accounts, recorded however they happen (any
+* endpoint, any plugin, server-side calls): sign-ups, deleted users,
+* linked accounts, changed and verified emails, two-factor turned on or off.
+*/
+function createDatabaseHooks(authContext, recorder) {
+	const contextFor = (context) => context?.context ?? authContext;
+	const headersOf = (context) => context?.request?.headers ?? context?.headers ?? null;
+	/** The signed-in user acting, e.g. an admin; `fallback` when nobody is signed in. */
+	const actor = (context, fallback) => context?.context.session?.user.id ?? fallback;
+	const newUsers = /* @__PURE__ */ new Map();
+	const rememberNewUser = (userId) => {
+		const now = Date.now();
+		for (const [id, at] of newUsers) if (now - at > NEW_USER_TTL) newUsers.delete(id);
+		newUsers.set(userId, now);
+	};
+	const wasJustCreated = (userId) => {
+		const at = newUsers.get(userId);
+		newUsers.delete(userId);
+		return at !== void 0 && Date.now() - at <= NEW_USER_TTL;
+	};
+	const pendingUpdates = /* @__PURE__ */ new WeakMap();
+	const record = (context, details) => recorder.record(contextFor(context), details, headersOf(context));
+	return {
+		user: {
+			create: { after: async (user, context) => {
+				rememberNewUser(user.id);
+				await record(context, {
+					type: "sign-up",
+					userId: user.id,
+					actorUserId: actor(context, user.id),
+					metadata: { method: signInMethod(context?.path, context?.params, context?.body) }
+				});
+			} },
+			update: {
+				before: async (data, context) => {
+					if (!context) return;
+					const flags = {
+						emailChanged: null,
+						emailVerified: false,
+						twoFactor: null,
+						twoFactorUserId: null
+					};
+					try {
+						if (typeof data.email === "string") {
+							const email = data.email.toLowerCase();
+							if (!await (await getCurrentAdapter(contextFor(context).adapter)).findOne({
+								model: "user",
+								where: [{
+									field: "email",
+									value: email
+								}]
+							})) flags.emailChanged = email;
+						}
+						flags.emailVerified = !flags.emailChanged && data.emailVerified === true && VERIFY_EMAIL_PATHS.has(context.path ?? "");
+						const twoFactorUserId = typeof data.twoFactorEnabled === "boolean" ? updatedUserId(context) : null;
+						if (twoFactorUserId) {
+							const stored = await (await getCurrentAdapter(contextFor(context).adapter)).findOne({
+								model: "user",
+								where: [{
+									field: "id",
+									value: twoFactorUserId
+								}]
+							});
+							if (stored && stored.twoFactorEnabled === true !== data.twoFactorEnabled) {
+								flags.twoFactor = data.twoFactorEnabled;
+								flags.twoFactorUserId = twoFactorUserId;
+							}
+						}
+					} catch (error) {
+						contextFor(context).logger.error("[audit-log] failed to inspect a user update", error);
+					}
+					const queue = pendingUpdates.get(context) ?? [];
+					queue.push(flags);
+					pendingUpdates.set(context, queue);
+				},
+				after: async (user, context) => {
+					if (!context || !user) return;
+					const flags = pendingUpdates.get(context)?.shift();
+					if (!flags) return;
+					if (flags.emailChanged && user.email?.toLowerCase() === flags.emailChanged) await record(context, {
+						type: "email-changed",
+						userId: user.id,
+						actorUserId: actor(context, user.id),
+						metadata: { email: flags.emailChanged }
+					});
+					else if (flags.emailVerified) await record(context, {
+						type: "email-verified",
+						userId: user.id,
+						actorUserId: user.id
+					});
+					const twoFactorEnabled = user.twoFactorEnabled;
+					if (flags.twoFactor !== null && user.id === flags.twoFactorUserId && twoFactorEnabled === flags.twoFactor) await record(context, {
+						type: flags.twoFactor ? "two-factor-enabled" : "two-factor-disabled",
+						userId: user.id,
+						actorUserId: actor(context, user.id)
+					});
+				}
+			},
+			delete: { after: async (user, context) => {
+				await record(context, {
+					type: "user-deleted",
+					userId: user.id,
+					actorUserId: actor(context, user.id)
+				});
+			} }
+		},
+		account: { create: { after: async (account, context) => {
+			if (wasJustCreated(account.userId)) return;
+			await record(context, {
+				type: "account-linked",
+				userId: account.userId,
+				actorUserId: actor(context, account.userId),
+				metadata: { providerId: account.providerId }
+			});
+		} } }
+	};
+}
+// src/hooks/paths.ts
+/** Where the before-hook leaves what it looked up for the after-hook. */
+const SUBJECT_KEY = "auditLogSubjectUserId";
+/** Endpoints whose failures are failed sign-ins. Only these: they check a credential. */
+const SIGN_IN_PATHS = /* @__PURE__ */ new Set([
+	"/sign-in/email",
+	"/sign-in/username",
+	"/sign-in/phone-number",
+	"/sign-in/email-otp",
+	"/two-factor/verify-totp",
+	"/two-factor/verify-otp",
+	"/two-factor/verify-backup-code"
+]);
+/**
+* Endpoints that set a new session cookie for a user who is already signed
+* in (rotation, impersonation): not sign-ins. Most of them also load the
+* session, which rules them out anyway; this list covers the rest.
+*/
+const NOT_SIGN_IN_PATHS = /* @__PURE__ */ new Set([
+	"/change-password",
+	"/update-user",
+	"/update-session",
+	"/change-email",
+	"/two-factor/enable",
+	"/two-factor/disable",
+	"/admin/impersonate-user",
+	"/admin/stop-impersonating",
+	"/multi-session/set-active"
+]);
+const target = (body) => body.userId;
+const lookedUp = (_body, _returned, userId) => userId;
+/** A field of the endpoint's result, if it succeeded (`returned` is an error otherwise). */
+function field(returned, ...path) {
+	let value = isAPIError(returned) ? void 0 : returned;
+	for (const key of path) value = value && typeof value === "object" ? value[key] : void 0;
+	return value;
+}
+/** Endpoints whose subject is the user of a password reset, looked up before the reset. */
+const PASSWORD_RESET_PATHS = /* @__PURE__ */ new Set([
+	"/reset-password",
+	"/email-otp/reset-password",
+	"/phone-number/reset-password"
+]);
+const passwordReset = {
+	type: "password-reset",
+	subject: lookedUp
+};
+/** Endpoints recorded by path. Admin actions are recorded on success and on failure. */
+const PATH_EVENTS = {
+	"/sign-out": { type: "sign-out" },
+	"/revoke-session": {
+		type: "session-revoked",
+		metadata: () => ({ scope: "session" })
+	},
+	"/revoke-sessions": {
+		type: "session-revoked",
+		metadata: () => ({ scope: "all" })
+	},
+	"/revoke-other-sessions": {
+		type: "session-revoked",
+		metadata: () => ({ scope: "others" })
+	},
+	"/change-password": {
+		type: "password-changed",
+		metadata: (body) => ({ revokeOtherSessions: body.revokeOtherSessions === true })
+	},
+	"/reset-password": passwordReset,
+	"/email-otp/reset-password": passwordReset,
+	"/phone-number/reset-password": passwordReset,
+	"/unlink-account": {
+		type: "account-unlinked",
+		metadata: (body) => ({ providerId: body.providerId })
+	},
+	"/admin/create-user": {
+		type: "admin.create-user",
+		subject: (_body, returned) => returned?.user?.id,
+		metadata: (body) => ({ role: body.role ?? null })
+	},
+	"/admin/update-user": {
+		type: "admin.update-user",
+		subject: target,
+		metadata: (body) => ({ fields: body.data && typeof body.data === "object" ? Object.keys(body.data) : [] })
+	},
+	"/admin/set-role": {
+		type: "admin.set-role",
+		subject: target,
+		metadata: (body) => ({ role: body.role })
+	},
+	"/admin/set-user-password": {
+		type: "admin.set-user-password",
+		subject: target
+	},
+	"/admin/ban-user": {
+		type: "admin.ban-user",
+		subject: target,
+		metadata: (body) => ({
+			reason: body.banReason ?? null,
+			expiresIn: body.banExpiresIn ?? null
+		})
+	},
+	"/admin/unban-user": {
+		type: "admin.unban-user",
+		subject: target
+	},
+	"/admin/impersonate-user": {
+		type: "admin.impersonate-user",
+		subject: target
+	},
+	"/admin/stop-impersonating": { type: "admin.stop-impersonating" },
+	"/admin/revoke-user-session": {
+		type: "admin.revoke-user-session",
+		subject: lookedUp
+	},
+	"/admin/revoke-user-sessions": {
+		type: "admin.revoke-user-sessions",
+		subject: target
+	},
+	"/admin/remove-user": {
+		type: "admin.remove-user",
+		subject: target
+	},
+	"/organization/create": {
+		type: "organization.created",
+		organization: (_body, returned) => field(returned, "id"),
+		metadata: (body) => ({
+			name: body.name ?? null,
+			slug: body.slug ?? null
+		})
+	},
+	"/organization/update": {
+		type: "organization.updated",
+		organization: (body, returned) => field(returned, "id") ?? body.organizationId,
+		metadata: (body) => ({ fields: body.data && typeof body.data === "object" ? Object.keys(body.data) : [] })
+	},
+	"/organization/delete": {
+		type: "organization.deleted",
+		organization: (body) => body.organizationId
+	},
+	"/organization/invite-member": {
+		type: "organization.invitation-created",
+		organization: (body, returned) => field(returned, "organizationId") ?? body.organizationId,
+		metadata: (body, returned) => ({
+			invitationId: field(returned, "id") ?? null,
+			email: typeof body.email === "string" ? body.email.toLowerCase() : null,
+			role: body.role ?? null
+		})
+	},
+	"/organization/accept-invitation": {
+		type: "organization.invitation-accepted",
+		organization: (_body, returned) => field(returned, "invitation", "organizationId"),
+		metadata: (body, returned) => ({
+			invitationId: body.invitationId ?? null,
+			memberId: field(returned, "member", "id") ?? null,
+			role: field(returned, "member", "role") ?? null
+		})
+	},
+	"/organization/reject-invitation": {
+		type: "organization.invitation-rejected",
+		organization: (_body, returned) => field(returned, "invitation", "organizationId"),
+		metadata: (body) => ({ invitationId: body.invitationId ?? null })
+	},
+	"/organization/cancel-invitation": {
+		type: "organization.invitation-canceled",
+		organization: (_body, returned) => field(returned, "organizationId"),
+		metadata: (body, returned) => ({
+			invitationId: body.invitationId ?? null,
+			email: field(returned, "email") ?? null
+		})
+	},
+	"/organization/remove-member": {
+		type: "organization.member-removed",
+		subject: (_body, returned) => field(returned, "member", "userId"),
+		organization: (body, returned) => field(returned, "member", "organizationId") ?? body.organizationId,
+		metadata: (_body, returned) => ({ memberId: field(returned, "member", "id") ?? null })
+	},
+	"/organization/update-member-role": {
+		type: "organization.member-role-changed",
+		subject: (_body, returned) => field(returned, "userId"),
+		organization: (body, returned) => field(returned, "organizationId") ?? body.organizationId,
+		metadata: (body) => ({
+			memberId: body.memberId ?? null,
+			role: body.role ?? null
+		})
+	},
+	"/organization/leave": {
+		type: "organization.member-left",
+		organization: (body) => body.organizationId
+	}
+};
+const asString = (value) => typeof value === "string" && value !== "" ? value : null;
+/**
+* Looks up, before the endpoint runs, what is gone afterwards: the
+* session (sign-out, revoke), the user of a password reset (by token, or by
+* the email or phone number of an OTP reset), or of a session an admin
+* revokes.
+*/
+async function lookUpSubject(ctx) {
+	const body = ctx.body ?? {};
+	if (ctx.path === "/reset-password") {
+		const token = asString(body.token) ?? asString(ctx.query?.token);
+		if (!token) return void 0;
+		return (await ctx.context.internalAdapter.findVerificationValue(`reset-password:${token}`))?.value;
+	}
+	if (ctx.path === "/email-otp/reset-password") {
+		const email = asString(body.email)?.trim().toLowerCase();
+		if (!email) return void 0;
+		return (await ctx.context.internalAdapter.findUserByEmail(email))?.user.id;
+	}
+	if (ctx.path === "/phone-number/reset-password") {
+		const phone = asString(body.phoneNumber)?.trim();
+		if (!phone) return void 0;
+		return (await ctx.context.adapter.findOne({
+			model: "user",
+			where: [{
+				field: "phoneNumber",
+				value: phone
+			}]
+		}).catch(() => null))?.id;
+	}
+	if (ctx.path === "/admin/revoke-user-session") {
+		const token = asString(body.sessionToken);
+		if (!token) return void 0;
+		return (await ctx.context.internalAdapter.findSession(token))?.user.id;
+	}
+}
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE = /^\+?[0-9 ()-]{5,20}$/;
+/**
+* Who a failed sign-in was for. People type their password into the
+* email or username field, so the input is only kept when it is clearly
+* an identifier: a well-formed email or phone number, or the username of
+* an existing user.
+*/
+async function failedSignInSubject(ctx, body) {
+	const email = asString(body.email)?.trim().toLowerCase();
+	if (email) {
+		if (!EMAIL.test(email) || email.length > 255) return {
+			userId: null,
+			identifier: null
+		};
+		return {
+			userId: (await ctx.context.internalAdapter.findUserByEmail(email))?.user.id ?? null,
+			identifier: email
+		};
+	}
+	const username = asString(body.username)?.trim().toLowerCase();
+	if (username) {
+		const user = await ctx.context.adapter.findOne({
+			model: "user",
+			where: [{
+				field: "username",
+				value: username
+			}]
+		}).catch(() => null);
+		return user ? {
+			userId: user.id,
+			identifier: username
+		} : {
+			userId: null,
+			identifier: null
+		};
+	}
+	const phone = asString(body.phoneNumber)?.trim();
+	if (phone && PHONE.test(phone)) return {
+		userId: (await ctx.context.adapter.findOne({
+			model: "user",
+			where: [{
+				field: "phoneNumber",
+				value: phone
+			}]
+		}).catch(() => null))?.id ?? null,
+		identifier: phone
+	};
+	return {
+		userId: null,
+		identifier: null
+	};
+}
+function failureOf(returned) {
+	if (!isAPIError(returned) || returned.statusCode < 400) return {
+		failed: false,
+		errorCode: null
+	};
+	const code = returned.body?.code;
+	return {
+		failed: true,
+		errorCode: typeof code === "string" ? code : returned.status.toString()
+	};
+}
+function sessionDetails(session) {
+	if (!session) return {};
+	const { id, activeOrganizationId } = session.session;
+	return {
+		sessionId: id,
+		organizationId: asString(activeOrganizationId)
+	};
+}
+function createPathHooks(options, recorder) {
+	const eventFor = (path) => {
+		if (!path) return void 0;
+		if (Object.hasOwn(options.paths, path)) return { type: options.paths[path] };
+		return Object.hasOwn(PATH_EVENTS, path) ? PATH_EVENTS[path] : void 0;
+	};
+	return {
+		before: [{
+			matcher: (context) => {
+				const event = eventFor(context.path);
+				return !!event && recorder.isRecorded(event.type);
+			},
+			handler: createAuthMiddleware(async (ctx) => {
+				try {
+					await getSessionFromCtx(ctx, { disableRefresh: true });
+					const subject = await lookUpSubject(ctx);
+					if (subject) ctx.context[SUBJECT_KEY] = subject;
+				} catch (error) {
+					ctx.context.logger.error("[audit-log] failed to prepare an event", error);
+				}
+			})
+		}],
+		after: [{
+			matcher: (context) => !!context.path,
+			handler: createAuthMiddleware(async (ctx) => {
+				try {
+					await afterEndpoint(ctx);
+				} catch (error) {
+					ctx.context.logger.error("[audit-log] failed to record an event", error);
+				}
+			})
+		}]
+	};
+	async function afterEndpoint(ctx) {
+		const { path } = ctx;
+		const body = ctx.body ?? {};
+		const headers = ctx.request?.headers ?? ctx.headers ?? null;
+		const { failed, errorCode } = failureOf(ctx.context.returned);
+		const session = ctx.context.session;
+		const created = ctx.context.newSession;
+		if (!failed && created && !session && !NOT_SIGN_IN_PATHS.has(path) && !created.session.impersonatedBy) await recorder.record(ctx.context, {
+			type: "sign-in",
+			userId: created.user.id,
+			actorUserId: created.user.id,
+			...sessionDetails(created),
+			metadata: { method: signInMethod(path, ctx.params, body) }
+		}, headers);
+		if (failed && SIGN_IN_PATHS.has(path)) {
+			const { userId, identifier } = await failedSignInSubject(ctx, body);
+			await recorder.record(ctx.context, {
+				type: "sign-in",
+				status: "failure",
+				errorCode,
+				userId,
+				metadata: {
+					method: signInMethod(path),
+					...identifier ? { identifier } : {}
+				}
+			}, headers);
+			return;
+		}
+		const event = eventFor(path);
+		if (!event) return;
+		const subject = ctx.context[SUBJECT_KEY];
+		let actorUserId = session?.user.id ?? null;
+		let userId = event.subject ? asString(event.subject(body, ctx.context.returned, subject)) : actorUserId;
+		if (path === "/admin/stop-impersonating" && session) {
+			actorUserId = asString(session.session.impersonatedBy) ?? session.user.id;
+			userId = session.user.id;
+		}
+		if (PASSWORD_RESET_PATHS.has(path)) actorUserId = userId;
+		if (!userId && !actorUserId) return;
+		const details = sessionDetails(session);
+		const organizationId = event.organization ? asString(event.organization(body, ctx.context.returned)) : null;
+		await recorder.record(ctx.context, {
+			type: event.type,
+			status: failed ? "failure" : "success",
+			errorCode,
+			userId,
+			actorUserId,
+			...details,
+			organizationId: organizationId ?? details.organizationId ?? null,
+			metadata: event.metadata ? event.metadata(body, ctx.context.returned) : null
+		}, headers);
+	}
+}
+// ../plugin-utils/src/admin.ts
+/** Applies the defaults of `AdminOptions`. */
+function resolveAdminOptions(options) {
+	return {
+		adminRoles: options.adminRoles ?? ["admin"],
+		adminUserIds: options.adminUserIds ?? []
+	};
+}
+/**
+* Whether `user` is listed in `adminUserIds`, or has one of `adminRoles`
+* in the admin plugin's `role` field, which holds several roles
+* comma-separated (`"user, admin"`).
+*/
+function isAdmin(user, options) {
+	if (options.adminUserIds.includes(user.id)) return true;
+	if (typeof user.role !== "string") return false;
+	return user.role.split(",").some((role) => options.adminRoles.includes(role.trim()));
+}
+// ../plugin-utils/src/options.ts
+/**
+* Returns a function that throws an option error prefixed with the plugin
+* id, `[referral] "codeLength" must be ...`, for validating options at
+* plugin creation.
+*/
+function createFail(pluginId) {
+	return (message) => {
+		throw new Error(`[${pluginId}] ${message}`);
+	};
+}
+const SEVERITIES = [
+	"low",
+	"medium",
+	"high",
+	"critical"
+];
+const fail = createFail("audit-log");
+function isValidEventType(type) {
+	return type.length <= 64 && /^[a-z0-9][a-z0-9._-]*$/i.test(type);
+}
+/**
+* Compiles `events` patterns into a matcher: exact types, or `group.*`
+* for every type starting with `group.`.
+*/
+function compileEventFilter(patterns) {
+	const exact = /* @__PURE__ */ new Set();
+	const prefixes = [];
+	for (const pattern of patterns) if (pattern.endsWith(".*") && isValidEventType(pattern.slice(0, -2))) prefixes.push(pattern.slice(0, -1));
+	else if (isValidEventType(pattern)) exact.add(pattern);
+	else fail(`Invalid event pattern ${JSON.stringify(pattern)} in "events".`);
+	return (type) => exact.has(type) || prefixes.some((prefix) => type.startsWith(prefix));
+}
+/** Resolves defaults and validates the options once, at plugin creation. */
+function resolveOptions(options) {
+	const paths = { ...options.paths };
+	for (const [path, type] of Object.entries(paths)) {
+		if (!path.startsWith("/")) fail(`Path ${JSON.stringify(path)} in "paths" must start with "/".`);
+		if (!isValidEventType(type)) fail(`Invalid event type ${JSON.stringify(type)} in "paths": use letters, digits, ".", "-", and "_", up to 64 characters.`);
+	}
+	const severity = { ...options.severity };
+	for (const [type, value] of Object.entries(severity)) if (!SEVERITIES.includes(value)) fail(`Invalid severity ${JSON.stringify(value)} for "${type}": use ${SEVERITIES.join(", ")}.`);
+	let retention;
+	if (options.retention) {
+		const { days, sweepInterval = 3600 } = options.retention;
+		if (!(typeof days === "number" && days > 0 && Number.isFinite(days))) fail(`"retention.days" must be a positive number, got ${days}.`);
+		if (!(typeof sweepInterval === "number" && sweepInterval > 0)) fail(`"retention.sweepInterval" must be a positive number of seconds, got ${sweepInterval}.`);
+		retention = {
+			days,
+			sweepInterval
+		};
+	}
+	let hashChain = null;
+	if (options.hashChain) {
+		if (options.storage) fail("\"hashChain\" needs the default database storage; remove \"storage\" or \"hashChain\".");
+		const secret = typeof options.hashChain === "object" ? options.hashChain.secret : void 0;
+		if (secret !== void 0 && secret.length < 32) fail("\"hashChain.secret\" must be at least 32 characters.");
+		hashChain = { secret };
+	}
+	return {
+		events: options.events ? compileEventFilter(options.events) : null,
+		paths,
+		severity,
+		captureIp: options.captureIp ?? true,
+		captureUserAgent: options.captureUserAgent ?? true,
+		beforeLog: options.beforeLog,
+		onEvent: options.onEvent,
+		storage: options.storage,
+		retention,
+		hashChain,
+		...resolveAdminOptions(options)
+	};
+}
+// src/record-event.ts
+/**
+* Records an event for another plugin, through
+* `ctx.context.getPlugin("audit-log")?.recordEvent(...)`, the way official
+* plugins reach each other (`anonymous` calls `twoFactor` like this).
+*
+* Fills in what the request knows: the signed-in user as actor (unless
+* `actorUserId` is given), the session, its active organization, the IP
+* address, and the user agent. Never throws.
+*
+* Inside a database transaction (a database hook while a user is created),
+* the event is written outside it once the transaction ends: an event
+* about something that was refused, like a blocked sign-up, must survive
+* the rollback.
+*/
+function createRecordEvent(recorder) {
+	return async (details, endpoint = tryGetCurrentAuthEndpointContext()) => {
+		if (!endpoint || !recorder.isRecorded(details.type)) return;
+		const ctx = endpoint.context;
+		const session = ctx.session;
+		const event = {
+			actorUserId: session?.user.id ?? null,
+			sessionId: session?.session.id ?? null,
+			organizationId: (session?.session)?.activeOrganizationId ?? null,
+			...details
+		};
+		const headers = endpoint.request?.headers ?? endpoint.headers ?? null;
+		try {
+			if (await getCurrentAdapter(ctx.adapter) === ctx.adapter) {
+				await recorder.record(ctx, event, headers);
+				return;
+			}
+			ctx.runInBackground(runWithAdapter(ctx.adapter, () => recorder.record(ctx, event, headers)));
+		} catch (error) {
+			ctx.logger.error(`[audit-log] failed to record a "${details.type}" event`, error);
+		}
+	};
+}
+// src/chain.ts
+/** The `previousHash` of the first link. */
+const GENESIS_HASH = "0".repeat(64);
+/** How often a link is retried when another writer took the sequence number. */
+const MAX_APPEND_ATTEMPTS = 20;
+/** Links read per query while verifying. */
+const VERIFY_PAGE_SIZE = 500;
+const keys = /* @__PURE__ */ new Map();
+function hmacKey(secret) {
+	let key = keys.get(secret);
+	if (!key) {
+		key = crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign"]);
+		keys.set(secret, key);
+	}
+	return key;
+}
+/**
+* Everything the hash covers, in a fixed order. `createdAt` is in whole
+* seconds, because some databases store dates with less precision than
+* JavaScript, and the hash must match what is read back.
+*/
+function canonical(event, sequence, previousHash) {
+	return JSON.stringify([
+		1,
+		sequence,
+		previousHash,
+		event.id,
+		event.type,
+		event.status,
+		event.severity,
+		event.userId ?? null,
+		event.actorUserId ?? null,
+		event.sessionId ?? null,
+		event.organizationId ?? null,
+		event.ipAddress ?? null,
+		event.userAgent ?? null,
+		event.errorCode ?? null,
+		event.metadata ? JSON.stringify(event.metadata) : null,
+		Math.floor(new Date(event.createdAt).getTime() / 1e3)
+	]);
+}
+async function linkHash(secret, event, sequence, previousHash) {
+	const signature = await crypto.subtle.sign("HMAC", await hmacKey(secret), new TextEncoder().encode(canonical(event, sequence, previousHash)));
+	return Array.from(new Uint8Array(signature), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function latestLink(adapter) {
+	const [link] = await adapter.findMany({
+		model: "auditChain",
+		limit: 1,
+		sortBy: {
+			field: "sequence",
+			direction: "desc"
+		}
+	});
+	return link ?? null;
+}
+function createChain(secretOption) {
+	const secretFor = (ctx) => secretOption ?? ctx.secret;
+	/**
+	* Adds a link for `event`. Concurrent writers compete for the next
+	* sequence number through its unique index; the loser reads the new
+	* latest link and tries again.
+	*/
+	async function append(ctx, event) {
+		const adapter = ctx.adapter;
+		for (let attempt = 0; attempt < MAX_APPEND_ATTEMPTS; attempt++) {
+			const previous = await latestLink(adapter);
+			const sequence = (previous?.sequence ?? 0) + 1;
+			const previousHash = previous?.hash ?? GENESIS_HASH;
+			const hash = await linkHash(secretFor(ctx), event, sequence, previousHash);
+			try {
+				await adapter.create({
+					model: "auditChain",
+					data: {
+						sequence,
+						eventId: event.id,
+						previousHash,
+						hash,
+						createdAt: event.createdAt
+					}
+				});
+				return;
+			} catch (error) {
+				if (!await adapter.findOne({
+					model: "auditChain",
+					where: [{
+						field: "sequence",
+						value: sequence
+					}]
+				})) throw error;
+				await new Promise((resolve) => setTimeout(resolve, Math.random() * 5 * (attempt + 1)));
+			}
+		}
+		throw new Error(`[audit-log] could not chain event ${event.id}: too many concurrent writers`);
+	}
+	/**
+	* `append`, but never inside a database transaction: a failed write
+	* there (a taken sequence number) would abort the transaction on some
+	* databases, and with it the sign-up being recorded. Inside one, the
+	* link is added after the commit, and dropped with a rollback like its
+	* event. Errors are logged: the event is stored, and verification
+	* reports it as unchained.
+	*/
+	async function link(ctx, event) {
+		const run = async () => {
+			try {
+				await append(ctx, event);
+			} catch (error) {
+				ctx.logger.error("[audit-log] failed to chain an event", error);
+			}
+		};
+		if (await getCurrentAdapter(ctx.adapter) === ctx.adapter) await run();
+		else await queueAfterTransactionHook(run);
+	}
+	/** Deletes links of events created before `date` (retention). */
+	async function deleteOlderThan(ctx, date) {
+		return ctx.adapter.deleteMany({
+			model: "auditChain",
+			where: [{
+				field: "createdAt",
+				value: date,
+				operator: "lt"
+			}]
+		});
+	}
+	/** Re-computes every link, oldest first, against the stored events. */
+	async function verify(ctx, readEvents) {
+		const { adapter } = ctx;
+		const secret = secretFor(ctx);
+		const problems = [];
+		const report = (link, problem) => {
+			if (problems.length < 100) problems.push({
+				sequence: link.sequence,
+				eventId: link.eventId,
+				problem
+			});
+		};
+		let checked = 0;
+		let first = null;
+		let previous = null;
+		let problemCount = 0;
+		for (;;) {
+			const links = await adapter.findMany({
+				model: "auditChain",
+				where: previous ? [{
+					field: "sequence",
+					value: previous.sequence,
+					operator: "gt"
+				}] : [],
+				limit: VERIFY_PAGE_SIZE,
+				sortBy: {
+					field: "sequence",
+					direction: "asc"
+				}
+			});
+			if (links.length === 0) break;
+			const events = await readEvents(links.map((link) => link.eventId));
+			for (const link of links) {
+				checked++;
+				first ??= link;
+				if (previous) {
+					if (link.sequence !== previous.sequence + 1) {
+						report(link, "sequence-gap");
+						problemCount++;
+					} else if (link.previousHash !== previous.hash) {
+						report(link, "broken-link");
+						problemCount++;
+					}
+				}
+				const event = events.get(link.eventId);
+				if (!event) {
+					report(link, "missing-event");
+					problemCount++;
+				} else if (await linkHash(secret, event, link.sequence, link.previousHash) !== link.hash) {
+					report(link, "hash-mismatch");
+					problemCount++;
+				}
+				previous = link;
+			}
+			if (links.length < VERIFY_PAGE_SIZE) break;
+		}
+		let unchainedEvents = 0;
+		if (first && previous) {
+			const firstEvent = (await readEvents([first.eventId])).get(first.eventId);
+			if (firstEvent) {
+				const stored = await adapter.count({
+					model: "auditEvent",
+					where: [{
+						field: "createdAt",
+						value: firstEvent.createdAt,
+						operator: "gte"
+					}]
+				});
+				unchainedEvents = Math.max(0, stored - checked);
+			}
+		}
+		return {
+			valid: problemCount === 0 && unchainedEvents === 0,
+			checked,
+			firstSequence: first?.sequence ?? null,
+			lastSequence: previous?.sequence ?? null,
+			lastHash: previous?.hash ?? null,
+			problems,
+			unchainedEvents
+		};
+	}
+	return {
+		link,
+		verify,
+		deleteOlderThan
+	};
+}
+// src/store.ts
+function toEvent(row) {
+	let metadata = null;
+	if (row.metadata) try {
+		metadata = JSON.parse(row.metadata);
+	} catch {
+		metadata = null;
+	}
+	return {
+		id: row.id,
+		type: row.type,
+		status: row.status,
+		severity: row.severity,
+		userId: row.userId ?? null,
+		actorUserId: row.actorUserId ?? null,
+		sessionId: row.sessionId ?? null,
+		organizationId: row.organizationId ?? null,
+		ipAddress: row.ipAddress ?? null,
+		userAgent: row.userAgent ?? null,
+		errorCode: row.errorCode ?? null,
+		metadata,
+		createdAt: new Date(row.createdAt)
+	};
+}
+function filters(query) {
+	const where = [];
+	if (query.userId) where.push({
+		field: "userId",
+		value: query.userId
+	});
+	if (query.actorUserId) where.push({
+		field: "actorUserId",
+		value: query.actorUserId
+	});
+	if (query.type) where.push({
+		field: "type",
+		value: query.type
+	});
+	if (query.status) where.push({
+		field: "status",
+		value: query.status
+	});
+	if (query.from) where.push({
+		field: "createdAt",
+		value: query.from,
+		operator: "gte"
+	});
+	if (query.to) where.push({
+		field: "createdAt",
+		value: query.to,
+		operator: "lt"
+	});
+	return where;
+}
+/**
+* The default storage: the plugin's `auditEvent` table, through
+* better-auth's adapter. Inside a transaction (database hooks), writes go
+* through the transaction's adapter, so SQLite doesn't wait on itself.
+*/
+function databaseStorage(baseAdapter) {
+	const adapter = () => getCurrentAdapter(baseAdapter);
+	return {
+		async write(event) {
+			return toEvent(await (await adapter()).create({
+				model: "auditEvent",
+				data: {
+					...event,
+					metadata: event.metadata ? JSON.stringify(event.metadata) : null
+				}
+			}));
+		},
+		async read(query) {
+			const db = await adapter();
+			const where = filters(query);
+			const [rows, total] = await Promise.all([db.findMany({
+				model: "auditEvent",
+				where,
+				limit: query.limit,
+				offset: query.offset,
+				sortBy: {
+					field: "createdAt",
+					direction: "desc"
+				}
+			}), db.count({
+				model: "auditEvent",
+				where
+			})]);
+			return {
+				events: rows.map(toEvent),
+				total
+			};
+		},
+		async readByIds(ids) {
+			if (ids.length === 0) return /* @__PURE__ */ new Map();
+			const rows = await (await adapter()).findMany({
+				model: "auditEvent",
+				where: [{
+					field: "id",
+					value: ids,
+					operator: "in"
+				}]
+			});
+			return new Map(rows.map((row) => [row.id, toEvent(row)]));
+		},
+		async deleteOlderThan(date) {
+			return (await adapter()).deleteMany({
+				model: "auditEvent",
+				where: [{
+					field: "createdAt",
+					value: date,
+					operator: "lt"
+				}]
+			});
+		}
+	};
+}
+// src/utils/redact.ts
+/** Keys whose values never reach the log, whatever their nesting or case. */
+const SECRET_KEY = /password|passphrase|secret|token|^otp$|backup.?codes?|api.?key|authorization|cookie/i;
+const REDACTED = "[redacted]";
+const MAX_DEPTH = 5;
+/**
+* Copies metadata with secret-looking values replaced, so a careless
+* `recordAuditEvent` call can't put a password or token in the log.
+*/
+function redact(value, depth = 0) {
+	if (depth > MAX_DEPTH) return REDACTED;
+	if (Array.isArray(value)) return value.map((item) => redact(item, depth + 1));
+	if (value instanceof Date) return value.toISOString();
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, SECRET_KEY.test(key) ? REDACTED : redact(item, depth + 1)]));
+	return value;
+}
+// src/utils/severity.ts
+const BUILT_IN = {
+	"sign-up": "low",
+	"sign-in": "low",
+	"sign-out": "low",
+	"email-verified": "low",
+	"session-revoked": "medium",
+	"account-linked": "medium",
+	"account-unlinked": "medium",
+	"email-changed": "medium",
+	"password-changed": "medium",
+	"password-reset": "medium",
+	"user-deleted": "high",
+	"two-factor-enabled": "medium",
+	"two-factor-disabled": "high",
+	"organization.deleted": "high",
+	"organization.member-removed": "medium",
+	"organization.member-role-changed": "high",
+	"admin.set-role": "critical",
+	"admin.set-user-password": "critical",
+	"admin.impersonate-user": "critical"
+};
+/**
+* The severity of an event: the `severity` option, then the built-in
+* table. Admin actions are `high` unless listed; failed sign-ins `medium`;
+* anything else `low`.
+*/
+function severityOf(type, status, overrides) {
+	const override = overrides[type];
+	if (override) return override;
+	if (type === "sign-in" && status === "failure") return "medium";
+	return BUILT_IN[type] ?? (type.startsWith("admin.") ? "high" : "low");
+}
+const MAX_USER_AGENT_LENGTH = 512;
+function createRecorder(options) {
+	let lastSweep = 0;
+	const chain = options.hashChain ? createChain(options.hashChain.secret) : null;
+	let lastCreatedAt = 0;
+	/**
+	* The current time, but never the same as or earlier than the previous
+	* event's: events recorded in the same millisecond (a sign-up and its
+	* sign-in) still list in the order they happened.
+	*/
+	const nextTimestamp = () => {
+		lastCreatedAt = Math.max(Date.now(), lastCreatedAt + 1);
+		return new Date(lastCreatedAt);
+	};
+	const storageFor = (ctx) => options.storage ?? databaseStorage(ctx.adapter);
+	const isRecorded = (type) => !options.events || options.events(type);
+	function build(ctx, details, headers) {
+		const status = details.status ?? "success";
+		let metadata = details.metadata ? redact(details.metadata) : null;
+		if (metadata && JSON.stringify(metadata).length > 4e3) metadata = { truncated: true };
+		const ipAddress = details.ipAddress ?? (options.captureIp && headers ? getIP(headers, ctx.options) : null);
+		const userAgent = details.userAgent ?? (options.captureUserAgent ? headers?.get("user-agent") ?? null : null);
+		return {
+			type: details.type,
+			status,
+			severity: details.severity ?? severityOf(details.type, status, options.severity),
+			userId: details.userId ?? null,
+			actorUserId: details.actorUserId ?? null,
+			sessionId: details.sessionId ?? null,
+			organizationId: details.organizationId ?? null,
+			ipAddress,
+			userAgent: userAgent ? userAgent.slice(0, MAX_USER_AGENT_LENGTH) : null,
+			errorCode: details.errorCode ?? null,
+			metadata,
+			createdAt: nextTimestamp()
+		};
+	}
+	/** Deletes events created before `date`, and their links. */
+	async function deleteOlderThan(ctx, date) {
+		const deleted = await storageFor(ctx).deleteOlderThan(date);
+		if (chain) await chain.deleteOlderThan(ctx, date);
+		return deleted;
+	}
+	/** Starts a retention sweep in the background, at most once per `sweepInterval`. */
+	function maybeSweep(ctx) {
+		if (!options.retention) return;
+		const now = Date.now();
+		if (now - lastSweep < options.retention.sweepInterval * 1e3) return;
+		lastSweep = now;
+		const sweep = deleteOlderThan(ctx, /* @__PURE__ */ new Date(now - options.retention.days * 864e5)).catch((error) => ctx.logger.error("[audit-log] retention sweep failed", error));
+		ctx.runInBackground(sweep);
+	}
+	/**
+	* Builds, filters, and stores an event, then calls `onEvent`. Returns
+	* `null` if the event isn't recorded (`events`, `beforeLog`). Storage
+	* errors are thrown; `onEvent` errors are logged.
+	*/
+	async function recordNow(ctx, details, headers) {
+		if (!isRecorded(details.type)) return null;
+		let event = build(ctx, details, headers);
+		if (options.beforeLog) {
+			try {
+				event = await options.beforeLog(event);
+			} catch (error) {
+				ctx.logger.error("[audit-log] beforeLog threw an error; the event was dropped", error);
+				return null;
+			}
+			if (!event) return null;
+		}
+		const stored = await storageFor(ctx).write(event);
+		if (chain) await chain.link(ctx, stored);
+		if (options.onEvent) try {
+			await options.onEvent(stored);
+		} catch (error) {
+			ctx.logger.error("[audit-log] onEvent threw an error", error);
+		}
+		maybeSweep(ctx);
+		return stored;
+	}
+	/**
+	* `recordNow` for hooks: never throws, and runs in the background when
+	* better-auth's `advanced.backgroundTasks` is configured.
+	*/
+	async function record(ctx, details, headers) {
+		if (!isRecorded(details.type)) return;
+		const task = recordNow(ctx, details, headers).then(() => void 0, (error) => ctx.logger.error(`[audit-log] failed to record a "${details.type}" event`, error));
+		await ctx.runInBackgroundOrAwait(task);
+	}
+	return {
+		record,
+		recordNow,
+		storageFor,
+		isRecorded,
+		deleteOlderThan,
+		chain
+	};
+}
+// ../plugin-utils/src/pagination.ts
+/**
+* The `limit` and `offset` fields of a list endpoint's query, coerced from
+* query strings. Spread into the endpoint's `z.object({ ... })`.
+*/
+function paginationQuery({ defaultLimit, maxLimit }) {
+	return {
+		limit: z.coerce.number().int().min(1).max(maxLimit).default(defaultLimit).meta({ description: `How many to return, at most ${maxLimit}. Defaults to ${defaultLimit}` }),
+		offset: z.coerce.number().int().min(0).default(0).meta({ description: "How many to skip. Defaults to 0" })
+	};
+}
+const statusSchema = z.enum(["success", "failure"]);
+const severitySchema = z.enum([
+	"low",
+	"medium",
+	"high",
+	"critical"
+]);
+const typeSchema = z.string().max(64).refine(isValidEventType, { message: "Invalid event type" });
+const idSchema = z.string().min(1).max(255);
+function createEventEndpoints(options, recorder) {
+	return {
+		listAuditEvents: createAuthEndpoint("/audit-log/list-events", {
+			method: "GET",
+			use: [sessionMiddleware],
+			query: z.optional(z.object({
+				userId: idSchema.optional().meta({ description: "Events about this user. Admins only, except for yourself" }),
+				actorUserId: idSchema.optional().meta({ description: "Events done by this user. Admins only" }),
+				type: typeSchema.optional().meta({ description: "Only events of this type" }),
+				status: statusSchema.optional().meta({ description: "Only events with this status" }),
+				from: z.coerce.date().optional().meta({ description: "Events at or after this time" }),
+				to: z.coerce.date().optional().meta({ description: "Events before this time" }),
+				...paginationQuery({
+					defaultLimit: 20,
+					maxLimit: 100
+				})
+			})),
+			metadata: { openapi: { description: "List audit events, newest first: your own, or any user's for admins" } }
+		}, async (ctx) => {
+			const me = ctx.context.session.user;
+			const query = ctx.query ?? {
+				limit: 20,
+				offset: 0
+			};
+			const admin = isAdmin(me, options);
+			if (!admin && (query.userId && query.userId !== me.id || query.actorUserId)) throw APIError.from("FORBIDDEN", AUDIT_LOG_ERROR_CODES.YOU_ARE_NOT_ALLOWED_TO_LIST_OTHER_USERS_EVENTS);
+			const { events, total } = await recorder.storageFor(ctx.context).read({
+				userId: admin ? query.userId : me.id,
+				actorUserId: query.actorUserId,
+				type: query.type,
+				status: query.status,
+				from: query.from,
+				to: query.to,
+				limit: query.limit ?? 20,
+				offset: query.offset ?? 0
+			});
+			return ctx.json({
+				events: admin ? events : events.map((event) => event.actorUserId === me.id ? event : {
+					...event,
+					ipAddress: null,
+					userAgent: null,
+					sessionId: null
+				}),
+				total
+			});
+		}),
+		/**
+		* Server only (no path, so not reachable over HTTP): records an event
+		* of your own, e.g. `auth.api.recordAuditEvent({ body: { type:
+		* "billing.plan-changed", userId } })`.
+		*/
+		recordAuditEvent: createAuthEndpoint({
+			method: "POST",
+			body: z.object({
+				type: typeSchema.meta({ description: "The event type, e.g. `billing.plan-changed`" }),
+				status: statusSchema.optional(),
+				severity: severitySchema.optional(),
+				userId: idSchema.optional().meta({ description: "The user the event is about" }),
+				actorUserId: idSchema.optional().meta({ description: "The user who did it" }),
+				organizationId: idSchema.optional(),
+				errorCode: z.string().max(255).optional(),
+				metadata: z.record(z.string(), z.unknown()).optional()
+			}),
+			metadata: { openapi: { description: "Record an audit event. Server only" } }
+		}, async (ctx) => {
+			const { metadata } = ctx.body;
+			if (metadata && JSON.stringify(metadata).length > 4e3) throw APIError.from("BAD_REQUEST", AUDIT_LOG_ERROR_CODES.METADATA_TOO_LARGE);
+			const event = await recorder.recordNow(ctx.context, ctx.body, ctx.request?.headers ?? ctx.headers);
+			return ctx.json({ event });
+		}),
+		/**
+		* Server only: deletes old events, for a cron job. Uses `retention.days`
+		* unless `days` is passed.
+		*/
+		deleteExpiredAuditEvents: createAuthEndpoint({
+			method: "POST",
+			body: z.optional(z.object({ days: z.number().positive().optional().meta({ description: "Delete events older than this" }) })),
+			metadata: { openapi: { description: "Delete audit events older than the retention period. Server only" } }
+		}, async (ctx) => {
+			const days = ctx.body?.days ?? options.retention?.days;
+			if (!days) throw APIError.from("BAD_REQUEST", AUDIT_LOG_ERROR_CODES.RETENTION_NOT_CONFIGURED);
+			const deleted = await recorder.deleteOlderThan(ctx.context, /* @__PURE__ */ new Date(Date.now() - days * 864e5));
+			return ctx.json({ deleted });
+		}),
+		/**
+		* Server only: re-computes the hash chain and reports changed, deleted,
+		* and unchained events. Reads every link, so run it from a job, not on
+		* every request.
+		*/
+		verifyAuditChain: createAuthEndpoint({
+			method: "POST",
+			metadata: { openapi: { description: "Verify the audit log's hash chain. Server only" } }
+		}, async (ctx) => {
+			const { chain } = recorder;
+			if (!chain) throw APIError.from("BAD_REQUEST", AUDIT_LOG_ERROR_CODES.HASH_CHAIN_NOT_ENABLED);
+			const storage = databaseStorage(ctx.context.adapter);
+			return ctx.json(await chain.verify(ctx.context, (ids) => storage.readByIds(ids)));
+		})
+	};
+}
+// src/schema.ts
+const auditLogSchema = { 
+/**
+* One row per event. User ids are plain columns, not foreign keys: the
+* log must outlive the users it mentions, `user-deleted` included.
+*/
+auditEvent: { fields: {
+	/** `sign-in`, `admin.ban-user`, or an app-defined type. */
+	type: {
+		type: "string",
+		required: true,
+		index: true
+	},
+	/** "success" | "failure" */
+	status: {
+		type: "string",
+		required: true
+	},
+	/** "low" | "medium" | "high" | "critical" */
+	severity: {
+		type: "string",
+		required: true
+	},
+	/** The user the event is about. */
+	userId: {
+		type: "string",
+		required: false,
+		index: true
+	},
+	/** The user who did it: the user themselves, or an admin. */
+	actorUserId: {
+		type: "string",
+		required: false,
+		index: true
+	},
+	sessionId: {
+		type: "string",
+		required: false
+	},
+	/** The session's active organization (organization plugin). */
+	organizationId: {
+		type: "string",
+		required: false
+	},
+	ipAddress: {
+		type: "string",
+		required: false
+	},
+	userAgent: {
+		type: "string",
+		required: false
+	},
+	/** The error code of a failed request, e.g. `INVALID_EMAIL_OR_PASSWORD`. */
+	errorCode: {
+		type: "string",
+		required: false
+	},
+	/** JSON-encoded. */
+	metadata: {
+		type: "string",
+		required: false
+	},
+	createdAt: {
+		type: "date",
+		required: true,
+		index: true
+	}
+} } };
+/** Added with the `hashChain` option: one link per event, in order. */
+const auditChainSchema = { auditChain: {
+	fields: {
+		/** 1, 2, 3, ... Unique, so concurrent writers can't fork the chain. */
+		sequence: {
+			type: "number",
+			required: true
+		},
+		/** The event's id. Not a foreign key: a deleted event must show as missing. */
+		eventId: {
+			type: "string",
+			required: true
+		},
+		previousHash: {
+			type: "string",
+			required: true
+		},
+		/** HMAC-SHA256 of the event, the sequence number, and `previousHash`. */
+		hash: {
+			type: "string",
+			required: true
+		},
+		/** The event's `createdAt`, for retention. */
+		createdAt: {
+			type: "date",
+			required: true,
+			index: true
+		}
+	},
+	indexes: [{
+		fields: ["sequence"],
+		unique: true
+	}]
+} };
+// src/memory.ts
+/**
+* Keeps events in memory, newest last. For tests and demos: events are
+* lost on restart and not shared between server instances.
+*
+* @example
+* ```ts
+* const storage = memoryStorage();
+* betterAuth({ plugins: [auditLog({ storage })] });
+* storage.events; // every stored event
+* ```
+*/
+function memoryStorage() {
+	const events = [];
+	const matches = (event, query) => (!query.userId || event.userId === query.userId) && (!query.actorUserId || event.actorUserId === query.actorUserId) && (!query.type || event.type === query.type) && (!query.status || event.status === query.status) && (!query.from || event.createdAt >= query.from) && (!query.to || event.createdAt < query.to);
+	return {
+		events,
+		async write(input) {
+			const event = {
+				...input,
+				id: crypto.randomUUID()
+			};
+			events.push(event);
+			return event;
+		},
+		async read(query) {
+			const found = events.filter((event) => matches(event, query)).reverse();
+			return {
+				events: found.slice(query.offset, query.offset + query.limit),
+				total: found.length
+			};
+		},
+		async deleteOlderThan(date) {
+			const kept = events.filter((event) => event.createdAt >= date);
+			const deleted = events.length - kept.length;
+			events.splice(0, events.length, ...kept);
+			return deleted;
+		}
+	};
+}
+// src/index.ts
+/** Plugins whose after-hooks clear `ctx.context.newSession` (a sign-in that isn't done yet). */
+const CLEARS_NEW_SESSION = /* @__PURE__ */ new Set(["two-factor"]);
+/**
+* Sign-ins are read from `ctx.context.newSession` after the endpoint ran,
+* which plugins such as `twoFactor` clear in their own after-hooks (the
+* sign-in isn't done until the second factor). Hooks run in plugin order,
+* so the audit log must come after them.
+*/
+function warnAboutOrder(ctx) {
+	const plugins = ctx.options.plugins ?? [];
+	const index = plugins.findIndex((plugin) => plugin.id === "audit-log");
+	const later = plugins.slice(index + 1).filter((plugin) => CLEARS_NEW_SESSION.has(plugin.id)).map((plugin) => plugin.id);
+	if (later.length > 0) ctx.logger.warn(`[audit-log] Put auditLog() after ${later.join(", ")} in "plugins", so sign-ins are recorded once they are complete.`);
+}
+/**
+* Records security-relevant events: sign-ins (any method) and failed
+* sign-ins, sign-ups, sign-outs, revoked sessions, password and email
+* changes, linked accounts, deleted users, and the actions of better-auth's
+* `admin` plugin. Users can list their own events, admins everyone's.
+*
+* @example
+* ```ts
+* import { betterAuth } from "better-auth";
+* import { auditLog } from "@checodo/better-auth-audit-log";
+*
+* export const auth = betterAuth({
+*   plugins: [
+*     // ...other plugins, then:
+*     auditLog({ retention: { days: 90 } }),
+*   ],
+* });
+* ```
+*/
+const auditLog = (options = {}) => {
+	const resolved = resolveOptions(options);
+	const recorder = createRecorder(resolved);
+	const plugin = {
+		id: "audit-log",
+		version,
+		init(ctx) {
+			warnAboutOrder(ctx);
+			return { options: { databaseHooks: createDatabaseHooks(ctx, recorder) } };
+		},
+		...resolved.storage ? {} : { schema: mergeSchema(structuredClone({
+			...auditLogSchema,
+			...resolved.hashChain ? auditChainSchema : {}
+		}), options.schema) },
+		endpoints: createEventEndpoints(resolved, recorder),
+		hooks: createPathHooks(resolved, recorder),
+		$ERROR_CODES: AUDIT_LOG_ERROR_CODES,
+		options
+	};
+	return Object.assign(plugin, { 
+	/**
+	* Records an event from another plugin or your own server code, with
+	* the current request's user, session, IP address, and user agent:
+	* `ctx.context.getPlugin("audit-log")?.recordEvent({ type: "x.y", userId })`.
+	* Never throws.
+	*/
+recordEvent: createRecordEvent(recorder) });
+};
+export { AUDIT_LOG_ERROR_CODES, auditLog, memoryStorage };
+
+//# sourceMappingURL=index.js.map