Forwarded Authentication

Relevant source files

The following files were used as context for generating this wiki page:

• src/proxy.rs
• src/auth.rs
• README.md
• AGENTS.md
• src/config.rs
• src/state.rs
• src/auth/session.rs

Forwarded Authentication is a mechanism within Hodor that informs upstream applications about the security context of a proxied request. Hodor intercepts all incoming traffic, validates credentials or network trust, and communicates the resulting authentication state through specific HTTP headers. This allows the backend application to identify how a user cleared the gate without requiring the backend to implement its own session validation or HMAC checks.

The system prioritizes security by sanitizing headers before they reach the upstream. Hodor unconditionally strips any client-supplied headers that begin with X-Hodor- to prevent authentication forgery. Only after sanitization does Hodor append its own verified authentication metadata.

Sources: README.md:212-226, AGENTS.md:38-41, src/proxy.rs:163-178

Authentication Status Reporting

Hodor identifies the authentication method used for each request and reports it via the X-Hodor-Auth header. The proxy resolves the authentication method by evaluating the request against a specific hierarchy of trust: public paths, session cookies, and IP-based bypasses.

Authentication Methods

Value	Description	Context
password	The request presented a valid HMAC-signed session cookie.	Authenticated User
bypass	The resolved client IP address matches a CIDR in BYPASS_CIDRS.	Network Trust
public	The request path matches an entry in BYPASS_PATHS.	No Authentication

Sources: src/proxy.rs:21-31, README.md:213-221

Resolution Logic

Hodor follows a strict order when determining the AuthMethod. It first checks if the path is explicitly marked as public. If not, it checks for a valid session. Finally, it checks the client's network address.

The diagram shows the priority Hodor gives to different authentication triggers during request processing.

Sources: src/proxy.rs:71-84, AGENTS.md:22-26

Header Management and Sanitization

Hodor manages headers to maintain the integrity of the authentication state and provide standard proxy information to the upstream.

Security Stripping

Before forwarding a request, Hodor removes all existing headers that start with the x-hodor- prefix. This prevents clients from injecting their own X-Hodor-Auth values to mimic an authenticated state. This removal occurs regardless of whether the path is public or protected.

Sources: src/proxy.rs:163-178, AGENTS.md:38-41

Forwarded Context

Hodor appends standard headers to maintain client context:

• X-Forwarded-For: Contains the client IP address. If Hodor trusts a proxy, it appends the client IP to the existing list.
• X-Forwarded-Proto: Identifies the protocol (http or https) used by the client. Hodor only trusts the protocol reported by external proxies if TRUST_PROXY is enabled.

Sources: src/proxy.rs:223-241, README.md:264-268

Static Upstream Headers

You can configure a single static header via UPSTREAM_HEADER (or the environment variable UPSTREAM_HEADER). Hodor injects this header into every proxied request. This is useful for passing backend-specific tokens that are shared across all users. Hodor rejects reserved headers (like Host or X-Hodor-*) in this configuration to prevent protocol interference.

Sources: src/config.rs:281-309, README.md:129-145

Network Trust and IP Resolution

Forwarded authentication relies on accurate identification of the client IP. Hodor supports complex networking environments through proxy trust settings.

Trusted Proxies

When TRUST_PROXY is true, Hodor looks at the X-Forwarded-For header to find the real client IP. You can restrict which proxies Hodor trusts by defining TRUSTED_PROXY_CIDRS. If the connecting IP address is not in the trusted list, Hodor ignores the forwarded headers and uses the direct TCP peer address.

Sources: src/proxy.rs:60-65, src/config.rs:115-117, README.md:188-195

Implementation Example

The sequence shows Hodor validating the session and injecting the verified authentication status before reaching the upstream.

Sources: src/proxy.rs:86-135, src/tests/proxy.rs:434-455

Configuration Summary

The following configuration options directly impact how Hodor handles forwarded authentication and identity resolution.

Option	Env Var	Purpose
trust_proxy	TRUST_PROXY	Enables processing of X-Forwarded-* headers.
trusted_proxy_cidrs	TRUSTED_PROXY_CIDRS	Defines which networks are allowed to provide forwarding headers.
bypass_cidrs	BYPASS_CIDRS	Networks that receive X-Hodor-Auth: bypass.
bypass_paths	BYPASS_PATHS	Paths that receive X-Hodor-Auth: public.
upstream_header	UPSTREAM_HEADER	Defines a static header sent to the upstream.
preserve_host	PRESERVE_HOST	Determines if the original Host header is forwarded.

Sources: src/config.rs:10-33, README.md:73-107

Hodor serves as a single-point-of-authentication that simplifies backend security by centralizing session management and IP filtering, communicating the result through non-forgeable HTTP headers.