homecore_plugins/lib.rs
1//! HOMECORE-PLUGINS — WASM integration plugin system.
2//!
3//! Implements [ADR-128](../../docs/adr/ADR-128-homecore-integration-plugin-system.md)
4//! P1 scaffold: manifest parsing, the `HomeCorePlugin` async trait, the
5//! `PluginRuntime` abstraction, and the `PluginRegistry`.
6//!
7//! ## What's here (P1)
8//!
9//! - [`manifest`] — `PluginManifest`: superset of HA `manifest.json`; serde
10//! round-trip + required-field validation.
11//! - [`plugin`] — `HomeCorePlugin` async trait, `PluginId` newtype.
12//! - [`runtime`] — `PluginRuntime` trait + `InProcessRuntime` (native Rust,
13//! first-party plugins compiled into the binary).
14//! - [`registry`] — `PluginRegistry<R>`: load / unload / list plugins.
15//! - [`error`] — `PluginError` typed error enum.
16//!
17//! ## Runtime scope
18//!
19//! - `WasmtimeRuntime` (`--features wasmtime`) provides the Cranelift sandbox.
20//! - Native Rust plugins are compiled into the server; arbitrary native
21//! dynamic libraries are not loaded.
22//! - The host ABI is deliberately narrow and resource-bounded.
23//!
24//! ## Now enforced (ADR-162)
25//!
26//! - **Ed25519 signature + SHA-256 integrity verification (P4)** — see
27//! [`verify`]: the plugin load path hashes the real `.wasm` bytes, checks
28//! the manifest `wasm_module_hash`, verifies `wasm_module_sig` against
29//! `publisher_key`, and enforces a [`verify::PluginPolicy`] allowlist.
30//! - **Permission / authority isolation (P5)** — see [`permissions`]: a
31//! plugin's `hc_state_set` writes are gated against the entity domains/
32//! globs it declared in `homecore_permissions`.
33//!
34//! ## Feature flags
35//!
36//! | Feature | Default | Description |
37//! |---------|---------|-------------|
38//! | `wasmtime` | off | Wasmtime Cranelift JIT runtime (P2) |
39
40pub mod error;
41pub mod discovery;
42pub mod host_abi;
43pub mod manifest;
44pub mod permissions;
45pub mod plugin;
46pub mod registry;
47pub mod runtime;
48pub mod verify;
49
50#[cfg(feature = "wasmtime")]
51pub mod wasmtime_runtime;
52
53pub use error::PluginError;
54pub use discovery::{discover_plugins, DiscoveredPlugin, DiscoveryLimits};
55pub use host_abi::{ConfigEntryJson, StateChangedEventJson};
56pub use manifest::{IotClass, IntegrationType, PluginManifest};
57pub use permissions::PermissionSet;
58pub use plugin::{HomeCorePlugin, PluginId};
59pub use registry::PluginRegistry;
60pub use runtime::{InProcessRuntime, LoadedPlugin, PluginRuntime};
61pub use verify::{verify_module, PluginPolicy};
62
63#[cfg(feature = "wasmtime")]
64pub use wasmtime_runtime::{WasmPlugin, WasmtimeRuntime};
65
66#[cfg(test)]
67mod tests;