Skip to main content

graphrt_bundle/
bundle.rs

1//! Opening and inspecting bundles.
2
3use std::collections::BTreeMap;
4use std::path::Path;
5
6use graphrt_core::{Registry, Workflow};
7use serde::Serialize;
8
9use crate::archive::{ArchiveLimits, read_zip, validate_path};
10use crate::error::BundleError;
11use crate::manifest::{BUNDLE_FORMAT_VERSION, BundleManifest, MANIFEST_PATH, SIGNATURE_PATH};
12use crate::sha256_hex;
13use crate::sign::{BundleSignature, parse_public_key, verify_manifest};
14
15/// Options for [`Bundle::open`].
16#[derive(Clone, Debug)]
17pub struct OpenOptions {
18    /// Maximum archive entries.
19    pub max_entries: usize,
20    /// Maximum size of one file.
21    pub max_file_bytes: u64,
22    /// Maximum total uncompressed size.
23    pub max_total_bytes: u64,
24    /// Maximum per-file compression ratio (zip-bomb guard).
25    pub max_compression_ratio: u64,
26    /// Hex Ed25519 public keys allowed to sign. When non-empty, a valid signature
27    /// from one of these keys is required.
28    pub trusted_keys: Vec<String>,
29    /// Require a valid signature even when `trusted_keys` is empty.
30    pub require_signature: bool,
31}
32
33impl Default for OpenOptions {
34    fn default() -> Self {
35        Self {
36            max_entries: 2_000,
37            max_file_bytes: 64 * 1024 * 1024,
38            max_total_bytes: 256 * 1024 * 1024,
39            max_compression_ratio: 200,
40            trusted_keys: Vec::new(),
41            require_signature: false,
42        }
43    }
44}
45
46impl OpenOptions {
47    /// Require a signature from `public_key` (hex). May be called repeatedly.
48    pub fn trust_key(mut self, public_key: impl Into<String>) -> Self {
49        self.trusted_keys.push(public_key.into());
50        self
51    }
52}
53
54/// A plugin shipped in the bundle.
55#[derive(Clone, Debug)]
56pub struct BundledPlugin {
57    pub name: String,
58    pub version: String,
59    /// `wasm`, `process` or `http`.
60    pub runtime: String,
61    /// The plugin manifest (`plugins/<name>/graphrt-plugin.json`).
62    pub manifest: serde_json::Value,
63    /// Module bytes for WebAssembly plugins.
64    pub module: Option<Vec<u8>>,
65    /// Directory of the plugin inside the bundle (`plugins/<name>`).
66    pub dir: String,
67}
68
69impl BundledPlugin {
70    /// Whether the plugin runs on every host (WebAssembly only).
71    pub fn is_portable(&self) -> bool {
72        self.runtime == "wasm"
73    }
74}
75
76/// Result of [`Bundle::check`].
77#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
78pub struct CompatReport {
79    /// Node kinds the workflows use that the host registry lacks.
80    pub missing_node_kinds: Vec<String>,
81    /// Plugins the host cannot load portably (process / http plugins).
82    pub non_portable_plugins: Vec<String>,
83    /// Model providers the workflows reference (the host must configure them).
84    pub providers: Vec<String>,
85    /// Environment variables the workflows declare (the host must supply them).
86    pub env: Vec<String>,
87    /// Set when the bundle's runtime requirement does not match this runtime.
88    #[serde(skip_serializing_if = "Option::is_none")]
89    pub version_mismatch: Option<String>,
90}
91
92impl CompatReport {
93    /// Whether the bundle can run on this host (env and providers are only advisory).
94    pub fn is_compatible(&self) -> bool {
95        self.missing_node_kinds.is_empty() && self.version_mismatch.is_none()
96    }
97}
98
99/// An opened, fully verified bundle held in memory.
100#[derive(Clone, Debug)]
101pub struct Bundle {
102    manifest: BundleManifest,
103    manifest_bytes: Vec<u8>,
104    files: BTreeMap<String, Vec<u8>>,
105    signer: Option<String>,
106}
107
108impl Bundle {
109    /// Open a bundle from archive bytes: enforce archive limits, check every file
110    /// against its SHA-256, reject unlisted files, and verify the signature.
111    pub fn open(bytes: &[u8], options: &OpenOptions) -> Result<Self, BundleError> {
112        let limits = ArchiveLimits {
113            max_entries: options.max_entries,
114            max_entry_bytes: options.max_file_bytes,
115            max_total_bytes: options.max_total_bytes,
116            max_ratio: options.max_compression_ratio,
117        };
118        let mut files = read_zip(bytes, &limits)?;
119        let manifest_bytes =
120            files.remove(MANIFEST_PATH).ok_or_else(|| BundleError::Manifest(format!("missing `{MANIFEST_PATH}`")))?;
121        let manifest: BundleManifest =
122            serde_json::from_slice(&manifest_bytes).map_err(|e| BundleError::Manifest(e.to_string()))?;
123        if manifest.format_version != BUNDLE_FORMAT_VERSION {
124            return Err(BundleError::Manifest(format!(
125                "unsupported format version {} (this runtime reads {BUNDLE_FORMAT_VERSION})",
126                manifest.format_version
127            )));
128        }
129
130        // Signature.
131        let signer = match files.remove(SIGNATURE_PATH) {
132            Some(raw) => {
133                let sig: BundleSignature = serde_json::from_slice(&raw)
134                    .map_err(|e| BundleError::Signature(format!("malformed `{SIGNATURE_PATH}`: {e}")))?;
135                Some(verify_manifest(&manifest_bytes, &sig)?)
136            }
137            None => None,
138        };
139        if !options.trusted_keys.is_empty() {
140            let trusted: Vec<String> = options
141                .trusted_keys
142                .iter()
143                .map(|k| parse_public_key(k).map(|key| crate::hex(key.as_bytes())))
144                .collect::<Result<_, _>>()?;
145            match &signer {
146                None => {
147                    return Err(BundleError::Signature(
148                        "bundle is unsigned but a trusted signature is required".into(),
149                    ));
150                }
151                Some(key) if !trusted.contains(key) => {
152                    return Err(BundleError::Signature(format!("signed by untrusted key {key}")));
153                }
154                Some(_) => {}
155            }
156        } else if options.require_signature && signer.is_none() {
157            return Err(BundleError::Signature("bundle is unsigned but a signature is required".into()));
158        }
159
160        // Integrity: exact set of files, each matching its hash.
161        for path in manifest.files.keys() {
162            validate_path(path)?;
163        }
164        for (path, data) in &files {
165            let Some(expected) = manifest.files.get(path) else {
166                return Err(BundleError::Integrity(format!("`{path}` is not listed in the manifest")));
167            };
168            if !expected.eq_ignore_ascii_case(&sha256_hex(data)) {
169                return Err(BundleError::Integrity(format!("`{path}` does not match its recorded SHA-256")));
170            }
171        }
172        if let Some(missing) = manifest.files.keys().find(|p| !files.contains_key(*p)) {
173            return Err(BundleError::Integrity(format!("`{missing}` is listed in the manifest but missing")));
174        }
175        if !manifest.workflows.contains(&manifest.entry) {
176            return Err(BundleError::Manifest(format!("entry `{}` is not one of the workflows", manifest.entry)));
177        }
178        if let Some(w) = manifest.workflows.iter().find(|w| !files.contains_key(*w)) {
179            return Err(BundleError::Manifest(format!("workflow `{w}` is missing")));
180        }
181        Ok(Self { manifest, manifest_bytes, files, signer })
182    }
183
184    /// Read and open a bundle file.
185    pub fn open_path(path: impl AsRef<Path>, options: &OpenOptions) -> Result<Self, BundleError> {
186        let path = path.as_ref();
187        let meta = std::fs::metadata(path).map_err(|e| BundleError::io(path, &e))?;
188        if meta.len() > options.max_total_bytes {
189            return Err(BundleError::Archive(format!("file is larger than {} bytes", options.max_total_bytes)));
190        }
191        let bytes = std::fs::read(path).map_err(|e| BundleError::io(path, &e))?;
192        Self::open(&bytes, options)
193    }
194
195    pub fn manifest(&self) -> &BundleManifest {
196        &self.manifest
197    }
198
199    /// Exact manifest bytes (what signatures cover).
200    pub fn manifest_bytes(&self) -> &[u8] {
201        &self.manifest_bytes
202    }
203
204    /// Hex public key of the verified signer, if the bundle is signed.
205    pub fn signer(&self) -> Option<&str> {
206        self.signer.as_deref()
207    }
208
209    /// Content of one file.
210    pub fn file(&self, path: &str) -> Option<&[u8]> {
211        self.files.get(path).map(Vec::as_slice)
212    }
213
214    /// Paths of every file (excluding manifest and signature).
215    pub fn paths(&self) -> impl Iterator<Item = &str> {
216        self.files.keys().map(String::as_str)
217    }
218
219    pub(crate) fn raw_files(&self) -> &BTreeMap<String, Vec<u8>> {
220        &self.files
221    }
222
223    /// Source text of a workflow (`None` = the entry workflow).
224    pub fn workflow_text(&self, name: Option<&str>) -> Result<&str, BundleError> {
225        let path = self.workflow_path(name)?;
226        let bytes = self.files.get(path).ok_or_else(|| BundleError::Manifest(format!("workflow `{path}` missing")))?;
227        std::str::from_utf8(bytes)
228            .map_err(|_| BundleError::Workflow { name: path.to_owned(), message: "not valid UTF-8".into() })
229    }
230
231    /// Parse a workflow (`None` = the entry workflow). `name` may be the stored path
232    /// or its file stem (`support` for `workflows/support.yaml`).
233    pub fn workflow(&self, name: Option<&str>) -> Result<Workflow, BundleError> {
234        let path = self.workflow_path(name)?.to_owned();
235        let text = self.workflow_text(Some(&path))?;
236        Workflow::parse(text).map_err(|e| BundleError::Workflow { name: path, message: e.to_string() })
237    }
238
239    fn workflow_path(&self, name: Option<&str>) -> Result<&str, BundleError> {
240        let Some(name) = name else {
241            return Ok(&self.manifest.entry);
242        };
243        self.manifest
244            .workflows
245            .iter()
246            .find(|w| w.as_str() == name || stem(w) == name)
247            .map(String::as_str)
248            .ok_or_else(|| BundleError::Workflow { name: name.to_owned(), message: "not in this bundle".into() })
249    }
250
251    /// Every plugin shipped under `plugins/<name>/`.
252    pub fn plugins(&self) -> Result<Vec<BundledPlugin>, BundleError> {
253        let mut out = Vec::new();
254        for (path, data) in &self.files {
255            let Some(rest) = path.strip_prefix("plugins/") else { continue };
256            let Some((dir_name, file)) = rest.split_once('/') else { continue };
257            if file != "graphrt-plugin.json" {
258                continue;
259            }
260            let plugin_err = |m: String| BundleError::Plugin { plugin: dir_name.to_owned(), message: m };
261            let manifest: serde_json::Value =
262                serde_json::from_slice(data).map_err(|e| plugin_err(format!("invalid manifest: {e}")))?;
263            let name = manifest.get("name").and_then(|v| v.as_str()).unwrap_or(dir_name).to_owned();
264            let version = manifest.get("version").and_then(|v| v.as_str()).unwrap_or_default().to_owned();
265            let runtime = manifest.get("runtime").and_then(|v| v.as_str()).unwrap_or("process").to_owned();
266            let dir = format!("plugins/{dir_name}");
267            let module = if runtime == "wasm" {
268                let module_path = manifest
269                    .get("module")
270                    .and_then(|v| v.as_str())
271                    .ok_or_else(|| plugin_err("wasm plugin without `module`".into()))?;
272                let full = format!("{dir}/{module_path}");
273                validate_path(&full)?;
274                Some(
275                    self.files
276                        .get(&full)
277                        .cloned()
278                        .ok_or_else(|| plugin_err(format!("module `{module_path}` is missing")))?,
279                )
280            } else {
281                None
282            };
283            out.push(BundledPlugin { name, version, runtime, manifest, module, dir });
284        }
285        Ok(out)
286    }
287
288    /// WebAssembly plugins only (portable to every host, including phones).
289    pub fn wasm_plugins(&self) -> Result<Vec<BundledPlugin>, BundleError> {
290        Ok(self.plugins()?.into_iter().filter(BundledPlugin::is_portable).collect())
291    }
292
293    /// Path and text of the knowledge-base config (`knowledge/knowledge.{yaml,yml,json}`).
294    pub fn knowledge_config(&self) -> Option<(&str, &str)> {
295        ["knowledge/knowledge.yaml", "knowledge/knowledge.yml", "knowledge/knowledge.json"]
296            .iter()
297            .find_map(|p| self.files.get(*p).and_then(|b| std::str::from_utf8(b).ok()).map(|t| (*p, t)))
298    }
299
300    /// Path and text of the providers file (`providers.{yaml,yml,json}`), which never holds secrets.
301    pub fn providers_config(&self) -> Option<(&str, &str)> {
302        ["providers.yaml", "providers.yml", "providers.json"]
303            .iter()
304            .find_map(|p| self.files.get(*p).and_then(|b| std::str::from_utf8(b).ok()).map(|t| (*p, t)))
305    }
306
307    /// The knowledge-base config as JSON with every store `path` inside `knowledge/`
308    /// rewritten to its location under `extracted` (the directory passed to
309    /// [`Bundle::extract_to`]). `None` when the bundle has no knowledge config.
310    pub fn knowledge_config_at(&self, extracted: &Path) -> Option<Result<serde_json::Value, BundleError>> {
311        let (path, text) = self.knowledge_config()?;
312        let parsed: Result<serde_json::Value, BundleError> = if path.ends_with(".json") {
313            serde_json::from_str(text).map_err(|e| BundleError::Manifest(format!("{path}: {e}")))
314        } else {
315            let options = serde_saphyr::options! { strict_booleans: true };
316            serde_saphyr::from_str_with_options(text, options)
317                .map_err(|e| BundleError::Manifest(format!("{path}: {e}")))
318        };
319        Some(parsed.map(|mut value| {
320            if let Some(stores) = value.get_mut("stores").and_then(|s| s.as_object_mut()) {
321                for store in stores.values_mut() {
322                    let Some(obj) = store.as_object_mut() else { continue };
323                    let rel = obj.get("path").and_then(|p| p.as_str()).map(str::to_owned);
324                    if let Some(rel) = rel.filter(|r| r.starts_with("knowledge/") && validate_path(r).is_ok()) {
325                        let full = extracted.join(rel).display().to_string();
326                        obj.insert("path".into(), serde_json::Value::String(full));
327                    }
328                }
329            }
330            value
331        }))
332    }
333
334    /// Write every file under `dir` (created if needed), preserving the layout.
335    /// Paths were validated on open, so nothing escapes `dir`.
336    pub fn extract_to(&self, dir: &Path) -> Result<(), BundleError> {
337        for (path, data) in &self.files {
338            let target = dir.join(path);
339            if let Some(parent) = target.parent() {
340                std::fs::create_dir_all(parent).map_err(|e| BundleError::io(parent, &e))?;
341            }
342            std::fs::write(&target, data).map_err(|e| BundleError::io(&target, &e))?;
343        }
344        Ok(())
345    }
346
347    /// Compare the bundle's requirements with a host registry (after bundled
348    /// plugins were registered) and this runtime's version.
349    pub fn check(&self, registry: &Registry) -> CompatReport {
350        let req = &self.manifest.requires;
351        let missing_node_kinds = req.node_kinds.iter().filter(|k| !registry.contains(k)).cloned().collect();
352        let non_portable_plugins = req.plugins.iter().filter(|p| !p.portable).map(|p| p.name.clone()).collect();
353        let version_mismatch = version_mismatch(&req.graphrt, env!("CARGO_PKG_VERSION"));
354        CompatReport {
355            missing_node_kinds,
356            non_portable_plugins,
357            providers: req.providers.clone(),
358            env: req.env.clone(),
359            version_mismatch,
360        }
361    }
362}
363
364fn stem(path: &str) -> &str {
365    let file = path.rsplit('/').next().unwrap_or(path);
366    file.rsplit_once('.').map_or(file, |(s, _)| s)
367}
368
369fn version_mismatch(requirement: &str, current: &str) -> Option<String> {
370    if requirement.trim().is_empty() {
371        return None;
372    }
373    let req = match semver::VersionReq::parse(requirement) {
374        Ok(r) => r,
375        Err(e) => return Some(format!("invalid runtime requirement `{requirement}`: {e}")),
376    };
377    match semver::Version::parse(current) {
378        Ok(v) if req.matches(&v) => None,
379        Ok(v) => Some(format!("bundle requires graphrt {requirement}, this is {v}")),
380        Err(e) => Some(format!("cannot parse runtime version `{current}`: {e}")),
381    }
382}
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387
388    #[test]
389    fn version_requirements() {
390        assert!(version_mismatch(">=0.1", "0.1.0").is_none());
391        assert!(version_mismatch(">=0.2", "0.1.0").is_some());
392        assert!(version_mismatch("", "0.1.0").is_none());
393        assert!(version_mismatch("nonsense!", "0.1.0").is_some());
394        assert_eq!(stem("workflows/support.yaml"), "support");
395    }
396}