477b856519
* [PM-31696] Add reverse proxy emulator for load balancer cookie testing Adds a local dev/QA tool that emulates AWS ELB authentication without real AWS infrastructure. It gates all traffic behind a BitwardenLoadBalancerCookie and serves a simple auth page to issue it, enabling testing of the load balancer cookie bootstrap flow (PM-27124). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * [PM-31696] Replace http-proxy with Node.js built-ins http-proxy has not been published in 6 years and uses the deprecated util._extend API. Replace it with https.request + piping for HTTP and tls.connect + socket piping for WebSocket, removing the dependency and the --no-deprecation workaround entirely. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * [PM-31696] Fix TLS verification for public backends Extend the default CA bundle with the self-signed cert instead of replacing it, so both localhost dev servers and public backends (e.g. vault.bitwarden.com) are trusted without --insecure. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * [PM-31696] Add cookie rotation via R keypress Press R while the proxy is running to increment the cookie generation, immediately invalidating all existing session cookies and forcing clients to re-authenticate on their next request. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: tweak docs * feat: improve error messages * docs: update readme --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
3.6 KiB
Reverse Proxy Emulator
A local development tool that emulates AWS ELB authentication without real AWS infrastructure. It sits in front of a Bitwarden server, gates all traffic behind a BitwardenLoadBalancerCookie, and serves a simple auth page to issue that cookie.
How it works
- Bypass paths (
/api/config,/api/cookie-vendor) are forwarded to the backend unconditionally, because the client needs them before it can authenticate. - All other requests are checked for the
BitwardenLoadBalancerCookie. Requests that carry the cookie are proxied to the backend. - Requests without the cookie are redirected to
/_elb-auth, which serves a page with a "Continue" button. Clicking the button sets the cookie in the browser and redirects back to the original URL.
WebSocket connections (used by the SignalR notification hub) are also gated on the cookie and proxied through.
Quick start
npm run dev:reverse-proxy
Then configure your Bitwarden client (desktop, browser extension, or web vault) to use https://localhost:8000 as its server URL.
TLS certificates
The proxy serves HTTPS using the same TLS certificate as the web vault dev server (apps/web/dev-server.shared.pem). If you have a dev-server.local.pem in that directory, it takes precedence (same logic as the web vault's webpack config).
For the proxy to work, the certificate must be trusted by your OS or browser. If you have already trusted the certificate for the web vault dev server, no additional setup is needed.
On macOS, open Keychain Access, find the localhost certificate, double-click it, expand Trust, and set When using this certificate to Always Trust.
The same certificate is also used to verify the backend connection. Public backends (e.g. vault.bitwarden.com) are verified against the system CA bundle as normal. If the backend uses a different self-signed certificate that is not in your trust store, pass --insecure to skip TLS verification for the backend connection, this is not tested so it might not work in all cases.
Configuration
All options can be set via environment variable or CLI argument. CLI arguments take precedence.
| CLI argument | Environment variable | Default |
|---|---|---|
--port |
RPE_PORT |
8000 |
--backend |
RPE_BACKEND_URL |
https://localhost:8080 |
--cookie-name |
RPE_COOKIE_NAME |
BitwardenLoadBalancerCookie |
--cookie-max-age |
RPE_COOKIE_MAX_AGE |
86400 (24 h, in seconds) |
--insecure |
(flag only) | false |
Examples
Point at a remote backend:
npm run dev:reverse-proxy -- --backend https://vault.bitwarden.com
Use a different port and cookie TTL:
RPE_PORT=9000 RPE_COOKIE_MAX_AGE=3600 npm run dev:reverse-proxy
Cookie rotation
Press R while the proxy is running to rotate the cookie and force all clients to re-authenticate on their next request. This is useful for testing the re-authentication flow without waiting for the cookie TTL to expire.
Client configuration
Set the custom server URL in the Bitwarden client to https://localhost:8000 (or whatever port you configured). The client will communicate through the proxy just as it would with a real load-balanced environment.
Notes
- Port conflicts: if port 8000 is already in use, change it with
--portorRPE_PORT. - Node version: requires Node 22.12+ (the
--experimental-strip-typesflag used to run the script is stable from 22.12 onward).