[ProviderConfirmationPolicy] Allow data provider to explicitly confirm data requests on DSP:ContractOfferRequests as

[AbdullahMuk]

Feature

Description (Problem to be solved and requirements to satisfy)

As a data provider I want to actively approve a consumer's request to consume my asset, because I want to have extended control over the consumption of my data. The confirmation shall happen after a consumer requested a contract offer. I shall be able to see trustable information from the Authority Portal about the requestor to derive a carefully considered decision.

Hint: The connector restricted policy does not help in this case, as it requires to know, who shall consume my data at date of creation.

Overview of Features

• Provider Confirmation Policy to let providers decide with whom a contract to establish
• Participant Information Service (ParIS) Extension to receive validated organization details from Authority Portal inside EDC. Solves following problems:
  • 1. Contracts / Transfer History on provider side does not contain any consumer details aside of URL and ID
  • 2. Logging House only knows ID
  • 3. On provider side with ProviderConfirmationPolicy no information about the consumer would be available
  • 4. On consumer side no validatable information are available. Workaround exists to set details by provider in asset details, but which are not validatable for consumers.

Benefits

• More control over who receives data
• Allows to openly show data offer, but to decide per request, if data is shared or not
• Manual decision to improve UX and foster implicitly experienced control
• Approve/restrict access also for newly joined participants in the data space
• Can increase the flexibility of the data space and offers more business opportunities for participants.
• Verifiable and trustable information about participants
• Complies with Participant Information Service of IDSA architecture
• No adjustment of DSP necessary

Stakeholders

• MDS
• Mobilithek: Feature is required to comply with requirements and enhances compatibility with Mobilithek
• @jkbquabeck
• @SebastianOpriel

References

• See https://github.com/sovity/edc-ce/discussions/823 for contract negotiation sequence interception feasibility

Solution Design

Affected Areas and Components

• edc-ui
• edc-ce
• authority-portal catalog ui
• authority-portal API

General Requirements

• Compatibility with existing Connectors SHALL not be broken, but non-optimal UX is acceptable
• Information about the requestor MUST be available and be verified by the Data Space Authority: Legal name, commerce register number, website, main address, contact name, contact email
• ID (e.g. MDS ID) of requestor MUST be taken from authentication object (e.g. DAT of DAPS)
• API MUST be integrated into API Wrapper
• Documentation about API and manual negotiation steps MUST be adjusted (especially for systems)
• Postman Collection MUST be adjusted / enhanced
• After successfull confirmation the contract SHALL not differ from other established ones
• As a consumer I SHALL only be able to create one request per Connector if a Provider Confirmation Policy is applied. This SHALL only be checked on consumer side.
• The solution of displaying verified organization details, SHALL be designed in a way, that in the future the lookup can be replaced with receiving Verifiable Credentials from the consumer.
• The Provider Confirmation Policy is shown in the Policies tab, but SHALL not be deletable

Out of scope

• Cancelation of a negotiation request
• Delete data offer request after inactivity of x weeks
• A potential consumer shall be able to ask or notify the provider again
• UI notification section

Processes

End-user UX via UI

1. The user creates a data offer and is asked on the Contract Definition Creation Dialog, if the offering shall always be manually accepted.
2. The consumer identifies a data offer via the built-in catalog or broker. In both cases it is visible, via an icon in the overview and as well in the details, that the offer requires approval of the provider. As consumer I request a contract for choosen data offer. I can see on the Dashboard the status of pending sent requests (e.g. 3 requests pending) and see my requests also in Contracts section.
3. On a request, the provider can see organization details of the requestor and can accept or decline the request. In addition I can see on the Dashboard the status of pending decisions to make (e.g. 2 decisions necessary) and see these requests also on Contracts page.

Developer UX via API

• The developer creates a tipical data offer and simply adds a pre-defined "Provider Confirmation Policy" to the contract definition.

• An API endpoint is available to get a list of all pending decisions enriched with information about the requestor (via ParIS)

• An API endpoint is available to accept and one is available to decline a decision

• As an developer I can use a custom message and related method passing an ID or a set of IDs receive in return organization details about: participant ID, Legal Name, Commerce Register Number, Website, Main Address, Main Contact (name+email)

Product Increments / Releases

1) Proof of Concept

• EDC custom message for Participant Information Service
  • Integrate Message Handler (server stub) into catalog-crawler extension in :extensions:catalog-crawler:catalog-crawler
  • Integrate Common Module for the Message Type ~ the API in :extensions:sovity-messenger
• EDC policy implementation incl. enforcement
• API Wrapper endpoints to provide list of pending contracts (includes logic fetching validated information via new message type), accept and decline Participant Confirmation.
• EDC UI Catalog adjustement adding a hint about necessary confirmation
• Authority Portal Catalog UI adjustment adding a hint about necessary confirmation

2) Minimal viable Product

• Integration verified information in EDC UI:
  • Catalog Browser
  • Transfer History
  • Contracts
• EDC Dashboard integration
• Decision to use policy in Contract Creation Dialog or at appropriate place
• Accept/Decline policy on provider side

3) Later Stage

• Integrate extension into Logging House

Work Breakdown

### Connector UI
- [ ] The catalog page needs to correctly indicate negotiation statuses even after refreshing. 
- [ ] The data offer detail dialog needs to correctly indicate negotiation statuses even after refreshing.
- [ ] Split up Contract Agreement Page into consuming and providing pages.
- [ ] New Page: Consuming Contracts Page
  - [ ] Main page shows consuming contracts.
  - [ ] In another tab failed negotiations are shown.
  - [ ] In another tab running/Pending negotiations are shown.
  - [ ] Running/pending negotiations have an indicator if they require "provider interaction", i.e. if policy ProviderConfirmationPolicy is used in the negotiation.
  - [ ] Negotiations have an UiAsset and a UiPolicy for all details regarding the consumed data offer. Here we also run into the issue of no asset metadata being persisted on the consumer side. We would go the same solution as the transfer history page and default to an asset with just the ID.
- [ ] New Page: Providing Contracts Page
  - [ ] Main page shows providing contracts.
  - [ ] In another tab running negotiations are shown.
  - [ ] In another tab failed negotiations are shown.
  - [ ] On main page a section exists where running negotiations are shown that require user action.
  - [ ] In details view all necessary information about the requestor are shown. In addition the user can accept and reject the negotiation.
  - [ ] Negotiations have an UiAsset and a UiPolicy for all details regarding the consumed data offer. 
- [ ] On the dashboard we show a new Field with "pending negotiation requests", that is very noticeable and contains a quick link to the providing contracts page if non-zero.
- [ ] Implement checkbox on Contract Creation Dialog and combine existing policy with selected ones properly (open for better solutions)

### EDC-CE / API Wrapper
- [ ] Extension uses Access to AP DB to fetch necessary data
- [ ] Connector would need to know where the broker is (he could keep track with a custom db row or in memory): Implement by setting the URL of the Broker manually.
- [ ] Sending C2C Messages is a question of:
  - [ ] `sendMessage(String endpoint, SovityMessage myMessage)`
  - [ ] `registerHandler(String messageType, (claims) -> {})`
- [ ] both are in the EDC CE: the crawler and the EDC
- [ ] Implement default existing policy "ProviderConfirmationPolicy" created on startup. The policy is always bound to the scope of contract negotiation, not to catalog requests.
- [ ] Define API Changes: Dashboard, Negotiation Actions, Contract Requests that need user action
- [ ] Implement new Dashboard KPI
- [ ] Implement Negotiation Actions: Approve, Reject
- [ ] Implement Negotiation Action: List of Contract Requests which need user action
- [ ] Implement "Participant Information Service Extension"
  - [ ] Enrich list of Contract Requests with validated information
  - [ ] Enrich Contracts endpoint with validated consumer details
- [ ] Add another API Wrapper endpoint for Contract Details which adds all organization details of the counter-party consumer/provider. 

### Authority Portal
- [ ] Adjust data offers tiles at catalog page to indicate at least via an icon that the offer contains a PrivderConfirmationPolicy
- [ ] Adjust data offers details popup to indicate at least via an icon that the offer contains a PrivderConfirmationPolicy

Architecture

[richardtreier]

Notes regarding estimation:

[ip312]

Additional requirement from here:

• In the MDS 2.3. we add in the asset description an additional field "Data Provider" (name to be discussed), to reflect the special situation for the Mobilithek (three roles: 1) connector hoster and MDS participant; 2) Mobilithek participant; 3) data owner)
• In the MDS 2.3. we will present the second role in the Asset headline together with the first role (to be designed)

[AbdullahMuk]

Additional requirement from here:

• In the MDS 2.3. we add in the asset description an additional field "Data Provider" (name to be discussed), to reflect the special situation for the Mobilithek (three roles: 1) connector hoster and MDS participant; 2) Mobilithek participant; 3) data owner)
• In the MDS 2.3. we will present the second role in the Asset headline together with the first role (to be designed)

Given that we need clear separation of scope, this comment is not relevant for this issue but for https://github.com/sovity/PMO-Software/issues/1436.