docs: ADR for support of Gaia-X Participant Self-Description in Ident…

…ityHub (#7)

ADR for support of Gaia-X Participant Self-Description in IdentityHub

docs/developer/decision-records/2023-01-03-gaiax-participant-self-description/README.md

@@ -0,0 +1,34 @@
+# Gaia-X Participant Self-Description
+
+## Decision
+
+Provide an extension for the [IdentityHub](https://github.com/eclipse-edc/IdentityHub) component enabling creation, signature and
+exposure of Gaia-X participant self-description.
+
+## Rationale
+
+In a Gaia-X dataspace, participants must describe themselves using standardised, machine comprehensible metadata called self-description (SD; cf. [definition in the Gaia-X Glossary](https://gaia-x.gitlab.io/glossary/self_description/)).
+According to the specification of the [Gaia-X credential format](https://gaia-x.gitlab.io/technical-committee/federation-services/icam/credential_format/), 
+a SD is essentially a [W3C Verifiable Presentation (VP)](https://www.w3.org/TR/vc-data-model/), comprising one or more Verifiable Credentials (VC), each composed of a set of standardised claims describing the Gaia-X entity 
+(e.g., in the case of a Participant, its name, LEI number, headquarter localisation, …). These VCs are signed by an authority endorsed by Gaia-X called a Trust Anchor (cf. the [Gaia-X Trust Framework](https://gaia-x.gitlab.io/policy-rules-committee/trust-framework/trust_anchors/))..  
+
+## Approach
+
+As described [here](https://gitlab.com/gaia-x/gaia-x-community/gaia-x-catalogue/catalogue-document/-/blob/85c23d34a6b1a37ab5982ec511493ce3ac8d54c6/01_self-descriptions.md), 
+the signature process can either be performed directly by the participant using an identity (certificate) provided by a Trust Anchor, or by the Trust Anchor itself. Both flavours
+should be supported by the extension.
+
+After the Self-Description has been created, it is sent to the [Gaia-X Compliance service](https://compliance.gaia-x.eu/docs/#/Participant/ParticipantController_signContent) which validates 
+the format of the VC claims and asserts that is has been signed by an endorsed Trust Anchor. If successful, the API returns a compliance credential, which is another VC containing a hash of the SD.
+
+Both the SD and the compliance credential are then persisted into the store of the Identity Hub. 
+Then, when a participant requests another participant SD, the SD and the associated compliance credential are 
+retrieved from the store, assembled, and returned back to the caller.
+
+## Diagram
+
+As depicted below, the proposed extension will build the SD and verify it against the Gaia-X compliance API in one single step. 
+Thus, the VP sent to the Gaia-X compliance service will contain a single VC whose claims are the one provided in input. 
+
+![](gaiax-participant-self-description.png)
+

docs/developer/decision-records/2023-01-03-gaiax-participant-self-description/gaiax-participant-self-description.puml

@@ -0,0 +1,51 @@
+@startuml
+skinparam BoxPadding 10
+autonumber "<b>0'.'"
+
+box "Participant A" #LightPink
+actor " " as ParticipantA
+participant "EDC\nIdentityHub" as IdentityHub
+database "IdentityHub\nStore" as VcStore
+end box
+
+box "Trust Anchor" #LightGreen
+participant "Signature\nService" as TrustAnchor
+end box
+
+box "Gaia-X" #LightYellow
+Participant "Compliance\nService" as GaiaX
+end box
+
+box "Participant B" #LightBlue
+Participant "Client" as ParticipantB
+end box
+
+== Self-Description creation ==
+
+ParticipantA -> IdentityHub ++: Send claims
+activate ParticipantA
+deactivate ParticipantA
+group Option A: self-signing
+  autonumber 2
+  IdentityHub -> IdentityHub: Normalize (canonize)\nand compute hash
+  IdentityHub -> IdentityHub: Sign hash and\ncreate VC (claims + proof)
+end
+group Option B: notarization officer (trust anchor)
+  autonumber 2
+  IdentityHub -> TrustAnchor ++: Send claims
+  return VC (claims + proof)
+end
+IdentityHub -> GaiaX ++: send VC
+return compliance credential (another VC)
+IdentityHub -> VcStore ++: store both VCs
+
+== Self-Description presentation ==
+
+ParticipantB -> IdentityHub : request Participant A \nsigned self-description
+activate ParticipantB
+group self-description aggregation
+  IdentityHub -> VcStore : retrieve VCs
+  VcStore --> IdentityHub : self-description and compliance credential
+end
+IdentityHub --> ParticipantB : complete self-description
+@enduml

docs/developer/decision-records/README.md

@@ -1 +1,3 @@
-# Decision Records
+# Decision Records
+
+- [2023-01-03 Gaia-X Participant Self-Description](2023-01-03-gaiax-participant-self-description/)