AeThex-Bot-Master/replit.md

AeThex Unified Bot

A single Discord bot combining community features and enterprise security (Sentinel).

Overview

AeThex Unified Bot handles both community features AND security in one instance:

• Sentinel Security: Anti-nuke protection with RAM-based heat tracking
• Federation Sync: Cross-server role synchronization across 5 realms
• Ticket System: Support tickets with automatic channel creation
• Admin Monitoring: Real-time status, threat monitoring, server overview

Tech Stack

• Runtime: Node.js 20
• Framework: discord.js v14
• Database: Supabase (optional, for user verification)
• Health Endpoint: HTTP server on port 8080

Project Structure

aethex-bot/
├── bot.js                      # Main entry point
├── package.json
├── .env.example
├── commands/
│   ├── admin.js                # /admin status|heat|servers|threats|federation
│   ├── federation.js           # /federation link|unlink|list
│   ├── status.js               # /status - network overview
│   └── ticket.js               # /ticket create|close
├── events/
│   └── guildMemberUpdate.js    # Federation role sync listener
├── listeners/
│   └── sentinel/
│       ├── antiNuke.js         # Channel delete monitor
│       ├── roleDelete.js       # Role delete monitor
│       ├── memberBan.js        # Mass ban detection
│       └── memberKick.js       # Mass kick detection
└── scripts/
    └── register-commands.js    # Slash command registration

Commands

Command	Description
/admin status	View bot status and statistics
/admin heat @user	Check heat level of a user
/admin servers	View all connected servers
/admin threats	View active threat monitor
/admin federation	View federation role mappings
/federation link @role	Link a role for cross-server sync
/federation unlink @role	Remove a role from sync
/federation list	List all linked roles
/ticket create [reason]	Create a support ticket
/ticket close	Close the current ticket
/status	View network status

Sentinel Security System

The anti-nuke system uses RAM-based heat tracking for instant response:

• Heat Threshold: 3 dangerous actions in 10 seconds triggers auto-ban
• Monitored Actions: Channel delete, role delete, member ban, member kick
• Alerts: Sends to configured alert channel and DMs server owner
• Whitelist: Set WHITELISTED_USERS env var for trusted users

Environment Variables

Required:

• DISCORD_TOKEN or DISCORD_BOT_TOKEN - Bot token
• DISCORD_CLIENT_ID - Application ID (currently: 578971245454950421)

Optional - Federation:

• HUB_GUILD_ID - Main hub server
• LABS_GUILD_ID, GAMEFORGE_GUILD_ID, CORP_GUILD_ID, FOUNDATION_GUILD_ID

Optional - Security:

• WHITELISTED_USERS - Comma-separated user IDs to skip heat tracking
• ALERT_CHANNEL_ID - Channel for security alerts

Optional - Supabase:

• SUPABASE_URL, SUPABASE_SERVICE_ROLE - For user verification features

Health Endpoint

GET /health (port 8080)

{
  "status": "online",
  "guilds": 5,
  "commands": 4,
  "uptime": 3600,
  "heatMapSize": 0,
  "timestamp": "2025-12-07T22:15:00.000Z"
}

GET /stats (port 8080)

{
  "guilds": [...],
  "totalMembers": 500,
  "uptime": 3600,
  "activeTickets": 0,
  "heatEvents": 0
}

Running the Bot

cd aethex-bot
npm install
node scripts/register-commands.js  # Register slash commands (run once)
npm start

Current Status

• Bot is running and connected to 5 servers
• All 4 commands registered (/admin, /federation, /status, /ticket)
• Sentinel listeners active (channel/role delete, ban/kick monitoring)
• Health endpoint available at port 8080