Security Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The security architecture of shunt is designed to provide a secure, transparent proxy for LLM requests while managing sensitive provider credentials. As a gateway between clients (like Claude Code) and various upstream AI providers, shunt prioritizes the isolation of secrets, validation of inbound requests, and the preservation of protocol integrity.
The system operates as a local or hosted process that handles API keys and OAuth tokens, ensuring that credentials are never logged and are only injected into authorized upstream requests. This architecture is centered around a request pipeline that enforces authentication gates and strictly manages credential writeback behavior to prevent leakage.
Sources: ARCHITECTURE.md:4-14, SECURITY.md:1-5
Authentication and Authorization
shunt implements a layered authentication model to secure both inbound client requests and outbound provider requests. The gateway acts as an intermediary that can validate incoming tokens before dispatching requests to selected adapters.
Inbound Authentication
The gateway includes an inbound-auth gate within the request pipeline. This gate validates that the client is authorized to use the gateway before any routing or buffering occurs. This is managed via src/auth/inbound.rs and is configured through the [server.auth] section of the configuration file.
Sources: ARCHITECTURE.md:43-52, ARCHITECTURE.md:130-132
Outbound Provider Authentication
For outbound traffic, shunt supports multiple authentication modes depending on the provider. The gateway can inject API keys or reuse existing session tokens (such as ChatGPT OAuth tokens) into the upstream request headers.
| Auth Mode | Description | Key Files |
|---|---|---|
| Passthrough | Forwards original client credentials to Anthropic. | src/auth/claude/ |
| API Key | Injects provider-specific keys (OpenAI, xAI, etc.). | src/auth/ |
| OAuth | Handles token lookup and refresh for session-based access. | src/auth/codex/, src/auth/xai/ |
Sources: ARCHITECTURE.md:89-94, ARCHITECTURE.md:104-111
Credential Management
Handling sensitive secrets is a core security concern for shunt. The system is designed to read, use, and occasionally refresh credentials without exposing them to unauthorized parties.
Secure Persistence and Refresh
Credential files, such as ~/.claude/.credentials.json or ~/.codex/auth.json, are accessed for authentication. The system ensures that credential refresh operations are cancellation-safe and perform I/O operations off-thread to maintain stability and security.
Sources: ARCHITECTURE.md:158-161, SECURITY.md:15-18
Critical Security Constraints
- No Secret Logging: The system explicitly forbids the logging of secrets, tokens, or captured authorization headers.
- Restricted Writeback: Credential-file writeback behavior is strictly guarded and requires explicit verification if changed.
- Safe Origins: Injected bearer credentials must be guarded by HTTPS and allowed origin checks to prevent interception.
Sources: AGENTS.md:107-108, blueprints/provider/_generic.md:42-45, blueprints/provider/_generic.md:65-67
Request Pipeline Security
The request processing flow is structured to ensure that security checks are performed at the earliest possible stage.
The diagram above shows the security checkpoints in the request pipeline. The Inbound Auth Gate acts as the primary barrier before any processing or routing occurs.
Sources: ARCHITECTURE.md:37-41, ARCHITECTURE.md:83-88
Data Isolation and Integrity
shunt maintains security through strict architectural invariants that prevent data leakage and ensure the integrity of the gateway's operations.
Configuration Snapshotting
To prevent inconsistent states or security holes during configuration updates, shunt snapshots the configuration exactly once per request. When a request enters proxy::post, it pins a consistent view of config, inbound_auth, and admin_auth. This ensures that a mid-request reload cannot alter security policies while a request is in flight.
Sources: ARCHITECTURE.md:150-156
Error Masking
Gateway-owned errors are reshaped into the Anthropic error envelope. This prevents the leaking of internal system details or upstream stack traces to the client. Upstream network failures are flattened to a generic 502 api_error.
Sources: ARCHITECTURE.md:144-148, src/AGENTS.md:30-31
Administrative Security
The project includes an optional admin surface for account provisioning and dashboarding. Access to this surface is strictly controlled:
- Opt-in only: The admin router is not active by default.
- Token-based access: The admin interface uses
admin_authtokens. - Read-only components: Includes a read-only pool dashboard to prevent unauthorized modification of state via the UI.
Sources: ARCHITECTURE.md:95-97, ARCHITECTURE.md:104-111
Security Policy Summary
| Feature | Policy |
|---|---|
| Vulnerability Reporting | Private reports to minsu.lee@passionfactory.ai; no public issues. |
| Credential Handling | Support for API keys and ChatGPT OAuth tokens; restricted writeback. |
| TLS/SSL | Usage of rustls; process-wide provider installed on first handshake. |
| Logging | Mandatory filtering of secrets; no logging of authorization headers. |
Sources: SECURITY.md:1-20, ARCHITECTURE.md:163-165