feat: add settings structs to the public API

cli/tests/fixtures/trust/cawg_sign_settings.toml

@@ -1,8 +1,7 @@
 # c2pa-rs Configuration File
 
 # Version information.
-version_major = 1
-version_minor = 0
+version = 1
 
 # Trust settings for certificate validation.
 # [trust]
@@ -220,13 +219,13 @@ xPd7wFhjRZHfuWb2cs63xjAGjQ==
 """
 # String to trust configuration.
 trust_config = """
-//id-kp-emailProtection 
+//id-kp-emailProtection
 1.3.6.1.5.5.7.3.4
-//id-kp-documentSigning 
+//id-kp-documentSigning
 1.3.6.1.5.5.7.3.36
-//id-kp-timeStamping 
+//id-kp-timeStamping
 1.3.6.1.5.5.7.3.8
-//id-kp-OCSPSigning 
+//id-kp-OCSPSigning
 1.3.6.1.5.5.7.3.9
 // MS C2PA Signing
 1.3.6.1.4.1.311.76.59.1.9
@@ -418,8 +417,8 @@ name = "c2pa-rs testing"
 version = "1.0.0"
 # The operating system the claim generator is running on.
 #operating_system.name = "macOS"
-# Or if the name isn't specified, it can be inferred automatically.
-operating_system.infer = true
+# Or specify "auto" to infer the operating system automatically.
+operating_system = "auto"
 # Arbitrary fields can also be defined.
 #
 # By default, the SDK adds a field "org.cai.c2pa_rs" with the value

sdk/examples/c2pa.toml

@@ -1,8 +1,7 @@
 # c2pa-rs Configuration File
 
 # Version information.
-version_major = 1
-version_minor = 0
+version = 1
 
 # # Trust settings for certificate validation.
 # [trust]
@@ -66,9 +65,8 @@ name = "My Service"
 # A human readable string of the product's version.
 version = "1.0.0"
 # The operating system the claim generator is running on.
-operating_system.name = "macOS"
-# Or if the name isn't specified, it can be inferred automatically.
-operating_system.infer = true
+# Or specify "auto" to infer the operating system automatically.
+operating_system = "macOS"
 # Arbitrary fields can also be defined.
 #
 # By default, the SDK adds a field "org.cai.c2pa_rs" with the value

sdk/src/settings/builder.rs

@@ -31,9 +31,10 @@ use crate::{
 ///
 /// These formats are a combination of types supported in [image-rs](https://docs.rs/image/latest/image/enum.ImageFormat.html)
 /// and types defined by the [IANA registry media type](https://www.iana.org/assignments/media-types/media-types.xhtml) (as defined in the spec).
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
-pub(crate) enum ThumbnailFormat {
+pub enum ThumbnailFormat {
     /// An image in PNG format.
     Png,
     /// An image in JPEG format.
@@ -46,9 +47,10 @@ pub(crate) enum ThumbnailFormat {
     Tiff,
 }
 /// Quality of the thumbnail.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
-pub(crate) enum ThumbnailQuality {
+pub enum ThumbnailQuality {
     /// Low quality.
     Low,
     /// Medium quality.
@@ -58,23 +60,36 @@ pub(crate) enum ThumbnailQuality {
 }
 
 /// Settings for controlling automatic thumbnail generation.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ThumbnailSettings {
+pub struct ThumbnailSettings {
     /// Whether or not to automatically generate thumbnails.
+    ///
+    /// The default value is true.
+    ///
+    /// <div class="warning">
+    /// This setting is only applicable if the crate is compiled with the `add_thumbnails` feature.
+    /// </div>
     pub enabled: bool,
     /// Whether to ignore thumbnail generation errors.
     ///
     /// This may occur, for instance, if the thumbnail media type or color layout isn't
     /// supported.
+    ///
+    /// The default value is true.
     pub ignore_errors: bool,
     /// The size of the longest edge of the thumbnail.
     ///
     /// This function will resize the input to preserve aspect ratio.
+    ///
+    /// The default value is 1024.
     pub long_edge: u32,
     /// Format of the thumbnail.
     ///
     /// If this field isn't specified, the thumbnail format will correspond to the
     /// input format.
+    ///
+    /// The default value is None.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub format: Option<ThumbnailFormat>,
     /// Whether or not to prefer a smaller sized media format for the thumbnail.
@@ -85,11 +100,15 @@ pub(crate) struct ThumbnailSettings {
     ///
     /// For instance, if the source input type is a PNG, but it doesn't have an alpha channel,
     /// the image will be converted to a JPEG of smaller size.
+    ///
+    /// The default value is true.
     pub prefer_smallest_format: bool,
     /// The output quality of the thumbnail.
     ///
     /// This setting contains sensible defaults for things like quality, compression, and
     /// algorithms for various formats.
+    ///
+    /// The default value is [`ThumbnailQuality::Medium`].
     pub quality: ThumbnailQuality,
 }
 
@@ -118,55 +137,57 @@ impl SettingsValidate for ThumbnailSettings {
 }
 
 /// Settings for the auto actions (e.g. created, opened, placed).
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct AutoActionSettings {
+pub struct AutoActionSettings {
     /// Whether to enable this auto action or not.
     pub enabled: bool,
     /// The default source type for the auto action.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub source_type: Option<DigitalSourceType>,
 }
 
-/// Settings for how to specify the claim generator info's operating system.
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ClaimGeneratorInfoOSSettings {
-    /// Whether or not to infer the operating system.
-    pub infer: bool,
+#[serde(untagged, rename_all = "lowercase")]
+pub enum ClaimGeneratorInfoOperatingSystem {
+    /// Whether or not to automatically infer the operating system.
+    ///
+    /// This option will attempt to following the [LLVM "triples"] conventions. For more information,
+    /// see [`ClaimGeneratorInfoOperatingSystem::Other`].
+    ///
+    /// [LLVM "triples"]: https://clang.llvm.org/docs/CrossCompilation.html#target-triple
+    Auto,
     /// The name of the operating system.
     ///
-    /// Note this field overrides [ClaimGeneratorInfoOSSettings::infer].
-    pub name: Option<String>,
-}
-
-impl Default for ClaimGeneratorInfoOSSettings {
-    fn default() -> Self {
-        Self {
-            infer: true,
-            name: None,
-        }
-    }
+    /// It is recommended to follow the [LLVM "triples"] conventions to define the operating system,
+    /// with the format `<arch><sub>-<vendor>-<sys>-<env>`. For instance:
+    /// - `x86_64-unknown-linux-gnu`
+    /// - `x86_64-pc-windows-msvc`
+    /// - `arm64-apple-darwin`
+    ///
+    /// [LLVM "triples"]: https://clang.llvm.org/docs/CrossCompilation.html#target-triple
+    Other(String),
 }
 
 /// Settings for the claim generator info.
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ClaimGeneratorInfoSettings {
+pub struct ClaimGeneratorInfoSettings {
     /// A human readable string naming the claim_generator.
     pub name: String,
     /// A human readable string of the product's version.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub version: Option<String>,
     /// Reference to an icon.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub icon: Option<ResourceRef>,
+    pub(crate) icon: Option<ResourceRef>,
     /// Settings for the claim generator info's operating system field.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub operating_system: Option<ClaimGeneratorInfoOSSettings>,
+    pub operating_system: Option<ClaimGeneratorInfoOperatingSystem>,
     /// Any other values that are not part of the standard.
     #[serde(flatten)]
-    pub other: HashMap<String, toml::Value>,
+    pub other: HashMap<String, serde_json::Value>,
 }
 
 impl TryFrom<ClaimGeneratorInfoSettings> for ClaimGeneratorInfo {
@@ -178,11 +199,12 @@ impl TryFrom<ClaimGeneratorInfoSettings> for ClaimGeneratorInfo {
             version: value.version,
             icon: value.icon.map(UriOrResource::ResourceRef),
             operating_system: {
-                let os = value.operating_system.unwrap_or_default();
-                match os.infer {
-                    true => Some(consts::OS.to_owned()),
-                    false => os.name,
-                }
+                value.operating_system.map(|os| match os {
+                    ClaimGeneratorInfoOperatingSystem::Auto => {
+                        format!("{}-unknown-{}", consts::ARCH, consts::OS)
+                    }
+                    ClaimGeneratorInfoOperatingSystem::Other(name) => name,
+                })
             },
             other: value
                 .other
@@ -198,6 +220,7 @@ impl TryFrom<ClaimGeneratorInfoSettings> for ClaimGeneratorInfo {
 }
 
 /// Settings for an action template.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub(crate) struct ActionTemplateSettings {
     /// The label associated with this action. See ([c2pa_action][crate::assertions::actions::c2pa_action]).
@@ -221,7 +244,7 @@ pub(crate) struct ActionTemplateSettings {
     pub description: Option<String>,
     /// Additional parameters for the template
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub template_parameters: Option<HashMap<String, toml::Value>>,
+    pub template_parameters: Option<HashMap<String, serde_json::Value>>,
 }
 
 impl TryFrom<ActionTemplateSettings> for ActionTemplate {
@@ -256,7 +279,6 @@ impl TryFrom<ActionTemplateSettings> for ActionTemplate {
 }
 
 /// Settings for an action.
-#[allow(unused)]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub(crate) struct ActionSettings {
     /// The label associated with this action. See ([`c2pa_action`]).
@@ -323,33 +345,34 @@ impl TryFrom<ActionSettings> for Action {
 ///
 /// The reason this setting exists only for an [Actions][crate::assertions::Actions] assertion
 /// is because of its mandations and reusable fields.
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ActionsSettings {
+pub struct ActionsSettings {
     /// Whether or not to set the [Actions::all_actions_included][crate::assertions::Actions::all_actions_included]
     /// field.
     pub all_actions_included: bool,
     /// Templates to be added to the [Actions::templates][crate::assertions::Actions::templates] field.
+    #[doc(hidden)]
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub templates: Option<Vec<ActionTemplateSettings>>,
-    // TODO: should we define a new struct for "Action" too, like ActionTemplateSettings?
+    pub(crate) templates: Option<Vec<ActionTemplateSettings>>,
     /// Actions to be added to the [Actions::actions][crate::assertions::Actions::actions] field.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub actions: Option<Vec<ActionSettings>>,
-    /// Whether to automatically generate a c2pa.created [Action][crate::assertions::Action]
-    /// assertion or error that it doesn't already exist.
+    #[doc(hidden)]
+    // TODO: ActionSettings indirectly depends on ActionParameters which contains a serde_cbor::Value and
+    // schemars can't generate a schema for cbor values. It also doesn't feel right to change our API for
+    // the sake of json schemas.
+    #[serde(skip)]
+    pub(crate) actions: Option<Vec<ActionSettings>>,
+    /// Whether to automatically generate a c2pa.created [Action] assertion or error that it doesn't already exist.
     ///
     /// For more information about the mandatory conditions for a c2pa.created action assertion, see here:
     /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_mandatory_presence_of_at_least_one_actions_assertion>
     pub auto_created_action: AutoActionSettings,
-    /// Whether to automatically generate a c2pa.opened [Action][crate::assertions::Action]
-    /// assertion or error that it doesn't already exist.
+    /// Whether to automatically generate a c2pa.opened [Action] assertion or error that it doesn't already exist.
     ///
     /// For more information about the mandatory conditions for a c2pa.opened action assertion, see here:
     /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_mandatory_presence_of_at_least_one_actions_assertion>
     pub auto_opened_action: AutoActionSettings,
-    /// Whether to automatically generate a c2pa.placed [Action][crate::assertions::Action]
-    /// assertion or error that it doesn't already exist.
+    /// Whether to automatically generate a c2pa.placed [Action] assertion or error that it doesn't already exist.
     ///
     /// For more information about the mandatory conditions for a c2pa.placed action assertion, see:
     /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_relationship>
@@ -389,9 +412,9 @@ impl SettingsValidate for ActionsSettings {
 
 // TODO: do more validation on URL fields, cert fields, etc.
 /// Settings for the [Builder][crate::Builder].
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, Default)]
-pub(crate) struct BuilderSettings {
+pub struct BuilderSettings {
     /// Claim generator info that is automatically added to the builder.
     ///
     /// Note that this information will prepend any claim generator info
@@ -404,18 +427,38 @@ pub(crate) struct BuilderSettings {
     ///
     /// For more information on the reasoning behind this field see [ActionsSettings].
     pub actions: ActionsSettings,
-
-    // Certificate statuses will be fetched for either all the manifest labels, or just the active manifest.
-    pub certificate_status_fetch: Option<OcspFetch>,
-
-    // Whether or not existing OCSP responses should be overridden by new values.
-    pub certificate_status_should_override: Option<bool>,
+    // TODO: this setting affects fetching and generation of the assertion; needs clarification
+    /// Whether to create [`CertificateStatus`] assertions for manifests to store certificate revocation
+    /// status. The assertion can be fetched for the active manifest or for all manifests (including
+    /// ingredients).
+    ///
+    /// The default is to not fetch them at all.
+    ///
+    /// See more information in the spec here:
+    /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#certificate_status_assertion>
+    ///
+    /// [`CertificateStatus`]: crate::assertions::CertificateStatus
+    pub(crate) certificate_status_fetch: Option<OcspFetchScope>,
+    // TODO: this setting affects fetching and generation of the assertion; needs clarification
+    /// Whether to only use [`CertificateStatus`] assertions to check certificate revocation status. If there
+    /// is a stapled OCSP in the COSE claim of the manifest, it will be ignored. If [`Verify::ocsp_fetch`] is
+    /// enabled, it will also be ignored.
+    ///
+    /// The default value is false.
+    ///
+    /// [`CertificateStatus`]: crate::assertions::CertificateStatus
+    /// [`Verify::ocsp_fetch`]: crate::settings::Verify::ocsp_fetch
+    pub(crate) certificate_status_should_override: Option<bool>,
 }
 
+/// The scope of which manifests to fetch for OCSP.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
-pub(crate) enum OcspFetch {
+pub(crate) enum OcspFetchScope {
+    /// Fetch OCSP for all manifests.
     All,
+    /// Fetch OCSP for the active manifest only.
     Active,
 }