glassframe-protocol 1.2.1 → 2.1.0

package/dist/src/GlassFrame.js

@@ -23,13 +23,19 @@ const AntiNukeLayer = require("./layers/AntiNukeLayer");
 const AIModerationLayer = require("./layers/AIModerationLayer");
 
 const PrefixRouter = require("./commands/PrefixRouter");
-const { buildPanel } = require("./ui/ControlPanel");
+const { buildPanel, buildMetricsMessage, buildEnginePage } = require("./ui/ControlPanel");
+
+const LAYER_NAMES = ["basicSecurity", "antiRaid", "antiNuke", "aiModeration"];
 
 /**
  * GlassFrame Protocol - a layered, self-contained Discord security engine.
  * One instance manages every layer, the shared threat/punishment pipeline,
  * logging, the prefix command router, and the 5-button control panel for a
  * discord.js Client. See docs/PROTOCOL_LAYERS.md for the architecture.
+ *
+ * Everything is per-guild: which layers are active, and the whitelist, are
+ * tracked independently for every server the bot is in, and persisted
+ * through `stateStore` so they survive a restart. See docs/STATE.md.
  */
 class GlassFrame extends EventEmitter {
   constructor(client, options = {}) {
@@ -41,10 +47,22 @@ class GlassFrame extends EventEmitter {
 
     this.client = client;
     this.config = mergeConfig(defaultConfig, options.config || {});
-    this.whitelist = new Set(options.whitelist || []);
     this.stateStore = options.stateStore || new MemoryStateStore();
+    this.autoStart = options.autoStart || [];
+    // Seed list of user IDs treated as trusted in every guild the bot is
+    // in or joins - only applied the first time we see a guild (same rule
+    // as autoStart), never overriding a guild's own saved whitelist.
+    this.defaultWhitelist = new Set(options.whitelist || []);
+    this.whitelist = new Map(); // guildId -> Set<userId>
+    this.customActions = new Map(); // actionName -> async (member, record) => void, for registerAction()
+    this.guildPrefixes = new Map(); // guildId -> custom prefix, for setPrefix()
     this.panelMessages = new Map(); // messageId -> guildId
     this.debug = Boolean(options.debug ?? this.config.cache.debug);
+    // Bot-owner user IDs - separate from per-guild Manage Server admins,
+    // since cross-server data (busiest server, all-guild activity) isn't
+    // something a random single server's admin should see about others.
+    this.owners = new Set(options.owners || []);
+    this.engineAttempts = new Map(); // userId -> { count, lockedUntil }
 
     this.threatEngine = new ThreatEngine(this.config, { debug: this.debug });
     this.roleAnalyzer = new RoleAnalyzer(this.config);
@@ -66,19 +84,23 @@ class GlassFrame extends EventEmitter {
       roleAnalyzer: this.roleAnalyzer,
       logger: this.logger,
       whitelist: this.whitelist,
+      customActions: this.customActions,
       queue: this.actionQueue,
       performance: this.performance,
       debug: this.debug
     });
 
-    // All four layers start disabled - nothing runs until armed via
-    // options.autoStart, the control panel, or enableLayer().
+    // All four layers start disabled per guild - nothing runs until armed
+    // via options.autoStart, the control panel, or enableLayer(name, guildId).
     this.layers = {
       basicSecurity: new BasicSecurityLayer(this),
       antiRaid: new AntiRaidLayer(this),
       antiNuke: new AntiNukeLayer(this),
       aiModeration: new AIModerationLayer(this)
     };
+    // Event listeners attach exactly once, ever - per-guild on/off is a
+    // gate inside each handler, not an attach/detach cycle. See core/Layer.js.
+    for (const layer of Object.values(this.layers)) layer.attach();
 
     this.prefixRouter = new PrefixRouter(this);
     this.prefixRouter.attach();
@@ -86,9 +108,21 @@ class GlassFrame extends EventEmitter {
 
     if (this.debug) console.log(VersionInfo.banner());
 
-    for (const name of options.autoStart || []) {
-      if (this.layers[name]) this.layers[name].enable();
-    }
+    // Restore saved state (or apply autoStart/whitelist defaults) for every
+    // guild the bot is already in. This is async (stateStore.get() may be a
+    // real file/DB read), so `ready` lets callers that care about the exact
+    // moment restoration finishes await it explicitly - in practice a
+    // Discord message can't arrive faster than this resolves, so most code
+    // never needs to. Any guild the bot joins *after* this (guildCreate)
+    // restores independently and isn't part of `ready`.
+    const initialRestores = [...this.client.guilds.cache.values()].map((guild) =>
+      this._restoreGuildState(guild.id).catch((err) => this.emit("warning", { layer: "core", message: err.message }))
+    );
+    this.ready = Promise.all(initialRestores).then(() => undefined);
+
+    this.client.on("guildCreate", (guild) => {
+      this._restoreGuildState(guild.id).catch((err) => this.emit("warning", { layer: "core", message: err.message }));
+    });
   }
 
   isAuthorized(member) {
@@ -97,15 +131,65 @@ class GlassFrame extends EventEmitter {
     return member.permissions.has(PermissionsBitField.Flags.ManageGuild);
   }
 
+  /** For the owner-only !gf engine dashboard - separate from per-guild isAuthorized(). */
+  isOwner(userId) {
+    return this.owners.has(userId);
+  }
+
+  /**
+   * Second factor on top of isOwner(), only for the initial `!gf engine`
+   * command - not required again for page-navigation button clicks, since
+   * those are already tied to a real, already-verified Discord identity.
+   * Returns true with no config.engine.password set (owner check alone is
+   * enough). Locks a user out for engine.lockoutMs after
+   * engine.maxAttempts wrong guesses, to make brute-forcing impractical.
+   */
+  verifyEnginePassword(userId, provided) {
+    const cfg = this.config.engine;
+    if (!cfg.password) return true;
+
+    const attempt = this.engineAttempts.get(userId) || { count: 0, lockedUntil: 0 };
+    if (Date.now() < attempt.lockedUntil) return false;
+
+    if (provided === cfg.password) {
+      this.engineAttempts.delete(userId);
+      return true;
+    }
+
+    attempt.count++;
+    if (attempt.count >= cfg.maxAttempts) {
+      attempt.lockedUntil = Date.now() + cfg.lockoutMs;
+      attempt.count = 0;
+    }
+    this.engineAttempts.set(userId, attempt);
+    return false;
+  }
+
   getStatus(guildId) {
     const out = {};
     for (const [name, layer] of Object.entries(this.layers)) {
-      out[name] = layer.enabled;
+      out[name] = layer.isEnabled(guildId);
     }
     return out;
   }
 
-  /** One-call health snapshot: event throughput/latency, queue depth, and every cache's stats. */
+  isWhitelisted(guildId, userId) {
+    return this.whitelist.get(guildId)?.has(userId) ?? false;
+  }
+
+  addToWhitelist(guildId, userId) {
+    if (!this.whitelist.has(guildId)) this.whitelist.set(guildId, new Set());
+    this.whitelist.get(guildId).add(userId);
+    this._persistGuildState(guildId);
+  }
+
+  removeFromWhitelist(guildId, userId) {
+    const existed = this.whitelist.get(guildId)?.delete(userId) ?? false;
+    if (existed) this._persistGuildState(guildId);
+    return existed;
+  }
+
+  /** One-call health snapshot: event throughput/latency, queue depth, and every cache's stats. Bot-wide, across every guild. */
   getMetrics() {
     return {
       performance: this.performance.snapshot(),
@@ -121,58 +205,244 @@ class GlassFrame extends EventEmitter {
     };
   }
 
-  enableLayer(name) {
+  /** Just this guild's numbers - which layers are on, and its slice of the shared threat/case caches. */
+  getGuildMetrics(guildId) {
+    const prefix = `${guildId}:`;
+    return {
+      status: this.getStatus(guildId),
+      whitelistSize: this.whitelist.get(guildId)?.size || 0,
+      flaggedMembers: this.threatEngine.scores.countByPrefix(prefix),
+      openCases: this.punishmentEngine.cases.countByPrefix(prefix)
+    };
+  }
+
+  /**
+   * Everything about the running process at once, across every guild -
+   * what's live, what's fast/slow, which server is generating the most
+   * work, and the last several things that happened anywhere. Powers the
+   * owner-only `!gf engine` command. This is intentionally NOT reachable
+   * by a per-guild admin - see isOwner().
+   */
+  getEngineReport() {
+    const guilds = [...this.client.guilds.cache.values()];
+    const layerNames = Object.keys(this.layers);
+
+    const adoption = {};
+    for (const name of layerNames) {
+      adoption[name] = guilds.filter((g) => this.layers[name].isEnabled(g.id)).length;
+    }
+
+    const busiest = this.performance.topGuildsByActivity(5).map(([guildId, count]) => {
+      const guild = this.client.guilds.cache.get(guildId);
+      return { guildId, name: guild ? guild.name : "(left / unknown)", count };
+    });
+
+    const recentLogs = this.logger.getRecentLogs(10).map((entry) => ({
+      ...entry,
+      guildName: this.client.guilds.cache.get(entry.guildId)?.name || entry.guildName || entry.guildId
+    }));
+
+    return {
+      version: VersionInfo.info(),
+      uptimeMs: Date.now() - this.performance.startedAt,
+      guildCount: guilds.length,
+      layerAdoption: adoption,
+      metrics: this.getMetrics(),
+      busiestGuilds: busiest,
+      recentLogs,
+      ai: {
+        available: this.groqClient.available,
+        keyCount: this.groqClient.keys.length,
+        keysOnCooldown: this.groqClient.keys.filter((k) => k.cooldownUntil > Date.now()).length,
+        callsLastMinute: this.groqClient.callTimestamps.length,
+        totalCallsRecorded: this.performance.eventCounts["groqClient.classify"] || 0
+      }
+    };
+  }
+
+  enableLayer(name, guildId) {
     if (!this.layers[name]) throw new Error(`GlassFrame Protocol: unknown layer "${name}"`);
-    this.layers[name].enable();
+    if (!guildId) throw new Error("GlassFrame Protocol: enableLayer(name, guildId) requires a guildId - layers are per-guild.");
+    this.layers[name].enable(guildId);
     return this;
   }
 
-  disableLayer(name) {
+  disableLayer(name, guildId) {
     if (!this.layers[name]) throw new Error(`GlassFrame Protocol: unknown layer "${name}"`);
-    this.layers[name].disable();
+    if (!guildId) throw new Error("GlassFrame Protocol: disableLayer(name, guildId) requires a guildId - layers are per-guild.");
+    this.layers[name].disable(guildId);
+    return this;
+  }
+
+  /**
+   * Adds your own security layer to the same pipeline the built-in four
+   * use - it gets per-guild enable/disable, state persistence, and can
+   * report signals to the shared ThreatEngine/PunishmentEngine, all for
+   * free. `layerInstance` must extend `core/Layer` (see
+   * docs/PROTOCOL_LAYERS.md, "Adding a fifth layer"). Custom layers do NOT
+   * get a button on the 5-button panel automatically - toggle them via
+   * `frame.enableLayer(name, guildId)` in code, or build your own command.
+   */
+  registerLayer(name, layerInstance) {
+    if (this.layers[name]) throw new Error(`GlassFrame Protocol: a layer named "${name}" already exists`);
+    if (typeof layerInstance?.attach !== "function" || typeof layerInstance?.enable !== "function") {
+      throw new Error("GlassFrame Protocol: registerLayer() expects an instance extending core/Layer");
+    }
+    this.layers[name] = layerInstance;
+    layerInstance.attach();
+    this.emit("layerRegistered", { layer: name });
+    return this;
+  }
+
+  /**
+   * Adds a custom punishment action beyond the built-in
+   * ban/kick/timeout/quarantine, so `config.punishment.ladder` can
+   * reference it by name. `handler` is `async (member, record) => {}` -
+   * `record` is the case object (tier, trust, reasons, ...). Runs through
+   * the same bounded-concurrency action queue as the built-in actions.
+   *
+   * @example
+   * frame.registerAction("addMutedRole", async (member) => {
+   *   const role = member.guild.roles.cache.find((r) => r.name === "Muted");
+   *   if (role) await member.roles.add(role);
+   * });
+   * // config: { punishment: { ladder: { medium: "addMutedRole" } } }
+   */
+  registerAction(name, handler) {
+    if (this.customActions.has(name)) throw new Error(`GlassFrame Protocol: an action named "${name}" is already registered`);
+    if (typeof handler !== "function") throw new Error("GlassFrame Protocol: registerAction() expects a function");
+    this.customActions.set(name, handler);
     return this;
   }
 
+  /** The prefix this guild actually uses - its own custom one if set, otherwise config.prefix. */
+  getPrefix(guildId) {
+    return this.guildPrefixes.get(guildId) || this.config.prefix;
+  }
+
+  /** Sets this guild's own command prefix. config.prefix keeps working everywhere as a fallback, in case a server forgets its custom one. */
+  setPrefix(guildId, prefix) {
+    this.guildPrefixes.set(guildId, prefix);
+    this._persistGuildState(guildId);
+  }
+
+  /** Snapshots one guild's layer + whitelist + prefix state into stateStore. Fire-and-forget by design (never blocks a handler on disk/network I/O). */
+  _persistGuildState(guildId) {
+    const state = {
+      layers: this.getStatus(guildId),
+      whitelist: [...(this.whitelist.get(guildId) || [])],
+      prefix: this.guildPrefixes.get(guildId) || null
+    };
+    Promise.resolve(this.stateStore.set(guildId, state)).catch((err) =>
+      this.emit("warning", { layer: "core", message: `failed to persist state for ${guildId}: ${err.message}` })
+    );
+  }
+
+  /** Loads a guild's saved state if one exists; otherwise applies the autoStart/whitelist defaults (and persists that as the new baseline). */
+  async _restoreGuildState(guildId) {
+    const saved = await this.stateStore.get(guildId);
+
+    if (saved) {
+      for (const name of Object.keys(this.layers)) {
+        if (saved.layers?.[name]) this.layers[name].enable(guildId);
+      }
+      for (const userId of saved.whitelist || []) {
+        if (!this.whitelist.has(guildId)) this.whitelist.set(guildId, new Set());
+        this.whitelist.get(guildId).add(userId);
+      }
+      if (saved.prefix) this.guildPrefixes.set(guildId, saved.prefix);
+      return;
+    }
+
+    for (const name of this.autoStart) {
+      if (this.layers[name]) this.layers[name].enable(guildId);
+    }
+    for (const userId of this.defaultWhitelist) {
+      this.addToWhitelist(guildId, userId);
+    }
+  }
+
   _attachButtonHandler() {
     this.client.on("interactionCreate", async (interaction) => {
-      if (!interaction.isButton() || !interaction.customId.startsWith("gfp_toggle_")) return;
+      if (!interaction.isButton()) return;
 
       try {
-        if (!this.isAuthorized(interaction.member)) {
-          await interaction.reply({ content: "You need Manage Server permission to use this.", ephemeral: true });
-          return;
+        if (interaction.customId.startsWith("gfp_toggle_")) {
+          await this._handlePanelButton(interaction);
+        } else if (interaction.customId.startsWith("gfp_metrics_")) {
+          await this._handleMetricsButton(interaction);
+        } else if (interaction.customId.startsWith("gfp_engine_")) {
+          await this._handleEngineButton(interaction);
         }
+      } catch (err) {
+        this.emit("warning", { layer: "controlPanel", message: err.message });
+      }
+    });
+  }
 
-        const layerKey = interaction.customId.replace("gfp_toggle_", "");
-
-        if (layerKey === "all") {
-          const status = this.getStatus(interaction.guild.id);
-          const allOn = Object.keys(this.layers).every((l) => status[l]);
-          for (const name of Object.keys(this.layers)) {
-            if (allOn) this.disableLayer(name);
-            else this.enableLayer(name);
-          }
-        } else if (this.layers[layerKey]) {
-          if (this.layers[layerKey].enabled) this.disableLayer(layerKey);
-          else this.enableLayer(layerKey);
-        } else {
-          return;
-        }
+  async _handlePanelButton(interaction) {
+    if (!this.isAuthorized(interaction.member)) {
+      await interaction.reply({ content: "You need Manage Server permission to use this.", ephemeral: true });
+      return;
+    }
 
-        const payload = buildPanel(this, interaction.guild.id);
-        await interaction.update(payload);
+    const guildId = interaction.guild.id;
+    const layerKey = interaction.customId.replace("gfp_toggle_", "");
 
-        await this.logger.log(interaction.guild, {
-          level: "info",
-          title: "Protocol Layer Toggled",
-          description: `${interaction.user.tag} updated GlassFrame Protocol layers from the control panel.`,
-          dedupeKey: "panel:toggle"
-        });
-      } catch (err) {
-        this.emit("warning", { layer: "controlPanel", message: err.message });
+    if (layerKey === "all") {
+      const status = this.getStatus(guildId);
+      const allOn = Object.keys(this.layers).every((l) => status[l]);
+      for (const name of Object.keys(this.layers)) {
+        if (allOn) this.disableLayer(name, guildId);
+        else this.enableLayer(name, guildId);
       }
+    } else if (this.layers[layerKey]) {
+      if (this.layers[layerKey].isEnabled(guildId)) this.disableLayer(layerKey, guildId);
+      else this.enableLayer(layerKey, guildId);
+    } else {
+      return;
+    }
+
+    const payload = buildPanel(this, guildId);
+    await interaction.update(payload);
+
+    await this.logger.log(interaction.guild, {
+      level: "info",
+      title: "Protocol Layer Toggled",
+      layer: "controlPanel",
+      description: `${interaction.user.tag} updated GlassFrame Protocol layers from the control panel.`,
+      dedupeKey: "panel:toggle"
     });
   }
+
+  async _handleMetricsButton(interaction) {
+    if (!this.isAuthorized(interaction.member)) {
+      await interaction.reply({ content: "You need Manage Server permission to use this.", ephemeral: true });
+      return;
+    }
+
+    const scope = interaction.customId.replace("gfp_metrics_", ""); // "guild" or "global"
+    const payload = buildMetricsMessage(this, interaction.guild.id, scope);
+    await interaction.update(payload);
+  }
+
+  /**
+   * Page navigation on the engine dashboard. Gated by isOwner() on the
+   * clicking Discord identity - not by the password again, since a button
+   * click is already tied to a real, verified Discord session, and
+   * re-prompting for a password on every tab click would be unusable.
+   */
+  async _handleEngineButton(interaction) {
+    if (!this.isOwner(interaction.user.id)) {
+      await interaction.reply({ content: "This isn't for you.", ephemeral: true });
+      return;
+    }
+
+    const page = interaction.customId.replace("gfp_engine_", "");
+    const report = this.getEngineReport();
+    const payload = buildEnginePage(report, page);
+    await interaction.update(payload);
+  }
 }
 
 function mergeConfig(base, override) {