feat(rust/signed-doc): example CLI builds signed documents

saibatizoku · saibatizoku · commit 14d500a8c165 · 2025-01-17T16:47:05.000-06:00
diff --git a/rust/signed_doc/examples/mk_signed_doc.rs b/rust/signed_doc/examples/mk_signed_doc.rs
@@ -8,7 +8,9 @@ use std::{
     path::PathBuf,
 };
 
-use catalyst_signed_doc::{CatalystSignedDocument, Decode, Decoder, KidUri, Metadata};
+use catalyst_signed_doc::{
+    Builder, CatalystSignedDocument, Content, Decode, Decoder, KidUri, Metadata, Signatures,
+};
 use clap::Parser;
 use coset::{CborSerializable, Header};
 use ed25519_dalek::{ed25519::signature::Signer, pkcs8::DecodePrivateKey};
@@ -60,19 +62,39 @@ impl Cli {
         match self {
             Self::Build {
                 doc,
-                schema,
+                schema: _,
                 output,
                 meta,
             } => {
-                let doc_schema = load_schema_from_file(&schema)?;
-                let json_doc = load_json_from_file(&doc)?;
-                let json_meta = &load_json_from_file(&meta)
+                // Load Metadata from JSON file
+                let metadata: Metadata = load_json_from_file(&meta)
                     .map_err(|e| anyhow::anyhow!("Failed to load metadata from file: {e}"))?;
-                println!("{json_meta}");
-                validate_json(&json_doc, &doc_schema)?;
-                let compressed_doc = brotli_compress_json(&json_doc)?;
-                let empty_cose_sign = build_empty_cose_doc(compressed_doc, json_meta)?;
-                store_cose_file(empty_cose_sign, &output)?;
+                println!("{metadata}");
+                // Load Document from JSON file
+                let json_doc: serde_json::Value = load_json_from_file(&doc)?;
+                // Possibly encode if Metadata has an encoding set.
+                let payload_bytes = serde_json::to_vec(&json_doc)?;
+                let payload = match metadata.content_encoding() {
+                    Some(encoding) => encoding.encode(&payload_bytes)?,
+                    None => payload_bytes,
+                };
+                let content = Content::new(
+                    payload,
+                    metadata.content_type(),
+                    metadata.content_encoding(),
+                )?;
+                // Start with no signatures.
+                let signatures = Signatures::try_from(&Vec::new())?;
+                let signed_doc = Builder::new()
+                    .content(content)
+                    .metadata(metadata)
+                    .signatures(signatures)
+                    .build()?;
+                let mut bytes: Vec<u8> = Vec::new();
+                minicbor::encode(signed_doc, &mut bytes)
+                    .map_err(|e| anyhow::anyhow!("Failed to encode document: {e}"))?;
+
+                write_bytes_to_file(&bytes, &output)?;
             },
             Self::Sign { sk, doc, kid } => {
                 let sk = load_secret_key_from_file(&sk)
@@ -106,14 +128,14 @@ fn decode_signed_doc(cose_bytes: &[u8]) {
     );
     match CatalystSignedDocument::decode(&mut Decoder::new(cose_bytes), &mut ()) {
         Ok(cat_signed_doc) => {
-            println!("This is a valid Catalyst Signed Document.");
+            println!("This is a valid Catalyst Document.");
             println!("{cat_signed_doc}");
         },
-        Err(e) => eprintln!("Invalid Catalyst Signed Document, err: {e}"),
+        Err(e) => eprintln!("Invalid Catalyst Document, err: {e}"),
     }
 }
 
-fn load_schema_from_file(schema_path: &PathBuf) -> anyhow::Result<jsonschema::JSONSchema> {
+fn _load_schema_from_file(schema_path: &PathBuf) -> anyhow::Result<jsonschema::JSONSchema> {
     let schema_file = File::open(schema_path)?;
     let schema_json = serde_json::from_reader(schema_file)?;
     let schema = jsonschema::JSONSchema::options()
@@ -130,7 +152,7 @@ where T: for<'de> serde::Deserialize<'de> {
     Ok(json)
 }
 
-fn validate_json(doc: &serde_json::Value, schema: &jsonschema::JSONSchema) -> anyhow::Result<()> {
+fn _validate_json(doc: &serde_json::Value, schema: &jsonschema::JSONSchema) -> anyhow::Result<()> {
     schema.validate(doc).map_err(|err| {
         let mut validation_error = String::new();
         for e in err {
@@ -141,15 +163,15 @@ fn validate_json(doc: &serde_json::Value, schema: &jsonschema::JSONSchema) -> an
     Ok(())
 }
 
-fn brotli_compress_json(doc: &serde_json::Value) -> anyhow::Result<Vec<u8>> {
+fn _brotli_compress_json(doc: &serde_json::Value) -> anyhow::Result<Vec<u8>> {
     let brotli_params = brotli::enc::BrotliEncoderParams::default();
-    let doc_bytes = serde_json::to_vec(&doc)?;
+    let doc_bytes = serde_json::to_vec(doc)?;
     let mut buf = Vec::new();
     brotli::BrotliCompress(&mut doc_bytes.as_slice(), &mut buf, &brotli_params)?;
     Ok(buf)
 }
 
-fn build_empty_cose_doc(doc_bytes: Vec<u8>, meta: &Metadata) -> anyhow::Result<coset::CoseSign> {
+fn _build_empty_cose_doc(doc_bytes: Vec<u8>, meta: &Metadata) -> anyhow::Result<coset::CoseSign> {
     let protected_header = Header::try_from(meta)?;
     Ok(coset::CoseSignBuilder::new()
         .protected(protected_header)
@@ -158,20 +180,28 @@ fn build_empty_cose_doc(doc_bytes: Vec<u8>, meta: &Metadata) -> anyhow::Result<c
 }
 
 fn load_cose_from_file(cose_path: &PathBuf) -> anyhow::Result<coset::CoseSign> {
-    let mut cose_file = File::open(cose_path)?;
-    let mut cose_file_bytes = Vec::new();
-    cose_file.read_to_end(&mut cose_file_bytes)?;
+    let cose_file_bytes = read_bytes_from_file(cose_path)?;
     let cose = coset::CoseSign::from_slice(&cose_file_bytes).map_err(|e| anyhow::anyhow!("{e}"))?;
     Ok(cose)
 }
 
+fn read_bytes_from_file(path: &PathBuf) -> anyhow::Result<Vec<u8>> {
+    let mut file_bytes = Vec::new();
+    File::open(path)?.read_to_end(&mut file_bytes)?;
+    Ok(file_bytes)
+}
+
+fn write_bytes_to_file(bytes: &[u8], output: &PathBuf) -> anyhow::Result<()> {
+    File::create(output)?
+        .write_all(bytes)
+        .map_err(|e| anyhow::anyhow!("Failed to write to file {output:?}: {e}"))
+}
+
 fn store_cose_file(cose: coset::CoseSign, output: &PathBuf) -> anyhow::Result<()> {
-    let mut cose_file = File::create(output)?;
     let cose_bytes = cose
         .to_vec()
         .map_err(|e| anyhow::anyhow!("Failed to Store COSE SIGN: {e}"))?;
-    cose_file.write_all(&cose_bytes)?;
-    Ok(())
+    write_bytes_to_file(&cose_bytes, output)
 }
 
 fn load_secret_key_from_file(sk_path: &PathBuf) -> anyhow::Result<ed25519_dalek::SigningKey> {
diff --git a/rust/signed_doc/src/builder.rs b/rust/signed_doc/src/builder.rs
@@ -3,7 +3,6 @@ use crate::{CatalystSignedDocument, Content, InnerCatalystSignedDocument, Metada
 
 /// Catalyst Signed Document Builder.
 #[derive(Debug, Default)]
-#[allow(dead_code)]
 pub struct Builder {
     /// Document Metadata
     metadata: Option<Metadata>,
@@ -45,18 +44,16 @@ impl Builder {
     ///
     /// ## Errors
     ///
-    /// Returns
+    /// Fails if any of the fields are missing.
     pub fn build(self) -> anyhow::Result<CatalystSignedDocument> {
         match (self.metadata, self.content, self.signatures) {
             (Some(metadata), Some(content), Some(signatures)) => {
-                Ok(CatalystSignedDocument {
-                    inner: InnerCatalystSignedDocument {
-                        metadata,
-                        content,
-                        signatures,
-                    }
-                    .into(),
-                })
+                Ok(InnerCatalystSignedDocument {
+                    metadata,
+                    content,
+                    signatures,
+                }
+                .into())
             },
             _ => Err(anyhow::anyhow!("Failed to build Catalyst Signed Document")),
         }
diff --git a/rust/signed_doc/src/content.rs b/rust/signed_doc/src/content.rs
@@ -10,6 +10,9 @@ impl Content {
     /// Creates a new `Content` value,
     /// verifies a Document's content, that it is correctly encoded and it corresponds and
     /// parsed to the specified type
+    ///
+    /// # Errors
+    /// Returns an error if content is not correctly encoded
     pub fn new(
         mut content: Vec<u8>, content_type: ContentType, encoding: Option<ContentEncoding>,
     ) -> anyhow::Result<Self> {
@@ -35,7 +38,20 @@ impl Content {
     }
 
     /// Return content bytes
+    #[must_use]
     pub fn bytes(&self) -> &[u8] {
         self.0.as_slice()
     }
+
+    /// Return content byte size
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.0.len()
+    }
+
+    /// Return `true` if content is empty
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
 }
diff --git a/rust/signed_doc/src/lib.rs b/rust/signed_doc/src/lib.rs
@@ -14,14 +14,14 @@ use std::{
 
 use anyhow::anyhow;
 pub use builder::Builder;
-use content::Content;
+pub use content::Content;
 use coset::{CborSerializable, Header};
 pub use metadata::{AdditionalFields, DocumentRef, Metadata, UuidV4, UuidV7};
 pub use minicbor::{decode, encode, Decode, Decoder, Encode};
-pub use signature::KidUri;
-use signature::Signatures;
+pub use signature::{KidUri, Signatures};
 
 /// Inner type that holds the Catalyst Signed Document with parsing errors.
+#[derive(Debug, Clone)]
 struct InnerCatalystSignedDocument {
     /// Document Metadata
     metadata: Metadata,
@@ -37,17 +37,30 @@ struct InnerCatalystSignedDocument {
 /// non-optional.
 pub struct CatalystSignedDocument {
     /// Catalyst Signed Document metadata, raw doc, with content errors.
-    pub(crate) inner: Arc<InnerCatalystSignedDocument>,
+    inner: Arc<InnerCatalystSignedDocument>,
 }
 
 impl Display for CatalystSignedDocument {
     fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
         writeln!(f, "{}", self.inner.metadata)?;
-        writeln!(f, "Signature Information [")?;
-        for kid in &self.inner.signatures.kids() {
-            writeln!(f, "  {kid}")?;
+        writeln!(f, "Payload Size: {} bytes", self.inner.content.len())?;
+        writeln!(f, "Signature Information")?;
+        if self.inner.signatures.0.is_empty() {
+            writeln!(f, "  This document is unsigned.")?;
+        } else {
+            for kid in &self.inner.signatures.kids() {
+                writeln!(f, "  Signature Key ID: {kid}")?;
+            }
+        }
+        Ok(())
+    }
+}
+
+impl From<InnerCatalystSignedDocument> for CatalystSignedDocument {
+    fn from(inner: InnerCatalystSignedDocument) -> Self {
+        Self {
+            inner: inner.into(),
         }
-        writeln!(f, "]\n")
     }
 }
 
@@ -154,22 +167,28 @@ impl Decode<'_, ()> for CatalystSignedDocument {
 
 impl Encode<()> for CatalystSignedDocument {
     fn encode<W: minicbor::encode::Write>(
-        &self, e: &mut encode::Encoder<W>, ctx: &mut (),
+        &self, e: &mut encode::Encoder<W>, _ctx: &mut (),
     ) -> Result<(), encode::Error<W::Error>> {
         let protected_header = Header::try_from(&self.inner.metadata).map_err(|e| {
             minicbor::encode::Error::message(format!("Failed to encode Document Metadata: {e}"))
         })?;
+
         let mut builder = coset::CoseSignBuilder::new()
             .protected(protected_header)
             .payload(self.inner.content.bytes().to_vec());
+
         for signature in self.signatures().signatures() {
             builder = builder.add_signature(signature);
         }
+
         let cose_sign = builder.build();
+
         let cose_bytes = cose_sign.to_vec().map_err(|e| {
             minicbor::encode::Error::message(format!("Failed to encode COSE Sign document: {e}"))
         })?;
-        cose_bytes.encode(e, ctx)?;
-        Ok(())
+
+        e.writer_mut()
+            .write_all(&cose_bytes)
+            .map_err(|_| minicbor::encode::Error::message("Failed to encode to CBOR"))
     }
 }
diff --git a/rust/signed_doc/src/metadata/additional_fields.rs b/rust/signed_doc/src/metadata/additional_fields.rs
@@ -8,7 +8,7 @@ use super::{cose_protected_header_find, decode_cbor_uuid, encode_cbor_uuid, Docu
 /// Additional Metadata Fields.
 ///
 /// These values are extracted from the COSE Sign protected header labels.
-#[derive(Default, Debug, serde::Serialize, serde::Deserialize)]
+#[derive(Clone, Default, Debug, serde::Serialize, serde::Deserialize)]
 pub struct AdditionalFields {
     /// Reference to the latest document.
     #[serde(rename = "ref")]
diff --git a/rust/signed_doc/src/metadata/content_encoding.rs b/rust/signed_doc/src/metadata/content_encoding.rs
@@ -14,6 +14,31 @@ pub enum ContentEncoding {
     Brotli,
 }
 
+impl ContentEncoding {
+    /// Compress a Brotli payload
+    pub fn encode(self, mut payload: &[u8]) -> anyhow::Result<Vec<u8>> {
+        match self {
+            Self::Brotli => {
+                let brotli_params = brotli::enc::BrotliEncoderParams::default();
+                let mut buf = Vec::new();
+                brotli::BrotliCompress(&mut payload, &mut buf, &brotli_params)?;
+                Ok(buf)
+            },
+        }
+    }
+
+    /// Decompress a Brotli payload
+    pub fn decode(self, mut payload: &[u8]) -> anyhow::Result<Vec<u8>> {
+        match self {
+            Self::Brotli => {
+                let mut buf = Vec::new();
+                brotli::BrotliDecompress(&mut payload, &mut buf)?;
+                Ok(buf)
+            },
+        }
+    }
+}
+
 impl Display for ContentEncoding {
     fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
         match self {
@@ -53,16 +78,3 @@ impl TryFrom<&coset::cbor::Value> for ContentEncoding {
         }
     }
 }
-
-impl ContentEncoding {
-    /// Decompress a Brotli payload
-    pub fn decode(self, mut payload: &[u8]) -> anyhow::Result<Vec<u8>> {
-        match self {
-            Self::Brotli => {
-                let mut buf = Vec::new();
-                brotli::BrotliDecompress(&mut payload, &mut buf)?;
-                Ok(buf)
-            },
-        }
-    }
-}
diff --git a/rust/signed_doc/src/metadata/mod.rs b/rust/signed_doc/src/metadata/mod.rs
@@ -26,7 +26,7 @@ const CONTENT_ENCODING_KEY: &str = "Content-Encoding";
 /// Document Metadata.
 ///
 /// These values are extracted from the COSE Sign protected header.
-#[derive(Debug, serde::Deserialize)]
+#[derive(Clone, Debug, serde::Deserialize)]
 pub struct Metadata {
     /// Document Type `UUIDv4`.
     #[serde(rename = "type")]
diff --git a/rust/signed_doc/src/signature/mod.rs b/rust/signed_doc/src/signature/mod.rs
