feat: Refine validation state logic (#1541)

* feat: add well-formed validation state

* docs: clarify validation state and manifest stores

* fix: rename invalid to malformed

* fix: add more checks to validation state

* fix: add unknown validation state

* test: check for ==Trusted instead of !=Malformed

* test: mark XCA.json as Malformed instead of Invalid

* feat: make Valid state more strict and remove WellFormed state

* test: reset settings before running test_builder_base_path

* fix: if there is no active manifest, assume it wasn't validated

* fix: remove unknown validation state for now

* docs: clarify invalid state may occur if validation is disabled

Author: ok-nick

sdk/src/builder.rs

@@ -2531,7 +2531,7 @@ mod tests {
         let manifest_store = Reader::from_file(&dest).expect("from_bytes");
 
         println!("{manifest_store}");
-        assert_ne!(manifest_store.validation_state(), ValidationState::Invalid);
+        assert_eq!(manifest_store.validation_state(), ValidationState::Trusted);
         assert_eq!(manifest_store.validation_status(), None);
         assert_eq!(
             manifest_store.active_manifest().unwrap().title().unwrap(),
@@ -2589,7 +2589,7 @@ mod tests {
             //println!("{}", manifest_store);
             if format != "c2pa" {
                 // c2pa files will not validate since they have no associated asset
-                assert_ne!(manifest_store.validation_state(), ValidationState::Invalid);
+                assert_eq!(manifest_store.validation_state(), ValidationState::Trusted);
             }
             assert_eq!(
                 manifest_store.active_manifest().unwrap().title().unwrap(),
@@ -2889,6 +2889,9 @@ mod tests {
     #[cfg(feature = "file_io")]
     #[test]
     fn test_builder_base_path() {
+        #[cfg(target_os = "wasi")]
+        Settings::reset().unwrap();
+
         let mut source = Cursor::new(TEST_IMAGE_CLEAN);
         let mut dest = Cursor::new(Vec::new());
 
@@ -2917,7 +2920,7 @@ mod tests {
         let reader = Reader::from_stream("image/jpeg", &mut dest).expect("from_bytes");
 
         //println!("{}", reader);
-        assert_ne!(reader.validation_state(), ValidationState::Invalid);
+        assert_eq!(reader.validation_state(), ValidationState::Trusted);
         assert_eq!(reader.validation_status(), None);
         assert_eq!(
             reader

sdk/src/validation_results.rs

@@ -11,6 +11,8 @@
 // specific language governing permissions and limitations under
 // each license.
 
+use std::collections::HashSet;
+
 #[cfg(feature = "json_schema")]
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
@@ -21,30 +23,48 @@ use crate::{
     jumbf::labels::manifest_label_from_uri,
     status_tracker::{LogKind, StatusTracker},
     store::Store,
-    validation_status::{log_kind, ValidationStatus},
+    validation_status::{self, log_kind, ValidationStatus},
 };
 
+/// Represents the levels of assurance a manifest store achives when evaluated against the C2PA
+/// specifications structural, cryptographic, and trust requirements.
+///
+/// See [§14.3. Validation states].
+///
+/// [§14.3. Validation states]: https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_validation_states
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[cfg_attr(feature = "json_schema", derive(JsonSchema))]
-/// Indicates if the manifest store is valid and trusted.
-///
-/// The Trusted state implies the manifest store is valid and the active signature is trusted.
 pub enum ValidationState {
-    /// Errors were found in the manifest store.
+    /// The manifest store fails to meet [ValidationState::WellFormed] requirements, meaning it cannot
+    /// even be parsed or its basic structure is non-compliant.
+    ///
+    /// This case may also occur if validation is disabled in the SDK.
     Invalid,
-    /// No errors were found in validation, but the active signature is not trusted.
+    /// The manifest store is well-formed and the cryptographic integrity checks succeed.
+    ///
+    /// See [§14.3.5. Valid Manifest].
+    ///
+    /// [§14.3.5. Valid Manifest]: https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_valid_manifest
     Valid,
-    /// The manifest store is valid and the active signature is trusted.
+    /// The manifest store is valid and signed by a certificate that chains up to a trusted root or known
+    /// authority in the trust list.
+    ///
+    /// See [§14.3.6. Trusted Manifest].
+    ///
+    /// [§14.3.6. Trusted Manifest]: https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_trusted_manifest
     Trusted,
 }
 
+/// Contains a set of success, informational, and failure validation status codes.
 #[derive(Clone, Serialize, Default, Deserialize, Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "json_schema", derive(JsonSchema))]
-/// Contains a set of success, informational, and failure validation status codes.
 pub struct StatusCodes {
-    pub success: Vec<ValidationStatus>, // an array of validation success codes. May be empty.
-    pub informational: Vec<ValidationStatus>, // an array of validation informational codes. May be empty.
-    pub failure: Vec<ValidationStatus>,       // an array of validation failure codes. May be empty.
+    /// An array of validation success codes. May be empty.
+    pub success: Vec<ValidationStatus>,
+    /// An array of validation informational codes. May be empty.
+    pub informational: Vec<ValidationStatus>,
+    // An array of validation failure codes. May be empty.
+    pub failure: Vec<ValidationStatus>,
 }
 
 impl StatusCodes {
@@ -85,18 +105,22 @@ impl StatusCodes {
     }
 }
 
-#[derive(Clone, Serialize, Default, Deserialize, Debug, PartialEq, Eq)]
-#[cfg_attr(feature = "json_schema", derive(JsonSchema))]
 /// A map of validation results for a manifest store.
 ///
 /// The map contains the validation results for the active manifest and any ingredient deltas.
 /// It is normal for there to be many
+#[derive(Clone, Serialize, Default, Deserialize, Debug, PartialEq, Eq)]
+#[cfg_attr(feature = "json_schema", derive(JsonSchema))]
 pub struct ValidationResults {
+    /// Validation status codes for the ingredient's active manifest. Present if ingredient is a C2PA
+    /// asset. Not present if the ingredient is not a C2PA asset.
     #[serde(rename = "activeManifest", skip_serializing_if = "Option::is_none")]
-    active_manifest: Option<StatusCodes>, // Validation status codes for the ingredient's active manifest. Present if ingredient is a C2PA asset. Not present if the ingredient is not a C2PA asset.
+    active_manifest: Option<StatusCodes>,
 
+    /// List of any changes/deltas between the current and previous validation results for each ingredient's
+    /// manifest. Present if the the ingredient is a C2PA asset.
     #[serde(rename = "ingredientDeltas", skip_serializing_if = "Option::is_none")]
-    ingredient_deltas: Option<Vec<IngredientDeltaValidationResult>>, // List of any changes/deltas between the current and previous validation results for each ingredient's manifest. Present if the the ingredient is a C2PA asset.
+    ingredient_deltas: Option<Vec<IngredientDeltaValidationResult>>,
 }
 
 impl ValidationResults {
@@ -180,29 +204,43 @@ impl ValidationResults {
     }
 
     /// Returns the [ValidationState] of the manifest store based on the validation results.
+    ///
+    /// See [§14.3. Validation states].
+    ///
+    /// [§14.3. Validation states]: https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_validation_states
     pub fn validation_state(&self) -> ValidationState {
-        let mut is_trusted = true; // Assume the state is trusted until proven otherwise
         if let Some(active_manifest) = self.active_manifest.as_ref() {
-            if !active_manifest.failure().is_empty() {
-                return ValidationState::Invalid;
-            }
-            // There must be a trusted credential in the active manifest for the state to be trusted
-            is_trusted = active_manifest.success().iter().any(|status| {
-                status.code() == crate::validation_status::SIGNING_CREDENTIAL_TRUSTED
+            let success_codes: HashSet<&str> = active_manifest
+                .success()
+                .iter()
+                .map(|status| status.code())
+                .collect();
+            let failure_codes = active_manifest.failure();
+            let ingredient_failure = self.ingredient_deltas.as_ref().is_some_and(|deltas| {
+                deltas
+                    .iter()
+                    .any(|idv| !idv.validation_deltas().failure().is_empty())
             });
-        }
-        if let Some(ingredient_deltas) = self.ingredient_deltas.as_ref() {
-            for idv in ingredient_deltas.iter() {
-                if !idv.validation_deltas().failure().is_empty() {
-                    return ValidationState::Invalid;
-                }
+
+            // https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_valid_manifest
+            let is_valid = success_codes.contains(validation_status::CLAIM_SIGNATURE_VALIDATED)
+                && success_codes.contains(validation_status::CLAIM_SIGNATURE_INSIDE_VALIDITY)
+                && failure_codes.is_empty()
+                && !ingredient_failure;
+
+            // https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_trusted_manifest
+            let is_trusted = success_codes.contains(validation_status::SIGNING_CREDENTIAL_TRUSTED)
+                && failure_codes.is_empty()
+                && is_valid;
+
+            if is_trusted {
+                return ValidationState::Trusted;
+            } else if is_valid {
+                return ValidationState::Valid;
             }
         }
-        if is_trusted {
-            ValidationState::Trusted
-        } else {
-            ValidationState::Valid
-        }
+
+        ValidationState::Invalid
     }
 
     /// Returns a list of all validation errors in [ValidationResults].

sdk/tests/known_good/XCA.json

@@ -171,4 +171,4 @@
     ]
   },
   "validation_state": "Invalid"
-}
+}

sdk/tests/test_builder.rs

@@ -219,7 +219,7 @@ fn test_builder_embedded_v1_otgp() -> Result<()> {
     dest.set_position(0);
     let reader = Reader::from_stream(format, &mut dest)?;
     // check that the v1 OTGP is embedded and we catch it correct with validation_results
-    assert_ne!(reader.validation_state(), ValidationState::Invalid);
+    assert_eq!(reader.validation_state(), ValidationState::Trusted);
     //println!("reader: {}", reader);
     assert_eq!(
         reader.active_manifest().unwrap().ingredients()[0]