AeThex-Bot-Master/replit.md

# AeThex Unified Bot

A complete Discord bot combining AeThex community features and Sentinel enterprise security in one instance.

## Overview

AeThex Unified Bot handles both community features AND security:

- **Community Features**: User verification, profile linking, realm selection, leaderboards, community posts
- **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 and community features)
- **Health Endpoint**: HTTP server on port 8080

## Project Structure

```
aethex-bot/
├── bot.js                      # Main entry point (merged: original + Sentinel)
├── package.json
├── .env.example                # Complete environment template
├── Dockerfile                  # Docker deployment config
├── discloud.config             # DisCloud hosting config
├── DEPLOYMENT_GUIDE.md         # Deployment documentation
├── commands/
│   ├── admin.js                # /admin status|heat|servers|threats|federation
│   ├── federation.js           # /federation link|unlink|list
│   ├── help.js                 # /help - command list
│   ├── leaderboard.js          # /leaderboard - top contributors
│   ├── post.js                 # /post - community feed posts
│   ├── profile.js              # /profile - view linked profile
│   ├── refresh-roles.js        # /refresh-roles - sync roles
│   ├── set-realm.js            # /set-realm - choose primary realm
│   ├── stats.js                # /stats - user statistics
│   ├── status.js               # /status - network overview
│   ├── ticket.js               # /ticket create|close
│   ├── unlink.js               # /unlink - disconnect account
│   ├── verify-role.js          # /verify-role - check roles
│   └── verify.js               # /verify - link account
├── events/
│   └── messageCreate.js        # Message event handler
├── listeners/
│   ├── feedSync.js             # Community feed sync
│   └── 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 (14 Total)

### Community Commands (10)
| Command | Description |
|---------|-------------|
| `/verify` | Link your Discord account to AeThex |
| `/unlink` | Disconnect your Discord from AeThex |
| `/profile` | View your linked AeThex profile |
| `/set-realm` | Choose your primary realm |
| `/verify-role` | Check your assigned Discord roles |
| `/refresh-roles` | Sync roles based on AeThex profile |
| `/stats` | View your AeThex statistics |
| `/leaderboard` | View top contributors |
| `/post` | Create a community feed post |
| `/help` | View all bot commands |

### Sentinel Commands (4)
| 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

Anti-nuke system using 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_BOT_TOKEN` - Bot token from Discord Developer Portal
- `DISCORD_CLIENT_ID` - Application ID (e.g., 578971245454950421)

### Optional - Supabase (for community features)
- `SUPABASE_URL` - Supabase project URL
- `SUPABASE_SERVICE_ROLE` - Supabase service role key

### 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 - Feed Sync
- `DISCORD_FEED_CHANNEL_ID` - Channel for community feed
- `DISCORD_FEED_GUILD_ID` - Guild for community feed
- `DISCORD_MAIN_CHAT_CHANNELS` - Comma-separated channel IDs

## Health Endpoints

**GET /health** (port 8080)
```json
{
  "status": "online",
  "guilds": 8,
  "commands": 14,
  "uptime": 3600,
  "heatMapSize": 0,
  "supabaseConnected": false,
  "timestamp": "2025-12-07T23:00:00.000Z"
}
```

**GET /stats** (port 8080)
```json
{
  "guilds": [...],
  "totalMembers": 500,
  "uptime": 3600,
  "activeTickets": 0,
  "heatEvents": 0
}
```

## Running the Bot

```bash
cd aethex-bot
npm install
npm start
```

Commands are registered automatically on startup or via POST to `/register-commands`.

## Current Status

- Bot running as AeThex#9389
- Connected to 8 servers
- 14 commands loaded
- 4 Sentinel listeners active
- Health endpoint on port 8080
- Supabase optional (community features limited when not configured)

## Workflow

- **Name**: AeThex Unified Bot
- **Command**: `cd aethex-bot && npm start`
- **Status**: Running