bc_components/id/
xid.rs

1use dcbor::prelude::*;
2use anyhow::{ bail, Result, Error };
3
4use crate::{tags, Digest, PrivateKeyBase, PublicKeys, Reference, ReferenceProvider, SigningPrivateKey, SigningPublicKey};
5
6/// A XID (eXtensible IDentifier).
7///
8/// A XID is a unique 32-byte identifier for a subject entity (person, organization, device, or any other entity).
9/// XIDs have the following characteristics:
10///
11/// - They're cryptographically tied to a public key at inception (the "inception key")
12/// - They remain stable throughout their lifecycle even as their keys and permissions change
13/// - They can be extended to XID documents containing keys, endpoints, permissions, and delegation info
14/// - They support key rotation and multiple verification schemes
15/// - They allow for delegation of specific permissions to other entities
16/// - They can include resolution methods to locate and verify the XID document
17/// 
18/// A XID is created by taking the SHA-256 hash of the CBOR encoding of a public signing key.
19/// This ensures the XID is cryptographically tied to the key.
20///
21/// As defined in [BCR-2024-010](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2024-010-xid.md).
22#[derive(Clone, Copy, Eq, PartialEq, Hash)]
23pub struct XID([u8; Self::XID_SIZE]);
24
25impl XID {
26    pub const XID_SIZE: usize = 32;
27
28    /// Create a new XID from data.
29    pub fn from_data(data: [u8; Self::XID_SIZE]) -> Self {
30        Self(data)
31    }
32
33    /// Create a new XID from data.
34    ///
35    /// Returns `None` if the data is not the correct length.
36    pub fn from_data_ref(data: impl AsRef<[u8]>) -> Result<Self> {
37        let data = data.as_ref();
38        if data.len() != Self::XID_SIZE {
39            bail!("Invalid XID size");
40        }
41        let mut arr = [0u8; Self::XID_SIZE];
42        arr.copy_from_slice(data.as_ref());
43        Ok(Self::from_data(arr))
44    }
45
46    /// Return the data of the XID.
47    pub fn data(&self) -> &[u8; Self::XID_SIZE] {
48        self.into()
49    }
50
51    /// Create a new XID from the given public key (the "genesis key").
52    ///
53    /// The XID is the SHA-256 digest of the CBOR encoding of the public key.
54    pub fn new(genesis_key: impl AsRef<SigningPublicKey>) -> Self {
55        let key_cbor_data = genesis_key.as_ref().to_cbor_data();
56        let digest = Digest::from_image(key_cbor_data);
57        Self::from_data(*digest.data())
58    }
59
60    /// Validate the XID against the given public key.
61    pub fn validate(&self, key: &SigningPublicKey) -> bool {
62        let key_data = key.to_cbor_data();
63        let digest = Digest::from_image(key_data);
64        *digest.data() == self.0
65    }
66
67    /// Create a new XID from the given hexadecimal string.
68    ///
69    /// # Panics
70    /// Panics if the string is not exactly 64 hexadecimal digits.
71    pub fn from_hex(hex: impl AsRef<str>) -> Self {
72        Self::from_data_ref(hex::decode(hex.as_ref()).unwrap()).unwrap()
73    }
74
75    /// The data as a hexadecimal string.
76    pub fn to_hex(&self) -> String {
77        hex::encode(self.0)
78    }
79
80    /// The first four bytes of the XID as a hexadecimal string.
81    pub fn short_description(&self) -> String {
82        self.ref_hex_short()
83    }
84
85    /// The first four bytes of the XID as upper-case ByteWords.
86    pub fn bytewords_identifier(&self, prefix: bool) -> String {
87        self.ref_bytewords(if prefix {Some("🅧")} else {None})
88    }
89
90    /// The first four bytes of the XID as Bytemoji.
91    pub fn bytemoji_identifier(&self, prefix: bool) -> String {
92        self.ref_bytemoji(if prefix {Some("🅧")} else {None})
93    }
94}
95
96/// A provider trait for obtaining XIDs from various objects.
97pub trait XIDProvider {
98    /// Returns the XID for this object.
99    fn xid(&self) -> XID;
100}
101
102/// Implements XIDProvider for XID to return itself.
103impl XIDProvider for XID {
104    fn xid(&self) -> XID {
105        *self
106    }
107}
108
109/// Implements XIDProvider for SigningPublicKey to generate an XID from the key.
110impl XIDProvider for SigningPublicKey {
111    fn xid(&self) -> XID {
112        XID::new(self)
113    }
114}
115
116/// Implements ReferenceProvider for XID to generate a Reference from the XID.
117impl ReferenceProvider for XID {
118    fn reference(&self) -> Reference {
119        Reference::from_data(*self.data())
120    }
121}
122
123/// Implements conversion from a XID reference to a byte array reference.
124impl<'a> From<&'a XID> for &'a [u8; XID::XID_SIZE] {
125    fn from(value: &'a XID) -> Self {
126        &value.0
127    }
128}
129
130/// Implements conversion from a XID reference to a byte slice reference.
131impl<'a> From<&'a XID> for &'a [u8] {
132    fn from(value: &'a XID) -> Self {
133        &value.0
134    }
135}
136
137/// Implements AsRef<[u8]> to allow XID to be treated as a byte slice.
138impl AsRef<[u8]> for XID {
139    fn as_ref(&self) -> &[u8] {
140        &self.0
141    }
142}
143
144/// Implements PartialOrd to allow XIDs to be compared and partially ordered.
145impl std::cmp::PartialOrd for XID {
146    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
147        Some(self.0.cmp(&other.0))
148    }
149}
150
151/// Implements Ord to allow XIDs to be fully ordered.
152impl std::cmp::Ord for XID {
153    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
154        self.0.cmp(&other.0)
155    }
156}
157
158/// Implements Debug formatting for XID showing the full hex representation.
159impl std::fmt::Debug for XID {
160    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
161        write!(f, "XID({})", hex::encode(self.0))
162    }
163}
164
165/// Implements Display formatting for XID showing a shortened hex representation.
166impl std::fmt::Display for XID {
167    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
168        write!(f, "XID({})", self.short_description())
169    }
170}
171
172/// Implements CBORTagged trait to provide CBOR tag information for XID.
173impl CBORTagged for XID {
174    fn cbor_tags() -> Vec<Tag> {
175        tags_for_values(&[tags::TAG_XID])
176    }
177}
178
179/// Implements conversion from XID to CBOR for serialization.
180impl From<XID> for CBOR {
181    fn from(value: XID) -> Self {
182        value.tagged_cbor()
183    }
184}
185
186/// Implements conversion from SigningPublicKey reference to XID.
187impl From<&SigningPublicKey> for XID {
188    fn from(key: &SigningPublicKey) -> Self {
189        Self::new(key)
190    }
191}
192
193/// Implements conversion from SigningPrivateKey reference to XID via the public key.
194impl TryFrom<&SigningPrivateKey> for XID {
195    type Error = Error;
196
197    fn try_from(key: &SigningPrivateKey) -> Result<Self, Self::Error> {
198        Ok(Self::new(&key.public_key()?))
199    }
200}
201
202/// Implements conversion from PublicKeys reference to XID via the signing public key.
203impl From<&PublicKeys> for XID {
204    fn from(key: &PublicKeys) -> Self {
205        Self::new(key.signing_public_key())
206    }
207}
208
209/// Implements conversion from PrivateKeyBase reference to XID via the Schnorr signing key.
210impl From<&PrivateKeyBase> for XID {
211    fn from(key: &PrivateKeyBase) -> Self {
212        Self::new(key.schnorr_signing_private_key().public_key().unwrap())
213    }
214}
215
216/// Implements CBORTaggedEncodable to provide CBOR encoding functionality for XID.
217impl CBORTaggedEncodable for XID {
218    fn untagged_cbor(&self) -> CBOR {
219        CBOR::to_byte_string(self.0)
220    }
221}
222
223/// Implements conversion from CBOR to XID for deserialization.
224impl TryFrom<CBOR> for XID {
225    type Error = Error;
226
227    fn try_from(cbor: CBOR) -> Result<Self, Self::Error> {
228        Self::from_tagged_cbor(cbor)
229    }
230}
231
232/// Implements CBORTaggedDecodable to provide CBOR decoding functionality for XID.
233impl CBORTaggedDecodable for XID {
234    fn from_untagged_cbor(cbor: CBOR) -> Result<Self> {
235        let data = CBOR::try_into_byte_string(cbor)?;
236        Self::from_data_ref(data)
237    }
238}
239
240/// Implements conversion from XID to `Vec<u8>` to allow access to the raw bytes.
241impl From<XID> for Vec<u8> {
242    fn from(xid: XID) -> Self {
243        xid.0.to_vec()
244    }
245}
246
247#[cfg(test)]
248mod tests {
249    use crate::{ECPrivateKey, SigningPrivateKey};
250
251    use super::*;
252    use bc_ur::prelude::*;
253    use hex_literal::hex;
254    use indoc::indoc;
255
256    #[test]
257    fn test_xid() {
258        crate::register_tags();
259        let xid = XID::from_data_ref(hex!("de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037")).unwrap();
260        assert_eq!(xid.to_hex(), "de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037");
261        assert_eq!(xid.short_description(), "de285368");
262        assert_eq!(xid.data(), &hex!("de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037"));
263        assert_eq!(format!("{:?}", xid), "XID(de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037)");
264        assert_eq!(format!("{}", xid), "XID(de285368)");
265
266        let xid_string = xid.ur_string();
267        assert_eq!(xid_string, "ur:xid/hdcxuedeguisgevwhdaxnbluenutlbglhfiygamsamadmojkdydtneteeowffhwprtemcaatledk");
268        assert_eq!(XID::from_ur_string(xid_string).unwrap(), xid);
269        assert_eq!(xid.bytewords_identifier(true), "🅧 URGE DICE GURU IRIS");
270        assert_eq!(xid.bytemoji_identifier(true), "🅧 🐻 😻 🍞 💐");
271    }
272
273    #[test]
274    fn test_xid_from_key() {
275        crate::register_tags();
276        let private_key = SigningPrivateKey::new_schnorr(
277            ECPrivateKey::from_data(
278                hex!("322b5c1dd5a17c3481c2297990c85c232ed3c17b52ce9905c6ec5193ad132c36")
279            )
280        );
281        let public_key = private_key.public_key().unwrap();
282
283        let key_cbor = public_key.to_cbor();
284        assert_eq!(key_cbor.diagnostic(), indoc! {"
285            40022(
286                h'e8251dc3a17e0f2c07865ed191139ecbcddcbdd070ec1ff65df5148c7ef4005a'
287            )
288        "}.trim());
289        assert_eq!(key_cbor.hex_annotated(), indoc! {"
290            d9 9c56                                 # tag(40022) signing-public-key
291                5820                                # bytes(32)
292                    e8251dc3a17e0f2c07865ed191139ecbcddcbdd070ec1ff65df5148c7ef4005a
293        "}.trim());
294        let key_cbor_data = key_cbor.to_cbor_data();
295        assert_eq!(key_cbor_data, hex!("d99c565820e8251dc3a17e0f2c07865ed191139ecbcddcbdd070ec1ff65df5148c7ef4005a"));
296        let digest = Digest::from_image(&key_cbor_data);
297        assert_eq!(digest.data(), &hex!("d40e0602674df1b732f5e025d04c45f2e74ed1652c5ae1740f6a5502dbbdcd47"));
298
299        let xid = XID::new(&public_key);
300        assert_eq!(format!("{:?}", xid), "XID(d40e0602674df1b732f5e025d04c45f2e74ed1652c5ae1740f6a5502dbbdcd47)");
301        xid.validate(&public_key);
302
303        assert_eq!(format!("{}", xid), "XID(d40e0602)");
304        let reference = xid.reference();
305        assert_eq!(format!("{reference}"), "Reference(d40e0602)");
306
307        assert_eq!(reference.bytewords_identifier(None), "TINY BETA ATOM ALSO");
308        assert_eq!(reference.bytemoji_identifier(None), "🧦 🤨 😎 😆");
309
310        assert_eq!(digest.data(), xid.data());
311    }
312}
bc_components/id/xid.rs

bc_components/id/
xid.rs
