Improve the provecontrol protocol documentation

did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.md

@@ -1,47 +1,64 @@
 # Prove Control Protocol
 
+This protocol is used a proof control of external identities.
 
--> Request verification
-<- Verification Challenge
--> Prove
-<- Confirm Verification
-
-type verificationType:
-- Email
-- DID
-- Discord
-- Tel
-- Domain
-- IP
-- Address
-
-fmgp.app/1/requestverification
- - `to`
- - `from`
- - `verificationType`
- - `subject`
-fmgp.app/1/verificationchallenge
- - `to`
- - `from`
- - `verificationType`
- - `subject`
- - `secret` (only the 'to' can see)
-fmgp.app/1/prove
- - `to`
- - `from`
- - `verificationType`
- - `subject`
- - `proof`
-fmgp.app/1/confirmverification
- - `to`
- - `from`
- - `verificationType`
- - `subject`
- - `attachments`
 
+- **Verifier** - The Verifier is a well-known DID that is trusted and the provides a verification service. It will challenge the User to prove the control over other identity. It then issues a statement (VC) as the User was control over that external identity.
+- **User** - The User is another DID that they have other identities (like an email) and wants to prove control over it.
+
+## Type verificationType:
+  - Email (read)
+    > User proof is able to read email on a specific email address. By receiving an email that contains an encrypted message for the User, which the user can create the message `prove` to send directly Verifier. <span style="color:red">Note: it can be a shared email</span>
+  - Domain
+    > User proof that it's in control of the Domain by being able to edit the content in the DNS server.
+      By creating a new entry of the type `TXT` when the key is the `id` of the message `verificationchallenge`, and the value is the `proof` of the message `prove`.
+  - Discord (read)
+    > User proof is able to read direct message on a specific account.
+  - Tel (read)
+    > User proof that the able to receive SMS to a specific number.
+    <span style="color:red">Note: An encrypted message is probably too big for a SMS</span>
+  - DID
+    > User proof is in possession of the private keys of (other) DID by reading and signing a statement with one of those keys.
+  - IP (read)
+    > <span style="color:red">Note: The IP probably too ephemeral</span>
+  - Address (read)
+    > User proof is able to receive physical mail. Like Google use case to verify shop owners.
+
+## message structure
+
+- fmgp.app/provecontrol/1/requestverification
+  > This message is a request from the User to Verifier. To start the verification process over some specific subject (liek an email address, a domain, etc)
+  - `to`
+  - `from`
+  - `verificationType`
+  - `subject`
+- fmgp.app/provecontrol/1/verificationchallenge
+  > This is encrypted message from the Verifier to the User. That challenge the User according to the `verificationType`.
+  - `to`
+  - `from`
+  - `verificationType`
+  - `subject`
+  - `secret` (only the 'to' can see, because the message is encrypted)
+- fmgp.app/provecontrol/1/prove
+  > This message is from the User to the Verifier.
+  - `to`
+  - `from`
+  - `verificationType`
+  - `subject`
+  - `proof`
+- fmgp.app/provecontrol/1/confirmverification
+  > This is a sign message from the Verifier to the User. It works like a VC verifiable credential. It's a statement from the Verifier that confirms that the User proofed the `verificationType` about the subject to him. The user can use this statement (VC) to show other DIDs that trust this Verifier.
+  - `to`
+  - `from`
+  - `verificationType`
+  - `subject`
 
 ## Calculate Proof
 
+The `proof` is a string (in the message `prove`) that can only be generated. From the decrypted `verificationchallenge` message type.
+
+Should be calculated according to the following:
+
 ```scala
 def calculateProof(
     verifier: DIDSubject, // TO in Prove == FROM in VerificationChallenge
@@ -52,7 +69,32 @@ def calculateProof(
 ) = SHA256.digestToHex(s"$verifier|$hoder|$verificationType|$subject|$secret")
 ```
 
-# Connection Gateway Protocol
 
--> Register
-<- Registration
+## Flow
+
+1. `User -> Verifier` (optional) : requestverification
+2. `User <- Verifier` : verificationchallenge
+3. `User -> Verifier` : prove
+4. `User <- Verifier` : confirmverification
+
+```mermaid
+sequenceDiagram
+  participant I as Extrenal_Identity
+  participant W as Wallet
+  participant V as Verifier
+
+  Note over W: User wallet
+  Note over I: User Identity to verify like Email/Tel/Discord/etc
+  Note over V: A DID that provide a service to verify control of external identity.
+
+  %%rect rgb(191, 223, 255)
+    W->>+V: 'request verification' DID Comm over http
+    V->>-I: 'verification_challenge' DID Comm over Email
+    I-->>W: open the encryted DID Comm Msg
+    W-->>W: decrypt the message and generate
+    W-->>W: generate a proof that you were able to read the message
+    W->>+V: 'prove' (DID Comm Msg over http)
+    V->>-W: 'confirm_verification' sign DID Comm Msg  over http
+    W-->>W: Store the 'confirm_verification' sign DID Comm Msg as a VC
+  %%end
+```

did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.scala

@@ -53,7 +53,7 @@ case class RequestVerification(
 }
 
 object RequestVerification {
-  def piuri = PIURI("https://fmgp.app/provecontrol/0.1/requestverification")
+  def piuri = PIURI("https://fmgp.app/provecontrol/1/requestverification")
 
   protected final case class Body(verificationType: VerificationType, subject: String) {
 
@@ -133,7 +133,7 @@ case class VerificationChallenge(
 
 /** This message MUST be send using the transport in 'verificationType' */
 object VerificationChallenge {
-  def piuri = PIURI("https://fmgp.app/provecontrol/0.1/verificationchallenge")
+  def piuri = PIURI("https://fmgp.app/provecontrol/1/verificationchallenge")
 
   export Prove.calculateProof
 
@@ -198,7 +198,7 @@ case class Prove(
 }
 
 object Prove {
-  def piuri = PIURI("https://fmgp.app/provecontrol/0.1/prove")
+  def piuri = PIURI("https://fmgp.app/provecontrol/1/prove")
 
   def calculateProof(
       verifier: DIDSubject, // TO in Prove == FROM in VerificationChallenge
@@ -273,7 +273,7 @@ case class ConfirmVerification(
 }
 
 object ConfirmVerification {
-  def piuri = PIURI("https://fmgp.app/provecontrol/0.1/confirmverification")
+  def piuri = PIURI("https://fmgp.app/provecontrol/1/confirmverification")
 
   protected final case class Body(verificationType: VerificationType, subject: String) {
 

did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/UserRegister.md

@@ -0,0 +1,41 @@
+# User Register Protocol
+
+TODO 
+
+## User Registration process of Extrenal Identity
+
+```mermaid
+sequenceDiagram
+  participant W as Wallet
+  participant R as Registy
+  participant O as Another_DID
+  
+  Note over R: A DID that provide a service of connecting
+  
+  %% rect rgb(191, 180, 255)
+    Note over W,O: Registration logic TODO
+    W->>+R: 'registar' DID Comm over http
+    R->>-W: 'registration_status'
+
+    Note over W,O: Add Information logic 
+    W->>+R: 'add' DID Comm over http
+    R->>R: check the VC ('fmgp.app/provecontrol/1/confirmverification') inside 'add' message. Must be valid and from a DID that is trust worth.
+    R->>-W: 'registration_status'
+  %% end
+
+  %% rect rgb(191, 223, 200)
+    Note over W,O: Query Logic
+    O->>+R: Ask to get in connect with the extrenal Identity
+    R->>+W: Infor the DID that controls the external identity
+    R->>-O: Informed that external identity is or not Registered
+    W->>-O: Start a conversation
+  %% end
+
+%%   rect rgb(191, 180, 255)
+%%   end
+
+%%   rect rgb(250, 223, 200)
+%%     loop Do (M) Operations
+%%     end
+%%   end
+```