@icure/api 6.3.1 → 7.0.0-beta.0

package/dist/icc-x-api/crypto/EntitiesEncryption.js

@@ -0,0 +1,700 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitiesEncryption = void 0;
+const utils_1 = require("../utils");
+const _ = require("lodash");
+const collection_utils_1 = require("../utils/collection-utils");
+const ShareMetadataBehaviour_1 = require("./ShareMetadataBehaviour");
+/**
+ * @internal this class is for internal use only and may be changed without notice
+ * Give access to functions for retrieving encryption metadata of entities.
+ */
+class EntitiesEncryption {
+    constructor(primitives, dataOwnerApi, exchangeKeysManager) {
+        this.primitives = primitives;
+        this.dataOwnerApi = dataOwnerApi;
+        this.exchangeKeysManager = exchangeKeysManager;
+    }
+    /**
+     * Get the encryption keys of an entity that the provided data owner can access, potentially using the keys for his parent.
+     * There should only be one encryption key for each entity, but the method supports more to allow to deal with conflicts and merged duplicate data.
+     * @param entity an encrypted entity.
+     * @param dataOwnerId optionally a data owner part of the hierarchy for the current data owner, defaults to the current data owner.
+     * @param tagsFilter allows to obtain only encryption keys associated to tags which satisfy the provided filter.
+     * @return the encryption keys that the provided data owner can decrypt, deduplicated.
+     */
+    encryptionKeysOf(entity, dataOwnerId, tagsFilter = () => Promise.resolve(true)) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            // Legacy entities may have encryption keys in delegations.
+            return this.extractMergedHierarchyFromDelegationAndOwner(Object.keys((_a = entity.encryptionKeys) !== null && _a !== void 0 ? _a : {}).length > 0 ? entity.encryptionKeys : (_b = entity.delegations) !== null && _b !== void 0 ? _b : {}, dataOwnerId, (k) => this.validateEncryptionKey(k), (t) => tagsFilter(t));
+        });
+    }
+    /**
+     * Get the encryption keys of an entity that the current data owner and his parents can access. The resulting array contains the keys for each data
+     * owner in the hierarchy which can be decrypted using only that data owner keys (excludes keys accessible through the parent keys). The order of
+     * the array is the same as in {@link IccDataOwnerXApi.getCurrentDataOwnerHierarchyIds}.
+     * Note that different data owners may have access to the same keys, but the keys extracted for each data owner are deduplicated.
+     * There should only be one encryption key for each entity, but the method supports more to allow to deal with conflicts and merged duplicate data.
+     * @param entity an encrypted entity.
+     * @param tagsFilter allows to obtain only encryption keys associated to tags which satisfy the provided filter.
+     * @return the encryption keys that each member of the current data owner hierarchy can decrypt using only his keys and not keys of his parents.
+     */
+    encryptionKeysForHcpHierarchyOf(entity, tagsFilter = () => Promise.resolve(true)) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.extractedHierarchyFromDelegation((_a = entity.encryptionKeys) !== null && _a !== void 0 ? _a : {}, (k) => this.validateEncryptionKey(k), (t) => tagsFilter(t));
+        });
+    }
+    /**
+     * Get the secret ids (SFKs) of an entity that the provided data owner can access, potentially using the keys for his parent.
+     * @param entity an encrypted entity.
+     * @param dataOwnerId optionally a data owner part of the hierarchy for the current data owner, defaults to the current data owner.
+     * @param tagsFilter allows to obtain only secret ids associated to tags which satisfy the provided filter.
+     * @return the secret ids (SFKs) that the provided data owner can decrypt, deduplicated.
+     */
+    secretIdsOf(entity, dataOwnerId, tagsFilter = () => Promise.resolve(true)) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.extractMergedHierarchyFromDelegationAndOwner((_a = entity.delegations) !== null && _a !== void 0 ? _a : {}, dataOwnerId, (k) => this.validateSecretId(k), (t) => tagsFilter(t));
+        });
+    }
+    /**
+     * Get the secret ids (SFKs) of an entity that the current data owner and his parents can access. The resulting array contains the ids for each data
+     * owner in the hierarchy which can be decrypted using only that data owner keys (excludes ids accessible through the parent keys). The order of
+     * the array is the same as in {@link IccDataOwnerXApi.getCurrentDataOwnerHierarchyIds}.
+     * Note that different data owners may have access to the same secret ids, but the secret ids extracted for each data owner are deduplicated.
+     * @param entity an encrypted entity.
+     * @param tagsFilter allows to obtain only secret ids associated to tags which satisfy the provided filter.
+     * @return the secret ids that each member of the current data owner hierarchy can decrypt using only his keys and not keys of his parents.
+     */
+    secretIdsForHcpHierarchyOf(entity, tagsFilter = () => Promise.resolve(true)) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.extractedHierarchyFromDelegation((_a = entity.delegations) !== null && _a !== void 0 ? _a : {}, (k) => this.validateSecretId(k), (t) => tagsFilter(t));
+        });
+    }
+    /**
+     * Get the decrypted owning entity ids (formerly CFKs) for the provided entity that can be decrypted using the private keys of the current data
+     * owner and his parents. The owning entity id would be, for example, the id of a patient for contact and healthcare elements, or the id of a
+     * message for documents.
+     * There should only be one owning entity id for each entity, but the method supports more to allow to deal with conflicts and merged duplicate
+     * data.
+     * @param entity an encrypted entity.
+     * @param dataOwnerId optionally a data owner part of the hierarchy for the current data owner, defaults to the current data owner.
+     * @param tagsFilter allows to obtain only owning entity ids associated to tags which satisfy the provided filter.
+     * @return the owning entity ids (CFKs) that the provided data owner can decrypt, deduplicated.
+     */
+    owningEntityIdsOf(entity, dataOwnerId, tagsFilter = () => Promise.resolve(true)) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.extractMergedHierarchyFromDelegationAndOwner((_a = entity.cryptedForeignKeys) !== null && _a !== void 0 ? _a : {}, dataOwnerId, (k) => this.validateOwningEntityId(k), (t) => tagsFilter(t));
+        });
+    }
+    /**
+     * Get the decrypted owning entity ids (formerly CFKs) for the provided entity that can be decrypted using the private keys of the current data
+     * owner and his parents. The owning entity id would be, for example, the id of a patient for contact and healthcare elements, or the id of a
+     * message for documents.
+     * The resulting array contains the ids for each data owner in the hierarchy which can be decrypted using only that data owner keys (excludes ids
+     * accessible through the parent keys). The order of the array is the same as in {@link IccDataOwnerXApi.getCurrentDataOwnerHierarchyIds}.
+     * Note that different data owners may have access to the same owning entity ids, but the owning entity ids extracted for each data owner are
+     * deduplicated in case they could be accessed through different delegations.
+     * There should only be one owning entity id for each entity, but the method supports more to allow to deal with conflicts and merged duplicate
+     * data.
+     * @param entity an encrypted entity.
+     * @param tagsFilter allows to obtain only owning entity ids associated to tags which satisfy the provided filter.
+     * @return the owning entity ids that each member of the current data owner hierarchy can decrypt using only his keys and not keys of his parents.
+     */
+    owningEntityIdsForHcpHierarchyOf(entity, tagsFilter = () => Promise.resolve(true)) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.extractedHierarchyFromDelegation((_a = entity.cryptedForeignKeys) !== null && _a !== void 0 ? _a : {}, (k) => this.validateOwningEntityId(k), (t) => tagsFilter(t));
+        });
+    }
+    /**
+     * @internal this method is intended only for internal use and may be changed without notice.
+     * Initializes encryption metadata for an entity. This includes the encrypted secret id, owning entity id, and encryption key for the entity, and
+     * the clear text secret foreign key of the parent entity.
+     * This method returns a modified copy of the entity.
+     * @param entity entity which requires encryption metadata initialisation.
+     * @param owningEntity id of the owning entity, if any (e.g. patient id for Contact/HealtchareElement, message id for Document, ...).
+     * @param owningEntitySecretId secret id of the parent entity, to use in the secret foreign keys for the provided entity, if any.
+     * @param initialiseEncryptionKeys if false this method will not initialize any encryption keys. Use only for entities which use delegations for
+     * access control but don't actually have any encrypted content.
+     * @param additionalDelegations automatically shares the
+     * @param tags tags to associate with the initial encryption keys and metadata
+     * @throws if the entity already has non-empty values for encryption metadata.
+     * @return an updated copy of the entity.
+     */
+    entityWithInitialisedEncryptedMetadata(entity, owningEntity, owningEntitySecretId, initialiseEncryptionKeys, additionalDelegations = [], tags = []) {
+        return __awaiter(this, arguments, void 0, function* () {
+            this.throwDetailedExceptionForInvalidParameter('entity.id', entity.id, 'entityWithInitialisedEncryptedMetadata', arguments);
+            this.checkEmptyEncryptionMetadata(entity);
+            const secretId = this.primitives.randomUuid();
+            const rawEncryptionKey = initialiseEncryptionKeys ? (0, utils_1.ua2hex)(this.primitives.randomBytes(16)) : undefined;
+            const selfId = yield this.dataOwnerApi.getCurrentDataOwnerId();
+            const allIds = [selfId, ...new Set(additionalDelegations.filter((x) => x !== selfId))];
+            const loadKeysResult = yield this.loadEncryptionKeysForDelegates(entity, allIds);
+            const updatedEntity = yield allIds.reduce((prevUpdate, delegateId) => __awaiter(this, void 0, void 0, function* () {
+                return yield this.createOrUpdateEntityDelegations(yield prevUpdate, delegateId, [], [], [], [secretId], initialiseEncryptionKeys ? [rawEncryptionKey] : [], owningEntity ? [owningEntity] : [], tags, loadKeysResult.keysForDelegates);
+            }), Promise.resolve(loadKeysResult.updatedEntity));
+            if (owningEntitySecretId) {
+                updatedEntity.secretForeignKeys = [owningEntitySecretId];
+            }
+            return { updatedEntity, secretId, rawEncryptionKey };
+        });
+    }
+    entityWithAutoExtendedEncryptedMetadata(entity, delegateId, shareSecretIds, shareEncryptionKeys, shareOwningEntityIds) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (shareSecretIds === undefined) {
+                const availableSecretIds = yield this.secretIdsOf(entity);
+                if (availableSecretIds.length) {
+                    shareSecretIds = availableSecretIds;
+                }
+                else {
+                    shareSecretIds = [this.primitives.randomUuid()];
+                }
+            }
+            let actualShareEncryptionKeys = [];
+            if (shareEncryptionKeys !== ShareMetadataBehaviour_1.ShareMetadataBehaviour.NEVER) {
+                const availableEncryptionKeys = yield this.encryptionKeysOf(entity);
+                if (!availableEncryptionKeys.length && shareEncryptionKeys === ShareMetadataBehaviour_1.ShareMetadataBehaviour.REQUIRED) {
+                    throw new Error(`Entity ${JSON.stringify(entity)} has no encryption keys or the current data owner can't access any encryption keys.`);
+                }
+                actualShareEncryptionKeys = availableEncryptionKeys;
+            }
+            let actualShareOwningEntityIds = [];
+            if (shareOwningEntityIds !== ShareMetadataBehaviour_1.ShareMetadataBehaviour.NEVER) {
+                const availableOwningEntityIds = yield this.owningEntityIdsOf(entity);
+                if (!availableOwningEntityIds.length && shareOwningEntityIds === ShareMetadataBehaviour_1.ShareMetadataBehaviour.REQUIRED) {
+                    throw new Error(`Entity ${JSON.stringify(entity)} has no owning entity ids or the current data owner can't access any owning entity ids.`);
+                }
+                actualShareOwningEntityIds = availableOwningEntityIds;
+            }
+            return this.entityWithExtendedEncryptedMetadata(entity, delegateId, shareSecretIds, actualShareEncryptionKeys, actualShareOwningEntityIds);
+        });
+    }
+    /**
+     * Updates encryption metadata for an entity in order to share it with a delegate or in order to add additional encrypted metadata for an existing
+     * delegate.
+     * The first time this method is used for a specific delegate it will give access to all unencrypted content of the entity to the delegate data
+     * owner. Additionally, this method also allows to share new or existing secret ids (shareSecretId), encryption keys (shareEncryptionKeys) and
+     * owning entity ids (shareOwningEntityIds) for the entity.
+     * You can use methods like {@link secretIdsOf}, {@link secretIdsForHcpHierarchyOf}, {@link encryptionKeysOf}, ... to retrieve the data you want to
+     * share. In most cases you may want to share everything related to the entity, but note that if you use confidential delegations for patients you
+     * may want to avoid sharing the confidential secret ids of the current user with other hcps.
+     * This method returns a modified copy of the entity.
+     * @param entity entity which requires encryption metadata initialisation.
+     * @param delegateId id of the delegate to share data with.
+     * @param shareSecretIds secret ids to share.
+     * @param shareEncryptionKeys encryption keys to share.
+     * @param shareOwningEntityIds owning enttiy ids to share.
+     * @param newTags tags to associate with the new encryption keys and metadata. Existing data won't be changed.
+     * @throws if any of the shareX parameters is set to `true` but the corresponding piece of data could not be retrieved.
+     * @return an updated copy of the entity.
+     */
+    entityWithExtendedEncryptedMetadata(entity, delegateId, shareSecretIds, shareEncryptionKeys, shareOwningEntityIds, newTags = []) {
+        var _a, _b, _c;
+        return __awaiter(this, arguments, void 0, function* () {
+            this.throwDetailedExceptionForInvalidParameter('entity.id', entity.id, 'entityWithSharedEncryptedMetadata', arguments);
+            function checkInputAndGet(input, inputName, validate) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    for (const x of input) {
+                        const validation = validate(x);
+                        if (validation !== true && validation !== false && !(yield validation))
+                            throw new Error(`Invalid input for ${inputName}.`);
+                    }
+                    return input;
+                });
+            }
+            const secretIdsToShare = yield checkInputAndGet(shareSecretIds, 'secretIds', (x) => this.validateSecretId(x));
+            const encryptionKeysToShare = yield checkInputAndGet(shareEncryptionKeys, 'encryptionKeys', (x) => this.validateEncryptionKey(x));
+            const owningEntityIdsToShare = yield checkInputAndGet(shareOwningEntityIds, 'owningEntityIds', (x) => this.validateOwningEntityId(x));
+            const deduplicateInfoSecretIds = yield this.deduplicateDelegationsAndFilterRequiredEntries(delegateId, (_a = entity.delegations) !== null && _a !== void 0 ? _a : {}, secretIdsToShare, (x) => this.validateSecretId(x));
+            const deduplicateInfoEncryptionKeys = yield this.deduplicateDelegationsAndFilterRequiredEntries(delegateId, (_b = entity.encryptionKeys) !== null && _b !== void 0 ? _b : {}, encryptionKeysToShare, (x) => this.validateEncryptionKey(x));
+            const deduplicateInfoOwningEntityIds = yield this.deduplicateDelegationsAndFilterRequiredEntries(delegateId, (_c = entity.cryptedForeignKeys) !== null && _c !== void 0 ? _c : {}, owningEntityIdsToShare, (x) => this.validateOwningEntityId(x));
+            /*TODO
+             * Temporary hack since secret id is necessary to create a delegation for access control: if there is no delegation existing from me to the
+             * delegate and there is no new secret id to be created create a new random id.
+             */
+            const selfId = yield this.dataOwnerApi.getCurrentDataOwnerId();
+            if (deduplicateInfoSecretIds.missingEntries.length === 0 && !deduplicateInfoSecretIds.deduplicatedDelegations.some((d) => d.owner === selfId)) {
+                deduplicateInfoSecretIds.missingEntries.push(this.primitives.randomUuid());
+            }
+            if (deduplicateInfoSecretIds.missingEntries.length === 0 &&
+                deduplicateInfoEncryptionKeys.missingEntries.length === 0 &&
+                deduplicateInfoOwningEntityIds.missingEntries.length === 0)
+                return _.cloneDeep(entity);
+            const { updatedEntity, keysForDelegates } = yield this.loadEncryptionKeysForDelegates(entity, [delegateId]);
+            return this.createOrUpdateEntityDelegations(updatedEntity, delegateId, deduplicateInfoSecretIds.deduplicatedDelegations, deduplicateInfoEncryptionKeys.deduplicatedDelegations, deduplicateInfoOwningEntityIds.deduplicatedDelegations, deduplicateInfoSecretIds.missingEntries, deduplicateInfoEncryptionKeys.missingEntries, deduplicateInfoOwningEntityIds.missingEntries, newTags, keysForDelegates);
+        });
+    }
+    /**
+     * Encrypts data using a key of the entity that the provided data owner can access (current data owner by default). If the provided data owner can
+     * access multiple encryption keys of the entity there is no guarantee on which key will be used.
+     * Note: you should not use this method to encrypt the `encryptedSelf` of iCure entities, since that will be automatically handled by the extended
+     * apis. You should use this method only to encrypt additional data, such as document attachments.
+     * @param entity an entity.
+     * @param content data of the entity which you want to encrypt.
+     * @param dataOwnerId optionally a data owner part of the hierarchy for the current data owner, defaults to the current data owner.
+     * @param tagsFilter allows to use for encryption only keys associated to tags which pass the filter.
+     * @return the encrypted data.
+     * @throws if the provided data owner can't access any encryption keys for the entity.
+     */
+    encryptDataOf(entity, content, dataOwnerId, tagsFilter = () => Promise.resolve(true)) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const keys = yield this.encryptionKeysOf(yield this.ensureEncryptionKeysInitialised(entity), dataOwnerId, tagsFilter);
+            if (keys.length === 0)
+                throw new Error(`Could not extract any encryption keys of entity ${entity} for data owner ${dataOwnerId !== null && dataOwnerId !== void 0 ? dataOwnerId : (yield this.dataOwnerApi.getCurrentDataOwnerId())}.`);
+            return this.primitives.AES.encryptWithRawKey(keys[0], content);
+        });
+    }
+    /**
+     * Decrypts data using a key of the entity that the provided data owner can access (current data owner by default). If the provided data owner can
+     * access multiple encryption keys each of them will be tried for decryption until one of them gives a result that is valid according to the
+     * provided validator.
+     * Note: you should not use this method to decrypt the `encryptedSelf` of iCure entities, since that will be automatically handled by the extended
+     * apis. You should use this method only to decrypt additional data, such as document attachments.
+     * @param entity an entity.
+     * @param content data of the entity which you want to decrypt.
+     * @param dataOwnerId optionally a data owner part of the hierarchy for the current data owner, defaults to the current data owner.
+     * @param validator a function which verifies the correctness of decrypted content: helps to identify decryption with the wrong key without relying
+     * solely on padding.
+     * @param tagsFilter allows to use for decryption only keys associated to tags which pass the filter.
+     * @return the decrypted data.
+     * @throws if the provided data owner can't access any encryption keys for the entity, or if no key could be found which provided valid decrypted
+     * content according to the validator.
+     */
+    decryptDataOf(entity, content, validator = () => Promise.resolve(true), dataOwnerId, tagsFilter = () => Promise.resolve(true)) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const keys = yield this.encryptionKeysOf(entity, dataOwnerId, tagsFilter);
+            for (const key of keys) {
+                try {
+                    const decrypted = yield this.primitives.AES.decryptWithRawKey(key, content);
+                    if (yield validator(decrypted))
+                        return decrypted;
+                }
+                catch (e) {
+                    /* ignore */
+                }
+            }
+            throw new Error(`No valid key found to decrypt data of ${entity} for data owner ${dataOwnerId !== null && dataOwnerId !== void 0 ? dataOwnerId : (yield this.dataOwnerApi.getCurrentDataOwnerId())}.`);
+        });
+    }
+    /**
+     * @internal this method is intended for internal use only and may be changed without notice.
+     * Decrypts the content of an encrypted entity.
+     */
+    decryptEntity(entity, ownerId, constructor) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!entity.encryptedSelf)
+                return { entity, decrypted: true };
+            const encryptionKeys = yield this.importAllValidKeys(yield this.encryptionKeysOf(entity, ownerId));
+            if (!encryptionKeys.length)
+                return { entity, decrypted: false };
+            return {
+                entity: constructor(yield (0, utils_1.decrypt)(entity, (encrypted) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    return (_a = (yield this.tryDecryptJson(encryptionKeys, encrypted, false))) !== null && _a !== void 0 ? _a : {};
+                }))),
+                decrypted: true,
+            };
+        });
+    }
+    /**
+     * @internal this method is intended for internal use only and may be changed without notice.
+     * Tries using the provided keys to decrypt some json.
+     */
+    tryDecryptJson(potentialKeys, encrypted, truncateTrailingDecryptedNulls) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const key of potentialKeys) {
+                try {
+                    const decrypted = (_a = (yield this.primitives.AES.decrypt(key.key, encrypted, key.raw))) !== null && _a !== void 0 ? _a : encrypted;
+                    return JSON.parse((0, utils_1.ua2utf8)(truncateTrailingDecryptedNulls ? (0, utils_1.truncateTrailingNulls)(new Uint8Array(decrypted)) : decrypted));
+                }
+                catch (e) { }
+            }
+            return undefined;
+        });
+    }
+    /**
+     * @internal this method is intended for internal use only and may be changed without notice.
+     * Tries to encrypt the content of an encrypted entity.
+     * 1. If valid key for encryption is found the method returns the entity with the encrypted fields specified by cryptedKeys
+     * 2. If requireEncryption is true and no key could be found for encryption of the entity the method fails.
+     * 3. If requireEncryption is false and no key could be found for encryption the method will only check that the entity does not specify any value
+     * for fields which should be encrypted according to cryptedKeys (e.g. note in a patient by default). If the entity specifies a value for any field
+     * which should be encrypted the method throws an error, otherwise the method returns the original entity.
+     */
+    tryEncryptEntity(entity, dataOwnerId, cryptedKeys, encodeBinaryData, requireEncryption, constructor) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const entityWithInitialisedEncryptionKeys = yield this.ensureEncryptionKeysInitialised(entity);
+            const encryptionKey = yield this.tryImportFirstValidKey(yield this.encryptionKeysOf(entity, dataOwnerId), entity.id);
+            if (!!encryptionKey) {
+                return constructor(yield (0, utils_1.crypt)(entityWithInitialisedEncryptionKeys, (obj) => {
+                    const json = encodeBinaryData
+                        ? JSON.stringify(obj, (k, v) => {
+                            return v instanceof ArrayBuffer || v instanceof Uint8Array
+                                ? (0, utils_1.b2a)(new Uint8Array(v).reduce((d, b) => d + String.fromCharCode(b), ''))
+                                : v;
+                        })
+                        : JSON.stringify(obj);
+                    return this.primitives.AES.encrypt(encryptionKey.key, (0, utils_1.utf8_2ua)(json), encryptionKey.raw);
+                }, cryptedKeys));
+            }
+            else if (requireEncryption) {
+                throw new Error(`No key found for encryption of entity ${entity}`);
+            }
+            else {
+                const cryptedCopyWithRandomKey = yield (0, utils_1.crypt)(_.cloneDeep(entity), (obj) => __awaiter(this, void 0, void 0, function* () { return Promise.resolve(new ArrayBuffer(1)); }), cryptedKeys);
+                if (!_.isEqual(_.omitBy(Object.assign(Object.assign({}, cryptedCopyWithRandomKey), { encryptedSelf: undefined }), _.isNil), _.omitBy(Object.assign(Object.assign({}, entity), { encryptedSelf: undefined }), _.isNil))) {
+                    throw new Error(`Impossible to modify encrypted value of an entity if no encryption key is known.\n${entity}`);
+                }
+                return entity;
+            }
+        });
+    }
+    /**
+     * @internal This method is for internal use only and may be changed without notice.
+     * Ensures that the encryption keys of an entity are initialised. If not will throw an exception or initialise them depending on the content of
+     * the entity. This function supports migration of entities using older encryption schemes (delegation only without encrypted keys) or entities
+     * which were previously not encrypted.
+     */
+    ensureEncryptionKeysInitialised(entity) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (Object.keys((_a = entity.encryptionKeys) !== null && _a !== void 0 ? _a : {}).length > 0)
+                return entity;
+            if (!entity.rev) {
+                throw new Error('New encrypted entity is lacking encryption metadata. ' +
+                    'Please instantiate new entities using the `newInstance` method from the respective extended api.');
+            }
+            /*
+             * If entity was using delegations as legacy encryption keys we will essentially revoke the access to the encrypted data for all other data
+             * owners. This however should not be a problem as this form of legacy entities should not exist anymore, and it should be present only in the
+             * databases of hcps without collaborators.
+             */
+            return yield this.entityWithExtendedEncryptedMetadata(entity, yield this.dataOwnerApi.getCurrentDataOwnerId(), [], [(0, utils_1.ua2hex)(this.primitives.randomBytes(16))], []);
+        });
+    }
+    /**
+     * Get the decrypted content of a delegation-like object which the provided data owner would be able to access using ONLY HIS EXCHANGE KEYS (does
+     * not consider exchange keys for parents).
+     * Note that the retrieved exchange keys are decrypted using the private keys available on the device, and results may vary from other devices.
+     * @param dataOwnerId id of a data owner, he should be part of the current data owner hierarchy.
+     * @param delegations a delegation-like object containing the encrypted key
+     * @param includeFromDelegations if true also considers delegation from the provided data owner (or parents) to look for values. This allows to
+     * decrypt delegations associated to exchange keys recovered after a giveAccessBack request.
+     * @param validateDecrypted validates the decrypted result, to drop decryption results with wrong key that still gave a valid checksum.
+     * @param tagsFilter allows to obtain only encryption keys associated to tags which satisfy the provided filter.
+     * @return the key which could be decrypted using only keys available on the current device and delegations from/to the provided data owner. May
+     * contain duplicates.
+     */
+    extractFromDelegationsForDataOwner(dataOwnerId, delegations, includeFromDelegations, validateDecrypted, tagsFilter) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const delegationsWithOwner = includeFromDelegations
+                ? Object.entries(delegations).flatMap(([delegateId, delegations]) => dataOwnerId === delegateId
+                    ? this.populateDelegatedTo(delegateId, delegations)
+                    : this.populateDelegatedTo(delegateId, delegations.filter((d) => d.owner === dataOwnerId)))
+                : (_a = delegations[dataOwnerId]) !== null && _a !== void 0 ? _a : [];
+            const res = [];
+            for (const delegation of delegationsWithOwner) {
+                if (yield tagsFilter((_b = delegation.tags) !== null && _b !== void 0 ? _b : [])) {
+                    const decrypted = yield this.tryDecryptDelegation(delegation, (k) => validateDecrypted(k));
+                    if (decrypted)
+                        res.push(decrypted);
+                }
+            }
+            return res;
+        });
+    }
+    // Ensures that the delegatedTo field of delegations has the appropriate values, else returns a copy of the delegations with the appropriate value.
+    populateDelegatedTo(delegateId, delegations) {
+        return delegations.map((d) => (d.delegatedTo === delegateId ? d : Object.assign(Object.assign({}, d), { delegatedTo: delegateId })));
+    }
+    extractedHierarchyFromDelegation(delegations, validateDecrypted, tagsFilter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return Promise.all((yield this.dataOwnerApi.getCurrentDataOwnerHierarchyIds()).map((ownerId) => __awaiter(this, void 0, void 0, function* () {
+                const extracted = this.deduplicate(yield this.extractFromDelegationsForDataOwner(ownerId, delegations, true, (k) => validateDecrypted(k), (t) => tagsFilter(t)));
+                return { ownerId, extracted };
+            })));
+        });
+    }
+    /**
+     * @internal This method should be private but is currently public/internal to allow to continue supporting legacy methods
+     */
+    extractMergedHierarchyFromDelegationAndOwner(delegations, dataOwnerId, validateDecrypted, tagsFilter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const hierarchy = dataOwnerId
+                ? yield this.dataOwnerApi.getCurrentDataOwnerHierarchyIdsFrom(dataOwnerId)
+                : yield this.dataOwnerApi.getCurrentDataOwnerHierarchyIds();
+            const extractedByOwner = yield Promise.all(
+            // Reverse is just to keep method behaviour as close as possible to the legacy behaviour, in case someone depended on the ordering.
+            [...hierarchy].reverse().map((ownerId) => this.extractFromDelegationsForDataOwner(ownerId, delegations, true, (k) => validateDecrypted(k), (t) => tagsFilter(t))));
+            return this.deduplicate(extractedByOwner.flatMap((x) => x));
+        });
+    }
+    tryDecryptDelegation(delegation, validateDecrypted) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const exchangeKeys = yield this.exchangeKeysManager.getDecryptionExchangeKeysFor(delegation.owner, delegation.delegatedTo);
+            for (const key of exchangeKeys) {
+                try {
+                    // Format of encrypted key for any delegation should be entityId:key, but with the merging of entities the entityId might not match the
+                    // current id. As a checksum we are only verifying that the decrypted bytes can be represented as a string with exactly one ':'.
+                    // Additionally, we also have a validator that is specific for each type of delegation content (encryption key, secret id, ...)
+                    const decrypted = (0, utils_1.ua2string)(yield this.primitives.AES.decrypt(key, (0, utils_1.hex2ua)(delegation.key)));
+                    const decryptedSplit = decrypted.split(':');
+                    if (decryptedSplit.length === 2) {
+                        const validation = validateDecrypted(decryptedSplit[1]);
+                        if (validation === true || (validation !== false && (yield validation)))
+                            return decryptedSplit[1];
+                    }
+                    else {
+                        console.warn("Error in the decrypted delegation: content should contain exactly 1 ':', the delegation is ignored.");
+                    }
+                }
+                catch (e) {
+                    // Do nothing: the delegation uses another exchange key owner->delegator
+                }
+            }
+        });
+    }
+    tryImportKey(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!/^[0-9A-Fa-f\-]+$/g.test(key))
+                return undefined;
+            try {
+                return yield this.primitives.AES.importKey('raw', (0, utils_1.hex2ua)(key.replace(/-/g, '')));
+            }
+            catch (e) {
+                console.warn(`Could not import key ${key} as an encryption key.`, e);
+                return undefined;
+            }
+        });
+    }
+    /**
+     * @internal this method is for internal use only and may be changed without notice.
+     */
+    importFirstValidKey(keys, entityId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.tryImportFirstValidKey(keys, entityId);
+            if (!res)
+                throw new Error(`Could not find any valid key for entity ${entityId}.`);
+            return res;
+        });
+    }
+    tryImportFirstValidKey(keys, entityId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const key of keys) {
+                const imported = yield this.tryImportKey(key);
+                if (imported)
+                    return { key: imported, raw: key };
+            }
+        });
+    }
+    /**
+     * @internal this method is for internal use only and may be changed without notice.
+     */
+    importAllValidKeys(keys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = [];
+            for (const key of keys) {
+                const imported = yield this.tryImportKey(key);
+                if (imported)
+                    res.push({ key: imported, raw: key });
+            }
+            return res;
+        });
+    }
+    validateEncryptionKey(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return !!(yield this.tryImportKey(key));
+        });
+    }
+    validateSecretId(key) {
+        return !!key;
+    }
+    validateOwningEntityId(key) {
+        return !!key;
+    }
+    createEncryptionKeyDelegation(entityId, delegateId, exchangeKey, encryptionKey, newTags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!(yield this.validateEncryptionKey(encryptionKey)))
+                throw new Error(`Invalid encryption key ${encryptionKey}`);
+            return this.createDelegation(entityId, delegateId, exchangeKey, encryptionKey, newTags);
+        });
+    }
+    createSecretIdDelegation(entityId, delegateId, exchangeKey, secretId, newTags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.validateSecretId(secretId))
+                throw new Error(`Invalid secret id ${secretId}`);
+            return this.createDelegation(entityId, delegateId, exchangeKey, secretId, newTags);
+        });
+    }
+    createOwningEntityIdDelegation(entityId, delegateId, exchangeKey, owningEntityId, newTags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.validateOwningEntityId(owningEntityId))
+                throw new Error(`Invalid owning id ${owningEntityId}`);
+            return this.createDelegation(entityId, delegateId, exchangeKey, owningEntityId, newTags);
+        });
+    }
+    createDelegation(entityId, delegateId, exchangeKey, content, newTags) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (entityId.includes(':'))
+                throw new Error("Ids for encrypted entities are not allowed to contain ':'");
+            if (content.includes(':'))
+                throw new Error("Content of delegations can not contain ':'");
+            return {
+                delegatedTo: delegateId,
+                owner: yield this.dataOwnerApi.getCurrentDataOwnerId(),
+                key: (0, utils_1.ua2hex)(yield this.primitives.AES.encrypt(exchangeKey, (0, utils_1.string2ua)(entityId + ':' + content))),
+                tags: newTags,
+            };
+        });
+    }
+    loadEncryptionKeysForDelegates(entity, delegates) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const { updatedDelegator, keysForDelegates } = yield delegates.reduce((acc, delegateId) => __awaiter(this, void 0, void 0, function* () {
+                var _b;
+                const awaitedAcc = yield acc;
+                const currUpdateResult = yield this.exchangeKeysManager.getOrCreateEncryptionExchangeKeysTo(delegateId);
+                return {
+                    updatedDelegator: (_b = currUpdateResult.updatedDelegator) !== null && _b !== void 0 ? _b : awaitedAcc.updatedDelegator,
+                    keysForDelegates: Object.assign(Object.assign({}, awaitedAcc.keysForDelegates), { [delegateId]: currUpdateResult.keys }),
+                };
+            }), Promise.resolve({
+                updatedDelegator: undefined,
+                keysForDelegates: {},
+            }));
+            const updatedEntity = entity.id === ((_a = updatedDelegator === null || updatedDelegator === void 0 ? void 0 : updatedDelegator.dataOwner) === null || _a === void 0 ? void 0 : _a.id)
+                ? Object.assign(Object.assign({}, entity), { rev: updatedDelegator.dataOwner.rev, hcPartyKeys: updatedDelegator.dataOwner.hcPartyKeys, aesExchangeKeys: updatedDelegator.dataOwner.aesExchangeKeys }) : entity;
+            return { updatedEntity, keysForDelegates };
+        });
+    }
+    createOrUpdateEntityDelegations(entity, delegateId, existingSecretIds, existingEncryptionKeys, existingOwningEntityIds, newSecretIds, newEncryptionKeys, newOwningEntityIds, newTags, keysForDelegates) {
+        var _a, _b, _c;
+        return __awaiter(this, void 0, void 0, function* () {
+            const entityCopy = _.cloneDeep(entity);
+            if (newSecretIds.length === 0 && newEncryptionKeys.length === 0 && newOwningEntityIds.length === 0)
+                return entityCopy;
+            const chosenKey = keysForDelegates[delegateId][0];
+            const updatedSecretIds = [
+                ...existingSecretIds,
+                ...(yield Promise.all(newSecretIds.map((x) => this.createSecretIdDelegation(entity.id, delegateId, chosenKey, x, newTags)))),
+            ];
+            const updatedEncryptionKeys = [
+                ...existingEncryptionKeys,
+                ...(yield Promise.all(newEncryptionKeys.map((x) => this.createEncryptionKeyDelegation(entity.id, delegateId, chosenKey, x, newTags)))),
+            ];
+            const updatedOwningEntityIds = [
+                ...existingOwningEntityIds,
+                ...(yield Promise.all(newOwningEntityIds.map((x) => this.createOwningEntityIdDelegation(entity.id, delegateId, chosenKey, x, newTags)))),
+            ];
+            if (updatedSecretIds.length > 0) {
+                entityCopy.delegations = Object.assign(Object.assign({}, ((_a = entity.delegations) !== null && _a !== void 0 ? _a : {})), { [delegateId]: updatedSecretIds });
+            }
+            if (updatedEncryptionKeys.length > 0) {
+                entityCopy.encryptionKeys = Object.assign(Object.assign({}, ((_b = entity.encryptionKeys) !== null && _b !== void 0 ? _b : {})), { [delegateId]: updatedEncryptionKeys });
+            }
+            if (updatedOwningEntityIds.length > 0) {
+                entityCopy.cryptedForeignKeys = Object.assign(Object.assign({}, ((_c = entity.cryptedForeignKeys) !== null && _c !== void 0 ? _c : {})), { [delegateId]: updatedOwningEntityIds });
+            }
+            return entityCopy;
+        });
+    }
+    /**
+     * De-duplicates all currently accessible delegations, by removing any delegations created by the current data owner which have duplicated content,
+     * and checks if any of the required entries are currently available to the delegate through the existing delegations.
+     * @param delegateId id of the delegate.
+     * @param allDelegations delegations of the entity.
+     * @param requiredEntries potentially new entries that the delegate needs to be able to access from the delegations.
+     * @param validateDecrypted validator for decrypted delegation content
+     * @return the deduplicated delegations
+     */
+    deduplicateDelegationsAndFilterRequiredEntries(delegateId, allDelegations, requiredEntries, validateDecrypted) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const selfId = yield this.dataOwnerApi.getCurrentDataOwnerId();
+            const delegationsToDelegate = (_a = allDelegations[delegateId]) !== null && _a !== void 0 ? _a : [];
+            const decryptedDelegations = yield Promise.all(delegationsToDelegate.map((d) => __awaiter(this, void 0, void 0, function* () {
+                return ({
+                    delegation: d,
+                    content: d.owner === selfId ? yield this.tryDecryptDelegation(d, (x) => validateDecrypted(x)) : undefined,
+                });
+            })));
+            const deduplicatedDelegations = [];
+            const deduplicatedContent = new Map();
+            decryptedDelegations.forEach(({ delegation, content }) => {
+                var _a, _b;
+                if (content === undefined) {
+                    // Keep all delegations we could not decrypt or from other data owners
+                    deduplicatedDelegations.push(delegation);
+                }
+                else {
+                    const deduplicatedTags = deduplicatedContent.get(content);
+                    if (!deduplicatedTags) {
+                        deduplicatedContent.set(content, [(_a = delegation.tags) !== null && _a !== void 0 ? _a : []]);
+                        deduplicatedDelegations.push(delegation);
+                    }
+                    else if (!deduplicatedTags.some((t) => { var _a; return (0, collection_utils_1.arrayEquals)(t, (_a = delegation.tags) !== null && _a !== void 0 ? _a : []); })) {
+                        deduplicatedTags.push((_b = delegation.tags) !== null && _b !== void 0 ? _b : []);
+                        deduplicatedDelegations.push(delegation);
+                    }
+                }
+            });
+            const delegationsFromDelegateToSelf = ((_b = allDelegations[selfId]) !== null && _b !== void 0 ? _b : []).filter((d) => d.owner === delegateId);
+            const decryptedDelegationsFromDelegate = new Set(yield Promise.all(delegationsFromDelegateToSelf.map((d) => this.tryDecryptDelegation(d, (x) => validateDecrypted(x)))).then((dels) => dels.flatMap((x) => (x ? [x] : []))));
+            return {
+                deduplicatedDelegations,
+                missingEntries: requiredEntries.filter((entry) => !(deduplicatedContent.has(entry) || decryptedDelegationsFromDelegate.has(entry))),
+            };
+        });
+    }
+    deduplicate(values) {
+        return [...new Set(values)];
+    }
+    throwDetailedExceptionForInvalidParameter(argName, argValue, methodName, methodArgs) {
+        if (argValue)
+            return;
+        let details = '\nMethod name: icc-crypto-x-api.' + methodName + '()\nArguments:';
+        if (methodArgs) {
+            try {
+                const argsArray = [...methodArgs];
+                _.each(argsArray, (arg, index) => (details += '\n[' + index + ']: ' + JSON.stringify(arg)));
+            }
+            catch (ex) {
+                details += '; a problem occured while logging arguments details: ' + ex;
+            }
+        }
+        throw new Error('### THIS SHOULD NOT HAPPEN: ' + argName + ' has an invalid value: ' + argValue + details);
+    }
+    checkEmptyEncryptionMetadata(entity) {
+        const existingMetadata = [];
+        if (entity.delegations && Object.keys(entity.delegations).length)
+            existingMetadata.push('delegations');
+        if (entity.cryptedForeignKeys && Object.keys(entity.cryptedForeignKeys).length)
+            existingMetadata.push('cryptedForeignKeys');
+        if (entity.encryptionKeys && Object.keys(entity.encryptionKeys).length)
+            existingMetadata.push('encryptionKeys');
+        if (entity.secretForeignKeys && entity.secretForeignKeys.length)
+            existingMetadata.push('secretForeignKeys');
+        if (existingMetadata.length > 0) {
+            throw new Error(`Entity should have no encryption metadata on initialisation, but the following fields already have some values: ${existingMetadata}\n` +
+                JSON.stringify(entity, undefined, 2));
+        }
+    }
+}
+exports.EntitiesEncryption = EntitiesEncryption;
+//# sourceMappingURL=EntitiesEncryption.js.map