feat(auth): support reverse-proxy driven proxy auth

Closes HP-353.

docs/features/proxy-auth.md

@@ -0,0 +1,99 @@
+---
+title: Proxy Authentication
+description: Delegate Headplane authentication to a trusted reverse proxy.
+outline: [2, 3]
+---
+
+:::warning
+Proxy authentication is **dangerously powerful**. If misconfigured, it can allow
+anyone to impersonate users and gain access to Headplane.
+
+It is recommended to use Headplane's built-in SSO integrations over proxy
+authentication if possible. No guarantees are made about the security of proxy
+authentication.
+:::
+
+# Proxy Authentication
+
+Proxy authentication lets Headplane delegate user authentication to a trusted
+reverse proxy. This is useful when Headplane is already protected by middleware
+such as nginx basic auth, Authelia, Authentik, or another SSO-aware proxy and
+you do not want users to log in to Headplane separately.
+
+Proxy authentication is intentionally opt-in and requires `headscale.api_key`.
+When enabled, Headplane trusts identity headers only on requests whose client IP
+matches `server.proxy_auth.allowed_cidrs`; all Headscale API calls then use the
+configured `headscale.api_key`.
+
+## Basic Configuration
+
+```yaml
+headscale:
+  api_key: "<your-headscale-api-key>"
+
+server:
+  proxy_auth:
+    enabled: true
+    user_header: "Remote-User"
+    email_header: "Remote-Email"
+    name_header: "Remote-Name"
+    allowed_cidrs:
+      - "127.0.0.1/32"
+      - "::1/128"
+```
+
+`user_header` is required for a request to authenticate and defaults to
+`Remote-User`. The value becomes the stable proxy identity in Headplane as
+`proxy:<value>`. `email_header`, `name_header`, and `picture_header` are
+optional profile metadata headers.
+
+The first proxy-authenticated user is created as the Headplane owner, matching
+the normal SSO first-user behavior. Subsequent users are created as members and
+can be reassigned from the Users page.
+
+## Client IP Checks
+
+If `allowed_cidrs` is omitted, Headplane trusts only localhost. By default, this
+CIDR check uses the socket address connected to Headplane, not
+`X-Forwarded-For`, `X-Real-IP`, or other forwarded headers. Configure
+`allowed_cidrs` for the direct address range your proxy uses to connect to
+Headplane.
+
+## Forwarded Client IP Headers
+
+If you need to check the original client IP from a proxy header, set `ip_header`
+to `X-Forwarded-For`, `X-Real-IP`, or another header your proxy controls. When
+`ip_header` is set, Headplane only reads that header if the direct socket peer
+matches `trusted_proxy_cidrs` (default localhost). The first IP in the header is
+then checked against `allowed_cidrs`:
+
+```yaml
+server:
+  proxy_auth:
+    enabled: true
+    ip_header: "X-Forwarded-For"
+    trusted_proxy_cidrs:
+      - "127.0.0.1/32"
+    allowed_cidrs:
+      - "10.0.0.0/8"
+```
+
+::: warning
+Only enable proxy authentication when Headplane is not directly reachable by
+untrusted clients. Anyone who can connect to Headplane from an allowed CIDR will
+be able to spoof the configured identity headers. Only configure `ip_header`
+for headers set or overwritten by your trusted reverse proxy.
+:::
+
+## Header Reference
+
+| Field                                   | Description                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------ |
+| `server.proxy_auth.enabled`             | Enables proxy authentication.                                                        |
+| `server.proxy_auth.user_header`         | Header containing the stable authenticated user identity. Defaults to `Remote-User`. |
+| `server.proxy_auth.email_header`        | Optional header containing the authenticated user's email address.                   |
+| `server.proxy_auth.name_header`         | Optional header containing the authenticated user's display name.                    |
+| `server.proxy_auth.picture_header`      | Optional header containing the authenticated user's profile picture URL.             |
+| `server.proxy_auth.allowed_cidrs`       | Client CIDRs allowed to authenticate. Defaults to localhost.                         |
+| `server.proxy_auth.ip_header`           | Optional original-client-IP header such as `X-Forwarded-For` or `X-Real-IP`.         |
+| `server.proxy_auth.trusted_proxy_cidrs` | Direct proxy CIDRs trusted to supply `ip_header`. Defaults to localhost.             |

docs/features/sso.md

@@ -17,6 +17,9 @@ Identity Provider (IdP) using the OpenID Connect (OIDC) protocol. When enabled,
 users sign in through your IdP and Headplane automatically links them to their
 Headscale identity, assigns a role, and manages their session.
 
+If your reverse proxy already performs authentication and can pass trusted user
+headers to Headplane, see [Proxy Authentication](./proxy-auth.md) instead.
+
 ## Getting Started
 
 ### Requirements