docs: how to configure the mediator (#60)

How to configure the mediator
Update Coordinate-Mediation-Protocol.md
For ATL-5359

Signed-off-by: Fabio Pinheiro <fabiomgpinheiro@gmail.com>
Co-authored-by: Anton Baliasnikov <Anton.baliasnikov@iohk.io>

Coordinate-Mediation-Protocol.md

@@ -0,0 +1,107 @@
+# Coordinate Mediation Protocol
+
+This protocol is a part of the [DIDComm](https://didcomm.org/).
+
+It coordinates the mediation configuration between a mediating agent and the recipient.
+
+This protocol follows the request-response message exchange pattern, and only requerires the simple state of waiting for a response or to produce a response.
+
+For a detailed description of the protocol, please, see [Mediator Coordination v2.0](https://didcomm.org/mediator-coordination/2.0/).
+
+## PIURI
+
+- `https://didcomm.org/coordinate-mediation/2.0/mediate-request`
+  **- Mediate Request**
+- `https://didcomm.org/coordinate-mediation/2.0/mediate-deny`
+  **- Mediate Deny** (possible response to deny mediate-request)
+- `https://didcomm.org/coordinate-mediation/2.0/mediate-grant`
+  **- Mediate Grant** (possible response to grant mediate-request)
+
+- `https://didcomm.org/coordinate-mediation/2.0/keylist-update`
+  **- Keylist Update**
+- `https://didcomm.org/coordinate-mediation/2.0/keylist-update-response`
+  **- Keylist Response** (response to keylist-update)
+
+- `https://didcomm.org/coordinate-mediation/2.0/keylist-query`
+  **- Keylist Query**
+- `https://didcomm.org/coordinate-mediation/2.0/keylist`
+  **- Keylist** (response to keylist-query)
+
+### Roles
+
+- mediator
+  - The agent that will be receiving forward messages on behalf of the recipient.
+- recipient
+  - The agent for whom the forward message payload is intended.
+
+### Messagem Flow Diagram
+
+```mermaid
+flowchart TD
+  MediateRequest --> MediateDeny
+  MediateRequest --> MediateGrant
+
+  KeylistUpdate --> KeylistUpdateResponse
+
+  KeylistQuery --> Keylist
+```
+
+### Mediator state machine
+
+```mermaid
+stateDiagram-v2
+  state MediateRequested <<choice>>
+  [*] --> MediateRequested: Receive 'mediate-request'
+  MediateRequested --> StoreNewMediateConfig
+  StoreNewMediateConfig --> [*]: 'mediate-grant'
+  MediateRequested --> [*]: 'mediate-deny'
+
+  state if_sate2 <<choice>>
+  [*] --> if_sate2: Receive 'keylist-update'
+  if_sate2 --> UpdateKeylist
+  UpdateKeylist -->  [*]: 'keylist-update-response'
+  if_sate2 --> [*]: ignore
+
+  state KeylistQueried <<choice>>
+  [*] --> KeylistQueried: Receive 'keylist-query'
+  KeylistQueried --> [*]: 'keylist'
+  KeylistQueried --> [*]: ignore
+```
+
+### Recipient state machine
+
+```mermaid
+stateDiagram-v2
+  direction LR
+  state fork_state <<fork>>
+  [*] --> fork_state
+  fork_state --> RequestMediation
+  fork_state --> RequestKeylistUpdate
+  fork_state --> QueryKeylist
+
+  state RequestMediation {
+    [*] --> MediationRequested: send 'mediate-request'
+    MediationRequested --> MediationDenied: 'mediate-deny'
+    MediationRequested --> MediationRequested: timeout (retry)
+    MediationRequested --> [*]: giveup
+    MediationDenied --> [*]
+    # MediationDenied --> MediationRequested: retry?
+    MediationRequested --> MediationGrant: 'mediate-grant'
+    MediationGrant --> [*]
+  }
+
+  state RequestKeylistUpdate {
+    [*] --> KeylistUpdateRequested: send 'keylist-update'
+    KeylistUpdateRequested --> KeylistUpdateRequested: timeout (retry)
+    KeylistUpdateRequested --> [*]: giveup
+    KeylistUpdateRequested --> KeylistUpdated: 'keylist-update-response'
+    KeylistUpdated --> [*]
+  }
+
+  state QueryKeylist {
+    [*]--> KeylistQueried: send 'keylist-query'
+    KeylistQueried --> KeylistQueried: timeout (retry)
+    KeylistQueried --> [*]: giveup
+    KeylistQueried --> [*]: 'keylist'
+  }
+```

README.md

@@ -10,8 +10,8 @@ graph LR
   M--pickup-->D((Reciever))
 ```
 
- - **CI** automate builds and tests all pushes to the main branch also as all PRs created.
- - **Scala Steward** automate 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.
+ - **CI** automate builds and tests all push to the main branch also as all PRs created.
+ - **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:**
@@ -23,32 +23,33 @@ DID Comm v2 (Decentralized Identifiers Communication Version 2) is a protocol en
 
 
 - Establishing Logical Connections - The Mediator empowers entities, which could be individuals or organizations, to forge secure connections amongst themselves. Each entity possesses a unique DID that acts as its identifier within the decentralized network.
-- DID resolution - When an entity seeks to communicate with another, it resolves the recipient's DID to procure the information necessary to establish a connection. This resolution procedure entails retrieving the recipient's public key and correlated metadata from decentralized identity infrastructure, which could be a blockchain or distributed ledger.
-- Message encryption - The sender employs a double encryption technique for the message: initially for the ultimate receiver, and subsequently encapsulates the encrypted message within another encryption layer for the Mediator. This is achieved using the public keys of both the Mediator and the recipient obtained through the DID resolution process. The dual encryption ensures that only the intended recipient has the capacity to decrypt and access the message.
+- DID resolution - When an entity seeks to communicate with another, it resolves the recipient's DID to procure the information necessary to establish a connection. This resolution procedure entails retrieving the recipient's public key and correlated metadata from a decentralized identity infrastructure, which could be a blockchain or distributed ledger.
+- Message encryption - The sender employs a double encryption technique for the message: initially for the ultimate receiver, and subsequently encapsulates the encrypted message within another encryption layer for the Mediator. This is achieved using the public keys of both the Mediator and the recipient obtained through the DID resolution process. Dual encryption ensures that only the intended recipient has the capacity to decrypt and access the message.
 
 ```mermaid
 graph LR
-  subgraph Encryted message to Mediator
-    subgraph Encryted message to Reciever
-    id1[[The planetext message]]
+  subgraph Encrypted message to Mediator
+    subgraph Encrypted message to Reciever
+    id1[[The plaintext message]]
     end
   end
 ```
 
 - Message routing - The sender transmits an encrypted message to the Mediator, which serves as a routing agent. In this role, the Mediator receives messages from the sender, decrypts one layer, and forwards them to the appropriate recipient based on the recipient's DID.
 - Mediation process- The Mediator verifies the authenticity and integrity of the incoming message by checking the digital signature attached to it. This signature ensures that the message was indeed sent by the claimed sender and that it hasn't been tampered with during transmission.
 
-- Message decryption - After verifying the message's authenticity, the Mediator decrypted one layer of the message using the mediator's private key, which is securely held by the mediator. Once decrypted, the next message becomes readable (the final planetext intended for the final user it's still encrypted).
+- Message decryption - After verifying the message's authenticity, the Mediator decrypted one layer of the message using the mediator's private key, which is securely held by the mediator. Once decrypted, the next message becomes readable (the final plaintext intended for the final user it's still encrypted).
 - Optional processing - The Mediator may perform additional processing on the message based on predefined rules or business logic. This could include applying filters, applying policies, or invoking external services.
 - Message forwarding - If necessary, the Mediator can further forward the decrypted message to additional entities in the communication flow. This enables multi-party communication scenarios.
 
-By acting as an intermediary, the DID Comm v2 Mediator helps facilitate secure and private communication between entities while leveraging the decentralized nature of DIDs and cryptographic techniques to ensure authenticity, integrity, and confidentiality of the messages exchanged.
+By acting as an intermediary, the DID Comm v2 Mediator helps facilitate secure and private communication between entities while leveraging the decentralized nature of DIDs and cryptographic techniques to ensure the authenticity, integrity, and confidentiality of the messages exchanged.
 
-The mediator is especially useful when the edge entities are not always online, like mobile paradigm. Usually, we can assume that the mediator is always online.
+The mediator is especially useful when the edge entities are not always online, like the mobile paradigm. Usually, we can assume that the mediator is always online.
 
 ## Protocols
 - [DONE] `BasicMessage 2.0` - https://didcomm.org/basicmessage/2.0
 - [DONE] `MediatorCoordination 2.0` - https://didcomm.org/mediator-coordination/2.0
+ - See [link for the protocol specs](/Coordinate-Mediation-Protocol.md)
 - [TODO] `MediatorCoordination 3.0` - https://didcomm.org/mediator-coordination/3.0
 - [DONE] `Pickup 3` - https://didcomm.org/pickup/3.0
 - [DONE] `TrustPing 2.0` - https://didcomm.org/trust-ping/2.0/
@@ -68,24 +69,45 @@ The webapp/webpage is atm just to show the QRcode with out of band invitation fo
 
 **Open the webpage for develop** - open> `file:///.../webapp/index-fastopt.html`
 
+### Configure the Mediator
+
+The default configuration is set up [application.conf](/mediator/src/main/resources/application.conf).
+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:
+
+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).
+- `KEY_AUTHENTICATION_D` - is the key authentication private key (MUST be an Ed25519 OKP key type).
+- `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.
+
+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_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 the database.
+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 have a single page application that will give the final user a invitation page.
+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`
 
 First build to docker image with `NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal`.
-The latest stable image version can also downloaded from the IOHK repositories.
+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.
-You will need to create the table and indexs before start the backend service. See the file `initdb.js`.
+You will need to create the table and indexes before starting the backend service. See the file `initdb.js`.
 
 ### Deploy
 
-You can easy deploy the image everywhere. We recommend a minimum of 250 mb ram to run the mediator backend service.
+You can easily deploy the image everywhere. We recommend a minimum of 250 mb ram to run the mediator backend service.