Public Paths (Bypass Paths)

Relevant source files

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

• src/auth/bypass_path.rs
• src/config.rs
• src/proxy.rs
• src/state.rs
• src/tests/auth/bypass_path.rs
• README.md

Public paths, also referred to as bypass paths, allow specific request routes to skip the Hodor password gate. This feature enables direct access to endpoints that do not require authentication, such as health checks, webhooks, metrics, or OAuth discovery endpoints, while still routing traffic through the proxy to maintain consistent header forwarding.

The system evaluates paths before checking for session cookies or IP-based bypasses. When a request matches a configured public path, Hodor proxies the request to the upstream with the header X-Hodor-Auth: public.

Sources: README.md, src/proxy.rs:77-80

Pattern Syntax and Matching

Hodor supports two types of path matching: exact matches and prefix-based matches. Patterns are defined in the BYPASS_PATHS configuration as a comma-separated list.

Pattern Type	Syntax	Description	Example
Exact	/path/name	Matches the specific path exactly. Does not match sub-paths.	/api/health matches /api/health only.
Prefix	/path/*	Matches the prefix and all sub-paths.	/static/* matches /static/img.png and /static/js/app.js.

Validation Rules

• Every pattern must start with a leading slash /.
• The wildcard character * is only permitted as a trailing /* segment.
• Interior wildcards (e.g., /a/*/b) or partial segment wildcards (e.g., /api*) are rejected at startup to prevent accidental security gaps.

Sources: src/auth/bypass_path.rs:1-25, src/tests/auth/bypass_path.rs:77-90, README.md

Security and Canonicalization

Hodor implements a "fail-closed" security model for path matching. The system only evaluates canonical paths to prevent attackers from using path traversal or encoding tricks to bypass the gate.

Canonical Path Requirements

A path is considered canonical if it meets the following criteria:

• It does not contain double slashes (//).
• It does not contain dot segments (. or ..).
• It does not contain traversal-relevant percent-encodings: %2e (dot), %2f (slash), or %25 (percent).

If Hodor receives a non-canonical path, it skips the bypass check entirely and forces the request into the password gate. This prevents discrepancies between Hodor's path evaluation and the upstream server's normalization logic.

Sources: src/auth/bypass_path.rs:34-51, src/tests/auth/bypass_path.rs:48-66

Request Flow Logic

The following diagram illustrates how Hodor determines if a request should bypass the password gate based on its path.

The diagram shows that non-canonical paths immediately bypass the public path check and fall through to standard authentication.

Sources: src/proxy.rs:67-85, src/auth/bypass_path.rs:53-57

Implementation Components

Data Structures

The core logic resides in the BypassPath enum, which categorizes patterns during configuration loading.

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum BypassPath {
    Exact(String),
    Prefix(String),
}

Sources: src/auth/bypass_path.rs:4-7

Key Functions

• BypassPath::parse(pattern: &str): Validates and converts a string pattern into a BypassPath variant. Sources: src/auth/bypass_path.rs:10-25
• is_bypass_path(path: &str, paths: &[BypassPath]): The entry point for checking a request path against the configured bypass list. Sources: src/auth/bypass_path.rs:53-57
• overwrite_auth_headers(headers: &mut HeaderMap, auth_method: AuthMethod): Ensures that any client-supplied X-Hodor-* headers are stripped and replaced with the verified public status. Sources: src/proxy.rs:185-200

Configuration

Bypass paths are configured via environment variables or the hodor.toml file.

Configuration Key	Environment Variable	Type	Description
bypass_paths	BYPASS_PATHS	CSV String	Comma-separated list of paths to serve without authentication.

During startup, build_app_state parses these strings and stores them as a Vec<BypassPath> in the global AppState.

Sources: src/config.rs:42, src/state.rs:101-105, src/config.rs:178-180

Summary

Public Paths provide a granular way to expose specific upstream resources while maintaining Hodor's proxying benefits. By enforcing strict canonicalization and limited wildcard syntax, the system ensures that these exceptions do not introduce path-traversal vulnerabilities or accidental exposure of protected routes. All requests clearing the gate via this method are explicitly marked with the public authentication header for the upstream's awareness.