@icure/api 7.1.14 → 8.0.0-RC.1

package/icc-x-api/crypto/ConfidentialEntities.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConfidentialEntities.js","sourceRoot":"","sources":["../../../icc-x-api/crypto/ConfidentialEntities.ts"],"names":[],"mappings":";;;;;;;;;;;;AAKA;;;;;;GAMG;AACH,MAAa,oBAAoB;IAC/B,YACmB,kBAAsC,EACtC,UAA4B,EAC5B,YAA8B;QAF9B,uBAAkB,GAAlB,kBAAkB,CAAoB;QACtC,eAAU,GAAV,UAAU,CAAkB;QAC5B,iBAAY,GAAZ,YAAY,CAAkB;IAC9C,CAAC;IAEJ;;;;;;;;OAQG;IACG,yCAAyC,CAA4B,MAAS;;YAClF,IAAI,MAAM,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC;gBAAE,OAAO,SAAS,CAAA;YAChE,MAAM,oBAAoB,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAA;YACzD,OAAO,MAAM,IAAI,CAAC,kBAAkB,CAAC,mCAAmC,CACtE,MAAM,EACN,MAAM,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,EAC/C,CAAC,oBAAoB,CAAC,EACtB,EAAE,EACF,EAAE,EACF,CAAC,cAAc,CAAC,CACjB,CAAA;QACH,CAAC;KAAA;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,MAAuB,EAAE,WAAoB;;YACzE,OAAO,IAAI,CAAC,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7E,CAAC;KAAA;IAED;;;;;;OAMG;IACG,+BAA+B,CAAC,MAAuB;;YAC3D,OAAO,CAAC,MAAM,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9D,CAAC;KAAA;IAED;;;;;;OAMG;IACG,wBAAwB,CAAC,MAAuB,EAAE,WAAoB;;YAC1E,iJAAiJ;YACjJ,MAAM,iBAAiB,GAAG,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC,CAAA;YAC1F,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,mCAAmC,CAAC,iBAAiB,CAAC,CAAA;YACzG,MAAM,kBAAkB,GAAG,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzG,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CACvC,CAAA;YACD,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,iBAAiB,CAAC,CAAA;YAExF,IAAI,CAAC,gBAAgB;gBAAE,OAAO,EAAE,CAAA;YAChC,OAAO,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,iBAAiB,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9I,CAAC;KAAA;IAED;;;;;OAKG;IACG,6BAA6B,CAAC,MAAuB;;YACzD,OAAO,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACxF,CAAC;KAAA;CACF;AAhFD,oDAgFC","sourcesContent":["import { EncryptedEntity } from '../../icc-api/model/models'\nimport { EntitiesEncryption } from './EntitiesEncryption'\nimport { CryptoPrimitives } from './CryptoPrimitives'\nimport { IccDataOwnerXApi } from '../icc-data-owner-x-api'\n\n/**\n * This class helps to create confidential medical data in systems where multiple hcps share data with each other using parent hcps: while normally\n * the hcps would share all data with other hcps part of the same \"family\" (e.g. an hospital) there are situations where the medical data is\n * confidential and should only be known by the doctor which created the data. In these situations it is also important that the secret foreign key\n * used in the confidential data is not known by other members of the hcp family, otherwise they may be able to draw some links between the medical\n * data and the patient.\n */\nexport class ConfidentialEntities {\n  constructor(\n    private readonly entitiesEncryption: EntitiesEncryption,\n    private readonly primitives: CryptoPrimitives,\n    private readonly dataOwnerApi: IccDataOwnerXApi\n  ) {}\n\n  /**\n   * Ensures that the current data owner has access to a confidential secret id for the provided entity: this is an id that is known to the data owner\n   * but is not known by any of his parents. If there is currently no confidential secret id for this entity the method returns a copy of the entity\n   * with a new confidential secret id for the current data owner (the entity in the database won't be updated), else this method returns undefined.\n   * New confidential secret ids will have an appropriate tag, but existing confidential secret ids may not necessarily have it.\n   * @param entity an entity which needs to have a confidential secret id for the current data owner\n   * @return undefined if the entity already had a confidential secret id for the current user, or the updated entity with the new confidential secret\n   * id.\n   */\n  async entityWithInitialisedConfidentialSecretId<T extends EncryptedEntity>(entity: T): Promise<T | undefined> {\n    if (await this.getConfidentialSecretId(entity)) return undefined\n    const confidentialSecretId = this.primitives.randomUuid()\n    return await this.entitiesEncryption.entityWithExtendedEncryptedMetadata(\n      entity,\n      await this.dataOwnerApi.getCurrentDataOwnerId(),\n      [confidentialSecretId],\n      [],\n      [],\n      ['confidential']\n    )\n  }\n\n  /**\n   * Get an existing confidential secret id of the provided entity for the provided data owner (current data owner by default). A confidential secret\n   * id is a secret id known by the data owner but not known by any of his parents: note however that children will know confidential secret ids.\n   * @param entity an entity for which you want to retrieve the confidential secret id.\n   * @param dataOwnerId (current data owner by default) a data owner for which you want to get a confidential secret id.\n   * @return the confidential secret id or undefined if there is no confidential secret id for the provided data owner.\n   */\n  async getConfidentialSecretId(entity: EncryptedEntity, dataOwnerId?: string): Promise<string | undefined> {\n    return this.getConfidentialSecretIds(entity, dataOwnerId).then((x) => x[0])\n  }\n\n  /**\n   * Gets a secret id known by the topmost parent of the current data owner hierarchy. If there is multiple secret ids shared with the topmost parent\n   * there is no guarantee on which one will be chosen.\n   * @param entity an entity.\n   * @return a secret id known by the topmost parent of the current data owner hierarchy, or undefined if there is no secret id currently available\n   * for the topmost parent.\n   */\n  async getAnySecretIdSharedWithParents(entity: EncryptedEntity): Promise<string | undefined> {\n    return (await this.getSecretIdsSharedWithParents(entity))[0]\n  }\n\n  /**\n   * Get all existing confidential secret ids of the provided entity for the provided data owner (current data owner by default). A confidential secret\n   * id is a secret id known by the data owner but not known by any of his parents: note however that children will know confidential secret ids.\n   * @param entity an entity for which you want to retrieve the confidential secret id.\n   * @param dataOwnerId (current data owner by default) a data owner for which you want to get a confidential secret id.\n   * @return the confidential secret ids for the data owner (may be empty).\n   */\n  async getConfidentialSecretIds(entity: EncryptedEntity, dataOwnerId?: string): Promise<string[]> {\n    // TODO throw exception if any parent key is not available? if we are missing even only one single parent key we can't be sure it is confidential\n    const chosenDataOwnerId = dataOwnerId ?? (await this.dataOwnerApi.getCurrentDataOwnerId())\n    const dataOwnerHierarchy = await this.dataOwnerApi.getCurrentDataOwnerHierarchyIdsFrom(chosenDataOwnerId)\n    const hierarchySecretIds = (await this.entitiesEncryption.secretIdsForHcpHierarchyOf(entity)).filter((x) =>\n      dataOwnerHierarchy.includes(x.ownerId)\n    )\n    const keysForDataOwner = hierarchySecretIds.find((x) => x.ownerId === chosenDataOwnerId)\n\n    if (!keysForDataOwner) return []\n    return keysForDataOwner.extracted.filter((k) => !hierarchySecretIds.some((x) => x.ownerId !== chosenDataOwnerId && x.extracted.includes(k)))\n  }\n\n  /**\n   * Gets all secret ids known by the topmost parent of the current data owner hierarchy (or all secret ids known by the current data owner if he is\n   * not part of any data owner hierarchy).\n   * @param entity an entity.\n   * @return all secret ids known by the topmost parent of the current data owner hierarchy, may be empty.\n   */\n  async getSecretIdsSharedWithParents(entity: EncryptedEntity): Promise<string[]> {\n    return (await this.entitiesEncryption.secretIdsForHcpHierarchyOf(entity))[0].extracted\n  }\n}\n"]}
+{"version":3,"file":"ConfidentialEntities.js","sourceRoot":"","sources":["../../../icc-x-api/crypto/ConfidentialEntities.ts"],"names":[],"mappings":";;;;;;;;;;;;AAKA,qEAAiE;AACjE,wFAAoF;AACpF,IAAO,uBAAuB,GAAG,uCAAkB,CAAC,uBAAuB,CAAA;AAI3E;;;;;;;GAOG;AACH,MAAa,oBAAoB;IAC/B,YACmB,kBAAqC,EACrC,UAA4B,EAC5B,YAA8B;QAF9B,uBAAkB,GAAlB,kBAAkB,CAAmB;QACrC,eAAU,GAAV,UAAU,CAAkB;QAC5B,iBAAY,GAAZ,YAAY,CAAkB;IAC9C,CAAC;IAEJ;;;;;;;;;;OAUG;IACG,8BAA8B,CAClC,MAAS,EACT,UAAwC,EACxC,0BAEyC;;YAEzC,IAAI,MAAM,IAAI,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;gBAAE,OAAO,SAAS,CAAA;YACtF,MAAM,oBAAoB,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAA;YACzD,OAAO,CACL,MAAM,IAAI,CAAC,kBAAkB,CAAC,0CAA0C,CACtE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAC5B,KAAK,EACL;gBACE,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC,EAAE;oBACjD,mBAAmB,EAAE,+CAAsB,CAAC,KAAK;oBACjD,oBAAoB,EAAE,+CAAsB,CAAC,KAAK;oBAClD,cAAc,EAAE,CAAC,oBAAoB,CAAC;oBACtC,oBAAoB,EAAE,uBAAuB,CAAC,SAAS;iBACxD;aACF,EACD,CAAC,OAAO,EAAE,EAAE,CAAC,0BAA0B,CAAC,OAAO,CAAC,CACjD,CACF,CAAC,oBAAoB,CAAA;QACxB,CAAC;KAAA;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,MAA+B,EAAE,WAAoB;;YACjF,OAAO,IAAI,CAAC,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7E,CAAC;KAAA;IAED;;;;;;OAMG;IACG,wBAAwB,CAAC,MAA+B,EAAE,WAAoB;;YAClF,iJAAiJ;YACjJ,MAAM,iBAAiB,GAAG,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC,CAAA;YAC1F,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,mCAAmC,CAAC,iBAAiB,CAAC,CAAA;YACzG,MAAM,kBAAkB,GAAG,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzG,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CACvC,CAAA;YACD,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,iBAAiB,CAAC,CAAA;YAExF,IAAI,CAAC,gBAAgB;gBAAE,OAAO,EAAE,CAAA;YAChC,OAAO,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,iBAAiB,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9I,CAAC;KAAA;IAED;;;;;;OAMG;IACG,+BAA+B,CAAC,MAA+B;;YACnE,OAAO,CAAC,MAAM,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9D,CAAC;KAAA;IAED;;;;;OAKG;IACG,6BAA6B,CAAC,MAA+B;;YACjE,OAAO,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACxF,CAAC;KAAA;CACF;AA/FD,oDA+FC","sourcesContent":["import { EncryptedEntity } from '../../icc-api/model/models'\nimport { ExtendedApisUtils } from './ExtendedApisUtils'\nimport { CryptoPrimitives } from './CryptoPrimitives'\nimport { IccDataOwnerXApi } from '../icc-data-owner-x-api'\nimport { EncryptedEntityWithType, EntityWithDelegationTypeName } from '../utils/EntityWithDelegationTypeName'\nimport { ShareMetadataBehaviour } from './ShareMetadataBehaviour'\nimport { EntityShareRequest } from '../../icc-api/model/requests/EntityShareRequest'\nimport RequestedPermissionEnum = EntityShareRequest.RequestedPermissionEnum\nimport { EntityShareOrMetadataUpdateRequest } from '../../icc-api/model/requests/EntityShareOrMetadataUpdateRequest'\nimport { EntityBulkShareResult } from '../../icc-api/model/requests/EntityBulkShareResult'\n\n/**\n * @internal this class is intended for internal use only and may be changed without notice.\n * This class helps to create confidential medical data in systems where multiple hcps share data with each other using parent hcps: while normally\n * the hcps would share all data with other hcps part of the same \"family\" (e.g. an hospital) there are situations where the medical data is\n * confidential and should only be known by the doctor which created the data. In these situations it is also important that the secret foreign key\n * used in the confidential data is not known by other members of the hcp family, otherwise they may be able to draw some links between the medical\n * data and the patient.\n */\nexport class ConfidentialEntities {\n  constructor(\n    private readonly entitiesEncryption: ExtendedApisUtils,\n    private readonly primitives: CryptoPrimitives,\n    private readonly dataOwnerApi: IccDataOwnerXApi\n  ) {}\n\n  /**\n   * Ensures that the current data owner has access to a confidential secret id for the provided entity: this is an id that is known to the data owner\n   * but is not known by any of his parents. If there is currently no confidential secret id for this entity the method returns a copy of the entity\n   * with a new confidential secret id for the current data owner (the entity in the database won't be updated), else this method returns undefined.\n   * New confidential secret ids will have an appropriate tag, but existing confidential secret ids may not necessarily have it.\n   * @param entity an entity which needs to have a confidential secret id for the current data owner\n   * @param entityType the type of the entity\n   * @param doRequestBulkShareOrUpdate perform the request to share or update an entity encrypted metadata on the cloud API (and save to DB).\n   * @return undefined if the entity already had a confidential secret id for the current user, or the updated AND SAVED entity with the new\n   * confidential secret id.\n   */\n  async initialiseConfidentialSecretId<T extends EncryptedEntity>(\n    entity: T,\n    entityType: EntityWithDelegationTypeName,\n    doRequestBulkShareOrUpdate: (request: {\n      [entityId: string]: { [requestId: string]: EntityShareOrMetadataUpdateRequest }\n    }) => Promise<EntityBulkShareResult<T>[]>\n  ): Promise<T | undefined> {\n    if (await this.getConfidentialSecretId({ entity, type: entityType })) return undefined\n    const confidentialSecretId = this.primitives.randomUuid()\n    return (\n      await this.entitiesEncryption.simpleShareOrUpdateEncryptedEntityMetadata(\n        { entity, type: entityType },\n        false,\n        {\n          [await this.dataOwnerApi.getCurrentDataOwnerId()]: {\n            shareEncryptionKeys: ShareMetadataBehaviour.NEVER,\n            shareOwningEntityIds: ShareMetadataBehaviour.NEVER,\n            shareSecretIds: [confidentialSecretId],\n            requestedPermissions: RequestedPermissionEnum.MAX_WRITE,\n          },\n        },\n        (request) => doRequestBulkShareOrUpdate(request)\n      )\n    ).updatedEntityOrThrow\n  }\n\n  /**\n   * Get an existing confidential secret id of the provided entity for the provided data owner (current data owner by default). A confidential secret\n   * id is a secret id known by the data owner but not known by any of his parents: note however that children will know confidential secret ids.\n   * @param entity an entity for which you want to retrieve the confidential secret id.\n   * @param dataOwnerId (current data owner by default) a data owner for which you want to get a confidential secret id.\n   * @return the confidential secret id or undefined if there is no confidential secret id for the provided data owner.\n   */\n  async getConfidentialSecretId(entity: EncryptedEntityWithType, dataOwnerId?: string): Promise<string | undefined> {\n    return this.getConfidentialSecretIds(entity, dataOwnerId).then((x) => x[0])\n  }\n\n  /**\n   * Get all existing confidential secret ids of the provided entity for the provided data owner (current data owner by default). A confidential secret\n   * id is a secret id known by the data owner but not known by any of his parents: note however that children will know confidential secret ids.\n   * @param entity an entity for which you want to retrieve the confidential secret id.\n   * @param dataOwnerId (current data owner by default) a data owner for which you want to get a confidential secret id.\n   * @return the confidential secret ids for the data owner (may be empty).\n   */\n  async getConfidentialSecretIds(entity: EncryptedEntityWithType, dataOwnerId?: string): Promise<string[]> {\n    // TODO throw exception if any parent key is not available? if we are missing even only one single parent key we can't be sure it is confidential\n    const chosenDataOwnerId = dataOwnerId ?? (await this.dataOwnerApi.getCurrentDataOwnerId())\n    const dataOwnerHierarchy = await this.dataOwnerApi.getCurrentDataOwnerHierarchyIdsFrom(chosenDataOwnerId)\n    const hierarchySecretIds = (await this.entitiesEncryption.secretIdsForHcpHierarchyOf(entity)).filter((x) =>\n      dataOwnerHierarchy.includes(x.ownerId)\n    )\n    const keysForDataOwner = hierarchySecretIds.find((x) => x.ownerId === chosenDataOwnerId)\n\n    if (!keysForDataOwner) return []\n    return keysForDataOwner.extracted.filter((k) => !hierarchySecretIds.some((x) => x.ownerId !== chosenDataOwnerId && x.extracted.includes(k)))\n  }\n\n  /**\n   * Gets a secret id known by the topmost parent of the current data owner hierarchy. If there is multiple secret ids shared with the topmost parent\n   * there is no guarantee on which one will be chosen.\n   * @param entity an entity.\n   * @return a secret id known by the topmost parent of the current data owner hierarchy, or undefined if there is no secret id currently available\n   * for the topmost parent.\n   */\n  async getAnySecretIdSharedWithParents(entity: EncryptedEntityWithType): Promise<string | undefined> {\n    return (await this.getSecretIdsSharedWithParents(entity))[0]\n  }\n\n  /**\n   * Gets all secret ids known by the topmost parent of the current data owner hierarchy (or all secret ids known by the current data owner if he is\n   * not part of any data owner hierarchy).\n   * @param entity an entity.\n   * @return all secret ids known by the topmost parent of the current data owner hierarchy, may be empty.\n   */\n  async getSecretIdsSharedWithParents(entity: EncryptedEntityWithType): Promise<string[]> {\n    return (await this.entitiesEncryption.secretIdsForHcpHierarchyOf(entity))[0].extracted\n  }\n}\n"]}

package/icc-x-api/crypto/CryptoStrategies.d.ts

@@ -1,7 +1,7 @@
 import { KeyPair } from './RSA';
 import { CryptoPrimitives } from './CryptoPrimitives';
-import { DataOwnerWithType } from '../../icc-api/model/DataOwnerWithType';
 import { CryptoActorStubWithType } from '../../icc-api/model/CryptoActorStub';
+import { DataOwnerWithType } from '../../icc-api/model/DataOwnerWithType';
 /**
  * Allows to customise the behaviour of the crypto api to better suit your needs.
  *
@@ -80,4 +80,11 @@ export interface CryptoStrategies {
      * @return all verified public keys, in spki hex-encoded format.
      */
     verifyDelegatePublicKeys(delegate: CryptoActorStubWithType, publicKeys: string[], cryptoPrimitives: CryptoPrimitives): Promise<string[]>;
+    /**
+     * Specifies if a data owner requires anonymous delegations, i.e. his id should not appear unencrypted in new secure delegations. This should always
+     * be the case for patient data owners.
+     * @param dataOwner a data owner.
+     * @return true if the delegations for the provided data owner should be anonymous.
+     */
+    dataOwnerRequiresAnonymousDelegation(dataOwner: CryptoActorStubWithType): boolean;
 }

package/icc-x-api/crypto/CryptoStrategies.js.map

@@ -1 +1 @@
-{"version":3,"file":"CryptoStrategies.js","sourceRoot":"","sources":["../../../icc-x-api/crypto/CryptoStrategies.ts"],"names":[],"mappings":"","sourcesContent":["import { KeyPair } from './RSA'\nimport { CryptoPrimitives } from './CryptoPrimitives'\nimport { DataOwnerWithType } from '../../icc-api/model/DataOwnerWithType'\nimport { CryptoActorStubWithType } from '../../icc-api/model/CryptoActorStub'\n\n/**\n * Allows to customise the behaviour of the crypto api to better suit your needs.\n *\n * An important task which should be done in these crypto strategies is public key verification: in general there is no guarantee that the public keys\n * stored in the iCure database are authentic, i.e. created by the data owner they are associated to. This is because the database admins or a\n * malicious attacker may have added his own public keys to the data owner's public keys.\n * Sharing any kind of data using unverified public keys could potentially cause a data leak: this is why when creating new exchange keys or when\n * creating recovery data only verified keys will be considered. For decrypting existing data instead unverified keys will be used without issues.\n */\nexport interface CryptoStrategies {\n  /**\n   * Method called during initialisation of the crypto API to validate keys recovered through iCure's recovery methods and/or to allow recovery of\n   * missing keys using means external to iCure.\n   * On startup the iCure sdk will try to load all keys for the current data owner and its parent hierarchy: if the sdk can't find some of the keys\n   * for any of the data owners (according to the public keys for the data owner in the iCure server) and/or the sdk could recover some private keys\n   * but can't verify the authenticity of the key pairs this method will be called.\n   * The recovered and verified keys will automatically be cached using the current api {@link KeyStorageFacade} and {@link StorageFacade}\n   *\n   * The input is an array containing an object for each data owner part of the current data owner hierarchy. The objects are ordered from the data\n   * for the topmost parent of the current data owner hierarchy (first element) to the data for the current data owner (last element). Each object\n   * contains:\n   * - dataOwner: the data owner entity that this object refers to\n   * - unknownKeys: all public keys (in hex-encoded spki format) of `dataOwner` for which the authenticity status (verified or unverified) is unknown\n   *   (no result was cached from a previous api instantiation and the key was not generated on the current device).\n   * - unavailableKeys: all public keys (in hex-encoded spki format) of `dataOwner` for which the sdk could not recover a private key. May overlap\n   *   (partially or completely) with `unknownKeys`.\n   *\n   * The returned value must be an object associating to each data owner id an object with:\n   * - `recoveredKeys`: all recovered keys (will be automatically considered as verified), by fingerprint.\n   * - `keyAuthenticity`: an object associating to each public key fingerprint its authenticity. Note that if any of the keys from `unknownKeys` is\n   *   completely missing from this object the key will be considered as unverified in this api instance (same as if associated to false), but this\n   *   value won't be cached (will be again part of `unknownKeys` in future instances.\n   * @param keysData all information on unknown and unavailable keys for each data owner part of the current data owner hierarchy.\n   * @param cryptoPrimitives cryptographic primitives you can use to support the process.\n   * @return all recovered keys and key authenticity information, by data owner.\n   */\n  recoverAndVerifySelfHierarchyKeys(\n    keysData: {\n      dataOwner: DataOwnerWithType\n      unknownKeys: string[]\n      unavailableKeys: string[]\n    }[],\n    cryptoPrimitives: CryptoPrimitives\n  ): Promise<{\n    [dataOwnerId: string]: {\n      recoveredKeys: { [keyPairFingerprint: string]: KeyPair<CryptoKey> }\n      keyAuthenticity: { [keyPairFingerprint: string]: boolean }\n    }\n  }>\n\n  /**\n   * The correct initialisation of the crypto API requires that at least 1 verified (or device) key pair is available for each data owner part of the\n   * current data owner hierarchy. If no verified key is available for any of the data owner parents the api initialisation will automatically fail,\n   * however if there is no verified key for the current data owner you can instead create a new crypto key.\n   * @param self the current data owner.\n   * @param cryptoPrimitives cryptographic primitives you can use to support the process.\n   * @return depending on which values you return the api initialisation will proceed differently:\n   * - If this method returns true a new key will be automatically generated by the sdk.\n   * - If this method returns a key pair the crypto api loads the key pair and considers it as a device key.\n   * - If this method returns false the initialisation will fail with a predefined error.\n   * - If this method throws an error the initialisation will propagate the error.\n   */\n  generateNewKeyForDataOwner(self: DataOwnerWithType, cryptoPrimitives: CryptoPrimitives): Promise<KeyPair<CryptoKey> | boolean>\n\n  /**\n   * Verifies if the public keys of a data owner which will be the delegate of a new exchange key do actually belong to the person the data owner\n   * represents. This method is not called when the delegate would be the current data owner for the api.\n   *\n   * The user will have to obtain the verified public keys of the delegate from outside iCure, for example by email with another hcp, by checking the\n   * personal website of the other user, or by scanning verification qr codes at the doctor office...\n   *\n   * As long as one of the public keys is verified the creation of a new exchange key will succeed. If no public key is verified the operation will\n   * fail.\n   * @param delegate the potential data owner delegate.\n   * @param publicKeys public keys requiring verification, in spki hex-encoded format.\n   * @param cryptoPrimitives cryptographic primitives you can use to support the process.\n   * @return all verified public keys, in spki hex-encoded format.\n   */\n  verifyDelegatePublicKeys(delegate: CryptoActorStubWithType, publicKeys: string[], cryptoPrimitives: CryptoPrimitives): Promise<string[]>\n}\n"]}
+{"version":3,"file":"CryptoStrategies.js","sourceRoot":"","sources":["../../../icc-x-api/crypto/CryptoStrategies.ts"],"names":[],"mappings":"","sourcesContent":["import { KeyPair } from './RSA'\nimport { CryptoPrimitives } from './CryptoPrimitives'\nimport { CryptoActorStubWithType } from '../../icc-api/model/CryptoActorStub'\nimport { DataOwnerWithType } from '../../icc-api/model/DataOwnerWithType'\n\n/**\n * Allows to customise the behaviour of the crypto api to better suit your needs.\n *\n * An important task which should be done in these crypto strategies is public key verification: in general there is no guarantee that the public keys\n * stored in the iCure database are authentic, i.e. created by the data owner they are associated to. This is because the database admins or a\n * malicious attacker may have added his own public keys to the data owner's public keys.\n * Sharing any kind of data using unverified public keys could potentially cause a data leak: this is why when creating new exchange keys or when\n * creating recovery data only verified keys will be considered. For decrypting existing data instead unverified keys will be used without issues.\n */\nexport interface CryptoStrategies {\n  /**\n   * Method called during initialisation of the crypto API to validate keys recovered through iCure's recovery methods and/or to allow recovery of\n   * missing keys using means external to iCure.\n   * On startup the iCure sdk will try to load all keys for the current data owner and its parent hierarchy: if the sdk can't find some of the keys\n   * for any of the data owners (according to the public keys for the data owner in the iCure server) and/or the sdk could recover some private keys\n   * but can't verify the authenticity of the key pairs this method will be called.\n   * The recovered and verified keys will automatically be cached using the current api {@link KeyStorageFacade} and {@link StorageFacade}\n   *\n   * The input is an array containing an object for each data owner part of the current data owner hierarchy. The objects are ordered from the data\n   * for the topmost parent of the current data owner hierarchy (first element) to the data for the current data owner (last element). Each object\n   * contains:\n   * - dataOwner: the data owner entity that this object refers to\n   * - unknownKeys: all public keys (in hex-encoded spki format) of `dataOwner` for which the authenticity status (verified or unverified) is unknown\n   *   (no result was cached from a previous api instantiation and the key was not generated on the current device).\n   * - unavailableKeys: all public keys (in hex-encoded spki format) of `dataOwner` for which the sdk could not recover a private key. May overlap\n   *   (partially or completely) with `unknownKeys`.\n   *\n   * The returned value must be an object associating to each data owner id an object with:\n   * - `recoveredKeys`: all recovered keys (will be automatically considered as verified), by fingerprint.\n   * - `keyAuthenticity`: an object associating to each public key fingerprint its authenticity. Note that if any of the keys from `unknownKeys` is\n   *   completely missing from this object the key will be considered as unverified in this api instance (same as if associated to false), but this\n   *   value won't be cached (will be again part of `unknownKeys` in future instances.\n   * @param keysData all information on unknown and unavailable keys for each data owner part of the current data owner hierarchy.\n   * @param cryptoPrimitives cryptographic primitives you can use to support the process.\n   * @return all recovered keys and key authenticity information, by data owner.\n   */\n  recoverAndVerifySelfHierarchyKeys(\n    keysData: {\n      dataOwner: DataOwnerWithType\n      unknownKeys: string[]\n      unavailableKeys: string[]\n    }[],\n    cryptoPrimitives: CryptoPrimitives\n  ): Promise<{\n    [dataOwnerId: string]: {\n      recoveredKeys: { [keyPairFingerprint: string]: KeyPair<CryptoKey> }\n      keyAuthenticity: { [keyPairFingerprint: string]: boolean }\n    }\n  }>\n\n  /**\n   * The correct initialisation of the crypto API requires that at least 1 verified (or device) key pair is available for each data owner part of the\n   * current data owner hierarchy. If no verified key is available for any of the data owner parents the api initialisation will automatically fail,\n   * however if there is no verified key for the current data owner you can instead create a new crypto key.\n   * @param self the current data owner.\n   * @param cryptoPrimitives cryptographic primitives you can use to support the process.\n   * @return depending on which values you return the api initialisation will proceed differently:\n   * - If this method returns true a new key will be automatically generated by the sdk.\n   * - If this method returns a key pair the crypto api loads the key pair and considers it as a device key.\n   * - If this method returns false the initialisation will fail with a predefined error.\n   * - If this method throws an error the initialisation will propagate the error.\n   */\n  generateNewKeyForDataOwner(self: DataOwnerWithType, cryptoPrimitives: CryptoPrimitives): Promise<KeyPair<CryptoKey> | boolean>\n\n  /**\n   * Verifies if the public keys of a data owner which will be the delegate of a new exchange key do actually belong to the person the data owner\n   * represents. This method is not called when the delegate would be the current data owner for the api.\n   *\n   * The user will have to obtain the verified public keys of the delegate from outside iCure, for example by email with another hcp, by checking the\n   * personal website of the other user, or by scanning verification qr codes at the doctor office...\n   *\n   * As long as one of the public keys is verified the creation of a new exchange key will succeed. If no public key is verified the operation will\n   * fail.\n   * @param delegate the potential data owner delegate.\n   * @param publicKeys public keys requiring verification, in spki hex-encoded format.\n   * @param cryptoPrimitives cryptographic primitives you can use to support the process.\n   * @return all verified public keys, in spki hex-encoded format.\n   */\n  verifyDelegatePublicKeys(delegate: CryptoActorStubWithType, publicKeys: string[], cryptoPrimitives: CryptoPrimitives): Promise<string[]>\n\n  /**\n   * Specifies if a data owner requires anonymous delegations, i.e. his id should not appear unencrypted in new secure delegations. This should always\n   * be the case for patient data owners.\n   * @param dataOwner a data owner.\n   * @return true if the delegations for the provided data owner should be anonymous.\n   */\n  dataOwnerRequiresAnonymousDelegation(dataOwner: CryptoActorStubWithType): boolean\n}\n"]}

package/icc-x-api/crypto/ExchangeDataManager.d.ts

@@ -0,0 +1,95 @@
+import { ExchangeData } from '../../icc-api/model/ExchangeData';
+import { IccDataOwnerXApi } from '../icc-data-owner-x-api';
+import { BaseExchangeDataManager } from './BaseExchangeDataManager';
+import { UserEncryptionKeysManager } from './UserEncryptionKeysManager';
+import { UserSignatureKeysManager } from './UserSignatureKeysManager';
+import { AccessControlSecretUtils } from './AccessControlSecretUtils';
+import { CryptoStrategies } from './CryptoStrategies';
+import { CryptoPrimitives } from './CryptoPrimitives';
+import { EntityWithDelegationTypeName } from '../utils/EntityWithDelegationTypeName';
+export type ExchangeDataManagerOptionalParameters = {
+    lruCacheSize?: number;
+};
+/**
+ * @internal this function is for internal use only and may be changed without notice.
+ * Initialises and returns the exchange data manager which is most appropriate for the current data owner.
+ */
+export declare function initialiseExchangeDataManagerForCurrentDataOwner(base: BaseExchangeDataManager, encryptionKeys: UserEncryptionKeysManager, signatureKeys: UserSignatureKeysManager, accessControlSecret: AccessControlSecretUtils, cryptoStrategies: CryptoStrategies, dataOwnerApi: IccDataOwnerXApi, primitives: CryptoPrimitives, useParentKeys: boolean, optionalParameters?: ExchangeDataManagerOptionalParameters): Promise<ExchangeDataManager>;
+/**
+ * @internal this class is intended for internal use only and may be changed without notice.
+ * Exchange data manager which automatically handles decryption and cache
+ */
+export interface ExchangeDataManager {
+    readonly base: BaseExchangeDataManager;
+    /**
+     * Updates all exchange data between the current data owner and another data owner to allow the other data owner to access existing exchange data
+     * using a new public key. Note that this will make existing exchange keys from the other data owner to the current data owner unverified, therefore
+     * invalid for encryption.
+     * @param otherDataOwner the other data owner.
+     * @param newDataOwnerPublicKey a new public key of the other data owner.
+     */
+    giveAccessBackTo(otherDataOwner: string, newDataOwnerPublicKey: string): Promise<void>;
+    /**
+     * Gets any existing and verified exchange data from the current data owner to the provided delegate or creates new data if no verified data is
+     * available, then caches it. The {@link entityType} and {@link entitySecretForeignKeys} will be used for the secure-delegation-hash-based cache
+     * of the exchange data and not for actually creating the exchange data.
+     * @param delegateId the id of the delegate.
+     * @param entityType type of the entity for which you want to create new metadata.
+     * @param entitySecretForeignKeys the secret foreign keys of the entity which you want to create new metadata.
+     * @return the access control secret and key of the data to use for encryption.
+     */
+    getOrCreateEncryptionDataTo(delegateId: string, entityType: EntityWithDelegationTypeName | undefined, entitySecretForeignKeys: string[] | undefined): Promise<{
+        exchangeData: ExchangeData;
+        accessControlSecret: string;
+        exchangeKey: CryptoKey;
+    }>;
+    /**
+     * Retrieve the cached decrypted exchange data key associated with any of the provided hashes/entry keys of secure delegations. Depending on the
+     * implementation the {@link entityType} and {@link entitySecretForeignKeys} may be used to improve the secure-delegation-hash-based cache of
+     * exchange data from the other available exchange data caches.
+     * @param hashes hashes of access control secrets for a specific entity, as they appear in the key of secure delegation entries
+     * @param entityType type of the entity containing the metadata for which you are retrieving the encryption key.
+     * @param entitySecretForeignKeys the secret foreign keys of the entity containing the metadata for which you are retrieving the encryption key.
+     * @return the exchange data and decrypted key associated to that hash if cached
+     */
+    getCachedDecryptionDataKeyByAccessControlHash(hashes: string[], entityType: EntityWithDelegationTypeName, entitySecretForeignKeys: string[]): Promise<{
+        [hash: string]: {
+            exchangeData: ExchangeData;
+            exchangeKey: CryptoKey;
+        };
+    }>;
+    /**
+     * Retrieves the exchange data with the provided id (from the cache if available or from the server otherwise if allowed by
+     * {@link retrieveIfNotCached}) and attempts to decrypt it, then caches the result. The {@link entityType} and {@link entitySecretForeignKeys} will
+     * be used for the secure-delegation-hash-based cache of the exchange data.
+     * @param id id of the exchange data
+     * @param entityType type of the entity containing the metadata for which you are retrieving the encryption key.
+     * @param entitySecretForeignKeys the secret foreign keys of the entity containing the metadata for which you are retrieving the encryption key.
+     * @param retrieveIfNotCached if false and there is no cached exchange data with the provided id the method returns undefined, else the method will
+     * attempt to load the exchange data from the server.
+     * @return undefined if the exchange data is not cached and {@link retrieveIfNotCached} is false. Else an object containing:
+     * - exchangeData: the exchange data with the provided id
+     * - exchangeKey: the exchange key corresponding to the provided exchange data if it could be decrypted, else undefined
+     * @throws if no exchange data with the given id is cached and {@link retrieveIfNotCached} is true and the data could not be found in the server
+     * either.
+     */
+    getDecryptionDataKeyById(id: string, entityType: EntityWithDelegationTypeName | undefined, entitySecretForeignKeys: string[] | undefined, retrieveIfNotCached: boolean): Promise<{
+        exchangeKey: CryptoKey | undefined;
+        exchangeData: ExchangeData;
+    } | undefined>;
+    /**
+     * Clears the cache or fully repopulates the cache if the current data owner can retrieve all of his exchange data according to the crypto
+     * strategies.
+     */
+    clearOrRepopulateCache(): Promise<void>;
+    /**
+     * If the current data owner requires anonymous delegations this returns the base64 representation of the concatenation of all available access
+     * control keys for the current data owner.
+     */
+    getAccessControlKeysValue(entityType: EntityWithDelegationTypeName): Promise<string | undefined>;
+    /**
+     * If the current data owner requires anonymous delegations this returns the access control keys which may be used in secure delegations for the
+     * data owner, which can be used to search for data.
+     */
+    getAllDelegationKeys(entityType: EntityWithDelegationTypeName): Promise<string[] | undefined>;
+}