gunnar_server/

oci.rs

//! **The artifact registry, and the images it holds** (roadmap phase 4).
//!
//! Content-addressed storage, an OCI image built out of the scratch base, and
//! the one rule from [`crate::registry`] enforced where a manifest lands.
//!
//! # Why the image is attested like any other artifact
//!
//! An image is a manifest, which names a config and some layers, all by digest.
//! So an image **is** a digest, and a digest is the thing `BuildRecord` already
//! attests to. Building one therefore writes a second signed record whose
//! *subject* is the manifest digest and whose *material* is the binary that
//! went in — which chains image → binary → commit → line with no new machinery
//! and, more importantly, no second kind of evidence to keep honest.
//!
//! That is what makes [`crate::registry::admit`] work unchanged on an image
//! reference. A manifest nobody built is refused for exactly the reason a
//! binary nobody built is.
//!
//! # The layer is an uncompressed tar, and that is deliberate
//!
//! `application/vnd.oci.image.layer.v1.tar` is a valid layer media type. Gzip
//! would make the layer's digest depend on the compressor's version and level —
//! two runs of the same build would produce two images — and reproducibility is
//! the whole point of attesting to a digest. Uncompressed, the layer is a pure
//! function of the files in it.
//!
//! Every tar header field that could carry a timestamp, a uid or a username is
//! **zeroed** for the same reason.
//!
//! # Zero CVEs is a measurement, and this is the part that earns it
//!
//! The image has one layer and that layer has one file. There is no distro, no
//! package manager, no shell — so "zero CVEs" is not a claim about diligence,
//! it is a statement about surface area, and `gunnar build image` prints the
//! file count so it stays a number rather than an adjective.

use std::path::{Path, PathBuf};

use anyhow::{Context, Result};

use crate::stores::ServerStores;

/// Where the registry keeps its bytes, under the data root.
pub const REGISTRY_DIR: &str = "registry";

/// One tar header block, 512 bytes.
const BLOCK: usize = 512;

/// A file going into a layer.
pub struct Entry<'a> {
    /// The path inside the image, without a leading `/`.
    pub path: &'a str,
    /// Its bytes.
    pub bytes: &'a [u8],
    /// The mode. `0o755` for something meant to be executed.
    pub mode: u32,
}

/// Write `entries` as an uncompressed tar.
///
/// Reproducible by construction: no timestamps, no uid, no gid, no user names.
/// Two calls with the same entries produce the same bytes, so the layer digest
/// is a function of the content and of nothing else.
pub fn tar(entries: &[Entry<'_>]) -> Result<Vec<u8>> {
    let mut out = Vec::new();
    for entry in entries {
        anyhow::ensure!(
            entry.path.len() < 100,
            "{:?} is too long for a ustar name field; a path this deep needs the prefix field, \
             which this writer does not use because no image gunnar builds has one",
            entry.path
        );
        let mut header = [0u8; BLOCK];
        header[..entry.path.len()].copy_from_slice(entry.path.as_bytes());
        // Octal, NUL-terminated, exactly as ustar wants. Written by hand
        // because every one of these fields is a place a formatter would put a
        // space or a timestamp that made the layer irreproducible.
        let octal = |field: &mut [u8], value: u64| {
            let text = format!("{value:0width$o}", width = field.len() - 1);
            field[..text.len()].copy_from_slice(text.as_bytes());
        };
        octal(&mut header[100..108], entry.mode as u64 & 0o7777);
        octal(&mut header[108..116], 0); // uid
        octal(&mut header[116..124], 0); // gid
        octal(&mut header[124..136], entry.bytes.len() as u64);
        octal(&mut header[136..148], 0); // mtime — zero, for reproducibility
        header[148..156].fill(b' '); // checksum field, blank while summing
        header[156] = b'0'; // typeflag: an ordinary file
        header[257..263].copy_from_slice(b"ustar\0");
        header[263..265].copy_from_slice(b"00");
        let sum: u64 = header.iter().map(|byte| *byte as u64).sum();
        let text = format!("{sum:06o}\0");
        header[148..148 + text.len()].copy_from_slice(text.as_bytes());
        out.extend_from_slice(&header);

        out.extend_from_slice(entry.bytes);
        let padding = (BLOCK - entry.bytes.len() % BLOCK) % BLOCK;
        out.extend(std::iter::repeat_n(0u8, padding));
    }
    // Two zero blocks end an archive. One is not enough and readers differ
    // about what a single one means.
    out.extend(std::iter::repeat_n(0u8, BLOCK * 2));
    Ok(out)
}

/// `sha256:<hex>` — how OCI names everything.
pub fn digest_of(bytes: &[u8]) -> String {
    // Through `gunnar_core`, so there is one place in this tree that decides
    // what the digest of something is (one implementation) — and so this crate does not grow
    // a hasher of its own beside the one it already links.
    format!("sha256:{}", gunnar_core::provenance::digest_bytes(bytes))
}

/// The registry's content-addressed store.
#[derive(Debug, Clone)]
pub struct Registry {
    root: PathBuf,
}

/// What a manifest push was refused for, or what it landed as.
#[derive(Debug, Clone)]
pub struct Landed {
    pub digest: String,
    pub name: String,
    pub reference: String,
}

impl Registry {
    /// The registry under a data root.
    pub fn under(root: impl AsRef<Path>) -> Registry {
        Registry {
            root: root.as_ref().join(REGISTRY_DIR),
        }
    }

    fn blob_path(&self, digest: &str) -> Result<PathBuf> {
        let hex = digest.strip_prefix("sha256:").with_context(|| {
            format!("{digest:?} is not a `sha256:` digest; this registry addresses nothing else")
        })?;
        anyhow::ensure!(
            hex.len() == 64 && hex.bytes().all(|b| b.is_ascii_hexdigit()),
            "{digest:?} is not a sha256 digest"
        );
        Ok(self.root.join("blobs").join("sha256").join(hex))
    }

    /// **Store bytes under their own digest.**
    ///
    /// The digest is computed here and never taken from the caller: a registry
    /// that trusts a supplied digest is one where a client chooses what its
    /// bytes are called, which is the whole attack content addressing exists to
    /// prevent.
    pub fn put_blob(&self, bytes: &[u8]) -> Result<String> {
        let digest = digest_of(bytes);
        let path = self.blob_path(&digest)?;
        std::fs::create_dir_all(path.parent().expect("a blob has a parent"))?;
        if path.exists() {
            // Content-addressed: the same digest is the same bytes, so a
            // re-push is a no-op rather than a conflict.
            return Ok(digest);
        }
        // Written beside and renamed, so a reader never sees a partial blob
        // under a digest that promises the whole thing.
        let temp = path.with_extension("partial");
        std::fs::write(&temp, bytes)?;
        std::fs::rename(&temp, &path)?;
        Ok(digest)
    }

    /// Read a blob back, verifying it still hashes to its own name.
    ///
    /// The check is not paranoia: a content-addressed store whose reads are not
    /// verified is a store where bit rot becomes a supply-chain event, and the
    /// cost is one hash of bytes already in memory.
    pub fn get_blob(&self, digest: &str) -> Result<Option<Vec<u8>>> {
        let path = self.blob_path(digest)?;
        let bytes = match std::fs::read(&path) {
            Ok(bytes) => bytes,
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
            Err(err) => return Err(err.into()),
        };
        let actual = digest_of(&bytes);
        anyhow::ensure!(
            actual == digest,
            "the blob stored as {digest} hashes to {actual}. The registry has been corrupted \
             or written around."
        );
        Ok(Some(bytes))
    }

    /// Where a tag's file lives, **inside this registry and nowhere else**.
    ///
    /// # An absolute name is not a name, it is a destination
    ///
    /// The check this replaced tested the name as ONE string: non-empty, under
    /// 128 bytes, drawn from an alphabet that includes `/`, and holding no
    /// `..`. Every one of those passes for `/etc/gunnar`, and
    /// `Path::join` **replaces** the whole path when what it is handed is
    /// absolute — so the registry root is silently discarded and the write
    /// lands wherever the leading slash pointed. The same trick works one
    /// component in (`team//app`, `team/./app`): the empty and `.` components
    /// are not traversal, they are just not names, and nothing rejected them.
    ///
    /// So the name is checked **component by component**, which is the only
    /// shape in which "this stays under the root" is a statement about a path
    /// rather than about a string: no empty component (which is what a leading,
    /// trailing or doubled `/` produces, absolute paths included), no `.`, no
    /// `..`, and the OCI alphabet otherwise.
    ///
    /// The HTTP surface has already put the name through
    /// `gunnar_core::resolve_repo_path` before a request reaches this crate.
    /// This is not that check repeated for the sake of it: `Registry` is a
    /// `pub` type with callers that never touched a URL (`gunnar build image`,
    /// the tests), and a store that is only safe when its callers are careful
    /// is a store that is one new caller away from not being safe.
    fn tag_path(&self, name: &str, reference: &str) -> Result<PathBuf> {
        let legal_component = |part: &str| {
            !part.is_empty()
                && part.len() < 128
                && part != "."
                && part != ".."
                && part
                    .bytes()
                    .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
        };
        anyhow::ensure!(
            !name.is_empty() && name.split('/').all(legal_component),
            "{name:?} is not a usable repository name"
        );
        anyhow::ensure!(
            legal_component(reference),
            "{reference:?} is not a usable tag"
        );
        let mut path = self.root.join("manifests");
        // Pushed component by component rather than as one string, so the
        // property the check above establishes is the property the path is
        // built with — `join` on a validated whole would still be `join` on a
        // string somebody could later widen.
        for part in name.split('/') {
            path.push(part);
        }
        path.push(reference);
        Ok(path)
    }

    /// **Land a manifest — if the image it names was built and attested.**
    ///
    /// This is [`crate::registry::admit`] at the one place bytes become
    /// pullable. A manifest whose digest no signed, logged build record names is
    /// refused, and the refusal says which of the four things is missing.
    pub fn put_manifest(
        &self,
        stores: &ServerStores,
        name: &str,
        reference: &str,
        manifest: &[u8],
    ) -> Result<std::result::Result<Landed, crate::registry::Refusal>> {
        let digest = digest_of(manifest);
        // `admit` speaks bare hex, because that is what a `BuildRecord` subject
        // carries; OCI speaks `sha256:`. The translation happens here, once.
        let hex = digest.trim_start_matches("sha256:");
        if let Err(refusal) = crate::registry::admit(stores, hex)? {
            return Ok(Err(refusal));
        }
        self.put_blob(manifest)?;
        let path = self.tag_path(name, reference)?;
        std::fs::create_dir_all(path.parent().expect("a tag has a parent"))?;
        std::fs::write(&path, &digest)?;
        Ok(Ok(Landed {
            digest,
            name: name.to_owned(),
            reference: reference.to_owned(),
        }))
    }

    /// What digest a tag points at.
    pub fn resolve(&self, name: &str, reference: &str) -> Result<Option<String>> {
        // A reference that is already a digest resolves to itself; that is how
        // `docker pull name@sha256:…` works and it must not go through the tag
        // directory.
        if reference.starts_with("sha256:") {
            return Ok(Some(reference.to_owned()));
        }
        let path = self.tag_path(name, reference)?;
        match std::fs::read_to_string(&path) {
            Ok(text) => Ok(Some(text.trim().to_owned())),
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(err) => Err(err.into()),
        }
    }
}

/// What building an image produced.
#[derive(Debug, Clone)]
pub struct Image {
    /// The manifest's digest — the image's identity.
    pub digest: String,
    pub manifest: Vec<u8>,
    pub config_digest: String,
    /// The config document itself.
    ///
    /// Carried rather than rebuilt, because a puller fetches this blob by
    /// digest and a second function deciding what a config says is a second
    /// authority that can drift from the first (one implementation).
    pub config: Vec<u8>,
    pub layer_digest: String,
    /// The layer tar itself, for the same reason as [`Image::config`].
    pub layer: Vec<u8>,
    /// How many files the image's filesystem holds. The number behind
    /// "zero CVEs".
    pub files: usize,
}

/// **Build an OCI image around one static binary, on nothing.**
///
/// `FROM scratch` is not a base image here, it is the *absence* of one: the
/// manifest names one layer, and that layer is a tar with one file in it. There
/// is no distro to have a CVE.
pub fn build_image(binary: &[u8], entrypoint: &str) -> Result<Image> {
    let path = entrypoint.trim_start_matches('/');
    anyhow::ensure!(
        !path.is_empty(),
        "an image needs an entrypoint; a layer with a binary nobody can name is not an image"
    );
    let layer = tar(&[Entry {
        path,
        bytes: binary,
        mode: 0o755,
    }])?;
    let layer_digest = digest_of(&layer);

    // `diff_ids` are the digests of the **uncompressed** layers, which for an
    // uncompressed layer is the same digest the manifest carries. Naming it
    // twice is OCI's shape, not a duplication that can drift: both come from
    // one variable.
    let config = format!(
        concat!(
            "{{\"architecture\":\"amd64\",\"os\":\"linux\",",
            "\"config\":{{\"Entrypoint\":[\"/{path}\"]}},",
            "\"rootfs\":{{\"type\":\"layers\",\"diff_ids\":[\"{layer}\"]}}}}"
        ),
        path = path,
        layer = layer_digest
    );
    let config_digest = digest_of(config.as_bytes());

    let manifest = format!(
        concat!(
            "{{\"schemaVersion\":2,",
            "\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",",
            "\"config\":{{\"mediaType\":\"application/vnd.oci.image.config.v1+json\",",
            "\"digest\":\"{config}\",\"size\":{config_size}}},",
            "\"layers\":[{{\"mediaType\":\"application/vnd.oci.image.layer.v1.tar\",",
            "\"digest\":\"{layer}\",\"size\":{layer_size}}}]}}"
        ),
        config = config_digest,
        config_size = config.len(),
        layer = layer_digest,
        layer_size = layer.len()
    );

    Ok(Image {
        digest: digest_of(manifest.as_bytes()),
        manifest: manifest.into_bytes(),
        config_digest,
        config: config.into_bytes(),
        layer_digest,
        layer,
        files: 1,
    })
}

/// Build an image and put every part of it in the registry.
///
/// Returns the image, with its blobs already stored — a manifest whose layers
/// are not there is a manifest nobody can pull, and landing them separately is
/// how that happens.
pub fn build_and_store(registry: &Registry, binary: &[u8], entrypoint: &str) -> Result<Image> {
    let image = build_image(binary, entrypoint)?;
    // Both blobs the manifest names, not just the layer. A puller fetches the
    // config first — it is where the entrypoint lives — and an image whose
    // config is missing is an image that resolves and then fails halfway.
    let stored_layer = registry.put_blob(&image.layer)?;
    let stored_config = registry.put_blob(&image.config)?;
    debug_assert_eq!(stored_layer, image.layer_digest);
    debug_assert_eq!(stored_config, image.config_digest);
    Ok(image)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_tar_is_reproducible_and_has_the_shape_a_reader_expects() {
        let a = tar(&[Entry {
            path: "gunnar",
            bytes: b"binary",
            mode: 0o755,
        }])
        .expect("tar");
        let b = tar(&[Entry {
            path: "gunnar",
            bytes: b"binary",
            mode: 0o755,
        }])
        .expect("tar");
        assert_eq!(a, b, "two identical layers produced different bytes");

        // ustar magic where a reader looks for it, and the name at the front.
        assert_eq!(&a[257..262], b"ustar");
        assert_eq!(&a[..6], b"gunnar");
        // Header, one padded data block, two zero blocks.
        assert_eq!(a.len(), BLOCK * 4);
        assert!(
            a[a.len() - BLOCK * 2..].iter().all(|byte| *byte == 0),
            "an archive must end in two zero blocks"
        );
        // The checksum field must be filled in, or `tar` refuses the archive.
        assert_ne!(&a[148..154], b"      ", "the checksum was left blank");
    }

    /// GNU tar is the outside oracle: gunnar's own reader agreeing with
    /// gunnar's own writer would prove nothing.
    #[test]
    fn stock_tar_reads_what_this_writer_produced() {
        let Ok(probe) = std::process::Command::new("tar").arg("--version").output() else {
            eprintln!("skipped: no `tar` on PATH");
            return;
        };
        assert!(probe.status.success());

        let dir = tempfile::tempdir().expect("tempdir");
        let archive = dir.path().join("layer.tar");
        std::fs::write(
            &archive,
            tar(&[Entry {
                path: "gunnar",
                bytes: b"the binary\n",
                mode: 0o755,
            }])
            .expect("tar"),
        )
        .expect("write");

        let out = std::process::Command::new("tar")
            .arg("-xf")
            .arg(&archive)
            .current_dir(dir.path())
            .output()
            .expect("run tar");
        assert!(
            out.status.success(),
            "stock tar refused the layer this writer produced: {}",
            String::from_utf8_lossy(&out.stderr)
        );
        assert_eq!(
            std::fs::read_to_string(dir.path().join("gunnar")).expect("extracted"),
            "the binary\n"
        );
        // **The mode in the ARCHIVE, not on the extracted file.** GNU tar
        // applies the caller's umask on extraction unless it is root or `-p`
        // was passed, so the file on disk here is `0o755 & !umask` and says
        // more about this shell than about the layer. `-tv` prints what the
        // header records, which is the thing under test.
        let listing = std::process::Command::new("tar")
            .arg("-tvf")
            .arg(&archive)
            .output()
            .expect("run tar -tv");
        let listing = String::from_utf8_lossy(&listing.stdout);
        assert!(
            listing.contains("rwxr-xr-x"),
            "the layer does not record the execute bit: {listing}"
        );
        assert!(
            listing.contains("0/0"),
            "the layer records a uid or gid, so it is not reproducible across machines: \
             {listing}"
        );
    }

    #[test]
    fn an_image_is_one_layer_of_one_file_and_names_its_own_parts() {
        let image = build_image(b"ELF...", "/gunnar").expect("image");
        assert_eq!(
            image.files, 1,
            "the scratch image must hold exactly one file"
        );
        let manifest = String::from_utf8(image.manifest.clone()).expect("utf-8");
        assert!(manifest.contains(&image.config_digest));
        assert!(manifest.contains(&image.layer_digest));
        assert!(manifest.contains("application/vnd.oci.image.manifest.v1+json"));
        // Uncompressed on purpose; see the module docs.
        assert!(manifest.contains("application/vnd.oci.image.layer.v1.tar\""));
        assert_eq!(image.digest, digest_of(&image.manifest));

        // Building it twice must produce the same image, or attesting to a
        // digest says nothing about a rebuild.
        assert_eq!(
            build_image(b"ELF...", "/gunnar").expect("again").digest,
            image.digest
        );
        assert_ne!(
            build_image(b"different", "/gunnar").expect("other").digest,
            image.digest,
            "two different binaries produced the same image digest"
        );
    }

    #[test]
    fn a_blob_is_stored_under_its_own_digest_and_read_back_verified() {
        let dir = tempfile::tempdir().expect("tempdir");
        let registry = Registry::under(dir.path());
        let digest = registry.put_blob(b"hello").expect("put");
        assert_eq!(digest, digest_of(b"hello"));
        assert_eq!(
            registry.get_blob(&digest).expect("get").as_deref(),
            Some(&b"hello"[..])
        );
        assert!(registry
            .get_blob(&digest_of(b"absent"))
            .expect("get")
            .is_none());

        // **A blob written around must not read back clean.** The store is
        // content-addressed; if a read does not check, bit rot is a supply
        // chain event.
        let path = registry.blob_path(&digest).expect("path");
        std::fs::write(&path, b"tampered").expect("rewrite");
        let err = registry.get_blob(&digest).expect_err("a rewritten blob");
        assert!(format!("{err}").contains("hashes to"), "{err}");
    }

    #[test]
    fn a_digest_a_client_supplies_cannot_name_bytes_it_does_not_hash_to() {
        let dir = tempfile::tempdir().expect("tempdir");
        let registry = Registry::under(dir.path());
        // There is no API to supply one — that is the point — so what is
        // asserted is that a malformed reference is refused rather than
        // creating a path.
        assert!(registry.get_blob("sha256:short").is_err());
        assert!(registry.get_blob("md5:whatever").is_err());
        assert!(registry
            .get_blob(&format!("sha256:{}", "z".repeat(64)))
            .is_err());
    }

    #[test]
    fn a_tag_may_not_escape_the_registry() {
        let dir = tempfile::tempdir().expect("tempdir");
        let registry = Registry::under(dir.path());
        assert!(registry.tag_path("team/app", "v1").is_ok());
        assert!(registry.tag_path("../escape", "v1").is_err());
        assert!(registry.tag_path("team/app", "../../etc/passwd").is_err());
        assert!(registry.tag_path("team/app", "a/b").is_err());
        assert!(registry.tag_path("", "v1").is_err());
    }

    /// **An absolute name is a destination, and `Path::join` takes it.**
    ///
    /// `join` replaces the whole path when it is handed an absolute one, so a
    /// name beginning with `/` discarded the registry root and the manifest
    /// landed wherever the name pointed. The `..` check never fired: there is
    /// no `..` in `/etc/gunnar`.
    ///
    /// The assertion is on the resulting PATH and not only on the refusal, so a
    /// `tag_path` that started returning `Ok` with the root thrown away could
    /// not satisfy this test by returning an error somewhere else.
    #[test]
    fn an_absolute_name_does_not_become_an_absolute_path() {
        let dir = tempfile::tempdir().expect("tempdir");
        let registry = Registry::under(dir.path());

        for escape in [
            "/etc/gunnar",
            "//etc/gunnar",
            "/",
            "team//app",
            "team/./app",
        ] {
            let refused = registry.tag_path(escape, "v1");
            assert!(
                refused.is_err(),
                "{escape:?} was accepted as a repository name and resolved to {:?}",
                refused.map(|path| path.display().to_string())
            );
        }

        // The accept side, first — without it a `tag_path` that refused
        // everything would pass every line above.
        let legal = registry.tag_path("team/app", "v1").expect("a legal name");
        assert!(
            legal.starts_with(dir.path()),
            "a legal name left the registry root: {}",
            legal.display()
        );
    }

    /// The same hole, reached through the method that WRITES. `put_manifest`
    /// goes through `admit` first, so this drives `resolve`, the read half that
    /// takes the same path and is reachable with no attestation at all.
    #[test]
    fn a_read_cannot_be_steered_out_of_the_registry_either() {
        let dir = tempfile::tempdir().expect("tempdir");
        let registry = Registry::under(dir.path());
        // A file outside the registry, which an absolute name would have read.
        let outside = dir.path().join("secret");
        std::fs::write(&outside, "sha256:not-yours").expect("write");
        let name = outside.to_str().expect("utf-8 tempdir");
        let err = registry.resolve(name, "v1").expect_err("an absolute name");
        assert!(
            format!("{err}").contains("not a usable repository name"),
            "{err}"
        );
    }
}