Working with Stores

Stores provide encrypted block storage, enabling simple file uploading and downloading.

Stores allow users to create multiple file containers, each with separate access rules.

Stores allow users to upload files to separate file containers.
Each Context can contain any number of Stores with a unique identifier (storeId) used to distinguish them.
Stores do not need to have unique names or assigned public keys.

Permissions

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

Activity	User	Manager
Uploading files	yes	yes
Editing files	yes	yes
Editing Store	no	yes
Deleting files	only their own	all files

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.

Before working with Stores, follow our Getting Started Guide. It will show you how to set up your project to work with PrivMX Bridge.

Sample code on this page is based on the initial assumptions.

To access Store methods, get the field storeApi from active connection. Connection should be initialized with Modules.STORE passed to PrivmxEndpoint().

val storeApi = endpointSession.storeApi

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

After creating a Store, all the users with management rights will be able to edit the Store. Skip to Modifying Stores for more info.

Creating a basic, unnamed Store, which can act as an encrypted data container:

val users : List<UserWithPubKey> = listOf(
    UserWithPubKey(user1Id, user1PublicKey),
    UserWithPubKey(user2Id, user2PublicKey)
)
val managers : List<UserWithPubKey> = listOf(
    UserWithPubKey(user1Id, user1PublicKey)
)
val publicMeta = ByteArray(0)
val privateMeta = ByteArray(0)

val storeId = storeApi.createStore(
    contextId,
    users,
    managers,
    publicMeta,
    privateMeta
)

Important note: Managers declared while creating the Store, also have to be included in the regular user list.

The user list in Stores is designed to be flexible, accommodating a wide range of use cases.

Listing Stores

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

Define Store item class with decoded publicMeta and privateMeta:

data class StoreItem(
    val store: Store,
    val decodedPrivateMeta: String,
    val decodedPublicMeta: StorePublicMeta
)

Fetching the most recent Stores in given Context:

val startIndex = 0L
val pageSize = 100L

val storesPagingList = storeApi.listStores(
    contextId,
    startIndex,
    pageSize,
    SortOrder.DESC
)

val stores = storesPagingList.readItems.map {
    StoreItem(
        it,
        it.privateMeta.decodeToString(),
        Json.decodeFromString(it.publicMeta.decodeToString())
    )
}

Modifying Stores

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

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

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

Updating a Store means overwriting it with the provided data. To successfully update a Store, 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 Store you must always provide its current version, as well as:

list of users
list of managers
new private and public meta (even if it didn't change)
Store's current version
true if update action should be forced

val storeID = "STORE_ID"
val store: Store = storeApi.getStore(storeID)
val users = store
    .users
    .map { userId ->
        //Your application must provide a way,
        //to get user's public key from their userId.
        UserWithPubKey(
            userId,
            "USER_PUBLIC_KEY"
        )
    }
val managers = store
    .managers
    .map { userId ->
        //Your application must provide a way,
        //to get user's public key from their userId.
        UserWithPubKey(
            userId,
            "USER_PUBLIC_KEY"
        )
    }
val newStoreNameAsPrivateMeta = "New store name"

storeApi.updateStore(
    storeID,
    users,
    managers,
    store.publicMeta,
    newStoreNameAsPrivateMeta.encodeToByteArray(),
    store.version,
    false
)

Working with Stores

Permissions