Use Cases
Relevant source files
The following files were used as context for generating this wiki page:
Hodor serves as a lightweight authentication gateway that protects web applications behind a single shared password. It operates as a streaming reverse proxy, intercepting incoming HTTP requests to verify credentials before forwarding traffic to an internal upstream service.
The system requires no database or complex identity provider integration, making it suitable for rapid deployments where a simple "gate" is sufficient for access control. Hodor specifically addresses scenarios involving internal tool protection, staging environment isolation, and secure access to specific API subtrees while maintaining public access for webhooks or health checks.
Sources: README.md:9-12, AGENTS.md:7-10
Internal Application Protection
Hodor provides a security layer for internal dashboards, documentation, or admin panels that lack native authentication. It runs as a sidecar container alongside the target application, ensuring that only users with the correct password can view the content.
Sidecar Deployment Flow
In a typical deployment, an orchestrator routes external traffic to Hodor. Hodor then evaluates the request and, upon successful authentication, proxies the traffic to the application bound to a private network or loopback interface.
This diagram shows the basic flow where Hodor acts as the entry point for an unauthenticated user, either presenting a login page or proxying to the protected upstream service.
Sources: README.md:21-33, AGENTS.md:15-22
Hybrid Access for Public APIs and Webhooks
Hodor supports scenarios where most of an application requires a password, but specific endpoints must remain accessible to external services like GitHub webhooks, health monitors, or OAuth providers.
Public Path Logic
Administrators define BYPASS_PATHS to list specific routes that skip the password gate. This allows machine-to-machine communication for automated services while keeping the user interface protected.
| Feature | Configuration Key | Behavior |
|---|---|---|
| Exact Path | /api/webhook | Matches only the specific path. |
| Subtree | /static/* | Matches the path and all nested children. |
| Health Checks | /_gate/health | Built-in bypass for process liveness checks. |
Sources: README.md:129-148, src/config.rs:163-166, src/proxy.rs:77-79
Trusted Network Access
Hodor allows users on specific networks to bypass the password gate entirely. This use case is common for developers working within a corporate VPN, a Tailscale tailnet, or a local office network.
Network Authentication Flow
When a request arrives, Hodor resolves the client's IP address. If the IP address falls within the ranges defined in BYPASS_CIDRS, Hodor grants access without prompting for a password.
This flowchart details the sequence of checks Hodor performs to determine if a request should be proxied and which authentication header to attach.
Sources: README.md:118-127, src/proxy.rs:69-87, src/tests/proxy.rs:370-381
Real-time Application Proxying
Hodor supports modern web applications that utilize WebSockets for real-time updates. It handles the initial HTTP upgrade request and establishes a bidirectional tunnel for raw data transfer.
WebSocket Handling
When Hodor detects an Upgrade: websocket header, it performs the following:
- Validates the session or bypass rules.
- Forwards the upgrade request to the upstream.
- If the upstream responds with a
101 Switching Protocolsstatus, Hodor spawns a task to copy data bidirectionally between the client and upstream without buffering.
Sources: README.md:167-167, src/proxy.rs:163-183, src/tests/proxy.rs:259-307
Multi-App Shared Authentication
Hodor can share login sessions across multiple subdomains of a primary domain. This is useful for organizations running several preview environments (e.g., app1.preview.example.com and app2.preview.example.com).
Configuration for Shared Sessions
By setting the COOKIE_DOMAIN (e.g., .preview.example.com), Hodor issues a session cookie that the browser sends to any Hodor instance guarding subdomains under that root. This provides a Single Sign-On (SSO) experience for the shared password.
Sources: README.md:76-76, src/config.rs:170-181
Upstream Authentication Awareness
Hodor informs the upstream application how a request was authorized via the X-Hodor-Auth header. This allows the upstream to implement granular permissions based on the authentication method.
Forwarded Header Values
| Value | Context |
|---|---|
password | The user entered the correct password and holds a signed cookie. |
bypass | The request originated from a trusted CIDR range. |
public | The request matched a defined public path. |
Sources: README.md:150-161, src/proxy.rs:30-41, src/tests/proxy.rs:408-433
Hodor simplifies access control by providing a unified gateway for various connectivity scenarios, ranging from manual user logins to automated network-based bypasses. Its ability to stream traffic and tunnel WebSockets ensures compatibility with a wide range of web applications while maintaining a minimal operational footprint.