feat: Enables generating created assertions and getting the created state (#1432)

* chore: fix build issues in main

* feat: Add support for created vs gathered assertions
Replace AssertionDefinition with ManifestAssertion.

* chore: fix example for passing ingredientIds

* chore: Actions Base should use struct LABEL

* feat: Add assertion label parsing code for base, version and instance

* chore: revert to AssertionDefinition
Adds created to ManifestAssertion
Adds AssertionKind kind() and content_type() to AssertionBase with defaults.
Adds AssertionBinary Trait (not used yet)

* fix: make tests repairs

* chore: cleanup

* feat: Settings for intent and created
add_action will now insert created and opened at the top of the actions (fixes a duplicate action bug)
Updates v2api example to add an opened action

* feat: make labels::parse_label public and document it.

* feat: make labels::parse_label() public and documented.

* feat: claim.add_assertion automation.
the add_assertion method will now determine when salting and created/vs gathered are needed.
A list of created assertion names can be provided in settings, and you can still call add_created_assertion when needed.
All assertions are considered gathered by default except for hard bindings.
All redactable assertions are salted.
Adding a custom salt is now private to Claim but can be made public if needed (it was never used)
add_assertion_with_salt and add_gathered_assertion_with salt have been removed.

* chore: add unit tests

* chore: review feedback
renamed settings.builder.created_assertions to created_assertion_labels
salt all assertions
removes unused AssertionBinary code.

* chore: build repairs

* chore: review feedback
changed v2api.rs to api.rs
removed unused experimental assertion static apis

* chore: remove println

Author: gpeacock

sdk/Cargo.toml

@@ -72,7 +72,7 @@ required-features = ["file_io"]
 name = "v2show"
 
 [[example]]
-name = "v2api"
+name = "api"
 
 [[example]]
 name = "fragmented_bmff"

sdk/examples/v2api.rs renamed to sdk/examples/api.rs

@@ -67,7 +67,7 @@ fn manifest_def(title: &str, format: &str) -> String {
     }).to_string()
 }
 
-/// This example demonstrates how to use the new v2 API to create a manifest store
+/// This example demonstrates how to use the API to create a manifest store
 /// It uses only streaming apis, showing how to avoid file i/o
 /// This example uses the `ed25519` signing algorithm
 fn main() -> Result<()> {
@@ -94,13 +94,21 @@ fn main() -> Result<()> {
     builder.add_ingredient_from_stream(
         json!({
             "title": parent_name,
-            "relationship": "parentOf"
+            "relationship": "parentOf",
+            "label": "parent_label",  // use a label to tie this ingredient to an action
         })
         .to_string(),
         format,
         &mut source,
     )?;
 
+    builder.add_action(json!({
+        "action": "c2pa.opened",
+        "parameters": {
+            "ingredientIds": ["parent_label"], // the ingredient title to reference the ingredient
+        }
+    }))?;
+
     let thumb_uri = builder
         .definition
         .thumbnail

sdk/examples/client/client.rs

@@ -116,7 +116,7 @@ pub fn main() -> Result<()> {
     // create an action assertion stating that we imported this file
     let actions = Actions::new().add_action(
         Action::new(c2pa_action::OPENED)
-            .set_parameter("ingredients", [parent.instance_id().to_owned()])?,
+            .set_parameter("ingredientIds", [parent.instance_id().to_owned()])?,
     );
 
     // build a creative work assertion

sdk/src/assertion.rs

@@ -103,21 +103,22 @@ pub trait AssertionBase
 where
     Self: Sized,
 {
+    /// The label for this assertion (reverse domain format)
     const LABEL: &'static str = "unknown";
 
+    /// The version for this assertion (if any) Defaults to None/1
     const VERSION: Option<usize> = None;
 
     /// Returns a label for this assertion.
     fn label(&self) -> &str {
         Self::LABEL
     }
 
-    /// Returns a version for this assertion.
     fn version(&self) -> Option<usize> {
         Self::VERSION
     }
 
-    /// Returns an Assertion upon success or Error otherwise.
+    /// Convert this instance to an Assertion
     fn to_assertion(&self) -> Result<Assertion>;
 
     /// Returns Self or AssertionDecode Result from an assertion
@@ -130,7 +131,7 @@ pub trait AssertionCbor: Serialize + DeserializeOwned + AssertionBase {
         let data = AssertionData::Cbor(
             serde_cbor::to_vec(self).map_err(|err| Error::AssertionEncoding(err.to_string()))?,
         );
-        Ok(Assertion::new(self.label(), self.version(), data))
+        Ok(Assertion::new(self.label(), self.version(), data).set_content_type("application/cbor"))
     }
 
     fn from_cbor_assertion(assertion: &Assertion) -> Result<Self> {
@@ -263,6 +264,10 @@ impl Assertion {
         self.version.unwrap_or(1)
     }
 
+    pub fn version(&self) -> usize {
+        self.version.unwrap_or(1)
+    }
+
     // pub fn check_version(&self, max_version: usize) -> AssertionDecodeResult<()> {
     //     match self.version {
     //         Some(version) if version > max_version => Err(AssertionDecodeError {
@@ -284,6 +289,7 @@ impl Assertion {
     }
 
     /// return mimetype for the the data enclosed in the Assertion
+    // Todo: deprecate this in favor of content_type()
     pub(crate) fn mime_type(&self) -> String {
         self.content_type.clone()
     }
@@ -383,7 +389,7 @@ impl Assertion {
 
         Self {
             label,
-            version,
+            version: if version == 1 { None } else { Some(version) },
             data,
             content_type: content_type.to_owned(),
         }
@@ -442,7 +448,7 @@ impl Assertion {
         let json = String::from_utf8(binary_data.to_vec()).map_err(|_| AssertionDecodeError {
             label: label.to_string(),
             version: None, // TODO: Can we get this info?
-            content_type: "json".to_string(),
+            content_type: "application/json".to_string(),
             source: AssertionDecodeErrorCause::BinaryDataNotUtf8,
         })?;
 
@@ -458,18 +464,17 @@ impl Assertion {
         &self,
         desired_version: usize,
     ) -> AssertionDecodeResult<()> {
-        if let Some(base_version) = labels::version(&self.label) {
-            if desired_version > base_version {
-                return Err(AssertionDecodeError {
-                    label: self.label.clone(),
-                    version: self.version,
-                    content_type: self.content_type.clone(),
-                    source: AssertionDecodeErrorCause::AssertionTooNew {
-                        max: desired_version,
-                        found: base_version,
-                    },
-                });
-            }
+        let base_version = labels::version(&self.label);
+        if desired_version > base_version {
+            return Err(AssertionDecodeError {
+                label: self.label.clone(),
+                version: self.version,
+                content_type: self.content_type.clone(),
+                source: AssertionDecodeErrorCause::AssertionTooNew {
+                    max: desired_version,
+                    found: base_version,
+                },
+            });
         }
 
         Ok(())

sdk/src/assertions/actions.rs

@@ -833,8 +833,15 @@ impl Actions {
     }
 
     /// Adds an [`Action`] to this assertion's list of actions.
+    /// OPENED and CREATED actions are inserted at the beginning of the list.
+    /// as required by the c2pa specification.
+    /// Note, this does not check for duplicates since it does not return errors.
     pub fn add_action(mut self, action: Action) -> Self {
-        self.actions.push(action);
+        if action.action() == c2pa_action::OPENED || action.action() == c2pa_action::CREATED {
+            self.actions.insert(0, action);
+        } else {
+            self.actions.push(action);
+        }
         self
     }
 
@@ -862,7 +869,7 @@ impl Actions {
 impl AssertionCbor for Actions {}
 
 impl AssertionBase for Actions {
-    const LABEL: &'static str = labels::ACTIONS;
+    const LABEL: &'static str = Self::LABEL;
     const VERSION: Option<usize> = Some(ASSERTION_CREATION_VERSION);
 
     fn version(&self) -> Option<usize> {

sdk/src/assertions/labels.rs

@@ -219,6 +219,13 @@ pub const METADATA: &str = "c2pa.metadata";
 /// [CAWG metadata assertion]: https://cawg.io/metadata/
 pub const CAWG_METADATA: &str = "cawg.metadata";
 
+/// Array of all hash labels because they have special treatment
+pub const HASH_LABELS: [&str; 4] = [DATA_HASH, BOX_HASH, BMFF_HASH, COLLECTION_HASH];
+
+/// Array of all non-redactable labels
+pub const NON_REDACTABLE_LABELS: [&str; 5] =
+    [ACTIONS, DATA_HASH, BOX_HASH, BMFF_HASH, COLLECTION_HASH];
+
 /// Must have a label that ends in '.metadata' and is preceded by an entity-specific namespace.
 /// For example, a 'com.litware.metadata' assertion would be valid.
 pub static METADATA_LABEL_REGEX: LazyLock<Regex> = LazyLock::new(|| {
@@ -229,14 +236,79 @@ pub static METADATA_LABEL_REGEX: LazyLock<Regex> = LazyLock::new(|| {
     }
 });
 
-/// Return the version suffix from an assertion label if it exists.
+/// Parse a label into its components
+///
+/// This function takes a label string and parses it into its base label,
+/// version number, and instance number. The base label is the part of the
+/// label without any version or instance suffixes. The version number is
+/// extracted from a suffix of the form `.v{number}`, defaulting to 1 if
+/// not present. The instance number is extracted from a suffix of the form
+/// `__{number}`, defaulting to 0 if not present.
+///
+/// ABNF grammar for labels:
+/// ```abnf
+/// namespaced-label = qualified-namespace label [version] [instance]
+/// qualified-namespace = "c2pa" / entity
+/// entity = entity-component *( "." entity-component )
+/// entity-component = 1( DIGIT / ALPHA ) *( DIGIT / ALPHA / "-" / "_" )
+/// label = 1*( "." label-component )
+/// label-component = 1( DIGIT / ALPHA ) *( DIGIT / ALPHA / "-" / "_" )
+/// version = ".v" 1*DIGIT
+/// instance = "__" 1*DIGIT
+/// ```
+pub fn parse_label(label: &str) -> (&str, usize, usize) {
+    // First, extract instance if present
+    let (without_instance, instance) = if let Some(pos) = label.rfind("__") {
+        let instance_str = &label[pos + 2..];
+        let instance = instance_str.parse::<usize>().unwrap_or(0);
+        (&label[..pos], instance)
+    } else {
+        (label, 0)
+    };
+
+    // Then, extract version if present
+    #[allow(clippy::unwrap_used)]
+    static VERSION_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^v\d+$").unwrap());
+    let components: Vec<&str> = without_instance.split('.').collect();
+    if let Some(last) = components.last() {
+        if VERSION_RE.is_match(last) {
+            if let Ok(version) = last[1..].parse::<usize>() {
+                let base_end = without_instance.len() - last.len() - 1;
+                return (&without_instance[..base_end], version, instance);
+            }
+        }
+    }
+
+    (without_instance, 1, instance)
+}
+
+/// Extract the base label without version or instance suffixes
+///
+/// This function removes both the version suffix (`.v{number}`) and
+/// instance suffix (`__{number}`) from a label, returning just the base.
+///
+/// # Examples
+/// ```
+/// use c2pa::assertions::labels;
+///
+/// assert_eq!(labels::base("c2pa.ingredient"), "c2pa.ingredient");
+/// assert_eq!(labels::base("c2pa.ingredient.v3"), "c2pa.ingredient");
+/// assert_eq!(labels::base("c2pa.ingredient__2"), "c2pa.ingredient");
+/// assert_eq!(labels::base("c2pa.ingredient.v3__2"), "c2pa.ingredient");
+/// assert_eq!(labels::base("c2pa.actions__1"), "c2pa.actions");
+/// ```
+pub fn base(label: &str) -> &str {
+    parse_label(label).0
+}
+
+/// Extract version from a label
 ///
 /// When an assertion's schema is changed in a backwards-compatible manner,
 /// the label would consist of an incremented version number, for example
 /// moving from `c2pa.ingredient` to `c2pa.ingredient.v2`.
 ///
-/// If such a suffix exists (`.v(integer)`), return that; otherwise,
-/// return `None`.
+/// Returns the version number, or 1 if no version suffix is present
+/// (since version 1 is the default and never explicitly included).
 ///
 /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_versioning>.
 ///
@@ -245,39 +317,38 @@ pub static METADATA_LABEL_REGEX: LazyLock<Regex> = LazyLock::new(|| {
 /// ```
 /// use c2pa::assertions::labels;
 ///
-/// assert_eq!(labels::version("c2pa.ingredient"), None);
-/// assert_eq!(labels::version("c2pa.ingredient.v2"), Some(2));
-/// assert_eq!(labels::version("c2pa.ingredient.V2"), None);
-/// assert_eq!(labels::version("c2pa.ingredient.x2"), None);
-/// assert_eq!(labels::version("c2pa.ingredient.v-2"), None);
+/// assert_eq!(labels::version("c2pa.ingredient"), 1);
+/// assert_eq!(labels::version("c2pa.ingredient.v2"), 2);
+/// assert_eq!(labels::version("c2pa.ingredient.v3__2"), 3);
+/// assert_eq!(labels::version("c2pa.ingredient.V2"), 1);
+/// assert_eq!(labels::version("c2pa.ingredient.x2"), 1);
+/// assert_eq!(labels::version("c2pa.ingredient.v-2"), 1);
 /// ```
-pub fn version(label: &str) -> Option<usize> {
-    let components: Vec<&str> = label.split('.').collect();
-    if let Some(last) = components.last() {
-        if last.len() > 1 {
-            let (ver, ver_inst_str) = last.split_at(1);
-            if ver == "v" {
-                if let Ok(ver) = ver_inst_str.parse::<usize>() {
-                    return Some(ver);
-                }
-            }
-        }
-    }
-
-    None
+pub fn version(label: &str) -> usize {
+    parse_label(label).1
 }
 
-/// Set the version of a label.
-/// If the version is 1, the original label is returned.
-/// Otherwise, the label is suffixed with the version number.
-/// This expects the label to not already have a version suffix.
-pub fn set_version(base_label: &str, version: usize) -> String {
-    if version == 1 {
-        // c2pa does not include v1 labels
-        base_label.to_string()
-    } else {
-        format!("{base_label}.v{version}")
-    }
+/// Extract the instance number from a label (return 0 if none)
+///
+/// This function looks for a double underscore followed by a number
+/// in the label and returns that number as the instance. If no such
+/// pattern is found, it returns zero.
+/// "__0" is default and never part of a label.
+/// Invalid instances are also treated as zero.
+///
+/// # Examples
+/// ```
+/// use c2pa::assertions::labels;
+///
+/// assert_eq!(labels::instance("c2pa.ingredient"), 0);
+/// assert_eq!(labels::instance("c2pa.actions__1"), 1);
+/// assert_eq!(labels::instance("c2pa.ingredient.v3__2"), 2);
+/// assert_eq!(labels::instance("c2pa.ingredient__2"), 2);
+/// assert_eq!(labels::instance("c2pa.ingredient__x"), 0);
+/// assert_eq!(labels::instance("c2pa.ingredient__"), 0);
+/// ```
+pub fn instance(label: &str) -> usize {
+    parse_label(label).2
 }
 
 /// Given a thumbnail label prefix such as `CLAIM_THUMBNAIL` and a file