feat: add AuditLogManager for dashboard settings audit logging

prisma/migrations/20260416120000_add_dashboard_audit_log/migration.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "audit_log" (
+  "id" SERIAL NOT NULL,
+  "guild_id" VARCHAR(19) NOT NULL,
+  "user_id" VARCHAR(19) NOT NULL,
+  "action" VARCHAR(64) NOT NULL,
+  "section" VARCHAR(64) NOT NULL,
+  "changes" JSON NOT NULL DEFAULT '[]',
+  "created_at" TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "audit_log_pkey" PRIMARY KEY ("id")
+);
+CREATE INDEX "IDX_audit_log_guild_created" ON "audit_log"("guild_id", "created_at" DESC);
+ALTER TABLE "audit_log" ADD CONSTRAINT "audit_log_guild_id_fkey" FOREIGN KEY ("guild_id") REFERENCES "guilds"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/schema.prisma

@@ -174,9 +174,12 @@ model Guild {
   channelsIgnoreVoiceActivity          String[] @default([]) @map("channels.ignore.voice-activity") @db.VarChar(19)
   eventsTimeout                        Boolean  @default(false) @map("events.timeout")
 
+  auditLogs AuditLog[]
+
   @@map("guilds")
 }
 
+
 model Migration {
   id        Int    @id(map: "PK_Migrations") @default(autoincrement())
   timestamp BigInt
@@ -219,3 +222,19 @@ model User {
 
   @@map("user")
 }
+
+model AuditLog {
+  id        Int      @id @default(autoincrement())
+  guild     Guild    @relation(fields: [guildId], references: [id], onDelete: Cascade)
+  guildId   String   @map("guild_id") @db.VarChar(19)
+  userId    String   @map("user_id") @db.VarChar(19)
+  action    String   @db.VarChar(64)
+  section   String   @db.VarChar(64)
+  /// [AuditLogChanges]
+  changes   Json     @default("[]") @db.Json
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamp(6)
+
+  @@index([guildId, createdAt(sort: Desc)], map: "IDX_audit_log_guild_created")
+  @@map("audit_log")
+}
+

src/lib/database/settings/context/SettingsContext.ts

@@ -1,5 +1,6 @@
 import { AdderManager } from '#lib/database/settings/structures/AdderManager';
 import { PermissionNodeManager } from '#lib/database/settings/structures/PermissionNodeManager';
+import { AuditLogManager } from '#lib/database/settings/structures/AuditLogManager';
 import type { ReadonlyGuildData } from '#lib/database/settings/types';
 import { create } from '#utils/Security/RegexCreator';
 import { RateLimitManager } from '@sapphire/ratelimits';
@@ -8,12 +9,14 @@ import { isNullish, isNullishOrEmpty } from '@sapphire/utilities';
 export class SettingsContext {
 	readonly #adders: AdderManager;
 	readonly #permissionNodes: PermissionNodeManager;
+	#auditLog: AuditLogManager;
 	#wordFilterRegExp: RegExp | null;
 	#noMentionSpam: RateLimitManager;
 
 	public constructor(settings: ReadonlyGuildData) {
 		this.#adders = new AdderManager(settings);
 		this.#permissionNodes = new PermissionNodeManager(settings);
+		this.#auditLog = new AuditLogManager(settings);
 		this.#wordFilterRegExp = isNullishOrEmpty(settings.selfmodFilterRaw) ? null : new RegExp(create(settings.selfmodFilterRaw), 'gi');
 		this.#noMentionSpam = new RateLimitManager(settings.noMentionSpamTimePeriod * 1000, settings.noMentionSpamMentionsAllowed);
 	}
@@ -26,6 +29,10 @@ export class SettingsContext {
 		return this.#permissionNodes;
 	}
 
+	public get auditLog() {
+		return this.#auditLog;
+	}
+
 	public get wordFilterRegExp() {
 		return this.#wordFilterRegExp;
 	}
@@ -36,6 +43,7 @@ export class SettingsContext {
 
 	public update(settings: ReadonlyGuildData, data: Partial<ReadonlyGuildData>) {
 		this.#adders.onPatch(settings);
+		this.#auditLog.onPatch(settings);
 
 		if (!isNullish(data.permissionsRoles) || !isNullish(data.permissionsUsers)) {
 			this.#permissionNodes.refresh(settings);

src/lib/database/settings/functions.ts

@@ -61,6 +61,10 @@ export function readSettingsCached(guild: GuildResolvable): ReadonlyGuildData |
 	return cache.get(resolveGuildId(guild)) ?? null;
 }
 
+export function readSettingsAuditLog(settings: ReadonlyGuildData) {
+	return getSettingsContext(settings).auditLog;
+}
+
 export async function writeSettings(
 	guild: GuildResolvable,
 	data: Partial<ReadonlyGuildData> | ((settings: ReadonlyGuildData) => Awaitable<Partial<ReadonlyGuildData>>)

src/lib/database/settings/index.ts

@@ -5,6 +5,7 @@ export * from '#lib/database/settings/schema/SchemaGroup';
 export * from '#lib/database/settings/schema/SchemaKey';
 export * from '#lib/database/settings/structures/AdderManager';
 export * from '#lib/database/settings/structures/PermissionNodeManager';
+export * from '#lib/database/settings/structures/AuditLogManager';
 export * from '#lib/database/settings/structures/Serializer';
 export * from '#lib/database/settings/structures/SerializerStore';
 export * from '#lib/database/settings/types';

src/lib/database/settings/structures/AuditLogManager.ts

@@ -0,0 +1,101 @@
+import type { AuditLogChange, ReadonlyGuildData } from '#lib/database/settings/types';
+import { container } from '@sapphire/framework';
+
+export class AuditLogManager {
+	#guildId: string;
+	#settings: ReadonlyGuildData;
+
+	public constructor(settings: ReadonlyGuildData) {
+		this.#guildId = settings.id;
+		this.#settings = settings;
+	}
+
+	public onPatch(settings: ReadonlyGuildData): void {
+		this.#guildId = settings.id;
+		this.#settings = settings;
+	}
+
+	public update(userId: string, newData: Record<string, unknown>): Promise<void> {
+		const changedKeys = Object.keys(newData);
+		const changes = this.#buildChanges(newData);
+
+		return this.write(userId, {
+			action: 'settings.update',
+			section: AuditLogManager.deriveSection(changedKeys),
+			changes
+		});
+	}
+
+	public add(userId: string, key: string, value: unknown): Promise<void> {
+		return this.write(userId, {
+			action: 'settings.add',
+			section: AuditLogManager.deriveSection([key]),
+			changes: [{ key, newValue: AuditLogManager.serializeValue(value) }]
+		});
+	}
+
+	public remove(userId: string, key: string, value: unknown): Promise<void> {
+		return this.write(userId, {
+			action: 'settings.remove',
+			section: AuditLogManager.deriveSection([key]),
+			changes: [{ key, oldValue: AuditLogManager.serializeValue(value) }]
+		});
+	}
+
+	public async write(userId: string, params: { action: string; section: string; changes: AuditLogChange[] }): Promise<void> {
+		await container.prisma.auditLog.create({
+			data: {
+				guildId: this.#guildId,
+				userId,
+				action: params.action,
+				section: params.section,
+				changes: JSON.parse(JSON.stringify(params.changes))
+			}
+		});
+	}
+
+	#buildChanges(newData: Record<string, unknown>): AuditLogChange[] {
+		return Object.keys(newData).map((key) => ({
+			key,
+			oldValue: AuditLogManager.serializeValue((this.#settings as Record<string, unknown>)[key]),
+			newValue: AuditLogManager.serializeValue(newData[key])
+		}));
+	}
+
+	private static deriveSection(keys: string[]): string {
+		const counts = new Map<string, number>();
+		for (const key of keys) {
+			const section = AuditLogManager.classifyKey(key);
+			counts.set(section, (counts.get(section) ?? 0) + 1);
+		}
+
+		if (counts.size === 0) return 'general';
+		if (counts.size === 1) return counts.keys().next().value!;
+
+		let best = 'general';
+		let max = 0;
+		for (const [section, count] of counts) {
+			if (count > max) {
+				max = count;
+				best = section;
+			}
+		}
+		return best;
+	}
+
+	private static classifyKey(key: string): string {
+		if (key.startsWith('permissions')) return 'permissions';
+		if (key.startsWith('selfmod') || key.startsWith('noMentionSpam')) return 'moderation';
+		if (key.startsWith('channels')) return 'channels';
+		if (key.startsWith('roles')) return 'roles';
+		if (key.startsWith('events')) return 'events';
+		if (key.startsWith('messages')) return 'messages';
+		if (key.startsWith('disabled')) return 'commands';
+		return 'general';
+	}
+
+	private static serializeValue(value: unknown): unknown {
+		if (typeof value === 'bigint') return Number(value);
+		return value;
+	}
+}

src/lib/database/settings/types.ts

@@ -14,6 +14,12 @@ import type { Snowflake } from 'discord.js';
 
 export type { Guild as GuildData, Moderation as ModerationData, User as UserData } from '#generated/prisma';
 
+export interface AuditLogChange {
+	key: string;
+	oldValue?: unknown;
+	newValue?: unknown;
+}
+
 export interface PermissionsNode {
 	allow: readonly Snowflake[];
 	deny: readonly Snowflake[];

src/lib/types/Augments.d.ts

@@ -7,7 +7,8 @@ import type {
 	ReactionRole,
 	SerializerStore,
 	StickyRole,
-	UniqueRoleSet
+	UniqueRoleSet,
+	AuditLogChange
 } from '#lib/database';
 import type { GuildMemberFetchQueue } from '#lib/discord/GuildMemberFetchQueue';
 import type { WorkerManager } from '#lib/moderation/workers/WorkerManager';
@@ -34,6 +35,7 @@ declare global {
 		export type StickyRoleEntries = StickyRole[];
 		export type ReactionRoleEntries = ReactionRole[];
 		export type UniqueRoleSetEntries = UniqueRoleSet[];
+		export type AuditLogChanges = AuditLogChange[];
 	}
 }
 

src/routes/guilds/[guild]/audit-logs.get.ts

@@ -0,0 +1,37 @@
+import { authenticated, canManage, ratelimit } from '#lib/api/utils';
+import { seconds } from '#utils/common';
+import { container } from '@sapphire/framework';
+import { HttpCodes, Route } from '@sapphire/plugin-api';
+
+export class UserRoute extends Route {
+	@authenticated()
+	@ratelimit(seconds(10), 5, true)
+	public async run(request: Route.Request, response: Route.Response) {
+		const guildId = request.params.guild;
+
+		const guild = container.client.guilds.cache.get(guildId);
+		if (!guild) return response.error(HttpCodes.BadRequest);
+
+		const member = await guild.members.fetch(request.auth!.id).catch(() => null);
+		if (!member) return response.error(HttpCodes.BadRequest);
+
+		if (!(await canManage(guild, member))) return response.error(HttpCodes.Forbidden);
+
+		const take = Math.min(Number(request.query.take) || 50, 100);
+		const skip = Math.max(Number(request.query.skip) || 0, 0);
+
+		const [results, total] = await Promise.all([
+			container.prisma.auditLog.findMany({
+				where: { guildId },
+				orderBy: { createdAt: 'desc' },
+				take,
+				skip
+			}),
+			container.prisma.auditLog.count({
+				where: { guildId }
+			})
+		]);
+
+		return response.status(HttpCodes.OK).json({ entries: results, total });
+	}
+}

src/routes/guilds/[guild]/settings.patch.ts

@@ -2,6 +2,7 @@ import { authenticated, canManage, ratelimit } from '#lib/api/utils';
 import {
 	getConfigurableKeys,
 	isSchemaKey,
+	readSettingsAuditLog,
 	serializeSettings,
 	writeSettingsTransaction,
 	type GuildDataValue,
@@ -37,7 +38,15 @@ export class UserRoute extends Route {
 		try {
 			using trx = await writeSettingsTransaction(guild);
 			const data = await this.validateAll(trx.settings, guild, entries);
-			await trx.write(Object.fromEntries(data)).submit();
+			const settingsData = Object.fromEntries(data);
+
+			// Capture current settings for audit log before mutation
+			const auditLog = readSettingsAuditLog(structuredClone(trx.settings));
+
+			await trx.write(settingsData).submit();
+
+			// Fire-and-forget audit log write
+			auditLog.update(request.auth!.id, settingsData).catch(() => null);
 
 			return this.sendSettings(response, trx.settings);
 		} catch (errors) {