PLUGIN_TRUST.md

Plugin Trust Model and Lifecycle

StarForge supports third-party plugins through a shared-library extension system. This document describes the trust model, compatibility requirements, and the full plugin lifecycle.

---

Trust levels

Every installed plugin is assigned one of three trust levels at install time:

Level	When assigned	StarForge behaviour
local	Plugin installed via --path (no source URL)	Always loaded without warnings
trusted	Source URL matches a known trusted prefix	Loaded without warnings
unknown	Source URL provided but not in the allow-list	Warning shown on load; --force required to install

Trusted sources

Trusted sources are defined in the StarForge configuration (~/.starforge/config.toml). By default, it includes:

• https://github.com/Nanle-code/starforge-*
• https://github.com/StarForge-Labs/*
• https://crates.io/crates/starforge-plugin-*

Any other source is unknown unless explicitly added to the plugin_trust.trusted_sources list in your configuration.

---

Compatibility requirements

Plugins are native shared libraries loaded at runtime via libloading. Two compatibility checks run before a plugin is executed:

1. rustc ABI check — the plugin must be compiled with the same Rust toolchain version as StarForge. Mismatches cause undefined behaviour and are rejected immediately.

2. Core version check — the plugin's declared core_version major number must match the running StarForge major version. A plugin built for StarForge 0.x.y is incompatible with StarForge 1.x.y.

Both checks produce actionable error messages that tell you exactly what to rebuild.

---

Plugin lifecycle

Install

# From a local path (always trusted)
starforge plugin install my-plugin --path ./libstarforge_my_plugin.so

# From a trusted source URL
starforge plugin install my-plugin --source https://github.com/Nanle-code/starforge-my-plugin

# From an unknown source (requires --force)
starforge plugin install my-plugin \
    --path ./libstarforge_my_plugin.so \
    --source https://example.com/my-plugin \
    --force

List

starforge plugin list

Shows all installed plugins with their path, trust level, and source.

Load and execute

starforge plugin load          # loads and reports all installed plugins
starforge my-plugin <args>     # execute a loaded plugin as an external subcommand

Verify

starforge plugin verify              # verify all installed plugins
starforge plugin verify my-plugin    # verify a specific plugin

Checks:

• Library file exists on disk at the registered path
• Trust level is local or trusted

Uninstall

starforge plugin uninstall my-plugin

Removes the plugin from the registry. The library file on disk is not deleted — remove it manually if desired.

---

Building a plugin

Use the starforge-plugin-sdk crate:

# Cargo.toml
[dependencies]
starforge-plugin-sdk = { path = "crates/starforge-plugin-sdk" }

[lib]
crate-type = ["cdylib"]

use starforge_plugin_sdk::{export_plugin, Plugin, PluginRegistrar};

struct MyPlugin;

impl Plugin for MyPlugin {
    fn name(&self) -> &'static str { "my-plugin" }
    fn version(&self) -> &'static str { "0.1.0" }
    fn description(&self) -> &'static str { "My StarForge plugin" }
    fn execute(&self, args: &[String]) -> Result<(), String> {
        println!("Hello from my-plugin! args={:?}", args);
        Ok(())
    }
}

fn register(registrar: &mut dyn PluginRegistrar) {
    registrar.register_plugin(Box::new(MyPlugin));
}

export_plugin!(register);

Build with the same Rust toolchain used to build StarForge:

cargo build --release

---

Security considerations

• Never load plugins from sources you do not control.
• Prefer --path installs from artifacts you have reviewed.
• The --force flag bypasses the source trust warning but does not bypass the ABI/version compatibility checks — those run unconditionally.
• There is no code-signing verification beyond source classification. Use OS-level file integrity tools (e.g., sha256sum) if you need cryptographic assurance.