glassframe-protocol 1.2.1 → 2.1.0

package/docs/ENGINE.md

@@ -0,0 +1,83 @@
+# The Engine Dashboard
+
+`!gf engine` is a bot-wide, cross-server dashboard for whoever actually runs
+the bot - not a per-server admin tool. It shows things a single server's
+admin shouldn't be able to see about *other* servers (which server is
+busiest, bot-wide AI usage, a live feed of what's happening everywhere), so
+it has its own, separate permission model from every other command.
+
+It is deliberately **not** listed in `!gf help` or `docs/COMMANDS.md`'s
+in-Discord command table - a random server admin shouldn't even know it
+exists. You're expected to learn about it from this file.
+
+## Who can use it
+
+Two independent checks, not one:
+
+1. **`isOwner(userId)`** - you must be listed in `options.owners` when you
+   construct `GlassFrame`. This is required, full stop, for the command
+   itself *and* every page-navigation button click afterward.
+2. **A password** (optional) - if `config.engine.password` is set, the
+   initial `!gf engine <password>` command also needs the correct password.
+   Page-navigation button clicks after that don't re-prompt for it, since a
+   button click is already tied to a real, verified Discord identity - only
+   the text-command entry point needs the second factor.
+
+```js
+const frame = new GlassFrame(client, {
+  getLogChannel: /* ... */,
+  owners: ["your-discord-user-id"],
+  config: {
+    engine: {
+      password: process.env.GLASSFRAME_ENGINE_PASSWORD // never hardcode a real one
+    }
+  }
+});
+```
+
+Leave `config.engine.password` unset to skip the second factor and rely on
+the owners list alone.
+
+## What happens to the password
+
+Typing a password into a normal Discord message means it briefly sits in
+plain text in a channel, visible to anyone watching and to Discord's own
+message history. GlassFrame does two things about that:
+
+- The command message is **deleted immediately** after being checked,
+  whether the password was right or wrong.
+- Wrong guesses count toward a **lockout** -
+  `config.engine.maxAttempts` wrong attempts (default 3) locks that user
+  out for `config.engine.lockoutMs` (default 10 minutes), making
+  brute-forcing impractical.
+
+Use a private channel (or a channel only you can see) for this command
+regardless - deletion happens right after Discord delivers the message, not
+before anyone in the channel could have glimpsed it.
+
+## The five pages
+
+One row of tab buttons switches between them; the active tab is highlighted.
+
+| Page | Shows |
+|---|---|
+| **Overview** | Version, uptime, guild count, layer adoption across every server |
+| **Servers** | The busiest servers ranked by event volume since this process started |
+| **AI** | Groq key pool status, cooldowns, call volume, verdict cache hit rate |
+| **Performance** | Action/AI queue depth, all three cache stats, average latency per operation |
+| **Activity Log** | The last several things logged anywhere, any server, newest first |
+
+All of it comes from one call: `frame.getEngineReport()`, if you want the
+raw data instead of the rendered message (for your own dashboard, an API
+endpoint, whatever).
+
+## "Busiest" and the activity log, precisely
+
+- **Busiest** is a count of events (messages/joins/audit entries) any armed
+  layer processed for that server, tracked in memory since the process
+  started - it resets on restart and isn't a judgment about which server is
+  causing trouble, just which one has the most traffic.
+- The **activity log** is the last 30 events logged anywhere (any server,
+  any layer), kept in memory by `SmartLogger` - see
+  `docs/CACHE_ARCHITECTURE.md`. The dashboard shows the most recent 10 of
+  those.

package/docs/PROTOCOL_LAYERS.md

@@ -37,11 +37,14 @@ instead of twenty separate ones.
 | `antiNuke` | `guildAuditLogEntryCreate`, plus `messageCreate` only when webhook-abuse watching is on | reverts a dangerous permission grant, deletes an abusive webhook | destructive-action bursts per executor across channels/roles/bans/kicks/webhooks/emoji/stickers |
 | `aiModeration` | `messageCreate` (independently of `basicSecurity`) | - | AI-confirmed category + confidence for gray-zone messages |
 
-Each layer extends `src/core/Layer.js`, which handles enabling/disabling
-cleanly: `enable()` attaches the layer's listeners, `disable()` detaches
-every one of them (not just an early-return check inside the handler), so a
-disabled layer truly does no work rather than quietly skipping its own
-logic on every event.
+Each layer extends `src/core/Layer.js`. Its event listeners attach exactly
+once, ever (`attach()`), rather than on every enable/disable - Discord's
+gateway has no concept of a listener scoped to one guild, so the listener
+always fires and each handler's first real check is
+`if (!this.isEnabled(guildId)) return;`. Enabling or disabling a layer is
+per-guild: `layer.enable(guildId)` / `layer.disable(guildId)` track a
+`Set<guildId>` (`enabledGuilds`), not a single boolean - see
+`docs/STATE.md` for the full per-guild state and persistence model.
 
 `basicSecurity` and `aiModeration` both listen to `messageCreate`
 independently rather than one calling into the other - either can be
@@ -75,15 +78,57 @@ how they respond.
 ## Why AntiNuke also runs a role audit
 
 `RoleAnalyzer.scanRoles()` (role name vs. permission mismatch detection)
-runs automatically once, the moment AntiNuke is armed, and again on demand
-via `!gf scan`. It reports flags, never actions - a human decides what, if
-anything, to do about a role that looks like impersonation bait or quietly
-holds dangerous permissions.
-
-## Adding a fifth layer
-
-Extend `Layer`, implement `onEnable()` / `onDisable()`, report signals via
-`this.frame.punishmentEngine.report({ guild, member, layer, weight, reason })`,
-register the instance in `GlassFrame`'s `this.layers` map, and add a button
-in `src/ui/ControlPanel.js` if you want it on the panel. Nothing else in the
-pipeline needs to know the new layer exists.
+runs automatically once for a server the moment AntiNuke is armed *for
+that server*, and again on demand via `!gf scan`. It reports flags, never
+actions - a human decides what, if anything, to do about a role that looks
+like impersonation bait or quietly holds dangerous permissions.
+
+## Adding a layer without editing the library
+
+`frame.registerLayer(name, layerInstance)` is the supported way to do this
+now - no need to edit `GlassFrame.js`'s `this.layers` map by hand.
+`layerInstance` must extend `core/Layer`: implement `attach()` (register
+your event listener(s) once - it's called exactly once, at registration),
+gate all real work behind `this.isEnabled(guildId)`, and report signals via
+`this.frame.punishmentEngine.report({ guild, member, layer, weight, reason })`.
+Per-guild enable/disable, state persistence, and `!gf status`/`!gf metrics`
+all pick it up automatically, since they iterate `frame.layers` rather than
+a fixed list. It does **not** get a button on the 5-button panel
+automatically (that stays fixed at exactly 5) - toggle it with
+`frame.enableLayer(name, guildId)` in code, or build your own command.
+
+```js
+const Layer = require("glassframe-protocol/src/core/Layer");
+
+class LinkAgeLayer extends Layer {
+  constructor(frame) { super("linkAge", frame); }
+  attach() {
+    this._listen(this.client, "messageCreate", (message) => this._handle(message).catch(() => {}));
+  }
+  async _handle(message) {
+    if (!message.guild || message.author.bot) return;
+    if (!this.isEnabled(message.guild.id)) return;
+    // ... your detection logic, then:
+    // await this.frame.punishmentEngine.report({ guild: message.guild, member: message.member, layer: "linkAge", weight: 40, reason: "..." });
+  }
+}
+
+frame.registerLayer("linkAge", new LinkAgeLayer(frame));
+```
+
+## Custom punishment actions
+
+`frame.registerAction(name, handler)` adds an action beyond the built-in
+ban/kick/timeout/quarantine, so `config.punishment.ladder` can reference it
+by name. `handler` is `async (member, record) => {}` and runs through the
+same bounded-concurrency action queue as the built-in ones.
+
+```js
+frame.registerAction("addMutedRole", async (member) => {
+  const role = member.guild.roles.cache.find((r) => r.name === "Muted");
+  if (role) await member.roles.add(role);
+});
+```
+```js
+config: { punishment: { ladder: { medium: "addMutedRole" } } }
+```

package/docs/STATE.md

@@ -0,0 +1,101 @@
+# Per-Guild State and Persistence
+
+One GlassFrame instance can serve many Discord servers at once. Two things
+are tracked independently per server, and both survive a bot restart if you
+give GlassFrame a persistent `stateStore`:
+
+- **Which layers are on.** Server A can run AntiRaid + AntiNuke while Server
+  B runs nothing, or everything, independently. There is no such thing as
+  "GlassFrame is on" globally - only "layer X is on for guild Y."
+- **The whitelist.** Exempting a user in one server does not exempt them
+  anywhere else.
+
+Everything else that's naturally guild-scoped already was before this -
+threat scores, open cases, join-rate tracking, audit-log burst tracking are
+all keyed by `guildId` internally. The two items above are the ones that
+used to be accidentally global; see `CHANGELOG.md` for the 2.0.0 entry if
+you're upgrading from an earlier version.
+
+## How it's stored
+
+`Layer.enabledGuilds` is a `Set<guildId>` per layer (not one shared
+boolean). `GlassFrame.whitelist` is a `Map<guildId, Set<userId>>`. Both are
+read through the frame's own methods rather than touched directly:
+
+```js
+frame.enableLayer("antiRaid", guildId);
+frame.disableLayer("antiRaid", guildId);
+frame.getStatus(guildId); // { basicSecurity: true, antiRaid: false, ... }
+
+frame.addToWhitelist(guildId, userId);
+frame.removeFromWhitelist(guildId, userId);
+frame.isWhitelisted(guildId, userId);
+```
+
+## Persistence across restarts
+
+Pass a `stateStore` when constructing GlassFrame - `MemoryStateStore`
+(default, lost on restart) or `JSONFileStateStore` (a single JSON file, no
+database, ARM64/Termux-friendly):
+
+```js
+const { JSONFileStateStore } = require("glassframe-protocol");
+
+const frame = new GlassFrame(client, {
+  getLogChannel: /* ... */,
+  stateStore: new JSONFileStateStore("./glassframe-state.json"),
+  autoStart: ["basicSecurity", "antiRaid"]
+});
+```
+
+Every time a layer is toggled or the whitelist changes for a guild,
+GlassFrame writes that guild's full state (which layers are on, its
+whitelist) to the store. At startup, for every guild the bot is already in,
+and again automatically whenever the bot joins a new guild
+(`guildCreate`), GlassFrame:
+
+1. Checks the store for saved state for that guild.
+2. If found, restores exactly that - the layers that were on stay on.
+3. If nothing is saved yet (a guild GlassFrame has never seen before),
+   applies `autoStart` and the constructor's `whitelist` option (see below)
+   as that guild's starting defaults.
+
+Restoring is async (a real `stateStore` might read from disk or a
+database), so it can't finish before the constructor returns. In practice
+this resolves well before a Discord event could possibly arrive, so most
+code never needs to think about it - but if you want a guarantee, `await
+frame.ready` after construction; it resolves once every guild the bot was
+already in has been restored (guilds joined later via `guildCreate`
+restore independently and aren't part of this promise, since there's
+nothing they could race against).
+
+`autoStart` and the `whitelist` option are only ever *defaults for a
+guild's first run* - once a guild has any saved state (even "everything
+off"), neither applies to it again; the saved state is the source of truth
+from then on.
+
+## The `whitelist` constructor option
+
+```js
+new GlassFrame(client, { getLogChannel: /* ... */, whitelist: ["123456789012345678"] });
+```
+
+This seeds a starting whitelist for every guild - both the ones already in
+`client.guilds.cache` and any the bot joins later - the first time
+GlassFrame sees that guild (i.e., it never overrides a guild's own saved
+whitelist). Think of it as "these users are trusted everywhere by default";
+`frame.removeFromWhitelist(guildId, userId)` still works normally
+per-guild afterward.
+
+## Writing your own store
+
+Implement two async methods and pass an instance as `stateStore`:
+
+```js
+class MyStore {
+  async get(guildId) { /* return the saved state object, or null */ }
+  async set(guildId, state) { /* persist `state` for this guildId */ }
+}
+```
+
+`state` is `{ layers: { basicSecurity: true, antiRaid: false, ... }, whitelist: ["userId1", "userId2"] }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glassframe-protocol",
-  "version": "1.2.1",
+  "version": "2.1.0",
   "description": "A layered, self-contained Discord security engine - AntiRaid, AntiNuke, Basic Security, and optional Groq-powered AI Moderation sharing one threat-scoring and punishment pipeline. Prefix commands only, Components V2 output, no slash commands.",
   "main": "dist/index.js",
   "files": [