Merge pull request #23 from HarperFast/debug-limit

Limit debug endpoint access by allowlist controlled IPs when debug is enabled

Author: heskew

docs/configuration.md

@@ -300,7 +300,44 @@ When `debug: true` is enabled, additional endpoints are available:
 - `GET /oauth/{provider}/user` - Current user info and token status
 - `GET /oauth/{provider}/refresh` - Trigger token refresh
 
-**Warning:** Never enable debug mode in production environments.
+### Security: IP-Based Access Control
+
+**By default, debug endpoints are only accessible from localhost** (`127.0.0.1` and `::1`). This prevents unauthorized access to sensitive debugging information.
+
+To allow access from other IPs, set the `DEBUG_ALLOWED_IPS` environment variable:
+
+```bash
+# Allow single IP
+DEBUG_ALLOWED_IPS=192.168.1.100
+
+# Allow multiple IPs (comma-separated)
+DEBUG_ALLOWED_IPS=192.168.1.100,192.168.1.101,10.0.0.50
+
+# Allow IP range using prefix matching (e.g., all 10.0.0.x)
+DEBUG_ALLOWED_IPS=10.0.0.
+
+# Deny all access (empty string)
+DEBUG_ALLOWED_IPS=
+```
+
+**Access denial response:**
+
+```json
+{
+	"error": "Access forbidden",
+	"message": "Debug endpoints are only accessible from allowed IPs.",
+	"hint": "Set DEBUG_ALLOWED_IPS environment variable to allow access from your IP. Defaults to localhost only (127.0.0.1,::1)."
+}
+```
+
+**Security best practices:**
+
+- Keep debug mode disabled in production
+- Use IP allowlist when debug mode must be enabled remotely
+- Monitor access logs for unauthorized attempts
+- Regular endpoints (`/login`, `/callback`, `/logout`) are not affected by IP restrictions
+
+**Warning:** Never enable debug mode in production environments without strict IP controls.
 
 ## Complete Example
 

src/lib/resource.ts

@@ -93,6 +93,65 @@ export class OAuthResource extends Resource {
 		return false;
 	}
 
+	/**
+	 * Check if a request is allowed to access debug endpoints
+	 * Uses IP allowlist for security (defaults to localhost only)
+	 *
+	 * @param request - The incoming request
+	 * @param logger - Optional logger for access tracking
+	 * @returns true if access is allowed, false otherwise
+	 */
+	static checkDebugAccess(request: Request, logger?: Logger): boolean {
+		// Get IP allowlist from environment variable or use localhost-only default
+		// Use ?? to allow empty string (which denies all access)
+		const DEBUG_ALLOWED_IPS = process.env.DEBUG_ALLOWED_IPS ?? '127.0.0.1,::1';
+		const allowedIps = DEBUG_ALLOWED_IPS.split(',').map((ip) => ip.trim());
+		const clientIp = request.ip || '';
+
+		// Check if client IP matches any allowed IP
+		let ipAllowed = false;
+		for (const allowed of allowedIps) {
+			// Exact match
+			if (allowed === clientIp) {
+				ipAllowed = true;
+				break;
+			}
+			// Simple prefix match for CIDR-like patterns (e.g., "10.0.0." matches "10.0.0.1")
+			if (allowed.endsWith('.') && clientIp.startsWith(allowed)) {
+				ipAllowed = true;
+				break;
+			}
+		}
+
+		// Log access attempt
+		if (ipAllowed) {
+			logger?.info?.('OAuth debug endpoint accessed', {
+				ip: clientIp,
+			});
+		} else {
+			logger?.warn?.('OAuth debug endpoint access denied - unauthorized IP', {
+				ip: clientIp,
+				allowedIps,
+			});
+		}
+
+		return ipAllowed;
+	}
+
+	/**
+	 * Build forbidden response for unauthorized debug access
+	 */
+	static forbiddenResponse(): any {
+		return {
+			status: 403,
+			body: {
+				error: 'Access forbidden',
+				message: 'Debug endpoints are only accessible from allowed IPs.',
+				hint: 'Set DEBUG_ALLOWED_IPS environment variable to allow access from your IP. Defaults to localhost only (127.0.0.1,::1).',
+			},
+		};
+	}
+
 	/**
 	 * Build the standard 404 response
 	 */
@@ -209,6 +268,13 @@ export class OAuthResource extends Resource {
 			return OAuthResource.notFoundResponse();
 		}
 
+		// If debug mode is enabled and this is a debug-only route, check IP allowlist
+		if (debugMode && OAuthResource.isDebugOnlyRoute(route)) {
+			if (!OAuthResource.checkDebugAccess(request, logger)) {
+				return OAuthResource.forbiddenResponse();
+			}
+		}
+
 		// Special case: /oauth/test without provider
 		if (providerName === 'test' && !action) {
 			return handleTestPage(logger);

src/types.ts

@@ -261,6 +261,8 @@ export interface Request extends IncomingMessage {
 	user?: User | string;
 	session?: Session;
 	headers: IncomingMessage['headers'];
+	/** Client IP address */
+	ip?: string;
 }
 
 /**

test/lib/OAuthResource.responses.test.js

@@ -6,9 +6,10 @@
 import { describe, it, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 
-// Note: Bun uses test/bun-preload.js to mock the harperdb module
-// Node.js will load the real harperdb module, which may trigger async
-// native module loading that continues after tests complete. This is harmless.
+// Mock Harper's Resource class
+global.Resource = class {
+	static loadAsInstance = false;
+};
 
 import { OAuthResource } from '../../dist/lib/resource.js';