fix: key login backoff on the declared proxy header only and cap total failures

Security audit follow-up, batch 3. `clientKey` (the identity the admin login
and approval-link backoffs bucket on) used to believe CF-Connecting-IP and
the FIRST X-Forwarded-For hop for any request on a loopback socket — which is
every request behind nginx, caddy, cloudflared or ssh -L. A caller could mint
a fresh bucket per request by writing its own header: unlimited online
password guessing plus a free scrypt per attempt.

- New setting `trustProxy` (Settings → Connection → "Behind a reverse proxy";
  env CG_TRUST_PROXY; the setting wins): "" trusts nothing (the socket is the
  client), "cloudflare" reads CF-Connecting-IP only, "xff" reads the LAST
  X-Forwarded-For hop (the proxy's, never the client's first one). Legacy
  CG_TRUST_PROXY=1 maps to "xff"; unknown values trust nothing and the admin
  API refuses them with 400.
- createLoginLimiter gains a key-independent global cap (default 50 failures
  per 10 minutes → every attempt waits the maximum delay until the window
  drains), injectable for tests and switchable off.
- The /approve limiter inherits both through the shared helper. Nothing else
  authorizes on forwarded headers; the Secure-cookie decision still reads
  x-forwarded-proto (it only ever makes the cookie stricter).
- docs/OPERATIONS.md and INSTALL.md: declare the proxy, or all remote logins
  share one backoff bucket.

Tests: web-security (clientKey per mode, settings/env precedence, global
cap), settings-save-version (route validation + UI wiring),
approval-links (end-to-end through the approve router with and without a
declared proxy). FEATURES, TEST-PLAN, CHANGELOG updated.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Tiberiu Socaci <tsocaci@makeitfuture.com>

Author: tbiyss

CHANGELOG.md

@@ -18,6 +18,13 @@ product overview.
 
 ## Unreleased
 
+- Security hardening (audit batch 3): the login and approval-link backoff key each client on the
+  header of the proxy the operator declares (new Settings → Connection → *Behind a reverse proxy*,
+  `trustProxy` / `CG_TRUST_PROXY`: none, `cloudflare`, `xff`) instead of trusting any forwarded
+  header that arrives on a loopback socket, and a global cap (50 failures per 10 minutes) bounds
+  password guessing from fresh buckets. Deployments behind a proxy should set the new option;
+  without it remote logins share one backoff bucket.
+
 - Supply new installations with Astra, Sol, Terra, Fable, Opus and Sonnet (`:sonet`) shortcuts
   using the newest supported stable family versions. Preserve customized lists and thread pins.
 

FEATURES.md

@@ -1,5 +1,22 @@
 # ChannelGate — Features
 
+## Login backoff behind a reverse proxy (security audit batch 3)
+
+- The admin login backoff and the approval-link token backoff key each client on the header of
+  the proxy the operator DECLARED, never on a header a loopback socket happened to carry. Settings
+  → Connection → *Behind a reverse proxy* (`trustProxy` in settings.json, `CG_TRUST_PROXY` in
+  `.env`; the setting wins) takes `""` (none: the connecting address is the client),
+  `cloudflare` (`CF-Connecting-IP`, which cloudflared overwrites on every request) or `xff` (the
+  LAST `X-Forwarded-For` hop, the one the trusted proxy appended, never the first, which the client
+  typed). The legacy `CG_TRUST_PROXY=1` means `xff`. An unknown value trusts nothing; the admin API
+  refuses it with 400.
+- A global failure cap bounds guessing independently of the key: more than 50 failed attempts in
+  ten minutes across all clients puts every login on the maximum delay until the window drains, so
+  a caller who can mint fresh buckets (a botnet, or a forged header behind a misdeclared proxy) is
+  still bounded, and so is the scrypt work an unauthenticated caller can cause.
+- Documented in `docs/OPERATIONS.md` → Reverse proxies and tunnels and in INSTALL.md: without the
+  setting, all remote logins behind a proxy share one backoff bucket.
+
 ## Admin access to Slack controls
 
 - Current organization admins can open Files, Variables, Settings and legacy menu Resume controls

INSTALL.md

@@ -230,8 +230,10 @@ For a shared workflow, start with one dedicated channel and one representative t
    history in the admin UI when reviewing the pilot.
 
 Slack Socket Mode needs no public inbound URL. If operators need the admin UI or approval links
-from outside the host, put a tunnel or reverse proxy in front of the loopback service and set
-**Settings → Connection → Public URL** to its HTTPS origin. See
+from outside the host, put a tunnel or reverse proxy in front of the loopback service, set
+**Settings → Connection → Public URL** to its HTTPS origin, and set **Behind a reverse proxy** to
+the proxy you run (`cloudflare`, or `xff` for nginx/caddy) so the login backoff keys on each real
+client — without it, all remote logins share one backoff bucket. See
 [reverse proxies and tunnels](./docs/OPERATIONS.md#reverse-proxies-and-tunnels).
 
 ## Backup & restore config (encrypted)

TEST-PLAN.md

@@ -1,5 +1,28 @@
 # ChannelGate — Test Plan
 
+## Login backoff behind a reverse proxy (2026-10-25)
+
+- [x] Automated: `node scripts/run-tests.mjs test/web-security.test.js test/settings-save-version.test.js
+  test/admin-auth-bind.test.js test/approval-links.test.js` — `clientKey` ignores both forwarded
+  headers with no proxy declared (loopback and non-loopback sockets alike); `cloudflare` reads
+  `CF-Connecting-IP` only; `xff` reads the LAST `X-Forwarded-For` hop; the stored setting wins over
+  `CG_TRUST_PROXY`; legacy `1`/`true`/`yes` mean `xff`; an unknown value trusts nothing; the global
+  cap holds fresh keys at the maximum delay after N failures and drains with the window, is
+  switchable off, and defaults to 50 per 10 minutes; the admin API persists `""`/`cloudflare`/`xff`,
+  maps `1` to `xff`, refuses unknown values with 400 and writes nothing; the Settings page paints
+  and saves the select.
+- [x] `npm run check:static`, `npm run secret-scan`.
+- [ ] Live, engine-independent (browser + curl): on the deployment (Cloudflare tunnel in front) set
+  Settings → Connection → Behind a reverse proxy to **Cloudflare tunnel** and save. From a browser
+  through the public hostname enter three wrong admin passwords; the fourth attempt is delayed
+  (the page reports the wait) while a colleague on a different network can still sign in at once.
+  Then, against the LAN/loopback bind only (Cloudflare overwrites the header on the public path),
+  `for i in 1 2 3 4 5 6; do curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:4747/api/login
+  -H 'content-type: application/json' -H "CF-Connecting-IP: 10.0.0.$i" -d '{"password":"wrong"}'; done`
+  with the setting at **None**: every request shares the loopback bucket, so the 4th onwards is
+  429/delayed regardless of the spoofed header. PASS when both hold and the setting round-trips
+  after a daemon restart.
+
 ## Harness default effort (2026-10-23)
 
 - [x] Automated: `node --test test/default-model.test.js test/qwen-provider-settings-route.test.js

docs/OPERATIONS.md

@@ -96,26 +96,29 @@ allowed past the DNS-rebinding guard (extra names go in `CG_ALLOWED_HOSTS`).
 **Client addresses behind that hop.** Every request then arrives on a loopback socket, so
 `req.ip` — and Express's idea of the client — is `127.0.0.1` for every caller on earth. Two things
 count failures per address: the admin login backoff and the approval-link token backoff. Keyed on
-the socket they would share ONE bucket, and a handful of bad tokens or passwords from anywhere
-would lock out every legitimate admin and every valid approval link. So both read the real client
-through one helper (`clientKey` in `src/web/security.js`): `CF-Connecting-IP` first, then the first
-hop of `X-Forwarded-For`, and **only when the socket itself is loopback** — from a non-loopback
-socket those headers are whatever the client typed and are ignored. A value that is not a valid IP
-address is ignored too.
+the socket they share ONE bucket, and a handful of bad tokens or passwords from anywhere delays
+every legitimate admin and every valid approval link. So **declare the proxy** in *Settings →
+Connection → Behind a reverse proxy* (`trustProxy` in settings.json, or `CG_TRUST_PROXY` in
+`.env`; the setting wins): `cloudflare` makes both limiters key on `CF-Connecting-IP`, which
+cloudflared overwrites on every request; `xff` keys on the **last** hop of `X-Forwarded-For`, the
+one your nginx/caddy appended (never the first, which the client typed). Without it, all remote
+logins share one backoff bucket. A loopback socket on its own is deliberately NOT taken as proof
+of a proxy — any process on the host or any tunnel opens one — so an undeclared header is ignored,
+and a value that is not a valid IP address is ignored too. Independently of the key, more than 50
+failed attempts in ten minutes across all clients puts every login on the maximum delay until the
+window drains, which bounds guessing even where a header is misdeclared.
 
 Notes for operators:
 
 - Express's app-wide `trust proxy` is deliberately NOT enabled: it would also re-point
   `req.secure` / `req.protocol` / `req.hostname` at client-supplied headers (the Host/Origin guard
   and the session cookie's `Secure` flag read those headers themselves, deliberately), and it knows
-  nothing about `CF-Connecting-IP`.
-- If your proxy runs on ANOTHER host, the socket is not loopback and the headers are ignored by
-  default. Set `CG_TRUST_PROXY=1` in `.env` to honour `X-Forwarded-For` there — only do this when a
-  proxy you control rewrites that header, or clients can pick their own limiter bucket.
-- Make the proxy set `X-Forwarded-For` rather than append to a client-supplied one. Where it
-  appends (Cloudflare does), `CF-Connecting-IP` is the unforgeable value and is preferred here; a
-  caller who spoofs the first XFF hop can only shed its own backoff, never push someone else into
-  one.
+  nothing about `CF-Connecting-IP`. The `Secure` cookie decision still reads `x-forwarded-proto`
+  on its own; that only ever makes the cookie stricter.
+- Only declare a proxy you control and that sets the header on EVERY request. If clients can reach
+  the daemon's port directly (a LAN bind) while `xff` is declared, a caller could append its own
+  hop; keep the bind on loopback or firewall the port, as the rest of this guide assumes.
+- The legacy `CG_TRUST_PROXY=1` still works and means `xff`.
 
 ## The ChannelGate rename migration
 

public/app.js

@@ -3891,6 +3891,7 @@ function readSettingsForm() {
     composioMcpUrl: document.getElementById("set-composio").value,
     toolboxMcpUrl: document.getElementById("set-toolbox").value,
     publicUrl: document.getElementById("set-public-url").value,
+    trustProxy: document.getElementById("set-trust-proxy").value,
     approvalLinks: document.getElementById("set-approval-links").value,
     aiTestingUsers: aiTestingPicker?.getValues() || [],
     ...(document.getElementById("set-gchat-key").value.trim() ? { googleChatServiceAccountJson: document.getElementById("set-gchat-key").value } : {}),
@@ -4020,6 +4021,7 @@ function paintSettings(s) {
   document.getElementById("set-composio").value = s.composioMcpUrl || "";
   document.getElementById("set-toolbox").value = s.toolboxMcpUrl || "";
   document.getElementById("set-public-url").value = s.publicUrl || "";
+  document.getElementById("set-trust-proxy").value = s.trustProxy || "";
   document.getElementById("set-approval-links").value = s.approvalLinks || "auto";
   aiTestingPicker = mountUserPicker(document.getElementById("set-ai-testing-users"), {
     users: USERS, selected: s.aiTestingUsers || [], onChange: markSettingsDirty,

public/index.html

@@ -539,6 +539,15 @@ <h4>Public URL</h4>
                     <span>Public URL (the daemon's externally-reachable base URL)</span>
                     <input id="set-public-url" type="text" placeholder="https://gateway.makeitfuture.com" />
                   </label>
+                  <label class="field">
+                    <span>Behind a reverse proxy — which header names the real client (login and approval-link backoff)</span>
+                    <select id="set-trust-proxy">
+                      <option value="">None — the connecting address is the client</option>
+                      <option value="cloudflare">Cloudflare tunnel (CF-Connecting-IP)</option>
+                      <option value="xff">nginx / caddy / other (last X-Forwarded-For hop)</option>
+                    </select>
+                  </label>
+                  <p class="desc">Without this, every remote login shares one backoff bucket behind the proxy; with it, each real client gets its own. Only declare a proxy you control: it must set the header on every request.</p>
                 </div>
                 <div class="setcard">
                   <h4>Approval links</h4>

src/config/settings.js

@@ -262,6 +262,25 @@ export function getApprovalLinks() {
   return APPROVAL_LINK_MODES.includes(v) ? v : "auto";
 }
 
+// Which forwarded-client header the login and approval-link backoff may believe. "" trusts
+// nothing (the socket address is the client); "cloudflare" reads `CF-Connecting-IP`, which
+// cloudflared overwrites on every request; "xff" reads the LAST hop of `X-Forwarded-For` — the one
+// the trusted proxy appended — never the first, which the client typed. The legacy truthy
+// CG_TRUST_PROXY=1 meant "there is a proxy" and maps onto "xff". Settings win over the env.
+export const TRUST_PROXY_MODES = ["", "cloudflare", "xff"];
+export function normalizeTrustProxy(value) {
+  const v = String(value ?? "").trim().toLowerCase();
+  if (v === "" || v === "0" || v === "false" || v === "no" || v === "off" || v === "none") return "";
+  if (v === "cloudflare" || v === "cf") return "cloudflare";
+  if (v === "xff" || v === "x-forwarded-for" || v === "1" || v === "true" || v === "yes" || v === "on") return "xff";
+  return null; // not a mode
+}
+export function getTrustProxy() {
+  const s = getSettings();
+  if (typeof s.trustProxy === "string") return normalizeTrustProxy(s.trustProxy) ?? "";
+  return normalizeTrustProxy(process.env.CG_TRUST_PROXY) ?? "";
+}
+
 // Opt-in recipients of supplemental Slack button links. Missing/invalid legacy values fail closed.
 export const AI_TESTING_USER_ID_RE = /^[UW][A-Z0-9]+$/;
 export function getAiTestingUsers() {
@@ -1105,6 +1124,7 @@ export function settingsForApi() {
     composioMcpUrl: s.composioMcpUrl ?? process.env.COMPOSIO_MCP_URL ?? "https://connect.composio.dev/mcp",
     toolboxMcpUrl: s.toolboxMcpUrl ?? process.env.TOOLBOX_MCP_URL ?? "https://www.skillsmanager.uk/toolbox",
     publicUrl: getPublicUrl(),
+    trustProxy: getTrustProxy(),
     approvalLinks: getApprovalLinks(),
     aiTestingUsers: getAiTestingUsers(),
     progressView: getProgressView(),

src/web/auth.js

@@ -187,10 +187,11 @@ export function noPasswordLockdown(req, res, next) {
 // Which identity the login backoff counts against. Behind a reverse proxy or tunnel every request
 // arrives from 127.0.0.1, so keying on the socket puts all remote clients in ONE bucket: an
 // attacker's failures lock out the real admin, and distributed guessing looks like one client.
-// The forwarding headers fix that and are honoured exactly where they cannot be forged — from a
-// loopback socket, which only the proxy in front and this host's own processes can open — or when
-// the operator declares a trusted proxy elsewhere on the network (CG_TRUST_PROXY). One helper,
-// shared with the approval-link router, so both limiters bucket callers the same way.
+// The forwarding header of the proxy the operator DECLARED (`trustProxy`: cloudflare → the
+// CF-Connecting-IP it overwrites, xff → the last X-Forwarded-For hop it appended) fixes that; an
+// undeclared header is a client's claim and is ignored, and a global failure cap bounds guessing
+// either way. One helper, shared with the approval-link router, so both limiters bucket callers
+// the same way.
 export function loginKey(req) {
   return clientKey(req);
 }

src/web/routes/approve.js

@@ -40,7 +40,8 @@ export const APPROVAL_LINK_PRINCIPAL = "link";
 // exponential backoff as a failed admin login. A CORRECT token never records a failure, so a
 // person retrying their own link is never slowed down. "Per-IP" is per REAL client: these URLs are
 // opened from the internet through a loopback tunnel, and keying on the socket would let six bad
-// tokens from anywhere lock out every legitimate link (see clientKey in ../security.js).
+// tokens from anywhere lock out every legitimate link — once the operator has declared the proxy
+// whose header names the client (see clientKey in ../security.js and the `trustProxy` setting).
 const DEFAULT_LIMITER = { freeAttempts: 5, baseDelayMs: 1_000, maxDelayMs: 60_000 };
 
 const escapeHtml = (value) =>