feat(rust/signed-doc): Catalyst Signed Documents signature kid validation rule (#274)

Mr-Leshiy · saibatizoku · web-flow · commit ae80c50112fc · 2025-04-10T20:45:34.000+07:00
* add SignatureKidRule

* feat(rust/signed-doc): update tests with signature kid validation

* wip

* add unit test

* wip

---------

Co-authored-by: Joaquín Rosales &lt;joaquin.rosales@iohk.io&gt;
diff --git a/rust/catalyst-types/src/id_uri/role_index.rs b/rust/catalyst-types/src/id_uri/role_index.rs
@@ -24,19 +24,23 @@ pub enum RoleIndexError {
 pub struct RoleIndex(u16);
 
 impl RoleIndex {
-    /// Default Role Index
-    pub const DEFAULT: RoleIndex = RoleIndex(0);
+    /// Delegated Representative
+    pub const DREP: RoleIndex = RoleIndex(1);
+    /// Proposer
+    pub const PROPOSER: RoleIndex = RoleIndex(3);
+    /// Default Role 0
+    pub const ROLE_0: RoleIndex = RoleIndex(0);
 
-    /// Is the `RoleIndex` the default value
+    /// Is the `RoleIndex` the default value (Role 0)
     #[must_use]
     pub fn is_default(self) -> bool {
-        self == Self::DEFAULT
+        self == Self::ROLE_0
     }
 }
 
 impl Default for RoleIndex {
     fn default() -> Self {
-        Self::DEFAULT
+        Self::ROLE_0
     }
 }
 
diff --git a/rust/signed_doc/src/validator/mod.rs b/rust/signed_doc/src/validator/mod.rs
@@ -10,11 +10,15 @@ use std::{
 };
 
 use anyhow::Context;
-use catalyst_types::{id_uri::IdUri, problem_report::ProblemReport, uuid::Uuid};
+use catalyst_types::{
+    id_uri::{role_index::RoleIndex, IdUri},
+    problem_report::ProblemReport,
+    uuid::Uuid,
+};
 use coset::{CoseSign, CoseSignature};
 use rules::{
     CategoryRule, ContentEncodingRule, ContentTypeRule, RefRule, ReplyRule, Rules, SectionRule,
-    TemplateRule,
+    SignatureKidRule, TemplateRule,
 };
 
 use crate::{
@@ -51,6 +55,9 @@ fn document_rules_init() -> HashMap<Uuid, Rules> {
         doc_ref: RefRule::NotSpecified,
         reply: ReplyRule::NotSpecified,
         section: SectionRule::NotSpecified,
+        kid: SignatureKidRule {
+            exp: &[RoleIndex::PROPOSER],
+        },
     };
     document_rules_map.insert(PROPOSAL_DOCUMENT_UUID_TYPE, proposal_document_rules);
 
@@ -81,6 +88,9 @@ fn document_rules_init() -> HashMap<Uuid, Rules> {
         },
         section: SectionRule::Specified { optional: true },
         category: CategoryRule::NotSpecified,
+        kid: SignatureKidRule {
+            exp: &[RoleIndex::ROLE_0],
+        },
     };
     document_rules_map.insert(COMMENT_DOCUMENT_UUID_TYPE, comment_document_rules);
 
@@ -102,6 +112,9 @@ fn document_rules_init() -> HashMap<Uuid, Rules> {
         },
         reply: ReplyRule::NotSpecified,
         section: SectionRule::NotSpecified,
+        kid: SignatureKidRule {
+            exp: &[RoleIndex::PROPOSER],
+        },
     };
 
     document_rules_map.insert(
diff --git a/rust/signed_doc/src/validator/rules/mod.rs b/rust/signed_doc/src/validator/rules/mod.rs
@@ -11,6 +11,7 @@ mod content_type;
 mod doc_ref;
 mod reply;
 mod section;
+mod signature_kid;
 mod template;
 
 pub(crate) use category::CategoryRule;
@@ -19,6 +20,7 @@ pub(crate) use content_type::ContentTypeRule;
 pub(crate) use doc_ref::RefRule;
 pub(crate) use reply::ReplyRule;
 pub(crate) use section::SectionRule;
+pub(crate) use signature_kid::SignatureKidRule;
 pub(crate) use template::TemplateRule;
 
 /// Struct represented a full collection of rules for all fields
@@ -37,6 +39,8 @@ pub(crate) struct Rules {
     pub(crate) section: SectionRule,
     /// 'category' field validation rule
     pub(crate) category: CategoryRule,
+    /// `kid` field validation rule
+    pub(crate) kid: SignatureKidRule,
 }
 
 impl Rules {
@@ -53,6 +57,7 @@ impl Rules {
             self.reply.check(doc, provider).boxed(),
             self.section.check(doc).boxed(),
             self.category.check(doc, provider).boxed(),
+            self.kid.check(doc).boxed(),
         ];
 
         let res = futures::future::join_all(rules)
diff --git a/rust/signed_doc/src/validator/rules/signature_kid.rs b/rust/signed_doc/src/validator/rules/signature_kid.rs
@@ -0,0 +1,79 @@
+//! Catalyst Signed Document COSE signature `kid` (Catalyst Id) role validation
+
+use catalyst_types::id_uri::role_index::RoleIndex;
+
+use crate::CatalystSignedDocument;
+
+///  COSE signature `kid` (Catalyst Id) role validation
+pub(crate) struct SignatureKidRule {
+    /// expected `RoleIndex` values for the `kid` field
+    pub(crate) exp: &'static [RoleIndex],
+}
+
+impl SignatureKidRule {
+    /// Field validation rule
+    #[allow(clippy::unused_async)]
+    pub(crate) async fn check(&self, doc: &CatalystSignedDocument) -> anyhow::Result<bool> {
+        let contains_exp_role = doc.kids().iter().enumerate().all(|(i, kid)| {
+            let (role_index, _) = kid.role_and_rotation();
+            let res = self.exp.contains(&role_index);
+            if !res {
+                doc.report().invalid_value(
+                    "kid",
+                    role_index.to_string().as_str(),
+                    format!("{:?}", self.exp).as_str(),
+                    format!(
+                        "Invalid Catalyst Signed Document signature {i} `kid` Catalyst Role value"
+                    )
+                    .as_str(),
+                );
+            }
+            res
+        });
+        if !contains_exp_role {
+            return Ok(false);
+        }
+
+        Ok(true)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use catalyst_types::{
+        id_uri::IdUri,
+        uuid::{UuidV4, UuidV7},
+    };
+
+    use super::*;
+    use crate::{Builder, ContentType};
+
+    #[tokio::test]
+    async fn signature_kid_rule_test() {
+        let mut rule = SignatureKidRule {
+            exp: &[RoleIndex::ROLE_0],
+        };
+
+        let sk = ed25519_dalek::SigningKey::generate(&mut rand::rngs::OsRng);
+        let pk = sk.verifying_key();
+        let kid = IdUri::new("cardano", None, pk).with_role(RoleIndex::ROLE_0);
+
+        let doc = Builder::new()
+            .with_decoded_content(serde_json::to_vec(&serde_json::Value::Null).unwrap())
+            .with_json_metadata(serde_json::json!({
+                "type": UuidV4::new().to_string(),
+                "id": UuidV7::new().to_string(),
+                "ver": UuidV7::new().to_string(),
+                "content-type": ContentType::Json.to_string(),
+            }))
+            .unwrap()
+            .add_signature(sk.to_bytes(), kid)
+            .unwrap()
+            .build();
+
+        assert!(rule.check(&doc).await.unwrap());
+
+        rule.exp = &[RoleIndex::PROPOSER];
+        assert!(!rule.check(&doc).await.unwrap());
+    }
+}
diff --git a/rust/signed_doc/tests/comment.rs b/rust/signed_doc/tests/comment.rs
@@ -1,6 +1,7 @@
 //! Integration test for comment document validation part.
 
 use catalyst_signed_doc::{providers::tests::TestCatalystSignedDocumentProvider, *};
+use catalyst_types::id_uri::role_index::RoleIndex;
 
 mod common;
 
@@ -12,21 +13,24 @@ async fn test_valid_comment_doc() {
         common::create_dummy_doc(doc_types::COMMENT_TEMPLATE_UUID_TYPE).unwrap();
 
     let uuid_v7 = UuidV7::new();
-    let (doc, ..) = common::create_dummy_signed_doc(Some(serde_json::json!({
-        "content-type": ContentType::Json.to_string(),
-        "content-encoding": ContentEncoding::Brotli.to_string(),
-        "type": doc_types::COMMENT_DOCUMENT_UUID_TYPE,
-        "id": uuid_v7.to_string(),
-        "ver": uuid_v7.to_string(),
-        "template": {
-          "id": template_doc_id,
-          "ver": template_doc_ver
-        },
-        "ref": {
-            "id": proposal_doc_id,
-            "ver": proposal_doc_ver
-        }
-    })))
+    let (doc, ..) = common::create_dummy_signed_doc(
+        Some(serde_json::json!({
+            "content-type": ContentType::Json.to_string(),
+            "content-encoding": ContentEncoding::Brotli.to_string(),
+            "type": doc_types::COMMENT_DOCUMENT_UUID_TYPE,
+            "id": uuid_v7.to_string(),
+            "ver": uuid_v7.to_string(),
+            "template": {
+              "id": template_doc_id,
+              "ver": template_doc_ver
+            },
+            "ref": {
+                "id": proposal_doc_id,
+                "ver": proposal_doc_ver
+            }
+        })),
+        RoleIndex::ROLE_0,
+    )
     .unwrap();
 
     let mut provider = TestCatalystSignedDocumentProvider::default();
@@ -66,25 +70,28 @@ async fn test_valid_comment_doc_with_reply() {
         .build();
 
     let uuid_v7 = UuidV7::new();
-    let (doc, ..) = common::create_dummy_signed_doc(Some(serde_json::json!({
-        "content-type": ContentType::Json.to_string(),
-        "content-encoding": ContentEncoding::Brotli.to_string(),
-        "type": doc_types::COMMENT_DOCUMENT_UUID_TYPE,
-        "id": uuid_v7.to_string(),
-        "ver": uuid_v7.to_string(),
-        "template": {
-          "id": template_doc_id,
-          "ver": template_doc_ver
-        },
-        "ref": {
-            "id": proposal_doc_id,
-            "ver": proposal_doc_ver
-        },
-        "reply": {
-            "id": comment_doc_id,
-            "ver": comment_doc_ver
-        }
-    })))
+    let (doc, ..) = common::create_dummy_signed_doc(
+        Some(serde_json::json!({
+            "content-type": ContentType::Json.to_string(),
+            "content-encoding": ContentEncoding::Brotli.to_string(),
+            "type": doc_types::COMMENT_DOCUMENT_UUID_TYPE,
+            "id": uuid_v7.to_string(),
+            "ver": uuid_v7.to_string(),
+            "template": {
+              "id": template_doc_id,
+              "ver": template_doc_ver
+            },
+            "ref": {
+                "id": proposal_doc_id,
+                "ver": proposal_doc_ver
+            },
+            "reply": {
+                "id": comment_doc_id,
+                "ver": comment_doc_ver
+            }
+        })),
+        RoleIndex::ROLE_0,
+    )
     .unwrap();
 
     let mut provider = TestCatalystSignedDocumentProvider::default();
@@ -105,19 +112,22 @@ async fn test_invalid_comment_doc() {
         common::create_dummy_doc(doc_types::COMMENT_TEMPLATE_UUID_TYPE).unwrap();
 
     let uuid_v7 = UuidV7::new();
-    let (doc, ..) = common::create_dummy_signed_doc(Some(serde_json::json!({
-        "content-type": ContentType::Json.to_string(),
-        "content-encoding": ContentEncoding::Brotli.to_string(),
-        "type": doc_types::COMMENT_DOCUMENT_UUID_TYPE,
-        "id": uuid_v7.to_string(),
-        "ver": uuid_v7.to_string(),
-        "template": {
-          "id": template_doc_id,
-          "ver": template_doc_ver
-        },
-        // without ref
-        "ref": serde_json::Value::Null
-    })))
+    let (doc, ..) = common::create_dummy_signed_doc(
+        Some(serde_json::json!({
+            "content-type": ContentType::Json.to_string(),
+            "content-encoding": ContentEncoding::Brotli.to_string(),
+            "type": doc_types::COMMENT_DOCUMENT_UUID_TYPE,
+            "id": uuid_v7.to_string(),
+            "ver": uuid_v7.to_string(),
+            "template": {
+              "id": template_doc_id,
+              "ver": template_doc_ver
+            },
+            // without ref
+            "ref": serde_json::Value::Null
+        })),
+        RoleIndex::ROLE_0,
+    )
     .unwrap();
 
     let mut provider = TestCatalystSignedDocumentProvider::default();
diff --git a/rust/signed_doc/tests/common/mod.rs b/rust/signed_doc/tests/common/mod.rs
@@ -3,6 +3,7 @@
 use std::str::FromStr;
 
 use catalyst_signed_doc::*;
+use catalyst_types::id_uri::role_index::RoleIndex;
 
 pub fn test_metadata() -> (UuidV7, UuidV4, serde_json::Value) {
     let uuid_v7 = UuidV7::new();
@@ -28,15 +29,17 @@ pub fn test_metadata() -> (UuidV7, UuidV4, serde_json::Value) {
     (uuid_v7, uuid_v4, metadata_fields)
 }
 
-pub fn create_dummy_key_pair() -> anyhow::Result<(
+pub fn create_dummy_key_pair(
+    role_index: RoleIndex,
+) -> anyhow::Result<(
     ed25519_dalek::SigningKey,
     ed25519_dalek::VerifyingKey,
     IdUri,
 )> {
     let sk = create_signing_key();
     let pk = sk.verifying_key();
     let kid = IdUri::from_str(&format!(
-        "id.catalyst://cardano/{}/0/0",
+        "id.catalyst://cardano/{}/{role_index}/0",
         base64_url::encode(pk.as_bytes())
     ))?;
 
@@ -71,9 +74,9 @@ pub fn create_signing_key() -> ed25519_dalek::SigningKey {
 }
 
 pub fn create_dummy_signed_doc(
-    with_metadata: Option<serde_json::Value>,
+    with_metadata: Option<serde_json::Value>, with_role_index: RoleIndex,
 ) -> anyhow::Result<(CatalystSignedDocument, ed25519_dalek::VerifyingKey, IdUri)> {
-    let (sk, pk, kid) = create_dummy_key_pair()?;
+    let (sk, pk, kid) = create_dummy_key_pair(with_role_index)?;
 
     let content = serde_json::to_vec(&serde_json::Value::Null)?;
     let (_, _, metadata) = test_metadata();
diff --git a/rust/signed_doc/tests/proposal.rs b/rust/signed_doc/tests/proposal.rs
diff --git a/rust/signed_doc/tests/signature.rs b/rust/signed_doc/tests/signature.rs
diff --git a/rust/signed_doc/tests/submission.rs b/rust/signed_doc/tests/submission.rs
