feat(rust): New catalyst IdUri type to replace the more limited Kid

Author: stevenj

docs/src/architecture/08_concepts/rbac_id_uri/catalyst-id-uri.md

@@ -32,7 +32,7 @@ License: CC-BY-4.0
 
 ## Abstract
 
-Definition of a [URI] which allows for RBAC keys used for different purposes to be easily and
+Definition of a [URI], which allows for RBAC keys used for different purposes to be easily and
 unambiguously identified.
 
 ## Motivation: why is this CIP necessary?
@@ -42,7 +42,7 @@ or which Key from a RBAC registration was used to sign data.
 RBAC defines a universal keychain of different keys that can be used for different purposes.
 They can be used not only for Signatures, but also Encryption.
 
-Sometimes all that is required is to identify the individual key chain.
+Sometimes all that is required is to identify the individual keychain.
 Other times a specific key on the chain needs to be referenced.
 
 Therefore, there needs to be an unambiguous and easy to lookup identifier to signify which keychain,
@@ -54,19 +54,21 @@ This document defines a [URI] scheme to unambiguously define a keychain or a spe
 
 ### URI
 
-The Catalyst RBAC Id is formatted using a [Universal Resource Identifier].
+The Catalyst RBAC ID is formatted using a [Universal Resource Identifier].
 Refer to [RFC3986] for the specification of the URI format.
 
 ### `scheme`
 
-The [scheme](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1) **MUST** be `id.catalyst`;
+The [scheme](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1) **MUST** be `id.catalyst`.
+
+When used as a Catalyst ID, where only catalyst IDs would be used, the scheme can be omitted.
 
 ### `authority`
 
 The [authority](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2) references the blockchain or network
 the key was registered within.
 
-It is perfectly valid for a Kid to reference a different network than the place where the Id or Key is used.
+It is perfectly valid for an ID Uri to reference a different network than the place where the ID or Key is used.
 For example, a `cardano` ID can be used to post documents to `IPFS`.
 Its purpose is to define WHERE the key was registered, and nothing more.
 
@@ -100,21 +102,21 @@ capable of storing catalyst RBAC registration keychains.
 #### `authority` - `userinfo`
 
 The [userinfo] is used to hold a user defined readable name that can be attached to the keychain.
-It may contain an optional `nonce` which is separated from the users name by a `:` and replaces a
+It may contain an optional `nonce` which is separated from the user's name by a `:` and replaces a
 traditional password used for HTTP basic authentication.
 
 Because the name is not unique, and is provided by the user, it is informational only.
 A URI is identical, provided the hostname and path are the same, the [userinfo] does not play
 a part in validating or finding the catalyst keychain being referenced.
 
 The `nonce` part contained in the `password` component of the username *MUST* be an integer,
-and it is the number of seconds since 1970 UTC, when the nonce was generated.
+and it is the number of seconds since 1970 UTC, when the Catalyst ID URI was generated.
 
 Applications which use the `nonce` will define its use, anything that does not use the `nonce` will ignore it.
 
 ##### Example `userinfo` with a `hostname`
 
-* `anne@cardano`  - username `anne` no nonce.
+* `anne@cardano` - username `anne` no nonce.
 * `blake:1737101079@midnight` - username `blake` with nonce 1737101079.
 * `:173710179#ethereum` - no username with nonce 173710179.
 
@@ -157,36 +159,38 @@ The first implementation will be Catalyst Voices.
   * Role 0 - Rotation 0.
   * `username` - undefined.
   * `nonce` - undefined.
-  In this example, it is exactly the same as the `<key>`.
+  * In this example, it is identical to `<key>/0/0` or `<key>/0`.
 * `id.catalyst://cardano/<key>/0`
   * A Signing key registered on the Cardano Main network.
   * Role 0 - Rotation 0.
   * `username` - undefined.
   * `nonce` - undefined.
+  * In this example, it is identical to `<key>/0/0` or `<key>`.
 * `id.catalyst://gary@cardano/<key>/0/0`
   * A Signing key registered on the Cardano Main network.
   * Role 0 - Rotation 0.
   * `username` - `gary`.
   * `nonce` - undefined.
+  * In this example, it is identical to `<key>` or `<key>/0`.
 * `id.catalyst://faith@preprod@cardano/<key>/7/3`
   * A Signing key registered on the Cardano pre-production network.
   * Role 7 - Rotation 3.
   * `username` - `faith`
   * `nonce` - undefined.
-  The Key for Role 7, and its third published rotation
+  * The Key for Role 7, and its third published rotation
   (i.e., the fourth key published, the first is the initial key, plus 3 rotations following it).
 * `id.catalyst://faith:173710179@preprod@cardano/<key>/2/0#encrypt`
   * A Public Encryption key registered on the Cardano pre-production network.
   * Role 2 - Rotation 0.
   * `username` - `faith`
   * `nonce` - 173710179.
-  The initially published Public Encryption Key for Role 2.
+  * The initially published Public Encryption Key for Role 2.
 * `kid.catalyst-rbac://:173710179@midnight/<key>/0/1`
   * A Signing key registered on the Midnight Blockchain Main network
   * Role 0 - Rotation 1.
   * `username` - undefined.
   * `nonce` - 173710179.
-  In this example, it is NOT the same as the `<key>`, as it identifies the first rotation after `<key>`.
+  * In this example, it is NOT the same as the `<key>`, as it identifies the first rotation after `<key>`.
 * `kid.catalyst-rbac://midnight/<key>/2/1#encrypt`
   * A public encryption key registered on the Midnight Blockchain Main network.
   * Role 2 - Rotation 1.

rust/catalyst-types/Cargo.toml

@@ -26,9 +26,10 @@ num-traits = "0.2.19"
 orx-concurrent-vec = "3.1.0"
 pallas-crypto = { version = "0.30.1", git = "https://github.com/input-output-hk/catalyst-pallas.git", rev = "9b5183c8b90b90fe2cc319d986e933e9518957b3" }
 serde = { version = "1.0.217", features = ["derive"] }
-thiserror = "2.0.9"
+thiserror = "2.0.11"
 base64-url = "3.0.0"
-uuid = { version = "1.11.0", features = ["v4", "v7", "serde"] }
+uuid = { version = "1.12.0", features = ["v4", "v7", "serde"] }
+chrono = "0.4.39"
 
 [dev-dependencies]
 ed25519-dalek = { version = "2.1.1", features = ["rand_core"] }

rust/catalyst-types/src/id_uri/errors.rs

@@ -7,13 +7,15 @@ use super::{key_rotation::KeyRotationError, role_index::RoleIndexError};
 
 /// Errors that can occur when parsing a `KidUri`
 #[derive(Display, Error, Debug)]
-pub enum KidUriError {
+pub enum IdUriError {
     /// Invalid KID URI
-    InvalidURI(#[from] fluent_uri::error::ParseError),
-    /// Invalid Scheme, not a KID URI
+    InvalidURI(#[from] fluent_uri::error::ParseError<String>),
+    /// Invalid Scheme, not a ID URI
     InvalidScheme,
     /// Network not defined in URI
     NoDefinedNetwork,
+    /// Invalid Nonce
+    InvalidNonce,
     /// Path of URI is invalid
     InvalidPath,
     /// Role 0 Key in path is invalid

rust/catalyst-types/src/id_uri/key_rotation.rs

@@ -21,6 +21,23 @@ pub enum KeyRotationError {
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct KeyRotation(u16);
 
+impl KeyRotation {
+    /// Default Role Index
+    pub const DEFAULT: KeyRotation = KeyRotation(0);
+
+    /// Is the `KeyRotation` the default value
+    #[must_use]
+    pub fn is_default(self) -> bool {
+        self == Self::DEFAULT
+    }
+}
+
+impl Default for KeyRotation {
+    fn default() -> Self {
+        Self::DEFAULT
+    }
+}
+
 impl From<u16> for KeyRotation {
     fn from(value: u16) -> Self {
         Self(value)