//! Plugin package manifest parsing (`SMH-SPEC-WASM0001`, identity and //! installation). //! //! This module bounds and validates the manifest's identity, artifact, world, //! and requested capabilities. use smith::error::{ProviderFault, Result, SmithError}; use std::io::Read; use std::path::{Path, PathBuf}; /// Persisted installed package records and development links. pub mod registry; /// Deterministic guest fixtures through mocked host capabilities. pub mod test; /// Persisted project trust decisions and capability grants. pub mod trust; /// Decode the supported provider setting from bounded KDL source. pub(crate) fn parse_provider_settings(input: &str, source: &Path) -> Result> { let document: kdl::KdlDocument = input.parse().map_err(|error| SmithError::Config { field: format!("{}:provider-settings", source.display()), message: format!("invalid provider settings KDL: {error:?}"), })?; let mut include_usage = None; for node in document.nodes() { let name = node.name().value(); let field = format!("{}:{name}", source.display()); if name != "include-usage" { return Err(SmithError::Config { field, message: format!("unknown provider setting {name}"), }); } if include_usage.is_some() { return Err(SmithError::Config { field, message: "duplicate provider setting include-usage".into(), }); } if node.entries().len() != 1 || node.entries()[0].name().is_some() || node.children().is_some() { return Err(SmithError::Config { field, message: "include-usage requires one boolean argument without properties or children" .into(), }); } let Some(value) = node.entry(0).and_then(|entry| entry.value().as_bool()) else { return Err(SmithError::Config { field, message: "include-usage requires one boolean argument".into(), }); }; include_usage = Some(value); } Ok(include_usage) } /// Maximum encoded size of a plugin manifest. pub const MANIFEST_BYTE_LIMIT: usize = 64 * 1024; /// A host effect requested by a plugin package. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum Capability { /// Scoped network HTTP effect. NetScope, /// Credential exchange effect. SecretProxy, /// Bounded diagnostic logging effect. Log, /// Scoped workspace filesystem effects. Workspace, /// Supervised external process effect. Process, } /// One explicit HTTP origin granted at trust or install time. #[derive(Clone, Debug, Eq, PartialEq)] pub struct NetScope(String); impl NetScope { /// Parse and canonicalize one HTTP origin. /// /// HTTPS origins may name production hosts. /// HTTP origins are limited to literal loopback for local testing. /// /// # Errors /// /// Returns a plugin fault for an unscoped scheme, authority, path, query, or port. pub fn parse(origin: &str) -> Result { let (scheme, authority) = origin .split_once("://") .ok_or_else(|| manifest_fault("net-scope origin requires an HTTP scheme"))?; if !matches!(scheme, "https" | "http") || authority.is_empty() || authority.contains(['/', '?', '#', '@']) || authority.bytes().any(|byte| byte.is_ascii_whitespace()) { return Err(manifest_fault( "net-scope origin must be HTTPS or literal-loopback HTTP without path, query, fragment, or credentials", )); } let host = authority .split_once(':') .map_or(authority, |(host, _)| host); if scheme == "http" && host != "127.0.0.1" { return Err(manifest_fault( "net-scope HTTP origin must use literal loopback 127.0.0.1", )); } if let Some((_, port)) = authority.split_once(':') && (port.is_empty() || port.parse::().is_err()) { return Err(manifest_fault("net-scope origin has an invalid port")); } Ok(Self(origin.to_string())) } /// Canonical origin text supplied to the host effect boundary. #[must_use] pub fn as_str(&self) -> &str { &self.0 } } impl Capability { /// Manifest spelling used in capability diagnostics. #[must_use] pub const fn name(self) -> &'static str { match self { Self::NetScope => "net-scope", Self::SecretProxy => "secret-proxy", Self::Log => "log", Self::Workspace => "workspace", Self::Process => "process", } } pub(crate) fn parse(value: &str) -> Result { match value { "net-scope" => Ok(Self::NetScope), "secret-proxy" => Ok(Self::SecretProxy), "log" => Ok(Self::Log), "workspace" => Ok(Self::Workspace), "process" => Ok(Self::Process), _ => Err(manifest_fault(format!("unknown capability {value}"))), } } } /// A trusted package's manifest and confined component artifact. #[derive(Clone, Debug, Eq, PartialEq)] pub struct PluginPackage { root: PathBuf, manifest_path: PathBuf, manifest: PluginManifest, manifest_bytes: Vec, artifact_bytes: Vec, } impl PluginPackage { /// Discover a package only after its project trust decision is positive. /// /// `project_trusted` is supplied by the trust resolver; rejection happens /// before resolving or reading any package path. /// /// # Errors /// /// Returns a plugin fault when trust is absent, package files are invalid, /// the manifest exceeds its bound, or its artifact escapes the package. pub fn discover(package_root: &Path, project_trusted: bool) -> Result { if !project_trusted { return Err(manifest_fault( "project plugin is untrusted; trust the project before loading its package", )); } let package_root = std::fs::canonicalize(package_root) .map_err(|error| manifest_fault(format!("package discovery failed: {error}")))?; let manifest_path = std::fs::canonicalize(package_root.join("plugin.kdl")).map_err(|error| { manifest_fault(format!("package manifest is missing or invalid: {error}")) })?; if !manifest_path.starts_with(&package_root) { return Err(manifest_fault("manifest escapes the declared package root")); } let manifest_bytes = read_bounded(&manifest_path, MANIFEST_BYTE_LIMIT, "manifest")?; let source = std::str::from_utf8(&manifest_bytes) .map_err(|error| manifest_fault(format!("manifest is not UTF-8: {error}")))?; let manifest = PluginManifest::parse(source)?; let artifact_path = std::fs::canonicalize(package_root.join(manifest.artifact())).map_err(|error| { manifest_fault(format!("package artifact is missing or invalid: {error}")) })?; if !artifact_path.starts_with(&package_root) { return Err(manifest_fault( "package artifact escapes the declared package root", )); } let artifact_bytes = read_bounded(&artifact_path, crate::wasm::ARTIFACT_BYTES_MAX, "artifact")?; Ok(Self { root: package_root, manifest_path, manifest, manifest_bytes, artifact_bytes, }) } /// Canonical package root containing its manifest and artifact. #[must_use] pub fn root(&self) -> &Path { &self.root } /// Canonical manifest path confined to the package root. #[must_use] pub fn manifest_path(&self) -> &Path { &self.manifest_path } /// Validated package manifest. #[must_use] pub const fn manifest(&self) -> &PluginManifest { &self.manifest } /// Exact manifest bytes parsed during discovery. #[must_use] pub fn manifest_bytes(&self) -> &[u8] { &self.manifest_bytes } /// Exact component bytes read during discovery. #[must_use] pub fn artifact_bytes(&self) -> &[u8] { &self.artifact_bytes } pub(crate) fn into_parts(self) -> (PluginManifest, Vec) { (self.manifest, self.artifact_bytes) } } /// Validated identity and requested effects for one plugin artifact. #[derive(Clone, Debug, Eq, PartialEq)] pub struct PluginManifest { id: String, version: String, world_version: String, artifact: String, capabilities: Vec, source: Option, } impl PluginManifest { /// Parse one KDL manifest. /// /// # Errors /// /// Returns a plugin fault when input exceeds [`MANIFEST_BYTE_LIMIT`], KDL /// or field syntax is invalid, required data is absent or empty, fields are /// repeated, or a requested capability is unknown or repeated. pub fn parse(input: &str) -> Result { if input.len() > MANIFEST_BYTE_LIMIT { return Err(manifest_fault(format!( "manifest exceeds byte limit of {MANIFEST_BYTE_LIMIT}" ))); } let document: kdl::KdlDocument = input .parse() .map_err(|error| manifest_fault(format!("invalid manifest: {error}")))?; let mut id = None; let mut version = None; let mut world_version = None; let mut artifact = None; let mut capabilities = Vec::new(); let mut source = None; for node in document.nodes() { let name = node.name().value(); match name { "id" => set_once(&mut id, node_string(node, name)?, name)?, "version" => set_once(&mut version, node_string(node, name)?, name)?, "world" => set_once(&mut world_version, node_string(node, name)?, name)?, "artifact" => set_once(&mut artifact, node_string(node, name)?, name)?, "capability" => { let value = node_string(node, name)?; let capability = Capability::parse(&value)?; if capabilities.contains(&capability) { return Err(manifest_fault(format!("duplicate capability {value}"))); } capabilities.push(capability); } "source" => set_once(&mut source, node_string(node, name)?, name)?, _ => return Err(manifest_fault(format!("unknown manifest field {name}"))), } } Ok(Self { id: required(id, "id")?, version: required(version, "version")?, world_version: required(world_version, "world")?, artifact: required(artifact, "artifact")?, capabilities, source, }) } /// Plugin identity, namespaced by publisher. #[must_use] pub fn id(&self) -> &str { &self.id } /// Plugin package version. #[must_use] pub fn version(&self) -> &str { &self.version } /// Declared Smith plugin world version. #[must_use] pub fn world_version(&self) -> &str { &self.world_version } /// Relative component artifact path. #[must_use] pub fn artifact(&self) -> &str { &self.artifact } /// Requested host capabilities in manifest order. #[must_use] pub fn capabilities(&self) -> &[Capability] { &self.capabilities } /// Optional source provenance. #[must_use] pub fn source(&self) -> Option<&str> { self.source.as_deref() } } fn canonical_grants(grants: &[Capability]) -> Vec { [ Capability::NetScope, Capability::SecretProxy, Capability::Log, Capability::Workspace, Capability::Process, ] .into_iter() .filter(|capability| grants.contains(capability)) .collect() } fn canonical_net_scopes(scopes: &[NetScope]) -> Vec { let mut scopes = scopes.to_vec(); scopes.sort_by(|left, right| left.as_str().cmp(right.as_str())); scopes.dedup_by(|left, right| left.as_str() == right.as_str()); scopes } pub(crate) fn read_bounded(path: &Path, bytes_max: usize, kind: &str) -> Result> { let metadata = std::fs::metadata(path) .map_err(|error| manifest_fault(format!("{kind} read failed: {error}")))?; if metadata.len() > bytes_max as u64 { return Err(manifest_fault(format!( "{kind} exceeds byte limit of {bytes_max}" ))); } let capacity = usize::try_from(metadata.len()) .map_err(|_| manifest_fault(format!("{kind} exceeds addressable memory")))?; let mut bytes = Vec::new(); bytes .try_reserve_exact(capacity) .map_err(|_| manifest_fault(format!("{kind} allocation failed")))?; let file = std::fs::File::open(path) .map_err(|error| manifest_fault(format!("{kind} read failed: {error}")))?; #[expect( clippy::disallowed_methods, reason = "Take caps package snapshot reads" )] file.take((bytes_max + 1) as u64) .read_to_end(&mut bytes) .map_err(|error| manifest_fault(format!("{kind} read failed: {error}")))?; if bytes.len() > bytes_max { return Err(manifest_fault(format!( "{kind} exceeds byte limit of {bytes_max}" ))); } Ok(bytes) } fn node_string(node: &kdl::KdlNode, name: &str) -> Result { if node.entries().len() != 1 || node.entries()[0].name().is_some() || node.children().is_some() { return Err(manifest_fault(format!( "manifest field {name} accepts one string value without properties or children" ))); } let Some(value) = node.entry(0).and_then(|entry| entry.value().as_string()) else { return Err(manifest_fault(format!( "manifest field {name} requires one string value" ))); }; Ok(value.to_string()) } fn set_once(slot: &mut Option, value: String, name: &str) -> Result<()> { if slot.replace(value).is_some() { return Err(manifest_fault(format!("duplicate manifest field {name}"))); } Ok(()) } fn required(value: Option, name: &str) -> Result { let value = value.ok_or_else(|| manifest_fault(format!("missing manifest field {name}")))?; if value.is_empty() { return Err(manifest_fault(format!( "manifest field {name} must not be empty" ))); } Ok(value) } pub(crate) fn native_path_identity(path: &Path) -> String { #[cfg(unix)] { use std::os::unix::ffi::OsStrExt; format!("unix:{}", hex(path.as_os_str().as_bytes())) } #[cfg(windows)] { use std::os::windows::ffi::OsStrExt; let mut bytes = Vec::new(); for unit in path.as_os_str().encode_wide() { bytes.extend_from_slice(&unit.to_le_bytes()); } format!("windows:{}", hex(&bytes)) } #[cfg(not(any(unix, windows)))] { format!("other:{}", hex(path.to_string_lossy().as_bytes())) } } pub(crate) fn native_path_from_identity(identity: &str) -> Result { let (platform, encoded) = identity .split_once(':') .ok_or_else(|| manifest_fault("invalid native path identity"))?; let bytes = unhex(encoded)?; #[cfg(unix)] if platform == "unix" { use std::os::unix::ffi::OsStringExt; return Ok(PathBuf::from(std::ffi::OsString::from_vec(bytes))); } #[cfg(windows)] if platform == "windows" { use std::os::windows::ffi::OsStringExt; let (pairs, remainder) = bytes.as_chunks::<2>(); if !remainder.is_empty() { return Err(manifest_fault("invalid Windows native path identity")); } let units = pairs .iter() .map(|pair| u16::from_le_bytes(*pair)) .collect::>(); return Ok(PathBuf::from(std::ffi::OsString::from_wide(&units))); } Err(manifest_fault(format!( "native path identity platform {platform} is unsupported" ))) } fn hex(bytes: &[u8]) -> String { const DIGITS: &[u8; 16] = b"0123456789abcdef"; let mut text = String::with_capacity(bytes.len().saturating_mul(2)); for byte in bytes { text.push(char::from(DIGITS[usize::from(byte >> 4)])); text.push(char::from(DIGITS[usize::from(byte & 15)])); } text } fn unhex(text: &str) -> Result> { if !text.len().is_multiple_of(2) { return Err(manifest_fault("invalid native path identity")); } let (pairs, remainder) = text.as_bytes().as_chunks::<2>(); assert!(remainder.is_empty(), "even-length input has no remainder"); pairs .iter() .map(|pair| { let high = char::from(pair[0]) .to_digit(16) .ok_or_else(|| manifest_fault("invalid native path identity"))?; let low = char::from(pair[1]) .to_digit(16) .ok_or_else(|| manifest_fault("invalid native path identity"))?; u8::try_from((high << 4) | low) .map_err(|_| manifest_fault("invalid native path identity")) }) .collect() } fn manifest_fault(message: impl Into) -> SmithError { SmithError::Provider { fault: ProviderFault::Plugin { message: message.into(), }, } } #[cfg(test)] mod tests { //! Trust-time authority parsing (`SMH-SPEC-PLUG0001`). use super::NetScope; #[test] fn net_scope_accepts_explicit_production_or_loopback_origins_only() { assert_eq!( NetScope::parse("https://api.example.test:8443") .unwrap() .as_str(), "https://api.example.test:8443" ); assert!(NetScope::parse("http://127.0.0.1:8080").is_ok()); for origin in [ "http://example.test", "https://api.example.test/path", "https://user@api.example.test", "https://api.example.test?token=secret", "https://api.example.test:bad", ] { assert!(NetScope::parse(origin).is_err(), "accepted {origin}"); } } }