Module auth 

Authentication Proxy Module

Provides comprehensive authentication and authorization for HeliosProxy.

Features

• JWT Validation: JWKS-based JWT token validation
• OAuth Introspection: RFC 7662 token introspection
• API Key Management: Generate, validate, and revoke API keys
• Role Mapping: Map identities to database roles
• Credential Providers: Vault, AWS Secrets Manager, environment
• Session Management: Token-based session handling

Architecture

                   ┌─────────────────────────────────────┐
                   │      AuthenticationHandler          │
                   │  (Main entry point for auth)        │
                   └─────────────┬───────────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
  ┌──────▼──────┐        ┌───────▼───────┐       ┌───────▼───────┐
  │ JwtValidator│        │  OAuthClient  │       │ ApiKeyManager │
  │  (JWKS)     │        │(Introspection)│       │ (Key mgmt)    │
  └─────────────┘        └───────────────┘       └───────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                   ┌─────────────▼───────────────────────┐
                   │          Identity                    │
                   │  (Unified user representation)       │
                   └─────────────┬───────────────────────┘
                                 │
                   ┌─────────────▼───────────────────────┐
                   │          RoleMapper                  │
                   │  (Identity → Database Roles)         │
                   └─────────────────────────────────────┘

Example

use heliosdb::proxy::auth::{
    AuthenticationHandler, AuthRequest, JwtConfig,
    RoleMapper, SessionManager,
};

// Create authentication handler
let handler = AuthenticationHandler::builder()
    .enabled(true)
    .with_jwt(JwtConfig::new("https://auth.example.com/.well-known/jwks.json"))
    .with_api_keys(ApiKeyConfig::default())
    .default_role("db_user")
    .build();

// Authenticate a request
let request = AuthRequest::new()
    .with_header("Authorization", "Bearer eyJ...");

let result = handler.authenticate(&request).await?;
println!("Authenticated: {}", result.identity.user_id);

// Map to database roles
let mapper = RoleMapper::builder()
    .group_role("admins", "db_admin")
    .group_role("developers", "db_developer")
    .default_role("db_readonly")
    .build();

let roles = mapper.map_roles(&result.identity);

AI/Agent Authentication

HeliosProxy supports special authentication patterns for AI agents:

• Agent Tokens: Short-lived tokens with conversation scope
• Tool Authorization: Role-based tool access control
• Quota Management: Per-agent resource quotas

use heliosdb::proxy::auth::{AgentIdentity, AgentQuota};

let agent_identity = AgentIdentity {
    agent_id: "claude-code".to_string(),
    parent_user_id: "user123".to_string(),
    conversation_id: Some("conv_abc".to_string()),
    allowed_tools: vec!["query", "insert".to_string()],
    quota: AgentQuota::default(),
};

Re-exports

pub use config::AuthConfig;

pub use config::AuthMethod;

pub use config::Identity;

pub use config::AgentIdentity;

pub use config::AgentQuota;

pub use config::JwtConfig;

pub use config::JwtClaims;

pub use config::OAuthConfig;

pub use config::LdapConfig;

pub use config::ApiKeyConfig;

pub use config::RoleMappingRule;

pub use config::RoleMappingCondition;

pub use config::CredentialConfig;

pub use config::SessionConfig;

pub use config::AuthRateLimitConfig;

pub use jwt::JwtValidator;

pub use jwt::JwtError;

pub use jwt::JwtHeader;

pub use jwt::Jwks;

pub use jwt::Jwk;

pub use jwt::TokenCache;

pub use handler::AuthenticationHandler;

pub use handler::AuthenticationHandlerBuilder;

pub use handler::AuthRequest;

pub use handler::AuthResult;

pub use handler::AuthError;

pub use handler::CacheStats;

pub use oauth::OAuthClient;

pub use oauth::OAuthError;

pub use oauth::IntrospectionResponse;

pub use oauth::TokenExchange;

pub use oauth::TokenResponse;

pub use api_keys::ApiKeyManager;

pub use api_keys::ApiKey;

pub use api_keys::ApiKeyError;

pub use api_keys::ApiKeyStats;

pub use api_keys::ApiKeyBuilder;

pub use role_mapper::RoleMapper;

pub use role_mapper::RoleMapperBuilder;

pub use role_mapper::PermissionSet;

pub use role_mapper::Operation;

pub use role_mapper::AuthorizationContext;

pub use credentials::CredentialManager;

pub use credentials::CredentialManagerBuilder;

pub use credentials::CredentialProvider;

pub use credentials::DatabaseCredential;

pub use credentials::CredentialSource;

pub use credentials::CredentialError;

pub use credentials::StaticCredentialProvider;

pub use credentials::EnvironmentCredentialProvider;

pub use credentials::VaultCredentialProvider;

pub use credentials::AwsSecretsManagerProvider;

pub use session::SessionManager;

pub use session::SessionManagerBuilder;

pub use session::Session;

pub use session::SessionError;

pub use session::SessionStats;

pub use session::CookieOptions;

pub use session::SameSite;

Modules

api_keys

API Key Management

config

Authentication Proxy Configuration

credentials

Credential Providers

handler

Authentication Handler

jwt

JWT Token Validation

oauth

OAuth Token Introspection

role_mapper

Role Mapping

session

Session Management

Structs

AuthProxy

Authentication proxy facade

AuthProxyBuilder

Auth proxy builder