@did-btcr2/method 0.18.0 → 0.19.0

package/src/core/types.ts

@@ -0,0 +1,78 @@
+import { HexString } from '@did-btcr2/common';
+import { BTCR2SignedUpdate } from '@did-btcr2/cryptosuite';
+import { SMTProof } from './interfaces.js';
+
+/**
+ * {@link https://dcdpr.github.io/did-btcr2/data-structures.html#cas-announcement | CAS Announcement }
+ * a data structure that maps DIDs to BTCR2 Signed Update hashes. All BTCR2 Signed
+ * Updates (data structure) MUST be hashed with the JSON Document Hashing algorithm.
+ * The concrete representation of this data structure will be published to a CAS.
+ * @example
+ * ```json
+ * {
+ *   "did:btcr2:k1q5pa5tq86fzrl0ez32nh8e0ks4tzzkxnnmn8tdvxk04ahzt70u09dag02h0cp": "a4ayc_80_OGda4BO_1o_V0etpOqiLx1JwB5S3beHW0s",
+ *   "did:btcr2:x1qhjw6jnhwcyu5wau4x0cpwvz74c3g82c3uaehqpaf7lzfgmnwsd7spmmf54": "1HNeOiZeFu7gP1lxi5tdAwGcB9i2xR-Q2jpmbuwTqzU",
+ *   "did:btcr2:k1qgp5h79scv4sfqkzak5g6y89dsy3cq0pd2nussu2cm3zjfhn4ekwrucc4q7t7": "TgdAhWK-24tgzgXB3s_jrRa3IjCWfeAfZAt-Rym0n84"
+ * }
+ * ```
+ */
+export type CASAnnouncement = {
+  [key: string]: string
+}
+
+/**
+ * See {@link https://dcdpr.github.io/did-btcr2/terminology.html#sidecar | Sidecar }
+ * for more details about the sidecar mechanism. See {@link https://dcdpr.github.io/did-btcr2/data-structures.html#sidecar-data | Sidecar Data}
+ * for more details about the data structure.
+ */
+export type Sidecar = {
+  /**
+   * The context string "https://btcr2.dev/context/v1"
+   */
+  '@context'?: string,
+
+  /**
+   * Optional Genesis Did Document. Required when resolving did:btcr2 identifiers
+   * with `x` HRP.D
+   */
+  genesisDocument?: object;
+
+  /**
+   * Optional array of BTCR2 Signed Updates. Required if the DID being resolved
+   * has ever had a published BTCR2 Update.
+   */
+  updates?: Array<BTCR2SignedUpdate>
+
+  /**
+   * Optional array of CAS Announcements. Required if the DID being reslved has
+   * used a CAS Beacon to publish a BTCR2 Update.
+   */
+  casUpdates?: Array<CASAnnouncement>;
+
+  /**
+   * Optional array of SMT Proofs. Required if the DID being resolved has used
+   * an SMT Beacon to publish a BTCR2 Update.
+   */
+  smtProofs?: Array<SMTProof>;
+};
+
+/**
+ * The Sidecar data structure post-processing used for resolution.
+ */
+export type SidecarData = {
+  /**
+   * Map of BTCR2 Signed Updates by their hash bytes.
+   * @type {Map<HexString, BTCR2SignedUpdate>}
+   */
+  updateMap: Map<HexString, BTCR2SignedUpdate>;
+  /**
+   * Map of CAS Announcements by their hash bytes.
+   * @type {Map<HexString, CASAnnouncement>}
+   */
+  casMap: Map<HexString, CASAnnouncement>;
+  /**
+   * Map of SMT Proofs by their ID.
+   * @type {Map<string, SMTProof>}
+   */
+  smtMap: Map<string, SMTProof>;
+}

package/src/core/{crud/update.ts → update.ts}

@@ -1,26 +1,23 @@
 import {
-  BTCR2_DID_UPDATE_PAYLOAD_CONTEXT,
-  DidUpdateInvocation,
-  DidUpdatePayload,
   INVALID_DID_DOCUMENT,
   INVALID_DID_UPDATE,
   INVALID_PUBLIC_KEY_TYPE,
-  Logger,
+  JSONPatch,
   MethodError,
   NOT_FOUND,
   PatchOperation,
-  ProofOptions
+  UpdateError
 } from '@did-btcr2/common';
-import { SchnorrMultikey } from '@did-btcr2/cryptosuite';
+import { BTCR2SignedUpdate, BTCR2UnsignedUpdate, DataIntegrityConfig, SchnorrMultikey } from '@did-btcr2/cryptosuite';
 import { CompressedSecp256k1PublicKey, SchnorrKeyPair, Secp256k1SecretKey } from '@did-btcr2/keypair';
 import { Kms } from '@did-btcr2/kms';
 import type { DidService } from '@web5/dids';
-import { BeaconService } from '../../interfaces/beacon.js';
-import { Appendix } from '../../utils/appendix.js';
-import { DidDocument, DidVerificationMethod } from '../../utils/did-document.js';
-import { SignalsMetadata } from '../../utils/types.js';
-import { BeaconFactory } from '../beacon/factory.js';
-import { Identifier } from '../identifier.js';
+import { canonicalization } from '../did-btcr2.js';
+import { Appendix } from '../utils/appendix.js';
+import { DidDocument, DidVerificationMethod } from '../utils/did-document.js';
+import { BeaconService } from './beacon/interfaces.js';
+import { Identifier } from './identifier.js';
+import { SidecarData } from './types.js';
 
 export interface ConstructUpdateParams {
     identifier: string;
@@ -36,7 +33,7 @@ export interface UpdateParams extends ConstructUpdateParams {
 
 export type InvokePayloadParams = {
   identifier: string;
-  didUpdatePayload: DidUpdatePayload;
+  BTCR2SignedUpdate: BTCR2SignedUpdate;
   verificationMethod: DidVerificationMethod;
 }
 
@@ -65,7 +62,7 @@ export class Update {
    * @param {DidDocument} params.sourceDocument The source document to be updated.
    * @param {string} params.sourceVersionId The versionId of the source document.
    * @param {DidDocumentPatch} params.patch The JSON patch to be applied to the source document.
-   * @returns {Promise<DidUpdatePayload>} The constructed DidUpdatePayload object.
+   * @returns {Promise<BTCR2SignedUpdate>} The constructed BTCR2SignedUpdate object.
    * @throws {MethodError} InvalidDid if sourceDocument.id does not match identifier.
    */
   public static async construct({
@@ -78,76 +75,79 @@ export class Update {
     sourceDocument: DidDocument;
     sourceVersionId: number;
     patch: PatchOperation[];
-  }): Promise<DidUpdatePayload> {
+  }): Promise<BTCR2UnsignedUpdate> {
 
     // 1. Check that sourceDocument.id equals identifier else MUST raise invalidDIDUpdate error.
     if (sourceDocument.id !== identifier) {
-      throw new MethodError(
-        INVALID_DID_UPDATE,
-        'Source document id does not match identifier',
-        { sourceDocument, identifier}
+      throw new UpdateError(
+        'Identifier mismatch: sourceDocument.id !== identifier',
+        INVALID_DID_UPDATE, { sourceDocument, identifier }
       );
     }
 
-    // 2. Initialize didUpdatePayload to an empty object.
-    const didUpdatePayload: DidUpdatePayload = {
-    // 3. Set didUpdatePayload.@context to the following list
-      '@context'      : BTCR2_DID_UPDATE_PAYLOAD_CONTEXT,
-      // 4. Set didUpdatePayload.patch to documentPatch.
+    // 2. Initialize an unsigned update.
+    const unsignedUpdate: BTCR2UnsignedUpdate = {
+    // 3. Set BTCR2SignedUpdate.@context to the following list
+      '@context'      : [
+        'https://w3id.org/security/v2',
+        'https://w3id.org/zcap/v1',
+        'https://w3id.org/json-ld-patch/v1',
+        'https://btcr2.dev/context/v1'
+      ],
+      // 4. Set BTCR2SignedUpdate.patch to documentPatch.
       patch,
       targetHash      : '',
       targetVersionId : 0,
       sourceHash      : '',
     };
-    // TODO: Need to add btcr2 context. ["https://w3id.org/zcap/v1", "https://w3id.org/security/data-integrity/v2", "https://w3id.org/json-ld-patch/v1"]
 
     // 5. Set targetDocument to the result of applying the documentPatch to the sourceDocument, following the JSON Patch
     //    specification.
-    const targetDocument = JSON.patch.apply(sourceDocument, patch) as DidDocument;
+    const targetDocument = JSONPatch.apply(sourceDocument, patch) as DidDocument;
 
     // 6. Validate targetDocument is a conformant DID document, else MUST raise invalidDIDUpdate error.
     DidDocument.validate(targetDocument);
 
     // 7. Set sourceHashBytes to the result of passing sourceDocument into the JSON Canonicalization and Hash algorithm.
-    // 8. Set didUpdatePayload.sourceHash to the base58-btc Multibase encoding of sourceHashBytes.
-    didUpdatePayload.sourceHash = (await JSON.canonicalization.process(sourceDocument, 'base58')).slice(1);
+    // 8. Set BTCR2SignedUpdate.sourceHash to the base58-btc Multibase encoding of sourceHashBytes.
+    unsignedUpdate.sourceHash = (canonicalization.process(sourceDocument, { encoding: 'base58' })).slice(1);
     // TODO: Question - is base58btc the correct encoding scheme?
 
     // 9. Set targetHashBytes to the result of passing targetDocument into the JSON Canonicalization and Hash algorithm.
-    // 10. Set didUpdatePayload.targetHash to the base58-btc Multibase encoding of targetHashBytes.
-    didUpdatePayload.targetHash = (await JSON.canonicalization.process(targetDocument, 'base58')).slice(1);
+    // 10. Set BTCR2SignedUpdate.targetHash to the base58-btc Multibase encoding of targetHashBytes.
+    unsignedUpdate.targetHash = (canonicalization.process(targetDocument, { encoding: 'base58' })).slice(1);
 
-    // 11. Set didUpdatePayload.targetVersionId to sourceVersionId + 1.
-    didUpdatePayload.targetVersionId = sourceVersionId + 1;
+    // 11. Set BTCR2SignedUpdate.targetVersionId to sourceVersionId + 1.
+    unsignedUpdate.targetVersionId = sourceVersionId + 1;
 
     // 12. Return updatePayload.
-    return didUpdatePayload;
+    return unsignedUpdate;
   }
 
   /**
    * {@link https://dcdpr.github.io/did-btcr2/#invoke-did-update-payload | 4.3.2 Invoke DID Update Payload}.
    *
-   * The Invoke DID Update Payload algorithm takes in a Identifier, an unsigned didUpdatePayload, and a
+   * The Invoke DID Update Payload algorithm takes in a Identifier, an unsigned BTCR2SignedUpdate, and a
    * verificationMethod. It retrieves the privateKeyBytes for the verificationMethod and adds a capability invocation in
    * the form of a Data Integrity proof following the Authorization Capabilities (ZCAP-LD) and VC Data Integrity
    * specifications. It returns the invoked DID Update Payload.
    *
    * @param {InvokePayloadParams} params Required params for calling the invokePayload method
    * @param {string} params.identifier The did-btcr2 identifier to derive the root capability from
-   * @param {DidUpdatePayload} params.didUpdatePayload The updatePayload object to be signed
+   * @param {BTCR2SignedUpdate} params.BTCR2SignedUpdate The updatePayload object to be signed
    * @param {DidVerificationMethod} params.verificationMethod The verificationMethod object to be used for signing
-   * @returns {DidUpdateInvocation} Did update payload secured with a proof => DidUpdateInvocation
+   * @returns {BTCR2SignedUpdate} Did update payload secured with a proof => BTCR2SignedUpdate
    * @throws {MethodError} if the privateKeyBytes are invalid
    */
   public static async invoke({
     identifier,
-    didUpdatePayload,
+    unsignedUpdate,
     verificationMethod
   }: {
     identifier: string;
-    didUpdatePayload: DidUpdatePayload;
+    unsignedUpdate: BTCR2UnsignedUpdate;
     verificationMethod: DidVerificationMethod;
-  }): Promise<DidUpdateInvocation> {
+  }): Promise<BTCR2SignedUpdate> {
     // Deconstruct the verificationMethod
     const { id: fullId, controller, publicKeyMultibase, secretKeyMultibase } = verificationMethod;
 
@@ -169,7 +169,7 @@ export class Update {
     const keyUri = new CompressedSecp256k1PublicKey(components.genesisBytes).hex;
     const keys = secretKeyMultibase
       ? new SchnorrKeyPair({ secretKey: Secp256k1SecretKey.decode(secretKeyMultibase) })
-      : await Kms.getKey(keyUri as string);
+      : Kms.getKey(keyUri as string);
     if (!keys) {
       throw new MethodError(
         'No privateKey found in kms or vm',
@@ -199,7 +199,13 @@ export class Update {
     // 7. Set proofOptions.proofPurpose to capabilityInvocation.
     // 8. Set proofOptions.capability to rootCapability.id.
     // 9. Set proofOptions.capabilityAction to Write.
-    const options: ProofOptions = {
+    const config: DataIntegrityConfig = {
+      '@context' : [
+        'https://w3id.org/security/v2',
+        'https://w3id.org/zcap/v1',
+        'https://w3id.org/json-ld-patch/v1',
+        'https://btcr2.dev/context/v1'
+      ],
       cryptosuite,
       type               : 'DataIntegrityProof',
       verificationMethod : fullId,
@@ -210,12 +216,12 @@ export class Update {
 
     // 10. Set cryptosuite to the result of executing the Cryptosuite Instantiation algorithm from the BIP340 Data
     //     Integrity specification passing in proofOptions.
-    const diproof = multikey.toCryptosuite(cryptosuite).toDataIntegrityProof();
+    const diproof = multikey.toCryptosuite().toDataIntegrityProof();
 
-    // 12. Set didUpdateInvocation to the result of executing the Add Proof algorithm from VC Data Integrity passing
-    //     didUpdatePayload as the input document, cryptosuite, and the set of proofOptions.
-    // 13. Return didUpdateInvocation.
-    return await diproof.addProof({ document: didUpdatePayload, options });
+    // 12. Set BTCR2SignedUpdate to the result of executing the Add Proof algorithm from VC Data Integrity passing
+    //     BTCR2SignedUpdate as the input document, cryptosuite, and the set of proofOptions.
+    // 13. Return BTCR2SignedUpdate.
+    return await diproof.addProof(unsignedUpdate, config);
   }
 
   /**
@@ -223,30 +229,30 @@ export class Update {
    *
    * The Announce DID Update algorithm retrieves beaconServices from the sourceDocument and calls the Broadcast DID
    * Update algorithm corresponding to the type of the Beacon. It takes in a Identifier, sourceDocument, an array of
-   * beaconIds, and a didUpdateInvocation. It returns an array of signalsMetadata, containing the necessary
-   * data to validate the Beacon Signal against the didUpdateInvocation.
+   * beaconIds, and a BTCR2SignedUpdate. It returns an array of signalsMetadata, containing the necessary
+   * data to validate the Beacon Signal against the BTCR2SignedUpdate.
    *
    * @param {AnnounceUpdatePayloadParams} params Required params for calling the announcePayload method
    * @param {DidDocument} params.sourceDocument The did-btcr2 did document to derive the root capability from
-   * @param {string[]} params.beaconIds The didUpdatePayload object to be signed
-   * @param {DidUpdateInvocation} params.didUpdatePayload The verificationMethod object to be used for signing
-   * @returns {SignalsMetadata} The signalsMetadata object containing data to validate the Beacon Signal
+   * @param {string[]} params.beaconIds The BTCR2SignedUpdate object to be signed
+   * @param {BTCR2SignedUpdate} params.BTCR2SignedUpdate The verificationMethod object to be used for signing
+   * @returns {BTCR2SignedUpdate} The BTCR2SignedUpdate object containing data to validate the Beacon Signal
    * @throws {MethodError} if the beaconService type is invalid
    */
   public static async announce({
     sourceDocument,
     beaconIds,
-    didUpdateInvocation
+    signedUpdate
   }: {
     sourceDocument: DidDocument;
     beaconIds: string[];
-    didUpdateInvocation: DidUpdateInvocation;
-  }): Promise<SignalsMetadata> {
+    signedUpdate: BTCR2SignedUpdate;
+  }): Promise<SidecarData> {
     // 1. Set beaconServices to an empty array.
     const beaconServices: BeaconService[] = [];
 
-    // 2. signalMetadata to an empty array.
-    let signalsMetadata;
+    // 2. sidecarData to an empty array.
+    let sidecarData: SidecarData | undefined;
 
     // 3. For beaconId in beaconIds:
     for (const beaconId of beaconIds) {
@@ -266,27 +272,28 @@ export class Update {
     for (const beaconService of beaconServices) {
       // 4.1 Set signalMetadata to null.
       // 4.2 If beaconService.type == SingletonBeacon:
-      //    4.2.1 Set signalMetadata to the result of passing beaconService and didUpdateInvocation to the Broadcast
+      //    4.2.1 Set signalMetadata to the result of passing beaconService and BTCR2SignedUpdate to the Broadcast
       //          Singleton Beacon Signal algorithm.
-      // 4.3 Else If beaconService.type == CIDAggregateBeacon:
-      //    4.3.1 Set signalMetadata to the result of passing Identifier, beaconService and didUpdateInvocation to
+      // 4.3 Else If beaconService.type == CASBeacon:
+      //    4.3.1 Set signalMetadata to the result of passing Identifier, beaconService and BTCR2SignedUpdate to
       //          the Broadcast CIDAggregate Beacon Signal algorithm.
-      // 4.4 Else If beaconService.type == SMTAggregateBeacon:
-      //    4.4.1 Set signalMetadata to the result of passing Identifier, beaconService and didUpdateInvocation to
+      // 4.4 Else If beaconService.type == SMTBeacon:
+      //    4.4.1 Set signalMetadata to the result of passing Identifier, beaconService and BTCR2SignedUpdate to
       //          the Broadcast SMTAggregate Beacon Signal algorithm.
       // 4.5 Else:
       //    4.5.1 MUST throw invalidBeacon error.
-      const beacon = BeaconFactory.establish(beaconService);
-      signalsMetadata = await beacon.broadcastSignal(didUpdateInvocation);
+      // const beacon = BeaconFactory.establish(beaconService);
+      // sidecarData = await beacon.broadcastSignal(signedUpdate);
+      console.log('TODO: refactor this code', signedUpdate, beaconService);
     }
-    if(!signalsMetadata) {
+    if(!sidecarData) {
       throw new MethodError(
-        'Invalid beacon: no signalsMetadata found',
+        'Invalid beacon: no sidecarData found',
         INVALID_DID_DOCUMENT, { beaconServices }
       );
     }
-    Logger.debug('signalsMetadata', signalsMetadata);
-    // Return the signalsMetadata
-    return signalsMetadata;
+
+    // Return the sidecarData
+    return sidecarData;
   }
 }