feat: guild admin authentication & authorization

.env.example

@@ -18,6 +18,13 @@ GUILD_ID=your_discord_guild_id
 # Discord OAuth2 client secret (required for web dashboard)
 DISCORD_CLIENT_SECRET=your_discord_client_secret
 
+# Discord OAuth2 redirect URI (required for web dashboard)
+DISCORD_REDIRECT_URI=http://localhost:3001/api/v1/auth/discord/callback
+
+# Session secret for JWT signing (required for OAuth2 dashboard auth)
+# Generate with: openssl rand -base64 32
+SESSION_SECRET=your_session_secret
+
 # ── OpenClaw ─────────────────────────────────
 
 # OpenClaw chat completions endpoint (required)
@@ -61,6 +68,15 @@ DASHBOARD_URL=http://localhost:3000
 # Discord client ID exposed to browser (required for web dashboard)
 NEXT_PUBLIC_DISCORD_CLIENT_ID=your_discord_client_id
 
+# ── Bot Owner / Permissions ───────────────────
+
+# Bot owner Discord user IDs are configured in config.json under
+# permissions.botOwners. The default value is the upstream maintainer's ID.
+# **Forks/deployers:** Update config.json permissions.botOwners with your own
+# Discord user ID(s). Bot owners bypass all permission checks.
+# Find your Discord user ID: User Settings → Advanced → Enable Developer Mode,
+# then right-click your name → Copy User ID.
+
 # ── Optional Integrations ────────────────────
 
 # mem0 API key for user long-term memory (optional — memory features disabled without it)

README.md

@@ -187,11 +187,15 @@ All configuration lives in `config.json` and can be updated at runtime via the `
 |-----|------|-------------|
 | `enabled` | boolean | Enable permission checks |
 | `adminRoleId` | string | Role ID for admin commands |
-| `allowedCommands` | object | Per-command permission levels |
+| `moderatorRoleId` | string | Role ID for moderator commands |
+| `botOwners` | string[] | Discord user IDs that bypass all permission checks |
+| `allowedCommands` | object | Per-command permission levels (`everyone`, `moderator`, `admin`) |
+
+> **⚠️ For forks/deployers:** The default `config.json` ships with the upstream maintainer's Discord user ID in `permissions.botOwners`. Update this array with your own Discord user ID(s) before deploying. Bot owners bypass all permission checks.
 
 ## ⚔️ Moderation Commands
 
-All moderation commands require the admin role (configured via `permissions.adminRoleId`).
+Most moderation commands require admin-level access. `/modlog` is moderator-level by default (`permissions.allowedCommands.modlog = "moderator"`).
 
 ### Core Actions
 
@@ -351,6 +355,9 @@ Set these in the Railway dashboard for the Bot service:
 | `DATABASE_URL` | Yes | `${{Postgres.DATABASE_URL}}` — Railway variable reference |
 | `MEM0_API_KEY` | No | Mem0 API key for long-term memory |
 | `LOG_LEVEL` | No | `debug`, `info`, `warn`, or `error` (default: `info`) |
+| `SESSION_SECRET` | Yes | JWT signing secret for OAuth2 sessions. Generate with `openssl rand -base64 32` |
+| `DISCORD_CLIENT_SECRET` | Yes | Discord OAuth2 client secret (required for dashboard auth) |
+| `DISCORD_REDIRECT_URI` | Yes | OAuth2 callback URL (e.g. `https://your-bot/api/v1/auth/discord/callback`) |
 | `BOT_API_SECRET` | Yes | Shared secret for web dashboard API auth |
 
 ### Web Dashboard Environment Variables

config.json

@@ -82,6 +82,8 @@
   "permissions": {
     "enabled": true,
     "adminRoleId": null,
+    "moderatorRoleId": null,
+    "botOwners": ["191633014441115648"],
     "usePermissions": true,
     "allowedCommands": {
       "ping": "everyone",
@@ -101,7 +103,7 @@
       "lock": "admin",
       "unlock": "admin",
       "slowmode": "admin",
-      "modlog": "admin"
+      "modlog": "moderator"
     }
   }
 }

package.json

@@ -20,6 +20,7 @@
     "discord.js": "^14.25.1",
     "dotenv": "^17.3.1",
     "express": "^5.2.1",
+    "jsonwebtoken": "^9.0.3",
     "mem0ai": "^2.2.2",
     "pg": "^8.18.0",
     "winston": "^3.19.0",

src/api/index.js

@@ -5,6 +5,7 @@
 
 import { Router } from 'express';
 import { requireAuth } from './middleware/auth.js';
+import authRouter from './routes/auth.js';
 import guildsRouter from './routes/guilds.js';
 import healthRouter from './routes/health.js';
 
@@ -13,7 +14,10 @@ const router = Router();
 // Health check — public (no auth required)
 router.use('/health', healthRouter);
 
-// Guild routes — require API secret
+// Auth routes — public (no auth required)
+router.use('/auth', authRouter);
+
+// Guild routes — require API secret or OAuth2 JWT
 router.use('/guilds', requireAuth(), guildsRouter);
 
 export default router;

src/api/middleware/auth.js

@@ -1,10 +1,11 @@
 /**
  * Authentication Middleware
- * Validates requests using a shared API secret
+ * Supports both shared API secret and OAuth2 JWT authentication
  */
 
 import crypto from 'node:crypto';
 import { warn } from '../../logger.js';
+import { handleOAuthJwt } from './oauthJwt.js';
 
 /**
  * Performs a constant-time comparison of the given secret against BOT_API_SECRET.
@@ -24,23 +25,46 @@ export function isValidSecret(secret) {
 }
 
 /**
- * Creates middleware that validates the x-api-secret header against BOT_API_SECRET.
- * Returns 401 JSON error if the header is missing or does not match.
+ * Creates middleware that validates either:
+ * - x-api-secret header (shared secret) — sets req.authMethod = 'api-secret'
+ * - Authorization: Bearer <jwt> header (OAuth2) — sets req.authMethod = 'oauth', req.user = decoded JWT
+ *
+ * Returns 401 JSON error if neither is valid.
  *
  * @returns {import('express').RequestHandler} Express middleware function
  */
 export function requireAuth() {
   return (req, res, next) => {
-    if (!process.env.BOT_API_SECRET) {
-      warn('BOT_API_SECRET not configured — rejecting API request');
-      return res.status(401).json({ error: 'API authentication not configured' });
+    // Try API secret first
+    const apiSecret = req.headers['x-api-secret'];
+    if (apiSecret) {
+      if (!process.env.BOT_API_SECRET) {
+        // API secret auth is not configured — ignore the header and fall through to JWT.
+        // This allows clients that always send x-api-secret to still authenticate via JWT
+        // when the deployer hasn't configured BOT_API_SECRET.
+        warn('BOT_API_SECRET not configured — ignoring x-api-secret header, trying JWT', {
+          ip: req.ip,
+          path: req.path,
+        });
+      } else if (isValidSecret(apiSecret)) {
+        req.authMethod = 'api-secret';
+        return next();
+      } else {
+        // BOT_API_SECRET is configured but the provided secret doesn't match.
+        // Reject immediately — an explicit API-secret auth attempt that fails
+        // should not silently fall through to JWT.
+        warn('Invalid API secret provided', { ip: req.ip, path: req.path });
+        return res.status(401).json({ error: 'Invalid API secret' });
+      }
     }
 
-    if (!isValidSecret(req.headers['x-api-secret'])) {
-      warn('Unauthorized API request', { ip: req.ip, path: req.path });
-      return res.status(401).json({ error: 'Unauthorized' });
+    // Try OAuth2 JWT
+    if (handleOAuthJwt(req, res, next)) {
+      return;
     }
 
-    next();
+    // Neither auth method provided or valid
+    warn('Unauthorized API request', { ip: req.ip, path: req.path });
+    return res.status(401).json({ error: 'Unauthorized' });
   };
 }

src/api/middleware/oauth.js

@@ -0,0 +1,18 @@
+/**
+ * OAuth2 JWT Middleware
+ * Verifies JWT tokens from Discord OAuth2 sessions
+ */
+
+import { handleOAuthJwt } from './oauthJwt.js';
+
+/**
+ * Creates middleware that verifies a JWT Bearer token from the Authorization header.
+ * Attaches the decoded user payload to req.user on success.
+ *
+ * @returns {import('express').RequestHandler} Express middleware function
+ */
+export function requireOAuth() {
+  return (req, res, next) => {
+    return handleOAuthJwt(req, res, next, { missingTokenError: 'No token provided' });
+  };
+}

src/api/middleware/oauthJwt.js

@@ -0,0 +1,56 @@
+/**
+ * Shared OAuth JWT middleware helpers
+ */
+
+import { error } from '../../logger.js';
+import { verifyJwtToken } from './verifyJwt.js';
+
+/**
+ * Extract Bearer token from Authorization header.
+ *
+ * @param {string|undefined} authHeader - Raw Authorization header value
+ * @returns {string|null} JWT token if present, otherwise null
+ */
+export function getBearerToken(authHeader) {
+  if (!authHeader?.startsWith('Bearer ')) {
+    return null;
+  }
+  return authHeader.slice(7);
+}
+
+/**
+ * Authenticate request using OAuth JWT Bearer token.
+ *
+ * @param {import('express').Request} req - Express request
+ * @param {import('express').Response} res - Express response
+ * @param {import('express').NextFunction} next - Express next callback
+ * @param {{ missingTokenError?: string }} [options] - Behavior options
+ * @returns {boolean} True if middleware chain has been handled, false if no Bearer token was provided and no missing-token error was requested
+ */
+export function handleOAuthJwt(req, res, next, options = {}) {
+  const token = getBearerToken(req.headers.authorization);
+  if (!token) {
+    if (options.missingTokenError) {
+      res.status(401).json({ error: options.missingTokenError });
+      return true;
+    }
+    return false;
+  }
+
+  const result = verifyJwtToken(token);
+  if (result.error) {
+    if (result.status === 500) {
+      error('SESSION_SECRET not configured — cannot verify OAuth token', {
+        ip: req.ip,
+        path: req.path,
+      });
+    }
+    res.status(result.status).json({ error: result.error });
+    return true;
+  }
+
+  req.authMethod = 'oauth';
+  req.user = result.user;
+  next();
+  return true;
+}

src/api/middleware/verifyJwt.js

@@ -0,0 +1,50 @@
+/**
+ * JWT Verification Helper
+ * Shared JWT verification logic used by both requireAuth and requireOAuth middleware
+ */
+
+import jwt from 'jsonwebtoken';
+import { getSessionToken } from '../utils/sessionStore.js';
+
+/**
+ * Lazily cached SESSION_SECRET — read from env on first call, then reused.
+ * Avoids per-request env lookup while remaining compatible with test stubs
+ * (vi.stubEnv sets process.env before the first call within each test).
+ * Call `_resetSecretCache()` in test teardown if needed.
+ */
+let _cachedSecret;
+
+/** @internal Reset the cached secret (for test teardown). */
+export function _resetSecretCache() {
+  _cachedSecret = undefined;
+}
+
+function getSecret() {
+  if (_cachedSecret === undefined) {
+    _cachedSecret = process.env.SESSION_SECRET || '';
+  }
+  return _cachedSecret;
+}
+
+/**
+ * Verify a JWT token and validate the associated server-side session.
+ *
+ * @param {string} token - The JWT Bearer token to verify
+ * @returns {{ user: Object } | { error: string, status: number }}
+ *   On success: `{ user }` with the decoded JWT payload.
+ *   On failure: `{ error, status }` with an error message and HTTP status code.
+ */
+export function verifyJwtToken(token) {
+  const secret = getSecret();
+  if (!secret) return { error: 'Session not configured', status: 500 };
+
+  try {
+    const decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });
+    if (!getSessionToken(decoded.userId)) {
+      return { error: 'Session expired or revoked', status: 401 };
+    }
+    return { user: decoded };
+  } catch {
+    return { error: 'Invalid or expired token', status: 401 };
+  }
+}