Vault

The vault is the encrypted record store of the current account. Your app keeps its own JSON documents in it, groups them in folders, attaches per-user settings to them and shares them with other accounts. The SDK encrypts every record on the device, keeps a local copy and syncs it with Folio.

You work with the vault through one store, VaultStore: you mount it on the runtime, dispatch VaultAction values and read the result from its state, VaultUiModel. The runtime itself returns no vault data. See Runtime for how stores work in general.

Records belong to your organizationCopy Anchor Link

The vault of a runtime holds the records of one organization: the organization value of the configuration. Your app never writes the organization into a record. Every record carries a schema, a short name your app chooses for the kind of document, and the SDK qualifies it with the organization internally.

A write with a schema name that breaks the rule fails with UnknownSchema.

The schema digital holds the documents organizations issue to the person. The SDK receives them into the vault on its own, and FolioDocumentListStore and FolioDocumentStore read them; see Folio documents. Do not write your own records under digital: the document stores leave out a record they cannot read as an issued document.

Mount the storeCopy Anchor Link

Mount VaultStore on the runtime after FolioSdk.create has returned, and close it when your app no longer needs it. mount takes any VaultHost; a FolioSdk runtime is one.

let vault = try VaultStore.mount(runtime: sdk)
let records = vault.state.records
vault.close()

The state updates on its own whenever the vault changes: after your own writes, after a sync, and when the user signs in or out. On the web it also follows writes that another tab makes to the same account's vault. Observe it the way you observe every store: on iOS VaultStore is an ObservableObject whose state is @Published, on Android state is a StateFlow<VaultUiModel>, and on the web subscribe(listener) calls the listener on every change and returns the function that stops it. On every platform, subscribe() without arguments returns a VaultSubscription whose async next() yields the current state first, then the latest state after each change (intermediate states can be skipped), and ends after the store is closed or the runtime shuts down. See Runtime.

Mount it from the UICopy Anchor Link

In Compose and React, the SDK mounts the store for you inside a FolioSDKProvider, and closes it when the component leaves.

struct RecordList: View {
    @ObservedObject var vault: VaultStore

    var body: some View {
        List(vault.state.records, id: \.header.id) { record in
            Text(record.header.schema)
        }
    }
}

Client-shaped bodiesCopy Anchor Link

The vault stores your documents as they are. There is no typed layer over them: a document is a JSON string that your app encodes and decodes itself.

RecordContentCopy Anchor Link

The body of a record, for create and update.

version is a UInt32 on iOS, a Long on Android and a number on the web. A payload that is not valid JSON fails the write with Codec.

FolderContentCopy Anchor Link

The body of a folder. It has the same fields as RecordContent: schema, version and a JSON payload, for example the folder's name in a shape your app chooses.

DocumentSettingsCopy Anchor Link

Per-user settings of a record or a folder, such as a favorite flag or a custom label.

Settings belong to the account that writes them: every account that can see a record keeps its own settings for it, and nobody else sees them. An account that only views a shared record can still write its own settings for it.

Encode and decode the payloadCopy Anchor Link

Encode your document to a JSON string when you write, and decode payload when you read.

struct Note: Codable {
    let title: String
    let body: String
}

let note = Note(title: "Visa", body: "Renew")
let payload = String(decoding: try JSONEncoder().encode(note), as: UTF8.self)
let content = RecordContent(schema: "note", version: 1, payload: payload)

let notes = try vault.state.records
    .filter { $0.header.schema == "note" }
    .map { try JSONDecoder().decode(Note.self, from: Data($0.payload.utf8)) }

Check header.schema and header.version before you decode a payload: the vault can hold documents of several schemas and of older versions of your format.

ActionsCopy Anchor Link

VaultAction has four cases.

On iOS the cases are .sync, .write(value:), .share(value:) and .dismissError; on Android VaultAction.Sync, VaultAction.Write, VaultAction.Share and VaultAction.DismissError; on the web VaultAction.sync, VaultAction.write(...), VaultAction.share(...) and VaultAction.dismissError.

try vault.dispatch(action: .write(value: .create(record: content)))
try vault.dispatch(action: .sync)
try vault.dispatch(action: .dismissError)

A dispatched action runs in the background. busy is true while at least one Sync, Write or Share action is running. When it finishes, a failure lands in error, and a success clears error. The records themselves reach the state through the vault's own change notifications, so read them from records and folders, not from the action.

VaultWriteCopy Anchor Link

The fields keep these names and this order on every platform. On iOS each case is lowerCamelCase with labeled fields, such as .addToFolder(folderId:recordId:); on Android it is a class of VaultWrite, such as VaultWrite.AddToFolder(folderId, recordId); on the web it is a function of VaultWrite, such as VaultWrite.addToFolder(folderId, recordId).

Rules the vault enforces:

• Only the owner changes a record. Update, Delete, Restore and PermanentlyDelete fail with PermissionDenied on a record whose permission is View. Update also fails with PermissionDenied on a record that is not active.
• A record keeps its schema. Update with a different schema fails with SchemaMismatch.
• Lifecycle moves one step at a time. Active to deleted (Delete), deleted to active (Restore), deleted to permanently deleted (PermanentlyDelete). Any other move fails with InvalidRequest.
• Folder changes need a connection in a signed-in session. In a signed-in session, CreateFolder, UpdateFolder, SetFolderOpen, DeleteFolder, AddToFolder and RemoveFromFolder fail with OfflineFolderOpNotSupported while the device is offline, and with UpstreamUnavailable when the network status cannot be read. In a transient session they work offline.
• A record joins a folder after both reached Folio. In a signed-in session, AddToFolder fails with InvalidRequest while the folder or the record has not been synced yet. Sync, then retry. AddToFolder of a permanently deleted record fails with InvalidRequest.
• A pending settings change blocks a body change. While a settings change of a record has not reached Folio yet, Update, Delete, Restore and PermanentlyDelete of that record fail with RevisionConflict. Sync, then retry.

The vault store has no action that adds attachments to a record or reads attachment bytes. The inquiry attaches the verification artifacts to the identity records it saves; header.attachments lists their ids. The images of an issued document are readable through FolioDocumentPhoto.image; see Photos.

StateCopy Anchor Link

VaultUiModel is the state of VaultStore.

VaultRecordCopy Anchor Link

RecordHeaderCopy Anchor Link

The SDK assigns an id when your app creates the record. Once Folio has confirmed the record, id is the id Folio assigned, so read the id from the state again after a sync instead of keeping it. Actions on the device that created the record accept both ids, so an action your app dispatches with the earlier id still finds the record. Ids the SDK assigns start with D_ for documents, F_ for folders and AT_ for attachments.

A deleted record stays in records with state Deleted until it is restored or permanently deleted. The SDK permanently deletes a record the account owns on its own, during its background sync, once the record has been deleted for 60 days. Filter on state to show active records and a trash view.

Revocation does not remove a record: the access the account already accepted and the record's content stay available. Use revokedAt to show that the issuer revoked it. For an issued document, FolioDocument.status is then Revoked; see Status.

let active = vault.state.records.filter { $0.header.state == .active }
let trash = vault.state.records.filter { $0.header.state == .deleted }
let shared = vault.state.records.filter { $0.header.permission == .view }

RecordMetadataCopy Anchor Link

folders follows the folder membership on the device, so it agrees with FolderMetadata.records, also before a change has reached Folio.

RecordSyncCopy Anchor Link

FolderCopy Anchor Link

FolderMetadataCopy Anchor Link

SyncCopy Anchor Link

Every write lands in the local vault first and shows up in the state at once, with header.sync.dirty set. In a signed-in session the SDK syncs in the background:

• when the session starts, it pushes local changes and fetches remote changes;
• after every local write, it pushes;
• when Folio reports a change, it fetches the changed record or the remote changes;
• when the network comes back, it pushes and fetches;
• when the app returns to the foreground, it pushes, and fetches at most once a minute;
• when a background push fails, it tries again after 2 seconds, then after a delay that doubles each time, up to 5 minutes.

Sync runs a push and a fetch right away. A failed Sync action is not retried.

In a transient session, before the user signs in, the SDK pushes nothing: local changes stay on the device. It still fetches remote changes in the background, at the same moments as in a signed-in session. Sync, ResolveConflict and every Share action fail there with TransientNotSupported. When the user signs in, the SDK copies the records and folders of the transient vault, with their attachments, into the account's vault, and removes the transient vault once every copy is in place.

DocSyncStatusCopy Anchor Link

DocSyncPhaseCopy Anchor Link

The Degraded message counts the failures, as in 1 record failure(s), 0 attachment failure(s). When a record stored on the device cannot be decoded or applied at the start of a session, phase is Error with that error's message. The SDK keeps the stored copy as it is and fetches no remote changes until a later session reads the records: Sync fails with that error in the meantime.

switch vault.state.sync.phase {
case .idle, .syncing:
    hideSyncWarning()
case .degraded(let message), .error(let message):
    showSyncWarning(message)
}

ConflictsCopy Anchor Link

A record enters a conflict when a local change of it cannot be pushed as it is. The record's header.sync.conflict names the kind, and sync.conflictCount counts such records.

Settle a conflict with VaultWrite.ResolveConflict and a ConflictResolution:

ResolveConflict on a record without a conflict fails with InvalidRequest.

if record.header.sync.conflict != .none {
    try vault.dispatch(
        action: .write(value: .resolveConflict(id: record.header.id, resolution: .acceptRemote))
    )
}

ErrorsCopy Anchor Link

error in the state is a VaultErrorView:

DismissError clears the error of the last failed action. An error from reading the vault stays until the next successful read.

Payload fields are strings unless the table names another type.

On the web, type is the case name in SCREAMING_SNAKE_CASE and the payload fields are under value. See Errors for how SDK errors reach your app.

switch vault.state.error?.details {
case .transientNotSupported?:
    showSignIn()
case .notFound(let message)?:
    showError(message)
default:
    break
}
try vault.dispatch(action: .dismissError)

Types on each platformCopy Anchor Link

Structs such as RecordContent, VaultRecord and RecordHeader have the field names above on every platform. The tables on this page write enum cases in UpperCamelCase and field types in a neutral form:

The enums of the vault without payloads have these spellings:

On the web, every enum also has a constant of the same name that holds its values, such as RecordState.ACTIVE for 'ACTIVE' and ConflictState.none for { type: 'NONE' }. Enums with payloads, such as VaultAction, VaultWrite, DocSyncPhase and VaultError, are lowerCamelCase cases with labeled payloads on iOS, subclasses on Android and objects with type and value on the web.