//! Yubaba release-manifest fetch + per-triple resolution (R330-F21).
//!
//! `.github/workflows/release.yml`'s `yubaba-release-manifest` job publishes
//! `https://cdn.yah.dev/yubaba/release-manifest.json` after every release tag
//! (R330-F19). Operators do not need to memorise per-release URLs and sha256s —
//! `yah cloud machine provision <name>` fetches the manifest once, looks up
//! the entry matching the machine's architecture, and threads the resolved
//! URL + sha256 + sig/cert URLs into the cloud-init render.
//!
//! Per W203 §1.5 + R330-F19's per-triple entries:
//!
//! ```json
//! {
//! "version": "0.9.0",
//! "triples": {
//! "x86_64-unknown-linux-musl": {
//! "url": "https://cdn.yah.dev/yubaba/0.9.0/x86_64-unknown-linux-musl/yah-yubaba-x86_64-unknown-linux-musl.tar.gz",
//! "size": 2345678,
//! "sha256": "abc…",
//! "sig_url": "https://cdn.yah.dev/yubaba/.../...tar.gz.sig",
//! "cert_url": "https://cdn.yah.dev/yubaba/.../...tar.gz.cert"
//! },
//! "aarch64-unknown-linux-musl": { … }
//! }
//! }
//! ```
//!
//! Identity-regexp is *not* per-release — it identifies the workspace's
//! GitHub OIDC identity (matches the cosign sign-blob step in release.yml).
//! See [`DEFAULT_YUBABA_COSIGN_IDENTITY`].
//!
//! @yah:ticket(R599-F1, "R2 bundle store: append-only blob/manifest publish + node-side materialize into kamaji LRU cache")
//! @yah:status(review)
//! @yah:assignee(agent:bundle-anthropic-ashguard)
//! @yah:at(2026-07-20T04:20:25Z)
//! @yah:phase(P1)
//! @yah:parent(R599)
//! @yah:depends_on(R599-F2)
//! @yah:next("R599-F2: wire mesofact-build to EMIT a BundleManifest during a build (add yah-mesofact-bundle default-features=false; assemble app/ + optional bins/ tree, per-file blake3, write manifest.toml). Type already exists -> F2 is 'emit', not 'define'.")
//! @yah:next("R599-F4: kamaji deploy dispatch calls materialize_bundle/BundleCache into kamaji state dir on Deploy of the mesofact bundle variant (add yah-mesofact-bundle features=store + yah-object-store to kamaji).")
//! @yah:next("R599-F8: services-tab sync arm calls cloud reconciler::bundle_store::publish_bundle_to_r2 after building a bundle.")
//! @yah:handoff("LANDED (types + store, 16 tests). New crate oss/yah-base/crates/mesofact-bundle (yah-mesofact-bundle). Default features = serde+blake3+toml TYPES ONLY: BundleManifest, BundleRuntime (self | mesofact/<ver>), BundleHash 64-hex, digest() over canonical length-prefixed fields, blob_key/manifest_key layout. This is what R599-F2's mesofact-build consumes via default-features=false.")
//! @yah:handoff("Feature `store` adds yah-object-store + publish_bundle (append-only blob dedupe via HEAD + blake3 verify + immutable manifest-by-digest PUT), materialize_bundle (fetch+verify+atomic-rename into cache tree, idempotent, path-traversal guarded), BundleCache (LRU-by-digest, bytes budget, 0=unbounded). Store tests via InMemoryObjectStore+tempdir.")
//! @yah:handoff("Canonical annotation kept here in release_manifest.rs (one-block-per-ID); the real work is the new crate (its lib.rs has a prose pointer, not a 2nd @yah block). Wired: yah-base workspace member + root + oss/yubaba [patch.crates-io]. cloud deps it (features=store) -> reconciler::bundle_store::publish_bundle_to_r2 (spawn_blocking R2ObjectStore wrapper) + BundlePublishReport re-export. Type home = new minimal crate (user-approved via ask_user): NOT workload-spec (avoids ts-rs/schemars weight at mesofact boundary), NOT mesofact-build (avoids drift); store logic feature-gated so the boundary stays serde-only.")
//! @yah:verify("cd oss/yah-base && cargo test -p yah-mesofact-bundle (8 pass, types-only)")
//! @yah:verify("cd oss/yah-base && cargo test -p yah-mesofact-bundle --features store (16 pass)")
//! @yah:verify("cd oss/yubaba && cargo test -p cloud --lib reconciler::bundle_store (1 pass)")
use anyhow::{anyhow, bail, Context, Result};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::time::Duration;
/// Canonical manifest URL published by `.github/workflows/release.yml`'s
/// `yubaba-release-manifest` job. Hardcoded so operators don't need to memorise
/// it; operators *can* still override by passing `--yubaba-manifest-url`.
pub const DEFAULT_RELEASE_MANIFEST_URL: &str = "https://cdn.yah.dev/yubaba/release-manifest.json";
/// Default cosign keyless OIDC identity regexp the yubaba release pipeline
/// signs against. Matches the `cosign sign-blob` certificate identity emitted
/// by GitHub Actions when running under `yah-ai/yah` (R330-F19). Operators
/// override with `--yubaba-cosign-identity` to point at a fork's OIDC subject.
pub const DEFAULT_YUBABA_COSIGN_IDENTITY: &str = r"^https://github\.com/yah-ai/yah/";
/// Sigstore Fulcio OIDC issuer for GitHub-Actions-rooted keyless signing —
/// what `.github/workflows/release.yml`'s `cosign sign-blob` step produces
/// (R330-F19). The canonical copy; `cloud_init` and the yah CLI's
/// `yubaba_fetch` both read it from here so the two verify paths can't drift.
pub const COSIGN_OIDC_ISSUER: &str = "https://token.actions.githubusercontent.com";
/// Prefix that selects key-based verification in a cosign-identity spec.
/// See [`ReleaseTrust::parse`].
pub const KEY_TRUST_PREFIX: &str = "key:";
/// How a consumer proves a release artifact is ours (R605-F1).
///
/// The two arms are the verify-side mirror of `yah_qed::SigningIdentity`, and
/// they exist for the same reason: a release cut on QED instead of GitHub
/// cannot use Fulcio keyless, because the public-good Fulcio only issues certs
/// for OIDC issuers on its own configured allowlist. W235 §"Off-GHA forfeits
/// GitHub OIDC keyless cosign" makes the call — key-based cosign, key vaulted
/// in kamaji — so every consumer that verifies a yubaba/CLI artifact has to be
/// able to express both.
///
/// This is carried through the config plumbing as a plain string (the existing
/// `--yubaba-cosign-identity` value, the `RenderInput` field, the manifest's
/// identity regexp) and parsed at the two points that actually shell `cosign`.
/// Keeping the wire type a string is deliberate: it means flipping a fleet to
/// key-based trust is a value change, not a schema migration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ReleaseTrust {
/// Fulcio keyless: pin the certificate identity + the OIDC issuer.
Keyless {
identity_regexp: String,
oidc_issuer: String,
},
/// Key-based: pin the cosign *public* key. `key_ref` is whatever
/// `cosign verify-blob --key` accepts — a `.pub` path, an `https://` URL,
/// or a KMS URI (`awskms://…`, `hashivault://…`).
Key { key_ref: String },
}
impl ReleaseTrust {
/// Parse an operator-supplied cosign-identity spec.
///
/// `key:<ref>` selects key-based verification; anything else is a keyless
/// certificate-identity regexp against [`COSIGN_OIDC_ISSUER`]. The prefix
/// is explicit rather than sniffed, because a KMS URI and a regexp are
/// both arbitrary strings and guessing between them would silently pick
/// the wrong trust model.
pub fn parse(spec: &str) -> Self {
match spec.strip_prefix(KEY_TRUST_PREFIX) {
Some(key_ref) => Self::Key {
key_ref: key_ref.trim().to_string(),
},
None => Self::Keyless {
identity_regexp: spec.to_string(),
oidc_issuer: COSIGN_OIDC_ISSUER.to_string(),
},
}
}
/// Whether verification consumes the `.cert` sidecar. Key-based signatures
/// have no Fulcio certificate, so a consumer must not fail the download
/// when the release published no `.cert` alongside the `.sig`.
pub fn needs_certificate(&self) -> bool {
matches!(self, Self::Keyless { .. })
}
/// The `cosign verify-blob` flags this trust model contributes, in order.
/// The caller appends `--signature`/`--certificate`/the blob itself.
pub fn verify_flags(&self) -> Vec<String> {
match self {
Self::Keyless {
identity_regexp,
oidc_issuer,
} => vec![
"--certificate-identity-regexp".into(),
identity_regexp.clone(),
"--certificate-oidc-issuer".into(),
oidc_issuer.clone(),
],
Self::Key { key_ref } => vec!["--key".into(), key_ref.clone()],
}
}
}
/// One per-triple entry in the manifest. Field order matches what
/// release.yml's `Emit per-triple manifest fragment` step writes.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ManifestTripleEntry {
pub url: String,
pub size: u64,
pub sha256: String,
pub sig_url: String,
pub cert_url: String,
}
/// Top-level shape of `release-manifest.json`.
///
/// The two epoch fields (R625-F2) are **release-wide, not per-triple** — the
/// raft protocol and on-disk layout are architecture-independent, so they sit
/// alongside `version` rather than inside each [`ManifestTripleEntry`]. They are
/// `Option` because manifests published before this field existed carry neither;
/// see [`YubabaReleaseManifest::cluster_epochs`] for why absent must never be
/// read as "compatible".
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct YubabaReleaseManifest {
pub version: String,
/// Wire-compatibility epoch: may a node running this release sit in one raft
/// cluster with a node running some other release. Mixed operation is
/// permitted iff every node shares this integer (W275 "Cluster compatibility
/// epochs"). Sourced from `oss/yubaba/crates/yubaba/cluster-epochs.json`,
/// the same file the binary parses at compile time.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cluster_protocol: Option<u32>,
/// On-disk state epoch: can this release read the previous release's raft
/// log/snapshot, and can you roll **back** to it. Tracked separately from
/// `cluster_protocol` on purpose — openraft 0.9→0.10 broke both at once,
/// which is exactly how one combined flag would have hidden the rollback
/// hazard (W275 §5 "Roll-back is symmetric").
#[serde(default, skip_serializing_if = "Option::is_none")]
pub state_epoch: Option<u32>,
pub triples: BTreeMap<String, ManifestTripleEntry>,
}
impl YubabaReleaseManifest {
/// Look up the manifest entry for the given Rust target triple. Returns a
/// descriptive error listing the available triples so operators can spot a
/// typo or a missing matrix leg at a glance.
pub fn entry(&self, triple: &str) -> Result<&ManifestTripleEntry> {
self.triples.get(triple).ok_or_else(|| {
let available: Vec<_> = self.triples.keys().cloned().collect();
anyhow!(
"release-manifest has no entry for triple '{triple}' (available: {available:?})"
)
})
}
}
/// Map a Hetzner server-type code to a Rust target triple. The current matrix
/// (W203 §1.2) is x86_64 + aarch64 Linux musl. Hetzner's ARM line uses the
/// `cax` prefix (cax11 / cax21 / …) — every other prefix (cpx*, ccx*, cx*) is
/// Intel/AMD x86_64. This is operational truth, not heuristic — Hetzner
/// publishes that mapping in their public pricing page and the catalog crate.
pub fn server_type_to_triple(server_type: &str) -> Result<&'static str> {
if server_type.starts_with("cax") {
Ok("aarch64-unknown-linux-musl")
} else if server_type.starts_with("cpx")
|| server_type.starts_with("ccx")
|| server_type.starts_with("cx")
{
Ok("x86_64-unknown-linux-musl")
} else {
bail!(
"unknown Hetzner server_type '{server_type}' — cannot infer architecture. \
Pass --yubaba-url + --yubaba-sha256 explicitly to skip manifest resolution."
)
}
}
/// Fetch the release-manifest from the canonical URL. Caller picks the runtime;
/// inside `yah cloud machine provision` the existing `tokio::runtime::Runtime`
/// drives this. Surfaces every failure mode loud (no silent placeholder
/// fallback) — operators see an actionable message and pass `--yubaba-url`
/// explicitly to bypass.
pub async fn fetch_release_manifest(url: &str) -> Result<YubabaReleaseManifest> {
let client = reqwest::Client::builder()
.timeout(Duration::from_secs(15))
.user_agent("yah/cloud release-manifest fetcher")
.build()
.context("building http client for release-manifest fetch")?;
let resp = client
.get(url)
.send()
.await
.with_context(|| format!("fetching release-manifest from {url}"))?;
if !resp.status().is_success() {
bail!(
"release-manifest fetch from {url} returned HTTP {} — \
pass --yubaba-url explicitly if the manifest is unreachable",
resp.status()
);
}
let body = resp
.bytes()
.await
.with_context(|| format!("reading release-manifest body from {url}"))?;
let manifest: YubabaReleaseManifest = serde_json::from_slice(&body).with_context(|| {
format!(
"parsing release-manifest from {url} — pass --yubaba-url explicitly if the manifest is malformed"
)
})?;
if manifest.triples.is_empty() {
bail!(
"release-manifest from {url} has no triples — \
pass --yubaba-url explicitly to bypass manifest resolution"
);
}
Ok(manifest)
}
#[cfg(test)]
mod tests {
use super::*;
// ── R605-F1 release trust spec ────────────────────────────────────────
#[test]
fn bare_spec_is_keyless_against_the_default_issuer() {
// Every existing config value must keep meaning exactly what it meant
// before the key arm existed.
assert_eq!(
ReleaseTrust::parse(DEFAULT_YUBABA_COSIGN_IDENTITY),
ReleaseTrust::Keyless {
identity_regexp: DEFAULT_YUBABA_COSIGN_IDENTITY.into(),
oidc_issuer: COSIGN_OIDC_ISSUER.into(),
}
);
}
#[test]
fn key_prefix_selects_key_trust_and_trims() {
assert_eq!(
ReleaseTrust::parse("key: awskms:///alias/yah-release "),
ReleaseTrust::Key {
key_ref: "awskms:///alias/yah-release".into()
}
);
}
#[test]
fn a_kms_uri_without_the_prefix_stays_keyless() {
// Deliberate: sniffing a URI scheme out of a free-form regexp would
// silently swap the trust model. The prefix is the only signal.
assert!(matches!(
ReleaseTrust::parse("awskms:///alias/yah-release"),
ReleaseTrust::Keyless { .. }
));
}
#[test]
fn verify_flags_and_cert_need_track_the_arm() {
let keyless = ReleaseTrust::parse(DEFAULT_YUBABA_COSIGN_IDENTITY);
assert!(keyless.needs_certificate());
assert_eq!(
keyless.verify_flags(),
vec![
"--certificate-identity-regexp".to_string(),
DEFAULT_YUBABA_COSIGN_IDENTITY.to_string(),
"--certificate-oidc-issuer".to_string(),
COSIGN_OIDC_ISSUER.to_string(),
]
);
let keyed = ReleaseTrust::parse("key:cosign.pub");
assert!(!keyed.needs_certificate());
assert_eq!(
keyed.verify_flags(),
vec!["--key".to_string(), "cosign.pub".to_string()]
);
}
#[test]
fn server_type_to_triple_maps_arm_prefix() {
assert_eq!(
server_type_to_triple("cax11").unwrap(),
"aarch64-unknown-linux-musl"
);
assert_eq!(
server_type_to_triple("cax21").unwrap(),
"aarch64-unknown-linux-musl"
);
assert_eq!(
server_type_to_triple("cax41").unwrap(),
"aarch64-unknown-linux-musl"
);
}
#[test]
fn server_type_to_triple_maps_x86_prefixes() {
assert_eq!(
server_type_to_triple("cpx22").unwrap(),
"x86_64-unknown-linux-musl"
);
assert_eq!(
server_type_to_triple("ccx13").unwrap(),
"x86_64-unknown-linux-musl"
);
assert_eq!(
server_type_to_triple("cx32").unwrap(),
"x86_64-unknown-linux-musl"
);
}
#[test]
fn server_type_to_triple_rejects_unknown_prefix() {
let err = server_type_to_triple("xxx99").unwrap_err().to_string();
assert!(err.contains("unknown Hetzner server_type"), "msg: {err}");
assert!(
err.contains("--yubaba-url"),
"msg points to override: {err}"
);
}
#[test]
fn manifest_round_trips_through_json() {
let raw = r#"{
"version": "0.9.0",
"triples": {
"x86_64-unknown-linux-musl": {
"url": "https://cdn.yah.dev/yubaba/0.9.0/x86_64-unknown-linux-musl/yah-yubaba-x86_64-unknown-linux-musl.tar.gz",
"size": 2345678,
"sha256": "abc123",
"sig_url": "https://cdn.yah.dev/yubaba/0.9.0/x86_64-unknown-linux-musl/yah-yubaba-x86_64-unknown-linux-musl.tar.gz.sig",
"cert_url": "https://cdn.yah.dev/yubaba/0.9.0/x86_64-unknown-linux-musl/yah-yubaba-x86_64-unknown-linux-musl.tar.gz.cert"
}
}
}"#;
let parsed: YubabaReleaseManifest = serde_json::from_str(raw).unwrap();
assert_eq!(parsed.version, "0.9.0");
// This manifest predates R625-F2 — the epochs are absent, not zero.
assert_eq!(parsed.cluster_protocol, None);
assert_eq!(parsed.state_epoch, None);
let entry = parsed.entry("x86_64-unknown-linux-musl").unwrap();
assert_eq!(entry.size, 2345678);
assert_eq!(entry.sha256, "abc123");
assert!(entry.sig_url.ends_with(".tar.gz.sig"));
assert!(entry.cert_url.ends_with(".tar.gz.cert"));
}
#[test]
fn manifest_entry_missing_triple_lists_available() {
let raw = r#"{"version":"0.9.0","triples":{"x86_64-unknown-linux-musl":{"url":"u","size":1,"sha256":"s","sig_url":"u.sig","cert_url":"u.cert"}}}"#;
let parsed: YubabaReleaseManifest = serde_json::from_str(raw).unwrap();
let err = parsed
.entry("aarch64-unknown-linux-musl")
.unwrap_err()
.to_string();
assert!(err.contains("aarch64-unknown-linux-musl"));
assert!(
err.contains("x86_64-unknown-linux-musl"),
"lists available: {err}"
);
}
#[test]
fn manifest_carries_the_two_cluster_epochs() {
// R625-F2. The shape release.yml now publishes: two release-wide
// integers alongside `version`, NOT per-triple (raft protocol and
// on-disk layout are architecture-independent).
let raw = r#"{
"version": "0.8.22",
"cluster_protocol": 2,
"state_epoch": 2,
"triples": {
"x86_64-unknown-linux-musl": {
"url": "u", "size": 1, "sha256": "s", "sig_url": "a", "cert_url": "b"
}
}
}"#;
let parsed: YubabaReleaseManifest = serde_json::from_str(raw).unwrap();
assert_eq!(parsed.cluster_protocol, Some(2));
assert_eq!(parsed.state_epoch, Some(2));
// Round-trip keeps them, and a manifest that declares nothing emits
// nothing (rather than an implicit 0, which would read as "declared").
let back: YubabaReleaseManifest =
serde_json::from_str(&serde_json::to_string(&parsed).unwrap()).unwrap();
assert_eq!(back.cluster_protocol, Some(2));
assert_eq!(back.state_epoch, Some(2));
let undeclared = YubabaReleaseManifest {
version: "0.8.20".into(),
cluster_protocol: None,
state_epoch: None,
triples: BTreeMap::new(),
};
let json = serde_json::to_string(&undeclared).unwrap();
assert!(!json.contains("cluster_protocol"), "{json}");
assert!(!json.contains("state_epoch"), "{json}");
}
#[test]
fn default_identity_regexp_matches_yah_ai_yah() {
// Sanity: the constant matches what release.yml's cosign sign-blob
// step emits as the keyless certificate identity. Bumping the org
// requires updating both this constant AND release.yml in lockstep.
assert!(DEFAULT_YUBABA_COSIGN_IDENTITY.contains("yah-ai/yah"));
}
}