feat: REST API layer for web dashboard

.env.example

@@ -44,15 +44,20 @@ NEXTAUTH_SECRET=your_nextauth_secret
 # Docker Compose overrides this to http://localhost:3000 automatically.
 NEXTAUTH_URL=http://localhost:3000
 
+# Bot REST API port (optional — default: 3001)
+BOT_API_PORT=3001
+
 # Bot API URL for web dashboard → bot communication (required for web dashboard)
-# Not yet implemented — the bot does not expose an HTTP API yet (see Issue #29).
 # Docker Compose overrides this when the bot API is available.
-# BOT_API_URL=http://localhost:3001
+BOT_API_URL=http://localhost:3001
 
 # Shared secret for bot ↔ web dashboard API authentication
 # Required when running the web dashboard.
 BOT_API_SECRET=your_bot_api_secret
 
+# Dashboard URL for CORS origin (required for web dashboard)
+DASHBOARD_URL=http://localhost:3000
+
 # Discord client ID exposed to browser (required for web dashboard)
 NEXT_PUBLIC_DISCORD_CLIENT_ID=your_discord_client_id
 

package.json

@@ -19,6 +19,7 @@
   "dependencies": {
     "discord.js": "^14.25.1",
     "dotenv": "^17.3.1",
+    "express": "^5.2.1",
     "mem0ai": "^2.2.2",
     "pg": "^8.18.0",
     "winston": "^3.19.0",
@@ -36,6 +37,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.0",
     "@vitest/coverage-v8": "^4.0.18",
+    "supertest": "^7.2.2",
     "vitest": "^4.0.18"
   }
 }

src/api/index.js

@@ -0,0 +1,19 @@
+/**
+ * API Router Aggregation
+ * Mounts all v1 API route groups
+ */
+
+import { Router } from 'express';
+import { requireAuth } from './middleware/auth.js';
+import guildsRouter from './routes/guilds.js';
+import healthRouter from './routes/health.js';
+
+const router = Router();
+
+// Health check — public (no auth required)
+router.use('/health', healthRouter);
+
+// Guild routes — require API secret
+router.use('/guilds', requireAuth(), guildsRouter);
+
+export default router;

src/api/middleware/auth.js

@@ -0,0 +1,36 @@
+/**
+ * Authentication Middleware
+ * Validates requests using a shared API secret
+ */
+
+import crypto from 'node:crypto';
+import { warn } from '../../logger.js';
+
+/**
+ * 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.
+ *
+ * @returns {import('express').RequestHandler} Express middleware function
+ */
+export function requireAuth() {
+  return (req, res, next) => {
+    const secret = req.headers['x-api-secret'];
+    const expected = process.env.BOT_API_SECRET;
+
+    if (!expected) {
+      warn('BOT_API_SECRET not configured — rejecting API request');
+      return res.status(401).json({ error: 'API authentication not configured' });
+    }
+
+    if (
+      !secret ||
+      secret.length !== expected.length ||
+      !crypto.timingSafeEqual(Buffer.from(secret), Buffer.from(expected))
+    ) {
+      warn('Unauthorized API request', { ip: req.ip, path: req.path });
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+
+    next();
+  };
+}

src/api/middleware/rateLimit.js

@@ -0,0 +1,52 @@
+/**
+ * Rate Limiting Middleware
+ * Simple in-memory per-IP rate limiter with no external dependencies
+ */
+
+/**
+ * Creates rate-limiting middleware that tracks requests per IP address.
+ * Returns 429 JSON error when the limit is exceeded.
+ *
+ * @param {Object} [options] - Rate limiter configuration
+ * @param {number} [options.windowMs=900000] - Time window in milliseconds (default: 15 minutes)
+ * @param {number} [options.max=100] - Maximum requests per window per IP (default: 100)
+ * @returns {import('express').RequestHandler} Express middleware function
+ */
+export function rateLimit({ windowMs = 15 * 60 * 1000, max = 100 } = {}) {
+  /** @type {Map<string, { count: number, resetAt: number }>} */
+  const clients = new Map();
+
+  // Periodically clean up expired entries to prevent memory leaks
+  const cleanup = setInterval(() => {
+    const now = Date.now();
+    for (const [ip, entry] of clients) {
+      if (now >= entry.resetAt) {
+        clients.delete(ip);
+      }
+    }
+  }, windowMs);
+
+  // Allow the timer to not prevent process exit
+  cleanup.unref();
+
+  return (req, res, next) => {
+    const ip = req.ip;
+    const now = Date.now();
+
+    let entry = clients.get(ip);
+    if (!entry || now >= entry.resetAt) {
+      entry = { count: 0, resetAt: now + windowMs };
+      clients.set(ip, entry);
+    }
+
+    entry.count++;
+
+    if (entry.count > max) {
+      const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+      res.set('Retry-After', String(retryAfter));
+      return res.status(429).json({ error: 'Too many requests, please try again later' });
+    }
+
+    next();
+  };
+}