fix: enhance proxy trust configuration for Express app

Author: austenstone

README.md

@@ -16,6 +16,19 @@ GitHub Value is a free and open-source application designed to help measure the
 
 github-value will take you through setup the first time you run it. You can manually configure it by copying the [`.env.example`](./.env.example) file to `.env` and configure the environment variables.
 
+#### Security Configuration
+
+When deploying behind load balancers, reverse proxies, or CDNs, configure the `TRUST_PROXY` environment variable:
+
+- **Development**: `TRUST_PROXY=false` (default)
+- **Production behind single proxy**: `TRUST_PROXY=1` (recommended)
+- **Production behind multiple proxies**: `TRUST_PROXY=2` (or number of hops)
+- **High security**: `TRUST_PROXY=10.0.0.1,172.16.0.0/12` (specific IPs/ranges)
+
+This ensures accurate rate limiting and IP detection while maintaining security.
+
+📖 **[Full Proxy Configuration Guide](./docs/PROXY_CONFIGURATION.md)**
+
 <details>
   <summary>Docker Compose</summary>
 

backend/.env.example

@@ -5,6 +5,17 @@
 # This will be requested during the setup process but you can set it manually
 MONGODB_URI=mongodb://localhost:27017/github-value
 
+# Proxy Trust Configuration
+# Controls how Express handles X-Forwarded-For headers for rate limiting and IP detection
+# Options:
+#   - 'true': Trust all proxies (least secure, use only in development)
+#   - 'false': Don't trust any proxies (default for development)
+#   - '1': Trust first proxy hop (recommended for production behind single load balancer)
+#   - '2': Trust first 2 proxy hops (for multiple proxy layers)
+#   - '10.0.0.1,172.16.0.0/12': Comma-separated trusted proxy IPs/ranges (most secure)
+# If not set, defaults to '1' in production, 'false' in development
+# TRUST_PROXY=1
+
 # GitHub App configuration
 # This will be automatically populated during the setup process but you can set it manually
 # GITHUB_WEBHOOK_SECRET=

backend/src/app.ts

@@ -114,8 +114,33 @@ class App {
   }
 
   private setupExpress() {
-    // Trust proxy when running behind load balancers/reverse proxies
-    this.e.set('trust proxy', true);
+    // Configure proxy trust based on environment variable
+    // Common values: 'true', 'false', number (proxy hops), or comma-separated IPs
+    const trustProxy = process.env.TRUST_PROXY;
+    
+    if (trustProxy !== undefined) {
+      // Parse the environment variable
+      if (trustProxy === 'true') {
+        this.e.set('trust proxy', true);
+      } else if (trustProxy === 'false') {
+        this.e.set('trust proxy', false);
+      } else if (/^\d+$/.test(trustProxy)) {
+        // Number of proxy hops (e.g., "1", "2")
+        this.e.set('trust proxy', parseInt(trustProxy, 10));
+      } else if (trustProxy.includes(',')) {
+        // Comma-separated IP addresses/ranges
+        this.e.set('trust proxy', trustProxy.split(',').map(ip => ip.trim()));
+      } else {
+        // Single IP address or invalid value
+        logger.warn(`Invalid TRUST_PROXY value: ${trustProxy}. Using default (false).`);
+        this.e.set('trust proxy', false);
+      }
+    } else {
+      // Default behavior: trust proxy in production environments
+      const isProd = process.env.NODE_ENV === 'production';
+      this.e.set('trust proxy', isProd ? 1 : false);
+      logger.info(`TRUST_PROXY not set. Using default: ${isProd ? '1 (production)' : 'false (development)'}`);
+    }
 
     this.e.use(cors());
     this.e.use((req, res, next) => {