Key Features

AuthProxy provides a comprehensive set of features designed to secure, route, and serve applications in the ItBuild ecosystem.

Authentication & Security

14 Authentication Methods

AuthProxy supports multiple authentication methods. Browser-facing key flows use challenge-response with Ed25519 signatures; OAuth and OTP keep their native protocols. MCP login is a separate programmatic path documented in MCP Access Model.

Category	Method	Description
Hardware / software keys	PassKey	Browser-native passkey support
	Fido2Key	FIDO2/WebAuthn hardware security keys
	UserKey	Ed25519 software passkey (challenge-response)
OTP	Phone	SMS verification (via Chat module)
	Email	Email OTP verification (via Chat module)
Magic links	Email	Email-only login with single-use link
OAuth	Google, Apple, Microsoft, GitHub, Facebook, VK, Discord, Telegram	Native OAuth 2.0 / OIDC handshake per provider
Federation v2	Browser federation	Sign in via verified partner ItBuild project (Form0 picker)
Service / programmatic	AppLogin	Application-level login bound to a verified user_app
	MCP (Basic / Verified / App)	Programmatic AI agent access; not a browser session

Challenge-Response Flow

1. Client requests challenge
2. Server generates random challenge
3. Client signs with private key (from password/WebAuthn/combined)
4. Server verifies signature
5. Session created

Session Management

• Secure Cookie Handling: HttpOnly, Secure, and SameSite cookie attributes
• Session Lifecycle Control: Configurable timeout and renewal policies
• Cross-Device Sessions: Support for multiple concurrent sessions
• Session Monitoring: Real-time session tracking and management

Security Features

• Rate Limiting: Configurable request rate limits per user and endpoint
• CORS Protection: Dynamic CORS policy based on registered origins
• EdDSA Signatures: Cryptographic signature verification for critical operations
• Audit Logging: Comprehensive security event logging
• IP Geolocation: Geographic tracking of authentication attempts

API Gateway Capabilities

Reverse Proxy

• Dynamic Routing: Database-driven routing configuration
• Load Balancing: Distribute requests across multiple backend services
• SSL Termination: Handle SSL/TLS encryption at the gateway level
• Request Transformation: Modify requests before forwarding to internal services

Routing Features

• Path-Based Routing: Route requests based on URL paths
• Header-Based Routing: Route based on request headers
• Query Parameter Routing: Dynamic routing based on query parameters
• Version Management: API versioning support

Performance Optimization

• Response Caching: HTTP response caching with configurable policies
• Connection Pooling: Efficient connection management to backend services
• Compression: Automatic response compression
• Keep-Alive Connections: Persistent connections for improved performance

Web Server Functions

Static File Serving

• Memory Caching: High-performance static file serving from memory
• Compression Support: Automatic file compression (gzip, brotli)
• ETags: Efficient cache validation
• Cache Headers: Optimized cache control headers

PWA Support

• Service Worker Support: Full Progressive Web App capabilities
• Manifest Handling: Automatic PWA manifest serving
• Offline Support: Cache strategies for offline functionality
• App Shell Architecture: Optimized loading for PWA applications
• Web Push Delivery: Browser push subscription lifecycle and service worker push handling for background notifications

SPA Routing

• Client-Side Routing: Support for single-page application routing
• Fallback Handling: Automatic fallback to index.html for SPA routes
• Base Path Configuration: Support for applications served from subdirectories

Administrative Features

User Management

• User Account Administration: Create, modify, and deactivate user accounts
• Authentication Method Management: Configure available authentication methods per user
• Access Control: Manage user permissions and access levels
• Bulk Operations: Batch user management operations

System Monitoring

• Real-Time Dashboards: Live system status and performance metrics
• Authentication Logs: Detailed authentication attempt logging
• Session Analytics: Session duration and usage statistics
• Error Tracking: Comprehensive error logging and monitoring

Configuration Management

• Route Configuration: Dynamic API route management
• CORS Policy Management: Configure allowed origins and headers
• Rate Limit Configuration: Adjust rate limiting policies
• Feature Toggles: Enable/disable features without deployment

Integration Capabilities

ItBuild Module Integration

• Seamless Module Communication: Native integration with other ItBuild modules
• Shared Authentication: Single sign-on across all modules
• Configuration Synchronization: Centralized configuration management
• Event Coordination: Inter-module event handling
• Dual Notification Transport: SSE for active tabs, Web Push for background delivery

Browser Push Notifications

AuthProxy supports browser Web Push alongside the existing SSE EventHub.

How it works

1. Frontend obtains a VAPID public key from AuthProxy.
2. Browser creates a push subscription through the root service worker.
3. AuthProxy stores the subscription in its own database.
4. EventPoller continues to normalize module events into BroadcastEvent.
5. Live tabs receive the event through SSE.
6. Background browsers can receive the same event through Web Push.

Why both transports exist

• SSE is the best transport for live UI refresh and reconnectable cursors.
• Web Push is the best transport for notification center / tray delivery when the app is in the background.

In phase 1 multi-proxy deployments, one AuthProxy node is configured as the active push sender, mirroring the existing single-sender webhook pattern.

Setup and verification details are documented in Browser Push Notifications.

External Service Integration

• OAuth Providers: Support for external OAuth providers
• Webhook Support: Configurable webhook endpoints
• File Storage Integration: Support for local disk storage and HTTP file servers
• Notification Services: Integration with external notification providers

API Standards Compliance

• JSON-RPC Format: Standardized API response format
• OpenAPI Documentation: Automatic API documentation generation
• RESTful Principles: REST-compliant endpoint design
• Versioning Support: API version management

Development & Deployment

Development Features

• Hot Reload: Development-time configuration reloading
• Comprehensive Logging: Detailed logging for debugging
• Swagger UI: Interactive API documentation
• Health Checks: Built-in health monitoring endpoints

Production Features

• Docker Support: Containerized deployment
• Environment Configuration: Environment-specific settings
• Telemetry Integration: OpenTelemetry support for monitoring
• Graceful Shutdown: Proper application lifecycle management

Horizontal Scaling with Session Locality

AuthProxy uses a unique scaling approach with session locality - no synchronization overhead:

main.app.com (DNS Round Robin) → IP1, IP2, IP3
         ↓
Frontend probes p1.app.com, p2.app.com, p3.app.com in parallel
         ↓
Client switches to fastest responding proxy
         ↓
Session is LOCAL to this proxy (no Redis/shared state needed)

Benefits:

• No synchronization overhead between instances
• User "sticks" to nearest/fastest proxy
• Each AuthProxy instance is fully independent
• Simple deployment without shared state infrastructure

Configuration: DNS Round Robin + subdomain probing enabled in frontend

Audit Logging

Comprehensive authentication logging in login_log table:

Field	Description
IP Address	Client IP with geolocation
Device Info	User agent string
Screen Resolution	Browser viewport size
Device GUID	Fingerprint for device identification
Timezone	Client timezone
Browser Language	Preferred language

Rate Limiting

Fixed-window counters at multiple scopes for defense in depth:

• Per Connection: limits a single TCP connection (default: 10 RPS).
• Per IP: aggregate limit across all connections from one IP (configurable).
• Per Session: counter for authenticated users (RateLimitWindowSeconds).
• Per Public Key: app-to-app API call limits.
• Per Bandwidth: byte-level throttling for file transfers.

X-RateLimit-* headers reflect the active scope; see Rate Limiting for the full window semantics. The earlier "token bucket" wording was wrong — counters are fixed-window in production code.

Performance Benchmarks

Tested February 2026 (k6, Docker local environment):

Metric	Value
Peak throughput	14,000+ requests/sec
Proxy overhead vs nginx	+1.8ms (p95)
Concurrent users (0% errors)	500
Static file serving (p95)	< 2ms (from memory cache)
Auth pipeline overhead	~2ms (lock-free session lookup)