[SDK-443] Add Sources & Verifiers

.gitignore

@@ -7,3 +7,6 @@ examples/profile/images/YotiSelfie.jpeg
 # Example project generated self-signed certificate
 examples/profile/yotiSelfSignedCert.pem
 examples/profile/yotiSelfSignedKey.pem
+
+# Debug files
+debug

CONTRIBUTING.md

@@ -35,7 +35,7 @@ For developing in VS Code, use the following `launch.json` file (placed inside a
         "host": "127.0.0.1",
         "program": "${workspaceFolder}/examples/profile/main.go",
         "env": {},
-        "args": [],
+        "args": ["certificatehelper.go"],
         "showLog": true
     }
     ]

README.md

@@ -104,21 +104,23 @@ if len(errStrings) != 0 {
 }
 ```
 
+### Profile
+
 You can then get the user profile from the activityDetails struct:
 
 ```Go
 rememberMeID := activityDetails.RememberMeID
 userProfile := activityDetails.UserProfile
 
-selfie := userProfile.Selfie().Value
-givenNames := userProfile.GivenNames().Value
-familyName := userProfile.FamilyName().Value
-fullName := userProfile.FullName().Value
-mobileNumber := userProfile.MobileNumber().Value
-emailAddress := userProfile.EmailAddress().Value
-address := userProfile.Address().Value
-gender := userProfile.Gender().Value
-nationality := userProfile.Nationality().Value
+selfie := userProfile.Selfie().Value()
+givenNames := userProfile.GivenNames().Value()
+familyName := userProfile.FamilyName().Value()
+fullName := userProfile.FullName().Value()
+mobileNumber := userProfile.MobileNumber().Value()
+emailAddress := userProfile.EmailAddress().Value()
+address := userProfile.Address().Value()
+gender := userProfile.Gender().Value()
+nationality := userProfile.Nationality().Value()
 dob, err := userProfile.DateOfBirth()
 if err != nil {
     //handle error
@@ -130,11 +132,45 @@ if err != nil {
 If you have chosen Verify Condition on the Yoti Dashboard with the age condition of "Over 18", you can retrieve the user information with the generic .GetAttribute method, which requires the result to be cast to the original type:
 
 ```Go
-userProfile.GetAttribute("age_over:18").Value.(string)
+userProfile.GetAttribute("age_over:18").Value().(string)
 ```
 
 GetAttribute returns an interface, the value can be acquired through a type assertion.
 
+### Anchors, Sources and Verifiers
+
+An `Anchor` represents how a given Attribute has been _sourced_ or _verified_.  These values are created and signed whenever a Profile Attribute is created, or verified with an external party.
+
+For example, an attribute value that was _sourced_ from a Passport might have the following values:
+
+`Anchor` property | Example value
+-----|------
+type | SOURCE
+value | PASSPORT
+subType | OCR
+signedTimestamp | 2017-10-31, 19:45:59.123789
+
+Similarly, an attribute _verified_ against the data held by an external party will have an `Anchor` of type _VERIFIER_, naming the party that verified it.
+
+From each attribute can retrieve the `Anchors`, and subsets `Sources` and `Verifiers` (all as `[]*anchor.Anchor`) as follows:
+
+```Go
+givenNamesAnchors := userProfile.GivenNames().Anchors()
+givenNamesSources := userProfile.GivenNames().Sources()
+givenNamesVerifiers := userProfile.GivenNames().Verifiers()
+```
+
+You can also retrieve further properties from these respective anchors in the following way:
+
+```Go
+givenNamesFirstAnchor := userProfile.GivenNames().Anchors()[0]
+
+anchorType := givenNamesFirstAnchor.Type
+signedTimestamp := givenNamesFirstAnchor.SignedTimestamp().Timestamp
+subType := givenNamesFirstAnchor.SubType()
+value := givenNamesFirstAnchor.Value()
+```
+
 ## Handling Users
 
 When you retrieve the user profile, you receive a user ID generated by Yoti exclusively for your application.
@@ -200,7 +236,7 @@ Performing an AML check on a person *requires* their consent.
 
 Given a YotiClient initialised with your SDK ID and KeyPair (see [Client Initialisation](#client-initialisation)) performing an AML check is a straightforward case of providing basic profile data.
 
-```go
+```Go
 givenNames := "Edward Richard George"
 familyName := "Heath"
 

anchor/anchors.go

@@ -57,8 +57,8 @@ func (a Anchor) OriginServerCerts() []*x509.Certificate {
 // message associated with the timestamp is the marshaled form of
 // AttributeSigning (i.e. the same message that is signed in the
 // Signature field). This method returns the SignedTimestamp
-// object, the actual timestamp as a DateTime can be called with
-// .Timestamp() on this object
+// object, the actual timestamp as a *time.Time can be called with
+// .Timestamp on the result of this function
 func (a Anchor) SignedTimestamp() SignedTimestamp {
 	return a.signedTimestamp
 }
@@ -76,3 +76,22 @@ func (a Anchor) SubType() string {
 func (a Anchor) Value() []string {
 	return a.value
 }
+
+// GetSources returns the anchors which identify how and when an attribute value was acquired.
+func GetSources(anchors []*Anchor) (sources []*Anchor) {
+	return filterAnchors(anchors, AnchorTypeSource)
+}
+
+// GetVerifiers returns the anchors which identify how and when an attribute value was verified by another provider.
+func GetVerifiers(anchors []*Anchor) (sources []*Anchor) {
+	return filterAnchors(anchors, AnchorTypeVerifier)
+}
+
+func filterAnchors(anchors []*Anchor, anchorType Type) (result []*Anchor) {
+	for _, v := range anchors {
+		if v.Type == anchorType {
+			result = append(result, v)
+		}
+	}
+	return result
+}

attribute/genericattribute.go

@@ -11,8 +11,10 @@ import (
 //GenericAttribute is a Yoti attribute which returns a generic value
 type GenericAttribute struct {
 	*yotiprotoattr_v3.Attribute
-	Value   interface{}
-	Anchors []*anchor.Anchor
+	value     interface{}
+	anchors   []*anchor.Anchor
+	sources   []*anchor.Anchor
+	verifiers []*anchor.Anchor
 }
 
 //NewGeneric creates a new generic attribute
@@ -49,12 +51,38 @@ func NewGeneric(a *yotiprotoattr_v3.Attribute) *GenericAttribute {
 		value = a.Value
 	}
 
+	parsedAnchors := anchor.ParseAnchors(a.Anchors)
+
 	return &GenericAttribute{
 		Attribute: &yotiprotoattr_v3.Attribute{
 			Name:        a.Name,
 			ContentType: a.ContentType,
 		},
-		Value:   value,
-		Anchors: anchor.ParseAnchors(a.Anchors),
+		value:     value,
+		anchors:   parsedAnchors,
+		sources:   anchor.GetSources(parsedAnchors),
+		verifiers: anchor.GetVerifiers(parsedAnchors),
 	}
 }
+
+// Value returns the value of the GenericAttribute as an interface
+func (a *GenericAttribute) Value() interface{} {
+	return a.value
+}
+
+// Anchors are the metadata associated with an attribute. They describe
+// how an attribute has been provided to Yoti (SOURCE Anchor) and how
+// it has been verified (VERIFIER Anchor).
+func (a *GenericAttribute) Anchors() []*anchor.Anchor {
+	return a.anchors
+}
+
+// Sources returns the anchors which identify how and when an attribute value was acquired.
+func (a *GenericAttribute) Sources() []*anchor.Anchor {
+	return a.sources
+}
+
+// Verifiers returns the anchors which identify how and when an attribute value was verified by another provider.
+func (a *GenericAttribute) Verifiers() []*anchor.Anchor {
+	return a.verifiers
+}

attribute/image.go

@@ -2,41 +2,26 @@ package attribute
 
 import (
 	"encoding/base64"
-	"log"
+	"fmt"
 )
 
-//ImageType Image format
-type ImageType int
-
 const (
 	//ImageTypeJpeg JPEG format
-	ImageTypeJpeg ImageType = 1 + iota
+	ImageTypeJpeg string = "jpeg"
 	//ImageTypePng PNG format
-	ImageTypePng
-	//ImageTypeOther Other image formats
-	ImageTypeOther
+	ImageTypePng string = "png"
 )
 
 //Image format of the image and the image data
 type Image struct {
-	Type ImageType
+	Type string
 	Data []byte
 }
 
-var mimeTypeMap = map[ImageType]string{
-	ImageTypeJpeg: "image/jpeg",
-	ImageTypePng:  "image/png",
-}
-
 // GetMIMEType returns the MIME type of this piece of Yoti user information. For more information see:
 // https://en.wikipedia.org/wiki/Media_type
-func GetMIMEType(imageType ImageType) (result string) {
-	if val, ok := mimeTypeMap[imageType]; ok {
-		return val
-	}
-
-	log.Printf("Unable to find a matching MIME type for value type %q", imageType)
-	return
+func GetMIMEType(imageType string) string {
+	return fmt.Sprintf("image/%v", imageType)
 }
 
 // Base64URL is the Image encoded as a base64 URL

attribute/imageattribute.go

@@ -1,20 +1,24 @@
 package attribute
 
 import (
+	"errors"
+
 	"github.com/getyoti/yoti-go-sdk/anchor"
 	"github.com/getyoti/yoti-go-sdk/yotiprotoattr_v3"
 )
 
 //ImageAttribute is a Yoti attribute which returns an image as its value
 type ImageAttribute struct {
 	*yotiprotoattr_v3.Attribute
-	Value   *Image
-	Anchors []*anchor.Anchor
+	value     *Image
+	anchors   []*anchor.Anchor
+	sources   []*anchor.Anchor
+	verifiers []*anchor.Anchor
 }
 
 //NewImage creates a new Image attribute
-func NewImage(a *yotiprotoattr_v3.Attribute) *ImageAttribute {
-	var imageType ImageType
+func NewImage(a *yotiprotoattr_v3.Attribute) (*ImageAttribute, error) {
+	var imageType string
 
 	switch a.ContentType {
 	case yotiprotoattr_v3.ContentType_JPEG:
@@ -24,18 +28,44 @@ func NewImage(a *yotiprotoattr_v3.Attribute) *ImageAttribute {
 		imageType = ImageTypePng
 
 	default:
-		imageType = ImageTypeOther
+		return nil, errors.New("Cannot create ImageAttribute with unsupported type")
 	}
 
+	parsedAnchors := anchor.ParseAnchors(a.Anchors)
+
 	return &ImageAttribute{
 		Attribute: &yotiprotoattr_v3.Attribute{
 			Name:        a.Name,
 			ContentType: a.ContentType,
 		},
-		Value: &Image{
+		value: &Image{
 			Data: a.Value,
 			Type: imageType,
 		},
-		Anchors: anchor.ParseAnchors(a.Anchors),
-	}
+		anchors:   parsedAnchors,
+		sources:   anchor.GetSources(parsedAnchors),
+		verifiers: anchor.GetVerifiers(parsedAnchors),
+	}, nil
+}
+
+// Value returns the value of the ImageAttribute as *Image
+func (a *ImageAttribute) Value() *Image {
+	return a.value
+}
+
+// Anchors are the metadata associated with an attribute. They describe
+// how an attribute has been provided to Yoti (SOURCE Anchor) and how
+// it has been verified (VERIFIER Anchor).
+func (a *ImageAttribute) Anchors() []*anchor.Anchor {
+	return a.anchors
+}
+
+// Sources returns the anchors which identify how and when an attribute value was acquired.
+func (a *ImageAttribute) Sources() []*anchor.Anchor {
+	return a.sources
+}
+
+// Verifiers returns the anchors which identify how and when an attribute value was verified by another provider.
+func (a *ImageAttribute) Verifiers() []*anchor.Anchor {
+	return a.verifiers
 }

attribute/jsonattribute.go

@@ -11,8 +11,10 @@ import (
 //JSONAttribute is a Yoti attribute which returns an interface as its value
 type JSONAttribute struct {
 	*yotiprotoattr_v3.Attribute // Value returns the value of a JSON attribute in the form of an interface
-	Value                       interface{}
-	Anchors                     []*anchor.Anchor
+	value                       interface{}
+	anchors                     []*anchor.Anchor
+	sources                     []*anchor.Anchor
+	verifiers                   []*anchor.Anchor
 }
 
 //NewJSON creates a new JSON attribute
@@ -23,13 +25,17 @@ func NewJSON(a *yotiprotoattr_v3.Attribute) (*JSONAttribute, error) {
 		return nil, err
 	}
 
+	parsedAnchors := anchor.ParseAnchors(a.Anchors)
+
 	return &JSONAttribute{
 		Attribute: &yotiprotoattr_v3.Attribute{
 			Name:        a.Name,
 			ContentType: a.ContentType,
 		},
-		Value:   interfaceValue,
-		Anchors: anchor.ParseAnchors(a.Anchors),
+		value:     interfaceValue,
+		anchors:   parsedAnchors,
+		sources:   anchor.GetSources(parsedAnchors),
+		verifiers: anchor.GetVerifiers(parsedAnchors),
 	}, nil
 }
 
@@ -44,3 +50,25 @@ func UnmarshallJSON(byteValue []byte) (result interface{}, err error) {
 
 	return unmarshalledJSON, err
 }
+
+// Value returns the value of the JSONAttribute as an interface
+func (a *JSONAttribute) Value() interface{} {
+	return a.value
+}
+
+// Anchors are the metadata associated with an attribute. They describe
+// how an attribute has been provided to Yoti (SOURCE Anchor) and how
+// it has been verified (VERIFIER Anchor).
+func (a *JSONAttribute) Anchors() []*anchor.Anchor {
+	return a.anchors
+}
+
+// Sources returns the anchors which identify how and when an attribute value was acquired.
+func (a *JSONAttribute) Sources() []*anchor.Anchor {
+	return a.sources
+}
+
+// Verifiers returns the anchors which identify how and when an attribute value was verified by another provider.
+func (a *JSONAttribute) Verifiers() []*anchor.Anchor {
+	return a.verifiers
+}