Skip to main content

weirdnet_ext/
package.rs

1//! Packages: a tar archive with `manifest.json`, `manifest.sig` and the files under `files/`.
2//!
3//! [`build`] makes one from a directory and the author's key. [`Package::open`] checks it:
4//! the signature, the author id, every listed file present with its size and BLAKE3 hash, no
5//! unlisted files, regular files only and safe paths. The [`Installer`] keeps extensions in a
6//! per-user directory, one read-only directory per version, pins each extension id to its
7//! first author, refuses updates by another author or that are not newer, says which
8//! capabilities an update adds, and checks every hash again before a launch.
9
10use crate::error::{Error, Result, invalid};
11use crate::manifest::{self, Capability, FileEntry, Manifest};
12use libp2p_identity::Keypair;
13use std::collections::{BTreeMap, HashMap};
14use std::io::Read;
15use std::path::{Path, PathBuf};
16
17/// Size limits when opening a package.
18#[derive(Debug, Clone, Copy)]
19pub struct Limits {
20    /// Largest package (sum of file sizes).
21    pub total: u64,
22    /// Most files.
23    pub files: usize,
24}
25
26impl Default for Limits {
27    fn default() -> Self {
28        Self { total: 512 << 20, files: 10_000 }
29    }
30}
31
32/// Builds a package from the files under `dir`: fills in `files` (sizes and hashes) and the
33/// author, signs, and returns the archive bytes.
34pub fn build(dir: &Path, mut m: Manifest, key: &Keypair) -> Result<Vec<u8>> {
35    let mut files = BTreeMap::new();
36    collect(dir, dir, &mut files)?;
37    m.files = files.iter().map(|(p, b)| FileEntry { path: p.clone(), size: b.len() as u64, blake3: blake3::hash(b).to_hex().to_string() }).collect();
38    m.set_author(&key.public());
39    m.check()?;
40    let json = serde_json::to_vec_pretty(&m).map_err(|e| invalid(e.to_string()))?;
41    let sig = manifest::sign(key, &json)?;
42    let mut t = tar::Builder::new(Vec::new());
43    let mut add = |name: &str, data: &[u8], mode: u32| -> Result<()> {
44        let mut h = tar::Header::new_gnu();
45        h.set_size(data.len() as u64);
46        h.set_mode(mode);
47        h.set_mtime(0);
48        h.set_entry_type(tar::EntryType::Regular);
49        h.set_cksum();
50        t.append_data(&mut h, name, data)?;
51        Ok(())
52    };
53    add("manifest.json", &json, 0o644)?;
54    add("manifest.sig", hex::encode(&sig).as_bytes(), 0o644)?;
55    for (p, b) in &files {
56        add(&format!("files/{p}"), b, 0o644)?;
57    }
58    Ok(t.into_inner()?)
59}
60
61fn collect(root: &Path, dir: &Path, out: &mut BTreeMap<String, Vec<u8>>) -> Result<()> {
62    for e in std::fs::read_dir(dir)? {
63        let e = e?;
64        let t = e.file_type()?;
65        let p = e.path();
66        if t.is_dir() {
67            collect(root, &p, out)?;
68        } else if t.is_file() {
69            let rel = p.strip_prefix(root).unwrap().components().map(|c| c.as_os_str().to_string_lossy().into_owned()).collect::<Vec<_>>().join("/");
70            manifest::check_path(&rel)?;
71            out.insert(rel, std::fs::read(&p)?);
72        } else {
73            return Err(invalid(format!("{} is not a regular file", p.display())));
74        }
75    }
76    Ok(())
77}
78
79/// A verified package in memory.
80#[derive(Debug, Clone)]
81pub struct Package {
82    /// The manifest.
83    pub manifest: Manifest,
84    manifest_json: Vec<u8>,
85    sig: Vec<u8>,
86    files: HashMap<String, Vec<u8>>,
87}
88
89impl Package {
90    /// Reads and verifies a package with the default [`Limits`].
91    pub fn open(bytes: &[u8]) -> Result<Self> {
92        Self::open_with(bytes, Limits::default())
93    }
94
95    /// Reads and verifies a package.
96    pub fn open_with(bytes: &[u8], limits: Limits) -> Result<Self> {
97        let mut a = tar::Archive::new(bytes);
98        let (mut mj, mut sig, mut files) = (None, None, HashMap::new());
99        let mut total = 0u64;
100        for e in a.entries()? {
101            let mut e = e?;
102            if e.header().entry_type() != tar::EntryType::Regular {
103                return Err(invalid("only regular files are allowed in a package"));
104            }
105            let name = e.path()?.to_string_lossy().into_owned();
106            let size = e.header().size()?;
107            total = total.saturating_add(size);
108            if total > limits.total || files.len() >= limits.files {
109                return Err(invalid("the package is too large"));
110            }
111            let mut b = Vec::with_capacity(size as usize);
112            e.read_to_end(&mut b)?;
113            match name.as_str() {
114                "manifest.json" if mj.is_none() => mj = Some(b),
115                "manifest.sig" if sig.is_none() => sig = Some(b),
116                n => {
117                    let p = n.strip_prefix("files/").ok_or_else(|| invalid(format!("unexpected entry {n:?}")))?;
118                    manifest::check_path(p)?;
119                    if files.insert(p.to_string(), b).is_some() {
120                        return Err(invalid(format!("{p} appears twice")));
121                    }
122                }
123            }
124        }
125        let mj = mj.ok_or_else(|| invalid("no manifest.json"))?;
126        let sig = hex::decode(sig.ok_or_else(|| invalid("no manifest.sig"))?.trim_ascii()).map_err(|_| invalid("bad manifest.sig"))?;
127        let m = manifest::verify(&mj, &sig)?;
128        check_files(&m, |p| files.get(p).cloned())?;
129        if files.len() != m.files.len() {
130            return Err(Error::Verify("the package has files its manifest does not list".into()));
131        }
132        Ok(Self { manifest: m, manifest_json: mj, sig, files })
133    }
134
135    /// A file's bytes.
136    pub fn file(&self, path: &str) -> Option<&[u8]> {
137        self.files.get(path).map(Vec::as_slice)
138    }
139}
140
141fn check_files(m: &Manifest, mut get: impl FnMut(&str) -> Option<Vec<u8>>) -> Result<()> {
142    for f in &m.files {
143        let b = get(&f.path).ok_or_else(|| Error::Verify(format!("{} is missing", f.path)))?;
144        if b.len() as u64 != f.size || blake3::hash(&b).to_hex().as_str() != f.blake3 {
145            return Err(Error::Verify(format!("{} does not match its hash", f.path)));
146        }
147    }
148    Ok(())
149}
150
151/// What installing a package would do; from [`Installer::inspect`].
152#[derive(Debug, Clone)]
153pub struct Plan {
154    /// The verified package.
155    pub package: Package,
156    /// The installed manifest it replaces, if any.
157    pub previous: Option<Manifest>,
158    /// Capabilities not in the previous version (all of them for a first install). Ask the
159    /// user about these.
160    pub new_capabilities: Vec<Capability>,
161    /// True if a native binary will run on this target; false means WASM only.
162    pub native_runs: bool,
163    /// True if the extension can run here at all (a native binary or WASM).
164    pub runs_here: bool,
165}
166
167/// An installed, verified extension.
168#[derive(Debug, Clone)]
169pub struct Installed {
170    /// Its manifest.
171    pub manifest: Manifest,
172    /// Its read-only directory (the files are under `files/`).
173    pub dir: PathBuf,
174}
175
176impl Installed {
177    /// The native binary for this target, if any.
178    pub fn native(&self) -> Option<PathBuf> {
179        self.manifest.native_for(&manifest::current_target()).map(|n| self.dir.join("files").join(&n.path))
180    }
181
182    /// The WASM component, if any.
183    pub fn wasm(&self) -> Option<PathBuf> {
184        self.manifest.wasm.as_ref().map(|w| self.dir.join("files").join(w))
185    }
186}
187
188/// Installs extensions under a per-user directory: `ROOT/<id>/<version>/`, `ROOT/pins.json`
189/// (extension id to author user id) and `ROOT/<id>/current` (the active version).
190#[derive(Debug, Clone)]
191pub struct Installer {
192    root: PathBuf,
193}
194
195fn set_mode(p: &Path, mode: u32) -> Result<()> {
196    #[cfg(unix)]
197    {
198        use std::os::unix::fs::PermissionsExt;
199        std::fs::set_permissions(p, std::fs::Permissions::from_mode(mode))?;
200    }
201    #[cfg(not(unix))]
202    {
203        let mut perm = std::fs::metadata(p)?.permissions();
204        perm.set_readonly(mode & 0o200 == 0);
205        std::fs::set_permissions(p, perm)?;
206    }
207    Ok(())
208}
209
210impl Installer {
211    /// An installer rooted at `root`.
212    pub fn new(root: impl Into<PathBuf>) -> Self {
213        Self { root: root.into() }
214    }
215
216    fn pins(&self) -> Result<BTreeMap<String, String>> {
217        match std::fs::read(self.root.join("pins.json")) {
218            Ok(b) => serde_json::from_slice(&b).map_err(|e| invalid(format!("pins.json: {e}"))),
219            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(BTreeMap::new()),
220            Err(e) => Err(e.into()),
221        }
222    }
223
224    /// The author an id is pinned to.
225    pub fn pinned(&self, id: &str) -> Result<Option<String>> {
226        Ok(self.pins()?.get(id).cloned())
227    }
228
229    /// The active version of `id`, if installed.
230    pub fn current(&self, id: &str) -> Result<Option<String>> {
231        match std::fs::read_to_string(self.root.join(id).join("current")) {
232            Ok(v) => Ok(Some(v.trim().to_string())),
233            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
234            Err(e) => Err(e.into()),
235        }
236    }
237
238    /// Verifies `bytes` and compares it with what is installed. Fails if the id is pinned to
239    /// another author or the version is not newer.
240    pub fn inspect(&self, bytes: &[u8]) -> Result<Plan> {
241        let package = Package::open(bytes)?;
242        let m = &package.manifest;
243        if let Some(pinned) = self.pinned(&m.id)?
244            && pinned != m.author
245        {
246            return Err(Error::AuthorChanged { id: m.id.clone(), pinned, got: m.author.clone() });
247        }
248        let previous = match self.current(&m.id)? {
249            Some(_) => Some(self.verify(&m.id)?.manifest),
250            None => None,
251        };
252        if let Some(p) = &previous
253            && m.semver()? <= p.semver()?
254        {
255            return Err(Error::NotNewer { id: m.id.clone(), have: p.version.clone(), got: m.version.clone() });
256        }
257        let new_capabilities = m.capabilities.iter().filter(|c| previous.as_ref().is_none_or(|p| !p.capabilities.contains(c))).cloned().collect();
258        let native_runs = m.native_for(&manifest::current_target()).is_some() && crate::sandbox::native_allowed();
259        let runs_here = native_runs || m.wasm.is_some();
260        Ok(Plan { package, previous, new_capabilities, native_runs, runs_here })
261    }
262
263    /// Installs a plan (after the user agreed to its capabilities) and makes it current.
264    pub fn install(&self, plan: Plan) -> Result<Installed> {
265        let m = plan.package.manifest.clone();
266        if let Some(pinned) = self.pinned(&m.id)?
267            && pinned != m.author
268        {
269            return Err(Error::AuthorChanged { id: m.id.clone(), pinned, got: m.author.clone() });
270        }
271        let base = self.root.join(&m.id);
272        std::fs::create_dir_all(&base)?;
273        let dir = base.join(&m.version);
274        let tmp = base.join(format!(".{}.tmp", m.version));
275        if tmp.exists() {
276            make_writable(&tmp)?;
277            std::fs::remove_dir_all(&tmp)?;
278        }
279        std::fs::create_dir_all(tmp.join("files"))?;
280        std::fs::write(tmp.join("manifest.json"), &plan.package.manifest_json)?;
281        std::fs::write(tmp.join("manifest.sig"), hex::encode(&plan.package.sig))?;
282        let bins: Vec<&str> = m.native.iter().map(|n| n.path.as_str()).collect();
283        for f in &m.files {
284            let p = tmp.join("files").join(&f.path);
285            if let Some(d) = p.parent() {
286                std::fs::create_dir_all(d)?;
287            }
288            std::fs::write(&p, plan.package.file(&f.path).unwrap())?;
289            set_mode(&p, if bins.contains(&f.path.as_str()) { 0o555 } else { 0o444 })?;
290        }
291        read_only_dirs(&tmp)?;
292        if dir.exists() {
293            make_writable(&dir)?;
294            std::fs::remove_dir_all(&dir)?;
295        }
296        std::fs::rename(&tmp, &dir)?;
297        crate::store::write_atomic(&base.join("current"), m.version.as_bytes())?;
298        let mut pins = self.pins()?;
299        pins.entry(m.id.clone()).or_insert(m.author.clone());
300        crate::store::write_atomic(&self.root.join("pins.json"), &serde_json::to_vec_pretty(&pins).unwrap())?;
301        Ok(Installed { manifest: m, dir })
302    }
303
304    /// Checks the active version of `id` again (signature, author pin, every hash); do this
305    /// before every launch.
306    pub fn verify(&self, id: &str) -> Result<Installed> {
307        let v = self.current(id)?.ok_or_else(|| invalid(format!("{id} is not installed")))?;
308        let dir = self.root.join(id).join(&v);
309        let mj = std::fs::read(dir.join("manifest.json"))?;
310        let sig = hex::decode(std::fs::read_to_string(dir.join("manifest.sig"))?.trim()).map_err(|_| invalid("bad manifest.sig"))?;
311        let m = manifest::verify(&mj, &sig)?;
312        if m.id != id || m.version != v {
313            return Err(Error::Verify("the installed manifest is for something else".into()));
314        }
315        if let Some(pinned) = self.pinned(id)?
316            && pinned != m.author
317        {
318            return Err(Error::AuthorChanged { id: id.into(), pinned, got: m.author });
319        }
320        check_files(&m, |p| std::fs::read(dir.join("files").join(p)).ok())?;
321        Ok(Installed { manifest: m, dir })
322    }
323
324    /// Removes every version of `id` (the author pin stays, so a reinstall needs the same key).
325    pub fn uninstall(&self, id: &str) -> Result<()> {
326        let base = self.root.join(id);
327        if base.exists() {
328            make_writable(&base)?;
329            std::fs::remove_dir_all(&base)?;
330        }
331        Ok(())
332    }
333}
334
335fn read_only_dirs(dir: &Path) -> Result<()> {
336    for e in std::fs::read_dir(dir)? {
337        let e = e?;
338        if e.file_type()?.is_dir() {
339            read_only_dirs(&e.path())?;
340        } else {
341            set_mode(&e.path(), if is_exec(&e.path()) { 0o555 } else { 0o444 })?;
342        }
343    }
344    set_mode(dir, 0o555)
345}
346
347fn is_exec(p: &Path) -> bool {
348    #[cfg(unix)]
349    {
350        use std::os::unix::fs::PermissionsExt;
351        std::fs::metadata(p).map(|m| m.permissions().mode() & 0o111 != 0).unwrap_or(false)
352    }
353    #[cfg(not(unix))]
354    {
355        let _ = p;
356        false
357    }
358}
359
360fn make_writable(dir: &Path) -> Result<()> {
361    set_mode(dir, 0o755)?;
362    for e in std::fs::read_dir(dir)? {
363        let e = e?;
364        if e.file_type()?.is_dir() {
365            make_writable(&e.path())?;
366        } else {
367            set_mode(&e.path(), 0o644)?;
368        }
369    }
370    Ok(())
371}
372
373#[cfg(test)]
374mod tests {
375    use super::*;
376
377    fn manifest(id: &str, version: &str, caps: &[&str]) -> Manifest {
378        Manifest {
379            format: manifest::FORMAT,
380            id: id.into(),
381            name: "Reader".into(),
382            version: version.into(),
383            author: String::new(),
384            author_key: String::new(),
385            api_version: 1,
386            capabilities: caps.iter().map(|c| Capability::new(*c)).collect(),
387            sites: vec!["https://*.example.com/*".into()],
388            native: vec![manifest::Native { target: manifest::current_target(), path: "bin/ext".into() }],
389            wasm: Some("ext.wasm".into()),
390            files: vec![],
391        }
392    }
393
394    fn src(d: &Path) -> PathBuf {
395        let s = d.join("src");
396        std::fs::create_dir_all(s.join("bin")).unwrap();
397        std::fs::write(s.join("bin/ext"), b"#!/bin/sh\n").unwrap();
398        std::fs::write(s.join("ext.wasm"), b"\0asm").unwrap();
399        std::fs::write(s.join("README"), b"hello").unwrap();
400        s
401    }
402
403    #[test]
404    fn build_open_and_reject_tampering() {
405        let d = tempfile::tempdir().unwrap();
406        let key = Keypair::generate_ed25519();
407        let bytes = build(&src(d.path()), manifest("com.example.reader", "1.0.0", &["page.read"]), &key).unwrap();
408        let p = Package::open(&bytes).unwrap();
409        assert_eq!(p.manifest.files.len(), 3);
410        assert_eq!(p.manifest.author, manifest::user_id(&key.public()));
411        assert_eq!(p.file("README"), Some(&b"hello"[..]));
412        // Change a byte of a file: its hash fails.
413        let i = bytes.windows(5).position(|w| w == b"hello").unwrap();
414        let mut bad = bytes.clone();
415        bad[i] = b'j';
416        assert!(matches!(Package::open(&bad), Err(Error::Verify(_))));
417        // Change the manifest: the signature fails.
418        let i = bytes.windows(6).position(|w| w == b"Reader").unwrap();
419        let mut bad = bytes.clone();
420        bad[i] = b'X';
421        assert!(matches!(Package::open(&bad), Err(Error::Verify(_))));
422        // Over the limits.
423        assert!(Package::open_with(&bytes, Limits { total: 4, files: 10 }).is_err());
424    }
425
426    #[test]
427    fn manifests_are_checked() {
428        let key = Keypair::generate_ed25519();
429        let mut m = manifest("com.example.reader", "1.0.0", &[]);
430        m.set_author(&key.public());
431        m.native.clear();
432        m.wasm = None;
433        m.check().unwrap();
434        for bad in ["Com.Example", "ab", "../x", ".x"] {
435            let mut x = m.clone();
436            x.id = bad.into();
437            assert!(x.check().is_err(), "{bad}");
438        }
439        let mut x = m.clone();
440        x.version = "1".into();
441        assert!(x.check().is_err());
442        let mut x = m.clone();
443        x.author = "0".repeat(32);
444        assert!(matches!(x.check(), Err(Error::Verify(_))));
445        let mut x = m.clone();
446        x.wasm = Some("missing.wasm".into());
447        assert!(x.check().is_err());
448        for bad in ["/a", "a/../b", "a\\b", "", "a//b"] {
449            assert!(manifest::check_path(bad).is_err(), "{bad}");
450        }
451    }
452
453    #[test]
454    fn install_update_pin_and_verify() {
455        let d = tempfile::tempdir().unwrap();
456        let s = src(d.path());
457        let key = Keypair::generate_ed25519();
458        let inst = Installer::new(d.path().join("ext"));
459        let v1 = build(&s, manifest("com.example.reader", "1.0.0", &["page.read"]), &key).unwrap();
460        let plan = inst.inspect(&v1).unwrap();
461        assert!(plan.previous.is_none() && plan.runs_here);
462        assert_eq!(plan.new_capabilities, vec![Capability::new("page.read")]);
463        let i = inst.install(plan).unwrap();
464        assert_eq!(inst.current("com.example.reader").unwrap().as_deref(), Some("1.0.0"));
465        assert!(i.native().unwrap().ends_with("files/bin/ext"));
466        #[cfg(unix)]
467        {
468            use std::os::unix::fs::PermissionsExt;
469            let mode = |p: &Path| std::fs::metadata(p).unwrap().permissions().mode() & 0o777;
470            assert_eq!(mode(&i.dir.join("files/README")), 0o444);
471            assert_eq!(mode(&i.dir.join("files/bin/ext")), 0o555);
472            assert_eq!(mode(&i.dir), 0o555);
473        }
474        inst.verify("com.example.reader").unwrap();
475
476        // The same or an older version is refused; a newer one lists only the added capability.
477        assert!(matches!(inst.inspect(&v1), Err(Error::NotNewer { .. })));
478        let v2 = build(&s, manifest("com.example.reader", "1.1.0", &["page.read", "net.fetch"]), &key).unwrap();
479        let plan = inst.inspect(&v2).unwrap();
480        assert_eq!(plan.new_capabilities, vec![Capability::new("net.fetch")]);
481        inst.install(plan).unwrap();
482        assert_eq!(inst.verify("com.example.reader").unwrap().manifest.version, "1.1.0");
483
484        // Another author can't take the id over, even after an uninstall.
485        let other = Keypair::generate_ed25519();
486        let v3 = build(&s, manifest("com.example.reader", "2.0.0", &[]), &other).unwrap();
487        assert!(matches!(inst.inspect(&v3), Err(Error::AuthorChanged { .. })));
488        inst.uninstall("com.example.reader").unwrap();
489        assert!(matches!(inst.inspect(&v3), Err(Error::AuthorChanged { .. })));
490    }
491
492    #[cfg(unix)]
493    #[test]
494    fn a_changed_installed_file_fails_the_launch_check() {
495        use std::os::unix::fs::PermissionsExt;
496        let d = tempfile::tempdir().unwrap();
497        let key = Keypair::generate_ed25519();
498        let inst = Installer::new(d.path().join("ext"));
499        let i = inst.install(inst.inspect(&build(&src(d.path()), manifest("com.example.reader", "1.0.0", &[]), &key).unwrap()).unwrap()).unwrap();
500        let f = i.dir.join("files/README");
501        std::fs::set_permissions(&f, std::fs::Permissions::from_mode(0o644)).unwrap();
502        std::fs::write(&f, b"evil!").unwrap();
503        assert!(matches!(inst.verify("com.example.reader"), Err(Error::Verify(_))));
504    }
505}