orbitchat 3.3.5 → 3.3.7

package/README.md

@@ -187,6 +187,8 @@ api:
   url: "http://localhost:3000"
 features:
   enableUpload: true
+server:
+  trustProxy: false
 ```
 
 Header logos (`header.logoUrl`, `header.logoUrlLight`, `header.logoUrlDark`) support:
@@ -209,6 +211,11 @@ Default logo fallback behavior:
   ```
   With this config, light/dark themes automatically use the default files from `public/`.
 
+Server/reverse proxy setting:
+- `server.trustProxy` maps directly to Express `app.set('trust proxy', value)`.
+- Default is `false`.
+- Set `server.trustProxy: 1` when ORBIT Chat is behind a single trusted reverse proxy.
+
 ### Environment Variables
 
 Adapter secrets are provided via:
@@ -262,9 +269,40 @@ If you've updated `orbitchat.yaml` but don't see changes:
 1. The CLI watches the YAML file and should restart automatically.
 2. Clear browser site data/localStorage for the app origin to ensure no stale session state is being used.
 
+### `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` (rate limit + reverse proxy)
+
+If you see a log like:
+
+```txt
+ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default).
+code: 'ERR_ERL_UNEXPECTED_X_FORWARDED_FOR'
+```
+
+this usually means ORBIT Chat is running behind a reverse proxy (Nginx, ingress controller, load balancer, Cloudflare, etc.) that adds `X-Forwarded-For`, but Express is still using the default `trust proxy = false`.
+
+Why this matters:
+1. The app still runs (this is a validation warning), but guest rate limiting may identify client IPs incorrectly.
+2. In the worst case, many users can be rate-limited as if they were a single client.
+
+How to prevent it:
+1. If you are behind a trusted reverse proxy, set this in `orbitchat.yaml`:
+   ```yaml
+   server:
+     trustProxy: 1
+   ```
+2. If you are not intentionally behind a proxy, remove unexpected `X-Forwarded-For` injection in your network path.
+3. As a temporary workaround, disable guest rate limiting in `orbitchat.yaml`:
+   ```yaml
+   guestLimits:
+     rateLimit:
+       enabled: false
+   ```
+
+Reference: https://express-rate-limit.github.io/ERR_ERL_UNEXPECTED_X_FORWARDED_FOR/
+
 ## Security
 
 - The browser **never** sees real API keys. The Express proxy maps adapter names to keys server-side.
 - `GET /api/adapters` only exposes non-secret metadata (name, description, notes, model) — never keys or backend URLs.
 - Keep `VITE_ADAPTER_KEYS` out of source control.
-- Run the proxy behind HTTPS in production.
+- Run the proxy behind HTTPS in production.

package/bin/orbitchat.js

@@ -253,6 +253,12 @@ function createServer(distPath, config, serverConfig = {}) {
   const adapters = loadAdaptersForProxy(config.adapters);
   const apiOnly = serverConfig.apiOnly || false;
   const localAssets = serverConfig.localAssets || {};
+  const trustProxy = serverConfig.trustProxy;
+
+  // For deployments behind reverse proxies, trust forwarded headers when configured.
+  if (typeof trustProxy !== 'undefined') {
+    app.set('trust proxy', trustProxy);
+  }
 
   if (apiOnly) {
     const allowedOrigin = serverConfig.corsOrigin || '*';
@@ -463,7 +469,12 @@ function main() {
   }
 
   const distPath = path.join(__dirname, '..', 'dist');
-  const app = createServer(distPath, config, { ...serverConfig, rateLimit: yamlObj?.guestLimits?.rateLimit, localAssets });
+  const app = createServer(distPath, config, {
+    ...serverConfig,
+    rateLimit: yamlObj?.guestLimits?.rateLimit,
+    trustProxy: yamlObj?.server?.trustProxy,
+    localAssets
+  });
 
   const server = app.listen(serverConfig.port, serverConfig.host, () => {
     console.debug(`🚀 ORBIT Chat is running at http://${serverConfig.host}:${serverConfig.port}`);