OpenHuman Tauri Shell Modules Explained: core_process, core_rpc, cdp, and cef_profile

The OpenHuman desktop application uses four specialized Tauri shell modules—core_process, core_rpc, cdp, and cef_profile—to manage the embedded core lifecycle, authenticate RPC calls, control CEF webviews via Chrome DevTools Protocol, and handle Chromium profile data securely.

The OpenHuman project is a Rust-based Tauri application that embeds a local core service directly within the desktop UI process. These Tauri shell modules form the critical glue layer between the JavaScript frontend and the embedded backend, handling process lifecycle, secure communication, webview introspection, and profile management according to the tinyhumansai/openhuman source code.

Core Process Lifecycle with core_process

The core_process module in app/src-tauri/src/core_process.rs manages the OpenHuman core as a Tokio task inside the Tauri host. This tight coupling ensures the core's HTTP/JSON-RPC server starts and stops with the desktop application.

Token Generation and Port Handling

Security begins with token generation. The generate_rpc_token() function creates a 256-bit random hex token stored in CURRENT_RPC_TOKEN, passed in-memory to the embedded core via run_server_embedded_with_ready. This eliminates the risk of token exposure through command-line arguments.

Port management uses default_core_port() to detect stale listeners and perform safe takeovers. If the preferred port is busy, the system falls back to an alternate port and records this via PortFallbackNotice. The identify_listener and takeover_stale_listener functions handle the detection and recovery logic.

Idempotent Start and Graceful Shutdown

The ensure_running() method provides idempotent startup. It checks if a task is already running on the expected port using self.is_rpc_port_open() and returns early to prevent self-termination. For shutdown and restart operations, restart_lock() serializes concurrent requests while shutdown_token provides cancellation tokens for the Tokio task.

The module exposes the RPC endpoint via rpc_url() and rpc_token(), supplying the URL (http://127.0.0.1:<port>/rpc) and bearer token to the frontend through the core_rpc_token command.

Authenticated RPC Communication with core_rpc

The core_rpc module in app/src-tauri/src/core_rpc.rs provides utilities for secure communication with the embedded core.

The core_rpc_url_value() function returns the RPC endpoint, defaulting to 127.0.0.1:<port>/rpc when OPENHUMAN_CORE_RPC_URL is not set. For authentication, apply_auth(builder) inserts the Authorization: Bearer <token> header by retrieving the current token from crate::core_process::current_rpc_token() and adding it to a reqwest::RequestBuilder.

Chrome DevTools Protocol Integration with cdp

The cdp package in app/src-tauri/src/cdp/ wraps the Chrome DevTools Protocol to introspect and control CEF webviews rendering external providers like Gmail or Slack.

Session and Target Management

The session.rs file manages CDP sessions through SessionId, handling open, close, and command operations. The target.rs module enumerates available targets (pages, workers) and handles attachment. The conn.rs and in_process.rs files manage WebSocket-based connections and provide in-process mocks for testing.

DOM Snapshots and Input Simulation

For screen intelligence and OCR pipelines, snapshot.rs captures DOMSnapshot objects representing the full DOM state. The input.rs module sends mouse and keyboard events into specific targets, enabling automated interaction with provider pages.

CEF Profile Management with cef_profile

The cef_profile module in app/src-tauri/src/cef_profile.rs manages the Chromium Embedded Framework cache directory and user profiles.

Profile Directory Structure

The default_root_openhuman_dir() function selects between .openhuman (production) and .openhuman-staging based on the OPENHUMAN_APP_ENV environment variable. User-specific paths are constructed via user_openhuman_dir() and cache_dir_for_user(), creating …/users/<id>/cef directories with strict validation of the user_id string.

The read_active_user_id() function reads active_user.toml to determine the currently logged-in user, while configured_cache_path_from_env() respects the OPENHUMAN_CEF_CACHE_PATH override.

Secure Cache Purging

The PendingCefPurgeState struct queues directories for removal on the next launch, typically after a reset_local_data command. The is_trusted_queued_purge_path validation prevents path-traversal attacks by ensuring only legitimate cache directories are targeted for deletion.

Practical Implementation Examples

Starting the Embedded Core

use app::src_tauri::core_process::CoreProcessHandle;

// Create a handle for the default port (7788)
let core = CoreProcessHandle::new(7788);

// Ensure the core is running (idempotent)
core.ensure_running().await.map_err(|e| anyhow::anyhow!(e))?;

Making Authenticated RPC Calls

use reqwest::Client;
use app::src_tauri::core_rpc::{core_rpc_url_value, apply_auth};

async fn list_threads() -> Result<String, String> {
    let client = Client::new();
    let url = core_rpc_url_value() + "/openhuman.threads_list";
    let builder = client.post(&url);
    let builder = apply_auth(builder)?;
    let resp = builder.send().await.map_err(|e| e.to_string())?;
    resp.text().await.map_err(|e| e.to_string())
}

Capturing DOM Snapshots

use app::src_tauri::cdp::{target, session::Session, snapshot::DOMSnapshot};

async fn capture_snapshot() -> Result<DOMSnapshot, anyhow::Error> {
    // Attach to the first page target
    let target = target::list().await?.into_iter()
        .find(|t| t.r#type == "page")
        .ok_or_else(|| anyhow::anyhow!("no page target"))?;

    // Open a session
    let sess = Session::new(target.target_id).await?;

    // Request a snapshot
    let snap = DOMSnapshot::capture(&sess).await?;
    Ok(snap)
}

Scheduling CEF Cache Purges

use app::src_tauri::cef_profile::{
    default_root_openhuman_dir, read_active_user_id, PendingCefPurgeState,
};

fn schedule_purge() -> Result<(), String> {
    let root = default_root_openhuman_dir()?;
    let user_id = read_active_user_id(&root).ok_or("no active user")?;
    let purge_path = root.join("users").join(user_id).join("cef");

    // Load existing pending state (or start fresh)
    let mut state = PendingCefPurgeState::default();
    state.paths.push(purge_path.to_string_lossy().into());

    // Write back to the pending-purge marker file
    let marker = root.parent()
        .ok_or("cannot locate parent of root")?
        .join("openhuman_pending_cef_purge.toml");
    std::fs::write(marker, toml::to_string(&state).unwrap())
        .map_err(|e| e.to_string())
}

Summary

• The core_process module in app/src-tauri/src/core_process.rs handles the OpenHuman core lifecycle, including token generation, port management, and graceful shutdown.
• core_rpc utilities in app/src-tauri/src/core_rpc.rs provide secure RPC URL resolution and bearer token authentication via apply_auth().
• The cdp package enables Chrome DevTools Protocol integration for controlling CEF webviews, capturing DOM snapshots, and simulating input events.
• cef_profile manages Chromium cache directories and user profiles with security validations to prevent path-traversal attacks during cache purges.

Frequently Asked Questions

What is the purpose of the core_process module in OpenHuman?

The core_process module manages the OpenHuman core as an embedded Tokio task within the Tauri application. It handles the entire lifecycle including generating secure RPC tokens with generate_rpc_token(), managing port allocation with default_core_port(), and ensuring idempotent startup through ensure_running().

How does the cdp module interact with Chromium Embedded Framework webviews?

The cdp module implements a Chrome DevTools Protocol client that connects to CEF webviews via WebSocket connections defined in conn.rs. It enables the Tauri host to enumerate targets, create sessions through Session::new(), capture DOM snapshots using DOMSnapshot::capture(), and inject input events for automating interactions with external providers.

Why does OpenHuman use bearer tokens for RPC authentication instead of other methods?

OpenHuman uses in-memory bearer tokens generated by core_process and applied via core_rpc::apply_auth() to eliminate command-line exposure and prevent unauthorized access to the embedded core's JSON-RPC endpoint. The 256-bit random tokens are passed directly to the core during run_server_embedded_with_ready, ensuring only the owning Tauri process can authenticate requests.

How does cef_profile prevent security issues during cache deletion?

The cef_profile module implements strict path validation through is_trusted_queued_purge_path before executing any cache deletion. The PendingCefPurgeState queue ensures deletions occur only on application restart, and all paths are validated against the expected …/users/<id>/cef structure to prevent path-traversal attacks that could target arbitrary filesystem locations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}