@sphereon/ssi-sdk.vc-status-list-issuer-drivers 0.34.1-feature.SSISDK.17.bitstring.sl.13 → 0.34.1-feature.SSISDK.17.bitstring.sl.16

package/src/drivers.ts

@@ -1,28 +1,50 @@
+/**
+ * StatusList Driver Implementation for TypeORM/Agent Data Sources
+ *
+ * This module provides the database-backed implementation of the IStatusListDriver interface,
+ * handling persistence and retrieval of status list credentials and entries using TypeORM.
+ * It delegates status list format-specific operations to the functions layer while managing
+ * database interactions, driver configuration, and entity lifecycle.
+ *
+ * Key responsibilities:
+ * - Database connection and store management
+ * - Status list CRUD operations
+ * - Status list entry management
+ * - Random index generation for new entries
+ * - Integration with multiple data sources
+ *
+ * @author Sphereon International B.V.
+ * @since 2024
+ */
+
 import { DataSources } from '@sphereon/ssi-sdk.agent-config'
 import {
+  BitstringStatusListEntryCredentialStatus,
   IAddStatusListArgs,
   IAddStatusListEntryArgs,
   IBitstringStatusListEntryEntity,
   IGetStatusListEntryByCredentialIdArgs,
   IGetStatusListEntryByIndexArgs,
-  IStatusListEntity,
   IStatusListEntryEntity,
   StatusListEntity,
   StatusListStore,
 } from '@sphereon/ssi-sdk.data-store'
 import {
-  BitstringStatusListEntryCredentialStatus,
   createCredentialStatusFromStatusList,
+  extractCredentialDetails,
   StatusList2021EntryCredentialStatus,
-  statusListCredentialToDetails,
   StatusListOAuthEntryCredentialStatus,
   StatusListResult,
+  toStatusListDetails,
 } from '@sphereon/ssi-sdk.vc-status-list'
 import { StatusListCredential, StatusListCredentialIdMode, StatusListDriverType, StatusListType } from '@sphereon/ssi-types'
 import { DataSource } from 'typeorm'
 import { IStatusListDriver } from './types'
 import { statusListResultToEntity } from './status-list-adapters'
 
+/**
+ * Configuration options for status list management
+ */
 export interface StatusListManagementOptions {
   id?: string
   correlationId?: string
@@ -32,14 +54,25 @@ export interface StatusListManagementOptions {
 
 export type DriverOptions = TypeORMOptions
 
+/**
+ * TypeORM-specific configuration options
+ */
 export interface TypeORMOptions {
   dbName?: string
 }
 
+/**
+ * Filesystem-specific configuration options
+ */
 export interface FilesystemOptions {
   path: string // The base path where statusList Credentials will be persisted. Should be a folder and thus not include the VC/StatusList itself
 }
 
+/**
+ * Creates status list management options for TypeORM driver
+ * @param args - Configuration parameters including id, correlationId, and database name
+ * @returns StatusListManagementOptions configured for TypeORM
+ */
 export function getOptions(args: { id?: string; correlationId?: string; dbName: string }): StatusListManagementOptions {
   return {
     id: args.id,
@@ -49,6 +82,11 @@ export function getOptions(args: { id?: string; correlationId?: string; dbName:
   }
 }
 
+/**
+ * Creates and initializes a status list driver instance
+ * @param args - Configuration parameters including database connection details
+ * @returns Promise resolving to initialized IStatusListDriver instance
+ */
 export async function getDriver(args: {
   id?: string
   correlationId?: string
@@ -70,15 +108,33 @@ export async function getDriver(args: {
   )
 }
 
+/**
+ * TypeORM-based implementation of the IStatusListDriver interface
+ *
+ * Manages status list credentials and entries using a TypeORM data source.
+ * Handles database operations while delegating format-specific logic to the functions layer.
+ */
 export class AgentDataSourceStatusListDriver implements IStatusListDriver {
   private _statusListLength: number | undefined
 
+  /**
+   * Creates a new AgentDataSourceStatusListDriver instance
+   * @param _dataSource - TypeORM DataSource for database operations
+   * @param _statusListStore - StatusListStore for data persistence
+   * @param options - Driver configuration options
+   */
   constructor(
     private _dataSource: DataSource,
     private _statusListStore: StatusListStore,
     private options: StatusListManagementOptions,
   ) {}
 
+  /**
+   * Initializes and creates a new AgentDataSourceStatusListDriver instance
+   * @param options - Status list management configuration
+   * @param dbArgs - Database connection arguments
+   * @returns Promise resolving to initialized driver instance
+   */
   public static async init(
     options: StatusListManagementOptions,
     dbArgs?: {
@@ -109,6 +165,10 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return new AgentDataSourceStatusListDriver(dataSource, statusListStore, options)
   }
 
+  /**
+   * Gets the TypeORM DataSource instance
+   * @returns DataSource instance for database operations
+   */
   get dataSource(): DataSource {
     if (!this._dataSource) {
       throw Error(`Datasource not available yet for ${this.options.driverOptions?.dbName}`)
@@ -116,6 +176,10 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return this._dataSource
   }
 
+  /**
+   * Gets the StatusListStore instance
+   * @returns StatusListStore for data persistence operations
+   */
   get statusListStore(): StatusListStore {
     if (!this._statusListStore) {
       this._statusListStore = new StatusListStore(this.dataSource)
@@ -123,14 +187,27 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return this._statusListStore
   }
 
+  /**
+   * Gets the driver configuration options
+   * @returns DriverOptions configuration
+   */
   getOptions(): DriverOptions {
     return this.options.driverOptions ?? {}
   }
 
+  /**
+   * Gets the driver type
+   * @returns StatusListDriverType enum value
+   */
   getType(): StatusListDriverType {
     return this.options.driverType
   }
 
+  /**
+   * Creates a new status list credential and stores it in the database
+   * @param args - Status list creation parameters
+   * @returns Promise resolving to StatusListResult
+   */
   async createStatusList(args: {
     statusListType: StatusListType
     statusListCredential: StatusListCredential
@@ -144,12 +221,13 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     }
     const credentialIdMode = args.credentialIdMode ?? StatusListCredentialIdMode.ISSUANCE
 
-    // Get implementation details
-    const implementationResult = await statusListCredentialToDetails({
-      ...args,
+    // Convert credential to implementation details using CREATE/READ context
+    const implementationResult = await toStatusListDetails({
+      statusListCredential: args.statusListCredential,
+      statusListType: args.statusListType,
+      bitsPerStatus: args.bitsPerStatus,
       correlationId,
       driverType: this.getType(),
-      bitsPerStatus: args.bitsPerStatus,
     })
 
     // Add driver-specific fields to create complete entity
@@ -164,29 +242,31 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     this._statusListLength = implementationResult.length
     return implementationResult
   }
-  async updateStatusList(args: {
-    statusListCredential: StatusListCredential
-    correlationId: string
-    statusListType: StatusListType
-  }): Promise<StatusListResult> {
+
+  /**
+   * Updates an existing status list credential in the database
+   * @param args - Status list update parameters
+   * @returns Promise resolving to StatusListResult
+   */
+  async updateStatusList(args: { statusListCredential: StatusListCredential; correlationId: string }): Promise<StatusListResult> {
     const correlationId = args.correlationId ?? this.options.correlationId
-    const details = await statusListCredentialToDetails({ ...args, correlationId, driverType: this.getType() })
-    const entity = await (
-      await this.statusListStore.getStatusListRepo(args.statusListType)
-    ).findOne({
-      where: [
-        {
-          id: details.id,
-        },
-        {
-          correlationId,
-        },
-      ],
+
+    const extractedDetails = await extractCredentialDetails(args.statusListCredential)
+    const entity = await this.statusListStore.getStatusList({
+      id: extractedDetails.id,
+      correlationId,
     })
     if (!entity) {
-      throw Error(`Status list ${details.id}, correlationId ${args.correlationId} could not be found`)
+      throw Error(`Status list ${extractedDetails.id}, correlationId ${correlationId} could not be found`)
     }
 
+    entity.statusListCredential = args.statusListCredential
+
+    const details = await toStatusListDetails({
+      extractedDetails,
+      statusListEntity: entity,
+    })
+
     // Merge details with existing entity and driver properties
     const updateArgs = {
       ...entity,
@@ -200,11 +280,20 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return { ...entity, ...details }
   }
 
+  /**
+   * Deletes the status list from the database
+   * @returns Promise resolving to boolean indicating success
+   */
   async deleteStatusList(): Promise<boolean> {
     await this.statusListStore.removeStatusList({ id: this.options.id, correlationId: this.options.correlationId })
     return Promise.resolve(true)
   }
 
+  /**
+   * Updates a status list entry and returns the credential status
+   * @param args - Status list entry update parameters
+   * @returns Promise resolving to credential status and entry
+   */
   async updateStatusListEntry(args: IAddStatusListEntryArgs): Promise<{
     credentialStatus: StatusList2021EntryCredentialStatus | StatusListOAuthEntryCredentialStatus | BitstringStatusListEntryCredentialStatus
     statusListEntry: IStatusListEntryEntity | IBitstringStatusListEntryEntity
@@ -228,18 +317,33 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     }
   }
 
+  /**
+   * Retrieves a status list entry by credential ID
+   * @param args - Query parameters including credential ID
+   * @returns Promise resolving to status list entry or undefined
+   */
   async getStatusListEntryByCredentialId(
     args: IGetStatusListEntryByCredentialIdArgs,
   ): Promise<IStatusListEntryEntity | IBitstringStatusListEntryEntity | undefined> {
     return await this.statusListStore.getStatusListEntryByCredentialId(args)
   }
 
+  /**
+   * Retrieves a status list entry by index
+   * @param args - Query parameters including status list index
+   * @returns Promise resolving to status list entry or undefined
+   */
   async getStatusListEntryByIndex(
     args: IGetStatusListEntryByIndexArgs,
   ): Promise<IStatusListEntryEntity | IBitstringStatusListEntryEntity | undefined> {
     return await this.statusListStore.getStatusListEntryByIndex(args)
   }
 
+  /**
+   * Generates a random available index for new status list entries
+   * @param args - Optional correlation ID parameter
+   * @returns Promise resolving to available index number
+   */
   async getRandomNewStatusListIndex(args?: { correlationId?: string }): Promise<number> {
     let result = -1
     let tries = 0
@@ -250,6 +354,12 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return result
   }
 
+  /**
+   * Implementation for generating random status list indices with retry logic
+   * @param tries - Number of attempts made
+   * @param args - Optional correlation ID parameter
+   * @returns Promise resolving to available index or -1 if none found
+   */
   private async getRandomNewStatusListIndexImpl(tries: number, args?: { correlationId?: string }): Promise<number> {
     const statusListId = this.options.id
     const correlationId = args?.correlationId ?? this.options.correlationId
@@ -270,6 +380,11 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return -1
   }
 
+  /**
+   * Gets the length of the status list
+   * @param args - Optional correlation ID parameter
+   * @returns Promise resolving to status list length
+   */
   async getStatusListLength(args?: { correlationId?: string }): Promise<number> {
     if (!this._statusListLength) {
       this._statusListLength = await this.getStatusList(args).then((details) => details.length)
@@ -277,30 +392,50 @@ export class AgentDataSourceStatusListDriver implements IStatusListDriver {
     return this._statusListLength!
   }
 
+  /**
+   * Retrieves the status list details
+   * @param args - Optional correlation ID parameter
+   * @returns Promise resolving to StatusListResult
+   */
   async getStatusList(args?: { correlationId?: string }): Promise<StatusListResult> {
     const id = this.options.id
     const correlationId = args?.correlationId ?? this.options.correlationId
-    return await this.statusListStore.getStatusList({ id, correlationId }).then((statusListEntity: IStatusListEntity) =>
-      statusListCredentialToDetails({
-        statusListType: statusListEntity.type,
-        statusListCredential: statusListEntity.statusListCredential!,
-        bitsPerStatus: statusListEntity.bitsPerStatus,
-      }),
-    )
+
+    const statusListEntity = await this.statusListStore.getStatusList({ id, correlationId })
+
+    // Convert entity to result using CREATE/READ context
+    return await toStatusListDetails({
+      statusListCredential: statusListEntity.statusListCredential!,
+      statusListType: statusListEntity.type,
+      bitsPerStatus: statusListEntity.bitsPerStatus,
+      correlationId: statusListEntity.correlationId,
+      driverType: statusListEntity.driverType,
+    })
   }
 
+  /**
+   * Retrieves all status lists
+   * @returns Promise resolving to array of StatusListResult
+   */
   async getStatusLists(): Promise<Array<StatusListResult>> {
     const statusLists = await this.statusListStore.getStatusLists({})
     return Promise.all(
       statusLists.map(async (statusListEntity) => {
-        return statusListCredentialToDetails({
-          statusListType: statusListEntity.type,
+        return toStatusListDetails({
           statusListCredential: statusListEntity.statusListCredential!,
+          statusListType: statusListEntity.type,
+          bitsPerStatus: statusListEntity.bitsPerStatus,
+          correlationId: statusListEntity.correlationId,
+          driverType: statusListEntity.driverType,
         })
       }),
     )
   }
 
+  /**
+   * Checks if a status list index is currently in use
+   * @returns Promise resolving to boolean indicating usage status
+   */
   isStatusListIndexInUse(): Promise<boolean> {
     return Promise.resolve(false)
   }

package/src/types.ts

@@ -1,5 +1,6 @@
 import { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
 import {
+  BitstringStatusListEntryCredentialStatus,
   IAddStatusListEntryArgs,
   IGetStatusListEntryByCredentialIdArgs,
   IGetStatusListEntryByIndexArgs,
@@ -7,13 +8,12 @@ import {
   StatusListStore,
 } from '@sphereon/ssi-sdk.data-store'
 import {
-  BitstringStatusListEntryCredentialStatus,
   IStatusListPlugin,
   StatusList2021EntryCredentialStatus,
   StatusListOAuthEntryCredentialStatus,
   StatusListResult,
 } from '@sphereon/ssi-sdk.vc-status-list'
-import { StatusListCredential, StatusListDriverType } from '@sphereon/ssi-types'
+import { StatusListCredential, StatusListDriverType, StatusListType } from '@sphereon/ssi-types'
 import { IAgentContext, ICredentialIssuer, ICredentialVerifier, IDataStoreORM, IDIDManager, IKeyManager, IResolver } from '@veramo/core'
 import { DriverOptions } from './drivers'
 import { IVcdmCredentialPlugin } from '@sphereon/ssi-sdk.credential-vcdm'
@@ -38,7 +38,12 @@ export interface IStatusListDriver {
 
   getStatusListLength(args?: { correlationId?: string }): Promise<number>
 
-  createStatusList(args: { statusListCredential: StatusListCredential; correlationId?: string; bitsPerStatus?: number }): Promise<StatusListResult>
+  createStatusList(args: {
+    statusListType: StatusListType
+    statusListCredential: StatusListCredential
+    correlationId?: string
+    bitsPerStatus?: number
+  }): Promise<StatusListResult>
 
   getStatusList(args?: { correlationId?: string }): Promise<StatusListResult>
 
@@ -53,7 +58,7 @@ export interface IStatusListDriver {
 
   getStatusListEntryByIndex(args: IGetStatusListEntryByIndexArgs): Promise<IStatusListEntryEntity | undefined>
 
-  updateStatusList(args: { statusListCredential: StatusListCredential }): Promise<StatusListResult>
+  updateStatusList(args: { statusListCredential: StatusListCredential; correlationId: string }): Promise<StatusListResult>
 
   deleteStatusList(): Promise<boolean>