Add optional Forward Auth support to integrate Fizzy with reverse-proxy SSO (Zero Trust / Enterprise gateway auth)

[soulteary]

Hi maintainers — I’d like to propose adding optional Forward Auth support to Fizzy so it can natively integrate with common reverse-proxy / gateway authentication setups (Traefik/Nginx/Zero Trust gateways, etc.).

The real problem this solves

In many orgs, authentication is centralized at the edge: users authenticate via an IdP (OIDC/SAML/MFA/OTP) and the gateway forwards requests to apps with identity headers such as X-Auth-Email / X-Auth-User.
In those deployments, requiring each app to run its own login flow (or depend on magic-link email delivery) is friction and sometimes not even feasible (no outbound SMTP, restricted email flows, internal-only networks).

Why this is valuable for Fizzy

1. Much better self-host / enterprise fit: Works out-of-the-box with existing SSO/Zero Trust stacks, where the gateway is the source of truth.
2. Removes email dependency in restricted environments: magic-link is great, but some networks can’t reliably deliver it.
3. Aligns with Fizzy’s multi-tenancy model: Forward Auth answers “who”, while tenant selection + authorization remain in Fizzy (URL path + local access records).
4. Fully opt-in, no behavior change by default: when disabled or untrusted, Fizzy behaves exactly as it does today.

Security / risk controls

The only scary part is header spoofing, so the feature must be strictly trust-gated:

• Trust by source IP/CIDR allowlist (FORWARD_AUTH_TRUSTED_IPS),
• and/or trust by a shared secret header (FORWARD_AUTH_SECRET_HEADER + FORWARD_AUTH_SECRET).
  This keeps it safe and clearly “enterprise-configured,” not a default-open surface area.

Why now

PR #2485 already structures this as a clean, configurable integration:

• A complete set of env flags (enablement, trust policy, auto-provisioning, default role, optional session creation for WebSocket compatibility, optional email locking, optional account auto-creation, etc.).
• The auth chain can prefer a trusted gateway identity and optionally create a Fizzy session so ActionCable continues to work without special casing every request.

Requested outcome

I’d love to see this supported as an official, optional “Forward Auth / reverse-proxy SSO integration” path for self-hosters:

• default OFF,
• docs strongly emphasize “only trust allowlisted IPs and/or a secret header,”
• tests cover trusted/untrusted requests + provisioning toggles.

Even if it lands as “experimental behind config” initially, I believe this is one of those features where a small, well-guarded change unlocks a large set of real-world enterprise deployments.