Move verification functionality from DocumentVerifier to CoreDocument

[olivereanderson]

Description of change

Removes DocumentVerifier and moves its verification methods verify, do_verify to CoreDocument essentially as:

pub fn verify_data<X>(&self, data: &X, options: &VerifierOptions) -> Result<()>;
pub fn do_verify<X>(method: &VerificationMethod<U>, data: &X) -> Result<()>; 

Additionally IotaDocument::verify_data now borrows VerifierOptions instead of consuming it. More precisely the new function signature is now:

pub fn verify_data<X>(&self, data: &X, options: &VerifierOptions) -> Result<()>; 

in place of

pub fn verify_data<X>(&self, data: &X, options: VerifierOptions) -> Result<()>; 

This is arguably more conceptual as it should be enough to "read" the verifier options in order to verify data and it allows for optimizations such as mutating the options in place between verifications.

Type of change

Add an x to the boxes that are relevant to your changes.

• Bug fix (a non-breaking change which fixes an issue)
• Enhancement (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Fix

How the change has been tested

cargo test and npm run build && npm run build:examples && npm run test:node && npm run test:browser run locally.

Change checklist

Add an x to the boxes that are relevant to your changes.

• I have followed the contribution guidelines for this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[cycraig]

Thanks for the changes. I'm still hesitant to approve because while the previous approach had the disadvantage of unexpected Cow/cloning behaviour internally, removing the mutability of the options from DocumentVerifier essentially makes it useless (since its purpose was mainly ergonomics using the builder pattern), unlike DocumentSigner which still retains some options separate from SigantureOptions.

If we were to proceed with the PR in this state (with VerifierOptions as a parameter of verify()) I would advocate we remove DocumentVerifier completely and replace it with a Verifier/SignatureVerifier trait implemented on CoreDocument, IotaDocument, and maybe Account.

Apologies for being difficult and I know I'm the one that requested the latest changes to your initial approach; I just want to minimise breaking API changes, since it looks like if this is merged as-is we might want/need to change it again later.

[PhilippGackstatter]

I really like the simplification of passing the options as a parameter as opposed to adding a second lifetime to DocumentVerifier and using Cow.

[olivereanderson]

I would advocate we remove DocumentVerifier completely and replace it with a Verifier/SignatureVerifier trait implemented on CoreDocument, IotaDocument, and maybe Account.

Interesting idea. How would such a trait fit with the traits we already have such as: https://github.com/iotaledger/identity.rs/blob/dev/identity-core/src/crypto/signature/traits/core.rs#L82?

Also which functions/methods would/might impose the new Verifier/SignatureVerifier trait as trait bounds?

[cycraig]

How would such a trait fit with the traits we already have such as: https://github.com/iotaledger/identity.rs/blob/dev/identity-core/src/crypto/signature/traits/core.rs#L82?
Also which functions/methods would/might impose the new Verifier/SignatureVerifier trait as trait bounds?

I imagine the DocumentVerifier trait to be user-facing, so it just exposes e.g. verify_data/verify_document since we don't have internal uses of the DocumentVerifier struct other than in tests and examples as far as I know. The other option would be just to leave them as associated methods on CoreDocument, IotaDocument and Account. The reason I initially suggested a trait was in case a developer wanted to take e.g. dyn DocumentVerifier somewhere but in reality I think they would just pass the document around or an Arc of the Account for instance, so it might not be useful.

I'm in favour of just leaving it as an associated method then, any other options or opinions? Leaving everything as-is is also an option.

[PhilippGackstatter]

What about moving the method and having it as CoreDocument::verify_data, then also exposing it as IotaDocument::verify_data? In theory the trait sounds nice, but if the only advantage of it is to have account.verify_data(...) instead of account.document().verify_data(...) that seems like too small of a reason to introduce a trait. Unless we expect to also implement it on more types in the future?

[cycraig]

[...] that seems like too small of a reason to introduce a trait. Unless we expect to also implement it on more types in the future?

A trait might be useful if we need interoperability between future DID method documents, but that assumes they will be implemented in different structs.

What about moving the method and having it as CoreDocument::verify_data, then also exposing it as IotaDocument::verify_data [...]

It looks like we're all leaning towards this option.

[cycraig]

Looks good to me, thanks for all the changes. I like that WasmDocument::verify_data borrows WasmVerifierOptions now, it's always going to be confusing to Javscript developers when our API consumes an object and nulls its pointer.