use crate::manifest::LayerManifest;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SbomFormat {
CycloneDx,
}
impl std::str::FromStr for SbomFormat {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"cyclonedx" | "cdx" => Ok(SbomFormat::CycloneDx),
other => Err(format!(
"unknown SBOM format '{other}' (supported: cyclonedx)"
)),
}
}
}
fn component(entry: &crate::manifest::ManifestEntry) -> serde_json::Value {
let hex = entry
.digest
.strip_prefix("sha256:")
.unwrap_or(&entry.digest);
let mut props: Vec<serde_json::Value> = Vec::new();
if let Some(platform) = entry.annotations.get("eu.pulseengine.platform") {
props.push(serde_json::json!({"name": "eu.pulseengine.platform", "value": platform}));
}
let ctype = match entry.kind() {
Ok(crate::kind::PayloadKind::Tool) => "application",
Ok(crate::kind::PayloadKind::Layer) => "platform",
Ok(_) => "library",
Err(_) => {
if let Some(raw) = entry.annotations.get(crate::kind::ANN_KIND) {
props.push(serde_json::json!({
"name": "eu.pulseengine.varve.kind.unrecognised",
"value": raw
}));
}
"library"
}
};
let name = match entry.annotations.get("eu.pulseengine.tool") {
Some(n) => n.clone(),
None => {
props.push(serde_json::json!({
"name": "eu.pulseengine.varve.unnamed",
"value": "the signed manifest names no tool for this entry; identified by digest"
}));
format!("sha256-{}", &hex[..hex.len().min(16)])
}
};
let version = entry
.annotations
.get("eu.pulseengine.tool.version")
.cloned()
.unwrap_or_default();
let mut c = serde_json::json!({
"type": ctype,
"name": name,
"version": version,
"hashes": [{"alg": "SHA-256", "content": hex}],
"bom-ref": entry.digest,
});
if let (Some(repo), false) = (
entry.annotations.get("eu.pulseengine.source.repo"),
version.is_empty(),
) && let Some((owner, name)) = repo.split_once('/')
{
c["purl"] = serde_json::json!(format!("pkg:github/{owner}/{name}@{version}"));
}
let repo_owner = entry
.annotations
.get("eu.pulseengine.source.repo")
.and_then(|r| r.split_once('/'))
.map(|(owner, _)| owner);
if let Some(owner) = repo_owner {
c["supplier"] = serde_json::json!({
"name": owner,
"url": [format!("https://github.com/{owner}")]
});
}
if let Some(signer) = entry.annotations.get(crate::ingest::ANN_PROOF_SIGNER) {
props.push(serde_json::json!({
"name": crate::ingest::ANN_PROOF_SIGNER,
"value": signer
}));
if let (Some(repo_owner), Some(signer_owner)) = (repo_owner, github_owner_of(signer))
&& repo_owner != signer_owner
{
props.push(serde_json::json!({
"name": "eu.pulseengine.varve.supplier-signer-differs",
"value": signer_owner
}));
}
}
if entry.kind() == Ok(crate::kind::PayloadKind::Layer) {
c["externalReferences"] = serde_json::json!([{
"type": "bom",
"url": format!("urn:varve:layer:{}", entry.digest)
}]);
return c;
}
if let Some(repo) = entry.annotations.get("eu.pulseengine.source.repo") {
let mut refs = vec![serde_json::json!({
"type": "vcs",
"url": format!("https://github.com/{repo}")
})];
if let (Some(asset), Some(release)) = (
entry.annotations.get("eu.pulseengine.source.asset"),
entry.annotations.get("eu.pulseengine.source.release"),
) {
refs.push(serde_json::json!({
"type": "distribution",
"url": format!("https://github.com/{repo}/releases/download/{release}/{asset}")
}));
}
if let (Some(sbom), Some(release), Some(sha)) = (
entry.annotations.get(crate::ingest::ANN_SBOM),
entry.annotations.get("eu.pulseengine.source.release"),
entry.annotations.get(crate::ingest::ANN_SBOM_SHA256),
) {
refs.push(serde_json::json!({
"type": "bom",
"url": format!("https://github.com/{repo}/releases/download/{release}/{sbom}"),
"hashes": [{"alg": "SHA-256", "content": sha}]
}));
}
c["externalReferences"] = serde_json::Value::Array(refs);
}
match entry.annotations.get(crate::ingest::ANN_LICENSE) {
Some(expr) => {
c["licenses"] =
serde_json::json!([{"expression": expr, "acknowledgement": "declared"}]);
}
None => props.push(serde_json::json!({
"name": "eu.pulseengine.varve.license",
"value": "not recorded: this layer was deposited before varve recorded upstream licenses, \
or upstream declares none GitHub can identify"
})),
}
if !props.is_empty() {
c["properties"] = serde_json::Value::Array(props);
}
c
}
fn github_owner_of(identity: &str) -> Option<&str> {
let rest = identity.strip_prefix("https://github.com/")?;
let owner = rest.split('/').next()?;
(!owner.is_empty()).then_some(owner)
}
pub fn emit(
manifest: &LayerManifest,
manifest_digest: &str,
format: SbomFormat,
root_public_key: &[u8],
) -> String {
let author = crate::store::manifest_digest(root_public_key);
let SbomFormat::CycloneDx = format;
let mut components: Vec<serde_json::Value> = manifest.entries.iter().map(component).collect();
components.sort_by(|a, b| a["bom-ref"].as_str().cmp(&b["bom-ref"].as_str()));
let refs: Vec<serde_json::Value> = components.iter().map(|c| c["bom-ref"].clone()).collect();
let doc = serde_json::json!({
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"version": 1,
"serialNumber": format!("urn:uuid:{}", uuid_from_digest(manifest_digest)),
"metadata": {
"timestamp": manifest.issued_at,
"authors": [{"name": format!("varve realm with root key {author} (whose root signed this layer)")}],
"component": {
"type": "firmware",
"name": format!("varve-layer-{}", manifest.layer),
"version": manifest.layer.to_string(),
"bom-ref": manifest_digest,
},
"properties": [
{"name": "eu.pulseengine.varve.channel", "value": manifest.channel},
{"name": "eu.pulseengine.varve.counter", "value": manifest.counter.to_string()},
{"name": "eu.pulseengine.varve.manifest-digest", "value": manifest_digest},
],
},
"components": components,
"dependencies": [{"ref": manifest_digest, "dependsOn": refs}],
"compositions": [
{"aggregate": "complete", "dependencies": [manifest_digest]},
{"aggregate": "unknown", "dependencies": refs},
],
});
serde_json::to_string_pretty(&doc).expect("sbom serialises")
}
fn uuid_from_digest(digest: &str) -> String {
let hex: String = digest
.strip_prefix("sha256:")
.unwrap_or(digest)
.chars()
.filter(|c| c.is_ascii_hexdigit())
.take(32)
.collect();
let mut h: Vec<u8> = format!("{hex:0<32}").into_bytes();
h[12] = b'8';
h[16] = b'a';
let h = String::from_utf8(h).expect("hex digits stay ascii");
format!(
"{}-{}-{}-{}-{}",
&h[0..8],
&h[8..12],
&h[12..16],
&h[16..20],
&h[20..32]
)
}
#[cfg(test)]
mod tests {
use super::*;
fn manifest() -> (LayerManifest, String) {
let bytes = crate::manifest::fixtures::manifest_with_tools(
"2026.08.0",
"qualified",
7,
"2026-08-01T00:00:00Z",
&[("synth", "sha256:aaaa"), ("rivet", "sha256:bbbb")],
);
let m = LayerManifest::parse(&bytes).unwrap();
(m, "sha256:1234567890abcdef".to_string())
}
#[test]
fn every_component_is_transcribed_from_the_signed_manifest() {
let (m, digest) = manifest();
let doc: serde_json::Value =
serde_json::from_str(&emit(&m, &digest, SbomFormat::CycloneDx, &[7u8; 32])).unwrap();
let comps = doc["components"].as_array().unwrap();
assert_eq!(
comps.len(),
m.entries.len(),
"the SBOM must describe exactly the signed entries — no more, no fewer"
);
for c in comps {
let hex = c["hashes"][0]["content"].as_str().unwrap();
assert!(
m.entries
.iter()
.any(|e| e.digest.strip_prefix("sha256:") == Some(hex)),
"component hash {hex} is not in the signed manifest"
);
}
assert_eq!(doc["bomFormat"], "CycloneDX");
assert_eq!(doc["specVersion"], "1.6");
}
#[test]
fn per_platform_entries_are_distinguishable_not_duplicates() {
let bytes = crate::manifest::fixtures::manifest_with_platform_tools(
"2026.08.0",
"qualified",
1,
"2026-08-01T00:00:00Z",
&[
("kilnd", "sha256:aaaa", Some("x86_64-unknown-linux-gnu")),
("kilnd", "sha256:bbbb", Some("aarch64-apple-darwin")),
],
);
let m = LayerManifest::parse(&bytes).unwrap();
let doc: serde_json::Value =
serde_json::from_str(&emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[7u8; 32]))
.unwrap();
let comps = doc["components"].as_array().unwrap();
assert_eq!(comps.len(), 2);
let platforms: Vec<&str> = comps
.iter()
.map(|c| c["properties"][0]["value"].as_str().unwrap())
.collect();
assert!(platforms.contains(&"x86_64-unknown-linux-gnu"));
assert!(platforms.contains(&"aarch64-apple-darwin"));
}
#[test]
fn no_signed_entry_is_ever_dropped_from_the_document() {
let bytes = br#"{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.index.v1+json",
"artifactType": "application/vnd.pulseengine.varve.layer.v1+json",
"annotations": {
"eu.pulseengine.varve.layer": "2026.08.0",
"eu.pulseengine.varve.channel": "qualified",
"eu.pulseengine.varve.counter": "1",
"org.opencontainers.image.created": "2026-08-01T00:00:00Z"
},
"manifests": [
{ "digest": "sha256:aaaa", "annotations": { "eu.pulseengine.tool": "synth", "eu.pulseengine.tool.version": "1.0.0" } },
{ "digest": "sha256:bbbb", "annotations": { "eu.pulseengine.tool": "future", "eu.pulseengine.varve.kind": "quantum-blob" } },
{ "digest": "sha256:cccc", "annotations": { "eu.pulseengine.platform": "riscv64-unknown-none" } }
]
}"#;
let m = LayerManifest::parse(bytes).unwrap();
assert_eq!(m.entries.len(), 3, "fixture sanity");
let doc: serde_json::Value =
serde_json::from_str(&emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[7u8; 32]))
.unwrap();
let comps = doc["components"].as_array().unwrap();
assert_eq!(
comps.len(),
3,
"every signed entry must appear; got {comps:#?}"
);
for e in &m.entries {
assert!(
comps.iter().any(|c| c["bom-ref"] == e.digest.as_str()),
"signed entry {} is missing from the document",
e.digest
);
}
}
#[test]
fn emission_is_deterministic() {
let (m, digest) = manifest();
let a = emit(&m, &digest, SbomFormat::CycloneDx, &[7u8; 32]);
let b = emit(&m, &digest, SbomFormat::CycloneDx, &[7u8; 32]);
assert_eq!(a, b, "the same layer must emit a byte-identical document");
let doc: serde_json::Value = serde_json::from_str(&a).unwrap();
assert_eq!(doc["metadata"]["timestamp"], "2026-08-01T00:00:00Z");
}
#[test]
fn the_document_binds_itself_to_the_layer_it_describes() {
let (m, digest) = manifest();
let doc: serde_json::Value =
serde_json::from_str(&emit(&m, &digest, SbomFormat::CycloneDx, &[7u8; 32])).unwrap();
assert_eq!(doc["metadata"]["component"]["bom-ref"], digest);
let props = doc["metadata"]["properties"].as_array().unwrap();
assert!(
props
.iter()
.any(|p| p["name"] == "eu.pulseengine.varve.manifest-digest"
&& p["value"] == digest.as_str()),
"the manifest digest must be recorded in the document"
);
assert!(
props
.iter()
.any(|p| p["name"] == "eu.pulseengine.varve.counter" && p["value"] == "7"),
"the anti-rollback counter belongs in the document"
);
}
#[test]
fn an_unknown_format_is_refused_not_guessed() {
assert!("cyclonedx".parse::<SbomFormat>().is_ok());
assert!("spdx".parse::<SbomFormat>().is_err());
assert!("".parse::<SbomFormat>().is_err());
}
const FIELDS: &[u8] = br#"{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.index.v1+json",
"artifactType": "application/vnd.pulseengine.varve.layer.v1+json",
"annotations": {
"eu.pulseengine.varve.layer": "2026.10.0",
"eu.pulseengine.varve.channel": "rolling",
"eu.pulseengine.varve.counter": "0",
"org.opencontainers.image.created": "2026-10-01T00:00:00Z"
},
"manifests": [
{ "digest": "sha256:aaaa", "annotations": {
"eu.pulseengine.tool": "kilnd", "eu.pulseengine.tool.version": "0.5.0",
"eu.pulseengine.source.repo": "pulseengine/kiln",
"eu.pulseengine.source.release": "v0.5.0",
"eu.pulseengine.source.asset": "kiln-v0.5.0-x86_64-unknown-linux-gnu.tar.gz",
"eu.pulseengine.source.license": "Apache-2.0 OR MIT",
"eu.pulseengine.source.sbom": "kiln-0.5.0.cdx.json",
"eu.pulseengine.source.sbom.sha256": "5555555555555555555555555555555555555555555555555555555555555555" } },
{ "digest": "sha256:bbbb", "annotations": {
"eu.pulseengine.tool": "rivet", "eu.pulseengine.tool.version": "0.40.0",
"eu.pulseengine.source.repo": "pulseengine/rivet",
"eu.pulseengine.source.release": "v0.40.0" } },
{ "digest": "sha256:cccc", "annotations": { "eu.pulseengine.platform": "riscv64-unknown-none" } }
]
}"#;
fn fields_doc() -> serde_json::Value {
let m = LayerManifest::parse(FIELDS).unwrap();
serde_json::from_str(&emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[7u8; 32])).unwrap()
}
fn comp<'a>(doc: &'a serde_json::Value, digest: &str) -> &'a serde_json::Value {
doc["components"]
.as_array()
.unwrap()
.iter()
.find(|c| c["bom-ref"] == digest)
.unwrap()
}
#[test]
fn each_component_names_the_upstream_that_supplied_it() {
let doc = fields_doc();
assert_eq!(
comp(&doc, "sha256:aaaa")["supplier"],
serde_json::json!({"name": "pulseengine", "url": ["https://github.com/pulseengine"]})
);
assert!(comp(&doc, "sha256:cccc").get("supplier").is_none());
}
#[test]
fn the_supplier_is_the_repo_owner_and_a_different_signer_is_recorded_not_obeyed() {
let manifest = br#"{
"annotations": {
"eu.pulseengine.varve.layer": "2026.10.0", "eu.pulseengine.varve.channel": "rolling",
"eu.pulseengine.varve.counter": "0", "org.opencontainers.image.created": "2026-10-01T00:00:00Z"
},
"manifests": [
{ "digest": "sha256:1111", "annotations": {
"eu.pulseengine.tool": "wasmtime", "eu.pulseengine.tool.version": "49.0.1",
"eu.pulseengine.source.repo": "bytecodealliance/wasmtime",
"eu.pulseengine.source.proof": "build-provenance",
"eu.pulseengine.source.proof-signer": "https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v2.0.0" } },
{ "digest": "sha256:2222", "annotations": {
"eu.pulseengine.tool": "b", "eu.pulseengine.tool.version": "1.0.0",
"eu.pulseengine.source.repo": "owner/b",
"eu.pulseengine.source.proof": "cosign-sums",
"eu.pulseengine.source.proof-signer": "https://github.com/owner/b/.github/workflows/release.yml@refs/tags/v1.0.0" } },
{ "digest": "sha256:3333", "annotations": {
"eu.pulseengine.tool": "c", "eu.pulseengine.tool.version": "1.0.0",
"eu.pulseengine.source.repo": "owner/c",
"eu.pulseengine.source.proof": "cosign-sums",
"eu.pulseengine.source.proof-signer": "release-bot@example.org" } },
{ "digest": "sha256:4444", "annotations": {
"eu.pulseengine.tool": "d", "eu.pulseengine.tool.version": "1.0.0",
"eu.pulseengine.source.repo": "owner/d" } },
{ "digest": "sha256:5555", "annotations": {
"eu.pulseengine.tool": "e", "eu.pulseengine.tool.version": "1.0.0",
"eu.pulseengine.source.proof": "cosign-sums",
"eu.pulseengine.source.proof-signer": "https://github.com/only-signer/e/.github/workflows/r.yml@refs/heads/main" } }
]
}"#;
let m = LayerManifest::parse(manifest).unwrap();
let doc: serde_json::Value =
serde_json::from_str(&emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[7u8; 32]))
.unwrap();
let prop = |d: &str, name: &str| -> Option<String> {
comp(&doc, d)["properties"]
.as_array()
.and_then(|ps| ps.iter().find(|p| p["name"] == name))
.map(|p| p["value"].as_str().unwrap().to_string())
};
const DIFFERS: &str = "eu.pulseengine.varve.supplier-signer-differs";
const SIGNER: &str = "eu.pulseengine.source.proof-signer";
assert_eq!(
comp(&doc, "sha256:1111")["supplier"],
serde_json::json!({"name": "bytecodealliance", "url": ["https://github.com/bytecodealliance"]})
);
assert_eq!(
prop("sha256:1111", DIFFERS).as_deref(),
Some("slsa-framework")
);
assert!(
prop("sha256:1111", SIGNER)
.unwrap()
.contains("slsa-github-generator")
);
assert_eq!(
comp(&doc, "sha256:2222")["supplier"],
serde_json::json!({"name": "owner", "url": ["https://github.com/owner"]})
);
assert!(prop("sha256:2222", SIGNER).is_some());
assert_eq!(prop("sha256:2222", DIFFERS), None);
assert_eq!(comp(&doc, "sha256:3333")["supplier"]["name"], "owner");
assert!(prop("sha256:3333", SIGNER).is_some());
assert_eq!(prop("sha256:3333", DIFFERS), None);
assert_eq!(comp(&doc, "sha256:4444")["supplier"]["name"], "owner");
assert_eq!(prop("sha256:4444", SIGNER), None);
assert_eq!(prop("sha256:4444", DIFFERS), None);
assert!(comp(&doc, "sha256:5555").get("supplier").is_none());
assert!(prop("sha256:5555", SIGNER).is_some());
assert_eq!(prop("sha256:5555", DIFFERS), None);
}
#[test]
fn the_author_is_named_by_the_roots_fingerprint_not_a_local_label() {
let m = LayerManifest::parse(FIELDS).unwrap();
let a = emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[1u8; 32]);
let b = emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[2u8; 32]);
let name = |s: &str| {
let v: serde_json::Value = serde_json::from_str(s).unwrap();
v["metadata"]["authors"][0]["name"]
.as_str()
.unwrap()
.to_string()
};
let fp = crate::store::manifest_digest(&[1u8; 32]);
assert!(name(&a).contains(&fp), "{}", name(&a));
assert_ne!(name(&a), name(&b), "a different root is a different author");
assert_eq!(
a,
emit(&m, "sha256:dd", SbomFormat::CycloneDx, &[1u8; 32]),
"the same root and manifest must re-emit byte-identically"
);
}
#[test]
fn the_document_names_the_realm_that_signed_it_as_author() {
let doc = fields_doc();
let authors = doc["metadata"]["authors"].as_array().unwrap();
assert_eq!(authors.len(), 1);
let fp = crate::store::manifest_digest(&[7u8; 32]);
let name = authors[0]["name"].as_str().unwrap();
assert!(name.contains(&fp), "{authors:?}");
assert!(name.contains("signed this layer"), "{authors:?}");
}
#[test]
fn the_layer_depends_on_every_component_and_their_own_are_unknown() {
let doc = fields_doc();
assert_eq!(
doc["dependencies"],
serde_json::json!([{
"ref": "sha256:dd",
"dependsOn": ["sha256:aaaa", "sha256:bbbb", "sha256:cccc"]
}])
);
assert_eq!(
doc["compositions"],
serde_json::json!([
{"aggregate": "complete", "dependencies": ["sha256:dd"]},
{"aggregate": "unknown", "dependencies": ["sha256:aaaa", "sha256:bbbb", "sha256:cccc"]}
])
);
}
#[test]
fn a_recorded_license_is_emitted_as_declared() {
let doc = fields_doc();
assert_eq!(
comp(&doc, "sha256:aaaa")["licenses"],
serde_json::json!([{"expression": "Apache-2.0 OR MIT", "acknowledgement": "declared"}])
);
}
#[test]
fn an_unrecorded_license_is_said_to_be_unrecorded() {
let doc = fields_doc();
let c = comp(&doc, "sha256:bbbb");
assert!(c.get("licenses").is_none());
let props = c["properties"].as_array().unwrap();
assert!(
props
.iter()
.any(|p| p["name"] == "eu.pulseengine.varve.license"
&& p["value"].as_str().unwrap().contains("not recorded")),
"{props:?}"
);
}
#[test]
fn a_recorded_upstream_sbom_is_referenced_with_its_digest() {
let doc = fields_doc();
let refs = comp(&doc, "sha256:aaaa")["externalReferences"]
.as_array()
.unwrap();
assert!(
refs.contains(&serde_json::json!({
"type": "bom",
"url": "https://github.com/pulseengine/kiln/releases/download/v0.5.0/kiln-0.5.0.cdx.json",
"hashes": [{"alg": "SHA-256", "content": "5555555555555555555555555555555555555555555555555555555555555555"}]
})),
"{refs:?}"
);
assert!(
!comp(&doc, "sha256:bbbb")["externalReferences"]
.as_array()
.unwrap()
.iter()
.any(|r| r["type"] == "bom")
);
}
#[test]
fn the_serial_number_is_derived_from_the_digest() {
let digest = format!("sha256:{}", "0123456789abcdef".repeat(4));
assert_eq!(
uuid_from_digest(&digest),
"01234567-89ab-8def-a123-456789abcdef"
);
assert_ne!(
uuid_from_digest(&digest),
uuid_from_digest(&format!("sha256:{}", "f".repeat(64)))
);
}
}