Tighten health endpoint hardening

SECURITY.md

@@ -74,7 +74,8 @@ KoalaSync's security is grounded in its architecture:
 
 - **RAM-only relay**: No database, no persistent logs. All session data evaporates on disconnect.
 - **Keyed SHA-256 room password hashes**: Plaintext passwords are never stored. Room passwords are held only as in-memory HMAC-SHA256 hashes for the short room lifetime, with brute-force protection: 5 attempts → 15-minute IP lockout.
-- **Rate limiting**: Connection rate (IP-based, 60s window) and event rate (per-socket, 10s window).
+- **Rate limiting**: Connection rate (IP-based, 60s window), health endpoint rate (20 requests/minute/IP), wrong admin-metrics bearer attempts (5 requests/minute/IP), and event rate (per-socket, 10s window).
+- **Reverse proxy boundary**: The relay trusts one proxy hop for client IP detection. In production, keep the Node server reachable only through Caddy or another trusted reverse proxy.
 - **URL-hash credential isolation**: Invitation credentials live in the URL fragment (`#join:...`) — never sent to the web server.
 - **Strict CSP**: `default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'`.
 - **No third-party requests**: Zero CDNs, fonts, analytics, or external scripts.

docker-compose.caddy.example.yml

@@ -9,7 +9,7 @@ services:
       - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
       - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
       - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
-      - ADMIN_METRICS_TOKEN=                                                               # Optional: enables aggregate-only /health metrics with Bearer auth
+      - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
     pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
     networks:                                                                              # Attaches the service to the networks listed below
       - caddy_net                                                                          # Joins the pre-existing Caddy network for reverse proxying

docker-compose.ip.example.yml

@@ -11,7 +11,7 @@ services:
       - MIN_VERSION=1.0.0                                                                  # Minimum client version allowed to connect
       - MAX_ROOMS=100                                                                      # Maximum number of rooms that can exist
       - MAX_PEERS_PER_ROOM=25                                                              # Maximum number of peers allowed per room
-      - ADMIN_METRICS_TOKEN=                                                               # Optional: enables aggregate-only /health metrics with Bearer auth
+      - ADMIN_METRICS_TOKEN=                                                               # Optional: 32+ char random token for aggregate-only /health metrics
     pids_limit: 2048                                                                       # Limits the container to 2048 process IDs for safety
     networks:                                                                              # Attaches the service to the networks listed below
       bond0_network:                                                                       # Network name as referenced by the service

docs/ARCHITECTURE.md

@@ -58,7 +58,7 @@ KoalaSync uses a megaphone routing approach to minimize server logic:
 ## 7. Security & Stability
 - **Service Worker Lifecycle**: Uses `chrome.alarms` (30s interval) to prevent the Manifest V3 service worker from suspending while in an active room. On wake, runtime state is restored from `chrome.storage.session` via `ensureState()`.
 - **Reconnect Visualization**: Badge shows "..." (orange) during reconnect. Popup displays "Reconnecting..." with attempt counter.
-- **Rate Limiting**: Server-side per-socket and per-IP rate limits to prevent sync-spamming or DoS. Real client IP extracted via `x-forwarded-for` header behind proxies/CDNs.
+- **Rate Limiting**: Server-side per-socket and per-IP rate limits to prevent sync-spamming or simple DoS. Public health endpoints are limited to 20 requests/minute/IP, wrong admin-metrics bearer attempts to 5 requests/minute/IP, and room discovery to one request every 10 seconds per socket. Real client IP is taken from the trusted reverse proxy hop, so the Node port must stay private behind Caddy or another trusted proxy.
 - **Room Creation Lock**: Per-room mutex prevents race conditions when multiple peers join a new room simultaneously.
 - **CORS**: Allows `chrome-extension://` origins for WebSocket fallback compatibility.
 - **Message Buffer**: `maxHttpBufferSize` set to 4KB to accommodate large `JOIN_ROOM` payloads.

scripts/test-server-ops.mjs

@@ -2,7 +2,8 @@ import assert from 'node:assert/strict';
 import {
   buildHealthPayload,
   checkCooldown,
-  isAdminMetricsAuthorized
+  isAdminMetricsAuthorized,
+  isAdminMetricsTokenStrong
 } from '../server/ops.js';
 
 const missingAuth = isAdminMetricsAuthorized(undefined, 'secret-token');
@@ -17,6 +18,14 @@ assert.equal(correctAuth, true, 'correct bearer token should authorize metrics')
 const disabledAuth = isAdminMetricsAuthorized('Bearer secret-token', '');
 assert.equal(disabledAuth, false, 'empty admin token disables admin metrics');
 
+assert.equal(isAdminMetricsTokenStrong(''), true, 'empty admin token is allowed because metrics stay disabled');
+assert.equal(isAdminMetricsTokenStrong('short-token'), false, 'short admin token should be reported as weak');
+assert.equal(
+  isAdminMetricsTokenStrong('a'.repeat(32)),
+  true,
+  'admin token with at least 32 characters should be considered strong'
+);
+
 const cooldowns = new Map();
 assert.equal(checkCooldown(cooldowns, 'socket-1', 10_000, 100_000), true, 'first cooldown check passes');
 assert.equal(checkCooldown(cooldowns, 'socket-1', 10_000, 105_000), false, 'second cooldown check inside window fails');
@@ -33,7 +42,7 @@ const basicHealth = buildHealthPayload({
   now: 1234,
   uptime: 99,
   memoryUsage: () => ({ rss: 10, heapUsed: 5, heapTotal: 8 }),
-  rateLimitSizes: { connections: 1, events: 2, health: 3, authFailures: 4, roomList: 5 }
+  rateLimitSizes: { connections: 1, events: 2, health: 3, adminMetricsAuth: 4, authFailures: 5, roomList: 6 }
 });
 
 assert.deepEqual(
@@ -49,7 +58,7 @@ const adminHealth = buildHealthPayload({
   now: 1234,
   uptime: 99,
   memoryUsage: () => ({ rss: 10, heapUsed: 5, heapTotal: 8 }),
-  rateLimitSizes: { connections: 1, events: 2, health: 3, authFailures: 4, roomList: 5 }
+  rateLimitSizes: { connections: 1, events: 2, health: 3, adminMetricsAuth: 4, authFailures: 5, roomList: 6 }
 });
 
 assert.equal(adminHealth.peers, 5, 'admin metrics should include aggregate peer count');
@@ -59,7 +68,7 @@ assert.equal(adminHealth.maxPeersInRoom, 3, 'admin metrics should include max ro
 assert.deepEqual(adminHealth.memory, { rss: 10, heapUsed: 5, heapTotal: 8 }, 'admin metrics should expose process memory');
 assert.deepEqual(
   adminHealth.rateLimitEntries,
-  { connections: 1, events: 2, health: 3, authFailures: 4, roomList: 5 },
+  { connections: 1, events: 2, health: 3, adminMetricsAuth: 4, authFailures: 5, roomList: 6 },
   'admin metrics should expose aggregate rate-limit map sizes'
 );
 

server/.env.example

@@ -3,4 +3,5 @@ MIN_VERSION=1.0.0
 MAX_ROOMS=1000
 MAX_PEERS_PER_ROOM=25
 # Optional: enables aggregate-only admin metrics on /health with Authorization: Bearer <token>
+# Use a long random token, 32+ characters recommended.
 ADMIN_METRICS_TOKEN=

server/README.md

@@ -17,13 +17,16 @@ MAX_ROOMS=1000
 MAX_PEERS_PER_ROOM=25
 MIN_VERSION=1.0.0
 # Optional: enables aggregate-only admin metrics on /health with Authorization: Bearer <token>
+# Use a long random token, 32+ characters recommended.
 ADMIN_METRICS_TOKEN=
 ```
 
 ### Health & Metrics
-`GET /` and `GET /health` are IP-rate-limited. By default `/health` returns only basic service status, uptime, room count, connection count, and a timestamp.
+`GET /` and `GET /health` are IP-rate-limited to 20 requests per minute per client IP. By default `/health` returns only basic service status, uptime, room count, connection count, and a timestamp.
 
-If `ADMIN_METRICS_TOKEN` is set, requests with `Authorization: Bearer <token>` receive additional aggregate metrics such as total peers, average peers per room, max room size, active lobby count, rate-limit map sizes, and process memory usage. The metrics response does not include room IDs, peer IDs, usernames, IP addresses, media titles, or other user-level data.
+If `ADMIN_METRICS_TOKEN` is set, requests with `Authorization: Bearer <token>` receive additional aggregate metrics such as total peers, average peers per room, max room size, active lobby count, rate-limit map sizes, and process memory usage. Wrong admin bearer attempts are separately limited to 5 requests per minute per client IP. The metrics response does not include room IDs, peer IDs, usernames, IP addresses, media titles, or other user-level data.
+
+Use a long random `ADMIN_METRICS_TOKEN` of at least 32 characters. Shorter configured tokens still work, but the server logs a startup warning.
 
 ### Docker (Recommended)
 The server is available as a pre-built image on GHCR.
@@ -45,7 +48,9 @@ npm start
 
 ## Security
 - **Rate Limiting**: IP-based connection limits and socket-based event limits.
+- **Health Endpoint Throttle**: `GET /` and `GET /health` are limited to 20 requests per minute per IP, with stricter throttling for wrong admin bearer attempts.
 - **Room Discovery Throttle**: Room-list refreshes are rate-limited server-side to one request every 10 seconds per socket.
 - **Token Handshake**: Requires a valid token defined in the root `shared/constants.js`.
 - **Single Source of Truth**: The server imports constants directly from the root `shared/` directory.
 - **In-Memory**: Rooms are automatically pruned after 2 hours of inactivity.
+- **Reverse Proxy Boundary**: The server trusts one reverse proxy hop for client IP detection. Keep the Node port private/firewalled so clients can only reach it through Caddy or another trusted proxy.

server/index.js

@@ -4,7 +4,12 @@ import { Server } from 'socket.io';
 import crypto from 'crypto';
 import dotenv from 'dotenv';
 import { EVENTS, OFFICIAL_SERVER_TOKEN, PROTOCOL_VERSION } from '../shared/constants.js';
-import { buildHealthPayload, checkCooldown, isAdminMetricsAuthorized } from './ops.js';
+import {
+    buildHealthPayload,
+    checkCooldown,
+    isAdminMetricsAuthorized,
+    isAdminMetricsTokenStrong
+} from './ops.js';
 
 dotenv.config();
 
@@ -20,6 +25,12 @@ const MAX_PEERS_PER_ROOM = parseInt(process.env.MAX_PEERS_PER_ROOM) || 25;
 const MIN_VERSION = process.env.MIN_VERSION || '1.0.0';
 const ADMIN_METRICS_TOKEN = process.env.ADMIN_METRICS_TOKEN || '';
 const ROOM_LIST_COOLDOWN_MS = 10000;
+const HEALTH_RATE_LIMIT_PER_MINUTE = 20;
+const ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE = 5;
+
+if (!isAdminMetricsTokenStrong(ADMIN_METRICS_TOKEN)) {
+    console.warn('[SECURITY] ADMIN_METRICS_TOKEN is set but shorter than 32 characters. Use a long random token.');
+}
 
 const app = express();
 app.set('trust proxy', 1); // For real client IP through reverse proxy
@@ -38,7 +49,11 @@ app.get('/health', (req, res) => {
     if (!checkHealthRate(clientIp)) {
         return res.status(429).json({ error: 'Rate limited' });
     }
-    const includeMetrics = isAdminMetricsAuthorized(req.get('authorization'), ADMIN_METRICS_TOKEN);
+    const authHeader = req.get('authorization');
+    const includeMetrics = isAdminMetricsAuthorized(authHeader, ADMIN_METRICS_TOKEN);
+    if (ADMIN_METRICS_TOKEN && authHeader && !includeMetrics && !checkAdminMetricsAuthRate(clientIp)) {
+        return res.status(429).json({ error: 'Rate limited' });
+    }
     res.json(buildHealthPayload({
         rooms,
         connections: io.engine?.clientsCount ?? 0,
@@ -48,6 +63,7 @@ app.get('/health', (req, res) => {
             connections: connectionCounts.size,
             events: eventCounts.size,
             health: healthCounts.size,
+            adminMetricsAuth: adminMetricsAuthCounts.size,
             authFailures: failedAuthAttempts.size,
             roomList: roomListCooldowns.size
         }
@@ -149,6 +165,7 @@ setInterval(() => {
 
 const eventCounts = new Map(); // socketId -> { count, resetTime }
 const healthCounts = new Map(); // ip -> { count, resetTime }
+const adminMetricsAuthCounts = new Map(); // ip -> { count, resetTime }
 const roomListCooldowns = new Map(); // socketId -> last allowed timestamp
 
 // Clean up connection counts and event counts to prevent memory leak
@@ -169,6 +186,11 @@ setInterval(() => {
             healthCounts.delete(ip);
         }
     }
+    for (const [ip, entry] of adminMetricsAuthCounts.entries()) {
+        if (now > entry.resetTime) {
+            adminMetricsAuthCounts.delete(ip);
+        }
+    }
     for (const [socketId] of roomListCooldowns.entries()) {
         if (!io.sockets.sockets.has(socketId)) {
             roomListCooldowns.delete(socketId);
@@ -200,7 +222,16 @@ function checkHealthRate(ip) {
     if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
     entry.count++;
     healthCounts.set(ip, entry);
-    return entry.count <= 60;
+    return entry.count <= HEALTH_RATE_LIMIT_PER_MINUTE;
+}
+
+function checkAdminMetricsAuthRate(ip) {
+    const now = Date.now();
+    const entry = adminMetricsAuthCounts.get(ip) || { count: 0, resetTime: now + 60000 };
+    if (now > entry.resetTime) { entry.count = 0; entry.resetTime = now + 60000; }
+    entry.count++;
+    adminMetricsAuthCounts.set(ip, entry);
+    return entry.count <= ADMIN_METRICS_AUTH_RATE_LIMIT_PER_MINUTE;
 }
 
 /**

server/ops.js

@@ -26,6 +26,10 @@ export function isAdminMetricsAuthorized(authHeader, adminToken) {
     return crypto.timingSafeEqual(expectedBuffer, providedBuffer);
 }
 
+export function isAdminMetricsTokenStrong(adminToken, minLength = 32) {
+    return !adminToken || (typeof adminToken === 'string' && adminToken.length >= minLength);
+}
+
 export function buildHealthPayload({
     rooms,
     connections,
@@ -64,6 +68,7 @@ export function buildHealthPayload({
             connections: rateLimitSizes.connections || 0,
             events: rateLimitSizes.events || 0,
             health: rateLimitSizes.health || 0,
+            adminMetricsAuth: rateLimitSizes.adminMetricsAuth || 0,
             authFailures: rateLimitSizes.authFailures || 0,
             roomList: rateLimitSizes.roomList || 0
         },