diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..ab3df964 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# code +* @FabioPinheiro @mineme0110 + +# E2E tests: +/tests/ @antonbaliasnikov + +# Docs: +*.md @petevielhaber \ No newline at end of file diff --git a/Mediator-Error_Handling.md b/Mediator-Error_Handling.md index 7266455a..5d884041 100644 --- a/Mediator-Error_Handling.md +++ b/Mediator-Error_Handling.md @@ -1,11 +1,7 @@ # Error Handling - -More info see https://input-output.atlassian.net/browse/ATL-5236 - https://identity.foundation/didcomm-messaging/spec/#problem-reports - On each step of all our protocols processing, when something wrong is happening, we need to: Goals - Update the record to a documented error state @@ -16,8 +12,6 @@ Goal other: error recover/resilient - [optional] Send event that record state changed to error - Decide on the policy of re-trying sending errors (one of the proposals is just to send it once, and if a recipient did not get this, then it’s on its own requesting record ID state) - - Note: most errors in Mediator will be synchronous - Store messages when sending (1w) @@ -28,31 +22,30 @@ Note: most errors in Mediator will be synchronous - [WIP] - (sync & async) e.p.crypto.replay - if the message is replay (possible he replay attack). - (sync) e.p.req - pickup message before enroling. - - [QA] StatusRequest - https://didcomm.org/messagepickup/3.0/status-request - - [QA] DeliveryRequest - https://didcomm.org/messagepickup/3.0/delivery-request + - [DONE] StatusRequest - https://didcomm.org/messagepickup/3.0/status-request + - [DONE] DeliveryRequest - https://didcomm.org/messagepickup/3.0/delivery-request - (sync) e.p.me.res.storage - connection MongoBD is not working. - - [QA] catch all StorageCollection Error + - [DONE] catch all StorageCollection Error - (sync) e.p.me.res.storage - business logic MongoBD is not working. - - [QA] catch all StorageThrowable + - [DONE] catch all StorageThrowable - (sync) e.p.did - for any DID method that is not `did.peer`. - (sync) e.p.did.malformed - for any DID method malformed. - (sync) e.p.msg - for parsing error from the message. - - [QA] All parsing errors from the decrypt function + - [DONE] All parsing errors from the decrypt function - [TODO] parsing for a specific data model of each protocol - (sync) e.p.msg.unsupported - for the message type LiveModeChange and all message that is not role of the mediator - - [QA] MediateGrant - - [QA] MediateDeny - - [QA] KeylistResponse - - [QA] Status - https://didcomm.org/messagepickup/3.0/status - - [TODO] ... + - [DONE] MediateGrant + - [DONE] MediateDeny + - [DONE] KeylistResponse + - [DONE] Status - https://didcomm.org/messagepickup/3.0/status - LiveModeChange Not Supported - - [QA] "e.m.live-mode-not-supported" - https://didcomm.org/messagepickup/3.0/live-delivery-change + - [DONE] "e.m.live-mode-not-supported" - https://didcomm.org/messagepickup/3.0/live-delivery-change - (sync) e.p.msg.unsupported - for parsing error due to unsupported version or protocol. - - [QA] MissingProtocolExecuter (unsupported protocol it also works fine for unsupported versions) + - [DONE] MissingProtocolExecuter (unsupported protocol it also works fine for unsupported versions) - (sync & async) e.p.req.not_enroll - Get a Forward message to a DID that is not enrolled. - - [QA] Send a Problem Report if the next DID is not enrolled in the Mediator. + - [DONE] Send a Problem Report if the next DID is not enrolled in the Mediator. - (sync & async) e.p.me - catch all error at the end. - - [WIP] + - [DONE] - Receive a problem report (1w): - in case of Warnings Reply `w.p` -> log warnings and escalate to an error `e.p` on the reply - in case of Error `e.p` -> log error @@ -63,3 +56,116 @@ Note: most errors in Mediator will be synchronous - [optional] update the protocol with new tokens (2d) - `e.p.me.res.storage` - `e.p.me.res.not_enroll` + +# Problem Reports in Mediator flow + +https://didcomm.org/coordinate-mediation/2.0/mediate-request + +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + + [*] -->Recipient + Recipient --> mediation_request_received:mediation request message(1) + mediation_request_received --> request_stored :received mediation request message (2) + request_stored --> request_processing:{Mediation request processing} (3) + request_processing -->Recipient: Mediation Grant message reply Sync (4) + request_processing -->Recipient: Mediation Deny message reply Sync (4) + request_processing -->Recipient: Problem report message reply sync (4) + class request_processing processing +``` + +https://didcomm.org/coordinate-mediation/2.0/keylist-update +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + classDef grant fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + mediation_granted -->Recipient + Recipient --> Key_list_update_request:key list update request message(1) + Key_list_update_request --> request_stored :received Key list update request message (2) + request_stored --> request_processing:{Key list update request processing} (3) + request_processing -->Recipient: Key list update Response message reply Sync (4) + request_processing -->Recipient: Problem report message reply sync (4) + class request_processing processing + class mediation_granted grant +``` + +https://didcomm.org/coordinate-mediation/2.0/keylist-query +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + classDef grant fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + mediation_granted -->Recipient + Recipient --> Key_list_query_request:key list query request message(1) + Key_list_query_request --> request_stored :received Key list query request message (2) + request_stored --> request_processing:{Key list query request processing} (3) + request_processing -->Recipient: Key list query Response message reply Sync (4) + request_processing -->Recipient: Problem report message reply sync (4) + class request_processing processing + class mediation_granted grant +``` + +Pickup 3.0 https://didcomm.org/pickup/3.0 + +https://didcomm.org/messagepickup/3.0/status-request +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + classDef success fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + mediation_granted --> Key_list_updated + Key_list_updated -->Recipient + Recipient --> status_request:status request message(1) + status_request --> request_stored :received status request message (2) + request_stored --> request_processing: status request processing (3) + request_processing -->Recipient: status Response message reply Sync (4) + request_processing -->Recipient: Problem report message reply sync (4) + class request_processing processing + class mediation_granted,Key_list_updated success +``` +https://didcomm.org/messagepickup/3.0/delivery-request +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + classDef success fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + mediation_granted --> Key_list_updated + Key_list_updated -->Recipient + Recipient --> Key_list_query_request:Delivery request message(1) + Key_list_query_request --> request_stored :received Delivery request message (2) + request_stored --> request_processing:{Delivery request processing} (3) + request_processing -->Recipient: Delivery Response message reply Sync (4) + request_processing -->Recipient: Problem report message reply sync (4) + class request_processing processing + class mediation_granted,Key_list_updated success +``` + +https://didcomm.org/messagepickup/3.0/messages-received +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + classDef success fill:#0a0,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + mediation_granted --> Key_list_updated + Key_list_updated -->Recipient + Recipient --> Key_list_query_request:messages-received request message(1) + Key_list_query_request --> request_stored :messages-received request message (2) + request_stored --> request_processing:{messages-received request processing} (3) + request_processing -->Recipient: messages-received Response message reply Sync (4) + request_processing -->Recipient: Problem report message reply sync (4) + class request_processing processing + class mediation_granted,Key_list_updated success +``` + + +Sender to Recipient (Sender use the type forward message) +https://didcomm.org/routing/2.0/forward +```mermaid +stateDiagram-v2 + classDef processing fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow + [*] --> Sender + Sender --> forward_message_request:forward message request(1) + forward_message_request --> request_stored :forward request message (2) + request_stored --> request_processing:{forward message request processing} (3) + request_processing --> forward_message_stored: message stored (4) + request_processing -->Sender: Problem report Signed message reply sync (4) + forward_message_stored --> [*] + class request_processing processing +``` \ No newline at end of file diff --git a/README.md b/README.md index 4faaef00..cd4b3be9 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,21 @@ graph LR - **Scala Steward** automates the creation of pull requests for libraries with updated dependencies, saving maintainers time and effort. It can also help ensure that libraries are kept up-to-date, improving their reliability and performance. -**More documentation:** -- [LICENSE](LICENSE) - Apache License, Version 2.0 +# Table of contents: +- [Mediator Purpose](#Description) +- [Protocols Supported](#Protocols) + - [Mediator Protocol State and Flow](Coordinate-Mediation-Protocol.md) +- [Pre-reqs](#pre-reqs) +- [Getting started](#getting-started) + - [Docker only](#docker-only) +- [Configuring the mediator](#configure-the-mediator) + - [Mediator identity](#identity) + - [Mediator storage](#mediator-storage) + - [Mediator-Storage-In-cloud](#mongodb-in-cloud) +- [Mediator Deployment](#deploy) +- [Mediator Test suite](#mediator-tests) +- [Mediator Error Handling](Mediator-Error_Handling.md#error-handling) +- [Mediator protocols state flow with problem reporting](Mediator-Error_Handling.md#problem-reports-in-mediator-flow) ## Description @@ -53,21 +66,47 @@ The mediator is especially useful when the edge entities are not always online, - [TODO] `MediatorCoordination 3.0` - https://didcomm.org/mediator-coordination/3.0 - [DONE] `Pickup 3` - https://didcomm.org/pickup/3.0 [ with exclusion of When the delivery request (https://didcomm.org/messagepickup/3.0/delivery-request) is made, but there are no messages currently available to be sent, No status message is sent immediately, Instead you can check the the status of message using the status request https://didcomm.org/messagepickup/3.0/status-request] - [DONE] `TrustPing 2.0` - https://didcomm.org/trust-ping/2.0/ +- [DONE] `Report Problem 2.0` https://didcomm.org/report-problem/2.0/ -## How to run -### server +# Pre-reqs -**Start the server**: - - shell> `docker-compose up mongo` - - sbt> `mediator/reStart` -### webapp +To build and run this mediator, locally you will need a few things: +- Install [Docker](https://docs.docker.com/get-docker/) +- Install [SBT](https://www.scala-sbt.org/download.html) -The webapp/webpage is atm just to show the QRcode with out of band invitation for the Mediator. +# Getting started +This DIDComm Mediator comprises two elements: a backend service and a database. +The backend service is a JVM application, and the database used is MongoDB. +The backend service is also a web service with a single-page application that will give the final user an invitation page -**Compile** - sbt> `webapp / Compile / fastOptJS / webpack` +- Clone the repository +``` +git clone git@github.com:input-output-hk/atala-prism-mediator.git +``` +``` +shell> cd atala-prism-mediator +shell> docker-compose up mongo +``` +In another shell from the project root directory `atala-prism-mediator` +``` +shell> sbt +sbt> mediator/reStart +``` +By default mediator will start on port 8080 -**Open the webpage for develop** - open> `file:///.../webapp/index-fastopt.html` +You can open the `http://localhost:8080/` URL in a web browser, and it will show a QR code that serves as an out-of-band invitation for the Mediator. + +## How to run mediator as docker image +# Docker only +It is possible to run everything with a single command with Docker compose docker-compose.yml +The latest stable image version is available in the IOHK repositories. +To build a docker image locally, run NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal. +``` +shell> cd atala-prism-mediator +shell> NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal +shell> MEDIATOR_VERSION=$(sbt "print mediator/version" --error) docker-compose up +``` ### Configure the Mediator @@ -75,6 +114,7 @@ The default configuration is set up [application.conf](/mediator/src/main/resour So in order to configure the mediator for your needs. You can either change the default configuration or you can set up environment variables that overrides the defaults: +# identity To set up the mediator identity: - `KEY_AGREEMENT_D` - is the key agreement private key (MUST be a X25519 OKP key type). - `KEY_AGREEMENT_X` - is the key agreement public key (MUST be a X25519 OKP key type). @@ -82,32 +122,26 @@ To set up the mediator identity: - `KEY_AUTHENTICATION_X` - is the key authentication public key (MUST be an Ed25519 OKP key type). - `SERVICE_ENDPOINT` - is the endpoint of the mediator. Where the mediator will be listening to incoming DID Comm messages. +# mediator-storage To set up the mediator storage (MongoDB): - `MONGODB_PROTOCOL` - is the protocol type used by mongo. - `MONGODB_HOST` - is the endpoint where the MongoDB will be listening. - `MONGODB_PORT` - is the endpoint's port where the MongoDB will be listening. -- `MONGODB_USER` - is the user name used by the Mediator service to connect to the database. +- `MONGODB_USER` - is the username used by the Mediator service to connect to the database. - `MONGODB_PASSWORD` - is the password used by the Mediator service to connect to the database. - `MONGODB_DB_NAME` - is the name of the database used by the Mediator. -## Run - -This DIDComm Mediator is composed of two elements, a backend service, and a database. -The backend service is a JVM application and the database used is MongoDB. -The backend service is also a web service that has a single-page application that will give the final user an invitation page. - -### Run localy - -Everything can be run with a single command with Docker compose `docker-compose.yml` +### MongoDB In cloud -First build to docker image with `NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal`. -The latest stable image version can also be downloaded from the IOHK repositories. - -### MongoBD - -Docker compose would do that for you but if you are running separately or on the cloud like MongoDB Atlas. +Using the mongodb from cloud like MongoDB Atlas. You will need to create the table and indexes before starting the backend service. See the file `initdb.js`. ### Deploy You can easily deploy the image everywhere. We recommend a minimum of 250 mb ram to run the mediator backend service. + +# mediator-tests +https://github.com/input-output-hk/didcomm-v2-mediator-test-suite +https://input-output-hk.github.io/didcomm-v2-mediator-test-suite/Reports.html + +- [LICENSE](LICENSE) - Apache License, Version 2.0 \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 24f88f90..9faaf783 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -14,7 +14,7 @@ services: - ./initdb.js:/docker-entrypoint-initdb.d/initdb.js atalaprism-mediator: - image: ghcr.io/input-output-hk/atala-prism-mediator:${MEDIATOR_VERSION:-0.2.0-SNAPSHOT} + image: ghcr.io/input-output-hk/atala-prism-mediator:${MEDIATOR_VERSION} ports: - "8080:8080" environment: