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.

publicMeta and privateMeta fields in Stores support any kind of data formats encoded to byte arrays. Examples in this section use JSON format serialization, which is available directly in Swift.

To access Store methods, get the field storeApi from active connection. Connection should be initialized with [.store] passed to PrivmxEndpoint.

Swift

privmxSession.storeApi?.... // instance of StoreApi

Assumptions

In further examples, the following structures are used:

Swift

struct StorePublicMeta:Codable{
    let tags: [String]
}

Creating Stores

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:

Swift

let contextId = "CONTEXT_ID"
         
let users = [privmx.endpoint.core.UserWithPubKey]() //should be prepared by developer
let managers = [privmx.endpoint.core.UserWithPubKey]() //should be prepared by developer
let publicMeta = Data()
let privateMeta = Data()

let storeId = try? endpointSession?.storeApi?
    .createStore(in: contextId,
        for: users,
        managedBy: managers,
        withPublicMeta: publicMeta,
        withPrivateMeta: privateMeta,
        withPolicies: nil)

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.

Listing the most recent Stores in given Context:

Swift

var startIndex:Int64 = 0
var pageSize:Int64 = 100

let contextId = "CONTEXT_ID"

    
guard let pagingList = try? endpointSession?.storeApi?
    .listStores(
        from:contextId,
        basedOn: .init(skip: startIndex, limit: pageSize, sortOrder: .asc)) else {return}

let stores =
pagingList.readItems.map { $0 }

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

Swift

 guard let store = try? endpointSession?.storeApi?
    .getStore(storeId) else {return}

//users list to be extracted from store
let users = store.users
    .map{
    //Your application must provide a way,
    //to get user's public key from their userId.
    privmx.endpoint.core.UserWithPubKey(userId: $0, pubKey: "PUB")
}
//managers list to be extracted from store
let managers = store.managers.map{
    //Your application must provide a way,
    //to get user's public key from their userId.
    privmx.endpoint.core.UserWithPubKey(userId: $0, pubKey: "PUB")
}

guard let newPrivateMeta = "New store name".data(using: .utf8) else {return}

_ = try? endpointSession?.storeApi?.updateStore(
    storeId,
    atVersion: store.version,
    replacingUsers: users,
    replacingManagers: managers,
    replacingPublicMeta: store.publicMeta.getData() ?? Data(),
    replacingPrivateMeta: newPrivateMeta,
    force:false,
    forceGenerateNewKey: false,
    replacingPolicies:nil)

Working with Stores

Permissions