oro-sdk 2.1.4-dev1

package/src/client.ts

@@ -0,0 +1,1843 @@
+import * as OroToolbox from 'oro-toolbox'
+import { CryptoRSA } from 'oro-toolbox'
+import { registerPatient, sessionStorePrivateKeyName, decryptGrants, decryptConsultLockboxGrants} from './helpers'
+import {
+    AssociatedLockboxNotFound,
+    AuthTokenRequest,
+    Consult,
+    ConsultRequest,
+    DataCreateResponse,
+    Document,
+    DocumentType,
+    EncryptedIndexEntry,
+    EncryptedVaultIndex,
+    Grant,
+    IdentityCreateRequest,
+    IdentityResponse,
+    IncompleteAuthentication,
+    IndexBuildError,
+    IndexConsultLockbox,
+    IndexKey,
+    LocalEncryptedData,
+    LocalizedData,
+    LockboxDataRequest,
+    LockboxGrantRequest,
+    LockboxManifest,
+    ManifestEntry,
+    Meta,
+    Metadata,
+    MetadataCategory,
+    MissingGrant,
+    MissingLockbox,
+    MissingLockboxOwner,
+    PersonalMeta,
+    PopulatedWorkflowData,
+    Practice,
+    PreferenceMeta,
+    RecoveryData,
+    RecoveryMeta,
+    RegisterPatientOutput,
+    SecretShard,
+    TokenData,
+    TosAndCpAcceptanceRequest,
+    UserPreference,
+    Uuid,
+    VaultIndex,
+    WorkflowData,
+} from './models'
+import { filterGrantsWithLockboxMetadata, buildLegacyVaultIndex } from './sdk-revision'
+import {
+    ConsultService,
+    DiagnosisService,
+    GuardService,
+    PracticeService,
+    TellerService,
+    VaultService,
+    WorkflowService,
+} from './services'
+
+export class OroClient {
+    private rsa?: CryptoRSA
+    private secrets: {
+        lockboxUuid: string
+        cryptor: OroToolbox.CryptoChaCha
+    }[] = []
+    private cachedMetadataGrants: {
+        [filter: string]: Grant[]
+    } = {}
+
+    private cachedManifest: {
+        [filter: string]: ManifestEntry[]
+    } = {}
+
+    private vaultIndex?: VaultIndex
+
+    constructor(
+        private toolbox: typeof OroToolbox,
+        public tellerClient: TellerService,
+        public vaultClient: VaultService,
+        public guardClient: GuardService,
+        public practiceClient: PracticeService,
+        public consultClient: ConsultService,
+        public workflowClient: WorkflowService,
+        public diagnosisClient: DiagnosisService,
+        private authenticationCallback?: (err: Error) => void
+    ) {}
+
+    /** 
+     * clears the vaultIndex and cached metadata grants
+    */
+    public async cleanIndex() {
+        this.vaultIndex = undefined
+        this.cachedMetadataGrants = {}
+        this.cachedManifest = {}    
+    }
+
+    /**
+     * Generates an RSA key pair and password payload (rsa private key encrypted with the password)
+     * Calls Guard to sign up with the email address, password, practice, legal and token data
+     *
+     * @param email
+     * @param password
+     * @param practice
+     * @param legal
+     * @param tokenData
+     * @returns
+     */
+    public async signUp(
+        email: string,
+        password: string,
+        practice: Practice,
+        tosAndCpAcceptance: TosAndCpAcceptanceRequest,
+        tokenData?: TokenData,
+        subscription?: boolean
+    ): Promise<IdentityResponse> {
+        this.rsa = new CryptoRSA()
+        const privateKey = this.rsa.private()
+
+        const symmetricEncryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+            password
+        )
+        const recoveryPassword = symmetricEncryptor.bytesEncryptToBase64Payload(
+            privateKey
+        )
+
+        const hashedPassword = this.toolbox.hashStringToBase64(
+            this.toolbox.hashStringToBase64(password)
+        )
+
+        const signupRequest: IdentityCreateRequest = {
+            practiceUuid: practice.uuid,
+            email: email.toLowerCase(),
+            password: hashedPassword,
+            publicKey: this.toolbox.encodeToBase64(this.rsa.public()),
+            recoveryPassword,
+            tosAndCpAcceptance,
+            tokenData,
+            subscription,
+        }
+
+        const identity = await this.guardClient.identityCreate(signupRequest)
+
+        if (identity.recoveryLogin) {
+            //Ensure we can recover from a page reload
+            let symetricEncryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+                identity.recoveryLogin
+            )
+            sessionStorage.setItem(
+                sessionStorePrivateKeyName(identity.id),
+                symetricEncryptor.bytesEncryptToBase64Payload(privateKey)
+            )
+        }
+
+        return identity
+    }
+
+    /**
+     * Parse the given accessToken claims by calling guard whoami and update theidentity to set it's emailConfirmed flag
+     * @param accessToken
+     * @returns The identity related to confirmedEmail
+     */
+    public async confirmEmail(accessToken: string): Promise<IdentityResponse> {
+        this.guardClient.setTokens({ accessToken })
+        const claims = await this.guardClient.whoAmI()
+        return this.guardClient.identityUpdate(claims.sub, {
+            emailConfirmed: true,
+        })
+    }
+
+    /**
+     * Calls Guard to sign in with the email address, password and one time password (if MFA is enabled)
+     * Then recover's the rsa private key from the recovery payload
+     *
+     * @param practiceUuid
+     * @param email
+     * @param password
+     * @param otp
+     * @returns the user identity
+     */
+    public async signIn(
+        practiceUuid: Uuid,
+        email: string,
+        password: string,
+        otp?: string
+    ): Promise<IdentityResponse> {
+        const hashedPassword = this.toolbox.hashStringToBase64(
+            this.toolbox.hashStringToBase64(password)
+        )
+        const tokenRequest: AuthTokenRequest = {
+            practiceUuid,
+            email: email.toLowerCase(),
+            password: hashedPassword,
+            otp,
+        }
+
+        await this.guardClient.authToken(tokenRequest)
+        const userUuid = (await this.guardClient.whoAmI()).sub
+
+        // Updates the rsa key to the one generated on the backend
+        await this.recoverPrivateKeyFromPassword(userUuid, password)
+        return await this.guardClient.identityGet(userUuid)
+    }
+
+    /**
+     * Will attempt to recover an existing login session and set back
+     * the private key in scope
+     */
+    public async resumeSession() {
+        const id = (await this.guardClient.whoAmI()).sub
+        const recoveryPayload = sessionStorage.getItem(
+            sessionStorePrivateKeyName(id)
+        )
+        const recoveryKey = (await this.guardClient.identityGet(id))
+            .recoveryLogin
+
+        if (!recoveryKey || !recoveryPayload) throw IncompleteAuthentication
+
+        const symmetricDecryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+            recoveryKey
+        )
+        let privateKey = symmetricDecryptor.base64PayloadDecryptToBytes(
+            recoveryPayload
+        )
+        this.rsa = this.toolbox.CryptoRSA.fromKey(privateKey)
+    }
+
+    /**
+     * This function let's you encrypt locally an Object
+     * @param value the Object to encrypt
+     * @returns a LocalEncryptedData Object
+     * @throws IncompleteAuthentication if rsa is not set
+     * @calls authenticationCallback if rsa is not set
+     */
+    public localEncryptToJsonPayload(value: any): LocalEncryptedData {
+        if (!this.rsa) {
+            if (this.authenticationCallback) {
+                this.authenticationCallback(new IncompleteAuthentication())
+            }
+
+            throw new IncompleteAuthentication()
+        }
+
+        const chaChaKey = new this.toolbox.CryptoChaCha()
+
+        const encryptedData = chaChaKey.jsonEncryptToBase64Payload(value)
+        const encryptedKey = this.toolbox.encodeToBase64(
+            this.rsa.encryptToBytes(chaChaKey.key())
+        )
+
+        return { encryptedData, encryptedKey }
+    }
+
+    /**
+     * This function let's you decrypt a LocalEncryptedData object
+     * @param value a LocalEncryptedData object
+     * @returns a decrypted Object
+     * @throws IncompleteAuthentication if rsa is not set
+     * @calls authenticationCallback if rsa is not set
+     */
+    public localDecryptJsonPayload({
+        encryptedKey,
+        encryptedData,
+    }: LocalEncryptedData): any {
+        if (!this.rsa) {
+            if (this.authenticationCallback) {
+                this.authenticationCallback(new IncompleteAuthentication())
+            }
+
+            throw new IncompleteAuthentication()
+        }
+
+        const chaChaKey = this.rsa.base64DecryptToBytes(encryptedKey)
+        const decryptedData = this.toolbox.CryptoChaCha.fromKey(
+            chaChaKey
+        ).base64PayloadDecryptToJson(encryptedData)
+
+        return decryptedData
+    }
+
+    /**
+     * Effectively kills your "session"
+     */
+    public async signOut() {
+        this.rsa = undefined
+        this.secrets = []
+        this.guardClient.setTokens({
+            accessToken: undefined,
+            refreshToken: undefined,
+        })
+        await this.guardClient.authLogout()
+    }
+
+    /**
+     * @name registerPatient
+     * @description The complete flow to register a patient
+     *
+     * Steps:
+     * 1. Create a consult (checks if payment has been done)
+     * 2. Creates a lockbox
+     * 3. Grants lockbox access to all practice personnel
+     * 4. Creates secure identification, medical, onboarding data
+     * 5. Generates and stores the rsa key pair and recovery payloads
+     *
+     * @param patientUuid
+     * @param consult
+     * @param workflow
+     * @param recoveryQA
+     * @returns
+     */
+    public async registerPatient(
+        patientUuid: Uuid,
+        consult: ConsultRequest,
+        workflow: WorkflowData,
+        recoveryQA?: {
+            recoverySecurityQuestions: string[]
+            recoverySecurityAnswers: string[]
+        }
+    ): Promise<RegisterPatientOutput> {
+        if (!this.rsa) throw IncompleteAuthentication
+        return registerPatient(
+            patientUuid,
+            consult,
+            workflow,
+            this,
+            this.toolbox.uuid(),
+            recoveryQA
+        )
+    }
+
+    /**
+     * Builds the vault index for the logged user
+     *
+     * Steps:
+     * 1. Retrieves, decrypts and sets the lockbox IndexSnapshot
+     * 2. Retrieves, decrypts and adds all other index entries starting at the snapshot timestamp
+     * 3. Updates the IndexSnapshot if changed
+     * @deprecated
+     * @returns the latest vault index
+     */
+    public async buildVaultIndex(forceRefresh: boolean = false) {
+        if (!this.vaultIndex || forceRefresh)
+            await buildLegacyVaultIndex(this)
+    }
+
+    /**
+     * Setter for the vault index
+     * @param index
+     */
+    public setVaultIndex(index: VaultIndex) {
+        this.vaultIndex = index
+    }
+
+    /**
+     * Fetches all grants, and consultations that exist in each lockbox
+     * Then updates the index for the current user with the lockbox consult relationship
+     */
+    public async forceUpdateIndexEntries() {
+        let grants = await this.getGrants()
+
+        let indexConsultLockbox: IndexConsultLockbox[] = await Promise.all(
+            grants.map(
+                async (grant: Grant) =>
+                    await this.vaultClient
+                        .lockboxMetadataGet(
+                            grant.lockboxUuid!,
+                            ['consultationId'],
+                            [],
+                            { category: MetadataCategory.Consultation },
+                            grant.lockboxOwnerUuid
+                        )
+                        .then((consults) => {
+                            try {
+                                return consults[0].map((consult: any) => {
+                                    return {
+                                        ...consult,
+                                        grant: {
+                                            lockboxOwnerUuid:
+                                                grant.lockboxOwnerUuid,
+                                            lockboxUuid: grant.lockboxUuid,
+                                        },
+                                    }
+                                })
+                            } catch (e) {
+                                // No consultations in lockbox or index could not be created
+                                return []
+                            }
+                        })
+                        .catch(() => [])
+            )
+        ).then((consults) => consults.flat())
+        this.vaultIndexAdd({
+            [IndexKey.Consultation]: indexConsultLockbox,
+        })
+            .then(() => alert('The Index was successfully updated!'))
+            .catch(() => console.error('The index failed to update!'))
+    }
+
+    /**
+     * Generates, encrypts and adds entries to vault index for a given index owner
+     *
+     * @param entries
+     * @param indexOwnerUuid
+     */
+    public async vaultIndexAdd(entries: VaultIndex, indexOwnerUuid?: Uuid) {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let rsaPub: Uint8Array
+        if (indexOwnerUuid) {
+            let base64IndexOwnerPubKey = (
+                await this.guardClient.identityGet(indexOwnerUuid)
+            ).publicKey
+            rsaPub = this.toolbox.decodeFromBase64(base64IndexOwnerPubKey)
+        } else {
+            rsaPub = this.rsa.public()
+        }
+
+        let encryptedIndex: EncryptedVaultIndex = {}
+
+        for (let keyString of Object.keys(entries)) {
+            let key = keyString as keyof VaultIndex
+            switch (key) {
+                case IndexKey.ConsultationLockbox:
+                    encryptedIndex[key] = (entries[
+                        key
+                    ] as IndexConsultLockbox[])
+                        .map((e) => ({
+                            ...e,
+                            uniqueHash: e.consultationId,
+                        }))
+                        .map(
+                            (e: IndexConsultLockbox) =>
+                                ({
+                                    uuid: e.uuid,
+                                    timestamp: e.timestamp,
+                                    uniqueHash: e.uniqueHash,
+                                    encryptedIndexEntry: CryptoRSA.jsonWithPubEncryptToBase64(
+                                        {
+                                            consultationId: e.consultationId,
+                                            grant: e.grant,
+                                        },
+                                        rsaPub
+                                    ),
+                                } as EncryptedIndexEntry)
+                        )
+                    break
+                //// DEPRECATED : REMOVE ME : BEGIN ///////////////////////////////////////////
+                case IndexKey.Consultation:
+                    encryptedIndex[key] = (entries[
+                        key
+                    ] as IndexConsultLockbox[])
+                        .map((e) => ({
+                            ...e,
+                            uniqueHash: this.toolbox.hashStringToBase64(
+                                JSON.stringify({
+                                    consultationId: e.consultationId,
+                                    grant: e.grant,
+                                })
+                            ),
+                        }))
+                        .filter(
+                            (e) =>
+                                !this.vaultIndex ||
+                                !this.vaultIndex[IndexKey.Consultation]?.find(
+                                    (v) => v.uniqueHash === e.uniqueHash
+                                )
+                        )
+                        .map(
+                            (e: IndexConsultLockbox) =>
+                                ({
+                                    uuid: e.uuid,
+                                    timestamp: e.timestamp,
+                                    uniqueHash: e.uniqueHash,
+                                    encryptedIndexEntry: CryptoRSA.jsonWithPubEncryptToBase64(
+                                        {
+                                            consultationId: e.consultationId,
+                                            grant: e.grant,
+                                        },
+                                        rsaPub
+                                    ),
+                                } as EncryptedIndexEntry)
+                        )
+                    break
+                //// DEPRECATED : REMOVE ME : END ///////////////////////////////////////////
+            }
+        }
+        await this.vaultClient.vaultIndexPut(encryptedIndex, indexOwnerUuid)
+    }
+
+    /**
+     * adds or updates the index snapshot for the logged user
+     * @param index
+     */
+    public async indexSnapshotAdd(index: VaultIndex) {
+        if (!this.rsa) throw IncompleteAuthentication
+        let rsaPub: Uint8Array = this.rsa.public()
+
+        let cleanedIndex: VaultIndex = {
+            [IndexKey.Consultation]: index[IndexKey.Consultation]
+                ?.filter((c) => c)
+                .map((c) => {
+                    return {
+                        grant: c.grant,
+                        consultationId: c.consultationId,
+                    }
+                }),
+        }
+
+        // the data of the snapshot should not contain the `IndexEntry` data
+        // (will create conflicts while updating)
+        let encryptedIndexEntry = CryptoRSA.jsonWithPubEncryptToBase64(
+            cleanedIndex,
+            rsaPub
+        )
+
+        // The encryptedIndexEntry can have the uuid and timstamp (for updating)
+        let encryptedIndex: EncryptedIndexEntry = {
+            uuid: index.uuid,
+            timestamp: index.timestamp,
+            encryptedIndexEntry,
+        }
+        this.vaultClient.vaultIndexSnapshotPut(encryptedIndex)
+    }
+
+    /**
+     * @name grantLockbox
+     * @description Grants a lockbox by retrieving the shared secret of the lockbox and encrypting it with the grantees public key
+     * @param granteeUuid
+     * @param lockboxUuid
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     */
+    public async grantLockbox(
+        granteeUuid: Uuid,
+        lockboxUuid: Uuid,
+        lockboxOwnerUuid?: Uuid
+    ) {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let secret = (
+            await this.getCachedSecretCryptor(lockboxUuid, lockboxOwnerUuid)
+        ).key()
+        let base64GranteePublicKey = (
+            await this.guardClient.identityGet(granteeUuid)
+        ).publicKey
+        let granteePublicKey = this.toolbox.decodeFromBase64(
+            base64GranteePublicKey
+        )
+
+        let granteeEncryptedSecret = CryptoRSA.bytesWithPubEncryptToBase64(
+            secret,
+            granteePublicKey
+        )
+        let request: LockboxGrantRequest = {
+            encryptedSecret: granteeEncryptedSecret,
+            granteeUuid: granteeUuid,
+        }
+        await this.vaultClient.lockboxGrant(
+            lockboxUuid,
+            request,
+            lockboxOwnerUuid
+        )
+    }
+
+    /**
+     * @name createMessageData
+     * @description Creates a Base64 encrypted Payload to send and store in the vault from a message string
+     * @param lockboxUuid
+     * @param message
+     * @param consultationId the consultation for which this message is sent
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @param previousDataUuid if it's a revision of existing file, specify the previous data uuid
+     * @returns the data uuid
+     */
+    public async createMessageData(
+        lockboxUuid: Uuid,
+        message: string,
+        consultationId: string,
+        lockboxOwnerUuid?: Uuid,
+        previousDataUuid?: Uuid
+    ): Promise<DataCreateResponse> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let symmetricEncryptor = await this.getCachedSecretCryptor(
+            lockboxUuid,
+            lockboxOwnerUuid
+        )
+
+        let encryptedData = symmetricEncryptor.jsonEncryptToBase64Payload(
+            message
+        )
+        let encryptedPrivateMeta = symmetricEncryptor.jsonEncryptToBase64Payload(
+            { author: (await this.guardClient.whoAmI()).sub }
+        )
+
+        let meta = {
+            consultationId,
+            category: MetadataCategory.Consultation,
+            documentType: DocumentType.Message,
+            contentType: 'text/plain',
+        }
+
+        let request: LockboxDataRequest = {
+            data: encryptedData,
+            publicMetadata: meta,
+            privateMetadata: encryptedPrivateMeta,
+        }
+
+        return this.tellerClient.lockboxDataStore(
+            lockboxUuid,
+            request,
+            lockboxOwnerUuid,
+            previousDataUuid
+        )
+    }
+
+    /**
+     * @name createMessageAttachmentData
+     * @description Creates a Base64 encrypted Payload to send and store in the vault from a file
+     * @param lockboxUuid
+     * @param data the file stored
+     * @param consultationId the consultation for which this message is sent
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @param previousDataUuid if it's a revision of existing file, specify the previous data uuid
+     * @returns the data uuid
+     */
+    public async createMessageAttachmentData(
+        lockboxUuid: Uuid,
+        data: File,
+        consultationId: string,
+        lockboxOwnerUuid?: Uuid,
+        previousDataUuid?: Uuid
+    ): Promise<DataCreateResponse> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let symmetricEncryptor = await this.getCachedSecretCryptor(
+            lockboxUuid,
+            lockboxOwnerUuid
+        )
+        let encryptedData = symmetricEncryptor.bytesEncryptToBase64Payload(
+            new Uint8Array(await data.arrayBuffer())
+        )
+        let encryptedPrivateMeta = symmetricEncryptor.jsonEncryptToBase64Payload(
+            {
+                author: (await this.guardClient.whoAmI()).sub,
+                fileName: data.name,
+                lastModified: data.lastModified,
+                size: data.size,
+            }
+        )
+
+        let meta = {
+            consultationId,
+            category: MetadataCategory.Consultation,
+            documentType: DocumentType.Message,
+            contentType: data.type,
+        }
+
+        let request: LockboxDataRequest = {
+            data: encryptedData,
+            publicMetadata: meta,
+            privateMetadata: encryptedPrivateMeta,
+        }
+
+        return this.tellerClient.lockboxDataStore(
+            lockboxUuid,
+            request,
+            lockboxOwnerUuid,
+            previousDataUuid
+        )
+    }
+
+    /**
+     * @name createAttachmentData
+     * @description Creates a Base64 encrypted Payload to send and store in the vault from a file
+     * @param lockboxUuid
+     * @param data the file stored
+     * @param consultationId the consultation for which this message is sent
+     * @param category the category for the attachment data
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @param previousDataUuid if it's a revision of existing file, specify the previous data uuid
+     * @returns the data uuid
+     */
+    public async createConsultationAttachmentData(
+        lockboxUuid: Uuid,
+        data: File,
+        consultationId: string,
+        documentType: DocumentType,
+        lockboxOwnerUuid?: Uuid,
+        previousDataUuid?: Uuid
+    ): Promise<DataCreateResponse> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        return this.createBytesData<Meta | any>(
+            lockboxUuid,
+            new Uint8Array(await data.arrayBuffer()),
+            {
+                consultationId,
+                category: MetadataCategory.Consultation,
+                documentType,
+                contentType: data.type,
+            },
+            {
+                author: (await this.guardClient.whoAmI()).sub,
+                fileName: data.name,
+            },
+            lockboxOwnerUuid,
+            previousDataUuid
+        )
+    }
+
+    /**
+     * @name createJsonData
+     * @description Creates a Base64 encrypted Payload to send and store in the vault. With the data input as a JSON
+     * @param lockboxUuid
+     * @param data
+     * @param meta
+     * @param privateMeta the metadata that will be secured in the vault
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @param previousDataUuid if it's a revision of existing data, specify the previous data uuid
+     * @returns the data uuid
+     */
+    public async createJsonData<T = Meta>(
+        lockboxUuid: Uuid,
+        data: any,
+        meta?: T,
+        privateMeta?: { [val: string]: any },
+        lockboxOwnerUuid?: Uuid,
+        previousDataUuid?: Uuid
+    ): Promise<DataCreateResponse> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let symmetricEncryptor = await this.getCachedSecretCryptor(
+            lockboxUuid,
+            lockboxOwnerUuid
+        )
+        let encryptedData = symmetricEncryptor.jsonEncryptToBase64Payload(data)
+        let encryptedPrivateMeta = symmetricEncryptor.jsonEncryptToBase64Payload(
+            privateMeta
+        )
+
+        let request: LockboxDataRequest = {
+            data: encryptedData,
+            publicMetadata: meta,
+            privateMetadata: encryptedPrivateMeta,
+        }
+
+        return this.tellerClient.lockboxDataStore(
+            lockboxUuid,
+            request,
+            lockboxOwnerUuid,
+            previousDataUuid
+        )
+    }
+
+    /**
+     * Get or upsert a data in lockbox
+     * @param lockboxUuid the lockbox uuid
+     * @param data the data to insert
+     * @param publicMetadata the public Metadata
+     * @param privateMetadata the private Metadata
+     * @param forceReplace set true when the insertion of data requires to replace the data when it exists already
+     * @returns the data uuid
+     */
+    public async getOrInsertJsonData<M = Metadata>(
+        lockboxUuid: Uuid,
+        data: any,
+        publicMetadata: M,
+        privateMetadata: Metadata,
+        forceReplace: boolean = false
+    ): Promise<Uuid> {
+        let manifest = await this.vaultClient.lockboxManifestGet(
+            lockboxUuid,
+            publicMetadata
+        )
+        if (!forceReplace && manifest.length > 0) {
+            console.log(
+                `The data for ${JSON.stringify(publicMetadata)} already exist`
+            )
+            return manifest[0].dataUuid
+        } else
+            return (
+                await this.createJsonData<M>(
+                    lockboxUuid,
+                    data,
+                    publicMetadata,
+                    privateMetadata,
+                    undefined,
+                    forceReplace && manifest.length > 0
+                        ? manifest[0].dataUuid
+                        : undefined // if forceReplace and data already exist, then replace data. Otherwise insert it
+                ).catch((err) => {
+                    console.error(
+                        `Error while upserting data ${JSON.stringify(
+                            publicMetadata
+                        )} data`,
+                        err
+                    )
+                    throw err
+                })
+            ).dataUuid
+    }
+
+    /**
+     * @name createBytesData
+     * @description Creates a Base64 encrypted Payload to send and store in the vault. With the data input as a Bytes
+     * @param lockboxUuid
+     * @param data
+     * @param meta
+     * @param privateMeta the metadata that will be secured in the vault
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @param previousDataUuid if it's a revision of existing data, specify the previous data uuid
+     * @returns the data uuid
+     */
+    public async createBytesData<T = Meta>(
+        lockboxUuid: Uuid,
+        data: Uint8Array,
+        meta: T,
+        privateMeta: { [val: string]: any },
+        lockboxOwnerUuid?: Uuid,
+        previousDataUuid?: Uuid
+    ): Promise<DataCreateResponse> {
+        if (!this.rsa) throw IncompleteAuthentication
+        let symmetricEncryptor = await this.getCachedSecretCryptor(
+            lockboxUuid,
+            lockboxOwnerUuid
+        )
+        let encryptedData = symmetricEncryptor.bytesEncryptToBase64Payload(data)
+        let encryptedPrivateMeta = symmetricEncryptor.jsonEncryptToBase64Payload(
+            privateMeta
+        )
+
+        let request: LockboxDataRequest = {
+            data: encryptedData,
+            publicMetadata: meta,
+            privateMetadata: encryptedPrivateMeta,
+        }
+
+        return this.tellerClient.lockboxDataStore(
+            lockboxUuid,
+            request,
+            lockboxOwnerUuid,
+            previousDataUuid
+        )
+    }
+
+    /**
+     * @name getJsonData
+     * @description Fetches and decrypts the lockbox data with the cached shared secret.
+     * Decrypts the data to a valid JSON object. If this is impossible, the call to the WASM binary will fail
+     *
+     * @type T is the generic type specifying the return type object of the function
+     * @param lockboxUuid
+     * @param dataUuid
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @returns the data specified by the generic type <T>
+     */
+    public async getJsonData<T = any>(
+        lockboxUuid: Uuid,
+        dataUuid: Uuid,
+        lockboxOwnerUuid?: Uuid
+    ): Promise<T> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let [encryptedPayload, symmetricDecryptor] = await Promise.all([
+            this.vaultClient.lockboxDataGet(
+                lockboxUuid,
+                dataUuid,
+                lockboxOwnerUuid
+            ),
+            this.getCachedSecretCryptor(lockboxUuid, lockboxOwnerUuid),
+        ])
+
+        return symmetricDecryptor.base64PayloadDecryptToJson(
+            encryptedPayload.data
+        )
+    }
+    /**
+     * @description Fetches and decrypts the lockbox data with the cached shared secret.
+     * @param lockboxUuid
+     * @param dataUuid
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @returns the bytes data
+     */
+    public async getBytesData(
+        lockboxUuid: Uuid,
+        dataUuid: Uuid,
+        lockboxOwnerUuid?: Uuid
+    ): Promise<Uint8Array> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let [encryptedPayload, symmetricDecryptor] = await Promise.all([
+            this.vaultClient.lockboxDataGet(
+                lockboxUuid,
+                dataUuid,
+                lockboxOwnerUuid
+            ),
+            this.getCachedSecretCryptor(lockboxUuid, lockboxOwnerUuid),
+        ])
+
+        return symmetricDecryptor.base64PayloadDecryptToBytes(
+            encryptedPayload.data
+        )
+    }
+
+    /**
+     * @name getGrants
+     * @description Get all lockboxes granted to user with the applied filter
+     * @note this function returns cached grants and will not update unless the page is refreshed
+     * @todo some versions of lockboxes do not make use of lockbox metadata
+     *  in this case, all lockboxes need to be filtered one-by-one to find the correct one
+     *  Remove if this is no longer the case
+     * @param filter: the consultationId in which the grant exists
+     * @returns decrypted lockboxes granted to user
+     */
+    public async getGrants(
+        filter?: { consultationId: Uuid },
+        forceRefresh: boolean = false
+    ): Promise<Grant[]> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let filterString = JSON.stringify(filter)
+        // retrieves cached grants
+        // Note: if filters is set to empty, it will be stored in the `undefined` key
+        if (!forceRefresh && this.cachedMetadataGrants[filterString])
+            return this.cachedMetadataGrants[filterString]
+
+        // retrieves the consult lockbox from the vault directly if it exists
+        // Note: will work only if the filter being applied is exclusively a consult id
+        const grantsByConsultLockbox = (await this.vaultClient.vaultIndexGet([IndexKey.ConsultationLockbox], [filter?.consultationId!]))[IndexKey.ConsultationLockbox] 
+        const decryptedConsults = decryptConsultLockboxGrants(grantsByConsultLockbox ?? [], this.rsa)
+        if (decryptedConsults.length > 0) {
+            console.info('[sdk:index] Grants found in user`s constant time secure index')
+            this.cachedMetadataGrants[JSON.stringify(filter)] = decryptedConsults
+            return this.cachedMetadataGrants[filterString]
+        }
+
+        let encryptedGrants
+        // if there are no grants with the applied filter from index, attempt for naive filter with backwards compatibility
+        if (filter) {
+            encryptedGrants = await filterGrantsWithLockboxMetadata(
+                this, 
+                filter,
+                this.vaultIndex,
+                forceRefresh
+            )
+        } else {
+            encryptedGrants = (await this.vaultClient.grantsGet()).grants
+        }
+
+        const decryptedGrants = await decryptGrants(encryptedGrants, this.rsa)
+        // sets the cached grant
+        this.cachedMetadataGrants[filterString] = decryptedGrants
+        return decryptedGrants
+    }
+
+    /**
+     * @name getCachedSecretCryptor
+     * @description Retrieves the cached lockbox secret or fetches the secret from vault, then creates the symmetric cryptor and stores it in memory
+     * @param lockboxUuid
+     * @param lockboxOwnerUuid the lockbox owner (ignored if lockbox is owned by self)
+     * @returns
+     */
+    async getCachedSecretCryptor(
+        lockboxUuid: string,
+        lockboxOwnerUuid?: string
+    ): Promise<OroToolbox.CryptoChaCha> {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let index = this.secrets.findIndex(
+            (secret) => secret.lockboxUuid === lockboxUuid
+        )
+        if (index === -1) {
+            let encryptedSecret = (
+                await this.vaultClient.lockboxSecretGet(
+                    lockboxUuid,
+                    lockboxOwnerUuid
+                )
+            ).sharedSecret
+
+            let secret = this.rsa.base64DecryptToBytes(encryptedSecret)
+            let cryptor = this.toolbox.CryptoChaCha.fromKey(secret)
+            this.secrets.push({ lockboxUuid, cryptor })
+            return cryptor
+        } else {
+            return this.secrets[index].cryptor
+        }
+    }
+
+    /**
+     * Retrieves the patient personal information associated to the `consultationId`
+     * The `consultationId` only helps to retrieve the patient lockboxes
+     * Note: it is possible to have several personal informations data
+     * @param consultationId The consultation Id
+     * @param category The personal MetadataCategory to fetch
+     * @param forceRefresh force data refresh (default to false)
+     * @returns the personal data
+     */
+    public async getPersonalInformationsFromConsultId(
+        consultationId: Uuid,
+        category:
+            | MetadataCategory.Personal
+            | MetadataCategory.ChildPersonal
+            | MetadataCategory.OtherPersonal,
+        forceRefresh = false
+    ): Promise<LocalizedData<PopulatedWorkflowData>[]> {
+        return this.getMetaCategoryFromConsultId(
+            consultationId,
+            category,
+            forceRefresh
+        )
+    }
+
+    /**
+     * Retrieves the patient medical data associated to the `consultationId`
+     * The `consultationId` only helps to retrieve the patient lockboxes
+     * Note: it is possible to have several medical data
+     * @param consultationId The consultation Id
+     * @param forceRefresh force data refresh (default to false)
+     * @returns the medical data
+     */
+    public async getMedicalDataFromConsultId(
+        consultationId: Uuid,
+        forceRefresh = false
+    ): Promise<LocalizedData<PopulatedWorkflowData>[]> {
+        return this.getMetaCategoryFromConsultId(
+            consultationId,
+            MetadataCategory.Medical,
+            forceRefresh
+        )
+    }
+
+    private async getMetaCategoryFromConsultId(
+        consultationId: Uuid,
+        category: MetadataCategory,
+        forceRefresh = false
+    ): Promise<LocalizedData<PopulatedWorkflowData>[]> {
+        let grants = await this.getGrants({ consultationId })
+        let workflowData: LocalizedData<PopulatedWorkflowData>[] = []
+        for (let grant of grants) {
+            let manifest = await this.getLockboxManifest(
+                grant.lockboxUuid!,
+                {
+                    category,
+                    documentType: DocumentType.PopulatedWorkflowData,
+                    consultationIds: [consultationId],
+                },
+                true,
+                grant.lockboxOwnerUuid,
+                forceRefresh
+            )
+
+            // TODO: find another solution for backwards compatibility (those without the metadata consultationIds)
+            if (manifest.length === 0) {
+                manifest = (
+                    await this.getLockboxManifest(
+                        grant.lockboxUuid!,
+                        {
+                            category,
+                            documentType: DocumentType.PopulatedWorkflowData,
+                            // backward compatiblility with TonTest
+                        },
+                        true,
+                        grant.lockboxOwnerUuid,
+                        forceRefresh
+                    )
+                ).filter((entry) => !entry.metadata.consultationIds) // Keep only entries without associated consultationIds
+            }
+            let data = await Promise.all(
+                manifest.map(async (entry) => {
+                    return {
+                        lockboxOwnerUuid: grant.lockboxOwnerUuid,
+                        lockboxUuid: grant.lockboxUuid!,
+                        dataUuid: entry.dataUuid,
+                        data: await this.getJsonData<PopulatedWorkflowData>(
+                            grant.lockboxUuid!,
+                            entry.dataUuid
+                        ),
+                    }
+                })
+            )
+            workflowData = { ...workflowData, ...data }
+        }
+        return workflowData
+    }
+
+    /**
+     * @description retrieves the personal information stored in the first owned lockbox
+     * @param userId The user Id
+     * @returns the personal data
+     */
+    public async getPersonalInformations(
+        userId: Uuid
+    ): Promise<LocalizedData<PopulatedWorkflowData>> {
+        const grant = (await this.getGrants()).find(
+            (lockbox) => lockbox.lockboxOwnerUuid === userId
+        )
+
+        if (!grant) {
+            throw MissingGrant
+        }
+
+        const { lockboxUuid, lockboxOwnerUuid } = grant
+
+        if (!lockboxUuid) throw MissingLockbox
+
+        if (!lockboxOwnerUuid) throw MissingLockboxOwner
+
+        const identificationDataUuid = (
+            await this.getLockboxManifest(
+                lockboxUuid,
+                {
+                    category: MetadataCategory.Personal,
+                    documentType: DocumentType.PopulatedWorkflowData,
+                },
+                false,
+                userId
+            )
+        )[0].dataUuid
+
+        return {
+            lockboxOwnerUuid,
+            lockboxUuid,
+            dataUuid: identificationDataUuid,
+            data: await this.getJsonData<PopulatedWorkflowData>(
+                lockboxUuid,
+                identificationDataUuid
+            ),
+        }
+    }
+
+    /**
+     * Retrieves the grant associated to a consultationId
+     * @note returns the first grant only
+     * @param consultationId The consultationId
+     * @returns the grant
+     */
+    public async getGrantFromConsultId(
+        consultationId: Uuid
+    ): Promise<Grant | undefined> {
+        let grants = await this.getGrants({ consultationId })
+
+        if (grants.length === 0) {
+            throw AssociatedLockboxNotFound
+        }
+
+        return grants[0]
+    }
+
+    /**
+     * retrieves the identity associated to the `consultationId`
+     * @param consultationId The consultation Id
+     * @returns the identity
+     */
+    public async getIdentityFromConsultId(
+        consultationId: Uuid
+    ): Promise<IdentityResponse | undefined> {
+        const grant = await this.getGrantFromConsultId(consultationId)
+
+        if (grant && grant.lockboxOwnerUuid) {
+            return await this.guardClient.identityGet(grant.lockboxOwnerUuid)
+        } else {
+            return undefined
+        }
+    }
+
+    /**
+     * retrieves the lockbox manifest for a given lockbox and add's its private metadata
+     * @note the lockbox manifest will retrieved the cached manifest first unless force refresh is enabled
+     * @param lockboxUuid
+     * @param filter
+     * @param expandPrivateMetadata
+     * @param lockboxOwnerUuid
+     * @param forceRefresh
+     * @returns the lockbox manifest
+     */
+    public async getLockboxManifest(
+        lockboxUuid: Uuid,
+        filter: Metadata,
+        expandPrivateMetadata: boolean,
+        lockboxOwnerUuid?: Uuid,
+        forceRefresh: boolean = false
+    ): Promise<LockboxManifest> {
+        let manifestKey = JSON.stringify({
+            lockboxUuid,
+            filter,
+            expandPrivateMetadata,
+            lockboxOwnerUuid,
+        })
+        if (!forceRefresh && this.cachedManifest[manifestKey])
+            return this.cachedManifest[manifestKey]
+
+        return this.vaultClient
+            .lockboxManifestGet(lockboxUuid, filter, lockboxOwnerUuid)
+            .then((manifest) => {
+                return Promise.all(
+                    manifest.map(async (entry) => {
+                        if (
+                            expandPrivateMetadata &&
+                            entry.metadata.privateMetadata
+                        ) {
+                            let privateMeta = await this.getJsonData<Metadata>(
+                                lockboxUuid!,
+                                entry.metadata.privateMetadata,
+                                lockboxOwnerUuid
+                            )
+                            entry.metadata = {
+                                ...entry.metadata,
+                                ...privateMeta,
+                            }
+                        }
+                        return entry
+                    })
+                ).then(
+                    (manifest) => (this.cachedManifest[manifestKey] = manifest)
+                )
+            })
+    }
+
+    /**
+     * @description Create or update the personal information and store it in the first owned lockbox
+     * @param identity The identity to use
+     * @param data The personal data to store
+     * @param dataUuid (optional) The dataUuid to update
+     * @returns
+     */
+    public async createPersonalInformations(
+        identity: IdentityResponse,
+        data: PopulatedWorkflowData,
+        dataUuid?: string
+    ): Promise<DataCreateResponse> {
+        const lockboxUuid = (await this.getGrants()).find(
+            (lockbox) => lockbox.lockboxOwnerUuid === identity.id
+        )?.lockboxUuid
+
+        if (lockboxUuid) {
+            return this.createJsonData<PersonalMeta>(
+                lockboxUuid,
+                data,
+                {
+                    category: MetadataCategory.Personal,
+                    documentType: DocumentType.PopulatedWorkflowData,
+                },
+                {},
+                undefined,
+                dataUuid
+            )
+        } else {
+            throw MissingLockbox
+        }
+    }
+
+    /**
+     * Create or update user Preference
+     * @param identity
+     * @param preference
+     * @param dataUuid
+     * @returns
+     */
+    public async createUserPreference(
+        identity: IdentityResponse,
+        preference: UserPreference,
+        dataUuid?: string
+    ): Promise<DataCreateResponse> {
+        const lockboxUuid = (await this.getGrants()).find(
+            (lockbox) => lockbox.lockboxOwnerUuid === identity.id
+        )?.lockboxUuid
+
+        if (lockboxUuid) {
+            return this.createJsonData<PreferenceMeta>(
+                lockboxUuid,
+                preference,
+                {
+                    category: MetadataCategory.Preference,
+                    contentType: 'application/json',
+                },
+                {},
+                undefined,
+                dataUuid
+            )
+        } else {
+            throw MissingLockbox
+        }
+    }
+
+    /**
+     * retrieves the user preference from a grant
+     * @param grant The grant
+     * @returns the user preference
+     */
+    public async getDataFromGrant<T = any>(
+        grant: Grant,
+        filter: Metadata
+    ): Promise<LocalizedData<T>> {
+        const { lockboxUuid, lockboxOwnerUuid } = grant
+
+        if (!lockboxUuid) throw MissingLockbox
+        if (!lockboxOwnerUuid) throw MissingLockboxOwner
+        const identificationDataUuid = (
+            await this.getLockboxManifest(
+                lockboxUuid,
+
+                filter,
+                false,
+                grant.lockboxOwnerUuid,
+                true
+            )
+        )[0].dataUuid
+
+        return {
+            lockboxOwnerUuid,
+            lockboxUuid,
+            dataUuid: identificationDataUuid,
+            data: await this.getJsonData<T>(
+                lockboxUuid,
+                identificationDataUuid
+            ),
+        }
+    }
+
+    /**
+     * retrieves the user preference from a consultation id
+     * @param consultationId The related consultationId
+     * @returns the user preference
+     */
+    public async getUserPreferenceFromConsultId(
+        consultationId: string
+    ): Promise<LocalizedData<UserPreference>> {
+        const grant = await this.getGrantFromConsultId(consultationId)
+
+        if (!grant) throw MissingGrant
+
+        return this.getDataFromGrant<UserPreference>(grant, {
+            category: MetadataCategory.Preference,
+            contentType: 'application/json',
+        })
+    }
+
+    /**
+     * retrieves the user preference stored in the first owned lockbox from identity
+     * @param identity The identity to use
+     * @returns the user preference
+     */
+    public async getUserPreference(
+        identity: IdentityResponse
+    ): Promise<LocalizedData<UserPreference>> {
+        const grant = (await this.getGrants()).find(
+            (lockbox) => lockbox.lockboxOwnerUuid === identity.id
+        )
+
+        if (!grant) throw MissingGrant
+
+        return this.getDataFromGrant<UserPreference>(grant, {
+            category: MetadataCategory.Preference,
+            contentType: 'application/json',
+        })
+    }
+
+    /**
+     * retrieves the user preference from a consultation id
+     * @param consultationId The related consultationId
+     * @returns the user preference
+     */
+    public async getRecoveryDataFromConsultId(
+        consultationId: string
+    ): Promise<LocalizedData<RecoveryData>> {
+        const grant = await this.getGrantFromConsultId(consultationId)
+
+        if (!grant) throw MissingGrant
+
+        return this.getDataFromGrant<RecoveryData>(grant, {
+            category: MetadataCategory.Recovery,
+            contentType: 'application/json',
+        })
+    }
+
+    /**
+     * retrieves the user preference stored in the first owned lockbox from identity
+     * @param identity The identity to use
+     * @returns the user preference
+     */
+    public async getRecoveryData(
+        identity: IdentityResponse
+    ): Promise<LocalizedData<RecoveryData>> {
+        const grant = (await this.getGrants()).find(
+            (lockbox) => lockbox.lockboxOwnerUuid === identity.id
+        )
+
+        if (!grant) throw MissingGrant
+
+        return this.getDataFromGrant(grant, {
+            category: MetadataCategory.Recovery,
+            contentType: 'application/json',
+        })
+    }
+
+    /**
+     * @name getAssignedConsultations
+     * @description finds all assigned or owned consultations for the logged user
+     * Steps:
+     *  - Retrieves all granted lockboxes given to the logged user
+     *  - for each lockbox, find all consultation ids
+     *  - for each consultation id, retrieve the consult information
+     *  @param practiceUuid the uuid of the practice to look consult into
+     * @returns the list of consults
+     */
+    public async getAssignedConsultations(
+        practiceUuid: Uuid,
+        forceRefresh: boolean = false
+    ): Promise<Consult[]> {
+        return Promise.all(
+            (await this.getGrants(undefined, forceRefresh)).map((grant) =>
+                this.getLockboxManifest(
+                    grant.lockboxUuid!,
+                    {
+                        category: MetadataCategory.Consultation,
+                        documentType: DocumentType.PopulatedWorkflowData,
+                    },
+                    true,
+                    undefined,
+                    forceRefresh
+                ).then((manifest) =>
+                    Promise.all(
+                        manifest.map(
+                            async (entry) =>
+                                await this.consultClient.getConsultByUUID(
+                                    entry.metadata.consultationId,
+                                    practiceUuid
+                                )
+                        )
+                    ).then((promise) => promise.flat())
+                )
+            )
+        ).then((consults) => consults.flat())
+    }
+
+    /**
+     * Gets the past consultations of the patient as well as his relatives if any
+     * @param consultationId any consultation uuid from which we will fetch all the other consultations of the same patient as the owner of this consultation id
+     * @param practiceUuid
+     */
+    public async getPastConsultationsFromConsultId(
+        consultationId: string,
+        practiceUuid: string
+    ): Promise<Consult[] | undefined> {
+        const grant = await this.getGrantFromConsultId(consultationId)
+        if (!grant) return undefined
+
+        let consultationsInLockbox: string[] = (
+            await this.vaultClient.lockboxMetadataGet(
+                grant.lockboxUuid!,
+                ['consultationId'],
+                ['consultationId'],
+                {
+                    category: MetadataCategory.Consultation,
+                    documentType: DocumentType.PopulatedWorkflowData,
+                },
+                grant.lockboxOwnerUuid
+            )
+        )
+            .flat()
+            .map(
+                (metadata: { consultationId: string }) =>
+                    metadata.consultationId
+            )
+
+        if (consultationsInLockbox.length == 0) return []
+
+        return await Promise.all(
+            consultationsInLockbox.map(async (consultId: string) => {
+                return await this.consultClient.getConsultByUUID(
+                    consultId,
+                    practiceUuid
+                )
+            })
+        )
+    }
+
+    /**
+     * @name getPatientConsultationData
+     * @description retrieves the consultation data
+     * @param consultationId
+     * @returns
+     */
+    public async getPatientConsultationData(
+        consultationId: Uuid,
+        forceRefresh: boolean = false
+    ): Promise<PopulatedWorkflowData[]> {
+        //TODO: make use of getPatientDocumentsList instead of doing it manually here
+        return Promise.all(
+            (await this.getGrants({ consultationId }, forceRefresh))
+                .map((grant) =>
+                    this.getLockboxManifest(
+                        grant.lockboxUuid!,
+                        {
+                            category: MetadataCategory.Consultation,
+                            documentType: DocumentType.PopulatedWorkflowData,
+                            consultationId, //since we want to update the cached manifest (if another consult data exists)
+                        },
+                        true,
+                        grant.lockboxOwnerUuid,
+                        forceRefresh
+                    ).then((manifest) =>
+                        Promise.all(
+                            manifest.map((e) =>
+                                this.getJsonData<PopulatedWorkflowData>(
+                                    grant.lockboxUuid!,
+                                    e.dataUuid,
+                                    grant.lockboxOwnerUuid
+                                )
+                            )
+                        )
+                    )
+                )
+                .flat()
+        ).then((data) => data.flat())
+    }
+
+    /**
+     * This function returns the patient prescriptions
+     * @param consultationId
+     * @returns
+     */
+    public async getPatientPrescriptionsList(
+        consultationId: Uuid
+    ): Promise<Document[]> {
+        return this.getPatientDocumentsList(
+            {
+                category: MetadataCategory.Consultation,
+                documentType: DocumentType.Prescription,
+            },
+            true,
+            consultationId
+        )
+    }
+
+    /**
+     * This function returns the patient results
+     * @param consultationId
+     * @returns
+     */
+    public async getPatientResultsList(
+        consultationId: Uuid
+    ): Promise<Document[]> {
+        return this.getPatientDocumentsList(
+            {
+                category: MetadataCategory.Consultation,
+                documentType: DocumentType.Result,
+            },
+            true,
+            consultationId
+        )
+    }
+
+    /**
+     * returns the patient treatment plan options
+     * @param consultationId
+     * @returns Document[] corresponding to the patient treatment plan options
+     */
+    public async getPatientTreatmentPlans(
+        consultationId: Uuid
+    ): Promise<Document[]> {
+        return this.getPatientDocumentsList(
+            {
+                category: MetadataCategory.Consultation,
+                documentType: DocumentType.TreatmentPlan,
+            },
+            true,
+            consultationId
+        )
+    }
+
+    /**
+     * returns a specific patient treatment plan option
+     * @param consultationId
+     * @param treatmentPlanId
+     * @returns
+     */
+    public async getPatientTreatmentPlanByUuid(
+        consultationId: Uuid,
+        treatmentPlanId: Uuid
+    ): Promise<Document[]> {
+        return this.getPatientDocumentsList(
+            {
+                category: MetadataCategory.Consultation,
+                documentType: DocumentType.TreatmentPlan,
+                treatmentPlanId,
+            },
+            true,
+            consultationId
+        )
+    }
+
+    /**
+     * @name getPatientDocumentsList
+     * @description applies the provided filter to the vault to only find those documents
+     * @param filters the applied filters (e.g. type of documents)
+     * @param expandPrivateMetadata whether or not, the private metadata needs to be retrieved
+     *  (more computationally expensive)
+     * @param consultationId
+     * @returns the filtered document list
+     */
+    public async getPatientDocumentsList(
+        filters: Object,
+        expandPrivateMetadata: boolean,
+        consultationId: Uuid
+    ): Promise<Document[]> {
+        return Promise.all(
+            (await this.getGrants({ consultationId }))
+                .map((grant) =>
+                    this.getLockboxManifest(
+                        grant.lockboxUuid!,
+                        { ...filters, consultationId },
+                        expandPrivateMetadata,
+                        grant.lockboxOwnerUuid,
+                        true
+                    ).then((manifest) =>
+                        Promise.all(
+                            manifest.map(
+                                async (entry): Promise<Document> => {
+                                    return {
+                                        lockboxOwnerUuid:
+                                            grant.lockboxOwnerUuid,
+                                        lockboxUuid: grant.lockboxUuid!,
+                                        ...entry,
+                                    }
+                                }
+                            )
+                        )
+                    )
+                )
+                .flat()
+        ).then((data) => data.flat())
+    }
+
+    /****************************************************************************************************************
+     *                                                  RECOVERY                                                    *
+     ****************************************************************************************************************/
+
+    /**
+     * @name recoverPrivateKeyFromSecurityQuestions
+     * @description Recovers and sets the rsa private key from the answered security questions
+     * @param id
+     * @param recoverySecurityQuestions
+     * @param recoverySecurityAnswers
+     * @param threshold the number of answers needed to recover the key
+     */
+    public async recoverPrivateKeyFromSecurityQuestions(
+        id: Uuid,
+        recoverySecurityQuestions: string[],
+        recoverySecurityAnswers: string[],
+        threshold: number
+    ) {
+        let shards: SecretShard[] = (await this.guardClient.identityGet(id))
+            .recoverySecurityQuestions
+        let answeredShards = shards
+            .filter((shard: any) => {
+                // filters all answered security questions
+                let indexOfQuestion = recoverySecurityQuestions.indexOf(
+                    shard.securityQuestion
+                )
+                if (indexOfQuestion === -1) return false
+                return (
+                    recoverySecurityAnswers[indexOfQuestion] &&
+                    recoverySecurityAnswers[indexOfQuestion] != ''
+                )
+            })
+            .map((item: any) => {
+                // appends the security answer to the answered shards
+                let index = recoverySecurityQuestions.indexOf(
+                    item.securityQuestion
+                )
+                item.securityAnswer = recoverySecurityAnswers[index]
+                return item
+            })
+        try {
+            // reconstructs the key from the answered security answers
+            let privateKey = this.toolbox.reconstructSecret(
+                answeredShards,
+                threshold
+            )
+            this.rsa = this.toolbox.CryptoRSA.fromKey(privateKey)
+        } catch (e) {
+            console.error(e)
+        }
+    }
+
+    /**
+     * @name recoverPrivateKeyFromPassword
+     * @description Recovers and sets the rsa private key from the password
+     * @param id
+     * @param password
+     */
+    public async recoverPrivateKeyFromPassword(id: Uuid, password: string) {
+        let identity = await this.guardClient.identityGet(id)
+
+        let recoveryPayload = identity.recoveryPassword
+        let symmetricDecryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+            password
+        )
+        let privateKey = symmetricDecryptor.base64PayloadDecryptToBytes(
+            recoveryPayload
+        )
+
+        if (identity.recoveryLogin) {
+            //Ensure we can recover from a page reload
+            let symetricEncryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+                identity.recoveryLogin
+            )
+            sessionStorage.setItem(
+                sessionStorePrivateKeyName(id),
+                symetricEncryptor.bytesEncryptToBase64Payload(privateKey)
+            )
+        }
+
+        this.rsa = this.toolbox.CryptoRSA.fromKey(privateKey)
+    }
+
+    /**
+     * @name recoverPrivateKeyFromMasterKey
+     * @description Recovers and sets the rsa private key from the master key
+     * @param id
+     * @param masterKey
+     */
+    public async recoverPrivateKeyFromMasterKey(id: Uuid, masterKey: string) {
+        let recoveryPayload = (await this.guardClient.identityGet(id))
+            .recoveryMasterKey
+        let symmetricDecryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+            masterKey
+        )
+        let privateKey = symmetricDecryptor.base64PayloadDecryptToBytes(
+            recoveryPayload
+        )
+        this.rsa = this.toolbox.CryptoRSA.fromKey(privateKey)
+    }
+
+    /**
+     * @description Generates and updates the security questions and answers payload using new recovery questions and answers
+     * Important: Since the security questions generate a payload for the private key, they will never be stored on the device as they must remain secret!!!
+     * @param id
+     * @param recoverySecurityQuestions
+     * @param recoverySecurityAnswers
+     * @param threshold the number of answers needed to rebuild the secret
+     */
+    public async updateSecurityQuestions(
+        id: Uuid,
+        recoverySecurityQuestions: string[],
+        recoverySecurityAnswers: string[],
+        threshold: number
+    ) {
+        if (!this.rsa) throw IncompleteAuthentication
+        let securityQuestionPayload = this.toolbox.breakSecretIntoShards(
+            recoverySecurityQuestions,
+            recoverySecurityAnswers,
+            this.rsa.private(),
+            threshold
+        )
+        let updateRequest = {
+            recoverySecurityQuestions: securityQuestionPayload,
+        }
+
+        return await this.guardClient.identityUpdate(id, updateRequest)
+    }
+
+    /**
+     * @description Generates and stores the payload encrypted payload and updates the password itself (double hash)
+     * @important
+     *  the recovery payload uses a singly hashed password and the password stored is doubly hashed so
+     *  the stored password cannot derive the decryption key in the payload
+     * @note
+     *  the old password must be provided when not performing an account recovery
+     * @param id
+     * @param newPassword
+     * @param oldPassword
+     */
+    public async updatePassword(
+        id: Uuid,
+        newPassword: string,
+        oldPassword?: string
+    ) {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let symmetricEncryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+            newPassword
+        )
+        let passwordPayload = symmetricEncryptor.bytesEncryptToBase64Payload(
+            this.rsa.private()
+        )
+        if (oldPassword) {
+            oldPassword = this.toolbox.hashStringToBase64(
+                this.toolbox.hashStringToBase64(oldPassword)
+            )
+        }
+
+        newPassword = this.toolbox.hashStringToBase64(
+            this.toolbox.hashStringToBase64(newPassword)
+        )
+
+        let updateRequest = {
+            password: {
+                oldPassword,
+                newPassword,
+            },
+            recoveryPassword: passwordPayload,
+        }
+
+        return await this.guardClient.identityUpdate(id, updateRequest)
+    }
+
+    /**
+     * @description Generates and stores the master key encrypted payload
+     * Important
+     *  Since the master key is used to generate a payload for the private key, it will never be stored on the device as it must remain secret!
+     * @param id
+     * @param masterKey
+     * @param lockboxUuid
+     */
+    async updateMasterKey(id: Uuid, masterKey: string, lockboxUuid: Uuid) {
+        if (!this.rsa) throw IncompleteAuthentication
+
+        let symmetricEncryptor = this.toolbox.CryptoChaCha.fromPassphrase(
+            masterKey
+        )
+        let masterKeyPayload = symmetricEncryptor.bytesEncryptToBase64Payload(
+            this.rsa.private()
+        )
+        let updateRequest = { recoveryMasterKey: masterKeyPayload }
+        const updatedIdentity = await this.guardClient.identityUpdate(
+            id,
+            updateRequest
+        )
+
+        await this.getOrInsertJsonData<RecoveryMeta>(
+            lockboxUuid,
+            { masterKey },
+            {
+                category: MetadataCategory.Recovery,
+                contentType: 'application/json',
+            },
+            {},
+            true
+        )
+
+        return updatedIdentity
+    }
+}