When sharing an item, a block of text can be added to the share, there is no required structure for these terms but something like the following should give you some idea of how it might be used.
I have allowed on-sharing on this item but before any on-sharing takes place call me on my phone to confirm it with me.
or
This information on this item is being shared for the express purpose of applying for a home loan, it is not to be shared with anyone for the purposes of marketing or analysis.
or
This information contains non-public business information and is for the eyes of Anthony Edward Stark only.
When creating a share there is an option to set whether acceptance of the terms and share is required, the settings allowed are acceptance_required
and acceptance_not_required
. Before the recipient of the share can view the data they must explicitly accept the share and it's terms via a second API call.
When a user shares an item with another user there is an option to allow or dis-allow sharing of that item with another person, this is called the "sharing mode". The sharing mode currently has two options available on it, either owner
or everyone
. The owner
sharing mode means the share can not be on-shared to another user. The anyone
option means that the item can be on-shared to anyone. While the system will allow any on-sharing to happen when the sharing mode is set to anyone
it is also important to check the terms
that have set on the share.
Due to use of e2e (end to end) encryption the client (client application) is the only place where data can be decrypted and re-encrypted. Sometimes there are tasks that do not need to happen right away when an action takes place but they will need to be done on the client at some point. An example of this is updating shares, for example...
If a Alice has shared an item with Bob and some time later Alice changes the data in the shared item the share will also need to be updated.
The data in Alice's items is encrypted with a DEK (data encryption key) that only Alice has access to, this means the server can not re-encrypt the data with a shared DEK on behalf of Alice, instead the server creates a ClientTask
.
Periodically Alice's client will check to see if there are any ClientTask
s that need to be executed.
Alice's client will pick up the ClientTask
of type update_shares
which will tell it to download and decrypt the modified item then re-encrypt the data with a shared DEK and update the share with the new data.
(it's recommended to complete the getting-started/quickstart guide before follwing this example)
(NOTE: each user will see the shared item as different item_id
, when referencing the item by id be sure to use the item_id
applicable to the user making the request)
First lets create three users.
meeco users:create -p supersecretpassword > .alice.yamlmeeco users:create -p supersecretpassword > .bob.yamlmeeco users:create -p supersecretpassword > .carlos.yaml
Next lets connect Alice to Bob, then Bob to Carlos.
meeco connections:create-config --from .alice.yaml --to .bob.yaml > .connection1_config.yamlmeeco connections:create -c .connection1_config.yaml > .connection1.yamlmeeco connections:create-config --from .bob.yaml --to .carlos.yaml > .connection2_config.yamlmeeco connections:create -c .connection2_config.yaml > .connection2.yaml
We create an item for Alice.
meeco items:create-config vehicle -a .alice.yaml > .vehicle_config.yaml# open up the .vehicle.yaml and add an item label and other datameeco items:create -i .vehicle_config.yaml -a .alice.yaml > .vehicle.yaml
Share that item from Alice to Bob, with some share terms
, acceptance_required
, and sharing mode of anyone
.
meeco shares:create-config -i $VEHICLE_ITEM_ID -f .alice.yaml -c $CONNECTION_1_FROM_USER_ID > .share1-config.yamlmeeco shares:create \--config .share1-config.yaml \--sharing_mode="anyone" \--terms="You may not use this information for advertising" \--acceptance_required="acceptance_required" \> .share1.yaml
Read the share as Bob.
meeco items:list -a .bob.yaml
You will get a result something like the following...
kind: Itemsspec:- id: 8e26d96f-7c15-444d-97a5-30e39b418c9down: falselabel: DeLoreandescription: nullcreated_at: 2020-10-12T05:52:45.395Zitem_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0item_template_label: Vehicleslot_ids:- 642ea490-ccce-49cc-9fef-d5d9c6668549...me: falsebackground_color: nulloriginal_id: dc66140c-3572-49b8-ad97-ec6de21827baowner_id: 94c27129-e179-4c69-a7f1-94438b920541share_id: b358bc99-89f1-48f3-8b84-8dad0516643e...
Note the share_id from above.
Next Bob will accept the share from Alice.
meeco shares:accept -y $EXISTING_SHARE_ID -a .bob.yaml
Now Bob can share this item with Carlos.
meeco shares:create-config -o $EXISTING_SHARE_ID -f .bob.yaml -c $CONNECTION_2_FROM_USER_ID > .share2-config.yamlmeeco shares:create \--config .share2-config.yaml \--sharing_mode="anyone" \--terms="You may not use this information for advertising" \--acceptance_required="acceptance_required" \> .share2.yaml
Carlos can now see the share.
meeco items:list -a .carlos.yaml
Returning something like...
kind: Itemsspec:- id: 59cb375f-6188-46fd-bdd6-ba730ae3282cown: falselabel: DeLoreandescription: nullcreated_at: 2020-10-13T05:41:02.376Zitem_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0item_template_label: Vehicleslot_ids:- e90e38f2-65d7-4203-b74f-0831dab393c1...original_id: dc66140c-3572-49b8-ad97-ec6de21827baowner_id: 94c27129-e179-4c69-a7f1-94438b920541share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c
Noting the share_id and item_id from the above command.
Accept it.
meeco shares:accept $EXISTING_SHARE2_ID -a .carlos.yaml
And view it.
meeco items:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yamlormeeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml
Getting the output something like...
kind: Itemspec:id: 59cb375f-6188-46fd-bdd6-ba730ae3282cown: falselabel: DeLoreanitem_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0item_template_label: Vehicleslot_ids:- 81cc655f-5ae8-4a7a-afc0-3d186ab3f736...me: falsebackground_color: nulloriginal_id: dc66140c-3572-49b8-ad97-ec6de21827baowner_id: 94c27129-e179-4c69-a7f1-94438b920541share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31cslots:- id: 81cc655f-5ae8-4a7a-afc0-3d186ab3f736own: falseshare_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31cname: licence_plateitem_id: 59cb375f-6188-46fd-bdd6-ba730ae3282cslot_type_name: key_valueencrypted_value: Aes256Gcm.AjR9r_An-mcqLla1dcGL.QUAAAAAFaXYADAAAAACcR_n2XVORiZ2wRjgFYXQAEAAAAACCNE5L6Gqq-4Zmm5Y8AgVEAmFkAAUAAABub25lAAA=encrypted_value_verification_key: Aes256Gcm.f4af1rELcDkDJQv7wPsfvOOVbnI6YyQlsnYLdDdekAZ2AcXm6Oq7WrgGytc3gUbvjnWvmkzAnWO2s2Kya0ZxLQ==.QUAAAAAFaXYADAAAAABQ346yXewWcSdSdBEFYXQAEAAAAACyZph19u-eZ-BWMPhrOqP4AmFkAAUAAABub25lAAA=value_verification_hash: d8c6e5f28837906505fa9e6a4740c8ddd5dddbe4b51675ae3daabef4a27d701blabel: Vehicle registration numberoriginal_id: 5503d256-19d6-45f8-b76b-9605f977cd3fowner_id: 94c27129-e179-4c69-a7f1-94438b920541value: NotACatDefsACarvalue_verification_key: "5ÁÑ\x1a=Ù¯\a\a\x1f|1\v§ì¨Nqe¡b\x05Ç\rrvý[nê\x05À\x11ÞBïÇí\eé\x14y\há_éûCz)êö\0Û]³"......thumbnails: []attachments: []...
So now we have an Item on-shared from Alice to Bob to Carlos. What if Alice now wants to update the item and get Bob and Carlos the updated data?
First Alice updates the item.
meeco items:get $VEHICLE_ITEM_ID -a .alice.yaml > .existing_vehicle_item.yaml# edit the .existing_vehicle_item.yaml file, specifically the `value` fields of the `slots` and/or the `label` field of the `item` then...meeco items:update -i .existing_vehicle_item.yaml -a .alice.yaml
Ok, the item has been updated at this stage but not the shares. Note that the last line of the items:update
command showed a comment saying
# Item updated. There are 1 outstanding client tasks. Todo: 1 & InProgress: 0
If we request the list of Client tasks with the following command...
meeco client-task-queue:list -a .alice.yaml
We will see a list of ClientTasks that are outstanding something like the following.
kind: ClientTaskQueuespec:- id: 0de4fb1a-6c43-4ca5-8880-c5187df3972bstate: todowork_type: update_item_sharestarget_id: dc66140c-3572-49b8-ad97-ec6de21827baadditional_options: {}last_state_transition_at: nullreport: {}created_at: 2020-10-13T06:02:55.028Z
What we need to do next is re-encrypt all the new data with a new DEK to share with both Bob and Carlos.
We can do this by running the command.
meeco client-task-queue:run-batch -a .alice.yaml
You will see the output something like the following.
completedTasks:- id: 0de4fb1a-6c43-4ca5-8880-c5187df3972bstate: todowork_type: update_item_sharestarget_id: dc66140c-3572-49b8-ad97-ec6de21827baadditional_options: {}last_state_transition_at: nullreport: {}created_at: 2020-10-13T06:02:55.028ZfailedTasks: []
Now Carlos and Bob have the updated shared data, you can check that by running the commands.
meeco items:get-incoming $BOB_SHARED_INCOMING_SHARE_ID -a .carlos.yamlormeeco items:get $BOB_SHARED_INCOMING_ITEM_ID -a .bob.yamlmeeco items:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yamlormeeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml
Hopefully this guide has given you a decent high level overview of how the process works. To dig further into the functionality why not try checking out how the CLI (https://github.com/Meeco/js-sdk/tree/master/packages/cli) uses the underlying SDK (https://github.com/Meeco/js-sdk/tree/master/packages/sdk).