discord-guardian 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 discord-guardian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# discord-guardian
+
+Test your Discord bot against simulated nukes without breaking anything.
+
+[![npm](https://img.shields.io/npm/v/discord-guardian)](https://www.npmjs.com/package/discord-guardian)
+[![license](https://img.shields.io/npm/l/discord-guardian)](./LICENSE)
+
+## Setup
+
+```js
+import { guardian } from "discord-guardian"
+
+guardian(client).auto()
+```
+
+## Simulation
+
+Run detection logic and UI without real actions.
+
+```js
+// simulate bans to trigger detection
+guardian(client).simulateAttack({ type: "ban", count: 3 })
+```
+
+Output
+```text
+[guardian] simulation start (antiBan)
+[guardian] step 1/3
+[guardian] step 2/3
+[guardian] antiBan -> count=3/3
+[guardian] antiBan -> threshold reached
+[guardian] simulation complete
+```
+
+## Logging
+
+Logs threshold progress and triggers.
+
+```text
+[guardian] antiKick -> count=2/3
+[guardian] antiKick -> threshold reached
+```
+
+## Features
+
+- simulate attacks without real actions
+- zero config setup via `.auto()`
+- minimal, structured logs
+- clear simulation indicators in Discord
+
+## Modules
+
+| module | trigger |
+|--------|---------|
+| `antiBan` | mass member bans |
+| `antiKick` | mass member kicks |
+| `antiBotAdd` | unauthorized bot adds |
+| `antiChannelDelete` | mass channel removals |
+
+## Permissions
+
+- View Audit Log
+- Ban Members
+- Kick Members
+- Manage Roles
+- Send Messages
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "discord-guardian",
+  "version": "1.0.1",
+  "description": "Test your Discord bot against simulated nukes and protect it with minimal setup.",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node test/smoke.js"
+  },
+  "keywords": [
+    "discord",
+    "discordjs",
+    "discord-bot",
+    "antinuke",
+    "raid-protection",
+    "security",
+    "testing",
+    "sdk",
+    "nodejs"
+  ],
+  "author": "demondev_",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/demondevx/discord-guardian.git"
+  },
+  "bugs": {
+    "url": "https://github.com/demondevx/discord-guardian/issues"
+  },
+  "homepage": "https://github.com/demondevx/discord-guardian#readme",
+  "peerDependencies": {
+    "discord.js": "^14.26.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/core/EventBus.js

@@ -0,0 +1,24 @@
+import { EventEmitter } from "events"
+
+export class EventBus extends EventEmitter {
+  /**
+   * Emit an event.
+   */
+  emit(event, ...args) {
+    return super.emit(event, ...args)
+  }
+
+  /**
+   * Listen for an event.
+   */
+  on(event, listener) {
+    return super.on(event, listener)
+  }
+
+  /**
+   * Remove a listener.
+   */
+  off(event, listener) {
+    return super.removeListener(event, listener)
+  }
+}

package/src/core/Guardian.js

@@ -0,0 +1,104 @@
+import { EventBus } from "./EventBus.js"
+import { setupInteractionHandler } from "../utils/interactionHandler.js"
+
+const MODULE_REGISTRY = {
+  antiBan:           () => import("../modules/antiBan.js").then((m) => m.antiBan),
+  antiKick:          () => import("../modules/antiKick.js").then((m) => m.antiKick),
+  antiBotAdd:        () => import("../modules/antiBotAdd.js").then((m) => m.antiBotAdd),
+  antiChannelDelete: () => import("../modules/antiChannelDelete.js").then((m) => m.antiChannelDelete),
+}
+
+export class Guardian {
+  /**
+   * @param {import("discord.js").Client} client
+   */
+  constructor(client) {
+    if (!client) throw new Error("[guardian] client is required")
+
+    this.client = client
+    this.eventBus = new EventBus()
+    this._activeModules = new Map()
+
+    setupInteractionHandler(this.client, this.eventBus)
+  }
+
+  /**
+   * Initialize with default protections.
+   */
+  auto() {
+    return this.protectAll()
+  }
+
+  /**
+   * Enable all built-in modules.
+   */
+  protectAll() {
+    for (const name of Object.keys(MODULE_REGISTRY)) {
+      this.use(name)
+    }
+    return this
+  }
+
+  /**
+   * Enable a specific protection module.
+   * @param {string} moduleName
+   * @param {object} [config]
+   */
+  use(moduleName, config = {}) {
+    if (!MODULE_REGISTRY[moduleName]) return this
+    if (this._activeModules.has(moduleName)) return this
+
+    this._activeModules.set(moduleName, config)
+
+    MODULE_REGISTRY[moduleName]().then((initFn) => {
+      initFn(this.client, this.eventBus, config)
+    }).catch((err) => {
+      console.error(`[guardian] failed to load ${moduleName}:`, err)
+    })
+
+    return this
+  }
+
+  /**
+   * Simulate an attack for testing detection logic.
+   * @param {object} options
+   */
+  async simulateAttack({ type, count = 3 }) {
+    const moduleName = `anti${String(type).charAt(0).toUpperCase() + String(type).slice(1)}`
+    
+    this._log(`simulation start (${moduleName})`)
+
+    for (let i = 1; i <= count; i++) {
+      await new Promise(r => setTimeout(r, 100))
+      this._log(`step ${i}/${count}`)
+      
+      this.eventBus.emit(`simulate:${moduleName}`, {
+        executorId: "000000000000000000",
+        guild: { 
+          id: "000000000000000000",
+          name: "simulation server",
+          members: this.client.users,
+          channels: { fetch: async () => null },
+          fetchAuditLogs: async () => ({ entries: new Map() })
+        }
+      })
+    }
+
+    this._log("simulation complete")
+    return this
+  }
+
+  /**
+   * Listen for guardian events.
+   * @param {string} event
+   * @param {Function} callback
+   */
+  on(event, callback) {
+    this.eventBus.on(event, callback)
+    return this
+  }
+
+  _log(message) {
+    console.log(`[guardian] ${message}`)
+  }
+}

package/src/index.js

@@ -0,0 +1,12 @@
+import { Guardian } from "./core/Guardian.js"
+
+/**
+ * Initialize a new Guardian instance.
+ * @param {import("discord.js").Client} client
+ */
+export function guardian(client) {
+  return new Guardian(client)
+}
+
+export { Guardian }
+export { EventBus } from "./core/EventBus.js"

package/src/modules/antiBan.js

@@ -0,0 +1,69 @@
+import { AuditLogEvent } from "discord.js"
+import { RateLimiter } from "../utils/rateLimiter.js"
+import { executePunishment } from "../utils/punishments.js"
+import { createThreatMessage } from "../utils/threatMessage.js"
+
+const DEFAULTS = {
+  maxBans: 3,
+  windowMs: 15_000,
+  punishment: "ban",
+  logChannelId: null,
+  whitelist: [],
+}
+
+/**
+ * Anti-ban protection module.
+ * @param {import("discord.js").Client} client
+ * @param {import("../core/EventBus.js").EventBus} eventBus
+ * @param {object} [config]
+ */
+export function antiBan(client, eventBus, config = {}) {
+  const opts = { ...DEFAULTS, ...config }
+  const limiter = new RateLimiter(opts.maxBans, opts.windowMs)
+
+  const handle = async (executorId, guild, isSimulated = false) => {
+    if (opts.whitelist.includes(executorId)) return
+
+    if (!limiter.hit(executorId) && !isSimulated) return
+
+    if (limiter.count(executorId) >= opts.maxBans || isSimulated) {
+      if (limiter.count(executorId) === opts.maxBans || isSimulated) {
+        console.log(`[guardian] antiBan -> count=${limiter.count(executorId)}/${opts.maxBans}`)
+        console.log(`[guardian] antiBan -> threshold reached`)
+      }
+
+      eventBus.emit("threatDetected", {
+        type: "antiBan",
+        executorId,
+        guild,
+        isSimulated
+      })
+
+      const member = await guild.members.fetch(executorId).catch(() => null)
+      if (member) {
+        await executePunishment(guild, member, opts.punishment, "antiBan threshold exceeded", isSimulated)
+      }
+
+      const logChannelId = opts.logChannelId
+      if (logChannelId) {
+        const channel = await guild.channels.fetch(logChannelId).catch(() => null)
+        if (channel) {
+          await channel.send(createThreatMessage({
+            userId: executorId,
+            threatType: "antiBan",
+            isSimulated
+          })).catch(() => {})
+        }
+      }
+    }
+  }
+
+  client.on("guildBanAdd", async (ban) => {
+    const logs = await ban.guild.fetchAuditLogs({ type: AuditLogEvent.MemberBanAdd, limit: 1 }).catch(() => null)
+    const entry = logs?.entries.first()
+    if (!entry || entry.executor.id === client.user.id) return
+    handle(entry.executor.id, ban.guild)
+  })
+
+  eventBus.on("simulate:antiBan", (data) => handle(data.executorId, data.guild, true))
+}

package/src/modules/antiBotAdd.js

@@ -0,0 +1,71 @@
+import { AuditLogEvent } from "discord.js"
+import { RateLimiter } from "../utils/rateLimiter.js"
+import { executePunishment } from "../utils/punishments.js"
+import { createThreatMessage } from "../utils/threatMessage.js"
+
+const DEFAULTS = {
+  maxBots: 2,
+  windowMs: 30_000,
+  punishment: "ban",
+  logChannelId: null,
+  whitelist: [],
+}
+
+/**
+ * Anti-bot protection module.
+ * @param {import("discord.js").Client} client
+ * @param {import("../core/EventBus.js").EventBus} eventBus
+ * @param {object} [config]
+ */
+export function antiBotAdd(client, eventBus, config = {}) {
+  const opts = { ...DEFAULTS, ...config }
+  const limiter = new RateLimiter(opts.maxBots, opts.windowMs)
+
+  const handle = async (executorId, guild, isSimulated = false) => {
+    if (opts.whitelist.includes(executorId)) return
+
+    if (!limiter.hit(executorId) && !isSimulated) return
+
+    if (limiter.count(executorId) >= opts.maxBots || isSimulated) {
+      if (limiter.count(executorId) === opts.maxBots || isSimulated) {
+        console.log(`[guardian] antiBotAdd -> count=${limiter.count(executorId)}/${opts.maxBots}`)
+        console.log(`[guardian] antiBotAdd -> threshold reached`)
+      }
+
+      eventBus.emit("threatDetected", {
+        type: "antiBotAdd",
+        executorId,
+        guild,
+        isSimulated
+      })
+
+      const member = await guild.members.fetch(executorId).catch(() => null)
+      if (member) {
+        await executePunishment(guild, member, opts.punishment, "antiBotAdd threshold exceeded", isSimulated)
+      }
+
+      const logChannelId = opts.logChannelId
+      if (logChannelId) {
+        const channel = await guild.channels.fetch(logChannelId).catch(() => null)
+        if (channel) {
+          await channel.send(createThreatMessage({
+            userId: executorId,
+            threatType: "antiBotAdd",
+            isSimulated
+          })).catch(() => {})
+        }
+      }
+    }
+  }
+
+  client.on("guildMemberAdd", async (member) => {
+    if (!member.user.bot) return
+    const logs = await member.guild.fetchAuditLogs({ type: AuditLogEvent.BotAdd, limit: 1 }).catch(() => null)
+    const entry = logs?.entries.first()
+    if (!entry || (Date.now() - entry.createdTimestamp > 10000)) return
+    if (entry.target?.id !== member.id || entry.executor.id === client.user.id) return
+    handle(entry.executor.id, member.guild)
+  })
+
+  eventBus.on("simulate:antiBotAdd", (data) => handle(data.executorId, data.guild, true))
+}

package/src/modules/antiChannelDelete.js

@@ -0,0 +1,70 @@
+import { AuditLogEvent } from "discord.js"
+import { RateLimiter } from "../utils/rateLimiter.js"
+import { executePunishment } from "../utils/punishments.js"
+import { createThreatMessage } from "../utils/threatMessage.js"
+
+const DEFAULTS = {
+  maxDeletes: 3,
+  windowMs: 15_000,
+  punishment: "ban",
+  logChannelId: null,
+  whitelist: [],
+}
+
+/**
+ * Anti-channel-delete protection module.
+ * @param {import("discord.js").Client} client
+ * @param {import("../core/EventBus.js").EventBus} eventBus
+ * @param {object} [config]
+ */
+export function antiChannelDelete(client, eventBus, config = {}) {
+  const opts = { ...DEFAULTS, ...config }
+  const limiter = new RateLimiter(opts.maxDeletes, opts.windowMs)
+
+  const handle = async (executorId, guild, isSimulated = false) => {
+    if (opts.whitelist.includes(executorId)) return
+
+    if (!limiter.hit(executorId) && !isSimulated) return
+
+    if (limiter.count(executorId) >= opts.maxDeletes || isSimulated) {
+      if (limiter.count(executorId) === opts.maxDeletes || isSimulated) {
+        console.log(`[guardian] antiChannelDelete -> count=${limiter.count(executorId)}/${opts.maxDeletes}`)
+        console.log(`[guardian] antiChannelDelete -> threshold reached`)
+      }
+
+      eventBus.emit("threatDetected", {
+        type: "antiChannelDelete",
+        executorId,
+        guild,
+        isSimulated
+      })
+
+      const member = await guild.members.fetch(executorId).catch(() => null)
+      if (member) {
+        await executePunishment(guild, member, opts.punishment, "antiChannelDelete threshold exceeded", isSimulated)
+      }
+
+      const logChannelId = opts.logChannelId
+      if (logChannelId) {
+        const channel = await guild.channels.fetch(logChannelId).catch(() => null)
+        if (channel) {
+          await channel.send(createThreatMessage({
+            userId: executorId,
+            threatType: "antiChannelDelete",
+            isSimulated
+          })).catch(() => {})
+        }
+      }
+    }
+  }
+
+  client.on("channelDelete", async (channel) => {
+    if (!channel.guild) return
+    const logs = await channel.guild.fetchAuditLogs({ type: AuditLogEvent.ChannelDelete, limit: 1 }).catch(() => null)
+    const entry = logs?.entries.first()
+    if (!entry || (Date.now() - entry.createdTimestamp > 5000) || entry.executor.id === client.user.id) return
+    handle(entry.executor.id, channel.guild)
+  })
+
+  eventBus.on("simulate:antiChannelDelete", (data) => handle(data.executorId, data.guild, true))
+}

package/src/modules/antiKick.js

@@ -0,0 +1,70 @@
+import { AuditLogEvent } from "discord.js"
+import { RateLimiter } from "../utils/rateLimiter.js"
+import { executePunishment } from "../utils/punishments.js"
+import { createThreatMessage } from "../utils/threatMessage.js"
+
+const DEFAULTS = {
+  maxKicks: 3,
+  windowMs: 15_000,
+  punishment: "ban",
+  logChannelId: null,
+  whitelist: [],
+}
+
+/**
+ * Anti-kick protection module.
+ * @param {import("discord.js").Client} client
+ * @param {import("../core/EventBus.js").EventBus} eventBus
+ * @param {object} [config]
+ */
+export function antiKick(client, eventBus, config = {}) {
+  const opts = { ...DEFAULTS, ...config }
+  const limiter = new RateLimiter(opts.maxKicks, opts.windowMs)
+
+  const handle = async (executorId, guild, isSimulated = false) => {
+    if (opts.whitelist.includes(executorId)) return
+
+    if (!limiter.hit(executorId) && !isSimulated) return
+
+    if (limiter.count(executorId) >= opts.maxKicks || isSimulated) {
+      if (limiter.count(executorId) === opts.maxKicks || isSimulated) {
+        console.log(`[guardian] antiKick -> count=${limiter.count(executorId)}/${opts.maxKicks}`)
+        console.log(`[guardian] antiKick -> threshold reached`)
+      }
+
+      eventBus.emit("threatDetected", {
+        type: "antiKick",
+        executorId,
+        guild,
+        isSimulated
+      })
+
+      const member = await guild.members.fetch(executorId).catch(() => null)
+      if (member) {
+        await executePunishment(guild, member, opts.punishment, "antiKick threshold exceeded", isSimulated)
+      }
+
+      const logChannelId = opts.logChannelId
+      if (logChannelId) {
+        const channel = await guild.channels.fetch(logChannelId).catch(() => null)
+        if (channel) {
+          await channel.send(createThreatMessage({
+            userId: executorId,
+            threatType: "antiKick",
+            isSimulated
+          })).catch(() => {})
+        }
+      }
+    }
+  }
+
+  client.on("guildMemberRemove", async (member) => {
+    const logs = await member.guild.fetchAuditLogs({ type: AuditLogEvent.MemberKick, limit: 1 }).catch(() => null)
+    const entry = logs?.entries.first()
+    if (!entry || (Date.now() - entry.createdTimestamp > 5000)) return
+    if (entry.target?.id !== member.id || entry.executor.id === client.user.id) return
+    handle(entry.executor.id, member.guild)
+  })
+
+  eventBus.on("simulate:antiKick", (data) => handle(data.executorId, data.guild, true))
+}

package/src/utils/idParser.js

@@ -0,0 +1,16 @@
+/**
+ * Parses a Discord snowflake from varying input formats.
+ * @param {string} input
+ * @returns {string|null}
+ */
+export function parseId(input) {
+  if (!input || typeof input !== "string") return null
+
+  const match = input.match(/^<[@#][!&]?(\d+)>$/)
+  if (match) return match[1]
+
+  const raw = input.trim()
+  if (/^\d{17,20}$/.test(raw)) return raw
+
+  return null
+}

package/src/utils/interactionHandler.js

@@ -0,0 +1,74 @@
+import { safeReply } from "./safeReply.js"
+import { executePunishment } from "./punishments.js"
+
+export function setupInteractionHandler(client, eventBus) {
+  client.on("interactionCreate", async (interaction) => {
+    try {
+      if (interaction.isButton()) {
+        const [scope, action, targetId] = interaction.customId.split(":")
+        if (scope !== "guardian") return
+
+        await interaction.deferReply({ ephemeral: true })
+
+        if (action === "punish") {
+          const guild = interaction.guild
+          if (!guild) return await safeReply(interaction, { content: "❌ Not in a guild." })
+
+          const member = await guild.members.fetch(targetId).catch(() => null)
+          if (!member) return await safeReply(interaction, { content: "❌ Member not found." })
+
+          await executePunishment(guild, member, "ban")
+          eventBus.emit("punishmentExecuted", {
+            type: "ban",
+            targetId,
+            executorId: interaction.user.id,
+            guild,
+          })
+
+          await safeReply(interaction, { content: `✅ **${member.user.tag}** banned.` })
+        }
+
+        if (action === "ignore") {
+          eventBus.emit("threatIgnored", {
+            targetId,
+            executorId: interaction.user.id,
+            guild: interaction.guild,
+          })
+          await safeReply(interaction, { content: "✅ Ignored." })
+        }
+        return
+      }
+
+      if (interaction.isStringSelectMenu()) {
+        const [scope, action, targetId] = interaction.customId.split(":")
+        if (scope !== "guardian") return
+
+        await interaction.deferReply({ ephemeral: true })
+
+        const type = interaction.values[0]
+        const guild = interaction.guild
+        if (!guild) return await safeReply(interaction, { content: "❌ Not in a guild." })
+
+        const member = await guild.members.fetch(targetId).catch(() => null)
+        if (!member) return await safeReply(interaction, { content: "❌ Member not found." })
+
+        await executePunishment(guild, member, type)
+        eventBus.emit("punishmentExecuted", {
+          type,
+          targetId,
+          executorId: interaction.user.id,
+          guild,
+        })
+
+        const labels = { ban: "banned", kick: "kicked", roles: "roles removed" }
+        await safeReply(interaction, { content: `✅ **${member.user.tag}** ${labels[type] || type}.` })
+        return
+      }
+    } catch (err) {
+      console.error("[Guardian] Interaction error:", err)
+      if (!interaction.replied && !interaction.deferred) {
+        await interaction.reply({ content: "❌ Internal error.", ephemeral: true }).catch(() => {})
+      }
+    }
+  })
+}

package/src/utils/punishments.js

@@ -0,0 +1,31 @@
+/**
+ * Execute a punishment on a member.
+ * @param {import("discord.js").Guild} guild
+ * @param {import("discord.js").GuildMember} member
+ * @param {"ban"|"kick"|"roles"} type
+ * @param {string} [reason]
+ * @param {boolean} [isSimulated]
+ */
+export async function executePunishment(
+  guild,
+  member,
+  type,
+  reason = "Guardian Action",
+  isSimulated = false
+) {
+  if (isSimulated) return
+
+  switch (type) {
+    case "ban":
+      await guild.members.ban(member.id, { reason, deleteMessageSeconds: 0 })
+      break
+    case "kick":
+      await member.kick(reason)
+      break
+    case "roles":
+      await member.roles.set([], reason)
+      break
+    default:
+      console.warn(`[guardian] unknown punishment: ${type}`)
+  }
+}

package/src/utils/rateLimiter.js

@@ -0,0 +1,47 @@
+export class RateLimiter {
+  /**
+   * @param {number} limit
+   * @param {number} windowMs
+   */
+  constructor(limit, windowMs) {
+    this.limit = limit
+    this.windowMs = windowMs
+    this.hits = new Map()
+    this.intervals = new Map()
+  }
+
+  /**
+   * Register a hit and return true if limit is reached.
+   * @param {string} key
+   */
+  hit(key) {
+    const now = Date.now()
+    let userHits = this.hits.get(key) || []
+    
+    userHits = userHits.filter(timestamp => now - timestamp < this.windowMs)
+    userHits.push(now)
+    this.hits.set(key, userHits)
+
+    return userHits.length >= this.limit
+  }
+
+  /**
+   * Get current hit count for a key.
+   * @param {string} key
+   */
+  count(key) {
+    return this.hits.get(key)?.length || 0
+  }
+
+  reset(key) {
+    this.hits.delete(key)
+  }
+
+  destroy() {
+    this.hits.clear()
+    for (const interval of this.intervals.values()) {
+      clearInterval(interval)
+    }
+    this.intervals.clear()
+  }
+}

package/src/utils/safeReply.js

@@ -0,0 +1,15 @@
+/**
+ * Safely reply to a discord.js interaction.
+ * @param {import("discord.js").Interaction} interaction
+ * @param {import("discord.js").InteractionReplyOptions} options
+ */
+export async function safeReply(interaction, options) {
+  try {
+    if (interaction.replied || interaction.deferred) {
+      return await interaction.editReply(options)
+    }
+    return await interaction.reply(options)
+  } catch (err) {
+    console.error("[guardian] safeReply error:", err.message)
+  }
+}

package/src/utils/threatMessage.js

@@ -0,0 +1,44 @@
+/**
+ * Build a threat-alert message.
+ * @param {object} opts
+ */
+export function createThreatMessage({ userId, threatType, details, isSimulated }) {
+  const embed = new EmbedBuilder()
+    .setColor(0xff3b3b)
+    .setTitle(isSimulated ? "⚠️ Simulation Mode" : "Guardian — Threat Detected")
+    .setDescription(isSimulated ? "⚠️ Simulation Mode — no real actions will be taken" : "Suspicious activity filtered and blocked.")
+    .addFields(
+      { name: "User", value: `<@${userId}>`, inline: true },
+      { name: "Module", value: `\`${threatType}\``, inline: true },
+    )
+    .setTimestamp()
+
+  if (details) embed.addFields({ name: "Details", value: details })
+
+  const buttons = new ActionRowBuilder().addComponents(
+    new ButtonBuilder()
+      .setCustomId(`guardian:punish:${userId}`)
+      .setLabel(isSimulated ? "Simulate Punish" : "Punish User")
+      .setStyle(ButtonStyle.Danger),
+    new ButtonBuilder()
+      .setCustomId(`guardian:ignore:${userId}`)
+      .setLabel("Ignore")
+      .setStyle(ButtonStyle.Secondary),
+  )
+
+  const menu = new ActionRowBuilder().addComponents(
+    new StringSelectMenuBuilder()
+      .setCustomId(`guardian:select:${userId}`)
+      .setPlaceholder("Select punishment...")
+      .addOptions([
+        { label: "Ban",          value: "ban" },
+        { label: "Kick",         value: "kick" },
+        { label: "Remove Roles", value: "roles" },
+      ]),
+  )
+
+  return {
+    embeds: [embed],
+    components: [buttons, menu],
+  }
+}