Working with KVDBs

KVDBs allow users to access key-value databases. Each Context can contain any number of KVDBs with a unique identifier (kvdbId) used to distinguish them. KVDBs do not need to have unique names or assigned public keys.

Permissions

KVDBs differentiate two types of users - Managers and Regular Users. The table below shows the differences in their permissions:

The values above are the default policy values defined by PrivMX. To read more about Policies and learn how to modify them, go to Policies.

Working with KVDBs

When working with KVDBs, you will use the following:

• KvdbApi - provides methods used to manage KVDBs in given Context

const kvdbApi  = await Endpoint.createKvdbApi(connection);

Creating KVDBs

To create a KVDB, you need a name and a list of public key - userID pairs. Due to the fact that each KVDB is inside a Context, all the public keys have to be registered inside the given Context. You can do it using PrivMX Bridge API.

After creating a KVDB, all the users with management rights will be able to edit the KVDB.

const managers = [
    {userId: USER1_ID, pubKey: USER1_PUBLIC_KEY}
];

const users = [
    {userId: USER1_ID, pubKey: USER1_PUBLIC_KEY},
    {userId: USER2_ID, pubKey: USER2_PUBLIC_KEY}
];

// create a new KVDB with access for USER_1 as manager and USER_2 as regular user
const kvdbId = await kvdbApi.createKvdb(CONTEXT_ID, users, managers,
    serializeObject("some kvdb's public meta-data"),
    serializeObject("some kvdb's private meta-data")
);

Listing KVDBs

Your application may include multiple KVDBs, each associated with different Contexts. You can retrieve a list of all KVDBs within a given Context. This list will include useful metadata about the KVDBs, such as the creation date, last message upload date, user list, and information about the last modification. However, to optimize performance, the list will only include the total number of entries in each KVDB, not the full entry content.

const defaultListQuery = {skip: 0, limit: 100, sortOrder: "desc"};
const kvdbList = await kvdbApi.listKvdbs(CONTEXT_ID, defaultListQuery);

// kvdbList:
{
    readItems: [<kvdbObject1>, <kvdbObject2>,..., <kvdbObjectN>],
    totalAvailable: <number_of_all_kvdbs>
}

A detailed description of the Kvdb object fields can be found in API Reference.

Modifying KVDBs

Depending on your project's specification, it may be necessary to modify a KVDB. It could be e.g. changing the name or adding/removing users. Each user with management rights is able to modify KVDB, delete them as a whole or only particular entries.

Three additional options are available when changing the list of users inside a KVDB:

• force - applies an update, without checking the current version;
• forceGenerateNewKey - re-encrypts entries in the KVDB. It's useful when a user is removed and we want to prevent them from accessing the KVDB.
• policies - allow you to manage access to KVDB and entries. Read more about Policies.

Updating a KVDB means overwriting it with the provided data. To successfully update a KVDB, you must specify its current version. The version field is mandatory to handle multiple updates on the server and it is incremented by 1 with each update.

To update a KVDB you must always provide a full list of parameters.

The updateKvdb(...) method needs all the parameters as in the createKvdb(...) method and a few more. If we want to update one of the parameters – provide it in a new modified form. If, on the other hand, you want to leave the parameter unchanged – provide it as it was before. All current values ​​of the parameters of a given KVDB can be obtained using getKvdb(kvdbId).

const kvdb = await kvdbApi.getKvdb(kvdbId);

const newUsers = kvdb.users.map(user => ({
    //Your application must provide a way,
    //to get user's public key from their userId.
    userId: user,
    pubKey: 'USER_PUBLIC_KEY'
    })
);

const newManagers = newUsers.filter(user =>
    kvdb.managers.find(manager => manager == user.userId));

const newPrivateMeta = {
    title: 'New kvdb name'
};

await kvdbApi.updateKvdb(
    kvdbId,
    newUsers,
    newManagers,
    kvdb.publicMeta,
    serializeObject(newPrivateMeta),
    kvdb.version,
    false,
    false
);