glassframe-protocol 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,197 @@
+# Changelog
+
+All notable changes to GlassFrame Protocol are logged here. This library
+follows semantic versioning (MAJOR.MINOR.PATCH). Runtime version metadata
+lives in `src/core/VersionInfo.js` (`VersionInfo.info()` /
+`VersionInfo.banner()`), so code can read the current version without
+parsing this file.
+
+# Changelog
+
+All notable changes to GlassFrame Protocol are logged here. This library
+follows semantic versioning (MAJOR.MINOR.PATCH). Runtime version metadata
+lives in `src/core/VersionInfo.js` (`VersionInfo.info()` /
+`VersionInfo.banner()`), so code can read the current version without
+parsing this file.
+
+## [1.2.0] - 2026-07-31
+
+Packaging and licensing changes to make this publishable to npm. No
+functional/runtime changes to any layer, engine, or command from 1.1.0.
+
+### Added
+
+- `GETTING_STARTED.md` - onboarding guide for adding GlassFrame to a bot you
+  already have running (this is the file to hand someone alongside the
+  package).
+- `scripts/build.js` + `npm run build` - produces `dist/`, the folder that
+  actually gets published (see `docs/PUBLISHING.md`). Uses `terser` for
+  real minification if it's installed as a devDependency, otherwise copies
+  files through unmodified rather than risking a hand-rolled comment
+  stripper - several files contain string literals with `//` in them (the
+  Groq endpoint URL, for one), which a naive regex-based stripper would
+  corrupt.
+- `docs/PUBLISHING.md` - step-by-step npm publishing (same steps on Termux,
+  Windows, and Linux), including what `"files"` in `package.json` does and
+  does not upload.
+- `.gitignore` for `node_modules/` and the generated `dist/`.
+
+### Changed
+
+- **License**: replaced the MIT license with a custom Limited Use License
+  (see `LICENSE`) - grants installing and using the package in your own bot
+  (personal or commercial), and withholds copying/modifying/redistributing
+  the source or reselling the library itself. This is the real mechanism
+  for restricting reuse; a plain `npm install`-able package cannot be made
+  technically unreadable once it's on someone's disk, since Node has to
+  parse the JS to run it. Not legal advice - see the note at the top of
+  `LICENSE`.
+- `package.json`: `main` now points at `dist/index.js`; added `files`
+  (whitelists what `npm publish` actually uploads - `src/` and the root
+  `config.js`/`index.js` are deliberately excluded), `prepublishOnly` (so
+  `dist/` can't go stale at publish time), `publishConfig.access: "public"`,
+  and placeholder `author`/`repository`/`homepage`/`bugs` fields to fill in.
+
+## [1.1.0] - 2026-07-31
+
+Adds a batch of security extensions, a performance layer, and faster
+processing under load - no breaking changes to the 1.0.0 API.
+
+### Added
+
+- `PhishingDatabase` (`src/security/PhishingDatabase.js`) - replaces the
+  inline link regex in Basic Security with a dedicated, server-editable
+  module: a live blocklist (`!gf phishing add/remove/list`) plus
+  general-purpose heuristics (raw-IP links, punycode/homograph domains,
+  digit-for-letter brand look-alikes, known shorteners). Ships with an
+  empty seed list by design - a hardcoded "known bad domains" list goes
+  stale immediately and risks flagging an innocent domain on unverified
+  information.
+- AntiNuke now watches three more attack surfaces:
+  - **Emoji/sticker bursts** - mass emoji or sticker deletion/creation is
+    tracked the same way channel/role bursts already were.
+  - **Invite abuse** - an unrestricted invite (no expiry, no use limit)
+    created by anyone *other than* recognized trusted staff is flagged;
+    the same pattern from real staff is left alone, so this doesn't turn
+    into noise on a server that already uses a permanent invite link.
+  - **Webhook message flooding** - a webhook created moments ago that then
+    sends a burst of messages is deleted immediately and traced back to
+    whoever created it. This closes a real gap: webhook messages carry no
+    guild member, so they were invisible to every other layer's per-member
+    checks.
+- AntiRaid now also runs **creation-time cluster correlation**
+  (`AntiRaidLayer._clusterScore`): a bulk-registered account farm that
+  trickles in slowly enough to dodge the join-rate counter is still caught
+  by noticing that several recent joiners' accounts were all created
+  within the same narrow window.
+- `EventQueue` (`src/core/EventQueue.js`) - a bounded-concurrency task
+  queue. Every Discord mutation `PunishmentEngine` performs and every
+  outbound Groq request now runs through one of two queues
+  (`frame.actionQueue`, `frame.aiQueue`) instead of firing unbounded, so a
+  burst (raid, nuke, wave of gray-zone messages) can't trip a rate limit by
+  hammering it all at once. See `docs/PERFORMANCE.md`.
+- `PerformanceMonitor` (`src/core/PerformanceMonitor.js`) and
+  `frame.getMetrics()` / `!gf metrics` - lightweight in-process event
+  counts and rolling latency averages, plus every cache's stats, in one
+  snapshot. No external dependency, no network call.
+- Command cooldown (`performance.commandCooldownMs`, default 3s) - prefix
+  commands are now throttled per user per guild.
+- `docs/PERFORMANCE.md`.
+
+### Changed
+
+- `GroqClient.classify()` split into a thin queued/cached front end and an
+  internal `_request()` - the per-request timeout clock now starts only
+  once a request actually leaves the queue, so a busy moment can no longer
+  cause a false "AI didn't respond in time".
+- `PunishmentEngine`: an open case can now **escalate** its action if
+  continued signals push the tier past what it was last acted on at (e.g.
+  log -> timeout -> kick -> ban within the same incident), instead of
+  freezing at whatever action was first decided for the entire debounce
+  window. Never downgrades, and a trusted member's ceiling
+  (quarantine/alert) is still respected on every re-evaluation.
+
+## [1.0.0] - 2026-07-29
+
+Initial release of **GlassFrame Protocol** - a full architectural rebuild of
+the previous `guardian-security-module`, renamed and restructured as a
+standalone library rather than a bundle of bot-side modules.
+
+### Added
+
+- Layered architecture (`Layer` base class): AntiRaid, AntiNuke, Basic
+  Security, and AI Moderation are now independently toggleable layers that
+  share one pipeline instead of four separate modules that each punished on
+  their own. `enable()`/`disable()` fully attach/detach a layer's listeners,
+  so a disabled layer does zero work.
+- `ThreatEngine` - a shared, decaying per-member risk score that every layer
+  reports to, so scattered small flags across layers combine into one
+  picture instead of triggering separate, redundant reactions. Tiers
+  (none/low/medium/high/critical) drive the punishment ladder.
+- `RoleAnalyzer` - role hierarchy checks (the protocol never attempts an
+  action it lacks permission for) and role **name** analysis: flags roles
+  whose name implies authority but hold no real permissions (impersonation
+  bait), and roles that quietly hold dangerous permissions under an
+  innocuous name. Exposed via the new `!gf scan` command and an automatic
+  audit the moment AntiNuke is armed.
+- `PunishmentEngine` - the single place that actually bans/kicks/times out/
+  quarantines a member. Consults role trust level before acting (a real
+  admin is never auto-banned - it's flagged for human review instead), and
+  debounces repeat signals against the same member so one incident produces
+  one action and one log line, not a stream of them.
+- `AIModerationLayer` + `GroqClient` - optional Groq-powered second opinion
+  for messages that land in the gray zone between local NLP's clean/dirty
+  thresholds. Supports an API key pool with automatic per-key cooldown on
+  rate-limit responses, so one exhausted key doesn't take moderation down.
+  Verdicts are cached briefly so repeated/near-identical messages don't each
+  cost a fresh call. Disabled by default - supply `aiModeration.apiKeys` to
+  turn it on.
+- `SmartLogger` - merges near-duplicate log events inside a short window
+  into a single message with a running count instead of one message per
+  event, and enforces a minimum interval between sends per guild.
+- 5-button control panel (`!gf panel`) - Activate/Deactivate AntiRaid, AI
+  Moderation, AntiNuke, and Basic Security individually, plus a fifth
+  "Full Protocol" button that arms or disarms all four together. Every
+  layer starts disabled until explicitly armed.
+- Prefix-only command surface (`!gf panel|status|scan|whitelist|help`) - no
+  slash commands are registered by this library, by design.
+- Dangerous permission-grant watchdog and identity-change watchdog inside
+  AntiNuke - a role quietly gaining Administrator, or the server's name/
+  icon/vanity URL changing, is flagged the moment it happens rather than
+  waiting for a repeat-offense threshold. A forensic role/channel snapshot
+  is captured the moment any AntiNuke threshold trips.
+- Alt-account composite scoring in AntiRaid (account age + username entropy
+  + missing avatar) alongside the existing join-velocity lockdown.
+- Link heuristics in Basic Security: raw-IP links, punycode domains, and
+  Discord look-alike domains.
+- Pluggable state persistence (`MemoryStateStore` by default,
+  `JSONFileStateStore` for restart-safe layer state with zero extra
+  dependencies - no native modules, ARM64/Termux-friendly).
+- `docs/CACHE_ARCHITECTURE.md` and `docs/PROTOCOL_LAYERS.md` - internal
+  architecture references for anyone extending the library.
+
+### Changed
+
+- Renamed from `guardian-security-module` to `glassframe-protocol`.
+  Directory layout moved from a flat `modules/` + `utils/` split into
+  `src/core`, `src/layers`, `src/moderation`, `src/ai`, `src/logging`,
+  `src/ui`, and `src/commands`.
+- All punishment decisions moved out of individual layers and into
+  `PunishmentEngine`; layers now report signals instead of calling
+  `.ban()` / `.kick()` / `.timeout()` directly.
+- Components V2 output kept (no legacy `EmbedBuilder` anywhere) and
+  extended to support the control panel's button row and event-count
+  badges on aggregated log messages.
+
+### Fixed
+
+- Anti-nuke's self-exemption check previously compared `executor.bot === false`
+  against the client's own ID, which could never be true for a bot account;
+  it now simply skips audit entries the client itself generated.
+
+## [0.x] - guardian-security-module (superseded)
+
+The pre-GlassFrame history shipped as `guardian-security-module` v1.0.0:
+local-NLP-only detection, flat `antiRaid.js` / `antiNuke.js` / `security.js`
+modules, each acting immediately and independently with no shared scoring,
+no role-name analysis, no AI layer, and no control panel.

package/GETTING_STARTED.md

@@ -0,0 +1,133 @@
+# Getting Started
+
+This is a library, not a bot - it has no login token of its own and does
+nothing until you attach it to a discord.js `Client` you already have
+running. This guide is written for that: you already have a working bot
+and want to add GlassFrame Protocol to it.
+
+If you're starting completely from scratch instead, `examples/basic-usage.js`
+is a full minimal bot (client creation included) you can copy and run
+directly.
+
+## Prerequisites
+
+- An existing discord.js v14.16+ bot, already logging in successfully
+- Node.js 18+ (GlassFrame's optional AI layer uses the global `fetch`)
+- Your bot invited with these permissions: Manage Roles, Kick Members, Ban
+  Members, Manage Channels, Manage Webhooks, View Audit Log, Moderate
+  Members, Manage Messages
+- These gateway intents enabled: `Guilds`, `GuildMembers`, `GuildMessages`,
+  `MessageContent`, `GuildModeration`
+
+## Step 1 - Place the folder
+
+Put the `glassframe-protocol` folder anywhere inside your existing project,
+for example:
+
+```
+your-bot/
+├── index.js
+├── node_modules/
+├── package.json
+└── libs/
+    └── glassframe-protocol/   <- this folder
+```
+
+You do **not** need to run `npm install` inside it for discord.js
+specifically. Node looks for `node_modules` starting at the file that's
+doing the `require()` and walks upward through parent folders - since
+`glassframe-protocol` is nested inside your project, it will find the
+discord.js your bot already has installed. If your project somehow doesn't
+have discord.js yet, run `npm install discord.js` at your project root as
+normal.
+
+## Step 2 - Attach it to your client
+
+In your main bot file, once your client is ready:
+
+```js
+const GlassFrame = require("./libs/glassframe-protocol");
+
+client.once("ready", () => {
+  const frame = new GlassFrame(client, {
+    // Required: tell GlassFrame where to send its logs.
+    getLogChannel: async (guild) =>
+      guild.channels.cache.find((c) => c.name === "security-logs") ?? null,
+
+    // Optional: which layers turn on immediately vs. stay off until
+    // someone arms them from the panel. Layers not listed here start OFF.
+    autoStart: ["basicSecurity", "antiRaid", "antiNuke"]
+  });
+
+  frame.on("warning", (w) => console.warn(`[GlassFrame:${w.layer}]`, w.message));
+});
+```
+
+This is the entire integration. You do not write a spam filter, a raid
+detector, a command handler, or any punishment logic - constructing
+`GlassFrame` attaches everything it needs to your existing `client`
+internally. Nothing else in your bot's code has to change.
+
+## Step 3 - Make a log channel
+
+Create a text channel (matching whatever `getLogChannel` looks for - the
+example above uses one named `security-logs`) and make sure your bot can
+see and send messages in it. Every alert, every punishment, every layer
+toggle gets reported there through Components V2 messages.
+
+## Step 4 - Turn features on
+
+Two ways, pick either or both:
+
+- **Code**: list layer names in `autoStart` (see Step 2), or call
+  `frame.enableLayer("antiNuke")` / `frame.disableLayer("antiNuke")`
+  anywhere after construction.
+- **In Discord**: an admin (Manage Server permission) sends `!gf panel` and
+  gets 5 buttons - Activate/Deactivate AntiRaid, AI Moderation, AntiNuke,
+  Basic Security, and Full Protocol (all four at once). This is the only
+  interface most server admins will ever need - no code, no slash commands.
+
+## Step 5 (optional) - AI Moderation
+
+Off by default. To turn it on:
+
+1. Get one or more free API keys from console.groq.com
+2. Pass them in config:
+   ```js
+   const frame = new GlassFrame(client, {
+     getLogChannel: /* ... */,
+     config: {
+       aiModeration: { apiKeys: (process.env.GROQ_API_KEYS || "").split(",") }
+     }
+   });
+   ```
+3. Arm the layer (panel button, or add `"aiModeration"` to `autoStart`)
+
+Multiple keys are rotated automatically, and any key that gets rate-limited
+is benched temporarily rather than breaking moderation. It only calls out
+to Groq for messages local detection scores as ambiguous - most messages
+never leave the process.
+
+## Everyday use, once it's running
+
+Nobody needs this guide again after setup. Server admins use:
+
+| Command | Does |
+|---|---|
+| `!gf panel` | The 5-button control panel |
+| `!gf status` | Which layers are active |
+| `!gf scan` | Checks current roles for name/permission mismatches |
+| `!gf metrics` | Performance and cache health |
+| `!gf phishing add/remove/list <domain>` | Manage the link blocklist |
+| `!gf whitelist add/remove <userId>` | Exempt a user from punitive action |
+| `!gf help` | Lists all of the above |
+
+## Going deeper
+
+- `README.md` - full feature overview
+- `docs/PROTOCOL_LAYERS.md` - how a signal becomes an action
+- `docs/CACHE_ARCHITECTURE.md` - every internal cache and its TTL
+- `docs/PERFORMANCE.md` - the bounded-concurrency queues and `!gf metrics`
+- `docs/COMMANDS.md` - full command/button reference
+- `CHANGELOG.md` - version history
+- `config.js` - every tunable threshold, all in one file

package/LICENSE

@@ -0,0 +1,56 @@
+GlassFrame Protocol - Limited Use License
+Copyright (c) 2026 GlassFrame Protocol
+
+This is a custom, non-open-source license. It is not MIT, Apache, GPL, or
+any OSI-approved license, and it is not legal advice - it is a starting
+template. Have an actual lawyer review it before relying on it for
+anything commercially significant; enforceability varies by jurisdiction,
+and only a licensed attorney can tell you how well specific wording holds
+up where you and your users live.
+
+1. GRANT OF USE
+   Permission is granted, free of charge, to any person obtaining a copy of
+   this software (the "Software") to install and use it, unmodified, as a
+   dependency inside their own Discord bot project - personal or
+   commercial - subject to the conditions below.
+
+2. RESTRICTIONS
+   Without prior written permission from the copyright holder, you may NOT:
+   a. Copy, extract, or redistribute the Software's source code on its own
+      (as opposed to using it as an installed dependency of your project).
+   b. Modify the Software and distribute or publish the modified version,
+      under this name or another.
+   c. Republish, mirror, or re-upload the Software (or a renamed/modified
+      copy of it) to npm or any other package registry.
+   d. Reverse-engineer, decompile, or disassemble the Software beyond what
+      your local law makes non-waivable.
+   e. Remove or alter this license, the copyright notice, or any
+      attribution notices contained in the Software.
+   f. Resell the Software itself as a standalone product (using it as a
+      component inside a bot you sell or host as a service is permitted;
+      selling the library itself, or a copy/fork of it, is not).
+
+3. ATTRIBUTION
+   Any bot or product that uses this Software should credit "GlassFrame
+   Protocol" somewhere reasonably discoverable (a credits command, a
+   footer, a README line) unless you have separate written permission to
+   omit it.
+
+4. NO WARRANTY
+   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 ARISING FROM THE
+   SOFTWARE OR ITS USE, INCLUDING ANY ACTION TAKEN BY THE SOFTWARE AGAINST
+   A DISCORD SERVER OR ITS MEMBERS (bans, kicks, timeouts, role changes,
+   webhook deletions, or any other moderation action).
+
+5. TERMINATION
+   This license terminates automatically for anyone who violates Section 2;
+   they must stop using the Software and destroy any copies in their
+   possession.
+
+To ask for permission beyond what's granted here (bulk redistribution,
+white-labeling, a different license for a specific use case), contact the
+copyright holder directly.

package/README.md

@@ -0,0 +1,145 @@
+# GlassFrame Protocol
+
+A layered, self-contained security engine for discord.js v14 bots. Four
+independently-toggleable layers - AntiRaid, AntiNuke, Basic Security, and
+Groq-powered AI Moderation - share one threat-scoring and punishment
+pipeline instead of each reacting on its own, so the same member never gets
+hit by four different modules for one incident, and a single soft flag
+never turns into an auto-ban.
+
+No slash commands - prefix commands only. No legacy `EmbedBuilder` - every
+log message renders through Discord's Components V2 system. No emoji
+anywhere in code or output.
+
+## Install
+
+Copy the `glassframe-protocol` folder into your bot project, then:
+
+```
+npm install
+```
+
+Requires `discord.js` v14.16+ (Components V2 support and the
+`guildAuditLogEntryCreate` event) and Node.js 18+ (global `fetch`, used only
+by the optional AI layer).
+
+## Required intents
+
+```js
+const { Client, GatewayIntentBits } = require("discord.js");
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMembers,
+    GatewayIntentBits.GuildMessages,
+    GatewayIntentBits.MessageContent,
+    GatewayIntentBits.GuildModeration
+  ]
+});
+```
+
+## Required bot permissions
+
+Manage Roles, Kick Members, Ban Members, Manage Channels, Manage Webhooks,
+View Audit Log, Moderate Members (timeout), Manage Messages. GlassFrame's
+own role must sit above any role/member it needs to act on -
+`RoleAnalyzer` checks this before every action instead of attempting and
+failing.
+
+## Usage
+
+```js
+const GlassFrame = require("glassframe-protocol");
+
+client.once("ready", () => {
+  const frame = new GlassFrame(client, {
+    getLogChannel: async (guild) =>
+      guild.channels.cache.find((c) => c.name === "security-logs") ?? null,
+    whitelist: ["123456789012345678"],
+    autoStart: ["basicSecurity"], // layers not listed here start OFF until armed from the panel
+    config: {
+      antiRaid: { joinThreshold: 8 },
+      aiModeration: { apiKeys: [process.env.GROQ_KEY_1, process.env.GROQ_KEY_2].filter(Boolean) }
+    }
+  });
+
+  frame.on("warning", (w) => console.warn(`[GlassFrame:${w.layer}]`, w.message));
+});
+
+client.login(process.env.BOT_TOKEN);
+```
+
+Send `!gf panel` in any channel (Manage Server permission required) to get
+the 5-button control panel and arm layers from there instead of in code.
+
+## The four layers
+
+- **Basic Security** - spam rate, duplicate flood, mention spam, local NLP
+  scam/phishing scoring, and link checks via `PhishingDatabase` (a
+  server-editable blocklist plus raw-IP/punycode/brand-look-alike/shortener
+  heuristics - `!gf phishing add/remove/list`).
+- **AntiRaid** - join-velocity lockdown with automatic verification-level
+  raise/restore, a composite alt-account score (account age, username
+  entropy, missing avatar), and creation-time cluster correlation that
+  catches a raid trickling in too slowly to trip the rate counter.
+- **AntiNuke** - audit-log burst detection across channels, roles, bans,
+  kicks, webhooks, emoji, and stickers per executor; a dangerous
+  permission-grant watchdog (catches a role quietly gaining Administrator
+  the moment it happens, with optional auto-revert); a server-identity
+  watchdog (name/icon/vanity URL changes); an invite-abuse watchdog
+  (unrestricted invites from non-staff); and webhook-flood containment
+  (deletes an abusive webhook and traces it back to its creator, since
+  webhook messages carry no guild member for other layers to see).
+- **AI Moderation** (optional, off by default) - Groq-powered second opinion
+  for messages the local NLP scores as "gray zone": not clean, not clearly
+  over threshold. Supports a pool of API keys with automatic per-key
+  cooldown on rate limits. See `config.aiModeration` and
+  `docs/CACHE_ARCHITECTURE.md` for how verdicts get cached and keys rotated.
+
+Every layer starts disabled. Nothing runs until you list it in
+`autoStart`, call `frame.enableLayer(name)`, or arm it from the control
+panel.
+
+## Performance under load
+
+Every Discord mutation `PunishmentEngine` performs and every outbound Groq
+request go through a bounded-concurrency queue (`frame.actionQueue` /
+`frame.aiQueue`) instead of firing unbounded, so a burst can't trip a rate
+limit by hammering it all at once. `frame.getMetrics()` / `!gf metrics`
+gives you queue depth, cache stats, and average latency in one snapshot.
+Full write-up in `docs/PERFORMANCE.md`.
+
+## How punishment works
+
+Layers never ban/kick/timeout directly - they report a signal
+(`{ layer, weight, reason }`) to a shared `ThreatEngine`, which keeps one
+decaying risk score per member. `PunishmentEngine` turns that score into an
+action, but only after `RoleAnalyzer` confirms the bot can actually act on
+the member and checks their real trust level (a genuine admin is flagged
+for human review, never auto-banned), and only if there isn't already an
+open case for that member from a moment ago. Full write-up in
+`docs/PROTOCOL_LAYERS.md`.
+
+## Docs
+
+- `GETTING_STARTED.md` - adding GlassFrame to a bot you already have running.
+- `docs/PROTOCOL_LAYERS.md` - full architecture: containment vs. punishment,
+  how a signal becomes an action, how to add a fifth layer.
+- `docs/CACHE_ARCHITECTURE.md` - every cache in the library, its key shape,
+  its TTL, and how to turn on cache-level debug logging.
+- `docs/PERFORMANCE.md` - the bounded-concurrency queues and internal
+  metrics collector, and what `!gf metrics` shows.
+- `docs/COMMANDS.md` - the full prefix command reference and the control
+  panel's five buttons.
+- `docs/PUBLISHING.md` - publishing this package to npm, and what actually
+  gets uploaded vs. stays local.
+- `CHANGELOG.md` - version history.
+
+## Tuning
+
+Every threshold lives in `config.js`. Start with the defaults, watch the
+security log channel for a week, and adjust - a very active server needs
+higher spam/mention thresholds than a quiet one. `frame.threatEngine` and
+`frame.punishmentEngine` are both plain properties on the returned instance
+if you want to inspect scores or open cases at runtime.

package/dist/config.js

@@ -0,0 +1,138 @@
+"use strict";
+
+module.exports = {
+  // Prefix for all commands. This library never registers slash commands.
+  prefix: "!gf ",
+
+  // Documentation only - the actual channel resolution always goes through
+  // the required options.getLogChannel(guild) function you provide.
+  logChannelName: "security-logs",
+
+  roleAnalysis: {
+    // Role-name fragments (lowercased, substring match) that imply real authority.
+    protectedNames: [
+      "owner", "admin", "administrator", "moderator", "mod",
+      "staff", "discord staff", "security"
+    ],
+    // Permission names (PermissionsBitField.Flags keys) treated as "dangerous"
+    // when granted to a role - watched by AntiNuke's grant watchdog.
+    dangerousPermissions: [
+      "Administrator", "ManageGuild", "ManageRoles", "ManageWebhooks",
+      "BanMembers", "ManageChannels"
+    ],
+    // Permission names that mark a member as genuinely trusted staff.
+    trustPermissions: ["Administrator", "ManageGuild", "ManageRoles", "BanMembers", "KickMembers"],
+    // A role younger than this that already holds a dangerous permission is extra suspicious.
+    newRoleGraceMs: 1000 * 60 * 10
+  },
+
+  threatEngine: {
+    // Score halves every this-many ms of inactivity - stale flags fade instead of lingering forever.
+    decayHalfLifeMs: 1000 * 60 * 30,
+    tiers: { low: 20, medium: 45, high: 70, critical: 90 }
+  },
+
+  punishment: {
+    // While a case is open for a member, new signals merge into it instead of re-punishing/re-logging.
+    caseCooldownMs: 1000 * 30,
+    ladder: { low: "log", medium: "timeout", high: "kick", critical: "ban" },
+    timeoutDurationMs: 1000 * 60 * 10,
+    // Action used instead of kick/ban when the target holds a real trusted/protected role.
+    protectedTrustAction: "quarantine"
+  },
+
+  basicSecurity: {
+    spam: { windowMs: 6000, messageThreshold: 6, duplicateThreshold: 4 },
+    mentionSpam: { maxMentionsPerMessage: 8 },
+    nlp: { scamScoreThreshold: 0.62, phishingScoreThreshold: 0.55 },
+    // Seed domains for PhishingDatabase (src/security/PhishingDatabase.js).
+    // Empty by default - populate with what you actually see via
+    // `!gf phishing add <domain>` rather than shipping unverified blocklists.
+    linkGuard: { seedDomains: [] }
+  },
+
+  antiRaid: {
+    joinWindowMs: 10000,
+    joinThreshold: 6,
+    minAccountAgeMs: 1000 * 60 * 60 * 24 * 3,
+    usernameEntropyFloor: 2.6,
+    usernameEntropyCeiling: 4.6,
+    lockdownDurationMs: 1000 * 60 * 10,
+    altScoreThreshold: 55,
+    // Behavioral correlation: catches a raid that trickles in slowly enough
+    // to dodge the join-rate counter above, by noticing that several
+    // "unrelated" new joiners were actually all created within the same
+    // narrow window - a classic sign of a bulk-registered account farm.
+    cluster: {
+      windowMs: 1000 * 60 * 5,
+      minClusterSize: 4,
+      creationToleranceMs: 1000 * 60 * 2
+    }
+  },
+
+  antiNuke: {
+    windowMs: 15000,
+    thresholds: {
+      channelDelete: 3, channelCreate: 5, roleDelete: 3, roleCreate: 5,
+      memberBanAdd: 4, memberKick: 5, webhookCreate: 3, botAdd: 1, guildUpdate: 3,
+      emojiDelete: 5, emojiCreate: 8, stickerDelete: 3, stickerCreate: 5
+    },
+    watchDangerousGrants: true,
+    autoRevertDangerousGrants: false,
+    watchVanityChanges: true,
+    // A brand-new invite with no expiry and no use limit, created by anyone
+    // other than the owner, is worth a look the moment it's created.
+    watchInviteAbuse: true,
+    // A webhook that starts pushing a burst of messages within minutes of
+    // being created is a classic "nuke via webhook" pattern - this catches
+    // it even though the messages themselves look like normal messageCreate
+    // events. The offending webhook is deleted as immediate containment.
+    webhookAbuse: {
+      enabled: true,
+      messageThreshold: 8,
+      windowMs: 8000,
+      // How long after creation a webhook is still considered "recent" enough to watch.
+      watchPeriodMs: 1000 * 60 * 5
+    },
+    // Forensic role/channel snapshot retention, taken the moment a threshold trips.
+    snapshotTtlMs: 1000 * 60 * 60
+  },
+
+  aiModeration: {
+    // Empty by default - the layer stays idle until you supply at least one key.
+    apiKeys: [],
+    model: "llama-3.3-70b-versatile",
+    endpoint: "https://api.groq.com/openai/v1/chat/completions",
+    timeoutMs: 6000,
+    cacheTtlMs: 1000 * 60 * 5,
+    // A conservative self-imposed budget shared across the whole key pool, not Groq's own rate limit.
+    maxCallsPerMinute: 20,
+    // Messages whose local NLP score falls in this band get a second, AI-backed opinion.
+    grayZone: { min: 0.30, max: 0.62 }
+  },
+
+  logging: {
+    // Near-duplicate log events inside this window merge into one message with a running count.
+    aggregationWindowMs: 15000,
+    // Minimum time between sends to the same guild's log channel.
+    minSendIntervalMs: 1200
+  },
+
+  // Bounded-concurrency controls (src/core/EventQueue.js) so a burst - a raid,
+  // a nuke attempt, a wave of gray-zone messages - queues smoothly instead of
+  // firing every Discord/Groq call at once and tripping a rate limit right
+  // when speed matters most. See docs/PERFORMANCE.md.
+  performance: {
+    actionConcurrency: 4, // simultaneous ban/kick/timeout/quarantine calls
+    aiConcurrency: 3, // simultaneous outbound Groq requests
+    // Per-user, per-guild floor between prefix commands, so a doubled
+    // keypress can't spawn two control panels or send a command twice.
+    commandCooldownMs: 3000
+  },
+
+  cache: {
+    // Default for GlassFrame's debug flag - logs every cache SET/HIT/MISS/EXPIRE to the console.
+    // See docs/CACHE_ARCHITECTURE.md. Overridden by the `debug` constructor option if provided.
+    debug: false
+  }
+};