glassframe-protocol 1.2.0

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+const GlassFrame = require("./src/GlassFrame");
+const VersionInfo = require("./src/core/VersionInfo");
+const { MemoryStateStore, JSONFileStateStore } = require("./src/core/StateStore");
+
+// module.exports IS the class (const GlassFrame = require("glassframe-protocol")),
+// with named properties attached for anyone who prefers destructuring.
+module.exports = GlassFrame;
+module.exports.GlassFrame = GlassFrame;
+module.exports.VersionInfo = VersionInfo;
+module.exports.MemoryStateStore = MemoryStateStore;
+module.exports.JSONFileStateStore = JSONFileStateStore;

package/dist/src/GlassFrame.js

@@ -0,0 +1,195 @@
+"use strict";
+
+const EventEmitter = require("events");
+const { PermissionsBitField } = require("discord.js");
+
+const defaultConfig = require("../config");
+const VersionInfo = require("./core/VersionInfo");
+const ThreatEngine = require("./core/ThreatEngine");
+const { MemoryStateStore } = require("./core/StateStore");
+const EventQueue = require("./core/EventQueue");
+const PerformanceMonitor = require("./core/PerformanceMonitor");
+
+const RoleAnalyzer = require("./moderation/RoleAnalyzer");
+const PunishmentEngine = require("./moderation/PunishmentEngine");
+
+const SmartLogger = require("./logging/SmartLogger");
+const GroqClient = require("./ai/GroqClient");
+const PhishingDatabase = require("./security/PhishingDatabase");
+
+const BasicSecurityLayer = require("./layers/BasicSecurityLayer");
+const AntiRaidLayer = require("./layers/AntiRaidLayer");
+const AntiNukeLayer = require("./layers/AntiNukeLayer");
+const AIModerationLayer = require("./layers/AIModerationLayer");
+
+const PrefixRouter = require("./commands/PrefixRouter");
+const { buildPanel } = require("./ui/ControlPanel");
+
+/**
+ * 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.
+ */
+class GlassFrame extends EventEmitter {
+  constructor(client, options = {}) {
+    super();
+    if (!client) throw new Error("GlassFrame Protocol: a discord.js Client is required");
+    if (typeof options.getLogChannel !== "function") {
+      throw new Error("GlassFrame Protocol: options.getLogChannel(guild) is required");
+    }
+
+    this.client = client;
+    this.config = mergeConfig(defaultConfig, options.config || {});
+    this.whitelist = new Set(options.whitelist || []);
+    this.stateStore = options.stateStore || new MemoryStateStore();
+    this.panelMessages = new Map(); // messageId -> guildId
+    this.debug = Boolean(options.debug ?? this.config.cache.debug);
+
+    this.threatEngine = new ThreatEngine(this.config, { debug: this.debug });
+    this.roleAnalyzer = new RoleAnalyzer(this.config);
+    this.logger = new SmartLogger(options.getLogChannel, this.config, { debug: this.debug });
+    this.performance = new PerformanceMonitor();
+    this.phishingDatabase = new PhishingDatabase(this.config.basicSecurity.linkGuard.seedDomains);
+
+    // Every heavy outbound call (Discord mutations, Groq requests) is routed
+    // through a bounded-concurrency queue instead of firing unbounded - see
+    // docs/PERFORMANCE.md. Two separate queues since Discord and Groq have
+    // entirely independent rate limits.
+    this.actionQueue = new EventQueue({ concurrency: this.config.performance.actionConcurrency });
+    this.aiQueue = new EventQueue({ concurrency: this.config.performance.aiConcurrency });
+
+    this.groqClient = new GroqClient(this.config, { debug: this.debug, queue: this.aiQueue, performance: this.performance });
+    this.punishmentEngine = new PunishmentEngine({
+      config: this.config,
+      threatEngine: this.threatEngine,
+      roleAnalyzer: this.roleAnalyzer,
+      logger: this.logger,
+      whitelist: this.whitelist,
+      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().
+    this.layers = {
+      basicSecurity: new BasicSecurityLayer(this),
+      antiRaid: new AntiRaidLayer(this),
+      antiNuke: new AntiNukeLayer(this),
+      aiModeration: new AIModerationLayer(this)
+    };
+
+    this.prefixRouter = new PrefixRouter(this);
+    this.prefixRouter.attach();
+    this._attachButtonHandler();
+
+    if (this.debug) console.log(VersionInfo.banner());
+
+    for (const name of options.autoStart || []) {
+      if (this.layers[name]) this.layers[name].enable();
+    }
+  }
+
+  isAuthorized(member) {
+    if (!member) return false;
+    if (member.id === member.guild.ownerId) return true;
+    return member.permissions.has(PermissionsBitField.Flags.ManageGuild);
+  }
+
+  getStatus(guildId) {
+    const out = {};
+    for (const [name, layer] of Object.entries(this.layers)) {
+      out[name] = layer.enabled;
+    }
+    return out;
+  }
+
+  /** One-call health snapshot: event throughput/latency, queue depth, and every cache's stats. */
+  getMetrics() {
+    return {
+      performance: this.performance.snapshot(),
+      queues: {
+        actions: this.actionQueue.getStats(),
+        ai: this.aiQueue.getStats()
+      },
+      caches: {
+        threatScores: this.threatEngine.scores.getStats(),
+        openCases: this.punishmentEngine.cases.getStats(),
+        groqVerdicts: this.groqClient.cache.getStats()
+      }
+    };
+  }
+
+  enableLayer(name) {
+    if (!this.layers[name]) throw new Error(`GlassFrame Protocol: unknown layer "${name}"`);
+    this.layers[name].enable();
+    return this;
+  }
+
+  disableLayer(name) {
+    if (!this.layers[name]) throw new Error(`GlassFrame Protocol: unknown layer "${name}"`);
+    this.layers[name].disable();
+    return this;
+  }
+
+  _attachButtonHandler() {
+    this.client.on("interactionCreate", async (interaction) => {
+      if (!interaction.isButton() || !interaction.customId.startsWith("gfp_toggle_")) return;
+
+      try {
+        if (!this.isAuthorized(interaction.member)) {
+          await interaction.reply({ content: "You need Manage Server permission to use this.", ephemeral: true });
+          return;
+        }
+
+        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;
+        }
+
+        const payload = buildPanel(this, interaction.guild.id);
+        await interaction.update(payload);
+
+        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 });
+      }
+    });
+  }
+}
+
+function mergeConfig(base, override) {
+  const out = { ...base };
+  for (const key of Object.keys(override)) {
+    if (
+      typeof override[key] === "object" &&
+      override[key] !== null &&
+      !Array.isArray(override[key]) &&
+      typeof base[key] === "object"
+    ) {
+      out[key] = mergeConfig(base[key], override[key]);
+    } else {
+      out[key] = override[key];
+    }
+  }
+  return out;
+}
+
+module.exports = GlassFrame;

package/dist/src/ai/GroqClient.js

@@ -0,0 +1,161 @@
+"use strict";
+
+const ProtocolCache = require("../core/Cache");
+
+/**
+ * Thin client for Groq's OpenAI-compatible chat completions endpoint, built
+ * around a pool of API keys rather than one: if a key comes back
+ * rate-limited it's benched for a cooldown and the next key in the pool is
+ * tried, so one exhausted key doesn't take AI moderation offline. Every
+ * verdict is cached briefly so a burst of identical/near-identical spam
+ * only costs one real API call (see docs/CACHE_ARCHITECTURE.md).
+ *
+ * Uses Node's built-in fetch/AbortController - no extra dependency, and
+ * consistent with the rest of the library staying dependency-light.
+ */
+class GroqClient {
+  constructor(config, { debug = false, queue, performance } = {}) {
+    this.config = config.aiModeration;
+    this.keys = (this.config.apiKeys || []).map((key) => ({ key, cooldownUntil: 0 }));
+    this.keyIndex = 0;
+    this.cache = new ProtocolCache("groq-verdicts", { ttlMs: this.config.cacheTtlMs, debug });
+    this.callTimestamps = [];
+    // Outbound requests go through a bounded-concurrency queue so a wave of
+    // gray-zone messages can't fire dozens of simultaneous Groq calls at
+    // once; falls back to running inline if no queue is supplied.
+    this.queue = queue || { push: (task) => task() };
+    this.performance = performance || { recordEvent() {}, time: () => () => {} };
+  }
+
+  get available() {
+    return this.keys.length > 0;
+  }
+
+  _nextKey() {
+    const now = Date.now();
+    for (let i = 0; i < this.keys.length; i++) {
+      const idx = (this.keyIndex + i) % this.keys.length;
+      if (this.keys[idx].cooldownUntil < now) {
+        this.keyIndex = (idx + 1) % this.keys.length;
+        return this.keys[idx];
+      }
+    }
+    return null;
+  }
+
+  _underRateBudget() {
+    const now = Date.now();
+    this.callTimestamps = this.callTimestamps.filter((t) => now - t < 60000);
+    return this.callTimestamps.length < this.config.maxCallsPerMinute;
+  }
+
+  _hash(text) {
+    let h = 0;
+    const s = String(text).slice(0, 500);
+    for (let i = 0; i < s.length; i++) {
+      h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+    }
+    return `h${h}`;
+  }
+
+  /**
+   * Returns { category, confidence, reason } or null if AI moderation is
+   * unavailable, unconfigured, exhausted, or errors out. Callers must treat
+   * null as "fall back to local detection", never as "message is clean".
+   */
+  async classify(text, context = "") {
+    if (!this.available || !text) return null;
+    if (!this._underRateBudget()) return null;
+
+    const cacheKey = this._hash(text);
+    const cached = this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    const slot = this._nextKey();
+    if (!slot) return null;
+
+    const done = this.performance.time("groqClient.classify");
+    try {
+      this.callTimestamps.push(Date.now());
+      // Queued rather than fired directly - the request's own timeout clock
+      // (below) only starts once it actually leaves the queue, so a busy
+      // moment never causes a false request-level timeout.
+      const verdict = await this.queue.push(() => this._request(slot, text, context));
+      if (verdict) this.cache.set(cacheKey, verdict);
+      return verdict;
+    } catch {
+      return null;
+    } finally {
+      done();
+      this.performance.recordEvent("groqClient.classify");
+    }
+  }
+
+  async _request(slot, text, context) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const res = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${slot.key}`
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          temperature: 0,
+          max_tokens: 200,
+          messages: [
+            {
+              role: "system",
+              content: "You are a Discord moderation classifier. Respond with ONLY compact JSON, no prose, no markdown fences."
+            },
+            { role: "user", content: this._buildPrompt(text, context) }
+          ]
+        }),
+        signal: controller.signal
+      });
+
+      if (res.status === 429) {
+        slot.cooldownUntil = Date.now() + 60000;
+        return null;
+      }
+      if (!res.ok) return null;
+
+      const data = await res.json();
+      const raw = data.choices?.[0]?.message?.content || "";
+      return this._parse(raw);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  _buildPrompt(text, context) {
+    return [
+      "Classify this Discord message for moderation purposes.",
+      context ? `Context: ${context}` : null,
+      `Message: ${JSON.stringify(text.slice(0, 1000))}`,
+      'Return JSON exactly like: {"category":"clean|spam|scam|phishing|raid_coordination|harassment|nsfw","confidence":0.0,"reason":"short reason"}'
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  _parse(raw) {
+    try {
+      const cleaned = raw.replace(/```json|```/g, "").trim();
+      const parsed = JSON.parse(cleaned);
+      if (typeof parsed.category !== "string" || typeof parsed.confidence !== "number") return null;
+      return {
+        category: parsed.category,
+        confidence: Math.max(0, Math.min(1, parsed.confidence)),
+        reason: parsed.reason || "AI classification"
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+module.exports = GroqClient;

package/dist/src/commands/PrefixRouter.js

@@ -0,0 +1,177 @@
+"use strict";
+
+const { buildPanel } = require("../ui/ControlPanel");
+const { buildLogMessage } = require("../logging/ComponentsV2");
+
+const LAYER_NAMES = ["antiRaid", "antiNuke", "basicSecurity", "aiModeration"];
+const COMMANDS = ["panel", "status", "help", "whitelist", "scan", "metrics", "phishing"];
+
+/**
+ * GlassFrame Protocol registers no slash commands, by design (see
+ * docs/COMMANDS.md). Every command here is a plain prefix command gated on
+ * Manage Server permission, with a short per-user cooldown so a doubled
+ * keypress can't fire the same command twice in a row.
+ */
+class PrefixRouter {
+  constructor(frame) {
+    this.frame = frame;
+    this.lastUsed = new Map(); // `guildId:userId` -> timestamp
+  }
+
+  attach() {
+    this.frame.client.on("messageCreate", (message) => this._handle(message).catch(() => {}));
+  }
+
+  _onCooldown(message) {
+    const key = `${message.guild.id}:${message.author.id}`;
+    const now = Date.now();
+    const last = this.lastUsed.get(key) || 0;
+    const cooldownMs = this.frame.config.performance.commandCooldownMs;
+    if (now - last < cooldownMs) return true;
+    this.lastUsed.set(key, now);
+    return false;
+  }
+
+  async _handle(message) {
+    if (!message.guild || message.author.bot) return;
+    const prefix = this.frame.config.prefix;
+    if (!message.content.toLowerCase().startsWith(prefix.toLowerCase())) return;
+
+    const args = message.content.slice(prefix.length).trim().split(/\s+/);
+    const command = (args.shift() || "").toLowerCase();
+    if (!COMMANDS.includes(command)) return;
+
+    if (!this.frame.isAuthorized(message.member)) {
+      await message.reply({ content: "You need Manage Server permission to use GlassFrame Protocol commands." });
+      return;
+    }
+
+    if (this._onCooldown(message)) return;
+
+    if (command === "panel") return this._panel(message);
+    if (command === "status") return this._status(message);
+    if (command === "help") return this._help(message);
+    if (command === "whitelist") return this._whitelist(message, args);
+    if (command === "scan") return this._scan(message);
+    if (command === "metrics") return this._metrics(message);
+    if (command === "phishing") return this._phishing(message, args);
+  }
+
+  async _panel(message) {
+    const payload = buildPanel(this.frame, message.guild.id);
+    const sent = await message.channel.send(payload);
+    this.frame.panelMessages.set(sent.id, message.guild.id);
+  }
+
+  async _status(message) {
+    const status = this.frame.getStatus(message.guild.id);
+    const fields = LAYER_NAMES.map((l) => ({ name: l, value: status[l] ? "ACTIVE" : "INACTIVE" }));
+    const payload = buildLogMessage({ level: "info", title: "GlassFrame Protocol - Status", fields });
+    await message.channel.send(payload);
+  }
+
+  async _help(message) {
+    const prefix = this.frame.config.prefix;
+    const payload = buildLogMessage({
+      level: "info",
+      title: "GlassFrame Protocol - Commands",
+      description: [
+        `${prefix}panel - open the 5-button control panel`,
+        `${prefix}status - show which layers are active`,
+        `${prefix}scan - check current roles for name/permission mismatches`,
+        `${prefix}metrics - show performance and cache health`,
+        `${prefix}phishing add|remove|list <domain> - manage the link blocklist`,
+        `${prefix}whitelist add <userId> - exempt a user from all punitive action`,
+        `${prefix}whitelist remove <userId> - remove an exemption`,
+        `${prefix}help - this message`
+      ].join("\n")
+    });
+    await message.channel.send(payload);
+  }
+
+  async _whitelist(message, args) {
+    const [sub, id] = args;
+    if (!sub || !id) {
+      await message.reply({ content: `Usage: ${this.frame.config.prefix}whitelist <add|remove> <userId>` });
+      return;
+    }
+
+    const action = sub.toLowerCase();
+    if (action === "add") this.frame.whitelist.add(id);
+    else if (action === "remove") this.frame.whitelist.delete(id);
+    else return;
+
+    await message.reply({
+      content: `Whitelist updated: ${id} ${action === "add" ? "added to" : "removed from"} the exemption list.`
+    });
+  }
+
+  async _scan(message) {
+    const flags = this.frame.roleAnalyzer.scanRoles(message.guild);
+    if (!flags.length) {
+      await message.reply({ content: "No role name/permission mismatches found." });
+      return;
+    }
+    const payload = buildLogMessage({
+      level: "warn",
+      title: "Role Audit Results",
+      description: flags.map((f) => `**${f.name}** - ${f.reason}`).join("\n")
+    });
+    await message.channel.send(payload);
+  }
+
+  async _metrics(message) {
+    const m = this.frame.getMetrics();
+    const fmtCache = (c) => `size ${c.size} | hits ${c.hits} | misses ${c.misses} | evictions ${c.evictions}`;
+    const fmtQueue = (q) => `active ${q.active}/${q.concurrency} | pending ${q.pending} | completed ${q.completed} | failed ${q.failed}`;
+    const fmtLatency = Object.entries(m.performance.avgLatencyMs)
+      .map(([name, ms]) => `${name}: ${ms}ms avg`)
+      .join("\n") || "no samples yet";
+
+    const payload = buildLogMessage({
+      level: "info",
+      title: "GlassFrame Protocol - Performance",
+      description: `Uptime: ${Math.round(m.performance.uptimeMs / 60000)} min`,
+      fields: [
+        { name: "Action queue", value: fmtQueue(m.queues.actions) },
+        { name: "AI queue", value: fmtQueue(m.queues.ai) },
+        { name: "Threat score cache", value: fmtCache(m.caches.threatScores) },
+        { name: "Open case cache", value: fmtCache(m.caches.openCases) },
+        { name: "Groq verdict cache", value: fmtCache(m.caches.groqVerdicts) },
+        { name: "Average latency", value: fmtLatency }
+      ]
+    });
+    await message.channel.send(payload);
+  }
+
+  async _phishing(message, args) {
+    const [sub, domain] = args;
+    const prefix = this.frame.config.prefix;
+
+    if (!sub || sub.toLowerCase() === "list") {
+      const domains = this.frame.phishingDatabase.list();
+      await message.reply({
+        content: domains.length ? `Blocked domains:\n${domains.join("\n")}` : "The phishing blocklist is empty."
+      });
+      return;
+    }
+
+    if (!domain) {
+      await message.reply({ content: `Usage: ${prefix}phishing <add|remove|list> <domain>` });
+      return;
+    }
+
+    const action = sub.toLowerCase();
+    if (action === "add") {
+      this.frame.phishingDatabase.add(domain);
+      await message.reply({ content: `Added **${domain}** to the phishing blocklist.` });
+    } else if (action === "remove") {
+      const existed = this.frame.phishingDatabase.remove(domain);
+      await message.reply({ content: existed ? `Removed **${domain}** from the blocklist.` : `**${domain}** wasn't on the blocklist.` });
+    } else {
+      await message.reply({ content: `Usage: ${prefix}phishing <add|remove|list> <domain>` });
+    }
+  }
+}
+
+module.exports = PrefixRouter;

package/dist/src/core/Cache.js

@@ -0,0 +1,98 @@
+"use strict";
+
+/**
+ * Small TTL cache used by every stateful piece of GlassFrame Protocol
+ * instead of a bare Map. Centralizing it means every cache in the library
+ * gets the same expiry rules, the same stats, and the same optional debug
+ * logging for free. See docs/CACHE_ARCHITECTURE.md for the full picture of
+ * which cache is used where and why.
+ */
+class ProtocolCache {
+  constructor(name, { ttlMs = 5 * 60 * 1000, debug = false, sweepEveryMs = 60000 } = {}) {
+    this.name = name;
+    this.ttlMs = ttlMs;
+    this.debug = debug;
+    this.store = new Map();
+    this.stats = { hits: 0, misses: 0, sets: 0, evictions: 0, sweeps: 0 };
+    this._sweeper = null;
+
+    if (sweepEveryMs) {
+      this._sweeper = setInterval(() => this.sweep(), sweepEveryMs);
+      this._sweeper.unref?.();
+    }
+  }
+
+  /** ttlOverrideMs of 0 or less means "never expires" for this entry. */
+  set(key, value, ttlOverrideMs) {
+    const ttl = ttlOverrideMs ?? this.ttlMs;
+    this.store.set(key, { value, expiresAt: ttl > 0 ? Date.now() + ttl : Infinity });
+    this.stats.sets++;
+    this._log("SET", key);
+    return value;
+  }
+
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      this.stats.misses++;
+      this._log("MISS", key);
+      return undefined;
+    }
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      this.stats.misses++;
+      this.stats.evictions++;
+      this._log("EXPIRE", key);
+      return undefined;
+    }
+    this.stats.hits++;
+    this._log("HIT", key);
+    return entry.value;
+  }
+
+  has(key) {
+    return this.get(key) !== undefined;
+  }
+
+  delete(key) {
+    const existed = this.store.delete(key);
+    if (existed) this._log("DELETE", key);
+    return existed;
+  }
+
+  sweep() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+        removed++;
+      }
+    }
+    this.stats.evictions += removed;
+    this.stats.sweeps++;
+    if (removed) this._log("SWEEP", `${removed} expired`);
+    return removed;
+  }
+
+  clear() {
+    this.store.clear();
+    this._log("CLEAR", "all keys");
+  }
+
+  getStats() {
+    return { ...this.stats, size: this.store.size, name: this.name };
+  }
+
+  destroy() {
+    if (this._sweeper) clearInterval(this._sweeper);
+  }
+
+  _log(op, key) {
+    if (this.debug) {
+      console.log(`[GlassFrame:Cache:${this.name}] ${op} ${key}`);
+    }
+  }
+}
+
+module.exports = ProtocolCache;