# Security Measures for TinyBus Admitted Native Modules in OpenHuman

> Discover OpenHuman's robust security for TinyBus native modules. Explore SHA-256 verification, ABI compatibility, runtime sandboxing, and audit logging to protect your core process.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: security-measures
- Published: 2026-08-28

---

**OpenHuman implements a defense-in-depth security model for TinyBus admitted native modules that includes cryptographic SHA-256 verification, strict ABI compatibility gates, runtime sandboxing with panic isolation, and comprehensive audit logging to prevent unauthorized or compromised code from executing in the core process.**

The OpenHuman runtime extends its capabilities through the TinyBus module system, which allows **TinyBus admitted native modules** to be dynamically loaded into the core process. When admitting these native extensions, the framework enforces a multi-layered security protocol designed to guarantee that only trusted, compatible code gains execution privileges according to the source code in `tinyhumansai/openhuman`.

## Manifest Validation and Cryptographic Integrity

Every TinyBus module must ship a manifest that declares supported ABI versions, required TinyBus versions, and allowed capabilities. The core parses this manifest in [`src/openhuman/modules/registry.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/registry.rs) and rejects any module that does not declare the exact ABI version the core expects.

Before loading, the system performs **SHA-256 digest verification**. The manifest contains a cryptographic hash of the module binary, and at load time the core computes the hash of the downloaded file and compares it with the manifest entry. A mismatch aborts the load immediately, preventing tampered binaries from execution. This logic resides in [`src/openhuman/modules/registry.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/registry.rs) between lines 45-62.

## ABI Compatibility Gates

OpenHuman enforces a **two-sided ABI gate** to prevent version conflicts. The core checks that the module's compiled TinyBus ABI matches the host's ABI down to the major and minor version numbers. This check, implemented in [`src/openhuman/modules/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/mod.rs) at lines 30-38, stops modules built against incompatible TinyBus versions from being linked into the core process.

## Runtime Sandboxing and Fault Isolation

Native modules are loaded via `dlopen` into the same address space, but the TinyBus runtime isolates them behind **bounded queues**, **timeouts**, and **panic-catchers**. Any panic occurring within a module is caught and converted into a module-failure event rather than crashing the entire process. This sandboxing implementation appears in [`src/openhuman/modules/loader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/loader.rs) at lines 78-95.

## Compile-Time Configuration and Fail-Closed Defaults

The framework supports **configuration gating** through the core's `DomainSet` and Cargo feature flags. When the `modules` feature is disabled at compile time, the stubs become compile-time-only and the admission code is not linked, guaranteeing that no module-related code can be invoked. This gating logic is defined in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs) at lines 112-123.

If a module fails any validation check, the core implements **fail-closed defaults** by registering the module as "unavailable" and continuing operation with built-in fallback implementations. This ensures that broken or untrusted modules never silently degrade functionality. The failure handling is implemented in [`src/openhuman/modules/loader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/loader.rs) at lines 110-118.

## Auditability and Event Logging

Every admitted module generates a `ModuleLoadEvent` on the global event bus. These logs include the module name, hash, checksum result, and load outcome, making post-mortem analysis straightforward. The event definitions and bus integration reside in [`src/core/event_bus/modules.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/event_bus/modules.rs).

## Practical Implementation Examples

### Loading a Module with Full Verification

```rust
use openhuman::modules::{ModuleRegistry, ModuleLoader};
use std::path::Path;

fn load_trusted_module(name: &str, dir: &Path) -> Result<(), ModuleLoadError> {
    // 1. Resolve the module entry from the compiled-in registry
    let entry = ModuleRegistry::lookup(name)?;
    
    // 2. Download the artifact and verify its SHA-256 digest
    let artifact = entry.fetch_artifact(dir)?;
    entry.verify_digest(&artifact)?;
    
    // 3. Perform ABI compatibility check
    entry.ensure_abi_compatible()?;
    
    // 4. Load the module with TinyBus runtime; panics are caught
    ModuleLoader::load(&artifact)
}

```

### Handling Load Failures Gracefully

```rust
match load_trusted_module("tinydocs", &modules_dir) {
    Ok(_) => log::info!("tinydocs module loaded successfully"),
    Err(e) => {
        log::error!("Failed to load tinydocs: {}", e);
        // The core falls back to its built-in stub implementation
        fallback_to_builtin("tinydocs");
    }
}

```

### Subscribing to Module Load Events

```rust
use openhuman::core::event_bus::EventBus;

fn subscribe_to_module_loads(bus: &EventBus) {
    bus.subscribe_global("modules.load", |event| {
        println!("Module load event: {:?}", event);
    });
}

```

## Summary

- **Manifest validation** and **SHA-256 verification** in [`registry.rs`](https://github.com/tinyhumansai/openhuman/blob/main/registry.rs) ensure only cryptographically intact modules are considered for loading.
- **Two-sided ABI gates** in [`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs) prevent version mismatches between the core and native modules.
- **Runtime sandboxing** with panic-catching and bounded queues in [`loader.rs`](https://github.com/tinyhumansai/openhuman/blob/main/loader.rs) isolates faults to prevent core process crashes.
- **Compile-time feature gates** in [`builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/builder.rs) allow complete elimination of module loading code when not required.
- **Fail-closed defaults** ensure that validation failures result in safe fallback to built-in implementations rather than degraded operation.
- **Comprehensive audit logging** via `ModuleLoadEvent` provides full traceability of module admission decisions.

## Frequently Asked Questions

### What happens if a TinyBus module fails the SHA-256 checksum verification?

If the computed hash of the module binary does not match the SHA-256 digest declared in the manifest, the core aborts the loading process immediately. The module is marked as unavailable, and the system falls back to built-in implementations without executing the compromised binary.

### How does OpenHuman prevent ABI version mismatches in native modules?

The core enforces a two-sided ABI compatibility check that verifies the module's compiled TinyBus ABI matches the host's ABI version exactly. This check occurs in [`src/openhuman/modules/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/mod.rs) before any dynamic linking occurs, preventing incompatible modules from being loaded.

### Can the native module system be completely disabled at compile time?

Yes. Through Cargo feature gates and the `DomainSet` configuration shown in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs), the entire `modules` family can be disabled at compile time. When disabled, only compile-time stubs remain, and no module admission code is linked into the final binary.

### What logging is available when a module fails to load?

Every module load attempt generates a `ModuleLoadEvent` on the global event bus, implemented in [`src/core/event_bus/modules.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/event_bus/modules.rs). These events include the module name, expected hash, verification results, and final load status, providing complete audit trails for security analysis.