//! 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 { 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, net_scopes: Vec, secret_grants: Vec, 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); 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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> { 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> { 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> { 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, CredentialModuleSnapshot)> { let (generations, records) = self.load_with_records(engine, None)?; Ok((generations, CredentialModuleSnapshot(records))) } pub(crate) fn credential_module_snapshot(&self) -> Result { 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 { Ok(self.credential_module_snapshot()? != *snapshot) } fn load_with_authority( &self, engine: &PluginEngine, auth_store: Option<&AuthStore>, ) -> Result> { self.load_with_records(engine, auth_store) .map(|(generations, _records)| generations) } fn load_with_records( &self, engine: &PluginEngine, auth_store: Option<&AuthStore>, ) -> Result<(Vec, Vec)> { 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 { 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> { 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 = document .nodes() .iter() .map(parse_record) .collect::>()?; 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 { let mut ordered: Vec = (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 { 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 { 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 { 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 { 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::>>()?; 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) -> 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::>(), [" 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::>(), ["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); } }