glassframe-protocol 1.2.1 → 2.1.0

package/CHANGELOG.md

@@ -14,6 +14,190 @@ lives in `src/core/VersionInfo.js` (`VersionInfo.info()` /
 `VersionInfo.banner()`), so code can read the current version without
 parsing this file.
 
+## [2.1.0] - 2026-08-01
+
+Additive - nothing from 2.0.0's API changes. New detections, a plugin
+system, per-guild customization, and an owner-only cross-server dashboard.
+
+### Added - security detections
+
+- **Dangerous role grants to a member.** The existing permission-grant
+  watchdog only caught a role's own permissions changing (`RoleUpdate`).
+  It missed the other half: someone with `ManageRoles` handing an
+  already-dangerous role directly to a member (`MemberRoleUpdate`) without
+  ever touching the role's definition. Now watched, gated the same way -
+  only flagged when the executor isn't recognized trusted staff.
+- **Channel permission-overwrite abuse.** A nuke doesn't have to delete
+  anything - locking @everyone out of a public channel, or opening a
+  private one up to @everyone, does equivalent damage through permission
+  overwrites. Only @everyone's own overwrite is watched; a role- or
+  member-specific overwrite change is routine administration and ignored.
+- **A dedicated @everyone/@here guard** in Basic Security, weighted well
+  above regular mention spam (a single mass ping reaches every member at
+  once) and skipped for recognized trusted staff, so a real admin's
+  announcement isn't flagged.
+- **Raid-recruitment language is now actually used.** `raidCallout` scoring
+  existed in the NLP engine already but was never wired into
+  `BasicSecurityLayer`'s real decision logic - fixed. Also added a specific
+  invite-link + raid-language combo check (the "join this server to raid
+  with us" pattern), and expanded the raid lexicon to catch common word
+  forms ("raiding", "raids") that the bare-verb-only version missed.
+
+### Added - extensibility
+
+- **`frame.registerLayer(name, layerInstance)`** - add a custom security
+  layer to the same shared pipeline the built-in four use. Must extend
+  `core/Layer`; gets per-guild enable/disable, state persistence, and
+  `!gf status`/`!gf metrics` visibility for free, since those now iterate
+  `frame.layers` dynamically instead of a fixed list. Does not get an
+  automatic button on the 5-button panel (that stays fixed at 5).
+- **`frame.registerAction(name, handler)`** - add a punishment action
+  beyond ban/kick/timeout/quarantine, referenceable from
+  `config.punishment.ladder`. Runs through the same action queue as the
+  built-in ones.
+- **Per-guild custom prefix** - `!gf prefix set <newPrefix>` /
+  `!gf prefix reset`. `config.prefix` always still works everywhere as a
+  fallback; an overlapping custom/default pair resolves by trying the
+  longer one first.
+- **Per-layer log channel routing** - `getLogChannel(guild, layerName)` now
+  receives the reporting layer's name as an optional second argument, so
+  different layers can route to different channels. Fully backward
+  compatible - a `getLogChannel` that only takes one parameter keeps
+  working unchanged.
+
+### Added - the owner-only engine dashboard
+
+- **`!gf engine`** - a bot-wide, cross-server dashboard: layer adoption
+  across every server, the busiest servers by event volume, AI usage
+  (Groq key pool/cooldowns/call volume), queue and cache health, and a live
+  feed of the last several things logged anywhere. See `docs/ENGINE.md`.
+  Deliberately not listed in `!gf help` - a per-server admin shouldn't know
+  it exists, let alone see data about other servers.
+- **Its own permission model**, separate from every other command:
+  `options.owners` (a list of Discord user IDs) is required regardless, and
+  an optional `config.engine.password` is a second factor on the initial
+  command only - page-navigation clicks re-check `isOwner()` but don't
+  re-prompt for the password. Wrong guesses count toward a lockout
+  (`config.engine.maxAttempts`, `config.engine.lockoutMs`), and the command
+  message is deleted immediately either way so the password doesn't sit
+  visible in channel history.
+- **5 pages** (Overview, Servers, AI, Performance, Activity Log), navigated
+  with a row of tab buttons - this is a second interactive surface,
+  entirely separate from the 5-button panel and the metrics command's own
+  button.
+- `frame.getEngineReport()` - the raw data behind the dashboard, if you
+  want it for your own tooling instead of the rendered message.
+- `PerformanceMonitor.recordEvent(name, guildId)` now optionally tracks
+  per-guild activity (`topGuildsByActivity()`) alongside the existing
+  by-name counters.
+- `SmartLogger` keeps a bounded in-memory ring buffer (`getRecentLogs()`,
+  last 30) of recent events across every guild, powering the Activity Log
+  page.
+
+### Changed
+
+- `!gf help` reorganized into sections (Getting started / Security tools /
+  Diagnostics / Customization) with a one-line explanation of what each
+  command actually does, instead of a flat list of syntax.
+- `!gf status` now explains what each layer actually watches for, not just
+  whether it's on, and iterates every registered layer (including custom
+  ones) instead of a fixed four.
+- `!gf metrics` and the global engine view now carry a short plain-language
+  explanation under every number - what it means, and whether it's
+  generally worth a closer look.
+
+### Fixed
+
+- `raidCallout` NLP scoring was computed but never checked anywhere.
+- The default `raidCalloutThreshold` (0.5) was miscalibrated against how
+  the scoring function actually behaves - lowered to 0.3, validated against
+  both a real raid-recruitment example and known-innocuous messages with
+  margin on both sides.
+
+## [2.0.0] - 2026-08-01
+
+**Breaking.** Layer activation and the whitelist were accidentally global
+across every server the bot is in - this release makes them per-guild, the
+way they were always supposed to work, and adds real state persistence.
+
+### Fixed (breaking)
+
+- **Layer on/off state is now per-guild.** Previously, `Layer.enabled` was
+  one shared boolean - arming AntiRaid from one server's control panel
+  silently armed it for *every* server the bot serves. `getStatus(guildId)`
+  accepted a `guildId` but never actually used it. Both are now genuinely
+  per-guild: `Layer.enabledGuilds` is a `Set<guildId>`, and
+  `frame.enableLayer(name, guildId)` / `frame.disableLayer(name, guildId)`
+  now **require** a `guildId` argument. Calling either without one throws,
+  rather than silently doing the wrong thing.
+- **The whitelist is now per-guild.** `frame.whitelist` was a single global
+  `Set<userId>` - whitelisting someone in one server exempted them
+  everywhere. It's now a `Map<guildId, Set<userId>>`; use the new
+  `frame.addToWhitelist(guildId, userId)`,
+  `frame.removeFromWhitelist(guildId, userId)`, and
+  `frame.isWhitelisted(guildId, userId)` instead of touching the Map
+  directly. The constructor's `whitelist: [...]` option still works exactly
+  as before from the outside - it now seeds that list into every guild
+  (present and future) the first time GlassFrame sees it, rather than
+  applying globally.
+- **State now actually persists.** `stateStore` was constructed and then
+  never read from or written to anywhere. Every layer toggle and whitelist
+  change is now saved per-guild, and restored at startup (and automatically
+  for any new guild the bot joins) - see `docs/STATE.md`.
+- Fixed a related bug in `BasicSecurityLayer`: its spam-rate buffer was
+  keyed by `userId` alone, so the same user active in two different
+  servers could incorrectly share one rate-limit window. Now keyed by
+  `guildId:userId`.
+
+### Migrating from 1.x
+
+**If you only use the built-in control panel and `!gf` commands, nothing in
+your bot's code needs to change** - update the package and you're done; the
+panel and commands already operate within a specific server, they just
+didn't respect that internally before now.
+
+**If your own code calls these directly, update the call sites:**
+
+| 1.x | 2.0.0 |
+|---|---|
+| `frame.enableLayer(name)` | `frame.enableLayer(name, guildId)` |
+| `frame.disableLayer(name)` | `frame.disableLayer(name, guildId)` |
+| `frame.whitelist.add(userId)` | `frame.addToWhitelist(guildId, userId)` |
+| `frame.whitelist.delete(userId)` | `frame.removeFromWhitelist(guildId, userId)` |
+| `frame.whitelist.has(userId)` | `frame.isWhitelisted(guildId, userId)` |
+| `layer.enabled` | `layer.isEnabled(guildId)` |
+
+`options.autoStart` in the constructor is unchanged - still a plain array
+of layer names - but now correctly applies per-guild (to every guild the
+bot is already in, and automatically to any new one it joins) instead of
+turning a layer on everywhere at once.
+
+### Added
+
+- `frame.ready` - a Promise that resolves once every guild the bot was
+  already in at construction time has finished restoring its saved state.
+  State restoration is async (a real `stateStore` may hit disk/a database),
+  so this exists for anyone who wants an explicit guarantee rather than
+  relying on the fact that, in practice, it resolves faster than any
+  Discord event could arrive.
+- `frame.getGuildMetrics(guildId)` - one server's layer status, whitelist
+  size, open-case count, and flagged-member count.
+- `!gf metrics` now shows **this server's** numbers by default instead of
+  bot-wide totals, with one button on the message to switch to the global
+  (all-servers) view and back. This is a second button, separate from the
+  5-button panel - the panel is still exactly 5 buttons; the metrics
+  command now has 1 of its own.
+- `ProtocolCache.countByPrefix(prefix)` - powers the per-guild counts above
+  by counting non-expired `guildId:userId`-keyed entries for one guild.
+- `docs/STATE.md` - the per-guild state and persistence model in full.
+
+## [1.2.1] - 2026-07-31
+
+### Added
+
+- `homepage` and `discord` fields in `package.json` linking to the docs site
+  and the support server.
+
 ## [1.2.0] - 2026-07-31
 
 Packaging and licensing changes to make this publishable to npm. No

package/GETTING_STARTED.md

@@ -79,9 +79,10 @@ toggle gets reported there through Components V2 messages.
 
 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.
+- **Code**: list layer names in `autoStart` (see Step 2) - applies to every
+  server by default - or call
+  `frame.enableLayer("antiNuke", guildId)` / `frame.disableLayer("antiNuke", guildId)`
+  for one specific server 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
@@ -119,13 +120,31 @@ Nobody needs this guide again after setup. Server admins use:
 | `!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 whitelist add/remove <userId>` | Exempt a user from punitive action in this server |
 | `!gf help` | Lists all of the above |
 
+## Step 6 (optional) - Your own bot-wide dashboard
+
+If you run the bot yourself, `!gf engine` gives you a cross-server view
+(busiest server, AI usage, a live activity feed) that regular server admins
+can't see:
+
+```js
+const frame = new GlassFrame(client, {
+  getLogChannel: /* ... */,
+  owners: ["your-discord-user-id"]
+});
+```
+
+See `docs/ENGINE.md` for the optional password/lockout system and what
+each of its 5 pages shows.
+
 ## Going deeper
 
 - `README.md` - full feature overview
 - `docs/PROTOCOL_LAYERS.md` - how a signal becomes an action
+- `docs/STATE.md` - per-server layer/whitelist state and persistence
+- `docs/ENGINE.md` - the owner-only bot-wide dashboard
 - `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

package/README.md

@@ -7,18 +7,23 @@ 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.
 
+Everything is per-server: one bot process can run GlassFrame across many
+Discord servers, each with its own independent set of active layers and its
+own whitelist, persisted across restarts. See `docs/STATE.md`.
+
 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
+npm install glassframe-protocol
 ```
 
+Or copy the `glassframe-protocol` folder directly into your bot project and
+`npm install` inside it - either works the same way.
+
 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).
@@ -56,8 +61,8 @@ 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
+    whitelist: ["123456789012345678"], // trusted everywhere, seeded into every guild on first run
+    autoStart: ["basicSecurity"], // starting layers for every guild - not a global on/off
     config: {
       antiRaid: { joinThreshold: 8 },
       aiModeration: { apiKeys: [process.env.GROQ_KEY_1, process.env.GROQ_KEY_2].filter(Boolean) }
@@ -75,8 +80,10 @@ 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
+- **Basic Security** - spam rate, duplicate flood, mention spam, a
+  dedicated trust-aware @everyone/@here guard, local NLP scam/phishing/
+  raid-recruitment scoring (including a specific invite-link +
+  raid-language combo check), 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
@@ -85,30 +92,36 @@ the 5-button control panel and arm layers from there instead of in code.
   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).
+  permission-grant watchdog covering both a role's own permissions
+  changing *and* a member being quietly handed an already-dangerous role
+  (with optional auto-revert); a channel permission-overwrite watchdog
+  (catches @everyone getting locked out of, or let into, a channel without
+  anything being deleted); 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.
+Every layer starts disabled, per guild. Nothing runs until you list it in
+`autoStart`, call `frame.enableLayer(name, guildId)`, or arm it from the
+control panel. Add your own layer alongside these four with
+`frame.registerLayer()` - see "Extending it" below.
 
 ## 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`.
+limit by hammering it all at once. `!gf metrics` shows this server's numbers
+by default (open cases, flagged members, active layers), with a button on
+the message to switch to bot-wide totals across every server
+(`frame.getMetrics()` / `frame.getGuildMetrics(guildId)`). Full write-up in
+`docs/PERFORMANCE.md`.
 
 ## How punishment works
 
@@ -121,15 +134,37 @@ 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`.
 
+## Extending it
+
+- **`frame.registerLayer(name, layerInstance)`** - add your own security
+  layer to the same pipeline the built-in four use (per-guild enable/state/
+  persistence come free from extending `core/Layer`). Doesn't get a button
+  on the panel automatically - the panel stays fixed at exactly 5.
+- **`frame.registerAction(name, handler)`** - add a custom punishment
+  action beyond ban/kick/timeout/quarantine, referenceable from
+  `config.punishment.ladder`.
+- **`!gf prefix set <newPrefix>`** - each server can run its own prefix;
+  `config.prefix` always still works everywhere as a fallback.
+- **`getLogChannel(guild, layerName)`** - route different layers to
+  different channels, if you want; the second parameter is optional and
+  backward compatible.
+- **`!gf engine`** - an owner-only, bot-wide dashboard (busiest server, AI
+  usage, live cross-server activity feed), gated separately from every
+  other command and not listed in `!gf help`. See `docs/ENGINE.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.
+  how a signal becomes an action, `registerLayer`/`registerAction`.
+- `docs/STATE.md` - per-guild layer/whitelist state and how persistence
+  across restarts works.
 - `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/ENGINE.md` - the owner-only bot-wide dashboard: the password/lockout
+  system and what each of its 5 pages 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

package/dist/config.js

@@ -44,7 +44,7 @@ module.exports = {
   basicSecurity: {
     spam: { windowMs: 6000, messageThreshold: 6, duplicateThreshold: 4 },
     mentionSpam: { maxMentionsPerMessage: 8 },
-    nlp: { scamScoreThreshold: 0.62, phishingScoreThreshold: 0.55 },
+    nlp: { scamScoreThreshold: 0.62, phishingScoreThreshold: 0.55, raidCalloutThreshold: 0.3 },
     // 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.
@@ -83,6 +83,10 @@ module.exports = {
     // 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,
+    // Watches @everyone's channel permission overwrites specifically - a
+    // channel getting locked out for everyone, or a private channel getting
+    // opened to everyone, is a nuke technique that doesn't delete anything.
+    watchOverwriteAbuse: 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
@@ -134,5 +138,20 @@ module.exports = {
     // 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
+  },
+
+  // The owner-only `!gf engine` dashboard - see docs/ENGINE.md. Being an
+  // owner (options.owners) is required no matter what; a password is an
+  // optional second factor on top of that for the initial command only -
+  // page-navigation button clicks are still gated by isOwner() but don't
+  // re-prompt for the password.
+  engine: {
+    // Set via an environment variable in your own bot, e.g.
+    // process.env.GLASSFRAME_ENGINE_PASSWORD - never hardcode a real
+    // password into a committed config.js. Leave null to skip the second
+    // factor and rely on the owners list alone.
+    password: null,
+    maxAttempts: 3,
+    lockoutMs: 1000 * 60 * 10
   }
 };