Polish identity_document (#1198)

* Remove outdated & wontfix TODOs, remove leftovers

* Remove unused document error variants

* Add error documentation

identity_document/src/document/core_document.rs

@@ -575,7 +575,6 @@ impl CoreDocument {
   ///
   /// If the method is referenced in the given scope, but the document does not contain the referenced verification
   /// method, then the reference will persist in the document (i.e. it is not removed).
-  // TODO: Is this the behaviour we want?
   pub fn detach_method_relationship<'query, Q>(
     &mut self,
     method_query: Q,
@@ -934,7 +933,6 @@ impl CoreDocument {
   /// - The `kid` value in the protected header must be an identifier of a verification method in this DID document.
   //
   // NOTE: This is tested in `identity_storage` and `identity_credential`.
-  // TODO: Consider including some unit tests for this method in this crate.
   pub fn verify_jws<'jws, T: JwsVerifier>(
     &self,
     jws: &'jws str,
@@ -963,7 +961,7 @@ impl CoreDocument {
       .ok_or(Error::MethodNotFound)?
       .data()
       .try_public_key_jwk()
-      .map_err(Error::InvalidKeyData)?;
+      .map_err(Error::InvalidKeyMaterial)?;
 
     validation_item
       .verify(signature_verifier, public_key)

identity_document/src/error.rs

@@ -9,60 +9,33 @@ pub type Result<T, E = Error> = ::core::result::Result<T, E>;
 /// This type represents all possible errors that can occur in the library.
 #[derive(Debug, thiserror::Error, strum::IntoStaticStr)]
 pub enum Error {
-  /// Caused by errors from the [identity_core] crate.
-  #[error("core error")]
-  CoreError(#[from] ::identity_core::Error),
-  #[error("did error")]
-  InvalidDID(#[from] identity_did::Error),
-
+  /// Caused by querying for a method that does not exist.
   #[error("verification method not found")]
   MethodNotFound,
-
   /// Caused by invalid or missing properties when constructing a [`CoreDocument`](crate::document::CoreDocument).
   #[error("invalid document property: {0}")]
   InvalidDocument(&'static str, #[source] Option<::identity_core::Error>),
   /// Caused by invalid or missing properties when constructing a [`Service`](crate::service::Service).
   #[error("invalid service property: {0}")]
   InvalidService(&'static str),
-  /// Caused by invalid or missing properties when constructing a
-  /// [`VerificationMethod`](::identity_verification::VerificationMethod).
-  #[error("invalid verification method property: {0}")]
-  InvalidMethod(&'static str),
-
+  /// Caused by an invalid or empty fragment.
   #[error("invalid or empty `id` fragment")]
   MissingIdFragment,
-  #[error("Invalid Verification Method Type")]
-  InvalidMethodType,
   /// Caused by attempting to add a verification method to a document, where a method or service with the same fragment
   /// already exists.
   #[error("unable to insert method: the id is already in use")]
   MethodInsertionError,
   /// Caused by attempting to attach or detach a relationship on an embedded method.
   #[error("unable to modify relationships on embedded methods, use insert or remove instead")]
   InvalidMethodEmbedded,
-
   /// Caused by attempting to insert a service whose id overlaps with a verification method or an already existing
   /// service.
   #[error("unable to insert service: the id is already in use")]
   InvalidServiceInsertion,
-
-  #[error("unknown method scope")]
-  UnknownMethodScope,
-  #[error("unknown method type")]
-  UnknownMethodType,
-
-  #[error("invalid key data")]
-  InvalidKeyData(#[source] identity_verification::Error),
-
-  #[error("signature verification failed: {0}")]
-  InvalidSignature(&'static str),
-
-  #[error("unable to decode base64 string: `{0}`")]
-  Base64DecodingError(String, #[source] identity_core::error::Error),
-  #[error("revocation bitmap could not be deserialized or decompressed")]
-  BitmapDecodingError(#[source] std::io::Error),
-  #[error("revocation bitmap could not be serialized or compressed")]
-  BitmapEncodingError(#[source] std::io::Error),
+  /// Caused by an attempt to use a method's key material in an incompatible context.
+  #[error("invalid key material")]
+  InvalidKeyMaterial(#[source] identity_verification::Error),
+  /// Caused by a failure to verify a JSON Web Signature.
   #[error("jws verification failed")]
   JwsVerificationError(#[source] identity_verification::jose::error::Error),
 }

identity_document/src/service/service.rs

@@ -77,9 +77,10 @@ impl Service {
     &self.id
   }
 
-  /// Sets the `Service` id.
+  /// Sets the `Service`'s id.
   ///
   /// # Errors
+  ///
   /// [`Error::MissingIdFragment`] if there is no fragment on the [`DIDUrl`].
   pub fn set_id(&mut self, id: DIDUrl) -> Result<()> {
     if id.fragment().unwrap_or_default().is_empty() {

identity_document/src/service/service_endpoint.rs

@@ -20,7 +20,6 @@ pub enum ServiceEndpoint {
   One(Url),
   Set(OrderedSet<Url>),
   Map(IndexMap<String, OrderedSet<Url>>),
-  // TODO: enforce set/map is non-empty?
 }
 
 impl From<Url> for ServiceEndpoint {

identity_document/src/utils/did_url_query.rs

@@ -89,7 +89,6 @@ impl<'query> From<DIDUrl> for DIDUrlQuery<'query> {
 
 impl<'query> From<&'query RelativeDIDUrl> for DIDUrlQuery<'query> {
   fn from(other: &'query RelativeDIDUrl) -> Self {
-    // TODO: improve RelativeDIDUrl performance - internal string segments representation
     Self(Cow::Owned(other.to_string()))
   }
 }