Release exp-v0.52.43: trusted-header auth / reverse-proxy SSO (#5568, #3351) (#5956)

* feat(#3351): add trusted-header auth core

* fix(#3351): reconcile trusted sessions per request

* fix(#3351): preserve valid trusted group mappings

* fix(#3351): defer trusted logout reconciliation until after csrf

* fix(auth): clear _pending_set_cookies in reset_trusted_auth_request_state (keep-alive cookie cross-request leak)

Codex gate CORE finding: a Set-Cookie queued in request N but not flushed
survived onto the reused HTTP/1.1 handler and could be emitted by request N+1
— after trusted-identity rotation on logout this could overwrite a valid login
cookie and 401 the user. Reset the queue at the per-request boundary + add a
keep-alive regression test.

* docs(.env.example): document trusted-header auth / reverse-proxy SSO env vars

HERMES_WEBUI_TRUSTED_AUTH_HEADER + TRUSTED_PROXY_CIDRS (with exact-proxy-IP
security warning) + optional groups-header/JSON group-profile-map/logout-url.

* Release exp-v0.52.43: trusted-header auth / reverse-proxy SSO (#5568, #3351) + keep-alive cookie fix + docs

---------

Co-authored-by: Rod Boev <rod.boev@gmail.com>
Co-authored-by: nesquena-hermes <agent@nesquena-hermes>

.env.example

@@ -77,6 +77,27 @@
 # HERMES_WEBUI_TRUST_FORWARDED_FOR=1
 # HERMES_WEBUI_TRUST_FORWARDED_PROTO=1
 
+# ── Trusted-header auth / reverse-proxy SSO (opt-in; OFF by default) ──────────
+# Delegate authentication to a reverse proxy you run (Authelia, oauth2-proxy,
+# corporate SSO, …) that authenticates the user and forwards their identity in a
+# header. When HERMES_WEBUI_TRUSTED_AUTH_HEADER is set, the WebUI treats a request
+# as that identity — but ONLY when the request's un-spoofable raw socket peer is
+# an allowlisted proxy (HERMES_WEBUI_TRUSTED_PROXY_CIDRS below). With no header
+# set, this path is disabled and normal password/passkey auth applies.
+#
+# ⚠️ SECURITY: HERMES_WEBUI_TRUSTED_PROXY_CIDRS MUST list the EXACT IP(s) of your
+# proxy — e.g. 10.0.0.5/32 or 127.0.0.1/32. NEVER use 0.0.0.0/0 or a broad range:
+# any client whose peer IP falls in the range could forge the identity header and
+# log in as anyone. If the allowlist is empty/malformed, the header is ignored
+# (fails closed). Loopback is trusted by default. Set the CIDR to your proxy only.
+# HERMES_WEBUI_TRUSTED_AUTH_HEADER=Remote-User
+# HERMES_WEBUI_TRUSTED_PROXY_CIDRS=10.0.0.5/32
+# Optional: map a forwarded groups header to WebUI profiles (JSON object), and a
+# logout URL to redirect to after clearing the local session (SSO single-logout).
+# HERMES_WEBUI_TRUSTED_GROUPS_HEADER=Remote-Groups
+# HERMES_WEBUI_GROUP_PROFILE_MAP={"admins":"default","team-a":"projecta"}
+# HERMES_WEBUI_TRUSTED_AUTH_LOGOUT_URL=https://sso.example.com/logout
+
 # ── Uploads & limits ─────────────────────────────────────────────────────────
 
 # Where chat attachments are stored (default: <state dir>/attachments).