iris_trust/lib.rs
1//! Decoder identity, content hashes and substitution policy.
2//!
3//! A decoder is named by a URI and pinned by a BLAKE3 digest. A host that recognises the digest may
4//! run its own native implementation instead, and a host that does not may fetch and verify.
5//!
6//! What is here now is the part that has to be right before any of the rest of it is worth having:
7//! a container hands over its decoder module only after the module has been hashed and the hash has
8//! matched. The prior art in this space stores a checksum and never checks it, which is the finding
9//! this project exists to not repeat, so the check is not a policy a host opts into. It is the only
10//! path to the bytes.
11//!
12//! What a host does opt into is where a decoder may come from. The default runs decoders embedded
13//! in the container and nothing else, because a decoder named by a URI means a dataset can cause a
14//! host to go and fetch something and then execute it. A host that means to allow that builds a
15//! [`Policy`] with a [`Resolve`] of its own, which is to say it writes the thing that goes and
16//! finds the module. Whatever comes back is hashed against the container's digest exactly like an
17//! embedded module, so opting in changes where the bytes come from and changes nothing about
18//! whether they are checked.
19//!
20//! ```
21//! # use iris_abi::CapabilitySet;
22//! # use iris_format::{Builder, Container, SectionKind};
23//! let mut builder = Builder::new("readings", 3);
24//! builder.section(SectionKind::Data, b"rows go here".to_vec());
25//! builder.embed_decoder("test", (1, 0), CapabilitySet::new(), b"a module".to_vec());
26//! let bytes = builder.build()?;
27//!
28//! let container = Container::parse(&bytes)?;
29//! let decoder = iris_trust::decoder(&container)?;
30//! assert_eq!(decoder.module(), b"a module");
31//! # Ok::<(), Box<dyn std::error::Error>>(())
32//! ```
33//!
34//! Substitution, signatures and a policy about what may be fetched are still ahead. See the
35//! milestone that owns this crate in `docs/ROADMAP.md`.
36
37mod error;
38mod policy;
39mod verify;
40
41pub use error::Untrusted;
42pub use policy::{Policy, Resolve};
43pub use verify::{Verified, decoder};
44
45/// The version of this crate, as reported by build metadata.
46pub const VERSION: &str = env!("CARGO_PKG_VERSION");