Add Option for The 'X-Forwarded-For' header for Express 'trust proxy' #4535
Description
Is your feature request related to a problem? Please describe.
Persistent validation errors in my Z-Wave logs when Z-Wave starts up. The error ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false indicates that the internal Express server is ignoring the forwarded headers. Adding an option to allow the trust proxy equal to true or false. I assume this is related to Eero or something else causing Z-Wave UI to complain.
Describe the solution you'd `like
Below is the technical implementation logic proposed for this change:
- Model Changes (lib/Settings.ts)
Add trustProxy to the GeneralSettings interface and initialize it:
export interface GeneralSettings {
// ... existing settings
trustProxy: boolean;
}
// In the constructor/defaults:
this.general = {
// ... existing defaults
trustProxy: false,
};
- Backend Server Integration (lib/app.ts)
Inject the setting into the Express app instance:
// Configure Express to trust proxy headers if enabled in settings or env
if (settings.general.trustProxy || process.env.TRUST_PROXY === 'true' || process.env.TRUST_PROXY === '1') {
app.set('trust proxy', true);
}
- Frontend UI (src/views/Settings.vue)
Expose the toggle to the user:
<v-col cols="12" sm="6">
<v-switch
v-model="settings.general.trustProxy"
label="Trust Proxy"
hint="Enable if running behind a reverse proxy to correctly handle X-Forwarded-For headers"
persistent-hint
></v-switch>
</v-col>
Describe alternatives you've considered
I have considered setting the TRUST_PROXY environment variable directly; however, this is not easily accessible for users running the official Home Assistant Add-on, as the wrapper does not expose a general environment variable configuration field. A UI-based toggle is a much more robust and user-friendly solution for managed container environments.
Additional context
This issue frequently appears for users of the Home Assistant Z-Wave JS UI add-on. Enabling this feature will allow the backend to correctly identify remote client IPs, resolving the logs and ensuring security features like rate-limiting function as intended. I'm not sure if others receive this error. I tired finding a way to toggle the trust setting.
Here is the actual error message I received every time I restart the Z-Wave JS Add-on (App)
ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default). This could indicate a misconfiguration which would prevent express-rate-limit from accurately identifying users. See https://express-rate-limit.github.io/ERR_ERL_UNEXPECTED_X_FORWARDED_FOR/ for more information.
at Object.xForwardedForHeader (file:///opt/node_modules/express-rate-limit/dist/index.mjs:157:13)
at Object.wrappedValidations.<computed> [as xForwardedForHeader] (file:///opt/node_modules/express-rate-limit/dist/index.mjs:369:22)
at Object.keyGenerator (file:///opt/node_modules/express-rate-limit/dist/index.mjs:630:20)
at file:///opt/node_modules/express-rate-limit/dist/index.mjs:682:32
at file:///opt/node_modules/express-rate-limit/dist/index.mjs:663:5 {
code: 'ERR_ERL_UNEXPECTED_X_FORWARDED_FOR',
help: 'https://express-rate-limit.github.io/ERR_ERL_UNEXPECTED_X_FORWARDED_FOR/'
}
The reason I didn't just do a pull request is because I want to validate from the community that this is the correct implementation and if other are getting this error. I assume its Eero Plus on the backend. I assume this is what the issue is. I mostly just wanted to try and enable the trust setting to see if the error would go away but I don't have a way to do that. Or maybe this is the issue. jshttp/proxy-addr#20