On-sharing & Client Tasks

Share Terms
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.
Share Acceptance
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. For convenience when using the cli we have automatically set this feild to acceptance_required when any terms are specified.
Sharing Mode
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 anyone. 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. For convenience in the cli we have added the flag --onshare which will set the sharing_mode to anyone if it is present and set it to owner if it is not present.
Client Tasks
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 ClientTasks 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.
Example of On-sharing and Executing Client Tasks
(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.
1
meeco users:create -p supersecretpassword > .alice.yaml
2
meeco users:create -p supersecretpassword > .bob.yaml
3
meeco users:create -p supersecretpassword > .carlos.yaml
Copied!
Next lets connect Alice to Bob, then Bob to Carlos.
1
meeco connections:create-config --from .alice.yaml --to .bob.yaml > .connection1_config.yaml
2
meeco connections:create -c .connection1_config.yaml > .connection1.yaml
3
meeco connections:create-config --from .bob.yaml --to .carlos.yaml > .connection2_config.yaml
4
meeco connections:create -c .connection2_config.yaml > .connection2.yaml
Copied!
We create an item for Alice.
1
meeco items:create-config vehicle -a .alice.yaml > .vehicle_config.yaml
2
# open up the .vehicle.yaml and add an item label and other data
3
meeco items:create -i .vehicle_config.yaml -a .alice.yaml > .vehicle.yaml
Copied!
Share that item from Alice to Bob, with some share terms, acceptance_required, and sharing mode of anyone.
1
meeco shares:create-config -i .vehicle.yaml -f .alice.yaml -c .connection1.yaml > .share1-config.yaml
2
meeco shares:create \
3
    --config .share1-config.yaml \
4
    --onshare \
5
    --terms="You may not use this information for advertising" \
6
    > .share1.yaml
Copied!
Read the share as Bob.
1
meeco items:list -a .bob.yaml
Copied!
You will get a result something like the following...
1
kind: Items
2
spec:
3
  - id: 8e26d96f-7c15-444d-97a5-30e39b418c9d
4
    own: false
5
    label: DeLorean
6
    description: null
7
    created_at: 2020-10-12T05:52:45.395Z
8
    item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0
9
    item_template_label: Vehicle
10
    slot_ids:
11
      - 642ea490-ccce-49cc-9fef-d5d9c6668549
12
      ...
13
    me: false
14
    background_color: null
15
    original_id: dc66140c-3572-49b8-ad97-ec6de21827ba
16
    owner_id: 94c27129-e179-4c69-a7f1-94438b920541
17
    share_id: b358bc99-89f1-48f3-8b84-8dad0516643e
18
    ...
Copied!
Note the share_id from above.
Bob can have a look at the details and specifically the terms of the share by getting the share's details with the command.
1
meeco shares:get-incoming -a .bob.yaml $EXISTING_SHARE_ID
Copied!
Note that the item slot details are not available to Bob until he accepts the share and it's terms.
Next Bob will accept the share from Alice.
1
meeco shares:accept -y $EXISTING_SHARE_ID -a .bob.yaml
Copied!
Bob can now pull down the item's details. (Note: the item id must come from the item when performing the items:list command, the item_id in the shares:accept command will not work).
1
meeco items:get 8e26d96f-7c15-444d-97a5-30e39b418c9d -a .bob.yaml > .shared-to-bob-item.yaml
2
# meeco items:get <item id> -a <auth file>
Copied!
Now Bob can share this item with Carlos.
1
meeco shares:create-config -i .shared-to-bob-item.yaml -f .bob.yaml -c .connection2.yaml > .share2-config.yaml
2
meeco shares:create \
3
    --config .share2-config.yaml \
4
    --terms="You may not use this information for advertising" \
5
    > .share2.yaml
Copied!
Carlos can now see the share.
1
meeco items:list -a .carlos.yaml
Copied!
Returning something like...
1
kind: Items
2
spec:
3
  - id: 59cb375f-6188-46fd-bdd6-ba730ae3282c
4
    own: false
5
    label: DeLorean
6
    description: null
7
    created_at: 2020-10-13T05:41:02.376Z
8
    item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0
9
    item_template_label: Vehicle
10
    slot_ids:
11
      - e90e38f2-65d7-4203-b74f-0831dab393c1
12
      ...
13
    original_id: dc66140c-3572-49b8-ad97-ec6de21827ba
14
    owner_id: 94c27129-e179-4c69-a7f1-94438b920541
15
    share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c
Copied!
Noting the share_id and item_id from the above command.
Accept it.
1
meeco shares:accept $EXISTING_SHARE2_ID -a .carlos.yaml
Copied!
And view it.
1
meeco shares:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yaml
2
# or
3
meeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml
Copied!
Getting the output something like...
1
kind: Item
2
spec:
3
  id: 59cb375f-6188-46fd-bdd6-ba730ae3282c
4
  own: false
5
  label: DeLorean
6
  item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0
7
  item_template_label: Vehicle
8
  slot_ids:
9
    - 81cc655f-5ae8-4a7a-afc0-3d186ab3f736
10
    ...
11
  me: false
12
  background_color: null
13
  original_id: dc66140c-3572-49b8-ad97-ec6de21827ba
14
  owner_id: 94c27129-e179-4c69-a7f1-94438b920541
15
  share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c
16
  slots:
17
    - id: 81cc655f-5ae8-4a7a-afc0-3d186ab3f736
18
      own: false
19
      share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c
20
      name: licence_plate
21
      item_id: 59cb375f-6188-46fd-bdd6-ba730ae3282c
22
      slot_type_name: key_value
23
      encrypted_value: Aes256Gcm.AjR9r_An-mcqLla1dcGL.QUAAAAAFaXYADAAAAACcR_n2XVORiZ2wRjgFYXQAEAAAAACCNE5L6Gqq-4Zmm5Y8AgVEAmFkAAUAAABub25lAAA=
24
      encrypted_value_verification_key: Aes256Gcm.f4af1rELcDkDJQv7wPsfvOOVbnI6YyQlsnYLdDdekAZ2AcXm6Oq7WrgGytc3gUbvjnWvmkzAnWO2s2Kya0ZxLQ==.QUAAAAAFaXYADAAAAABQ346yXewWcSdSdBEFYXQAEAAAAACyZph19u-eZ-BWMPhrOqP4AmFkAAUAAABub25lAAA=
25
      value_verification_hash: d8c6e5f28837906505fa9e6a4740c8ddd5dddbe4b51675ae3daabef4a27d701b
26
      label: Vehicle registration number
27
      original_id: 5503d256-19d6-45f8-b76b-9605f977cd3f
28
      owner_id: 94c27129-e179-4c69-a7f1-94438b920541
29
      value: NotACatDefsACar
30
      value_verification_key: "5ÁÑ\x1a=Ù¯\a\a\x1f|1\v§ì¨Nqe¡b\x05Ç\rrvý[nê\x05À\x11ÞBïÇí\eé\x14y\
31
        há_éûCz)êö\0Û]³"
32
      ...
33
    ...
34
  thumbnails: []
35
  attachments: []
36
  ...
Copied!
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.
1
meeco items:get $VEHICLE_ITEM_ID -a .alice.yaml > .existing_vehicle_item.yaml
2
# edit the .existing_vehicle_item.yaml file, specifically the `value` fields of the `slots` and/or the `label` field of the `item` then...
3
meeco items:update -i .existing_vehicle_item.yaml -a .alice.yaml
Copied!
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
1
# Item updated. There are 1 outstanding client tasks. Todo: 1 & InProgress: 0
Copied!
If we request the list of Client tasks with the following command...
1
meeco client-task-queue:list -a .alice.yaml
Copied!
We will see a list of ClientTasks that are outstanding something like the following.
1
kind: ClientTaskQueue
2
spec:
3
  - id: 0de4fb1a-6c43-4ca5-8880-c5187df3972b
4
    state: todo
5
    work_type: update_item_shares
6
    target_id: dc66140c-3572-49b8-ad97-ec6de21827ba
7
    additional_options: {}
8
    last_state_transition_at: null
9
    report: {}
10
    created_at: 2020-10-13T06:02:55.028Z
Copied!
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.
1
meeco client-task-queue:run-batch -a .alice.yaml
Copied!
You will see the output something like the following.
1
completedTasks:
2
  - id: 0de4fb1a-6c43-4ca5-8880-c5187df3972b
3
    state: todo
4
    work_type: update_item_shares
5
    target_id: dc66140c-3572-49b8-ad97-ec6de21827ba
6
    additional_options: {}
7
    last_state_transition_at: null
8
    report: {}
9
    created_at: 2020-10-13T06:02:55.028Z
10
failedTasks: []
Copied!
Now Carlos and Bob have the updated shared data, you can check that by running the commands.
1
meeco shares:get-incoming $BOB_SHARED_INCOMING_SHARE_ID -a .carlos.yaml
2
or
3
meeco items:get $BOB_SHARED_INCOMING_ITEM_ID -a .bob.yaml
4
​
5
meeco shares:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yaml
6
or
7
meeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml
Copied!
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).
Guides - Previous
Organizations
Next - Guides
Account Delegation
Last modified 5mo ago
Copy link
Contents
Example of On-sharing and Executing Client Tasks