feat(kms): add backup manifest and responsibility contract types (#5483)

Contract-only module for KMS backup/restore (no handler or backend wiring): versioned manifest schema with completeness marker and sealed digest, the (backend, at-rest protection) responsibility matrix, typed fail-closed errors, and the zero-write restore dry-run report. Fields whose shape depends on in-flight contracts are reserved and reject data in format version 1.
2026-08-13 08:36:54 +00:00 · 2026-07-31 01:49:21 +08:00
parent 7051a5ce41
commit b457c6abcc
8 changed files with 1890 additions and 6 deletions
@@ -0,0 +1,233 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Backup responsibility matrix: what a RustFS backup bundle owns per backend.
+//!
+//! The matrix is two-dimensional on purpose: responsibility is a function of
+//! the backend *and* its at-rest protection state, not of the backend alone.
+//! This keeps the schema stable when a backend changes protection direction —
+//! switching Vault KV2 between storage-only and Transit-wrapped operation
+//! selects a different existing row instead of changing the contract.
+//!
+//! These enums are backup-domain contract types. Once the backlog#1571
+//! capability-discovery contract lands, the discovery surface is expected to
+//! converge on (or map onto) the states defined here.
+
+use serde::{Deserialize, Serialize};
+
+/// Backend discriminant recorded in a backup manifest.
+///
+/// Wire names are aligned with [`crate::config::BackendConfig`] and
+/// [`crate::config::KmsBackend`] (including the legacy `Vault` alias) so that
+/// a manifest and a persisted KMS configuration never disagree about how the
+/// same backend is spelled.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum BackupBackendKind {
+    /// Local file-based backend.
+    Local,
+    /// Vault KV v2 storage backend.
+    #[serde(rename = "VaultKV2", alias = "Vault")]
+    VaultKv2,
+    /// Vault Transit backend.
+    VaultTransit,
+    /// Static single-key backend.
+    Static,
+}
+
+/// At-rest protection state of master key material, as observed at snapshot
+/// time.
+///
+/// The first three states mirror the Local backend's on-disk protection
+/// marker (`StoredKeyProtection` in `backends/local.rs`, kebab-case wire
+/// names). The remaining states describe the non-local backends.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum AtRestProtection {
+    /// Local key files AEAD-encrypted under the Argon2id-derived master key.
+    EncryptedMasterKey,
+    /// Local development-only plaintext key files. Such files must never
+    /// enter a bundle as-is; bundle artifacts are always re-wrapped under the
+    /// backup KEK.
+    PlaintextDevOnly,
+    /// Pre-beta.9 local key files without a protection marker; the effective
+    /// mode is resolved at read time. Treated like [`Self::PlaintextDevOnly`]
+    /// for bundling purposes: re-wrap is mandatory.
+    LegacyUnspecified,
+    /// Vault KV2 as currently shipped: material confidentiality relies on
+    /// Vault ACLs, KV2 at-rest encryption, and TLS only (the backend reports
+    /// `at_rest_protection = "vault-kv2-acl"`); RustFS applies no
+    /// cryptographic wrapping of its own.
+    StorageOnly,
+    /// Vault KV2 with material wrapped by Vault Transit before storage. Not
+    /// produced by any current backend; the row exists so a future direction
+    /// change selects a state instead of changing the schema.
+    TransitWrapped,
+    /// Vault Transit: the cryptographic root lives in Vault and is not
+    /// exportable. RustFS can only ever own metadata and references.
+    ExternalNonExportable,
+    /// Static backend: the secret is delivered externally at startup and
+    /// RustFS persists no key material at all.
+    ExternalSecretDelivery,
+}
+
+/// What a RustFS backup bundle is responsible for, per (backend, protection)
+/// combination.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum BackupResponsibility {
+    /// The bundle carries the complete recoverable state: encrypted key
+    /// material for every version, salt, metadata, and configuration.
+    ///
+    /// Restore precondition for the Local backend: the operator re-supplies
+    /// the master key out of band. The master key itself is outside the
+    /// backup domain; the manifest stores at most an opaque verifier.
+    FullMaterial,
+    /// The bundle carries only non-sensitive references and verification
+    /// information. The source of truth is external secret delivery and the
+    /// operator re-provides the secret during restore. Embedding the secret
+    /// itself in a bundle is forbidden.
+    ReferenceOnly,
+    /// The bundle carries RustFS-side metadata, configuration references and
+    /// verification data, while the cryptographic root is protected by the
+    /// external system's native snapshot/disaster-recovery flow (Vault/HSM).
+    /// Restore must re-establish the external trust root first.
+    MetadataPlusExternalRoot,
+}
+
+impl BackupResponsibility {
+    /// Resolve the responsibility matrix for one (backend, protection) cell.
+    ///
+    /// Returns `None` for combinations that no supported deployment can
+    /// produce; manifests declaring such a combination are rejected as
+    /// corrupted. This function is total and the unit tests anchor every
+    /// cell, so any change to the matrix is a deliberate contract change.
+    pub fn for_backend(backend: BackupBackendKind, protection: AtRestProtection) -> Option<Self> {
+        use AtRestProtection::*;
+        use BackupBackendKind::*;
+
+        match (backend, protection) {
+            (Local, EncryptedMasterKey | PlaintextDevOnly | LegacyUnspecified) => Some(Self::FullMaterial),
+            (Local, _) => None,
+            // Storage-only KV2 offers no external cryptographic root, so the
+            // bundle must own the material (re-wrapped under the backup KEK).
+            (VaultKv2, StorageOnly) => Some(Self::FullMaterial),
+            (VaultKv2, TransitWrapped) => Some(Self::MetadataPlusExternalRoot),
+            (VaultKv2, _) => None,
+            (VaultTransit, ExternalNonExportable) => Some(Self::MetadataPlusExternalRoot),
+            (VaultTransit, _) => None,
+            (Static, ExternalSecretDelivery) => Some(Self::ReferenceOnly),
+            (Static, _) => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::KmsBackend;
+
+    fn json<T: Serialize>(value: &T) -> String {
+        serde_json::to_string(value).expect("serialization should succeed")
+    }
+
+    #[test]
+    fn backend_kind_wire_names_match_kms_backend() {
+        let pairs = [
+            (BackupBackendKind::Local, KmsBackend::Local),
+            (BackupBackendKind::VaultKv2, KmsBackend::VaultKv2),
+            (BackupBackendKind::VaultTransit, KmsBackend::VaultTransit),
+            (BackupBackendKind::Static, KmsBackend::Static),
+        ];
+        for (backup_kind, config_kind) in pairs {
+            assert_eq!(json(&backup_kind), json(&config_kind), "wire name drifted for {backup_kind:?}");
+        }
+    }
+
+    #[test]
+    fn backend_kind_accepts_legacy_vault_alias() {
+        let decoded: BackupBackendKind = serde_json::from_str("\"Vault\"").expect("legacy alias should decode");
+        assert_eq!(decoded, BackupBackendKind::VaultKv2);
+    }
+
+    #[test]
+    fn responsibility_matrix_is_anchored_cell_by_cell() {
+        use AtRestProtection::*;
+        use BackupBackendKind::*;
+        use BackupResponsibility::*;
+
+        // Every (backend, protection) cell, exhaustively. Changing any row is
+        // a contract change and must be made here consciously.
+        let matrix = [
+            (Local, EncryptedMasterKey, Some(FullMaterial)),
+            (Local, PlaintextDevOnly, Some(FullMaterial)),
+            (Local, LegacyUnspecified, Some(FullMaterial)),
+            (Local, StorageOnly, None),
+            (Local, TransitWrapped, None),
+            (Local, ExternalNonExportable, None),
+            (Local, ExternalSecretDelivery, None),
+            (VaultKv2, EncryptedMasterKey, None),
+            (VaultKv2, PlaintextDevOnly, None),
+            (VaultKv2, LegacyUnspecified, None),
+            (VaultKv2, StorageOnly, Some(FullMaterial)),
+            (VaultKv2, TransitWrapped, Some(MetadataPlusExternalRoot)),
+            (VaultKv2, ExternalNonExportable, None),
+            (VaultKv2, ExternalSecretDelivery, None),
+            (VaultTransit, EncryptedMasterKey, None),
+            (VaultTransit, PlaintextDevOnly, None),
+            (VaultTransit, LegacyUnspecified, None),
+            (VaultTransit, StorageOnly, None),
+            (VaultTransit, TransitWrapped, None),
+            (VaultTransit, ExternalNonExportable, Some(MetadataPlusExternalRoot)),
+            (VaultTransit, ExternalSecretDelivery, None),
+            (Static, EncryptedMasterKey, None),
+            (Static, PlaintextDevOnly, None),
+            (Static, LegacyUnspecified, None),
+            (Static, StorageOnly, None),
+            (Static, TransitWrapped, None),
+            (Static, ExternalNonExportable, None),
+            (Static, ExternalSecretDelivery, Some(ReferenceOnly)),
+        ];
+        assert_eq!(matrix.len(), 28, "matrix must stay exhaustive: 4 backends x 7 protection states");
+        for (backend, protection, expected) in matrix {
+            assert_eq!(
+                BackupResponsibility::for_backend(backend, protection),
+                expected,
+                "matrix cell drifted for ({backend:?}, {protection:?})"
+            );
+        }
+    }
+
+    #[test]
+    fn local_protection_wire_names_match_stored_key_protection() {
+        use crate::backends::local::StoredKeyProtection;
+
+        // The manifest must record exactly the marker values the Local
+        // backend writes to disk, or a restore could misread protection.
+        let pairs = [
+            (AtRestProtection::EncryptedMasterKey, StoredKeyProtection::EncryptedMasterKey),
+            (AtRestProtection::PlaintextDevOnly, StoredKeyProtection::PlaintextDevOnly),
+            (AtRestProtection::LegacyUnspecified, StoredKeyProtection::LegacyUnspecified),
+        ];
+        for (backup_state, stored_state) in pairs {
+            assert_eq!(json(&backup_state), json(&stored_state), "wire name drifted for {backup_state:?}");
+        }
+    }
+
+    #[test]
+    fn responsibility_wire_names_are_frozen() {
+        assert_eq!(json(&BackupResponsibility::FullMaterial), "\"full-material\"");
+        assert_eq!(json(&BackupResponsibility::ReferenceOnly), "\"reference-only\"");
+        assert_eq!(json(&BackupResponsibility::MetadataPlusExternalRoot), "\"metadata-plus-external-root\"");
+    }
+}