feat(rust/signed-doc): New CollaboratorsRule type, validating collaborators metadata field (#555)

Mr-Leshiy · web-flow · commit 51cca940dba2 · 2025-09-15T17:29:34.000+04:00
* added new Signers type

* wip

* add ReplyRule initialisation

* wip

* wip

* fix

* cleanup

* fix clippy

* add CollaboratorsRule type

* fix fmt

* fix clippy
diff --git a/rust/signed_doc/src/metadata/collaborators.rs b/rust/signed_doc/src/metadata/collaborators.rs
@@ -17,6 +17,12 @@ impl Deref for Collaborators {
     }
 }
 
+impl From<Vec<CatalystId>> for Collaborators {
+    fn from(value: Vec<CatalystId>) -> Self {
+        Self(value)
+    }
+}
+
 impl minicbor::Encode<()> for Collaborators {
     fn encode<W: minicbor::encode::Write>(
         &self,
diff --git a/rust/signed_doc/src/validator/mod.rs b/rust/signed_doc/src/validator/mod.rs
@@ -18,7 +18,7 @@ use crate::{
     },
     metadata::DocType,
     providers::{CatalystSignedDocumentProvider, VerifyingKeyProvider},
-    validator::rules::{SignatureRule, TemplateRule},
+    validator::rules::{CollaboratorsRule, SignatureRule, TemplateRule},
     CatalystSignedDocument, ContentEncoding, ContentType,
 };
 
@@ -55,6 +55,7 @@ fn proposal_rule() -> Rules {
         doc_ref: RefRule::NotSpecified,
         reply: ReplyRule::NotSpecified,
         section: SectionRule::NotSpecified,
+        collaborators: CollaboratorsRule::NotSpecified,
         content: ContentRule::NotNil,
         kid: SignatureKidRule {
             allowed_roles: vec![RoleId::Proposer],
@@ -101,6 +102,7 @@ fn proposal_comment_rule() -> Rules {
             allowed_type: parameters.clone(),
             optional: false,
         },
+        collaborators: CollaboratorsRule::NotSpecified,
         content: ContentRule::NotNil,
         kid: SignatureKidRule {
             allowed_roles: vec![RoleId::Role0],
@@ -153,6 +155,7 @@ fn proposal_submission_action_rule() -> Rules {
         },
         reply: ReplyRule::NotSpecified,
         section: SectionRule::NotSpecified,
+        collaborators: CollaboratorsRule::NotSpecified,
         content: ContentRule::StaticSchema(ContentSchema::Json(proposal_action_json_schema)),
         kid: SignatureKidRule {
             allowed_roles: vec![RoleId::Proposer],
diff --git a/rust/signed_doc/src/validator/rules/collaborators.rs b/rust/signed_doc/src/validator/rules/collaborators.rs
@@ -0,0 +1,156 @@
+//! `collaborators` rule type impl.
+
+use crate::CatalystSignedDocument;
+
+/// `collaborators` field validation rule
+#[derive(Debug)]
+pub(crate) enum CollaboratorsRule {
+    /// Is 'collaborators' specified
+    #[allow(dead_code)]
+    Specified {
+        /// optional flag for the `collaborators` field
+        optional: bool,
+    },
+    /// 'collaborators' is not specified
+    NotSpecified,
+}
+
+impl CollaboratorsRule {
+    /// Field validation rule
+    #[allow(clippy::unused_async)]
+    pub(crate) async fn check(
+        &self,
+        doc: &CatalystSignedDocument,
+    ) -> anyhow::Result<bool> {
+        if let Self::Specified { optional } = self {
+            if doc.doc_meta().collaborators().is_empty() && !optional {
+                doc.report().missing_field(
+                    "collaborators",
+                    "Document must have at least one entry in 'collaborators' field",
+                );
+                return Ok(false);
+            }
+        }
+        if let Self::NotSpecified = self {
+            if !doc.doc_meta().collaborators().is_empty() {
+                doc.report().unknown_field(
+                    "collaborators",
+                    &format!(
+                        "{:#?}",
+                        doc.doc_meta()
+                            .collaborators()
+                            .iter()
+                            .map(ToString::to_string)
+                            .reduce(|a, b| format!("{a}, {b}"))
+                    ),
+                    "Document does not expect to have a 'collaborators' field",
+                );
+                return Ok(false);
+            }
+        }
+
+        Ok(true)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use catalyst_types::catalyst_id::role_index::RoleId;
+    use test_case::test_case;
+
+    use super::*;
+    use crate::{
+        builder::tests::Builder, metadata::SupportedField,
+        validator::rules::utils::create_dummy_key_pair,
+    };
+
+    #[test_case(
+        || {
+            Builder::new()
+                .with_metadata_field(SupportedField::Collaborators(
+                        vec![create_dummy_key_pair(RoleId::Role0).2].into()
+                    ))
+                .build()
+        }
+        => true
+        ;
+        "valid 'collaborators' field present"
+    )]
+    #[test_case(
+        || {
+            Builder::new().build()
+        }
+        => true
+        ;
+        "missing 'collaborators' field"
+    )]
+    #[tokio::test]
+    async fn section_rule_specified_optional_test(
+        doc_gen: impl FnOnce() -> CatalystSignedDocument
+    ) -> bool {
+        let rule = CollaboratorsRule::Specified { optional: true };
+
+        let doc = doc_gen();
+        rule.check(&doc).await.unwrap()
+    }
+
+    #[test_case(
+        || {
+            Builder::new()
+                .with_metadata_field(SupportedField::Collaborators(
+                        vec![create_dummy_key_pair(RoleId::Role0).2].into()
+                    ))
+                .build()
+        }
+        => true
+        ;
+        "valid 'collaborators' field present"
+    )]
+    #[test_case(
+        || {
+            Builder::new().build()
+        }
+        => false
+        ;
+        "missing 'collaborators' field"
+    )]
+    #[tokio::test]
+    async fn section_rule_specified_not_optional_test(
+        doc_gen: impl FnOnce() -> CatalystSignedDocument
+    ) -> bool {
+        let rule = CollaboratorsRule::Specified { optional: false };
+
+        let doc = doc_gen();
+        rule.check(&doc).await.unwrap()
+    }
+
+    #[test_case(
+        || {
+            Builder::new().build()
+        }
+        => true
+        ;
+        "missing 'collaborators' field"
+    )]
+    #[test_case(
+        || {
+            Builder::new()
+                .with_metadata_field(SupportedField::Collaborators(
+                        vec![create_dummy_key_pair(RoleId::Role0).2].into()
+                    ))
+                .build()
+        }
+        => false
+        ;
+        "valid 'collaborators' field present"
+    )]
+    #[tokio::test]
+    async fn section_rule_not_specified_test(
+        doc_gen: impl FnOnce() -> CatalystSignedDocument
+    ) -> bool {
+        let rule = CollaboratorsRule::NotSpecified;
+
+        let doc = doc_gen();
+        rule.check(&doc).await.unwrap()
+    }
+}
diff --git a/rust/signed_doc/src/validator/rules/mod.rs b/rust/signed_doc/src/validator/rules/mod.rs
@@ -8,6 +8,7 @@ use crate::{
     CatalystSignedDocument,
 };
 
+mod collaborators;
 mod content;
 mod content_encoding;
 mod content_type;
@@ -23,6 +24,7 @@ mod template;
 mod utils;
 mod ver;
 
+pub(crate) use collaborators::CollaboratorsRule;
 pub(crate) use content::{ContentRule, ContentSchema};
 pub(crate) use content_encoding::ContentEncodingRule;
 pub(crate) use content_type::ContentTypeRule;
@@ -58,6 +60,8 @@ pub(crate) struct Rules {
     pub(crate) section: SectionRule,
     /// 'parameters' field validation rule
     pub(crate) parameters: ParametersRule,
+    /// 'collaborators' field validation rule
+    pub(crate) collaborators: CollaboratorsRule,
     /// document's content validation rule
     pub(crate) content: ContentRule,
     /// `kid` field validation rule
@@ -88,6 +92,7 @@ impl Rules {
             self.reply.check(doc, provider).boxed(),
             self.section.check(doc).boxed(),
             self.parameters.check(doc, provider).boxed(),
+            self.collaborators.check(doc).boxed(),
             self.content.check(doc).boxed(),
             self.kid.check(doc).boxed(),
             self.signature.check(doc, provider).boxed(),
@@ -132,6 +137,7 @@ impl Rules {
                 doc_ref: RefRule::new(&spec.docs, &doc_spec.metadata.doc_ref)?,
                 reply: ReplyRule::new(&spec.docs, &doc_spec.metadata.reply)?,
                 section: SectionRule::NotSpecified,
+                collaborators: CollaboratorsRule::NotSpecified,
                 content: ContentRule::new(&doc_spec.payload)?,
                 kid: SignatureKidRule::new(&doc_spec.signers.roles),
                 signature: SignatureRule { mutlisig: false },
diff --git a/rust/signed_doc/src/validator/rules/signature.rs b/rust/signed_doc/src/validator/rules/signature.rs
@@ -118,37 +118,7 @@ mod tests {
     use ed25519_dalek::ed25519::signature::Signer;
 
     use super::*;
-    use crate::{providers::tests::*, *};
-
-    mod helper {
-        use std::str::FromStr;
-
-        use catalyst_types::catalyst_id::role_index::RoleId;
-
-        use crate::*;
-
-        pub(super) fn create_dummy_key_pair(
-            role_index: RoleId
-        ) -> anyhow::Result<(
-            ed25519_dalek::SigningKey,
-            ed25519_dalek::VerifyingKey,
-            CatalystId,
-        )> {
-            let sk = create_signing_key();
-            let pk = sk.verifying_key();
-            let kid = CatalystId::from_str(&format!(
-                "id.catalyst://cardano/{}/{role_index}/0",
-                base64_url::encode(pk.as_bytes())
-            ))?;
-
-            Ok((sk, pk, kid))
-        }
-
-        pub(super) fn create_signing_key() -> ed25519_dalek::SigningKey {
-            let mut csprng = rand::rngs::OsRng;
-            ed25519_dalek::SigningKey::generate(&mut csprng)
-        }
-    }
+    use crate::{providers::tests::*, validator::rules::utils::create_dummy_key_pair, *};
 
     fn metadata() -> serde_json::Value {
         serde_json::json!({
@@ -177,7 +147,7 @@ mod tests {
 
     #[tokio::test]
     async fn single_signature_validation_test() {
-        let (sk, pk, kid) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
+        let (sk, pk, kid) = create_dummy_key_pair(RoleId::Role0);
 
         let signed_doc = Builder::new()
             .with_json_metadata(metadata())
@@ -207,7 +177,7 @@ mod tests {
             .unwrap());
 
         // case: signed with different key
-        let (another_sk, ..) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
+        let (another_sk, ..) = create_dummy_key_pair(RoleId::Role0);
         let invalid_doc = signed_doc
             .into_builder()
             .unwrap()
@@ -235,10 +205,10 @@ mod tests {
 
     #[tokio::test]
     async fn multiple_signatures_validation_test() {
-        let (sk1, pk1, kid1) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
-        let (sk2, pk2, kid2) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
-        let (sk3, pk3, kid3) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
-        let (_, pk_n, kid_n) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
+        let (sk1, pk1, kid1) = create_dummy_key_pair(RoleId::Role0);
+        let (sk2, pk2, kid2) = create_dummy_key_pair(RoleId::Role0);
+        let (sk3, pk3, kid3) = create_dummy_key_pair(RoleId::Role0);
+        let (_, pk_n, kid_n) = create_dummy_key_pair(RoleId::Role0);
 
         let signed_doc = Builder::new()
             .with_json_metadata(metadata())
@@ -391,7 +361,7 @@ mod tests {
 
     #[tokio::test]
     async fn special_cbor_cases() {
-        let (sk, pk, kid) = helper::create_dummy_key_pair(RoleId::Role0).unwrap();
+        let (sk, pk, kid) = create_dummy_key_pair(RoleId::Role0);
         let mut provider = TestCatalystProvider::default();
         provider.add_pk(kid.clone(), pk);
 
diff --git a/rust/signed_doc/src/validator/rules/utils.rs b/rust/signed_doc/src/validator/rules/utils.rs
@@ -49,3 +49,24 @@ pub(crate) fn content_json_schema_check(
 
     true
 }
+
+#[cfg(test)]
+pub(super) fn create_dummy_key_pair(
+    role_index: catalyst_types::catalyst_id::role_index::RoleId
+) -> (
+    ed25519_dalek::SigningKey,
+    ed25519_dalek::VerifyingKey,
+    catalyst_types::catalyst_id::CatalystId,
+) {
+    let sk = create_signing_key();
+    let pk = sk.verifying_key();
+    let kid =
+        catalyst_types::catalyst_id::CatalystId::new("cardano", None, pk).with_role(role_index);
+    (sk, pk, kid)
+}
+
+#[cfg(test)]
+pub(super) fn create_signing_key() -> ed25519_dalek::SigningKey {
+    let mut csprng = rand::rngs::OsRng;
+    ed25519_dalek::SigningKey::generate(&mut csprng)
+}

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,12 @@ impl Deref for Collaborators {`
`17`	`17`	`}`
`18`	`18`	`}`
`19`	`19`
	`20`	`+impl From<Vec<CatalystId>> for Collaborators {`
	`21`	`+ fn from(value: Vec<CatalystId>) -> Self {`
	`22`	`+ Self(value)`
	`23`	`+ }`
	`24`	`+}`
	`25`	`+`
`20`	`26`	`impl minicbor::Encode<()> for Collaborators {`
`21`	`27`	`fn encode<W: minicbor::encode::Write>(`
`22`	`28`	`&self,`