oci: Extend with more OCI-native manifest/config storage

Previously, composefs-oci only stored the config and layer data but
discarded the OCI manifest after pulling. This forced downstream
consumers (like bootc) to implement manifest storage internally,
which doesn't really make sense.

My opinion is that while the true "composefs core" is today and
should remain logically flexible, there's absolutely not reason for
us not to have a very opinionated mechanism to store OCI. Very very
key to this is that OCI is not just container images (with tar media
types) - there's nowadays OCI artifacts which allow storing arbitrary
data easily - and I think mapping "foreign" types to OCI makes a
ton of sense.

So as part of this the composefs-oci layer also learns how to handle
non-tar layers from manifests.

- Manifests stored at `oci-manifest-{digest}` with refs to config/layers
- Named tags under `streams/refs/oci/{name}` act as GC roots
- New `OciImage` type provides high-level access to stored images
- `pull_image()` returns `PullResult` with both manifest and config info
- Original `pull()` maintained for backward compatibility

CLI additions (cfsctl oci):
- `images` - list all tagged OCI images
- `inspect <image>` - show image details (arch, labels, layers, etc.)
- `tag <digest> <name>` - tag an image by manifest digest
- `untag <name>` - remove a tag

The storage model follows OCI semantics: everything is content-addressed,
manifests reference their components, and tags are just named pointers
to manifests. This enables offline access to all image metadata and
proper garbage collection of unreferenced content.

See-also: bootc-dev/bootc#1830

Assisted-by: OpenCode (Opus 4.5)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

crates/cfsctl/src/main.rs

@@ -73,10 +73,34 @@ enum OciCommand {
         #[clap(long)]
         bootable: bool,
     },
+    /// Pull an OCI image from a registry
     Pull {
+        /// Image reference (e.g., docker://registry.io/image:tag)
         image: String,
+        /// Tag to assign to the image in the local repository
         name: Option<String>,
     },
+    /// List all tagged OCI images in the repository
+    #[clap(name = "images")]
+    ListImages,
+    /// Show information about an OCI image
+    #[clap(name = "inspect")]
+    Inspect {
+        /// Image reference (tag name or manifest digest)
+        image: String,
+    },
+    /// Tag an image with a new name
+    Tag {
+        /// Manifest digest (sha256:...)
+        manifest_digest: String,
+        /// Tag name to assign
+        name: String,
+    },
+    /// Remove a tag from an image
+    Untag {
+        /// Tag name to remove
+        name: String,
+    },
     ComputeId {
         config_name: String,
         config_verity: Option<String>,
@@ -298,11 +322,110 @@ where
                 println!("{}", image_id.to_id());
             }
             OciCommand::Pull { ref image, name } => {
-                let (digest, verity) =
-                    composefs_oci::pull(&Arc::new(repo), image, name.as_deref(), None).await?;
+                // If no explicit name provided, use the image reference as the tag
+                let tag_name = name.as_deref().unwrap_or(image);
+                let result =
+                    composefs_oci::pull_image(&Arc::new(repo), image, Some(tag_name), None).await?;
 
-                println!("config {digest}");
-                println!("verity {}", verity.to_hex());
+                println!("manifest {}", result.manifest_digest);
+                println!("config   {}", result.config_digest);
+                println!("verity   {}", result.manifest_verity.to_hex());
+                println!("tagged   {tag_name}");
+            }
+            OciCommand::ListImages => {
+                let images = composefs_oci::oci_image::list_images(&repo)?;
+
+                if images.is_empty() {
+                    println!("No images found");
+                } else {
+                    println!(
+                        "{:<30} {:<12} {:<10} {:<8} {:<6}",
+                        "NAME", "DIGEST", "ARCH", "SEALED", "LAYERS"
+                    );
+                    for img in images {
+                        let digest_short = img
+                            .manifest_digest
+                            .strip_prefix("sha256:")
+                            .unwrap_or(&img.manifest_digest);
+                        let digest_display = if digest_short.len() > 12 {
+                            &digest_short[..12]
+                        } else {
+                            digest_short
+                        };
+                        println!(
+                            "{:<30} {:<12} {:<10} {:<8} {:<6}",
+                            img.name,
+                            digest_display,
+                            if img.architecture.is_empty() {
+                                "artifact"
+                            } else {
+                                &img.architecture
+                            },
+                            if img.sealed { "yes" } else { "no" },
+                            img.layer_count
+                        );
+                    }
+                }
+            }
+            OciCommand::Inspect { ref image } => {
+                let img = if image.starts_with("sha256:") {
+                    composefs_oci::oci_image::OciImage::open(&repo, image, None)?
+                } else {
+                    composefs_oci::oci_image::OciImage::open_ref(&repo, image)?
+                };
+
+                println!("Manifest:     {}", img.manifest_digest());
+                println!("Config:       {}", img.config_digest());
+                println!(
+                    "Type:         {}",
+                    if img.is_container_image() {
+                        "container"
+                    } else {
+                        "artifact"
+                    }
+                );
+
+                if img.is_container_image() {
+                    println!("Architecture: {}", img.architecture());
+                    println!("OS:           {}", img.os());
+                }
+
+                if let Some(created) = img.created() {
+                    println!("Created:      {created}");
+                }
+
+                println!(
+                    "Sealed:       {}",
+                    if img.is_sealed() { "yes" } else { "no" }
+                );
+                if let Some(seal) = img.seal_digest() {
+                    println!("Seal digest:  {seal}");
+                }
+
+                println!("Layers:       {}", img.layer_descriptors().len());
+                for (i, layer) in img.layer_descriptors().iter().enumerate() {
+                    println!("  [{i}] {} ({} bytes)", layer.digest(), layer.size());
+                }
+
+                if let Some(labels) = img.labels() {
+                    if !labels.is_empty() {
+                        println!("Labels:");
+                        for (k, v) in labels {
+                            println!("  {k}: {v}");
+                        }
+                    }
+                }
+            }
+            OciCommand::Tag {
+                ref manifest_digest,
+                ref name,
+            } => {
+                composefs_oci::oci_image::tag_image(&repo, manifest_digest, name)?;
+                println!("Tagged {manifest_digest} as {name}");
+            }
+            OciCommand::Untag { ref name } => {
+                composefs_oci::oci_image::untag_image(&repo, name)?;
+                println!("Removed tag {name}");
             }
             OciCommand::Seal {
                 ref config_name,

crates/composefs-oci/Cargo.toml

@@ -29,6 +29,7 @@ tokio-util = { version = "0.7", default-features = false, features = ["io"] }
 [dev-dependencies]
 similar-asserts = "1.7.0"
 composefs = { workspace = true, features = ["test"] }
+ocidir = "0.6.0"
 once_cell = "1.21.3"
 tempfile = "3.8.0"
 

crates/composefs-oci/src/lib.rs

@@ -11,6 +11,7 @@
 //! - Sealing containers with fs-verity hashes for integrity verification
 
 pub mod image;
+pub mod oci_image;
 pub mod skopeo;
 pub mod tar;
 
@@ -26,6 +27,13 @@ use composefs::{fsverity::FsVerityHashValue, repository::Repository};
 use crate::skopeo::{OCI_CONFIG_CONTENT_TYPE, TAR_LAYER_CONTENT_TYPE};
 use crate::tar::get_entry;
 
+// Re-export key types for convenience
+pub use oci_image::{
+    list_images, list_refs, resolve_ref, tag_image, untag_image, ImageInfo, OciImage,
+    OCI_REF_PREFIX,
+};
+pub use skopeo::{pull_image, PullResult};
+
 type ContentAndVerity<ObjectID> = (String, ObjectID);
 
 fn layer_identifier(diff_id: &str) -> String {
@@ -123,7 +131,11 @@ pub fn open_config<ObjectID: FsVerityHashValue>(
         // No verity means we need to verify the content hash
         let mut data = vec![];
         stream.read_to_end(&mut data)?;
-        ensure!(config_digest == hash(&data), "Data integrity issue");
+        let computed = hash(&data);
+        ensure!(
+            config_digest == computed,
+            "Config integrity check failed: expected {config_digest}, got {computed}"
+        );
         ImageConfiguration::from_reader(&data[..])?
     } else {
         ImageConfiguration::from_reader(&mut stream)?
@@ -252,4 +264,81 @@ mod test {
 /file4097 4097 100700 1 0 0 0 0.0 09/3756e4ea9683329106d4a16982682ed182c14bf076463a9e7f97305cbac743 - 093756e4ea9683329106d4a16982682ed182c14bf076463a9e7f97305cbac743
 ");
     }
+
+    #[test]
+    fn test_write_and_open_config() {
+        use oci_spec::image::{ImageConfigurationBuilder, RootFsBuilder};
+
+        let repo_dir = tempdir();
+        let repo = Arc::new(Repository::<Sha256HashValue>::open_path(CWD, &repo_dir).unwrap());
+
+        // Create a minimal config
+        let rootfs = RootFsBuilder::default()
+            .typ("layers")
+            .diff_ids(vec!["sha256:abc123def456".to_string()])
+            .build()
+            .unwrap();
+
+        let config = ImageConfigurationBuilder::default()
+            .architecture("amd64")
+            .os("linux")
+            .rootfs(rootfs)
+            .build()
+            .unwrap();
+
+        // Create layer refs (simulating what happens during pull)
+        let mut refs = HashMap::new();
+        refs.insert("sha256:abc123def456".into(), Sha256HashValue::EMPTY);
+
+        // Write the config
+        let (config_digest, config_verity) = write_config(&repo, &config, refs.clone()).unwrap();
+
+        // Verify the digest format
+        assert!(config_digest.starts_with("sha256:"));
+
+        // Open the config with verity (fast path)
+        let (opened_config, opened_refs) =
+            open_config(&repo, &config_digest, Some(&config_verity)).unwrap();
+        assert_eq!(opened_config.architecture().to_string(), "amd64");
+        assert_eq!(opened_config.os().to_string(), "linux");
+        assert_eq!(opened_refs.len(), 1);
+        assert!(opened_refs.contains_key("sha256:abc123def456"));
+
+        // Open the config without verity (verifies content hash)
+        let (opened_config2, _) = open_config(&repo, &config_digest, None).unwrap();
+        assert_eq!(opened_config2.architecture().to_string(), "amd64");
+    }
+
+    #[test]
+    fn test_open_config_bad_hash() {
+        use oci_spec::image::{ImageConfigurationBuilder, RootFsBuilder};
+
+        let repo_dir = tempdir();
+        let repo = Arc::new(Repository::<Sha256HashValue>::open_path(CWD, &repo_dir).unwrap());
+
+        // Create and write a config
+        let rootfs = RootFsBuilder::default()
+            .typ("layers")
+            .diff_ids(vec![])
+            .build()
+            .unwrap();
+
+        let config = ImageConfigurationBuilder::default()
+            .architecture("amd64")
+            .os("linux")
+            .rootfs(rootfs)
+            .build()
+            .unwrap();
+
+        let (config_digest, _config_verity) = write_config(&repo, &config, HashMap::new()).unwrap();
+
+        // Try to open with a wrong digest (should fail)
+        let bad_digest = "sha256:0000000000000000000000000000000000000000000000000000000000000000";
+        let result = open_config::<Sha256HashValue>(&repo, bad_digest, None);
+        assert!(result.is_err());
+
+        // Opening with correct digest should work
+        let result = open_config::<Sha256HashValue>(&repo, &config_digest, None);
+        assert!(result.is_ok());
+    }
 }