glassframe-protocol 1.2.0

package/docs/PERFORMANCE.md

@@ -0,0 +1,59 @@
+# Performance
+
+GlassFrame Protocol is built to stay fast under exactly the conditions that
+make speed hardest: a raid, a nuke attempt, or a wave of borderline messages
+all create a burst of work at the same moment. Two small pieces exist
+specifically for that.
+
+## EventQueue - bounded concurrency
+
+`src/core/EventQueue.js` is a plain async queue with a concurrency cap.
+Every actual Discord mutation `PunishmentEngine` performs (ban/kick/timeout/
+role removal) and every outbound Groq request `GroqClient` makes goes
+through one of two queues instead of firing directly:
+
+- `frame.actionQueue` - Discord mutations, default concurrency 4
+  (`config.performance.actionConcurrency`).
+- `frame.aiQueue` - Groq requests, default concurrency 3
+  (`config.performance.aiConcurrency`).
+
+Nothing is ever dropped - tasks queue instead of running unbounded. This
+matters most during a burst: twenty raid removals firing at once is exactly
+what trips Discord's per-route rate limit and makes every request slower,
+including the ones that matter. Capping concurrency keeps steady throughput
+instead of a stall-then-flood pattern. `GroqClient`'s per-request timeout
+clock only starts once a request actually leaves the queue, so a busy
+moment never produces a false "the AI didn't respond in time" the way it
+would if the timer started at the moment of the API call being requested.
+
+Both queues expose `getStats()` (`active`, `pending`, `completed`, `failed`,
+`concurrency`), surfaced through `frame.getMetrics()` and `!gf metrics`.
+
+## PerformanceMonitor - lightweight internal metrics
+
+`src/core/PerformanceMonitor.js` tracks two things, both in memory, neither
+requiring a dependency:
+
+- **Event counts** - `recordEvent(name)` increments a counter. Every layer's
+  main handler calls this once per event it processes
+  (`basicSecurity.messageCreate`, `antiRaid.guildMemberAdd`,
+  `antiNuke.auditEntry.<type>`, `groqClient.classify`, ...).
+- **Latency samples** - `time(name)` returns a function; call it when the
+  unit of work finishes. The last 50 samples per name are kept and averaged.
+  Used around `punishmentEngine.execute` and `groqClient.classify`, the two
+  places most likely to be slow (Discord API round trips, network calls).
+
+`frame.getMetrics()` returns all of this plus every cache's stats in one
+snapshot:
+
+```js
+{
+  performance: { uptimeMs, events: { "basicSecurity.messageCreate": 412, ... }, avgLatencyMs: { "groqClient.classify": 340.2, ... } },
+  queues: { actions: { active, pending, completed, failed, concurrency }, ai: { ... } },
+  caches: { threatScores: { size, hits, misses, evictions }, openCases: { ... }, groqVerdicts: { ... } }
+}
+```
+
+`!gf metrics` renders the same data as a Components V2 message. Neither
+`EventQueue` nor `PerformanceMonitor` phones out anywhere - everything here
+stays in the process.

package/docs/PROTOCOL_LAYERS.md

@@ -0,0 +1,89 @@
+# Protocol Layers
+
+GlassFrame Protocol splits every reaction into two kinds, and keeping them
+separate is the core design decision of the whole library.
+
+## Containment vs. punishment
+
+**Containment** is a guild-wide, reversible, time-critical measure a layer
+takes on its own the moment it detects trouble - raising verification level
+during a join spike, reverting a role that just gained Administrator. These
+can't wait for a shared decision pipeline; a raid in progress needs an
+answer in milliseconds, not after a round trip through scoring.
+
+**Punishment** is anything aimed at one member - timeout, kick, ban,
+quarantine. Every layer funnels this through the same two pieces instead of
+deciding on its own:
+
+1. **`ThreatEngine`** - turns a signal (`{ layer, weight, reason }`) into a
+   decaying score per member, and a tier (`none/low/medium/high/critical`).
+2. **`PunishmentEngine`** - turns a tier into an action, after checking
+   `RoleAnalyzer` for hierarchy and trust, and checking for an already-open
+   case on that member so a second signal a moment later merges into the
+   first incident instead of firing again.
+
+This is what makes the protocol "smart" rather than reflexive: a moderator
+account that trips one soft signal doesn't get banned, a member the bot has
+no hierarchy over doesn't get a failed API call retried on every message,
+and twenty raid joins in ten seconds produce one aggregated log line
+instead of twenty separate ones.
+
+## The four layers
+
+| Layer | Listens to | Containment it can do alone | Signals it reports |
+|---|---|---|---|
+| `basicSecurity` | `messageCreate` | deletes the offending message | spam rate, duplicate flood, mention spam, scam/phishing language, suspicious links (via `PhishingDatabase`) |
+| `antiRaid` | `guildMemberAdd` | raises verification level, ends lockdown automatically | fast join-rate spikes, alt-account scoring, and creation-time cluster correlation (see below) |
+| `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.
+
+`basicSecurity` and `aiModeration` both listen to `messageCreate`
+independently rather than one calling into the other - either can be
+enabled without the other, and if both happen to flag the same message,
+`PunishmentEngine`'s per-member case debounce (see above) merges the two
+signals into one incident rather than double-punishing.
+
+## Evasion-resistant detections
+
+Two additions specifically target attacks designed to slip past the
+straightforward rate-counters above:
+
+- **Join clustering** (`AntiRaidLayer._clusterScore`) - a bulk-registered
+  account farm can trickle members in slowly enough that the join-rate
+  counter never trips. Clustering instead asks whether several recent
+  joiners' accounts were all *created* within the same narrow window
+  (`antiRaid.cluster`), which doesn't depend on how fast they join at all.
+- **Webhook message flooding** (`AntiNukeLayer._handleWebhookMessage`) - a
+  webhook message carries no guild member, so a "create a webhook, then
+  spam through it" nuke is invisible to every per-member spam check in the
+  library. AntiNuke remembers who created a webhook (`recentWebhooks`) for
+  a short window and, if that webhook then floods messages
+  (`antiNuke.webhookAbuse`), deletes the webhook and reports the original
+  creator to `PunishmentEngine` - the only path in the library that reaches
+  a member through something *other* than a direct per-member signal.
+
+Both feed the same `ThreatEngine` / `PunishmentEngine` pipeline as
+everything else; they're evasion-resistant in what they watch for, not in
+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.

package/docs/PUBLISHING.md

@@ -0,0 +1,93 @@
+# Publishing to npm
+
+This covers turning this folder into a real `npm install glassframe-protocol`
+package, and what actually happens to the code when you do.
+
+## What "publish to npm" actually means for the code
+
+`npm publish` uploads whatever `package.json`'s `"files"` field points at
+(here: `dist/`, `docs/`, `examples/`, and the root `README.md` / `LICENSE` /
+`GETTING_STARTED.md` / `CHANGELOG.md`) to the public npm registry. Anyone
+who runs `npm install glassframe-protocol` downloads that and it lands as
+plain text in their `node_modules/glassframe-protocol/` folder - Node has to
+be able to parse it to run it, so there's no way to publish something
+installable that isn't also readable on their disk. `src/`, the root
+`config.js`, and the root `index.js` are **not** in `files`, so they never
+get uploaded - only `dist/` does, which the build script (below) produces.
+That's the real, honest ceiling of what "protection" a package publish can
+offer; the [LICENSE](../LICENSE) is what actually restricts copying and
+modifying it - that's a legal boundary, not a technical one.
+
+## One-time setup
+
+1. **Create an npm account** at https://www.npmjs.com/signup if you don't
+   have one, and verify your email.
+2. **Fill in the placeholders** in `package.json`: `author`, `repository`,
+   `homepage`, `bugs`. If you don't have a public git repo for this, you can
+   delete those three fields entirely rather than leave `TODO` text in a
+   published package.
+3. **Check the name is still free**: open
+   `https://www.npmjs.com/package/glassframe-protocol` in a browser. If it's
+   taken, either pick a different `name` in `package.json` or use a scoped
+   name like `@yourusername/glassframe-protocol` (scoped names are
+   basically always available, and `publishConfig.access: "public"` is
+   already set so a scoped package still publishes publicly rather than
+   defaulting to private).
+4. **(Optional) Install terser** for real minification of what gets
+   published: `npm install --save-dev terser`. Without it, `npm run build`
+   still works, it just copies files through unminified - see
+   `scripts/build.js` for why a shortcut minifier isn't used instead.
+
+## Publishing (same steps on Termux, Windows, and Linux - npm doesn't care)
+
+```
+npm login
+```
+Enter your npm username, password, and the one-time code from your
+authenticator app (npm requires 2FA for publishing now). On Termux this
+works exactly the same as any other terminal - it opens a login flow in
+whatever browser is available, or accepts credentials directly depending on
+your npm version.
+
+```
+npm run build
+```
+Regenerates `dist/` from the current source. This also runs automatically
+before publish (see `prepublishOnly` in `package.json`), but running it
+yourself first lets you check the output in `dist/` before it goes out.
+
+```
+npm publish
+```
+That's it - this uploads the package. `npm view glassframe-protocol` right
+after should show your new version.
+
+## Verifying it from a completely clean install
+
+On any machine (Termux, Windows PowerShell/cmd, Linux terminal):
+
+```
+mkdir test-install && cd test-install
+npm init -y
+npm install glassframe-protocol discord.js
+node -e "console.log(require('glassframe-protocol'))"
+```
+
+If that prints the `GlassFrame` class with no errors, the published package
+resolves and loads correctly end to end.
+
+## Publishing an update later
+
+1. Make your changes in `src/` / `config.js` / `index.js` (never in `dist/`
+   directly - it gets overwritten).
+2. Add an entry to `CHANGELOG.md` and bump `VERSION` in
+   `src/core/VersionInfo.js` to match.
+3. Bump `"version"` in `package.json` to the same number
+   (`npm version patch` / `minor` / `major` does both the bump and creates a
+   git tag for you, if you're using git).
+4. `npm publish` again - `prepublishOnly` rebuilds `dist/` automatically.
+
+npm permanently reserves every version number you publish - you can
+`npm unpublish` within a short window after publishing, but you can never
+reuse the same version number afterward, so double-check `dist/` before
+publishing rather than after.

package/examples/basic-usage.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const { Client, GatewayIntentBits } = require("discord.js");
+const GlassFrame = require("../index");
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMembers,
+    GatewayIntentBits.GuildMessages,
+    GatewayIntentBits.MessageContent,
+    GatewayIntentBits.GuildModeration
+  ]
+});
+
+client.once("ready", () => {
+  const frame = new GlassFrame(client, {
+    getLogChannel: async (guild) => {
+      return guild.channels.cache.find((c) => c.name === "security-logs") ?? null;
+    },
+    whitelist: [],
+    // Layers not listed here stay off until someone presses the panel button
+    // or you call frame.enableLayer(name) yourself.
+    autoStart: ["basicSecurity", "antiRaid", "antiNuke"],
+    debug: false,
+    config: {
+      aiModeration: {
+        // Supply one key or several - GlassFrame rotates across the pool and
+        // benches any key that comes back rate-limited.
+        apiKeys: (process.env.GROQ_API_KEYS || "").split(",").filter(Boolean)
+      }
+    }
+  });
+
+  frame.on("warning", (w) => console.warn(`[GlassFrame:${w.layer}]`, w.message));
+  frame.punishmentEngine.on("case", (record) => {
+    console.log(`[GlassFrame] ${record.action} on ${record.userId} (tier ${record.tier})`);
+  });
+
+  console.log(`GlassFrame Protocol ready in ${client.guilds.cache.size} guild(s).`);
+  console.log('Send "!gf panel" in a channel (Manage Server permission) to open the control panel.');
+});
+
+client.login(process.env.BOT_TOKEN);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "glassframe-protocol",
+  "version": "1.2.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": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "GETTING_STARTED.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepublishOnly": "node scripts/build.js",
+    "test": "echo \"See GETTING_STARTED.md - this package has no bundled test runner\" && exit 0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Sarthak & Sashreek, suvrodey9@gmail.com",
+  "keywords": [
+    "discord",
+    "discord.js",
+    "security",
+    "anti-raid",
+    "anti-nuke",
+    "moderation",
+    "groq",
+    "ai-moderation"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "discord.js": "^14.16.0"
+  },
+  "devDependencies": {
+    "terser": "^5.31.0"
+  }
+}