Update configuration and README for improved setup and security; disable default API and emoji sync, and enhance Discord permission checks in API routes.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
TheOnlyMace
133
dashboard/README.md
Normal file
133
dashboard/README.md
Normal file
@@ -0,0 +1,133 @@
|
||||
<div align="center">
|
||||
|
||||
# ZyroX Dashboard
|
||||
|
||||
Next.js web dashboard for configuring the ZyroX Discord bot.
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
- **Discord OAuth login** — users only see servers they can manage
|
||||
- **Server-side API proxy** — `DASHBOARD_API_KEY` never exposed to the browser
|
||||
- **Guild permission checks** — bot API verifies Discord Manage Server / Admin rights
|
||||
- **Fully branded** — name and colours via environment variables
|
||||
- **Vercel-ready**
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Notes |
|
||||
|---|---|
|
||||
| Node.js 18+ | — |
|
||||
| ZyroX bot running | with `API_ENABLED=true` on `127.0.0.1` (or via Cloudflare Tunnel) |
|
||||
| Discord OAuth app | from [Discord Developer Portal](https://discord.com/developers/applications) |
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1 — Install dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2 — Configure environment
|
||||
|
||||
Create `.env.local` in this folder (see `.env.example`):
|
||||
|
||||
```env
|
||||
# ── Bot API (server-side only — never use NEXT_PUBLIC_ for the key) ──
|
||||
DASHBOARD_API_URL = http://127.0.0.1:8000/api/v1
|
||||
DASHBOARD_API_KEY = same_secret_as_bot_DASHBOARD_API_KEY
|
||||
|
||||
# ── NextAuth ──────────────────────────────────────────────────────
|
||||
NEXTAUTH_URL = http://localhost:3000
|
||||
NEXTAUTH_SECRET = a_long_random_string
|
||||
|
||||
# ── Discord OAuth ─────────────────────────────────────────────────
|
||||
DISCORD_CLIENT_ID = your_discord_oauth_client_id
|
||||
DISCORD_CLIENT_SECRET = your_discord_oauth_client_secret
|
||||
|
||||
# ── Admin & Branding ──────────────────────────────────────────────
|
||||
ADMIN_IDS = your_discord_user_id
|
||||
NEXT_PUBLIC_ADMIN_IDS = your_discord_user_id
|
||||
NEXT_PUBLIC_BRAND_NAME = "ZyroX"
|
||||
NEXT_PUBLIC_BRAND_NAME_WORD = "ZX"
|
||||
```
|
||||
|
||||
### 3 — Run locally
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000)
|
||||
|
||||
---
|
||||
|
||||
## Environment Reference
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `DASHBOARD_API_URL` | Bot API URL (server-side). Local: `http://127.0.0.1:8000/api/v1` |
|
||||
| `DASHBOARD_API_KEY` | Must match bot `DASHBOARD_API_KEY` — **server-side only** |
|
||||
| `NEXTAUTH_URL` | Dashboard public URL |
|
||||
| `NEXTAUTH_SECRET` | Random secret for NextAuth session signing |
|
||||
| `DISCORD_CLIENT_ID` | Discord OAuth2 client ID |
|
||||
| `DISCORD_CLIENT_SECRET` | Discord OAuth2 client secret |
|
||||
| `ADMIN_IDS` | Server-side admin user IDs (for admin API routes) |
|
||||
| `NEXT_PUBLIC_ADMIN_IDS` | Same IDs for admin panel UI visibility |
|
||||
| `NEXT_PUBLIC_BRAND_NAME` | Bot name in the dashboard UI |
|
||||
| `NEXT_PUBLIC_BRAND_NAME_WORD` | Short abbreviation (e.g. `ZX`) |
|
||||
|
||||
> Do **not** set `NEXT_PUBLIC_DASHBOARD_API_KEY`. The browser uses `/api/proxy`, which adds the secret server-side.
|
||||
|
||||
---
|
||||
|
||||
## How API auth works
|
||||
|
||||
```
|
||||
Browser → /api/proxy/guilds/... → Next.js (session check)
|
||||
→ Bot API with:
|
||||
Authorization: Bearer DASHBOARD_API_KEY
|
||||
X-Discord-Access-Token: <oauth token>
|
||||
X-Discord-User-Id: <user id>
|
||||
→ Bot verifies Discord Manage Server permission per guild
|
||||
```
|
||||
|
||||
SSR (server components) call the bot API directly with the same headers from the active session.
|
||||
|
||||
---
|
||||
|
||||
## Deployment (Vercel)
|
||||
|
||||
1. Connect repo → set root directory to `dashboard/`
|
||||
2. Add all environment variables from the table above
|
||||
3. Set `NEXTAUTH_URL` to your Vercel domain
|
||||
4. Add OAuth redirect: `https://your-app.vercel.app/api/auth/callback/discord`
|
||||
5. Deploy
|
||||
|
||||
For production with Cloudflare Tunnel, set:
|
||||
|
||||
```env
|
||||
DASHBOARD_API_URL=https://api.yourdomain.com/api/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Fix |
|
||||
|---|---|
|
||||
| Dashboard can't load data | Bot running with `API_ENABLED=true`, `DASHBOARD_API_URL` correct |
|
||||
| 401 from bot API | `DASHBOARD_API_KEY` must match bot `.env` exactly |
|
||||
| 403 on guild routes | User must have Manage Server or Admin on that Discord server |
|
||||
| Admin panel 403 | Add your Discord ID to `ADMIN_IDS` and bot `DASHBOARD_ADMIN_IDS` |
|
||||
| Auth error on login | Check Discord OAuth client ID/secret and redirect URI |
|
||||
|
||||
See also `SECURITY_FIXES.md` in the project root.
|
||||
Reference in New Issue
Block a user