Define the API Payload - Githubissues

pfeairheller commented 2 years ago

We need 4 payloads defined.

[x] Payload for QVI Presentation
[x] Payload for Legal Entity Presentation
[x] Payload for OOR Presentation
[x] Payload for Revocation

Sally will be configured at start up with on URL to call as a web hook. Sally will perform all structural and cryptographic verification of any credential or revocation presented as well as performing all vLEI value validation.

pfeairheller commented 2 years ago

Modifying the approach to the payloads for the outbound webhook call from Sally. Modeling the calls after the sentry.io webhook, each request will have the following headers:

{
   "Content-Type": "application/json",
   "Content-Length": <size of body>,
   "Sally-Resource": "EWCeT9zTxaZkaC_3-amV2JtG6oUxNA36sCC0P5MI7Buw",
   "Sally-Timestamp": "2022-06-24T14:19:19.591808+00:00"
}

Header	Description
Content-Type	Will always be "application/json"
Content-Length	Size of body of outbound request
Sally-Resource	The SAID of the schema of the credential that triggered the request
Sally-Timestamp	The timestamp of the request (replay attack prevention)

Presentation

The presentation API will be a POST to the configured web hook URL and will contain one of the following 3 payloads depending on the type of credential being presented.

QVI Payload

{
   "action": "iss",
   "actor": "EPqeYsDPrYdb9HxJ0Yk9gH0VfspezBVLjxAzjfTGsgkY",
   "data": { 
       "schema": "EWCeT9zTxaZkaC_3-amV2JtG6oUxNA36sCC0P5MI7Buw",
       "issuer": "EPqeYsDPrYdb9HxJ0Yk9gH0VfspezBVLjxAzjfTGsgkY",
       "issueTimestamp": "2022-06-24T14:19:19.591808+00:00",
       "credential": "EnR0SI1z7gwUYvnRUSwSLvP8O5oWZ_uzuFKSQGmanR9w",
       "recipient": "EGhyphY8VJwvliB0ZeX6-8kkyS9L_eGZE-TkPifM29HY",
       "LEI": "506700GE1G29325QX363"
    }
}

Legal Entity Payload

{
   "action": "iss",
   "actor": "EGhyphY8VJwvliB0ZeX6-8kkyS9L_eGZE-TkPifM29HY",
   "data": { 
       "schema": "EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs",
       "issuer": "EGhyphY8VJwvliB0ZeX6-8kkyS9L_eGZE-TkPifM29HY",
       "issueTimestamp": "2022-06-24T14:19:19.591808+00:00",
       "credential": "EHcRiSahoTAKNWZRLNN7MGtUfbMJgUldvPjpc3NCWxsQ",
       "recipient": "EkjlNRao4AZEmasi2jb9E3u4xnLD5Oe2qkHS_JWCIq-U",
       "qviCredential": "EnR0SI1z7gwUYvnRUSwSLvP8O5oWZ_uzuFKSQGmanR9w",
       "LEI": "506700GE1G29325QX363"
    }
}

Official Organization Role Payload

{
   "action": "iss",
   "actor": "EGhyphY8VJwvliB0ZeX6-8kkyS9L_eGZE-TkPifM29HY",
   "data": { 
       "schema": "E2RzmSCFmG2a5U2OqZF-yUobeSYkW-a3FsN82eZXMxY0",
       "issuer": "EGhyphY8VJwvliB0ZeX6-8kkyS9L_eGZE-TkPifM29HY",
       "issueTimestamp": "2022-06-24T14:19:19.591808+00:00",
       "credential": "EecctjiS0dFyohgz0GBC6O9NlJJ7-pSJ3U5ZFEvzm48A",
       "recipient": "ECRi-yUy_bq2YrgTKI-VbG1MdvWsNstdyjvfx1ZEHJOY",
       "legalEntityCredential": "EHcRiSahoTAKNWZRLNN7MGtUfbMJgUldvPjpc3NCWxsQ"
       "qviCredential": "EnR0SI1z7gwUYvnRUSwSLvP8O5oWZ_uzuFKSQGmanR9w",
       "LEI": "506700GE1G29325QX363" ,
       "personLegalName": "Stephan Wolf",
       "officialRole": "Chief Executive Officer"
    }
}

Presentation Payload Field Key The following table contains a description for every field in all the credential presentation payloads defined above:

Field Label	Description
action	the action that triggered the web hook call. Value will be "iss" for issue presentations
actor	The AID of the presenter of the credential
data	Attributes specific to the credential being presentedl
data -> schema	SAID of the schema of the credential that was presented
data -> issuer	Issuer of the credential presented
data -> issueTimestamp	Issuance timestamp for the credential
data -> credential	SAID of credential being presented
data -> recipient	AID of the holder of the credential
data -> qviCredential	SAID of a chained QVI credential (for LE and OOR credentials)
data -> legalEntityCredential	SAID of a chained legal entity credential (for OOR credentials)
data -> LEI	Legal Entity Identifier
data -> personLegalName	Person Legal Name data field of the OOR credential
data -> officialRole	Official Role Name data field of the OOR credential

Schema

The credential schema define the type of credential being presented. The following table contains the list of the schema SAID for the vLEI credentials defined above.

Schema	Type
EWCeT9zTxaZkaC_3-amV2JtG6oUxNA36sCC0P5MI7Buw	Qualified vLEI Issuer vLEI Credential
EWJkQCFvKuyxZi582yJPb0wcwuW3VXmFNuvbQuBpgmIs	Legal Entity vLEI Credential
E2RzmSCFmG2a5U2OqZF-yUobeSYkW-a3FsN82eZXMxY0	Official Organization Role vLEI Credential

Revocation

All revocation web hook requests will have the same format as follows:

Revocation Payload

{
   "action": "rev",
   "actor": "EGhyphY8VJwvliB0ZeX6-8kkyS9L_eGZE-TkPifM29HY",
   "data": { 
       "schema": "EWCeT9zTxaZkaC_3-amV2JtG6oUxNA36sCC0P5MI7Buw",
       "credential": "EZBfSGG5k1CZYk1QH3GXFPtEwLHf0H06zuDUEJRyar1E",
       "revocationTimestamp": "2022-06-24T14:19:19.591808+00:00"
    }
}

Revocation Payload Field Key The following table contains a description for every field in all the credential revocation payloads defined above:

Field Label	Description
action	the action that triggered the web hook call. Value will be "rev" for revocation presentations
actor	The AID of the presenter of the revocation
data	Attributes specific to the credential being presentedl
data -> schema	SAID of the schema of the credential that was revoked
data -> revocationTimestamp	Revocation timestamp for the credential
data -> credential	SAID of credential being revoked

tsterker commented 2 years ago

@pfeairheller For my understanding:

The above endpoints and payloads are what KARA would offer for credential presentation/revocation.
The payloads are what we would expect them to send

Would you imagine that the webhooks would include the same payload "verbatim", or would there be the necessity/possibility to extend the webhook payload with more relevant information/context?

FYI @m00sey @bernardkissi

tsterker commented 2 years ago

@pfeairheller This is mine and @bernardkissi's current understanding:

Let's discuss it in the call later

pfeairheller commented 2 years ago

I've updated the payload in my first comment. Notable changes:

Mirrored the requests after the sentry.io webhook API
Removed the OOBI field. There is no way to keep this up to date.
Change field names to be easier to understand and map
Removed all fields not needed for database updates

Please let me know if anything is unclear or if you feel there are additional fields you will need

tsterker commented 2 years ago

@pfeairheller Thanks for the update. This looks good at a glance and we'll try to update our POC implementation to make use of this.

There's two up-front questions:

1) How is the ORR credential linked to the LE credential?

To our understanding, the link is currently established via the LEI code only? I believe this would not suffice if we need to deal with e.g. revocation events, where we would need to explicitly link LEs to OORs to mark them also as revoked? Or is the legal entity credential identified recipient (i.e. the "holder")?

2) Not a real-world example?

e.g. in the example OOR payload the actor and recipient seems to be the same, which should not be possible?

FYI @bernardkissi

pfeairheller commented 2 years ago

You are only marking the credential you receive notifications about as revoked and you have the SAID of the credential which is sufficient.
"actor" is marked at the presenter of the credential and in most cases of SSI, the holder of the credential is the presenter. So yes, this is possible. For this example, we were merely trying to convey the structure of the messages.

pfeairheller commented 2 years ago

The payload has been defined and been documented in the README so I consider this issue closed.

tsterker commented 2 years ago

RE 1: You are only marking the credential you receive notifications about as revoked and you have the SAID of the credential which is sufficient.

We are not only marking the credential as revoked for which we received a notification. We'll need to have the revocation cascade down for the whole hierarchy. And to my understanding, we would currently don't have a link between LE --> OOR and thus not be able to mark child OORs as revoked as well.

RE 2: For this example, we were merely trying to convey the structure of the messages.

While the structure of the message is most important at this point, making sure we fully understand the individual pieces of information and how these link credentials with each other will be important for us to validate our understanding.

e.g. I assume this case is not possible, where a credential is issued "by itself"?

I could try to generate valid examples myself, but would still rely on you to confirm I didn't make any mistake.

pfeairheller commented 2 years ago

We are not only marking the credential as revoked for which we received a notification. We'll need to have the revocation cascade down for the whole hierarchy. And to my understanding, we would currently don't have a link between LE --> OOR and thus not be able to mark child OORs as revoked as well.

Your original question was unclear, it sounded as if you wanted to update legal entities when OORs were revoked. I added chained credentials to the payloads above.

I could try to generate valid examples myself, but would still rely on you to confirm I didn't make any mistake.

The AIDs are merely opaque identifiers that have no contextual meaning for the samples above. Regardless, I've changed them so they are different in the samples above to make them more clear for you. Also, as mentioned in other issues, the POC is complete and you should be able to run the software locally and see the actual payloads.

tsterker commented 2 years ago

Just for reference:

GLEIF-IT / sally

Define the API Payload #2

Presentation

Schema

Revocation