search

bcgov / aries-oca-bundles

aries-oca-bundles
Apache License 2.0
8 stars 23 forks source link

Create a command line utility (probably Python) to calculate the SAIDs in an OCA Bundle #146

Open swcurran opened 4 days ago

swcurran commented 4 days ago

Background: The OCA Bundles that we generate and use are not fully compliant with the OCA because because we don't always maintain the digest attribute in all of the overlays. The branding credential never gets a digest, and if we manually update the OCA Bundle (vs. using the Excel), but digests don't get updated. The task is to write a command line utility that given an OCA Bundle, (re)calculates all of the digests in the bundle. An option on the command will verify (but not update) the digests in an OCA Bundle file.

An OCA digest is populated through the calculation of a SAID (Self Addressing IDentifier). A SAID is generated by hashing the content of the object (in this case, a JSON object) in a formally specified way to be used as the SAID, and then inserting the identifier into the object itself. That allows a verifier to do when they find a reference to a SAID, is to recalculate the SAID (e.g., hash the same data again in the same way) and make sure that the content has not changed. More background on SAIDs can be found here: https://kentbull.com/2024/09/22/keri-series-understanding-self-addressing-identifiers-said/ by @kentbull. For the purpose of this task, the most important part of the document is the the section on the seven steps to creating a SAID.

This task is to write a command line utility that implements (or borrows) the "seven steps" described in the blog post to generate a SAID, and then use that to process an OCA File. Given an OCA File (such as this), the steps of the process are:

  1. Iterate over the outer array. Typically with Aries OCA Bundles, we only have one OCA Bundle in the array, but assume there could be multiple. For each:
    1. Calculate the SAID for the capture_base object, and update its digest property with the SAID value.
    2. Iterate through the list of overlays, and for each:
      1. Update the value of the capture_base property with the SAID calculated for the capture_base object.
      2. Calculate the SAID for the Overlay and update its digest property with the SAID value.
    3. Find, or if not present add, a property d to the root of the OCABundle (beside capture_base) that will be a SAID, generate its value over the entire bundle and set its value to be the calculated SAID.

Add an option to verify the SAIDs of an OCA Bundle. Given an OCA Bundle, iterate through the Bundle and make sure that all of the SAIDs are accurate. Allow for the OCA Bundle level d SAID to NOT be present -- don't error if it is missing.

swcurran commented 4 days ago

Once you have something sort of working, we’ll find test cases for you to try. Anything produced from processing an OCA Bundle Excel file should have the right SAIDs, and so is a valid test case for you. For example, our bundles should have the right digests in the capture base and core bundles.