Core Services & Event Hub
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate is designed as a secure bastion host that mediates connections for SSH, HTTPS, MySQL, and PostgreSQL protocols. The core services and event hub architecture facilitate the orchestration of authentication, session management, and credential handling across these disparate protocols. By acting as a central gateway, Warpgate intercepts credentials, authenticates users against a local SQLite database, and establishes secure tunnels to target hosts.
The system is built using safe Rust and leverages a modular crate structure where warpgate-core provides the primary business logic and warpgate-common contains shared utilities and data structures. This architecture ensures that session recordings, configuration management, and protocol-specific handlers operate within a unified framework.
Sources: README.md:15-35, warpgate/src/main.rs:1-15
System Architecture
The Warpgate architecture centers on the Services struct, which acts as the primary container for shared system resources. These resources include the database connection pool, configuration state, and protocol-specific keys.
Core Service Components
| Component | Description | Source |
|---|---|---|
| Services | The main lifecycle and resource manager for the application. | warpgate/src/commands/setup.rs:200-205 |
| Database | SQLite backend managed via sea-orm and sqlx. | README.md:86-88, warpgate-core/Cargo.toml:48-50 |
| Event Handling | Internal signaling for session starts, ends, and recording status. | README.md:43-46 |
| Protocol Handlers | Specific implementations for SSH, HTTP, MySQL, and PostgreSQL. | warpgate/Cargo.toml:39-43 |
The following diagram illustrates how the Services object orchestrates different system modules during startup and execution:
The diagram shows the initialization flow where the CLI triggers the creation of the core Services which then provides shared resources to protocol listeners.
Sources: warpgate/src/main.rs:105-125, warpgate/src/commands/setup.rs:200-210
Service Initialization and Configuration
The Services::new() function is responsible for bootstrapping the application state. During this phase, it establishes a connection to the database defined in the WarpgateConfigStore.
Setup and Database Migration
During the setup command, the system initializes the database schema and creates a default administrator role (warpgate:admin) and user. This ensures that the event hub and management APIs have the necessary backing store to function immediately upon first run.
// Snippet of the setup process creating the admin user and role
let admin_role = Role::Entity::find()
.filter(Role::Column::Name.eq(BUILTIN_ADMIN_ROLE_NAME))
.all(&*db)
.await?
.into_iter()
.next()
.ok_or_else(|| anyhow::anyhow!("Database inconsistent: no admin role"))?;
Sources: warpgate/src/commands/setup.rs:210-220
Configuration Parameters
The configuration store (WarpgateConfigStore) defines the behavior of the core services, including listener endpoints and recording paths.
| Parameter | Type | Default | Description |
|---|---|---|---|
database_url | Secret | sqlite:db | Connection string for the persistence layer. |
recordings.enable | Boolean | true | Enables or disables session capture. |
http.listen | SocketAddr | [::]:8888 | Port and address for the web UI and proxy. |
ssh.enable | Boolean | true | Toggles the SSH bastion functionality. |
Sources: warpgate/src/commands/setup.rs:80-150
Event Lifecycle and Protocol Interaction
When a connection is received by a protocol listener (e.g., warpgate-protocol-ssh), it interacts with the Core Services to validate credentials.
Connection Flow Sequence
The sequence below demonstrates how a connection is handled across the core services:
The sequence diagram details the interaction between the protocol-specific handler and the central Core Services during authentication and session establishment.
Sources: README.md:43-50, warpgate-core/Cargo.toml:11-15, warpgate-common/Cargo.toml:10-15
Session Recording Service
One of the primary responsibilities of the Core Services is managing session recordings. If recordings.enable is true in the configuration, the service opens a file handle in the specified recordings directory (defaulting to a subdirectory in /var/lib/warpgate). The recording service receives binary streams from the protocol handlers and persists them for later playback via the Admin UI.
Sources: README.md:48-52, warpgate/src/commands/setup.rs:165-175
Authentication Mechanisms
Core services utilize several cryptographic libraries to ensure secure authentication:
- Argon2: Used for hashing and verifying user passwords stored in the database.
- TOTP: Supports Time-based One-Time Passwords for native 2FA.
- OpenID Connect: Facilitates SSO via the
warpgate-ssocrate integrated into core.
Sources: warpgate-core/Cargo.toml:11-13, 27-28, 41-42
Built-in Administrative Access
A special warpgate:admin role is defined in warpgate-core which grants full access to the management APIs. This role is assigned to the initial admin user created during the setup or unattended-setup commands.
Sources: warpgate/src/commands/setup.rs:215-230, warpgate-core/Cargo.toml:1-10
Conclusion
The Core Services and Event Hub form the backbone of Warpgate, providing the necessary infrastructure for protocol handlers to perform authentication and session management. By centralizing database access, configuration, and recording logic, the system maintains a high security posture while supporting multiple access protocols through a unified administrative interface.