Add Anti-Spam Discord bot

Introduce a new Anti-Spam Discord bot project. Adds project metadata and scripts (package.json, .env.example, .gitignore, README, deploy-commands.js) and the full src implementation: command registration and handling, per-guild settings persistence, configuration parsing, spam detection logic (phishing URLs, suspicious TLDs, mass/role mentions, image+URL combos, new account heuristics), and the bot entrypoint (index.js) that enforces permissions, logs actions, and optionally bans offenders. README explains setup, required intents, and usage; per-server settings are stored under data/guild-settings.json. (package-lock.json added for dependency resolution.)
2026-06-12 08:10:30 +12:00
commit 7205bcd5ac
12 changed files with 1168 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Anti-Spam Discord Bot
+
+Automatically deletes phishing and mass-mention spam, then bans the sender. Works across **multiple servers** from a single bot instance.
+
+## What it catches
+
+- Phishing URLs (fake Discord / Nitro / Steam links, typosquat domains)
+- Suspicious TLDs combined with spam patterns
+- Messages with image links plus other URLs
+- `@everyone` and large role mentions (default: roles with 50+ members)
+- Mass mentions paired with links
+- Optional: stricter rules for very new accounts
+
+## Setup
+
+1. Create a bot at the [Discord Developer Portal](https://discord.com/developers/applications).
+2. Under **Bot → Privileged Gateway Intents**, enable **Message Content Intent**.  
+   (Required — the bot cannot read messages without this. You do **not** need Server Members Intent.)
+3. Invite the bot using a URL that includes the **`applications.commands`** scope, plus `Ban Members`, `Manage Messages`, `Read Message History`, and `View Channels`.  
+   In the Developer Portal: **OAuth2 → URL Generator** → scopes: `bot` + `applications.commands`.
+4. Copy `.env.example` to `.env` and set `DISCORD_TOKEN` and `APPLICATION_ID`.
+5. Install and run:
+
+```bash
+npm install
+npm start
+```
+
+6. In each server, run `/antispam set-log` to choose a mod log channel.
+
+### Commands not showing?
+
+- `/antispam` is only visible to users with **Manage Server** permission.
+- Restart the bot after inviting it — commands are registered per-server on startup.
+- Or deploy instantly: set `DEPLOY_GUILD_ID` to your server ID in `.env`, then run `npm run deploy-commands`.
+- Re-invite the bot if it was added without the `applications.commands` scope.
+
+## Per-server configuration
+
+Use `/antispam` in any server (requires **Manage Server** permission):
+
+| Command | Description |
+|---------|-------------|
+| `/antispam set-log` | Set the moderation log channel for this server |
+| `/antispam add-trusted-role` | Exempt a role from spam checks |
+| `/antispam remove-trusted-role` | Remove a trusted role |
+| `/antispam status` | View this server's settings |
+| `/antispam enable` / `/antispam disable` | Turn protection on or off per server |
+
+Settings are stored in `data/guild-settings.json` on disk.
+
+## Global configuration (`.env`)
+
+These apply to every server the bot is in:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MAX_ROLE_MENTION_SIZE` | `50` | Flag role pings at or above this size |
+| `BAN_ON_SPAM` | `true` | Ban offenders (set `false` to only delete) |
+| `TRUSTED_USER_IDS` | — | User IDs that bypass checks on all servers |
+
+Admins and users with **Manage Server** are always trusted.
+
+## Notes
+
+- The bot needs a role **above** spammers in each server's role list to ban them.
+- Test in a private channel first with `BAN_ON_SPAM=false` if you want delete-only mode.