repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-harness/src/plugins/registry.rs
Raw//! Installed plugin records and development links (`SMH-SPEC-WASM0001`).
//!
//! Registry entries are explicit user decisions.
//! Package files are read only after their path was explicitly registered.
use super::{
Capability, NetScope, PluginPackage, canonical_grants, canonical_net_scopes,
native_path_from_identity, native_path_identity,
};
use crate::wasm::{PluginEngine, PluginGeneration, SecretGrantConfig};
use smith::error::{ProviderFault, Result, SmithError};
use smith_ai::auth::{AuthStore, CredentialKey};
use smith_ai::models::ProviderKind;
use std::collections::BTreeSet;
use std::io::Read;
use std::path::{Path, PathBuf};
const REGISTRY_FILE: &str = "registry.kdl";
const REGISTRY_BYTES_MAX: usize = 1024 * 1024;
/// Source tier for an explicitly registered user package.
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub enum PackageSource {
/// Hash-pinned package accepted by an explicit install operation.
Installed,
/// Canonical source directory intentionally loaded by reference.
DevLink,
}
impl PackageSource {
const fn text(self) -> &'static str {
match self {
Self::Installed => "installed",
Self::DevLink => "link",
}
}
fn parse(text: &str) -> Result<Self> {
match text {
"installed" => Ok(Self::Installed),
"link" => Ok(Self::DevLink),
_ => Err(registry_fault(format!("unknown package source {text}"))),
}
}
}
/// One persisted package decision and its bounded content identities.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PackageRecord {
source: PackageSource,
id: String,
root: PathBuf,
grants: Vec<Capability>,
net_scopes: Vec<NetScope>,
secret_grants: Vec<SecretGrantConfig>,
manifest_sha256: String,
artifact_sha256: String,
}
impl PackageRecord {
/// Source tier that selected this package.
#[must_use]
pub const fn source(&self) -> PackageSource {
self.source
}
/// Validated package identity recorded during registration.
#[must_use]
pub fn id(&self) -> &str {
&self.id
}
/// Exact canonical source directory.
#[must_use]
pub fn root(&self) -> &Path {
&self.root
}
/// Explicit capability grants fixed at install or link time.
#[must_use]
pub fn grants(&self) -> &[Capability] {
&self.grants
}
/// Explicit HTTP origins fixed at install or trust time.
#[must_use]
pub fn net_scopes(&self) -> &[NetScope] {
&self.net_scopes
}
/// Explicit secret authorities fixed at install or link time.
#[must_use]
pub fn secret_grants(&self) -> &[SecretGrantConfig] {
&self.secret_grants
}
/// SHA-256 of manifest observed at registration or latest dev-link load.
#[must_use]
pub fn manifest_sha256(&self) -> &str {
&self.manifest_sha256
}
/// SHA-256 of artifact observed at registration or latest dev-link load.
#[must_use]
pub fn artifact_sha256(&self) -> &str {
&self.artifact_sha256
}
}
/// Persistent installed-package and development-link registry.
pub struct PackageRegistry {
root: PathBuf,
path: PathBuf,
}
#[derive(Clone, Eq, PartialEq)]
pub(crate) struct CredentialModuleSnapshot(Vec<PackageRecord>);
impl PackageRegistry {
/// Registry rooted in Smith's XDG configuration area.
#[must_use]
pub fn at_default() -> Self {
Self::at(smith::config::plugin_registry_dir())
}
/// Registry rooted in an explicit Smith-owned directory.
#[must_use]
pub fn at(root: PathBuf) -> Self {
let path = root.join(REGISTRY_FILE);
Self { root, path }
}
/// Validate, hash, and atomically register one installed package.
///
/// # Errors
///
/// Returns without changing the registry when discovery, hashing, or guest
/// registration fails.
pub fn install(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
) -> Result<PackageRecord> {
self.install_with_net_scopes(engine, root, grants, &[])
}
/// Validate, hash, and atomically register one installed package with explicit HTTP origins.
///
/// # Errors
///
/// Returns without publication when package validation or static registration fails.
pub fn install_with_net_scopes(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
net_scopes: &[NetScope],
) -> Result<PackageRecord> {
self.install_with_authority(engine, root, grants, net_scopes, &[])
}
/// Validate, hash, and register one installed package with explicit secret authority.
///
/// # Errors
///
/// Returns without publication when package or authority validation fails.
pub fn install_with_authority(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
net_scopes: &[NetScope],
secret_grants: &[SecretGrantConfig],
) -> Result<PackageRecord> {
self.register(
engine,
root,
grants,
net_scopes,
secret_grants,
PackageSource::Installed,
)
}
/// Validate, hash, and atomically register one canonical development link.
///
/// # Errors
///
/// Returns without changing the registry when discovery, hashing, or guest
/// registration fails.
pub fn link(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
) -> Result<PackageRecord> {
self.link_with_net_scopes(engine, root, grants, &[])
}
/// Validate, hash, and atomically register one development link with explicit HTTP origins.
///
/// # Errors
///
/// Returns without publication when package validation or static registration fails.
pub fn link_with_net_scopes(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
net_scopes: &[NetScope],
) -> Result<PackageRecord> {
self.link_with_authority(engine, root, grants, net_scopes, &[])
}
/// Validate, hash, and register one development link with explicit secret authority.
///
/// # Errors
///
/// Returns without publication when package or authority validation fails.
pub fn link_with_authority(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
net_scopes: &[NetScope],
secret_grants: &[SecretGrantConfig],
) -> Result<PackageRecord> {
self.register(
engine,
root,
grants,
net_scopes,
secret_grants,
PackageSource::DevLink,
)
}
/// Remove every installed or development-link source for one plugin id.
///
/// # Errors
///
/// Returns a registry fault when the persistent record cannot be read or
/// atomically published.
pub fn remove(&self, id: &str) -> Result<bool> {
let mut records = self.read()?;
let before = records.len();
records.retain(|record| record.id != id);
if records.len() == before {
return Ok(false);
}
self.write(&records)?;
Ok(true)
}
/// List persisted records in deterministic source and identity order.
///
/// # Errors
///
/// Returns a registry fault when the store is invalid or too large.
pub fn list(&self) -> Result<Vec<PackageRecord>> {
self.read()
}
/// Load a complete candidate generation from persisted records.
///
/// Development links precede installed packages with the same plugin id.
/// Installed package hashes must match their install-time identities.
/// Development-link hashes are refreshed only after every candidate loads.
///
/// # Errors
///
/// Returns with no partially loaded output when any candidate fails.
pub fn load(
&self,
engine: &PluginEngine,
auth_store: &AuthStore,
) -> Result<Vec<PluginGeneration>> {
self.load_with_authority(engine, Some(auth_store))
}
/// Load trusted packages as credential-module candidates without their
/// ordinary network or stored-secret grants.
///
/// The selected module receives only the profile-bound OAuth authority.
///
/// # Errors
///
/// Returns with no partially loaded output when any candidate fails.
pub fn load_credential_modules(&self, engine: &PluginEngine) -> Result<Vec<PluginGeneration>> {
self.load_with_authority(engine, None)
}
/// Load credential modules and preserve identities from the exact package
/// bytes used to construct their candidate generations.
///
/// # Errors
///
/// Returns with no partially loaded output when any candidate fails.
pub(crate) fn load_credential_modules_with_snapshot(
&self,
engine: &PluginEngine,
) -> Result<(Vec<PluginGeneration>, CredentialModuleSnapshot)> {
let (generations, records) = self.load_with_records(engine, None)?;
Ok((generations, CredentialModuleSnapshot(records)))
}
pub(crate) fn credential_module_snapshot(&self) -> Result<CredentialModuleSnapshot> {
let records = self.read()?;
let mut selected = Vec::new();
for index in selected_indices(&records) {
let record = &records[index];
let package = PluginPackage::discover(&record.root, true)?;
if package.manifest().id() != record.id {
return Err(registry_fault(format!(
"registered package identity changed from {} to {}",
record.id,
package.manifest().id()
)));
}
let mut snapshot = record.clone();
snapshot.manifest_sha256 = hash_bytes(package.manifest_bytes());
snapshot.artifact_sha256 = hash_bytes(package.artifact_bytes());
selected.push(snapshot);
}
Ok(CredentialModuleSnapshot(selected))
}
pub(crate) fn credential_modules_changed(
&self,
snapshot: &CredentialModuleSnapshot,
) -> Result<bool> {
Ok(self.credential_module_snapshot()? != *snapshot)
}
fn load_with_authority(
&self,
engine: &PluginEngine,
auth_store: Option<&AuthStore>,
) -> Result<Vec<PluginGeneration>> {
self.load_with_records(engine, auth_store)
.map(|(generations, _records)| generations)
}
fn load_with_records(
&self,
engine: &PluginEngine,
auth_store: Option<&AuthStore>,
) -> Result<(Vec<PluginGeneration>, Vec<PackageRecord>)> {
let mut records = self.read()?;
let selected = selected_indices(&records);
let mut candidates = Vec::with_capacity(selected.len());
let mut selected_records = Vec::with_capacity(selected.len());
let mut changed = false;
for index in selected {
let record = &mut records[index];
let package = PluginPackage::discover(&record.root, true)?;
if package.manifest().id() != record.id {
return Err(registry_fault(format!(
"registered package identity changed from {} to {}",
record.id,
package.manifest().id()
)));
}
let manifest_sha256 = hash_bytes(package.manifest_bytes());
let artifact_sha256 = hash_bytes(package.artifact_bytes());
match record.source {
PackageSource::Installed => {
if record.manifest_sha256 != manifest_sha256
|| record.artifact_sha256 != artifact_sha256
{
return Err(registry_fault(format!(
"installed package {} changed since install; install it again",
record.id
)));
}
}
PackageSource::DevLink => {
changed |= record.manifest_sha256 != manifest_sha256
|| record.artifact_sha256 != artifact_sha256;
record.manifest_sha256 = manifest_sha256;
record.artifact_sha256 = artifact_sha256;
}
}
let mut generation = PluginGeneration::load_package(engine, package, &record.grants)?;
if let Some(auth_store) = auth_store {
generation.configure_net_scopes(record.net_scopes.clone());
generation.configure_secret_grants(
record
.secret_grants
.iter()
.map(|grant| grant.with_auth_store(auth_store.clone()))
.collect(),
);
}
candidates.push(generation);
selected_records.push(record.clone());
}
if changed {
self.write(&records)?;
}
Ok((candidates, selected_records))
}
fn register(
&self,
engine: &PluginEngine,
root: &Path,
grants: &[Capability],
net_scopes: &[NetScope],
secret_grants: &[SecretGrantConfig],
source: PackageSource,
) -> Result<PackageRecord> {
validate_secret_grants(grants, net_scopes, secret_grants)?;
let package = PluginPackage::discover(root, true)?;
let record = PackageRecord {
source,
id: package.manifest().id().to_string(),
root: package.root().to_path_buf(),
grants: canonical_grants(grants),
net_scopes: canonical_net_scopes(net_scopes),
secret_grants: secret_grants.to_vec(),
manifest_sha256: hash_bytes(package.manifest_bytes()),
artifact_sha256: hash_bytes(package.artifact_bytes()),
};
let mut candidate = PluginGeneration::load_package(engine, package, &record.grants)?;
candidate.configure_net_scopes(record.net_scopes.clone());
let mut records = self.read()?;
records.retain(|current| !(current.id == record.id && current.source == source));
records.push(record.clone());
records.sort_by(|left, right| {
(left.id.as_str(), left.source.text()).cmp(&(right.id.as_str(), right.source.text()))
});
self.write(&records)?;
Ok(record)
}
fn path(&self) -> &Path {
&self.path
}
fn read(&self) -> Result<Vec<PackageRecord>> {
let path = self.path();
let file = match std::fs::File::open(path) {
Ok(file) => file,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
Err(error) => return Err(registry_fault(format!("registry read failed: {error}"))),
};
let metadata = file
.metadata()
.map_err(|error| registry_fault(format!("registry metadata failed: {error}")))?;
if metadata.len() > REGISTRY_BYTES_MAX as u64 {
return Err(registry_fault(format!(
"registry exceeds byte limit of {REGISTRY_BYTES_MAX}"
)));
}
let mut bytes = Vec::new();
bytes
.try_reserve_exact(
usize::try_from(metadata.len())
.map_err(|_| registry_fault("registry exceeds addressable memory"))?,
)
.map_err(|_| registry_fault("registry allocation failed"))?;
#[expect(
clippy::disallowed_methods,
reason = "Take caps the registry read at REGISTRY_BYTES_MAX + 1"
)]
file.take((REGISTRY_BYTES_MAX + 1) as u64)
.read_to_end(&mut bytes)
.map_err(|error| registry_fault(format!("registry read failed: {error}")))?;
if bytes.len() > REGISTRY_BYTES_MAX {
return Err(registry_fault(format!(
"registry exceeds byte limit of {REGISTRY_BYTES_MAX}"
)));
}
let source = std::str::from_utf8(&bytes)
.map_err(|error| registry_fault(format!("registry is not UTF-8: {error}")))?;
let document: kdl::KdlDocument = source
.parse()
.map_err(|error| registry_fault(format!("invalid package registry: {error}")))?;
let mut records: Vec<PackageRecord> = document
.nodes()
.iter()
.map(parse_record)
.collect::<Result<_>>()?;
records.sort_by(|left, right| {
(left.id.as_str(), left.source.text()).cmp(&(right.id.as_str(), right.source.text()))
});
if records
.windows(2)
.any(|pair| pair[0].id == pair[1].id && pair[0].source == pair[1].source)
{
return Err(registry_fault("duplicate package registry record"));
}
Ok(records)
}
fn write(&self, records: &[PackageRecord]) -> Result<()> {
std::fs::create_dir_all(&self.root).map_err(|error| {
registry_fault(format!("registry directory creation failed: {error}"))
})?;
let temporary = self.root.join("registry.kdl.new");
std::fs::write(&temporary, render(records))
.map_err(|error| registry_fault(format!("registry write failed: {error}")))?;
std::fs::rename(&temporary, &self.path)
.map_err(|error| registry_fault(format!("registry publication failed: {error}")))
}
}
fn selected_indices(records: &[PackageRecord]) -> Vec<usize> {
let mut ordered: Vec<usize> = (0..records.len()).collect();
ordered.sort_by(|left, right| {
let left = &records[*left];
let right = &records[*right];
(left.id.as_str(), std::cmp::Reverse(left.source))
.cmp(&(right.id.as_str(), std::cmp::Reverse(right.source)))
});
let mut ids = BTreeSet::new();
ordered.retain(|index| ids.insert(records[*index].id.clone()));
ordered
}
fn parse_record(node: &kdl::KdlNode) -> Result<PackageRecord> {
if node.name().value() != "package" || node.entries().len() != 5 {
return Err(registry_fault("invalid package registry record"));
}
let text = |index| {
node.entry(index)
.and_then(|entry| entry.value().as_string())
.filter(|value| !value.is_empty())
.map(str::to_string)
.ok_or_else(|| registry_fault("package registry record requires string fields"))
};
let source = PackageSource::parse(&text(0)?)?;
let id = text(1)?;
let root = native_path_from_identity(&text(2)?)
.map_err(|_| registry_fault("package registry contains invalid native path"))?;
let manifest_sha256 = text(3)?;
let artifact_sha256 = text(4)?;
if !valid_sha256(&manifest_sha256) || !valid_sha256(&artifact_sha256) {
return Err(registry_fault("package registry contains invalid SHA-256"));
}
let (grants, net_scopes, secret_grants) = node.children().map_or_else(
|| Ok((Vec::new(), Vec::new(), Vec::new())),
|children| {
let mut grants = Vec::new();
let mut net_scopes = Vec::new();
let mut secret_grants = Vec::new();
for child in children.nodes() {
match child.name().value() {
"grant" => grants.push(parse_grant(child)?),
"net-origin" => net_scopes.push(parse_net_scope(child)?),
"secret-grant" => secret_grants.push(parse_secret_grant(child)?),
_ => return Err(registry_fault("invalid package registry authority")),
}
}
Ok((grants, net_scopes, secret_grants))
},
)?;
Ok(PackageRecord {
source,
id,
root,
grants: canonical_grants(&grants),
net_scopes: canonical_net_scopes(&net_scopes),
secret_grants,
manifest_sha256,
artifact_sha256,
})
}
fn parse_grant(node: &kdl::KdlNode) -> Result<Capability> {
let value = node
.entries()
.first()
.and_then(|entry| entry.value().as_string())
.filter(|_| node.name().value() == "grant" && node.entries().len() == 1)
.ok_or_else(|| registry_fault("invalid package registry grant"))?;
Capability::parse(value).map_err(|_| registry_fault(format!("unknown package grant {value}")))
}
fn parse_net_scope(node: &kdl::KdlNode) -> Result<NetScope> {
let value = node
.entries()
.first()
.and_then(|entry| entry.value().as_string())
.filter(|_| node.name().value() == "net-origin" && node.entries().len() == 1)
.ok_or_else(|| registry_fault("invalid package registry net origin"))?;
NetScope::parse(value)
}
fn parse_secret_grant(node: &kdl::KdlNode) -> Result<SecretGrantConfig> {
if node.name().value() != "secret-grant" || node.entries().len() < 4 {
return Err(registry_fault("invalid package registry secret grant"));
}
let text = |index| {
node.entry(index)
.and_then(|entry| entry.value().as_string())
.filter(|value| !value.is_empty())
.ok_or_else(|| registry_fault("invalid package registry secret grant"))
};
let key = match text(1)? {
"openai" => CredentialKey::Provider(ProviderKind::OpenAiCompatible),
"anthropic" => CredentialKey::Provider(ProviderKind::Anthropic),
"google" => CredentialKey::Provider(ProviderKind::Google),
"zai" => CredentialKey::Provider(ProviderKind::Zai),
"zai-coding-plan" => CredentialKey::ZaiCodingPlan,
_ => return Err(registry_fault("invalid package registry secret provider")),
};
let scopes = (3..node.entries().len())
.map(|index| text(index).map(str::to_string))
.collect::<Result<Vec<_>>>()?;
SecretGrantConfig::new(
text(0)?.to_string(),
NetScope::parse(text(2)?)?,
scopes,
key,
)
}
fn validate_secret_grants(
grants: &[Capability],
net_scopes: &[NetScope],
secret_grants: &[SecretGrantConfig],
) -> Result<()> {
if secret_grants.is_empty() {
return Ok(());
}
if !grants.contains(&Capability::SecretProxy) || !grants.contains(&Capability::NetScope) {
return Err(registry_fault(
"secret authority requires secret-proxy and net-scope grants",
));
}
if secret_grants.iter().any(|grant| {
!net_scopes
.iter()
.any(|scope| scope.as_str() == grant.origin().as_str())
}) {
return Err(registry_fault(
"secret authority origin must also be an explicit net-scope origin",
));
}
Ok(())
}
fn render(records: &[PackageRecord]) -> String {
let mut text = String::new();
for record in records {
text.push_str("package ");
kdl_string(&mut text, record.source.text());
text.push(' ');
kdl_string(&mut text, &record.id);
text.push(' ');
kdl_string(&mut text, &native_path_identity(&record.root));
text.push(' ');
kdl_string(&mut text, &record.manifest_sha256);
text.push(' ');
kdl_string(&mut text, &record.artifact_sha256);
text.push_str(" {\n");
for grant in &record.grants {
text.push_str(" grant ");
kdl_string(&mut text, grant.name());
text.push('\n');
}
for scope in &record.net_scopes {
text.push_str(" net-origin ");
kdl_string(&mut text, scope.as_str());
text.push('\n');
}
for grant in &record.secret_grants {
text.push_str(" secret-grant ");
kdl_string(&mut text, grant.source_id());
text.push(' ');
kdl_string(&mut text, grant.credential_key().slug());
text.push(' ');
kdl_string(&mut text, grant.origin().as_str());
for scope in grant.scopes() {
text.push(' ');
kdl_string(&mut text, scope);
}
text.push('\n');
}
text.push_str("}\n");
}
text
}
fn kdl_string(output: &mut String, value: &str) {
output.push('"');
for character in value.chars() {
match character {
'\\' => output.push_str("\\\\"),
'"' => output.push_str("\\\""),
'\n' => output.push_str("\\n"),
'\r' => output.push_str("\\r"),
'\t' => output.push_str("\\t"),
character if character.is_control() => {
use std::fmt::Write;
assert!(
write!(output, "\\u{{{:x}}}", u32::from(character)).is_ok(),
"writing into String is infallible"
);
}
character => output.push(character),
}
}
output.push('"');
}
fn hash_bytes(bytes: &[u8]) -> String {
smith::sha256::digest_hex(bytes)
}
fn valid_sha256(value: &str) -> bool {
value.len() == 64 && value.bytes().all(|byte| byte.is_ascii_hexdigit())
}
fn registry_fault(message: impl Into<String>) -> SmithError {
SmithError::Provider {
fault: ProviderFault::Plugin {
message: message.into(),
},
}
}
#[cfg(test)]
mod tests {
//! Registry persistence tests (`SMH-SPEC-PLUG0001`).
use super::*;
#[cfg(unix)]
#[test]
fn registry_roundtrips_non_utf8_package_root() {
use std::os::unix::ffi::OsStringExt;
let scratch =
std::env::temp_dir().join(format!("smith-registry-path-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&scratch);
let registry = PackageRegistry::at(scratch.clone());
let root = PathBuf::from(std::ffi::OsString::from_vec(b"/tmp/smith-\xff".to_vec()));
let records = [PackageRecord {
source: PackageSource::Installed,
id: "example:nonutf8".to_string(),
root: root.clone(),
grants: canonical_grants(&[
Capability::Process,
Capability::NetScope,
Capability::Process,
]),
net_scopes: canonical_net_scopes(&[
NetScope::parse("https://z.example.test").unwrap(),
NetScope::parse("https://a.example.test").unwrap(),
NetScope::parse("https://z.example.test").unwrap(),
]),
secret_grants: Vec::new(),
manifest_sha256: "0".repeat(64),
artifact_sha256: "1".repeat(64),
}];
registry.write(&records).unwrap();
let persisted = std::fs::read_to_string(registry.path()).unwrap();
assert!(persisted.contains("unix:"));
assert_eq!(registry.list().unwrap()[0].root(), root);
assert_eq!(
persisted
.lines()
.filter(|line| line.trim_start().starts_with("grant "))
.collect::<Vec<_>>(),
[" grant \"net-scope\"", " grant \"process\""]
);
assert_eq!(
persisted
.lines()
.filter_map(|line| {
line.trim_start()
.strip_prefix("net-origin ")
.map(|scope| scope.trim_matches('"'))
})
.collect::<Vec<_>>(),
["https://a.example.test", "https://z.example.test"]
);
let record = ®istry.list().unwrap()[0];
assert_eq!(record.grants(), [Capability::NetScope, Capability::Process]);
assert_eq!(
record.net_scopes(),
[
NetScope::parse("https://a.example.test").unwrap(),
NetScope::parse("https://z.example.test").unwrap(),
]
);
let _ = std::fs::remove_dir_all(&scratch);
}
}