Windows installer: payload hash-locking, SBOM, client-IP handling, operator docs

plugins/geenforce/api/routes.py

@@ -52,12 +52,23 @@ def _trusted_client_ip():
     Uses request.remote_addr, NOT the raw X-Forwarded-For header. Proxies APPEND
     to X-Forwarded-For, so its first hop is attacker-controlled: parsing it (as
     _client_ip does for rate-limiting) would let any caller send
-    'X-Forwarded-For: <allowlisted-ip>' and bypass the token. remote_addr cannot
-    be forged here - behind IIS the URL-Rewrite rule overwrites X-Forwarded-For
-    with the real TCP peer and waitress (--trusted-proxy=127.0.0.1
-    --trusted-proxy-headers=x-forwarded-for) derives remote_addr from it; a
-    client hitting waitress directly is not a trusted proxy, so its remote_addr
-    is its own real peer address. Either way remote_addr is the true client.
+    'X-Forwarded-For: <allowlisted-ip>' and bypass the token.
+
+    DEPLOYMENT DEPENDENCY, not a property of this function. remote_addr is only
+    trustworthy because of what sits in front:
+
+      - Behind IIS, the URL-Rewrite rule OVERWRITES X-Forwarded-For with the real
+        TCP peer, and waitress (--trusted-proxy=127.0.0.1
+        --trusted-proxy-headers=x-forwarded-for) derives remote_addr from it.
+      - Remove that rule and IIS still forwards whatever X-Forwarded-For the
+        CALLER sent. waitress trusts it because it comes from 127.0.0.1, so
+        remote_addr becomes attacker-controlled and this allowlist is bypassable
+        from anywhere on the network. It does NOT fail closed.
+      - A client reaching waitress directly is not a trusted proxy, so there
+        remote_addr is its own peer address.
+
+    The rule is the control. See the geenforce-api-cutover wiki page; the Windows
+    installer enables it and verifies it is live at the end of an install.
     """
     return request.remote_addr or ''