Network-Based Bypass

Relevant source files

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

• src/auth.rs
• src/auth/bypass_path.rs
• src/proxy.rs
• src/state.rs
• src/main.rs
• README.md
• AGENTS.md

Network-Based Bypass allows specific requests to skip the mandatory password gate based on their origin IP address or requested URL path. This feature enables automated systems, health checks, and trusted networks to access protected upstreams without manual authentication.

The system evaluates bypass rules before checking for session cookies. If a request matches a bypass condition, Hodor proxies the request to the upstream and identifies the bypass method via the X-Hodor-Auth header.

Sources: README.md:129-131, src/proxy.rs:77-88

Core Bypass Mechanisms

Hodor implements two primary bypass strategies: Path-Based Bypass and CIDR-Based Bypass.

Path-Based Bypass (BYPASS_PATHS)

Path-Based Bypass permits access to specific URL subtrees without authentication. This is commonly used for webhooks, metrics, or public assets.

• Exact Match: Matches the path exactly (e.g., /api/health).
• Wildcard Match: Matches a prefix and all sub-paths if the pattern ends in /* (e.g., /static/*).
• Safety: Hodor only matches canonical paths. It rejects requests containing dot segments (..), double slashes (//), or percent-encoded separators to prevent path traversal attacks.

Sources: src/auth/bypass_path.rs:11-40, README.md:162-178

CIDR-Based Bypass (BYPASS_CIDRS)

CIDR-Based Bypass allows entire network ranges to access the upstream. This is intended for trusted private networks or sidecar communication.

• Client Resolution: Hodor identifies the client IP from the TCP connection or the X-Forwarded-For header if TRUST_PROXY is enabled.
• Evaluation: The resolved IP is checked against the configured list of IpNet structures.

Sources: src/state.rs:44, src/proxy.rs:65-72, README.md:154-160

Request Evaluation Flow

The following diagram illustrates how Hodor decides whether to bypass authentication or present the login gate.

Configuration Options

The behavior of network bypasses is controlled through environment variables or the hodor.toml file.

Option	Environment Variable	Type	Description
bypass_paths	BYPASS_PATHS	String (Comma-sep)	Paths or prefixes (with /*) to serve without auth.
bypass_cidrs	BYPASS_CIDRS	String (Comma-sep)	Client networks (CIDR) allowed to bypass auth.
trust_proxy	TRUST_PROXY	Boolean	Enables parsing of X-Forwarded-For for IP resolution.
trusted_proxy_cidrs	TRUSTED_PROXY_CIDRS	String (Comma-sep)	Limits which proxies can provide forwarding headers.

Sources: README.md:60-84, src/state.rs:104-107

Upstream Communication

When a request is bypassed, Hodor informs the upstream application how the request was cleared by setting the X-Hodor-Auth header. This allows the upstream to apply its own granular permissions based on the trust level.

X-Hodor-Auth Value	Triggering Condition
public	Request path matched an entry in BYPASS_PATHS.
bypass	Client IP matched a network in BYPASS_CIDRS.
password	Request contained a valid HMAC-signed session cookie.

Hodor unconditionally strips any client-supplied X-Hodor-* headers before forwarding to prevent authentication spoofing.

Sources: src/proxy.rs:25-35, src/proxy.rs:163-176, AGENTS.md:36-39

Implementation Details

The bypass logic is encapsulated in the AppState and evaluated during the proxy_or_login handler execution.

// src/proxy.rs:77-88
fn resolve_auth_method(
    state: &AppState,
    client_ip: IpAddr,
    request: &Request<Body>,
) -> Option<AuthMethod> {
    if is_bypass_path(request.uri().path(), &state.bypass_paths) {
        return Some(AuthMethod::Public);
    }
    if is_authenticated(request.headers(), &state.secret) {
        return Some(AuthMethod::Password);
    }
    if is_bypass_ip(client_ip, &state.bypass_cidrs) {
        return Some(AuthMethod::Bypass);
    }
    None
}

Sources: src/proxy.rs:77-88

The BypassPath enum handles the distinction between exact strings and prefix-based wildcards:

• BypassPath::Exact(String): Used for literal path matching.
• BypassPath::Prefix(String): Created when a pattern ends in /*, matching any path starting with that prefix.

Sources: src/auth/bypass_path.rs:5-10

Summary

Network-Based Bypass provides a flexible way to manage access for automated tools and trusted environments. By combining path-based rules with IP-based CIDR filtering, Hodor maintains security for human users via the password gate while ensuring operational continuity for system-level requests. All bypass decisions are communicated to the upstream via a secure, non-forgeable header.