@binsky/passman-client-ts 0.1.10 → 0.2.0

package/lib/Model/Vault.d.ts

@@ -1,21 +1,64 @@
 import { NextcloudServerInterface } from "../Interfaces/NextcloudServer/NextcloudServerInterface";
 import Credential from "./Credential";
-import { VaultInterface } from "../Interfaces/Vault/VaultInterface";
+import { SpecificVaultInformationFromServerInterface } from "../Interfaces/Vault/SpecificVaultInformationFromServerInterface";
+import { SerializableTransferFullVaultInterface } from "../Interfaces/Vault/SerializableTransferFullVaultInterface";
 export default class Vault {
-    private data;
-    private server;
+    private _specificVaultInformation;
+    private readonly server;
     private _vaultKey;
-    constructor(data: VaultInterface, server: NextcloudServerInterface);
-    static create(vaultName: string, vaultPassword: string, server: NextcloudServerInterface): Promise<Vault>;
+    collectedTags: Set<string>;
+    private _credentials;
+    private constructor();
+    /**
+     * Filler for the now private Vault constructor. Use this carefully, or even better: do not use it!
+     * The constructor was previously used for custom re-creation from cache, this is now handled using a custom persistence service (when constructing PassmanClient).
+     * @param _specificVaultInformation
+     * @param server
+     * @deprecated use Vault.create() or Vault.fetchFullVaultFromServer() (with the option of setting getCachedIfPossible: boolean) instead.
+     */
+    static createManually(_specificVaultInformation: SpecificVaultInformationFromServerInterface, server: NextcloudServerInterface): Vault;
+    /**
+     * Create a new vault on the server and return an unlocked full-featured vault instance with fresh data.
+     * @param vaultName
+     * @param vaultPassword
+     * @param server
+     * @return new fresh vault instance or void if something went wrong
+     */
+    static create(vaultName: string, vaultPassword: string, server: NextcloudServerInterface): Promise<Vault | void>;
+    /**
+     * Creates a locked full-featured vault instance with fresh data (metadata, credentials, shared credentials) from the passman server.
+     * Optional: directly unlock by providing the correct vault key.
+     */
+    static fetchFullVaultFromServer(server: NextcloudServerInterface, guid: string, vaultKey?: string, getCachedIfPossible?: boolean): Promise<Vault | void>;
+    /**
+     * Clear all request caches for this vault. (not for the specific credentials that's managed by the Credential model)
+     */
+    clearRequestCache(): Promise<void>;
+    /**
+     * Reload current vault's metadata and credentials (as well as shared credentials) from the server.
+     * @param getCachedIfPossible
+     */
     refresh(getCachedIfPossible?: boolean): Promise<boolean>;
     update(): Promise<boolean>;
     delete(currentPassword: string): Promise<boolean>;
     lock(): void;
+    /**
+     * Set the given sharing keys for the current vault on the server. Does not (!) store the given keys in the current vault object.
+     * @param public_sharing_key
+     * @param private_sharing_key
+     */
     updateSharingKeys(public_sharing_key: string, private_sharing_key: string): Promise<void>;
     testVaultKey(vaultKey: string): boolean;
     private getChallengingFieldValue;
     private getFirstOwnedCredential;
     getCredentialByGuid(guid: string): Credential | undefined;
+    getAsSerializable(): SerializableTransferFullVaultInterface;
+    /**
+     * Returns a locked vault, made out of SerializableTransferFullVaultInterface data.
+     * @param serializable
+     * @param server
+     */
+    static fromSerializable(serializable: SerializableTransferFullVaultInterface, server: NextcloudServerInterface): Vault;
     getServer(): NextcloudServerInterface;
     get vaultId(): number | null;
     get vaultKey(): string;

package/lib/Model/Vault.js

@@ -7,27 +7,48 @@ const Credential_1 = __importDefault(require("./Credential"));
 const PassmanCrypto_1 = require("../Service/PassmanCrypto");
 const ShareService_1 = require("../Service/ShareService");
 const File_1 = require("./File");
+const NextcloudServer_1 = require("./NextcloudServer");
 class Vault {
-    data;
+    _specificVaultInformation;
     server;
     _vaultKey;
-    constructor(data, server) {
-        this.data = data;
+    collectedTags = new Set();
+    _credentials;
+    constructor(_specificVaultInformation, server) {
+        this._specificVaultInformation = _specificVaultInformation;
         this.server = server;
+        this._credentials = [];
     }
+    /**
+     * Filler for the now private Vault constructor. Use this carefully, or even better: do not use it!
+     * The constructor was previously used for custom re-creation from cache, this is now handled using a custom persistence service (when constructing PassmanClient).
+     * @param _specificVaultInformation
+     * @param server
+     * @deprecated use Vault.create() or Vault.fetchFullVaultFromServer() (with the option of setting getCachedIfPossible: boolean) instead.
+     */
+    static createManually(_specificVaultInformation, server) {
+        return new Vault(_specificVaultInformation, server);
+    }
+    /**
+     * Create a new vault on the server and return an unlocked full-featured vault instance with fresh data.
+     * @param vaultName
+     * @param vaultPassword
+     * @param server
+     * @return new fresh vault instance or void if something went wrong
+     */
     static async create(vaultName, vaultPassword, server) {
         let vaultResponse = await server.postJson('/vaults', { vault_name: vaultName }, (response) => {
             server.logger.onError(response.message);
         });
         if (vaultResponse) {
-            const vault = new Vault(vaultResponse, server);
-            vault._vaultKey = vaultPassword;
+            const creator_only_vault = new Vault(vaultResponse, server);
+            creator_only_vault._vaultKey = vaultPassword;
             await PassmanCrypto_1.PassmanCrypto.generateRSAKeypair(2048).then(async (value) => {
                 if (value.keypair) {
                     const pemKeyPair = PassmanCrypto_1.PassmanCrypto.rsaKeyPairToPEM(value.keypair);
-                    await vault.updateSharingKeys(pemKeyPair.publicKey, pemKeyPair.privateKey);
+                    await creator_only_vault.updateSharingKeys(pemKeyPair.publicKey, pemKeyPair.privateKey);
                     // todo: create hidden test credential
-                    let testCredential = new Credential_1.default(vault, server);
+                    let testCredential = new Credential_1.default(creator_only_vault, server);
                     testCredential.label = 'Test key for vault ' + vaultName;
                     testCredential.hidden = true;
                     testCredential.password = 'lorum ipsum';
@@ -43,58 +64,88 @@ class Vault {
                     server.logger.onError('Failed to create a new vault rsa key-pair');
                 }
             });
-            return vault;
+            return await Vault.fetchFullVaultFromServer(server, creator_only_vault.guid, vaultPassword, false);
         }
     }
-    async refresh(getCachedIfPossible = false) {
-        let vaultResponse = await this.server.getJson('/vaults/' + this.guid, (response) => {
-            this.server.logger.onError(response.message);
+    /**
+     * Creates a locked full-featured vault instance with fresh data (metadata, credentials, shared credentials) from the passman server.
+     * Optional: directly unlock by providing the correct vault key.
+     */
+    static async fetchFullVaultFromServer(server, guid, vaultKey, getCachedIfPossible = false) {
+        let specificVaultResponse = await server.getJson('/vaults/' + guid, (response) => {
+            server.logger.onError(response.message);
         }, getCachedIfPossible);
-        if (vaultResponse) {
+        if (specificVaultResponse) {
+            const vault = new Vault(specificVaultResponse, server);
+            // test vault key with the challenge_password value, to have a definite unlock state for restoring decrypted credential data from cache
+            let vaultIsUnlocked = false;
+            if (vaultKey && vault.testVaultKey(vaultKey)) {
+                vault.vaultKey = vaultKey;
+                vaultIsUnlocked = true;
+            }
             const credentials = [];
-            for (const credentialData of vaultResponse.credentials) {
+            let collectedTags = [];
+            for (const encryptedCredentialDataFromServer of specificVaultResponse.credentials) {
                 try {
-                    credentials.push(await Credential_1.default.fromData(credentialData, this, this.server));
+                    const credential = Credential_1.default.fromData(encryptedCredentialDataFromServer, vault, server);
+                    // restore and counting tags only if the correct vaultKey is given (current vault can then be assumed as unlocked)
+                    if (vaultIsUnlocked === true) {
+                        if (getCachedIfPossible) {
+                            await credential.restoreSerializedDecryptedDataCache();
+                        }
+                        if (credential.tags && credential.tags.length > 0) {
+                            collectedTags = collectedTags.concat(credential.tags.map(value => value.text).filter(Boolean));
+                        }
+                    }
+                    credentials.push(credential);
                 }
                 catch (e) {
-                    this.server.logger.anyError(e);
-                    this.server.logger.onError('Failed to decrypt credential: ' + credentialData.label);
+                    server.logger.anyError(e);
+                    server.logger.onError('Failed to decrypt credential: ' + encryptedCredentialDataFromServer.label);
                 }
             }
-            const credentialsSharedWithUs = await ShareService_1.ShareService.getCredentialsSharedWithUs(this, this.server, getCachedIfPossible);
+            vault.collectedTags = new Set(collectedTags);
+            const credentialsSharedWithUs = await ShareService_1.ShareService.getCredentialsSharedWithUs(vault, server, getCachedIfPossible);
             for (const credential of credentialsSharedWithUs) {
                 credentials.push(credential);
             }
+            vault._credentials = credentials;
+            // we could also test vault key here when we have all credentials, but it would make it harder to restore decrypted credential cache
+            return vault;
+        }
+    }
+    /**
+     * Clear all request caches for this vault. (not for the specific credentials that's managed by the Credential model)
+     */
+    clearRequestCache() {
+        return this.server.persistence.getRequestCacheHandler().set(NextcloudServer_1.NextcloudServer.getRequestCachePrefix + '/vaults/' + this.guid, undefined);
+    }
+    /**
+     * Reload current vault's metadata and credentials (as well as shared credentials) from the server.
+     * @param getCachedIfPossible
+     */
+    async refresh(getCachedIfPossible = false) {
+        const vaultFromServer = await Vault.fetchFullVaultFromServer(this.server, this.guid, this.vaultKey, getCachedIfPossible);
+        if (vaultFromServer) {
+            this.collectedTags = vaultFromServer.collectedTags;
+            this._credentials = vaultFromServer.credentials;
             // todo: check if a creation of vault.private_sharing_key for old vaults is required
-            this.data = {
-                challenge_password: vaultResponse.challenge_password,
-                created: vaultResponse.created,
-                credentials: credentials,
-                delete_request_pending: vaultResponse.delete_request_pending,
-                guid: vaultResponse.guid,
-                last_access: vaultResponse.last_access,
-                name: vaultResponse.name,
-                private_sharing_key: vaultResponse.private_sharing_key,
-                public_sharing_key: vaultResponse.public_sharing_key,
-                sharing_keys_generated: vaultResponse.sharing_keys_generated,
-                vault_id: vaultResponse.vault_id,
-                vault_settings: vaultResponse.vault_settings,
-            };
+            this._specificVaultInformation = vaultFromServer._specificVaultInformation;
             return true;
         }
         return false;
     }
     async update() {
-        const result = await this.server.postJson('/vaults/' + this.data.guid, {
-            guid: this.data.guid,
-            vault_id: this.data.vault_id,
-            name: this.data.name,
-            created: this.data.created,
-            public_sharing_key: this.data.public_sharing_key,
-            last_access: this.data.last_access,
-            delete_request_pending: this.data.delete_request_pending,
-            sharing_keys_generated: this.data.sharing_keys_generated,
-            vault_settings: this.data.vault_settings
+        const result = await this.server.postJson('/vaults/' + this._specificVaultInformation.guid, {
+            guid: this._specificVaultInformation.guid,
+            vault_id: this._specificVaultInformation.vault_id,
+            name: this._specificVaultInformation.name,
+            created: this._specificVaultInformation.created,
+            public_sharing_key: this._specificVaultInformation.public_sharing_key,
+            last_access: this._specificVaultInformation.last_access,
+            delete_request_pending: this._specificVaultInformation.delete_request_pending,
+            sharing_keys_generated: this._specificVaultInformation.sharing_keys_generated,
+            vault_settings: this._specificVaultInformation.vault_settings
         }, (response) => {
             this.server.logger.onError(response.message);
         }, 'PATCH');
@@ -135,14 +186,21 @@ class Vault {
     }
     lock() {
         this.vaultKey = null;
+        this.collectedTags.clear();
         // clear decrypted credential cache from memory
-        for (const credential of this.data.credentials) {
+        // no need to touch _specificVaultInformation.credentials since these are fully encrypted
+        for (const credential of this._credentials) {
             credential.clearDecryptedDataCache();
         }
     }
+    /**
+     * Set the given sharing keys for the current vault on the server. Does not (!) store the given keys in the current vault object.
+     * @param public_sharing_key
+     * @param private_sharing_key
+     */
     async updateSharingKeys(public_sharing_key, private_sharing_key) {
-        return await this.server.postJson('/vaults/' + this.data.guid + '/sharing-keys', {
-            guid: this.data.guid,
+        return await this.server.postJson('/vaults/' + this._specificVaultInformation.guid + '/sharing-keys', {
+            guid: this._specificVaultInformation.guid,
             public_sharing_key: public_sharing_key,
             private_sharing_key: PassmanCrypto_1.PassmanCrypto.encryptString(private_sharing_key, this.vaultKey),
         }, (response) => {
@@ -166,6 +224,7 @@ class Vault {
     }
     getChallengingFieldValue() {
         const testCredential = this.getFirstOwnedCredential();
+        // use getEncrypted to prevent trying to decrypt an already decrypted or cached value
         if (testCredential.getEncrypted().username != null) {
             return testCredential.getEncrypted().username;
         }
@@ -179,7 +238,7 @@ class Vault {
     }
     getFirstOwnedCredential() {
         for (let credential of this.credentials) {
-            if (!credential.hasValidSharedKey() && credential.sharedCredentialEncryptionKey === undefined) {
+            if (!credential.hasValidSharedKey() && credential.encryptedSharedCredentialEncryptionKey === undefined) {
                 return credential;
             }
         }
@@ -191,11 +250,32 @@ class Vault {
             }
         }
     }
+    getAsSerializable() {
+        const { credentials, ...serializableSpecificVaultInformation } = this._specificVaultInformation;
+        return {
+            serializableSpecificVaultInformation,
+            encryptedSerializableCredentials: this.credentials.map(credential => credential.getAsSerializable()),
+        };
+    }
+    /**
+     * Returns a locked vault, made out of SerializableTransferFullVaultInterface data.
+     * @param serializable
+     * @param server
+     */
+    static fromSerializable(serializable, server) {
+        const specificVaultInformation = {
+            credentials: [],
+            ...serializable.serializableSpecificVaultInformation
+        };
+        const vault = new Vault(specificVaultInformation, server);
+        vault._credentials = serializable.encryptedSerializableCredentials.map(serializableCredential => Credential_1.default.fromSerializable(serializableCredential, vault, server));
+        return vault;
+    }
     getServer() {
         return this.server;
     }
     get vaultId() {
-        return this.data.vault_id;
+        return this._specificVaultInformation.vault_id;
     }
     get vaultKey() {
         return this._vaultKey;
@@ -204,49 +284,49 @@ class Vault {
         this._vaultKey = value;
     }
     get guid() {
-        return this.data.guid;
+        return this._specificVaultInformation.guid;
     }
     get name() {
-        return this.data.name;
+        return this._specificVaultInformation.name;
     }
     set name(value) {
-        this.data.name = value;
+        this._specificVaultInformation.name = value;
     }
     get created() {
-        return this.data.created;
+        return this._specificVaultInformation.created;
     }
     get public_sharing_key() {
-        return this.data.public_sharing_key;
+        return this._specificVaultInformation.public_sharing_key;
     }
     get private_sharing_key() {
-        return PassmanCrypto_1.PassmanCrypto.decryptString(this.data.private_sharing_key, this.vaultKey);
+        return PassmanCrypto_1.PassmanCrypto.decryptString(this._specificVaultInformation.private_sharing_key, this.vaultKey);
     }
     get sharing_keys_generated() {
-        return this.data.sharing_keys_generated;
+        return this._specificVaultInformation.sharing_keys_generated;
     }
     set sharing_keys_generated(value) {
-        this.data.sharing_keys_generated = value;
+        this._specificVaultInformation.sharing_keys_generated = value;
     }
     get last_access() {
-        return this.data.last_access;
+        return this._specificVaultInformation.last_access;
     }
     get challenge_password() {
-        return this.data.challenge_password;
+        return this._specificVaultInformation.challenge_password;
     }
     get delete_request_pending() {
-        return this.data.delete_request_pending;
+        return this._specificVaultInformation.delete_request_pending;
     }
     set delete_request_pending(value) {
-        this.data.delete_request_pending = value;
+        this._specificVaultInformation.delete_request_pending = value;
     }
     get vault_settings() {
-        return this.data.vault_settings;
+        return this._specificVaultInformation.vault_settings;
     }
     set vault_settings(value) {
-        this.data.vault_settings = value;
+        this._specificVaultInformation.vault_settings = value;
     }
     get credentials() {
-        return this.data.credentials ?? [];
+        return this._credentials;
     }
 }
 exports.default = Vault;

package/lib/PassmanClient.d.ts

@@ -2,33 +2,74 @@ import Vault from "./Model/Vault";
 import type { LoggingHandlerInterface } from "./Interfaces/LoggingHandlerInterface";
 import { NextcloudServerInfoInterface } from "./Interfaces/NextcloudServer/NextcloudServerInfoInterface";
 import type { NextcloudServerInterface } from "./Interfaces/NextcloudServer/NextcloudServerInterface";
+import PreloadedVault from "./Model/PreloadedVault";
+import { PersistenceInterface } from "./Interfaces/PersistenceInterface";
+import { RequestCachingHandlerInterface } from "./Interfaces/RequestCachingHandlerInterface";
 export declare class PassmanClient {
     readonly server: NextcloudServerInterface;
-    private logger;
-    vaults: Vault[];
+    private readonly logger;
     /**
-     * Create PassmanClient instance.
+     * Non-serializable in-memory object cache, useful for long-living instances.
+     * todo: may add a constructor option to disable this one to save memory (for short-living instances like webextensions)
+     */
+    protected readonly _fullFeaturedVaultObjectCache: Vault[];
+    /**
+     * Array of available vaults, with just enough metadata for a vault listing and to run testVaultKey('...').
+     */
+    protected _preloadedVaults: PreloadedVault[];
+    /**
+     * Create PassmanClient instance. Deprecated!
      * @param serverData
      * @param nextcloudServer
      * @param logger
+     * @param persistence
      * @throws ConfigurationError from nextcloud server configuration data
+     * @deprecated use PassmanClient.createInstance() instead in external/public libs
+     */
+    constructor(serverData: NextcloudServerInfoInterface, nextcloudServer?: NextcloudServerInterface, logger?: LoggingHandlerInterface, persistence?: PersistenceInterface);
+    /**
+     * Create PassmanClient instance.
+     * To use "auto restore on reconstruction" provide a custom persistence instance. This will never auto-unlock vaults.
+     * @param serverData
+     * @param nextcloudServer
+     * @param logger
+     * @param persistence
      */
-    constructor(serverData: NextcloudServerInfoInterface, nextcloudServer?: NextcloudServerInterface, logger?: LoggingHandlerInterface);
+    static createInstance(serverData: NextcloudServerInfoInterface, nextcloudServer?: NextcloudServerInterface, logger?: LoggingHandlerInterface, persistence?: PersistenceInterface): Promise<PassmanClient>;
+    protected restoreFromCacheHandler(cache: RequestCachingHandlerInterface): Promise<void>;
     /**
-     * Refresh local (internal) vaults cache.
+     * Preloads vaults or refreshes the preloaded vaults array, if getCachedIfPossible = false.
      * @param throwError
-     * @param preserveInMemoryVaultKeys
      * @param getCachedIfPossible
-     * @throws Error if throwError = true and the api request fails with an error
      */
-    refreshVaults(throwError?: boolean, preserveInMemoryVaultKeys?: boolean, getCachedIfPossible?: boolean): Promise<boolean>;
+    preloadVaults(throwError?: boolean, getCachedIfPossible?: boolean): Promise<boolean>;
     createVault(vaultName: string, vaultPassword: string): Promise<void | Vault>;
+    /**
+     * @deprecated use getFullVaultByGuid instead
+     * @param guid
+     * @param getCachedIfPossible
+     */
     getVaultByGuid(guid: string, getCachedIfPossible?: boolean): Promise<Vault>;
     /**
-     * Make sure that this.vaults is an array and not undefined, before using this method.
+     * Returns full vault from cache, or fetches it from the server (and updates the full-featured vault cache afterward).
+     * If a vault key is provided, it tries not only to unlock, also to restore decrypted data if getCachedIfPossible is set.
      * @param guid
+     * @param getCachedIfPossible
+     */
+    getFullVaultByGuid(guid: string, getCachedIfPossible?: boolean, vaultKey?: string): Promise<Vault>;
+    get preloadedVaults(): PreloadedVault[];
+    set preloadedVaults(preloadedVaults: PreloadedVault[]);
+    /**
+     * Returns the full-featured vault instance from the in-memory object cache, if possible.
+     * @param guid
+     * @private
+     */
+    protected _getFullFeaturedVaultFromObjectCacheByGuid(guid: string): Vault | void;
+    /**
+     * Add or update a full-featured vault instance in the in-memory object cache.
+     * @param vault
      * @private
      */
-    private _getVaultByGuid;
+    protected _updateFullFeaturedVaultInObjectCache(vault: Vault): void;
     getTranslation(lang?: string): Promise<void | object>;
 }

package/lib/PassmanClient.js

@@ -7,48 +7,78 @@ exports.PassmanClient = void 0;
 const NextcloudServer_1 = require("./Model/NextcloudServer");
 const Vault_1 = __importDefault(require("./Model/Vault"));
 const DefaultLoggingService_1 = require("./Service/DefaultLoggingService");
+const PreloadedVault_1 = __importDefault(require("./Model/PreloadedVault"));
+const DefaultPersistenceService_1 = require("./Service/DefaultPersistenceService");
 class PassmanClient {
     server;
     logger;
-    vaults;
     /**
-     * Create PassmanClient instance.
+     * Non-serializable in-memory object cache, useful for long-living instances.
+     * todo: may add a constructor option to disable this one to save memory (for short-living instances like webextensions)
+     */
+    _fullFeaturedVaultObjectCache;
+    /**
+     * Array of available vaults, with just enough metadata for a vault listing and to run testVaultKey('...').
+     */
+    _preloadedVaults;
+    /**
+     * Create PassmanClient instance. Deprecated!
      * @param serverData
      * @param nextcloudServer
      * @param logger
+     * @param persistence
      * @throws ConfigurationError from nextcloud server configuration data
+     * @deprecated use PassmanClient.createInstance() instead in external/public libs
      */
-    constructor(serverData, nextcloudServer, logger) {
+    constructor(serverData, nextcloudServer, logger, persistence) {
         this.logger = logger ?? new DefaultLoggingService_1.DefaultLoggingService();
-        this.server = nextcloudServer ?? new NextcloudServer_1.NextcloudServer(serverData, this.logger);
+        this.server = nextcloudServer ?? new NextcloudServer_1.NextcloudServer(serverData, this.logger, persistence ?? new DefaultPersistenceService_1.DefaultPersistenceService());
+        this._fullFeaturedVaultObjectCache = [];
+    }
+    /**
+     * Create PassmanClient instance.
+     * To use "auto restore on reconstruction" provide a custom persistence instance. This will never auto-unlock vaults.
+     * @param serverData
+     * @param nextcloudServer
+     * @param logger
+     * @param persistence
+     */
+    static async createInstance(serverData, nextcloudServer, logger, persistence) {
+        if (persistence?.autoRestoreOnReconstruction()) {
+            let passmanClient = new this(serverData, nextcloudServer ?? new NextcloudServer_1.NextcloudServer(serverData, logger, persistence), logger, persistence);
+            await passmanClient.restoreFromCacheHandler(persistence.getRequestCacheHandler());
+            return passmanClient;
+        }
+        else {
+            return new this(serverData, nextcloudServer, logger, persistence);
+        }
+    }
+    async restoreFromCacheHandler(cache) {
+        await this.preloadVaults(false, true);
+        // test for which vaults we have full-feature loading requests cached and hint-load them to be recreated from request cache
+        const cachePrefix = 'cache-getJson-';
+        for (const preloadedVault of this.preloadedVaults) {
+            const cachedValue = await cache.get(cachePrefix + '/vaults/' + preloadedVault.guid);
+            if (cachedValue && cachedValue !== '') {
+                await this.getFullVaultByGuid(preloadedVault.guid, true);
+            }
+        }
     }
     /**
-     * Refresh local (internal) vaults cache.
+     * Preloads vaults or refreshes the preloaded vaults array, if getCachedIfPossible = false.
      * @param throwError
-     * @param preserveInMemoryVaultKeys
      * @param getCachedIfPossible
-     * @throws Error if throwError = true and the api request fails with an error
      */
-    async refreshVaults(throwError = false, preserveInMemoryVaultKeys = true, getCachedIfPossible = false) {
-        let newVaults = [];
-        const vaults = await this.server.getJson('/vaults', (error) => {
+    async preloadVaults(throwError = false, getCachedIfPossible = false) {
+        const vaultsResponse = await this.server.getJson('/vaults', (error) => {
             console.error(error);
             if (throwError) {
                 this.logger.onThrow(error);
             }
         }, getCachedIfPossible);
-        if (vaults) {
-            vaults.forEach((vaultData) => {
-                const vault = new Vault_1.default(vaultData, this.server);
-                if (this.vaults !== undefined && preserveInMemoryVaultKeys) {
-                    const oldVaultInstance = this._getVaultByGuid(vault.guid);
-                    if (oldVaultInstance && oldVaultInstance.vaultKey && vault.testVaultKey(oldVaultInstance.vaultKey)) {
-                        vault.vaultKey = oldVaultInstance.vaultKey;
-                    }
-                }
-                newVaults.push(vault);
-            });
-            this.vaults = newVaults;
+        let newPreloadedVaults = PreloadedVault_1.default.parseResponse(vaultsResponse, this.server);
+        if (newPreloadedVaults) {
+            this.preloadedVaults = newPreloadedVaults;
             return true;
         }
         return false;
@@ -56,34 +86,70 @@ class PassmanClient {
     async createVault(vaultName, vaultPassword) {
         let newVault = await Vault_1.default.create(vaultName, vaultPassword, this.server);
         if (newVault) {
-            this.vaults.push(newVault);
+            this._updateFullFeaturedVaultInObjectCache(newVault);
             return newVault;
         }
     }
+    /**
+     * @deprecated use getFullVaultByGuid instead
+     * @param guid
+     * @param getCachedIfPossible
+     */
     async getVaultByGuid(guid, getCachedIfPossible = false) {
-        if (this.vaults === undefined) {
-            if (!await this.refreshVaults(false, true, getCachedIfPossible)) {
-                this.logger.onError("failed to refresh vaults");
-                return;
+        return this.getFullVaultByGuid(guid, getCachedIfPossible);
+    }
+    /**
+     * Returns full vault from cache, or fetches it from the server (and updates the full-featured vault cache afterward).
+     * If a vault key is provided, it tries not only to unlock, also to restore decrypted data if getCachedIfPossible is set.
+     * @param guid
+     * @param getCachedIfPossible
+     */
+    async getFullVaultByGuid(guid, getCachedIfPossible = false, vaultKey) {
+        if (getCachedIfPossible) {
+            const cachedVault = this._getFullFeaturedVaultFromObjectCacheByGuid(guid);
+            if (cachedVault) {
+                return cachedVault;
             }
         }
-        const foundVault = this._getVaultByGuid(guid);
-        if (foundVault) {
-            return foundVault;
+        const freshVault = await Vault_1.default.fetchFullVaultFromServer(this.server, guid, vaultKey, getCachedIfPossible);
+        if (freshVault) {
+            this._updateFullFeaturedVaultInObjectCache(freshVault);
+            return freshVault;
         }
         this.logger.onError(`vault with guid ${guid} not found`);
     }
+    get preloadedVaults() {
+        return this._preloadedVaults ?? [];
+    }
+    set preloadedVaults(preloadedVaults) {
+        this._preloadedVaults = preloadedVaults;
+    }
     /**
-     * Make sure that this.vaults is an array and not undefined, before using this method.
+     * Returns the full-featured vault instance from the in-memory object cache, if possible.
      * @param guid
      * @private
      */
-    _getVaultByGuid(guid) {
-        for (const element of this.vaults) {
-            if (element.guid === guid) {
-                return element;
+    _getFullFeaturedVaultFromObjectCacheByGuid(guid) {
+        for (const vault of this._fullFeaturedVaultObjectCache) {
+            if (vault.guid === guid) {
+                return vault;
+            }
+        }
+    }
+    /**
+     * Add or update a full-featured vault instance in the in-memory object cache.
+     * @param vault
+     * @private
+     */
+    _updateFullFeaturedVaultInObjectCache(vault) {
+        for (let i = 0; i < this._fullFeaturedVaultObjectCache.length; i++) {
+            if (this._fullFeaturedVaultObjectCache[i].guid === vault.guid) {
+                this._fullFeaturedVaultObjectCache[i] = vault;
+                return;
             }
         }
+        // add if vault was not found in the cache loop above
+        this._fullFeaturedVaultObjectCache.push(vault);
     }
     async getTranslation(lang = 'en') {
         return await this.server.getJson('/language?lang=' + lang, (response) => {