feat: new key management service with multiple backends

packages/askar/package.json

@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@openwallet-foundation/askar-shared": "^0.3.1",
-    "@animo-id/expo-secure-environment": "^0.1.0-alpha.11"
+    "@animo-id/expo-secure-environment": "^0.1.0-alpha.12"
   },
   "peerDependenciesMeta": {
     "@animo-id/expo-secure-environment": {

packages/askar/src/AskarApi.ts

@@ -0,0 +1,87 @@
+import { AgentContext } from '@credo-ts/core'
+import { injectable } from 'tsyringe'
+
+import { AskarStoreRotateKeyOptions, AskarStoreExportOptions, AskarStoreImportOptions } from './AskarApiOptions'
+import { AskarStoreManager } from './AskarStoreManager'
+
+@injectable()
+export class AskarApi {
+  public constructor(private agentContext: AgentContext, private askarStoreManager: AskarStoreManager) {}
+
+  public get isStoreOpen() {
+    return this.askarStoreManager.isStoreOpen(this.agentContext)
+  }
+
+  /**
+   * @throws {AskarStoreDuplicateError} if the wallet already exists
+   * @throws {AskarStoreError} if another error occurs
+   */
+  public async provisionStore(): Promise<void> {
+    await this.askarStoreManager.provisionStore(this.agentContext)
+  }
+
+  /**
+   * @throws {AskarStoreNotFoundError} if the wallet does not exist
+   * @throws {AskarStoreError} if another error occurs
+   */
+  public async openStore(): Promise<void> {
+    await this.askarStoreManager.openStore(this.agentContext)
+  }
+
+  /**
+   * Rotate the key of the current askar store.
+   *
+   * NOTE: multiple agent contexts (tenants) can use the same store. This method rotates the key for the whole store,
+   * it is advised to only run this method on the root tenant agent when using profile per wallet database strategy.
+   * After running this method you should change the store configuration in the Askar module.
+   *
+   * @throws {AskarStoreNotFoundError} if the wallet does not exist
+   * @throws {AskarStoreError} if another error occurs
+   */
+  public async rotateStoreKey(options: AskarStoreRotateKeyOptions): Promise<void> {
+    await this.askarStoreManager.rotateStoreKey(this.agentContext, options)
+  }
+
+  /**
+   * Exports the current askar store.
+   *
+   * NOTE: a store can contain profiles for multiple tenants. When you export a store
+   * all profiles will be exported with it.
+   *
+   * NOTE: store must be open before store can be expored
+   */
+  public async exportStore(options: AskarStoreExportOptions) {
+    await this.askarStoreManager.exportStore(this.agentContext, options)
+  }
+
+  /**
+   * Imports from an external store config into the current askar store config.
+   *
+   * NOTE: store must be closed first (using `closeStore`) before store can be imported
+   */
+  public async importStore(options: AskarStoreImportOptions) {
+    await this.askarStoreManager.importStore(this.agentContext, options)
+  }
+
+  /**
+   * Delete the current askar store.
+   *
+   * NOTE: multiple agent contexts (tenants) can use the same store. This method deletes the whole store.
+   *
+   *
+   * @throws {AskarStoreNotFoundError} if the wallet does not exist
+   * @throws {AskarStoreError} if another error occurs
+   */
+  public async deleteStore(): Promise<void> {
+    await this.askarStoreManager.deleteStore(this.agentContext)
+  }
+
+  /**
+   * Close the current askar store.
+   *
+   * This will close all sessions (also for tenants) in this store.
+   */
+  public async closeStore() {
+    await this.askarStoreManager.closeStore(this.agentContext)
+  }
+}

packages/askar/src/AskarApiOptions.ts

@@ -0,0 +1,28 @@
+import type { AskarModuleConfigStoreOptions } from './AskarModuleConfig'
+
+export interface AskarStoreExportOptions {
+  /**
+   * The store config to export the current store to.
+   */
+  exportToStore: AskarModuleConfigStoreOptions
+}
+
+export interface AskarStoreImportOptions {
+  /**
+   * The store config to import the current store from.
+   */
+  importFromStore: AskarModuleConfigStoreOptions
+}
+
+export interface AskarStoreRotateKeyOptions {
+  /**
+   * The new key to use for the store.
+   */
+  newKey: string
+
+  /**
+   * The new key derivation method to use for the store. If not provided the
+   * key derivation method from the current store config will be used.
+   */
+  newKeyDerivationMethod?: AskarModuleConfigStoreOptions['keyDerivationMethod']
+}

packages/askar/src/AskarModule.ts

@@ -1,13 +1,13 @@
 import type { AskarModuleConfigOptions } from './AskarModuleConfig'
 import type { AgentContext, DependencyManager, Module } from '@credo-ts/core'
 
-import { CredoError, InjectionSymbols } from '@credo-ts/core'
-import { Store } from '@openwallet-foundation/askar-shared'
+import { AgentConfig, CredoError, InjectionSymbols, Kms } from '@credo-ts/core'
 
+import { AskarApi } from './AskarApi'
 import { AskarMultiWalletDatabaseScheme, AskarModuleConfig } from './AskarModuleConfig'
+import { AskarStoreManager } from './AskarStoreManager'
+import { AksarKeyManagementService } from './kms/AskarKeyManagementService'
 import { AskarStorageService } from './storage'
-import { assertAskarWallet } from './utils/assertAskarWallet'
-import { AskarProfileWallet, AskarWallet } from './wallet'
 
 export class AskarModule implements Module {
   public readonly config: AskarModuleConfig
@@ -16,52 +16,68 @@ export class AskarModule implements Module {
     this.config = new AskarModuleConfig(config)
   }
 
+  public api = AskarApi
+
   public register(dependencyManager: DependencyManager) {
     dependencyManager.registerInstance(AskarModuleConfig, this.config)
 
-    if (dependencyManager.isRegistered(InjectionSymbols.Wallet)) {
-      throw new CredoError('There is an instance of Wallet already registered')
-    } else {
-      dependencyManager.registerContextScoped(InjectionSymbols.Wallet, AskarWallet)
+    if (!this.config.enableKms && !this.config.enableStorage) {
+      dependencyManager
+        .resolve(AgentConfig)
+        .logger.warn(`Both 'enableKms' and 'enableStorage' are disabled, meaning Askar won't be used by the agent.`)
+    }
 
-      // If the multiWalletDatabaseScheme is set to ProfilePerWallet, we want to register the AskarProfileWallet
-      if (this.config.multiWalletDatabaseScheme === AskarMultiWalletDatabaseScheme.ProfilePerWallet) {
-        dependencyManager.registerContextScoped(AskarProfileWallet)
-      }
+    if (this.config.enableKms) {
+      const kmsConfig = dependencyManager.resolve(Kms.KeyManagementModuleConfig)
+      kmsConfig.registerBackend(new AksarKeyManagementService())
     }
 
-    if (dependencyManager.isRegistered(InjectionSymbols.StorageService)) {
-      throw new CredoError('There is an instance of StorageService already registered')
-    } else {
+    if (this.config.enableStorage) {
+      if (dependencyManager.isRegistered(InjectionSymbols.StorageService)) {
+        throw new CredoError(
+          'Unable to register AskatStoreService. There is an instance of StorageService already registered'
+        )
+      }
       dependencyManager.registerSingleton(InjectionSymbols.StorageService, AskarStorageService)
     }
+
+    dependencyManager.registerSingleton(AskarStoreManager)
   }
 
-  public async initialize(agentContext: AgentContext): Promise<void> {
-    // We MUST use an askar wallet here
-    assertAskarWallet(agentContext.wallet)
-
-    const wallet = agentContext.wallet
-
-    // Register the Askar store instance on the dependency manager
-    // This allows it to be re-used for tenants
-    agentContext.dependencyManager.registerInstance(Store, agentContext.wallet.store)
-
-    // If the multiWalletDatabaseScheme is set to ProfilePerWallet, we want to register the AskarProfileWallet
-    // and return that as the wallet for all tenants, but not for the main agent, that should use the AskarWallet
-    if (this.config.multiWalletDatabaseScheme === AskarMultiWalletDatabaseScheme.ProfilePerWallet) {
-      agentContext.dependencyManager.container.register(InjectionSymbols.Wallet, {
-        useFactory: (container) => {
-          // If the container is the same as the root dependency manager container
-          // it means we are in the main agent, and we should use the root wallet
-          if (container === agentContext.dependencyManager.container) {
-            return wallet
-          }
-
-          // Otherwise we want to return the AskarProfileWallet
-          return container.resolve(AskarProfileWallet)
-        },
-      })
+  public async onInitializeContext(agentContext: AgentContext, metadata: Record<string, unknown>) {
+    // TODO: I think we should also register the store here
+    if (agentContext.contextCorrelationId === 'default') {
+      const storeManager = agentContext.dependencyManager.resolve(AskarStoreManager)
+      await storeManager.getInitializedStoreWithProfile(agentContext)
+      return
+    } else if (this.config.multiWalletDatabaseScheme === AskarMultiWalletDatabaseScheme.DatabasePerWallet) {
+      agentContext.dependencyManager.registerInstance('AskarContextMetadata', metadata)
+      const storeManager = agentContext.dependencyManager.resolve(AskarStoreManager)
+      await storeManager.getInitializedStoreWithProfile(agentContext)
     }
   }
+
+  public async onProvisionContext(agentContext: AgentContext) {
+    // We don't have any side effects to run
+    if (agentContext.contextCorrelationId === 'default') return null
+    if (this.config.multiWalletDatabaseScheme === AskarMultiWalletDatabaseScheme.ProfilePerWallet) return null
+
+    // For new stores (so not profiles) we need to generate a wallet key
+    return {
+      walletKey: this.config.askar.storeGenerateRawKey({}),
+    }
+  }
+
+  public async onDeleteContext(agentContext: AgentContext) {
+    const storeManager = agentContext.dependencyManager.resolve(AskarStoreManager)
+
+    // Will delete either the store (when root agent context or database per wallet) or profile (when not root agent context and profile per wallet)
+    await storeManager.deleteContext(agentContext)
+  }
+
+  public async onCloseContext(agentContext: AgentContext): Promise<void> {
+    const storeManager = agentContext.dependencyManager.resolve(AskarStoreManager)
+
+    await storeManager.closeContext(agentContext)
+  }
 }

packages/askar/src/AskarModuleConfig.ts

@@ -1,4 +1,5 @@
-import type { Askar } from '@openwallet-foundation/askar-shared'
+import type { AskarWalletPostgresStorageConfig, AskarWalletSqliteStorageConfig } from './wallet'
+import type { Askar, KdfMethod } from '@openwallet-foundation/askar-shared'
 
 export enum AskarMultiWalletDatabaseScheme {
   /**
@@ -12,7 +13,48 @@ export enum AskarMultiWalletDatabaseScheme {
   ProfilePerWallet = 'ProfilePerWallet',
 }
 
+export interface AskarModuleConfigStoreOptions {
+  /**
+   * The id of the store, and also the default profile that will be used for the root agent instance.
+   *
+   * - When SQLite is used that is not in-memory this will influence the path where the SQLite database is stored.
+   * - When Postgres is used, this determines the database.
+   */
+  id: string
+
+  /**
+   * The key to open the store
+   */
+  key: string
+
+  /**
+   * Key derivation method to use for opening the store.
+   *
+   * - `kdf:argon2i:mod` - most secure
+   * - `kdf:argon2i:int` - faster, less secure
+   * - `raw` - no key derivation. Useful if key is stored in e.g. the keychain on-device backed by biometrics.
+   *
+   * @default 'kdf:argon2i:mod'
+   */
+  keyDerivationMethod?: `${KdfMethod.Argon2IInt}` | `${KdfMethod.Argon2IMod}` | `${KdfMethod.Raw}`
+
+  /**
+   * The backend to use with backend specific configuraiton options.
+   *
+   * If not provided SQLite will be used by default
+   */
+  database?: AskarWalletSqliteStorageConfig | AskarWalletPostgresStorageConfig
+}
+
 export interface AskarModuleConfigOptions {
+  /**
+   * Store configuration used for askar.
+   *
+   * If `multiWalletDatabaseScheme` is set to `AskarMultiWalletDatabaseScheme.DatabasePerWallet` a new store will be created
+   * for each tenant. For performance reasons it is recommended to use `AskarMultiWalletDatabaseScheme.ProfilePerWallet`.
+   */
+  store: AskarModuleConfigStoreOptions
+
   /**
    *
    * ## Node.JS
@@ -58,6 +100,20 @@ export interface AskarModuleConfigOptions {
    * @default {@link AskarMultiWalletDatabaseScheme.DatabasePerWallet} (for backwards compatibility)
    */
   multiWalletDatabaseScheme?: AskarMultiWalletDatabaseScheme
+
+  /**
+   * Whether to enable and register the `AskarKeyManagementService` for key management and cryptographic operations.
+   *
+   * @default true
+   */
+  enableKms?: boolean
+
+  /**
+   * Whether to enable and register the `AskarStorageService` for storage
+   *
+   * @default true
+   */
+  enableStorage?: boolean
 }
 
 /**
@@ -79,4 +135,16 @@ export class AskarModuleConfig {
   public get multiWalletDatabaseScheme() {
     return this.options.multiWalletDatabaseScheme ?? AskarMultiWalletDatabaseScheme.DatabasePerWallet
   }
+
+  public get store() {
+    return this.options.store
+  }
+
+  public get enableKms() {
+    return this.options.enableKms
+  }
+
+  public get enableStorage() {
+    return this.options.enableStorage
+  }
 }