feat(rust/catalyst-types): CatalystId with admin differentiation (#602)

* update CatalystId type with admin functionality

* add unit test

* fix

* fix spelling

* bump crate version

* removed admin roles

* fix clippy

Author: Mr-Leshiy

rust/catalyst-types/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "catalyst-types"
-version = "0.0.9"
+version = "0.0.10"
 edition.workspace = true
 license.workspace = true
 authors.workspace = true
@@ -24,7 +24,7 @@ num-traits = "0.2.19"
 orx-concurrent-vec = { version = "3.6.0", features = ["serde"] }
 serde = { version = "1.0.217", features = ["derive", "rc"] }
 thiserror = "2.0.11"
-base64-url = "3.0.0"
+base64-url = "=3.0.0"
 uuid = { version = "1.12.0", features = ["v4", "v7", "serde"] }
 chrono = "0.4.39"
 tracing = "0.1.41"

rust/catalyst-types/src/catalyst_id/mod.rs

@@ -63,14 +63,24 @@ struct CatalystIdInner {
     /// - `true`: The key is used for encryption.
     /// - `false`: The key is used for signing (signature key).
     encryption: bool,
-    /// Indicates if this is an `id` type, or a `uri` type.
-    /// Used by the serialization functions.
-    /// `true` = format as an `Id`
-    /// `false` = format as a `Uri`
-    id: bool,
+    /// Catalyst ID type (URI, ID or Admin URI)
+    r#type: CatalystIdType,
+}
+
+#[derive(Debug, Clone, Default)]
+enum CatalystIdType {
+    /// format as an `Id`
+    Id,
+    /// format as a `Uri`
+    #[default]
+    Uri,
+    /// format as a admin `Uri`
+    AdminUri,
 }
 
 impl CatalystId {
+    /// Admin URI scheme for Catalyst
+    pub const ADMIN_SCHEME: &Scheme = Scheme::new_or_panic("admin.catalyst");
     /// Encryption Key Identifier Fragment
     const ENCRYPTION_FRAGMENT: &EStr<Fragment> = EStr::new_or_panic("encrypt");
     /// Maximum allowable Nonce Value
@@ -140,7 +150,7 @@ impl CatalystId {
             role: RoleId::default(), // Defaulted, use `with_role()` to change it.
             rotation: KeyRotation::default(), // Defaulted, use `with_rotation()` to change it.
             encryption: false,       // Defaulted, use `with_encryption()` to change it.
-            id: false,               // Default to `URI` formatted.
+            r#type: CatalystIdType::default(), // Default to `URI` formatted.
         });
 
         Self { inner }
@@ -150,28 +160,51 @@ impl CatalystId {
     #[must_use]
     pub fn as_uri(self) -> Self {
         let inner = Arc::try_unwrap(self.inner).unwrap_or_else(|v| (*v).clone());
-        let inner = Arc::new(CatalystIdInner { id: false, ..inner });
+        let inner = Arc::new(CatalystIdInner {
+            r#type: CatalystIdType::Uri,
+            ..inner
+        });
         Self { inner }
     }
 
     /// The `CatalystId` is formatted as a id.
     #[must_use]
     pub fn as_id(self) -> Self {
         let inner = Arc::try_unwrap(self.inner).unwrap_or_else(|v| (*v).clone());
-        let inner = Arc::new(CatalystIdInner { id: true, ..inner });
+        let inner = Arc::new(CatalystIdInner {
+            r#type: CatalystIdType::Id,
+            ..inner
+        });
+        Self { inner }
+    }
+
+    /// The `CatalystId` is formatted as a admin URI.
+    #[must_use]
+    pub fn as_admin(self) -> Self {
+        let inner = Arc::try_unwrap(self.inner).unwrap_or_else(|v| (*v).clone());
+        let inner = Arc::new(CatalystIdInner {
+            r#type: CatalystIdType::AdminUri,
+            ..inner
+        });
         Self { inner }
     }
 
     /// Was `CatalystId` formatted as an id when it was parsed.
     #[must_use]
     pub fn is_id(&self) -> bool {
-        self.inner.id
+        matches!(self.inner.r#type, CatalystIdType::Id)
+    }
+
+    /// Is `CatalystId` formatted as an Admin.
+    #[must_use]
+    pub fn is_admin(&self) -> bool {
+        matches!(self.inner.r#type, CatalystIdType::AdminUri)
     }
 
     /// Was `CatalystId` formatted as an uri when it was parsed.
     #[must_use]
     pub fn is_uri(&self) -> bool {
-        !self.inner.id
+        matches!(self.inner.r#type, CatalystIdType::Uri)
     }
 
     /// Add or change the username in a Catalyst ID URI.
@@ -588,27 +621,26 @@ impl FromStr for CatalystId {
     /// This will parse a URI or a RAW ID.\
     /// The only difference between them is a URI has the scheme, a raw ID does not.
     fn from_str(s: &str) -> Result<Self, Self::Err> {
-        // Did we serialize an ID?
-        let mut id = false;
-
-        // Check if we have a scheme, and if not default it to the catalyst ID scheme.
-        let raw_uri = {
+        let (uri, r#type) = {
             if s.contains("://") {
-                s.to_owned()
+                let uri = Uri::parse(s.to_owned())?;
+                // Check if its the correct scheme.
+                let r#type = if uri.scheme() == Self::SCHEME {
+                    CatalystIdType::Uri
+                } else if uri.scheme() == Self::ADMIN_SCHEME {
+                    CatalystIdType::AdminUri
+                } else {
+                    return Err(errors::CatalystIdError::InvalidScheme);
+                };
+                (uri, r#type)
             } else {
-                id = true;
                 // It might be a RAW ID, so try and parse with the correct scheme.
-                format!("{}://{}", CatalystId::SCHEME, s)
+                let uri = Uri::parse(format!("{}://{}", Self::SCHEME, s))?;
+                let r#type = CatalystIdType::Id;
+                (uri, r#type)
             }
         };
 
-        let uri = Uri::parse(raw_uri)?;
-
-        // Check if its the correct scheme.
-        if uri.scheme() != CatalystId::SCHEME {
-            return Err(errors::CatalystIdError::InvalidScheme);
-        }
-
         // Decode the network and subnet
         let auth = uri
             .authority()
@@ -684,36 +716,26 @@ impl FromStr for CatalystId {
             }
         };
 
-        let cat_id = {
-            let mut cat_id = Self::new(network, subnet, role0_pk)
-                .with_role(role_index)
-                .with_rotation(rotation);
-
-            if uri.has_fragment() {
-                if uri.fragment() == Some(Self::ENCRYPTION_FRAGMENT) {
-                    cat_id = cat_id.with_encryption();
-                } else {
-                    return Err(errors::CatalystIdError::InvalidEncryptionKeyFragment);
-                }
-            }
-
-            if let Some(username) = username {
-                cat_id = cat_id.with_username(&username);
-            }
-
-            if let Some(nonce) = nonce {
-                cat_id = cat_id.with_specific_nonce(nonce);
-            }
-
-            // Default to URI, so only set it as an ID if its not a URI.
-            if id {
-                cat_id = cat_id.as_id();
-            }
-
-            cat_id
+        let encryption = match uri.fragment() {
+            None => false,
+            Some(f) if f == Self::ENCRYPTION_FRAGMENT => true,
+            Some(_) => return Err(errors::CatalystIdError::InvalidEncryptionKeyFragment),
         };
 
-        Ok(cat_id)
+        let inner = CatalystIdInner {
+            network: network.to_string(),
+            subnet: subnet.map(ToString::to_string),
+            role0_pk,
+            r#type,
+            rotation,
+            role: role_index,
+            username,
+            nonce,
+            encryption,
+        }
+        .into();
+
+        Ok(Self { inner })
     }
 }
 
@@ -722,8 +744,10 @@ impl Display for CatalystId {
         &self,
         f: &mut Formatter<'_>,
     ) -> Result<(), std::fmt::Error> {
-        if !self.inner.id {
-            write!(f, "{}://", Self::SCHEME.as_str())?;
+        match self.inner.r#type {
+            CatalystIdType::Uri => write!(f, "{}://", Self::SCHEME.as_str())?,
+            CatalystIdType::AdminUri => write!(f, "{}://", Self::ADMIN_SCHEME.as_str())?,
+            CatalystIdType::Id => {},
         }
 
         let mut needs_at = false;
@@ -754,9 +778,9 @@ impl Display for CatalystId {
         )?;
 
         // Role and Rotation are only serialized if its NOT and ID or they are not the defaults.
-        if !self.inner.role.is_default() || !self.inner.rotation.is_default() || !self.inner.id {
+        if !self.inner.role.is_default() || !self.inner.rotation.is_default() || !self.is_id() {
             write!(f, "/{}", self.inner.role)?;
-            if !self.inner.rotation.is_default() || !self.inner.id {
+            if !self.inner.rotation.is_default() || !self.is_id() {
                 write!(f, "/{}", self.inner.rotation)?;
             }
         }
@@ -792,7 +816,7 @@ mod tests {
 
     use super::CatalystId;
 
-    const CATALYST_ID_TEST_VECTOR: [&str; 9] = [
+    const CATALYST_ID_TEST_VECTOR: [&str; 13] = [
         "cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE",
         "user@cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE",
         "user:1735689600@cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE",
@@ -802,6 +826,11 @@ mod tests {
         "id.catalyst://preview.cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/2/0#encrypt",
         "id.catalyst://midnight/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0/1",
         "id.catalyst://midnight/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/2/1#encrypt",
+        // Admin types
+        "admin.catalyst://preprod.cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/7/3",
+        "admin.catalyst://preview.cardano/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/2/0#encrypt",
+        "admin.catalyst://midnight/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/0/1",
+        "admin.catalyst://midnight/FftxFnOrj2qmTuB2oZG2v0YEWJfKvQ9Gg8AgNAhDsKE/2/1#encrypt",
     ];
 
     #[test]
@@ -845,6 +874,22 @@ mod tests {
         assert_eq!(uri_id.as_short_id().inner, short_id.inner);
     }
 
+    #[test]
+    fn catalyst_id_type_test() {
+        for id_string in &CATALYST_ID_TEST_VECTOR[0..5] {
+            let id = id_string.parse::<CatalystId>().unwrap();
+            assert!(id.is_id());
+        }
+        for id_string in &CATALYST_ID_TEST_VECTOR[5..9] {
+            let id = id_string.parse::<CatalystId>().unwrap();
+            assert!(id.is_uri());
+        }
+        for id_string in &CATALYST_ID_TEST_VECTOR[9..13] {
+            let id = id_string.parse::<CatalystId>().unwrap();
+            assert!(id.is_admin());
+        }
+    }
+
     #[test_case(0, 1, true, false, false; "base vs user")]
     #[test_case(0, 2, true, false, false; "base vs user_nonce")]
     #[test_case(0, 3, true, false, false; "base vs nonce")]

rust/catalyst-types/src/catalyst_id/role_index.rs

@@ -37,24 +37,6 @@ pub enum RoleId {
     DelegatedRepresentative = 1,
     /// Proposer that enabling creation, collaboration, and submission of proposals.
     Proposer = 3,
-    /// Root Certificate Authority role.
-    RootCA = 100,
-    /// Brand Certificate Authority role.
-    BrandCA = 101,
-    /// Campaign Certificate Authority role.
-    CampaignCA = 102,
-    /// Category Certificate Authority role.
-    CategoryCA = 103,
-    /// Root Admin role.
-    RootAdmin = 104,
-    /// Brand Admin role.
-    BrandAdmin = 105,
-    /// Campaign Admin role.
-    CampaignAdmin = 106,
-    /// Category Admin role.
-    CategoryAdmin = 107,
-    /// Moderator role.
-    Moderator = 108,
     /// A custom role.
     Unknown(u8),
 }
@@ -73,15 +55,6 @@ impl RoleId {
             RoleId::Role0 => 0,
             RoleId::DelegatedRepresentative => 1,
             RoleId::Proposer => 3,
-            RoleId::RootCA => 100,
-            RoleId::BrandCA => 101,
-            RoleId::CampaignCA => 102,
-            RoleId::CategoryCA => 103,
-            RoleId::RootAdmin => 104,
-            RoleId::BrandAdmin => 105,
-            RoleId::CampaignAdmin => 106,
-            RoleId::CategoryAdmin => 107,
-            RoleId::Moderator => 108,
             RoleId::Unknown(b) => b,
         }
     }
@@ -93,15 +66,6 @@ impl From<u8> for RoleId {
             0 => Self::Role0,
             1 => Self::DelegatedRepresentative,
             3 => Self::Proposer,
-            100 => Self::RootCA,
-            101 => Self::BrandCA,
-            102 => Self::CampaignCA,
-            103 => Self::CategoryCA,
-            104 => Self::RootAdmin,
-            105 => Self::BrandAdmin,
-            106 => Self::CampaignAdmin,
-            107 => Self::CategoryAdmin,
-            108 => Self::Moderator,
             b => Self::Unknown(b),
         }
     }