@icure/api 7.1.4 → 7.1.6

package/icc-x-api/crypto/ConfidentialEntities.ts

@@ -0,0 +1,93 @@
+import { EncryptedEntity } from '../../icc-api/model/models'
+import { EntitiesEncryption } from './EntitiesEncryption'
+import { CryptoPrimitives } from './CryptoPrimitives'
+import { IccDataOwnerXApi } from '../icc-data-owner-x-api'
+
+/**
+ * This class helps to create confidential medical data in systems where multiple hcps share data with each other using parent hcps: while normally
+ * 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
+ * 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
+ * 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
+ * data and the patient.
+ */
+export class ConfidentialEntities {
+  constructor(
+    private readonly entitiesEncryption: EntitiesEncryption,
+    private readonly primitives: CryptoPrimitives,
+    private readonly dataOwnerApi: IccDataOwnerXApi
+  ) {}
+
+  /**
+   * 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
+   * 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
+   * 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.
+   * New confidential secret ids will have an appropriate tag, but existing confidential secret ids may not necessarily have it.
+   * @param entity an entity which needs to have a confidential secret id for the current data owner
+   * @return undefined if the entity already had a confidential secret id for the current user, or the updated entity with the new confidential secret
+   * id.
+   */
+  async entityWithInitialisedConfidentialSecretId<T extends EncryptedEntity>(entity: T): Promise<T | undefined> {
+    if (await this.getConfidentialSecretId(entity)) return undefined
+    const confidentialSecretId = this.primitives.randomUuid()
+    return await this.entitiesEncryption.entityWithExtendedEncryptedMetadata(
+      entity,
+      await this.dataOwnerApi.getCurrentDataOwnerId(),
+      [confidentialSecretId],
+      [],
+      [],
+      ['confidential']
+    )
+  }
+
+  /**
+   * Get an existing confidential secret id of the provided entity for the provided data owner (current data owner by default). A confidential secret
+   * 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.
+   * @param entity an entity for which you want to retrieve the confidential secret id.
+   * @param dataOwnerId (current data owner by default) a data owner for which you want to get a confidential secret id.
+   * @return the confidential secret id or undefined if there is no confidential secret id for the provided data owner.
+   */
+  async getConfidentialSecretId(entity: EncryptedEntity, dataOwnerId?: string): Promise<string | undefined> {
+    return this.getConfidentialSecretIds(entity, dataOwnerId).then((x) => x[0])
+  }
+
+  /**
+   * 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
+   * there is no guarantee on which one will be chosen.
+   * @param entity an entity.
+   * @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
+   * for the topmost parent.
+   */
+  async getAnySecretIdSharedWithParents(entity: EncryptedEntity): Promise<string | undefined> {
+    return (await this.getSecretIdsSharedWithParents(entity))[0]
+  }
+
+  /**
+   * Get all existing confidential secret ids of the provided entity for the provided data owner (current data owner by default). A confidential secret
+   * 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.
+   * @param entity an entity for which you want to retrieve the confidential secret id.
+   * @param dataOwnerId (current data owner by default) a data owner for which you want to get a confidential secret id.
+   * @return the confidential secret ids for the data owner (may be empty).
+   */
+  async getConfidentialSecretIds(entity: EncryptedEntity, dataOwnerId?: string): Promise<string[]> {
+    // 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
+    const chosenDataOwnerId = dataOwnerId ?? (await this.dataOwnerApi.getCurrentDataOwnerId())
+    const dataOwnerHierarchy = await this.dataOwnerApi.getCurrentDataOwnerHierarchyIdsFrom(chosenDataOwnerId)
+    const hierarchySecretIds = (await this.entitiesEncryption.secretIdsForHcpHierarchyOf(entity)).filter((x) =>
+      dataOwnerHierarchy.includes(x.ownerId)
+    )
+    const keysForDataOwner = hierarchySecretIds.find((x) => x.ownerId === chosenDataOwnerId)
+
+    if (!keysForDataOwner) return []
+    return keysForDataOwner.extracted.filter((k) => !hierarchySecretIds.some((x) => x.ownerId !== chosenDataOwnerId && x.extracted.includes(k)))
+  }
+
+  /**
+   * 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
+   * not part of any data owner hierarchy).
+   * @param entity an entity.
+   * @return all secret ids known by the topmost parent of the current data owner hierarchy, may be empty.
+   */
+  async getSecretIdsSharedWithParents(entity: EncryptedEntity): Promise<string[]> {
+    return (await this.entitiesEncryption.secretIdsForHcpHierarchyOf(entity))[0].extracted
+  }
+}

package/icc-x-api/crypto/CryptoPrimitives.ts

@@ -0,0 +1,65 @@
+import { RSAUtils } from './RSA'
+import { AESUtils } from './AES'
+import { ShamirClass } from './shamir'
+
+/**
+ * Gives access to cryptographic primitives.
+ */
+export class CryptoPrimitives {
+  private readonly _rsa: RSAUtils
+  private readonly _aes: AESUtils
+  private readonly _shamir: ShamirClass
+  private readonly _crypto: Crypto
+
+  get crypto(): Crypto {
+    return this._crypto
+  }
+
+  get shamir(): ShamirClass {
+    return this._shamir
+  }
+
+  get RSA(): RSAUtils {
+    return this._rsa
+  }
+
+  get AES(): AESUtils {
+    return this._aes
+  }
+
+  constructor(crypto: Crypto = typeof window !== 'undefined' ? window.crypto : typeof self !== 'undefined' ? self.crypto : ({} as Crypto)) {
+    this._crypto = crypto
+    this._rsa = new RSAUtils(crypto)
+    this._aes = new AESUtils(crypto)
+    this._shamir = new ShamirClass(crypto)
+  }
+
+  /**
+   * Generates a UUID using a cryptographically secure random number generator.
+   */
+  randomUuid() {
+    return ((1e7).toString() + -1e3 + -4e3 + -8e3 + -1e11).replace(
+      /[018]/g,
+      //Keep next inlined or you will lose the random
+      (c) => (Number(c) ^ ((this.crypto.getRandomValues(new Uint8Array(1))! as Uint8Array)[0] & (15 >> (Number(c) / 4)))).toString(16)
+    )
+  }
+
+  /**
+   * @param data some data
+   * @return the sha256 hash of {@link data}
+   */
+  sha256(data: ArrayBuffer | Uint8Array): Promise<ArrayBuffer> {
+    return this.crypto.subtle.digest('SHA-256', data)
+  }
+
+  /**
+   * @param n how many bytes to generate
+   * @return an array with n random bytes
+   */
+  randomBytes(n: number): Uint8Array {
+    const res = new Uint8Array(n)
+    this.crypto.getRandomValues(res)
+    return res
+  }
+}

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

@@ -0,0 +1,85 @@
+import { KeyPair } from './RSA'
+import { CryptoPrimitives } from './CryptoPrimitives'
+import { DataOwnerWithType } from '../../icc-api/model/DataOwnerWithType'
+import { CryptoActorStubWithType } from '../../icc-api/model/CryptoActorStub'
+
+/**
+ * Allows to customise the behaviour of the crypto api to better suit your needs.
+ *
+ * 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
+ * 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
+ * malicious attacker may have added his own public keys to the data owner's public keys.
+ * 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
+ * creating recovery data only verified keys will be considered. For decrypting existing data instead unverified keys will be used without issues.
+ */
+export interface CryptoStrategies {
+  /**
+   * Method called during initialisation of the crypto API to validate keys recovered through iCure's recovery methods and/or to allow recovery of
+   * missing keys using means external to iCure.
+   * 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
+   * 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
+   * but can't verify the authenticity of the key pairs this method will be called.
+   * The recovered and verified keys will automatically be cached using the current api {@link KeyStorageFacade} and {@link StorageFacade}
+   *
+   * 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
+   * for the topmost parent of the current data owner hierarchy (first element) to the data for the current data owner (last element). Each object
+   * contains:
+   * - dataOwner: the data owner entity that this object refers to
+   * - unknownKeys: all public keys (in hex-encoded spki format) of `dataOwner` for which the authenticity status (verified or unverified) is unknown
+   *   (no result was cached from a previous api instantiation and the key was not generated on the current device).
+   * - unavailableKeys: all public keys (in hex-encoded spki format) of `dataOwner` for which the sdk could not recover a private key. May overlap
+   *   (partially or completely) with `unknownKeys`.
+   *
+   * The returned value must be an object associating to each data owner id an object with:
+   * - `recoveredKeys`: all recovered keys (will be automatically considered as verified), by fingerprint.
+   * - `keyAuthenticity`: an object associating to each public key fingerprint its authenticity. Note that if any of the keys from `unknownKeys` is
+   *   completely missing from this object the key will be considered as unverified in this api instance (same as if associated to false), but this
+   *   value won't be cached (will be again part of `unknownKeys` in future instances.
+   * @param keysData all information on unknown and unavailable keys for each data owner part of the current data owner hierarchy.
+   * @param cryptoPrimitives cryptographic primitives you can use to support the process.
+   * @return all recovered keys and key authenticity information, by data owner.
+   */
+  recoverAndVerifySelfHierarchyKeys(
+    keysData: {
+      dataOwner: DataOwnerWithType
+      unknownKeys: string[]
+      unavailableKeys: string[]
+    }[],
+    cryptoPrimitives: CryptoPrimitives
+  ): Promise<{
+    [dataOwnerId: string]: {
+      recoveredKeys: { [keyPairFingerprint: string]: KeyPair<CryptoKey> }
+      keyAuthenticity: { [keyPairFingerprint: string]: boolean }
+    }
+  }>
+
+  /**
+   * 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
+   * current data owner hierarchy. If no verified key is available for any of the data owner parents the api initialisation will automatically fail,
+   * however if there is no verified key for the current data owner you can instead create a new crypto key.
+   * @param self the current data owner.
+   * @param cryptoPrimitives cryptographic primitives you can use to support the process.
+   * @return depending on which values you return the api initialisation will proceed differently:
+   * - If this method returns true a new key will be automatically generated by the sdk.
+   * - If this method returns a key pair the crypto api loads the key pair and considers it as a device key.
+   * - If this method returns false the initialisation will fail with a predefined error.
+   * - If this method throws an error the initialisation will propagate the error.
+   */
+  generateNewKeyForDataOwner(self: DataOwnerWithType, cryptoPrimitives: CryptoPrimitives): Promise<KeyPair<CryptoKey> | boolean>
+
+  /**
+   * 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
+   * represents. This method is not called when the delegate would be the current data owner for the api.
+   *
+   * 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
+   * personal website of the other user, or by scanning verification qr codes at the doctor office...
+   *
+   * 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
+   * fail.
+   * @param delegate the potential data owner delegate.
+   * @param publicKeys public keys requiring verification, in spki hex-encoded format.
+   * @param cryptoPrimitives cryptographic primitives you can use to support the process.
+   * @return all verified public keys, in spki hex-encoded format.
+   */
+  verifyDelegatePublicKeys(delegate: CryptoActorStubWithType, publicKeys: string[], cryptoPrimitives: CryptoPrimitives): Promise<string[]>
+}