glassframe-protocol 1.2.0

package/dist/src/core/EventQueue.js

@@ -0,0 +1,62 @@
+"use strict";
+
+/**
+ * Bounded-concurrency async task queue. Under a real raid or nuke burst,
+ * dozens of heavy operations (Groq calls, member fetches, role/ban edits)
+ * can all become ready within the same second. Running them all
+ * concurrently is exactly what trips Discord's per-route rate limits and
+ * makes the bot fall behind right when speed matters most. EventQueue caps
+ * how many run at once and queues the rest with no message rejected, no
+ * task dropped - so throughput stays smooth under load instead of
+ * collapsing into a wall of 429s.
+ *
+ * Not guild-aware by design: PunishmentEngine and GroqClient each own one
+ * shared queue across every guild they serve, since the failure mode this
+ * guards against (hammering Discord's/Groq's global rate limits) is global
+ * too.
+ */
+class EventQueue {
+  constructor({ concurrency = 4 } = {}) {
+    this.concurrency = Math.max(1, concurrency);
+    this.active = 0;
+    this.queue = [];
+    this.stats = { queued: 0, completed: 0, failed: 0, maxQueueDepth: 0 };
+  }
+
+  /** Enqueues an async task (a zero-arg function returning a Promise) and resolves/rejects with its result. */
+  push(task) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ task, resolve, reject });
+      this.stats.queued++;
+      this.stats.maxQueueDepth = Math.max(this.stats.maxQueueDepth, this.queue.length);
+      this._drain();
+    });
+  }
+
+  _drain() {
+    while (this.active < this.concurrency && this.queue.length) {
+      const next = this.queue.shift();
+      this.active++;
+      Promise.resolve()
+        .then(next.task)
+        .then((result) => {
+          this.stats.completed++;
+          next.resolve(result);
+        })
+        .catch((err) => {
+          this.stats.failed++;
+          next.reject(err);
+        })
+        .finally(() => {
+          this.active--;
+          this._drain();
+        });
+    }
+  }
+
+  getStats() {
+    return { ...this.stats, active: this.active, pending: this.queue.length, concurrency: this.concurrency };
+  }
+}
+
+module.exports = EventQueue;

package/dist/src/core/Layer.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const EventEmitter = require("events");
+
+/**
+ * Base class for every GlassFrame Protocol security layer.
+ *
+ * A layer owns exactly one security domain (raid, nuke, message security,
+ * AI). Layers do not punish members directly - they report signals to the
+ * shared ThreatEngine/PunishmentEngine so every layer is judged by the same,
+ * smart, non-spammy rulebook (see docs/PROTOCOL_LAYERS.md). Layers CAN take
+ * immediate, reversible containment action on the guild itself (raise
+ * verification level, revert a role's permissions) since those are
+ * time-critical and aren't about penalizing one member.
+ *
+ * enable()/disable() are the only lifecycle a layer needs to implement -
+ * disable() fully detaches every listener the layer attached, so a disabled
+ * layer does zero work rather than quietly early-returning inside a handler
+ * that's still subscribed.
+ */
+class Layer extends EventEmitter {
+  constructor(name, frame) {
+    super();
+    this.name = name;
+    this.frame = frame;
+    this.enabled = false;
+    this._listeners = [];
+  }
+
+  get client() {
+    return this.frame.client;
+  }
+
+  get config() {
+    return this.frame.config[this.name] || {};
+  }
+
+  _listen(emitter, event, handler) {
+    emitter.on(event, handler);
+    this._listeners.push([emitter, event, handler]);
+  }
+
+  enable() {
+    if (this.enabled) return this;
+    this.enabled = true;
+    this.onEnable();
+    this.frame.emit("layerToggled", { layer: this.name, enabled: true });
+    return this;
+  }
+
+  disable() {
+    if (!this.enabled) return this;
+    this.enabled = false;
+    for (const [emitter, event, handler] of this._listeners) {
+      emitter.removeListener(event, handler);
+    }
+    this._listeners = [];
+    this.onDisable();
+    this.frame.emit("layerToggled", { layer: this.name, enabled: false });
+    return this;
+  }
+
+  // Subclasses override these two hooks.
+  onEnable() {}
+  onDisable() {}
+}
+
+module.exports = Layer;

package/dist/src/core/PerformanceMonitor.js

@@ -0,0 +1,52 @@
+"use strict";
+
+/**
+ * Lightweight internal metrics collector - no external dependency, no
+ * network call, just counters and a small rolling latency sample per event
+ * type. Exposed via `frame.getMetrics()` / `!gf metrics` so you can see
+ * whether the protocol is keeping up on a busy server without wiring in a
+ * separate APM tool.
+ */
+class PerformanceMonitor {
+  constructor() {
+    this.startedAt = Date.now();
+    this.eventCounts = {};
+    this.latencies = {}; // name -> last 50 durations in ms
+  }
+
+  recordEvent(name) {
+    this.eventCounts[name] = (this.eventCounts[name] || 0) + 1;
+  }
+
+  /** Call at the start of a unit of work; call the returned function when it finishes. */
+  time(name) {
+    const start = process.hrtime.bigint();
+    return () => {
+      const ms = Number(process.hrtime.bigint() - start) / 1e6;
+      const arr = this.latencies[name] || (this.latencies[name] = []);
+      arr.push(ms);
+      if (arr.length > 50) arr.shift();
+    };
+  }
+
+  _avg(name) {
+    const arr = this.latencies[name];
+    if (!arr || !arr.length) return null;
+    return arr.reduce((a, b) => a + b, 0) / arr.length;
+  }
+
+  snapshot() {
+    const avgLatencyMs = {};
+    for (const name of Object.keys(this.latencies)) {
+      const avg = this._avg(name);
+      avgLatencyMs[name] = avg === null ? null : Math.round(avg * 100) / 100;
+    }
+    return {
+      uptimeMs: Date.now() - this.startedAt,
+      events: { ...this.eventCounts },
+      avgLatencyMs
+    };
+  }
+}
+
+module.exports = PerformanceMonitor;

package/dist/src/core/StateStore.js

@@ -0,0 +1,69 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Default store: nothing persists across restarts. Fine for most setups,
+ * since layer state is usually re-armed via autoStart or the control panel.
+ */
+class MemoryStateStore {
+  constructor() {
+    this.data = new Map();
+  }
+
+  async get(guildId) {
+    return this.data.get(guildId) || null;
+  }
+
+  async set(guildId, state) {
+    this.data.set(guildId, state);
+    return state;
+  }
+}
+
+/**
+ * Optional convenience store backed by a single JSON file - no database,
+ * no native module, so it works the same on ARM64/Termux as anywhere else.
+ * Fine for the scale this library operates at (per-guild layer toggles),
+ * not intended as a general-purpose datastore.
+ */
+class JSONFileStateStore {
+  constructor(filePath) {
+    this.filePath = filePath || path.join(process.cwd(), "glassframe-state.json");
+    this._cache = null;
+  }
+
+  _load() {
+    if (this._cache) return this._cache;
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf8");
+      this._cache = JSON.parse(raw);
+    } catch {
+      this._cache = {};
+    }
+    return this._cache;
+  }
+
+  _persist() {
+    try {
+      fs.writeFileSync(this.filePath, JSON.stringify(this._cache, null, 2));
+    } catch (err) {
+      console.error("[GlassFrame:StateStore] failed to persist:", err.message);
+    }
+  }
+
+  async get(guildId) {
+    const data = this._load();
+    return data[guildId] || null;
+  }
+
+  async set(guildId, state) {
+    const data = this._load();
+    data[guildId] = state;
+    this._persist();
+    return state;
+  }
+}
+
+module.exports = { MemoryStateStore, JSONFileStateStore };

package/dist/src/core/ThreatEngine.js

@@ -0,0 +1,86 @@
+"use strict";
+
+const EventEmitter = require("events");
+const ProtocolCache = require("./Cache");
+
+/**
+ * Central, cross-layer risk aggregator. Every layer reports weighted
+ * signals here instead of deciding punishment on its own; ThreatEngine
+ * keeps one decaying score per member so a scattering of small, unrelated
+ * flags from different layers combines into one picture instead of each
+ * separately triggering a reaction, and a single serious flag isn't diluted
+ * by history that's long since gone stale.
+ */
+class ThreatEngine extends EventEmitter {
+  constructor(config, { debug = false } = {}) {
+    super();
+    this.config = config.threatEngine;
+    // No hard TTL - decay handles staleness. _prune() below reclaims memory
+    // once an entry has decayed to noise instead of relying on a timed expiry.
+    this.scores = new ProtocolCache("threat-scores", { ttlMs: 0, debug, sweepEveryMs: 0 });
+
+    this._pruner = setInterval(() => this._prune(), 10 * 60 * 1000);
+    this._pruner.unref?.();
+  }
+
+  key(guildId, userId) {
+    return `${guildId}:${userId}`;
+  }
+
+  _decayed(entry) {
+    if (!entry) return 0;
+    const elapsed = Date.now() - entry.updatedAt;
+    const factor = Math.pow(0.5, elapsed / this.config.decayHalfLifeMs);
+    return entry.score * factor;
+  }
+
+  addSignal(guildId, userId, { layer, weight, reason }) {
+    const key = this.key(guildId, userId);
+    const existing = this.scores.get(key);
+    const decayedScore = this._decayed(existing);
+    const newScore = Math.min(100, decayedScore + weight);
+    const history = existing ? existing.history.slice(-9) : [];
+    history.push({ layer, weight, reason, at: Date.now() });
+
+    this.scores.set(key, { score: newScore, updatedAt: Date.now(), history });
+
+    const tier = this.getTier(newScore);
+    this.emit("signal", { guildId, userId, layer, reason, weight, score: newScore, tier });
+    return { score: newScore, tier, history };
+  }
+
+  getScore(guildId, userId) {
+    return this._decayed(this.scores.get(this.key(guildId, userId)));
+  }
+
+  getTier(score) {
+    const t = this.config.tiers;
+    if (score >= t.critical) return "critical";
+    if (score >= t.high) return "high";
+    if (score >= t.medium) return "medium";
+    if (score >= t.low) return "low";
+    return "none";
+  }
+
+  getHistory(guildId, userId) {
+    const entry = this.scores.get(this.key(guildId, userId));
+    return entry ? entry.history : [];
+  }
+
+  reset(guildId, userId) {
+    this.scores.delete(this.key(guildId, userId));
+  }
+
+  /** Drops entries that have decayed to near-zero and haven't moved in a long time. */
+  _prune() {
+    const now = Date.now();
+    for (const [key, entry] of this.scores.store) {
+      const decayed = this._decayed(entry);
+      if (decayed < 0.5 && now - entry.updatedAt > this.config.decayHalfLifeMs * 4) {
+        this.scores.delete(key);
+      }
+    }
+  }
+}
+
+module.exports = ThreatEngine;

package/dist/src/core/VersionInfo.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const VERSION = "1.2.0";
+const NAME = "GlassFrame Protocol";
+const RELEASED = "2026-07-31";
+
+/**
+ * A plain-ASCII banner (no emoji, no box-drawing Unicode) so it renders
+ * identically in every terminal, including Termux. Printed once at startup
+ * when GlassFrame is constructed with { debug: true }.
+ */
+function banner() {
+  const title = `${NAME} v${VERSION}`;
+  const subtitle = "Layered Discord Security Engine";
+  const width = Math.max(title.length, subtitle.length) + 4;
+
+  const bar = "+" + "-".repeat(width - 2) + "+";
+  const center = (text) => {
+    const spare = width - 2 - text.length;
+    const left = Math.floor(spare / 2);
+    const right = spare - left;
+    return "|" + " ".repeat(left) + text + " ".repeat(right) + "|";
+  };
+
+  return [bar, center(title), center(subtitle), bar].join("\n");
+}
+
+function info() {
+  return { name: NAME, version: VERSION, released: RELEASED };
+}
+
+module.exports = { VERSION, NAME, RELEASED, banner, info };

package/dist/src/layers/AIModerationLayer.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const Layer = require("../core/Layer");
+const { classifyMessage } = require("../utils/nlpEngine");
+
+const SEVERITY_WEIGHT = {
+  spam: 15,
+  harassment: 30,
+  scam: 40,
+  phishing: 40,
+  raid_coordination: 45,
+  nsfw: 35
+};
+
+/**
+ * Two-stage message moderation: the free, local NLP classifier runs first
+ * and handles the obvious cases. Only messages that land in the gray zone -
+ * not clean, not obviously over threshold - get escalated to Groq for a
+ * second, smarter opinion. This keeps AI calls rare, cheap, and reserved
+ * for the messages that actually need judgement, and keeps this layer fully
+ * independent of BasicSecurityLayer so either can run without the other.
+ */
+class AIModerationLayer extends Layer {
+  constructor(frame) {
+    super("aiModeration", frame);
+  }
+
+  get groq() {
+    return this.frame.groqClient;
+  }
+
+  onEnable() {
+    if (!this.groq?.available) {
+      this.frame.emit("warning", {
+        layer: "aiModeration",
+        message: "No Groq API keys configured - layer is active but will stay idle. Set aiModeration.apiKeys in config."
+      });
+    }
+    this._listen(this.client, "messageCreate", (message) => this._handle(message).catch(() => {}));
+  }
+
+  onDisable() {}
+
+  async _handle(message) {
+    if (!message.guild || message.author.bot || !message.content) return;
+    if (!this.groq?.available) return;
+
+    const cfg = this.config;
+    const local = classifyMessage(message.content);
+    const topScore = Math.max(local.scam, local.phishing, local.raidCallout);
+
+    const inGrayZone = topScore >= cfg.grayZone.min && topScore < cfg.grayZone.max;
+    if (!inGrayZone) return;
+
+    const verdict = await this.groq.classify(message.content, `local pre-scan suggested: ${local.topLabel}`);
+    if (!verdict || verdict.category === "clean") return;
+
+    const weight = Math.round((SEVERITY_WEIGHT[verdict.category] || 20) * verdict.confidence);
+    if (weight <= 0) return;
+
+    try {
+      if (message.deletable) await message.delete();
+    } catch {
+      /* best effort */
+    }
+
+    await this.frame.punishmentEngine.report({
+      guild: message.guild,
+      member: message.member,
+      layer: "aiModeration",
+      weight,
+      reason: `AI flagged ${verdict.category} (${Math.round(verdict.confidence * 100)}%): ${verdict.reason}`
+    });
+  }
+}
+
+module.exports = AIModerationLayer;