Bootstrap legacy snapshot generations safely

eldryoth · eldryoth · commit 4b6592187da5 · 2026-07-11T20:59:26.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -62,6 +62,10 @@ behavior when the change improves security or project direction.
   legacy manifests remain fully verifiable for current, rollback, and doctor
   operations and are atomically migrated after verification during the next
   locked snapshot creation.
+- Bootstrap authenticated generation state for a fully verified store whose
+  retained manifests all predate generation witnesses. Fluxheim persists the
+  authenticated high-water mark before migrating those manifests and publishing
+  generation `max + 1`; missing state still fails closed for V2 or mixed stores.
 - Make OpenSSL cipher allow-lists deterministic across protocol families:
   omitting all TLS 1.2 or TLS 1.3 suites now disables that protocol version
   instead of retaining Mozilla acceptor defaults. Use the current Mozilla v5
diff --git a/crates/fluxheim-snapshot/src/generation.rs b/crates/fluxheim-snapshot/src/generation.rs
@@ -25,18 +25,25 @@ struct GenerationState {
     hmac_sha256: Option<String>,
 }
 
+struct GenerationObservation {
+    maximum: u64,
+    legacy_ids: Vec<String>,
+    allow_missing_state: bool,
+}
+
 impl SnapshotStore {
     pub(crate) fn allocate_generation_unlocked(&self) -> Result<u64, SnapshotError> {
-        let observed_max = self.observed_max_generation(true)?;
+        let observation = self.observe_generations()?;
         let current = match read_optional_regular_file_to_string_with_limit(
             &self.generation_path(),
             MAX_GENERATION_STATE_BYTES as u64,
         )? {
             Some(raw) => self.decode_generation_state(&raw)?,
-            None if observed_max == 0 => 0,
+            None if observation.maximum == 0 => 0,
+            None if observation.allow_missing_state => observation.maximum,
             None => return Err(SnapshotError::GenerationStateInvalid),
         };
-        if current < observed_max {
+        if current < observation.maximum {
             return Err(SnapshotError::GenerationStateInvalid);
         }
         let next = current
@@ -47,24 +54,29 @@ impl SnapshotStore {
             return Err(SnapshotError::GenerationStateInvalid);
         }
         write_atomically(&self.generation_path(), raw.as_bytes())?;
+        if let Some(key) = self.integrity.as_deref() {
+            for id in observation.legacy_ids {
+                self.migrate_legacy_manifest(&id, key)?;
+            }
+        }
         Ok(next)
     }
 
     pub(crate) fn verify_generation_state(&self) -> Result<(), SnapshotError> {
-        let observed_max = self.observed_max_generation(false)?;
+        let observation = self.observe_generations()?;
         let Some(raw) = read_optional_regular_file_to_string_with_limit(
             &self.generation_path(),
             MAX_GENERATION_STATE_BYTES as u64,
         )?
         else {
-            return if observed_max == 0 {
+            return if observation.maximum == 0 || observation.allow_missing_state {
                 Ok(())
             } else {
                 Err(SnapshotError::GenerationStateInvalid)
             };
         };
         let persisted = self.decode_generation_state(&raw)?;
-        if persisted < observed_max {
+        if persisted < observation.maximum {
             return Err(SnapshotError::GenerationStateInvalid);
         }
         Ok(())
@@ -122,22 +134,31 @@ impl SnapshotStore {
         self.root().join("generation.toml")
     }
 
-    fn observed_max_generation(&self, migrate_legacy: bool) -> Result<u64, SnapshotError> {
+    fn observe_generations(&self) -> Result<GenerationObservation, SnapshotError> {
         if !self.safe_existing_configs_dir()? {
-            return Ok(0);
+            return Ok(GenerationObservation {
+                maximum: 0,
+                legacy_ids: Vec::new(),
+                allow_missing_state: false,
+            });
         }
         if let Some(key) = self.integrity.as_deref() {
-            return self.observed_authenticated_generation(key, migrate_legacy);
+            return self.observe_authenticated_generations(key);
         }
-        self.observed_unverified_generation()
+        Ok(GenerationObservation {
+            maximum: self.observed_unverified_generation()?,
+            legacy_ids: Vec::new(),
+            allow_missing_state: false,
+        })
     }
 
-    fn observed_authenticated_generation(
+    fn observe_authenticated_generations(
         &self,
         key: &SnapshotIntegrityKey,
-        migrate_legacy: bool,
-    ) -> Result<u64, SnapshotError> {
+    ) -> Result<GenerationObservation, SnapshotError> {
         let mut maximum = 0;
+        let mut legacy_ids = Vec::new();
+        let mut snapshot_count = 0_usize;
         for entry in fs::read_dir(self.configs_dir()).map_err(SnapshotError::Io)? {
             let path = entry.map_err(SnapshotError::Io)?.path();
             if path.extension().and_then(|extension| extension.to_str()) != Some("toml") {
@@ -149,6 +170,7 @@ impl SnapshotStore {
             if id.ends_with(".meta") || id.ends_with(".integrity") {
                 continue;
             }
+            snapshot_count = snapshot_count.saturating_add(1);
             validate_snapshot_id(id).map_err(|_| SnapshotError::GenerationStateInvalid)?;
             if !regular_snapshot_file_exists(&path)? {
                 return Err(SnapshotError::GenerationStateInvalid);
@@ -164,21 +186,27 @@ impl SnapshotStore {
                     key.verify_generation_witness(id, witness)
                 }
                 SnapshotIntegrityManifest::V1(_) => {
-                    self.verify_legacy_generation(id, key, &manifest, migrate_legacy)
+                    let generation = self.verify_legacy_generation(id, key, &manifest)?;
+                    legacy_ids.push(id.to_owned());
+                    Ok(generation)
                 }
             }
             .map_err(generation_scan_error)?;
             maximum = maximum.max(generation);
         }
-        Ok(maximum)
+        let allow_missing_state = snapshot_count != 0 && legacy_ids.len() == snapshot_count;
+        Ok(GenerationObservation {
+            maximum,
+            legacy_ids,
+            allow_missing_state,
+        })
     }
 
     fn verify_legacy_generation(
         &self,
         id: &str,
         key: &SnapshotIntegrityKey,
         manifest: &SnapshotIntegrityManifest,
-        migrate: bool,
     ) -> Result<u64, SnapshotError> {
         let config = read_regular_file_to_string_with_limit(
             &self.config_path(id),
@@ -198,22 +226,54 @@ impl SnapshotStore {
             metadata.generation,
             manifest,
         )?;
-        if migrate {
-            let witness = key.manifest(
-                id,
-                config.as_bytes(),
-                metadata_raw.as_bytes(),
-                metadata.generation,
-            )?;
-            let raw = toml::to_string_pretty(&witness).map_err(SnapshotError::Encode)?;
-            if raw.len() as u64 > MAX_INTEGRITY_MANIFEST_BYTES {
-                return Err(SnapshotError::GenerationStateInvalid);
-            }
-            write_atomically(&self.integrity_path(id), raw.as_bytes())?;
-        }
         Ok(metadata.generation)
     }
 
+    fn migrate_legacy_manifest(
+        &self,
+        id: &str,
+        key: &SnapshotIntegrityKey,
+    ) -> Result<(), SnapshotError> {
+        let raw = read_regular_file_to_string_with_limit(
+            &self.integrity_path(id),
+            MAX_INTEGRITY_MANIFEST_BYTES,
+        )?;
+        let manifest: SnapshotIntegrityManifest =
+            toml::from_str(&raw).map_err(SnapshotError::Decode)?;
+        if matches!(manifest, SnapshotIntegrityManifest::V2(_)) {
+            return Ok(());
+        }
+        let config = read_regular_file_to_string_with_limit(
+            &self.config_path(id),
+            crate::store_fs::MAX_SNAPSHOT_FILE_BYTES,
+        )?;
+        let metadata_raw = read_regular_file_to_string_with_limit(
+            &self.metadata_path(id),
+            MAX_SNAPSHOT_METADATA_BYTES,
+        )?;
+        let metadata: SnapshotMetadata =
+            toml::from_str(&metadata_raw).map_err(SnapshotError::Decode)?;
+        validate_snapshot_metadata(&metadata, id)?;
+        key.verify(
+            id,
+            config.as_bytes(),
+            metadata_raw.as_bytes(),
+            metadata.generation,
+            &manifest,
+        )?;
+        let witness = key.manifest(
+            id,
+            config.as_bytes(),
+            metadata_raw.as_bytes(),
+            metadata.generation,
+        )?;
+        let raw = toml::to_string_pretty(&witness).map_err(SnapshotError::Encode)?;
+        if raw.len() as u64 > MAX_INTEGRITY_MANIFEST_BYTES {
+            return Err(SnapshotError::GenerationStateInvalid);
+        }
+        write_atomically(&self.integrity_path(id), raw.as_bytes())
+    }
+
     fn observed_unverified_generation(&self) -> Result<u64, SnapshotError> {
         let mut maximum = 0;
         for entry in fs::read_dir(self.configs_dir()).map_err(SnapshotError::Io)? {
diff --git a/crates/fluxheim-snapshot/src/lib.rs b/crates/fluxheim-snapshot/src/lib.rs
@@ -21,6 +21,8 @@ mod store_support;
 mod operations_tests;
 #[cfg(test)]
 mod snapshot_hardening_tests;
+#[cfg(test)]
+mod snapshot_upgrade_tests;
 
 pub use integrity::SnapshotCryptoProvider;
 pub use metadata::{MAX_SNAPSHOT_MESSAGE_BYTES, SnapshotMetadata};
diff --git a/crates/fluxheim-snapshot/src/snapshot_upgrade_tests.rs b/crates/fluxheim-snapshot/src/snapshot_upgrade_tests.rs
@@ -0,0 +1,157 @@
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use fluxheim_common::test_support::{safe_child_path, unique_temp_path};
+use fluxheim_config::Config;
+
+use crate::{SnapshotCryptoProvider, SnapshotStore};
+
+#[derive(Debug)]
+struct TestCryptoProvider;
+
+impl SnapshotCryptoProvider for TestCryptoProvider {
+    fn label(&self) -> &'static str {
+        "snapshot-upgrade-test"
+    }
+
+    fn compliance_capable(&self) -> bool {
+        false
+    }
+
+    fn sha256(&self, chunks: &[&[u8]]) -> Result<[u8; 32], String> {
+        let mut context = ring::digest::Context::new(&ring::digest::SHA256);
+        for chunk in chunks {
+            context.update(chunk);
+        }
+        let mut output = [0_u8; 32];
+        output.copy_from_slice(context.finish().as_ref());
+        Ok(output)
+    }
+
+    fn hmac_sha256(&self, key: &[u8], chunks: &[&[u8]]) -> Result<[u8; 32], String> {
+        let key = ring::hmac::Key::new(ring::hmac::HMAC_SHA256, key);
+        let mut context = ring::hmac::Context::with_key(&key);
+        for chunk in chunks {
+            context.update(chunk);
+        }
+        let mut output = [0_u8; 32];
+        output.copy_from_slice(context.sign().as_ref());
+        Ok(output)
+    }
+}
+
+#[test]
+fn pre_generation_authenticated_store_bootstraps_and_migrates() {
+    let dir = TestDir::new("snapshot-pre-generation-bootstrap");
+    let store = authenticated_store(&dir);
+    let first = store
+        .snapshot_config(&Config::default(), Some("first"))
+        .unwrap();
+    let second = store
+        .snapshot_config(&Config::default(), Some("second"))
+        .unwrap();
+    for id in [&first.id, &second.id] {
+        rewrite_manifest_as_v1(&store, id);
+    }
+    std::fs::remove_file(store.root().join("generation.toml")).unwrap();
+
+    assert_eq!(store.current_snapshot().unwrap().unwrap().id, second.id);
+    assert!(store.doctor().unwrap().healthy);
+    assert!(!manifest_raw(&store, &first.id).contains("generation_hmac_sha256"));
+
+    let third = store
+        .snapshot_config(&Config::default(), Some("third"))
+        .unwrap();
+
+    assert_eq!(third.metadata.generation, 3);
+    assert!(store.root().join("generation.toml").is_file());
+    assert!(store.doctor().unwrap().healthy);
+    for id in [&first.id, &second.id, &third.id] {
+        assert!(manifest_raw(&store, id).contains("generation_hmac_sha256"));
+        assert_eq!(
+            store.verify(id).unwrap(),
+            crate::SnapshotIntegrityStatus::Authenticated
+        );
+    }
+}
+
+#[test]
+fn authenticated_counter_allows_interrupted_legacy_migration_to_resume() {
+    let dir = TestDir::new("snapshot-legacy-migration-resume");
+    let store = authenticated_store(&dir);
+    let first = store
+        .snapshot_config(&Config::default(), Some("first"))
+        .unwrap();
+    let second = store
+        .snapshot_config(&Config::default(), Some("second"))
+        .unwrap();
+    rewrite_manifest_as_v1(&store, &first.id);
+
+    let third = store
+        .snapshot_config(&Config::default(), Some("third"))
+        .unwrap();
+
+    assert_eq!(third.metadata.generation, 3);
+    assert!(store.doctor().unwrap().healthy);
+    for id in [&first.id, &second.id, &third.id] {
+        assert!(manifest_raw(&store, id).contains("generation_hmac_sha256"));
+    }
+}
+
+fn rewrite_manifest_as_v1(store: &SnapshotStore, id: &str) {
+    let path = integrity_path(store, id);
+    let mut manifest: toml::Table =
+        toml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+    manifest.remove("generation");
+    manifest.remove("generation_hmac_sha256");
+    std::fs::write(path, toml::to_string_pretty(&manifest).unwrap()).unwrap();
+}
+
+fn manifest_raw(store: &SnapshotStore, id: &str) -> String {
+    std::fs::read_to_string(integrity_path(store, id)).unwrap()
+}
+
+fn integrity_path(store: &SnapshotStore, id: &str) -> PathBuf {
+    store
+        .root()
+        .join("configs")
+        .join(format!("{id}.integrity.toml"))
+}
+
+fn authenticated_store(dir: &TestDir) -> SnapshotStore {
+    let key = dir.child("snapshot.key");
+    std::fs::write(&key, [17_u8; 32]).unwrap();
+    set_private_file(&key);
+    SnapshotStore::with_integrity_key_file(dir.child("store"), &key, Arc::new(TestCryptoProvider))
+        .unwrap()
+}
+
+fn set_private_file(path: &Path) {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt as _;
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).unwrap();
+    }
+    #[cfg(not(unix))]
+    let _ = path;
+}
+
+struct TestDir(PathBuf);
+
+impl TestDir {
+    fn new(name: &str) -> Self {
+        let path = unique_temp_path(name);
+        std::fs::create_dir(&path).unwrap();
+        Self(path)
+    }
+
+    fn child(&self, name: &str) -> PathBuf {
+        safe_child_path(&self.0, name)
+    }
+}
+
+impl Drop for TestDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
diff --git a/docs/config-snapshots.md b/docs/config-snapshots.md
