Refactor

[timothee-haudebourg]

This PR aims at refactoring ssi to make better use of Rust traits.

• Abstract the credential/presentation types (using traits) to accept user defined types.
• Unify verifiable claim types (JWT, W3C VC). Have a uniform Verifable<Claims> type family for verifiable claims, independent of the underlying implementation.
• ~TreeLDR integration~ (although it was one of the main motivation for this refactor, integration with TreeLDR will be de facto possible using the new abstractions. ssi will not depend on TreeLDR).

This is a work in early progress.

Status

Most of the work is completed. There are still some DID methods that needs to be reintroduced. Most of the remaining work is testing everything (and that's a lot).

Below are all the parts that needs to be added or changed in ssi:

• [x] Generate VC datamodel with TreeLDR
• [x] JWT VC (new dedicated ssi-vc-jwt library)
  • [x] JWT+LD decoding
  • [x] verification
  • [x] JWT+LD signing
  • [x] encoding
• [x] Add an independent library for Verification Methods (ssi-verification-methods library), with VMs clearly defined.
  • [x] API design
  • [x] Verification methods implementation
  • [x] EcdsaSecp256k1RecoveryMethod2020
  • [x] EcdsaSecp256k1VerificationKey2019
  • [x] EcdsaSecp256r1VerificationKey2019
  • [x] Ed25519VerificationKey2018
  • [x] Ed25519VerificationKey2020
  • [x] JsonWebKey2020
  • [x] Multikey
  • [x] RsaVerificationKey2018
  • [x] Ed25519PublicKeyBLAKE2BDigestSize20Base58CheckEncoded2021
  • [x] P256PublicKeyBLAKE2BDigestSize20Base58CheckEncoded2021
  • [x] TezosMethod2021
  • [x] AleoMethod2021
  • [x] BlockchainVerificationMethod2021
  • [x] Eip712Method2021
• [x] DIDs (ssi-dids library)
  • [x] Improve the DIDResolver trait
  • [x] Use the ssi-verification-methods library
  • [x] Reintroduce DID methods
  • [x] tz (Tezos)
  • [x] jwk
  • [x] pkh (https://github.com/spruceid/ssi/pull/539)
  • [x] key (https://github.com/spruceid/ssi/pull/540)
  • [x] web (https://github.com/spruceid/ssi/pull/541)
  • [x] ethr (https://github.com/spruceid/ssi/pull/542)
  • [x] ion (https://github.com/spruceid/ssi/pull/543)
  • [x] ~sol~ (deprecate)
  • [x] ~onion~ (deprecate)
  • [x] ~webkey~ (deprecate)
  • [ ] test (test suite? not sure if required)
• [x] Data Integrity (in the ssi-vc-ldp library)
  • [x] VC decoding from JSON-LD
  • [x] VC encoding
  • [x] CryptographicSuite trait design
  • [x] Cryptosuites implementations
  • [x] EcdsaSecp256k1Signature2019
  • [x] EcdsaSecp256r1Signature2019
  • [x] Ed25519Signature2018
  • [x] Ed25519Signature2020
  • [x] eddsa-2022
  • [x] EthereumEip712Signature2021
  • [x] JsonWebSignature2020
  • [x] RsaSignature2018
  • [x] EcdsaSecp256k1RecoverySignature2020
  • [x] AleoSignature2021
  • [x] Eip712Signature2021
  • [x] EthereumPersonalSignature2021
  • [x] SolanaSignature2021
  • [x] Any VC API
• [x] Testing

[timothee-haudebourg]

This is finally happening! Everything compiles, every test, doc test, example can run fine, no warnings, no broken doc links. I've fixed, tested and documented features. Now it is not perfect, there are a lot of ugly things living in ssi_jwk, ssi_jws for instance, but I'll consider it out of scope. Other issues are directly related to the refactor:

• Before, the various verification functions would return a VerificationResult containing warnings and errors. There was no distinction between verification failure (the signature/proof is not valid), and verification errors (we could not verify the signature for some reason, it may or may not be valid). I tried to do the distinction using a more fine grain result type Result<ProofValidity, VerificationError> where ProofValidity captures the validity of the proof (it may be invalid) and VerificationError for when the verification process failed. I think its a good idea overall but
  • I haven't done it right everywhere. Some errors that should raise ProofValidity::Invalid instead throw a VerificationError
  • Ideally ProofValidity::Invalid would also gives the reason why the verification failed, but for now there is none
  • Warnings are lost, but we could add them to the ProofValidity::Valid variant
  • I've added a Validate trait to validate claims independently of the proof/signature. It can be used to check the expiration date of a credential for instance. I think this trait could be improved so we can pass an "environment" to the validation function. This is required for some advanced validation checks, such as validating the aud (audience) claim of a JWT against the application domain. To do it correctly the validation function needs to know the application domain, which could be passed through this "environment".

These are points we can discuss but I think overall the refactor is ready to be reviewed.

[itsbalamurali]

@sbihel any ETA on merging this?

[timothee-haudebourg]

rustfmt is failing because the crates/multicodec/src/table.rs file is not found. This file is generated by the build.rs script of ssi_multicodec from the crates/multicodec/src/table.csv file. I'll try to find a way to run the build script before rustfmt.

[sbihel]

For context I'm in the process of rewriting the VC API in DIDKit https://github.com/spruceid/didkit/pull/384, and I'm currently stuck with lifetime bound issues, but if you could have a look to see if I'm doing anything wrong that would be great.

[ianhamilton87]

@timothee-haudebourg @clehner @sbihel - any ETA on the completion of this PR? Reason I ask is because merging this PR is blocking one of mine: https://github.com/spruceid/ssi/pull/545

Thanks.

[sbihel]

There's is no ETA but we're hoping to get it merged and published within two months.

[timothee-haudebourg]

I've made some changes to follow the reviews. With a few days away from ssi I had some fresh eyes, so I've fixed some other issues that were necessary in my opinion:

• Normalized all the claim signature/verification error types. There is now one SignatureError and one ProofValidationError used across all the sign/verify functions, whatever the claim type (Data-Integrity, JWS, JWT, etc.).
• Provided an environment to the claim validation method Validate::validate. This can be used to deterministically set the time of verification for instance, used to check the expiration/issuance date claims. The function now returns a result, giving an insight on why the validation failed (if the claim expired for instance).
• Normalized the verification/signature API across claim types. Now besides Data-Integrity claims, the same verification pipeline is (can be) used to verify JWS, JWT, etc. I've added some example in the crate-level documentation of ssi-jws and ssi-jwt. I've also added documentation of this "verification pipeline" here: crates/claims/core/src/verification/mod.rs (maybe not the best place since this won't appear in the generated doc).
• Changed the way we encode JWT registered claims. It is now very similar to cose-rs, which we will probably use in the future to verify CBOR-encoded claims. It is also more memory efficient.
• Completely separated JWS/JWT from the ssi-verification-methods crate, just so it stays reasonable to use the ssi-jws/ss-jwt crates alone, without the rest of ssi.

[sbihel]

There are still some error types that are missing Send and would probably benefit from moving to a String or anyhow::Error -- at least MessageSignatureError. Have you tried compiling the VC API in DIDKit in https://github.com/spruceid/didkit/pull/384?

[jceb]

🎉