@sphereon/ssi-sdk.vc-status-list 0.34.0 → 0.34.1-feature.SSISDK.17.bitstring.sl.11

package/src/impl/OAuthStatusList.ts

@@ -1,26 +1,28 @@
 import type { IAgentContext, ICredentialPlugin, IKeyManager } from '@veramo/core'
-import { type CompactJWT, type CWT, type CredentialProofFormat, StatusListType } from '@sphereon/ssi-types'
+import { type CompactJWT, type CredentialProofFormat, type CWT, StatusListType } from '@sphereon/ssi-types'
 import type {
   CheckStatusIndexArgs,
   CreateStatusListArgs,
   SignedStatusListData,
+  StatusListOAuthEntryCredentialStatus,
   StatusListResult,
   StatusOAuth,
   ToStatusListDetailsArgs,
   UpdateStatusListFromEncodedListArgs,
   UpdateStatusListIndexArgs,
 } from '../types'
-import { determineProofFormat, getAssertedValue, getAssertedValues } from '../utils'
-import type { IStatusList } from './IStatusList'
+import { determineProofFormat, ensureDate, getAssertedValue, getAssertedValues } from '../utils'
+import type { IOAuthStatusListImplementationResult, IStatusList } from './IStatusList'
 import { StatusList } from '@sd-jwt/jwt-status-list'
 import type { IJwtService } from '@sphereon/ssi-sdk-ext.jwt-service'
 import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
 import { createSignedJwt, decodeStatusListJWT } from './encoding/jwt'
 import { createSignedCbor, decodeStatusListCWT } from './encoding/cbor'
+import { IBitstringStatusListEntryEntity, IStatusListEntryEntity, OAuthStatusListEntity, StatusListEntity } from '@sphereon/ssi-sdk.data-store'
 
 type IRequiredContext = IAgentContext<ICredentialPlugin & IJwtService & IIdentifierResolution & IKeyManager>
 
-export const DEFAULT_BITS_PER_STATUS = 1 // 1 bit is sufficient for 0x00 - "VALID"  0x01 - "INVALID" saving space in the process
+export const DEFAULT_BITS_PER_STATUS = 1 // 1 bit is sufficient for 0x00 - "VALID" 0x01 - "INVALID" saving space in the process
 export const DEFAULT_LIST_LENGTH = 250000
 export const DEFAULT_PROOF_FORMAT = 'jwt' as CredentialProofFormat
 
@@ -32,7 +34,8 @@ export class OAuthStatusListImplementation implements IStatusList {
 
     const proofFormat = args?.proofFormat ?? DEFAULT_PROOF_FORMAT
     const { issuer, id, oauthStatusList, keyRef } = args
-    const { bitsPerStatus, expiresAt } = oauthStatusList
+    const { bitsPerStatus } = oauthStatusList
+    const expiresAt = ensureDate(oauthStatusList.expiresAt)
     const length = args.length ?? DEFAULT_LIST_LENGTH
     const issuerString = typeof issuer === 'string' ? issuer : issuer.id
     const correlationId = getAssertedValue('correlationId', args.correlationId)
@@ -56,7 +59,8 @@ export class OAuthStatusListImplementation implements IStatusList {
   }
 
   async updateStatusListIndex(args: UpdateStatusListIndexArgs, context: IRequiredContext): Promise<StatusListResult> {
-    const { statusListCredential, value, expiresAt, keyRef } = args
+    const { statusListCredential, value, keyRef } = args
+    const expiresAt = ensureDate(args.expiresAt)
     if (typeof statusListCredential !== 'string') {
       return Promise.reject('statusListCredential in neither JWT nor CWT')
     }
@@ -70,6 +74,10 @@ export class OAuthStatusListImplementation implements IStatusList {
       throw new Error('Status list index out of bounds')
     }
 
+    if (typeof value !== 'number') {
+      throw new Error('Status list values should be of type number')
+    }
+
     statusList.setStatus(index, value)
     const { statusListCredential: signedCredential, encodedList } = await this.createSignedStatusList(
       proofFormat,
@@ -102,15 +110,15 @@ export class OAuthStatusListImplementation implements IStatusList {
       throw new Error('OAuthStatusList options are required for type OAuthStatusList')
     }
     const { proofFormat, oauthStatusList, keyRef } = args
-    const { bitsPerStatus, expiresAt } = oauthStatusList
+    const { bitsPerStatus } = oauthStatusList
+    const expiresAt = ensureDate(oauthStatusList.expiresAt)
 
     const { issuer, id } = getAssertedValues(args)
     const issuerString = typeof issuer === 'string' ? issuer : issuer.id
 
     const listToUpdate = StatusList.decompressStatusList(args.encodedList, bitsPerStatus ?? DEFAULT_BITS_PER_STATUS)
     const index = typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex)
-    // FIXME: See above.
-    listToUpdate.setStatus(index, args.value ? 1 : 0)
+    listToUpdate.setStatus(index, args.value)
 
     const { statusListCredential, encodedList } = await this.createSignedStatusList(
       proofFormat ?? DEFAULT_PROOF_FORMAT,
@@ -138,10 +146,6 @@ export class OAuthStatusListImplementation implements IStatusList {
     }
   }
 
-  private buildContentType(proofFormat: 'jwt' | 'lds' | 'EthereumEip712Signature2021' | 'cbor' | undefined) {
-    return `application/statuslist+${proofFormat === 'cbor' ? 'cwt' : 'jwt'}`
-  }
-
   async checkStatusIndex(args: CheckStatusIndexArgs): Promise<number | StatusOAuth> {
     const { statusListCredential, statusListIndex } = args
     if (typeof statusListCredential !== 'string') {
@@ -153,19 +157,23 @@ export class OAuthStatusListImplementation implements IStatusList {
 
     const index = typeof statusListIndex === 'number' ? statusListIndex : parseInt(statusListIndex)
     if (index < 0 || index >= statusList.statusList.length) {
-      throw new Error('Status list index out of bounds')
+      throw new Error(`Status list index out of bounds, has ${statusList.statusList.length} items, requested ${index}`)
     }
 
     return statusList.getStatus(index)
   }
 
-  async toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult> {
+  async toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult & IOAuthStatusListImplementationResult> {
     const { statusListPayload } = args as { statusListPayload: CompactJWT | CWT }
     const proofFormat = determineProofFormat(statusListPayload)
     const decoded = proofFormat === 'jwt' ? decodeStatusListJWT(statusListPayload) : decodeStatusListCWT(statusListPayload)
     const { statusList, issuer, id, exp } = decoded
 
+    const bitsPerStatus = statusList.getBitsPerStatus()
+    const expiresAt = exp ? new Date(exp * 1000) : undefined
+
     return {
+      // Base implementation fields
       id,
       encodedList: statusList.compressStatusList(),
       issuer,
@@ -174,17 +182,51 @@ export class OAuthStatusListImplementation implements IStatusList {
       length: statusList.statusList.length,
       statusListCredential: statusListPayload,
       statuslistContentType: this.buildContentType(proofFormat),
+      correlationId: args.correlationId, // FIXME these do not need to be inside the impl
+      driverType: args.driverType, // FIXME these do not need to be inside the impl
+
+      // Flattened OAuth-specific fields
+      bitsPerStatus,
+      ...(expiresAt && { expiresAt }),
+
+      // Legacy nested structure for backward compatibility
       oauthStatusList: {
-        bitsPerStatus: statusList.getBitsPerStatus(),
-        ...(exp && { expiresAt: new Date(exp * 1000) }),
+        bitsPerStatus,
+        ...(expiresAt && { expiresAt }),
       },
+
+      // Optional fields from args
       ...(args.correlationId && { correlationId: args.correlationId }),
       ...(args.driverType && { driverType: args.driverType }),
     }
   }
 
+  async createCredentialStatus(args: {
+    statusList: StatusListEntity
+    statusListEntry: IStatusListEntryEntity | IBitstringStatusListEntryEntity
+    statusListIndex: number
+  }): Promise<StatusListOAuthEntryCredentialStatus> {
+    const { statusList, statusListIndex } = args
+
+    // Cast to OAuthStatusListEntity to access specific properties
+    const oauthStatusList = statusList as OAuthStatusListEntity
+
+    return {
+      id: `${statusList.id}#${statusListIndex}`,
+      type: 'OAuthStatusListEntry',
+      bitsPerStatus: oauthStatusList.bitsPerStatus,
+      statusListIndex: '' + statusListIndex,
+      statusListCredential: statusList.id,
+      expiresAt: oauthStatusList.expiresAt,
+    }
+  }
+
+  private buildContentType(proofFormat: CredentialProofFormat | undefined) {
+    return `application/statuslist+${proofFormat === 'cbor' ? 'cwt' : 'jwt'}`
+  }
+
   private async createSignedStatusList(
-    proofFormat: 'jwt' | 'lds' | 'EthereumEip712Signature2021' | 'cbor',
+    proofFormat: CredentialProofFormat,
     context: IAgentContext<ICredentialPlugin & IJwtService & IIdentifierResolution & IKeyManager>,
     statusList: StatusList,
     issuerString: string,

package/src/impl/StatusList2021.ts

@@ -2,15 +2,15 @@ import type { IAgentContext, ICredentialPlugin, ProofFormat as VeramoProofFormat
 import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
 import {
   CredentialMapper,
+  type CredentialProofFormat,
   DocumentFormat,
   type IIssuer,
-  type CredentialProofFormat,
   type StatusListCredential,
   StatusListType,
 } from '@sphereon/ssi-types'
 
 import { StatusList } from '@sphereon/vc-status-list'
-import type { IStatusList } from './IStatusList'
+import type { IStatusList, IStatusList2021ImplementationResult } from './IStatusList'
 import type {
   CheckStatusIndexArgs,
   CreateStatusListArgs,
@@ -19,12 +19,12 @@ import type {
   UpdateStatusListFromEncodedListArgs,
   UpdateStatusListIndexArgs,
 } from '../types'
-
-import { Status2021 } from '../types'
+import { Status2021, StatusList2021EntryCredentialStatus } from '../types'
 import { assertValidProofType, getAssertedProperty, getAssertedValue, getAssertedValues } from '../utils'
+import { IBitstringStatusListEntryEntity, IStatusListEntryEntity, StatusList2021Entity, StatusListEntity } from '@sphereon/ssi-sdk.data-store'
 
 export const DEFAULT_LIST_LENGTH = 250000
-export const DEFAULT_PROOF_FORMAT = 'lds' as VeramoProofFormat
+export const DEFAULT_PROOF_FORMAT = 'lds' as CredentialProofFormat
 
 export class StatusList2021Implementation implements IStatusList {
   async createNewStatusList(
@@ -96,11 +96,15 @@ export class StatusList2021Implementation implements IStatusList {
       context,
     )
 
+    if (!('statusPurpose' in credentialSubject)) {
+      return Promise.reject(Error('statusPurpose is required in credentialSubject for StatusList2021'))
+    }
+
     return {
       statusListCredential: updatedCredential,
       encodedList,
       statusList2021: {
-        ...('statusPurpose' in credentialSubject ? { statusPurpose: credentialSubject.statusPurpose } : {}),
+        statusPurpose: credentialSubject.statusPurpose,
         indexingDirection: 'rightToLeft',
       },
       length: statusList.length - 1,
@@ -126,7 +130,7 @@ export class StatusList2021Implementation implements IStatusList {
     const { issuer, id } = getAssertedValues(args)
     const statusList = await StatusList.decode({ encodedList: args.encodedList })
     const index = typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex)
-    statusList.setStatus(index, args.value)
+    statusList.setStatus(index, args.value !== 0)
 
     const newEncodedList = await statusList.encode()
     const credential = await this.createVerifiableCredential(
@@ -166,7 +170,7 @@ export class StatusList2021Implementation implements IStatusList {
     return status ? Status2021.Invalid : Status2021.Valid
   }
 
-  async toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult> {
+  async toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult & IStatusList2021ImplementationResult> {
     const { statusListPayload } = args
     const uniform = CredentialMapper.toUniformCredential(statusListPayload)
     const { issuer, credentialSubject } = uniform
@@ -175,9 +179,11 @@ export class StatusList2021Implementation implements IStatusList {
     const proofFormat: CredentialProofFormat = CredentialMapper.detectDocumentType(statusListPayload) === DocumentFormat.JWT ? 'jwt' : 'lds'
 
     const statusPurpose = getAssertedProperty('statusPurpose', credentialSubject)
+    const indexingDirection = 'rightToLeft'
     const list = await StatusList.decode({ encodedList })
 
     return {
+      // Base implementation fields
       id,
       encodedList,
       issuer,
@@ -186,12 +192,41 @@ export class StatusList2021Implementation implements IStatusList {
       length: list.length,
       statusListCredential: statusListPayload,
       statuslistContentType: this.buildContentType(proofFormat),
+      correlationId: args.correlationId, // FIXME these do not need to be inside the impl
+      driverType: args.driverType, // FIXME these do not need to be inside the impl
+
+      // Flattened StatusList2021-specific fields
+      indexingDirection,
+      statusPurpose,
+
+      // Legacy nested structure for backward compatibility
       statusList2021: {
-        indexingDirection: 'rightToLeft',
+        indexingDirection,
         statusPurpose,
+
+        // Optional fields from args
+        ...(args.correlationId && { correlationId: args.correlationId }),
+        ...(args.driverType && { driverType: args.driverType }),
       },
-      ...(args.correlationId && { correlationId: args.correlationId }),
-      ...(args.driverType && { driverType: args.driverType }),
+    }
+  }
+
+  async createCredentialStatus(args: {
+    statusList: StatusListEntity
+    statusListEntry: IStatusListEntryEntity | IBitstringStatusListEntryEntity
+    statusListIndex: number
+  }): Promise<StatusList2021EntryCredentialStatus> {
+    const { statusList, statusListIndex } = args
+
+    // Cast to StatusList2021Entity to access specific properties
+    const statusList2021 = statusList as StatusList2021Entity
+
+    return {
+      id: `${statusList.id}#${statusListIndex}`,
+      type: 'StatusList2021Entry',
+      statusPurpose: statusList2021.statusPurpose ?? 'revocation',
+      statusListIndex: '' + statusListIndex,
+      statusListCredential: statusList.id,
     }
   }
 
@@ -234,7 +269,7 @@ export class StatusList2021Implementation implements IStatusList {
     return CredentialMapper.toWrappedVerifiableCredential(verifiableCredential as StatusListCredential).original as StatusListCredential
   }
 
-  private buildContentType(proofFormat: 'jwt' | 'lds' | 'EthereumEip712Signature2021' | 'cbor' | undefined) {
+  private buildContentType(proofFormat: CredentialProofFormat | undefined) {
     switch (proofFormat) {
       case 'jwt':
         return `application/statuslist+jwt`

package/src/impl/StatusListFactory.ts

@@ -2,6 +2,7 @@ import type { IStatusList } from './IStatusList'
 import { StatusList2021Implementation } from './StatusList2021'
 import { OAuthStatusListImplementation } from './OAuthStatusList'
 import { StatusListType } from '@sphereon/ssi-types'
+import { BitstringStatusListImplementation } from './BitstringStatusListImplementation'
 
 export class StatusListFactory {
   private static instance: StatusListFactory
@@ -11,6 +12,7 @@ export class StatusListFactory {
     this.implementations = new Map()
     this.implementations.set(StatusListType.StatusList2021, new StatusList2021Implementation())
     this.implementations.set(StatusListType.OAuthStatusList, new OAuthStatusListImplementation())
+    this.implementations.set(StatusListType.BitstringStatusList, new BitstringStatusListImplementation())
   }
 
   public static getInstance(): StatusListFactory {

package/src/types/BitstringStatusList.ts

@@ -0,0 +1,4 @@
+import { StatusListCredential } from '@sphereon/ssi-types'
+import { BitstringStatusListCredentialUnsigned } from '../../../../../vc-bitstring-status-lists'
+
+export type BitstringStatusListCredential = BitstringStatusListCredentialUnsigned & StatusListCredential

package/src/types/index.ts

@@ -1,13 +1,12 @@
 import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
 import {
+  type CredentialProofFormat,
   type ICredential,
   type ICredentialStatus,
   type IIssuer,
   type IVerifiableCredential,
   type OrPromise,
-  type CredentialProofFormat,
   type StatusListCredential,
-  StatusListCredentialIdMode,
   StatusListDriverType,
   type StatusListIndexingDirection,
   StatusListType,
@@ -26,6 +25,7 @@ import { DataSource } from 'typeorm'
 import type { BitsPerStatus } from '@sd-jwt/jwt-status-list'
 import type { SdJwtVcPayload } from '@sd-jwt/sd-jwt-vc'
 import type { StatusListOpts } from '@sphereon/oid4vci-common'
+import { BitstringStatusPurpose } from '@4sure-tech/vc-bitstring-status-lists'
 
 export enum StatusOAuth {
   Valid = 0,
@@ -38,6 +38,8 @@ export enum Status2021 {
   Invalid = 1,
 }
 
+export type BitstringStatus = number
+
 export type StatusList2021Args = {
   indexingDirection: StatusListIndexingDirection
   statusPurpose?: StatusPurpose2021
@@ -45,10 +47,18 @@ export type StatusList2021Args = {
 }
 
 export type OAuthStatusListArgs = {
-  bitsPerStatus?: BitsPerStatus
+  bitsPerStatus: BitsPerStatus
   expiresAt?: Date
 }
 
+export type BitstringStatusListArgs = {
+  statusPurpose: BitstringStatusPurpose
+  bitsPerStatus: number
+  ttl?: number
+  validFrom?: Date
+  validUntil?: Date
+}
+
 export type BaseCreateNewStatusListArgs = {
   type: StatusListType
   id: string
@@ -59,6 +69,7 @@ export type BaseCreateNewStatusListArgs = {
   keyRef?: string
   statusList2021?: StatusList2021Args
   oauthStatusList?: OAuthStatusListArgs
+  bitstringStatusList?: BitstringStatusListArgs
   driverType?: StatusListDriverType
 }
 
@@ -71,10 +82,18 @@ export type UpdateOAuthStatusListArgs = {
   expiresAt?: Date
 }
 
+export type UpdateBitstringStatusListArgs = {
+  statusPurpose: BitstringStatusPurpose
+  bitsPerStatus: number
+  validFrom?: Date
+  validUntil?: Date
+  ttl?: number
+}
+
 export interface UpdateStatusListFromEncodedListArgs {
   type?: StatusListType
   statusListIndex: number | string
-  value: boolean
+  value: number
   proofFormat?: CredentialProofFormat
   keyRef?: string
   correlationId?: string
@@ -83,41 +102,57 @@ export interface UpdateStatusListFromEncodedListArgs {
   id: string
   statusList2021?: UpdateStatusList2021Args
   oauthStatusList?: UpdateOAuthStatusListArgs
+  bitstringStatusList?: UpdateBitstringStatusListArgs
 }
 
 export interface UpdateStatusListFromStatusListCredentialArgs {
   statusListCredential: StatusListCredential // | CompactJWT
   keyRef?: string
   statusListIndex: number | string
-  value: number | Status2021 | StatusOAuth
+  value: number | Status2021 | StatusOAuth | BitstringStatus
 }
 
 export interface StatusListResult {
+  id: string
   encodedList: string
-  statusListCredential: StatusListCredential
-  length: number
+  issuer: string | IIssuer
   type: StatusListType
   proofFormat: CredentialProofFormat
-  id: string
+  length: number
+  statusListCredential: StatusListCredential
   statuslistContentType: string
-  issuer: string | IIssuer
-  statusList2021?: StatusList2021Details
-  oauthStatusList?: OAuthStatusDetails
-
-  // These cannot be deduced from the VC, so they are present when callers pass in these values as params
   correlationId?: string
   driverType?: StatusListDriverType
-  credentialIdMode?: StatusListCredentialIdMode
-}
 
-interface StatusList2021Details {
-  indexingDirection: StatusListIndexingDirection
-  statusPurpose?: StatusPurpose2021
-}
+  // Flattened StatusList2021 fields
+  indexingDirection?: StatusListIndexingDirection
+  statusPurpose?: StatusPurpose2021 | BitstringStatusPurpose | BitstringStatusPurpose[]
 
-interface OAuthStatusDetails {
-  bitsPerStatus?: BitsPerStatus
+  // Flattened OAuth fields
+  bitsPerStatus?: number
   expiresAt?: Date
+
+  // Flattened Bitstring fields
+  validFrom?: Date
+  validUntil?: Date
+  ttl?: number
+
+  // Legacy nested structures for backward compatibility
+  statusList2021?: {
+    indexingDirection: StatusListIndexingDirection
+    statusPurpose: StatusPurpose2021
+  }
+  oauthStatusList?: {
+    bitsPerStatus: number
+    expiresAt?: Date
+  }
+  bitstringStatusList?: {
+    statusPurpose: BitstringStatusPurpose | BitstringStatusPurpose[]
+    bitsPerStatus?: number
+    validFrom?: Date
+    validUntil?: Date
+    ttl?: number
+  }
 }
 
 export interface StatusList2021EntryCredentialStatus extends ICredentialStatus {
@@ -135,6 +170,16 @@ export interface StatusListOAuthEntryCredentialStatus extends ICredentialStatus
   expiresAt?: Date
 }
 
+export interface BitstringStatusListEntryCredentialStatus extends ICredentialStatus {
+  type: 'BitstringStatusListEntry'
+  statusPurpose: BitstringStatusPurpose | BitstringStatusPurpose[]
+  statusListIndex: string
+  statusListCredential: string
+  bitsPerStatus?: number
+  statusMessage?: Array<BitstringStatus>
+  statusReference?: string | string[]
+}
+
 export interface StatusList2021ToVerifiableCredentialArgs {
   issuer: string | IIssuer
   id: string
@@ -154,12 +199,14 @@ export interface CreateStatusListArgs {
   length?: number
   statusList2021?: StatusList2021Args
   oauthStatusList?: OAuthStatusListArgs
+  bitstringStatusList?: BitstringStatusListArgs
 }
 
 export interface UpdateStatusListIndexArgs {
   statusListCredential: StatusListCredential // | CompactJWT
   statusListIndex: number | string
-  value: number | Status2021 | StatusOAuth
+  value: number | Status2021 | StatusOAuth | BitstringStatus
+  bitsPerStatus?: number
   keyRef?: string
   expiresAt?: Date
 }
@@ -167,12 +214,14 @@ export interface UpdateStatusListIndexArgs {
 export interface CheckStatusIndexArgs {
   statusListCredential: StatusListCredential // | CompactJWT
   statusListIndex: string | number
+  bitsPerStatus?: number
 }
 
 export interface ToStatusListDetailsArgs {
   statusListPayload: StatusListCredential
   correlationId?: string
   driverType?: StatusListDriverType
+  bitsPerStatus?: number
 }
 
 /**

package/src/utils.ts

@@ -11,7 +11,7 @@ import { jwtDecode } from 'jwt-decode'
 
 export function getAssertedStatusListType(type?: StatusListType) {
   const assertedType = type ?? StatusListType.StatusList2021
-  if (![StatusListType.StatusList2021, StatusListType.OAuthStatusList].includes(assertedType)) {
+  if (![StatusListType.StatusList2021, StatusListType.OAuthStatusList, StatusListType.BitstringStatusList].includes(assertedType)) {
     throw Error(`StatusList type ${assertedType} is not supported (yet)`)
   }
   return assertedType
@@ -39,8 +39,9 @@ export function getAssertedProperty<T extends object>(propertyName: string, obj:
 }
 
 const ValidProofTypeMap = new Map<StatusListType, CredentialProofFormat[]>([
-  [StatusListType.StatusList2021, ['jwt', 'lds', 'EthereumEip712Signature2021']],
+  [StatusListType.StatusList2021, ['jwt', 'lds']],
   [StatusListType.OAuthStatusList, ['jwt', 'cbor']],
+  [StatusListType.BitstringStatusList, ['lds']],
 ])
 
 export function assertValidProofType(type: StatusListType, proofFormat: CredentialProofFormat) {
@@ -93,3 +94,35 @@ export function determineProofFormat(credential: StatusListCredential): Credenti
       throw Error('Cannot determine credential payload type')
   }
 }
+
+/**
+ * Ensures a value is converted to a Date object if it's a valid date string,
+ * otherwise returns the original value or undefined
+ *
+ * @param value - The value to convert to Date (can be Date, string, or undefined)
+ * @returns Date object, undefined, or the original value if conversion fails
+ */
+export function ensureDate(value: Date | string | undefined): Date | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+
+  if (value instanceof Date) {
+    return value
+  }
+
+  if (typeof value === 'string') {
+    if (value.trim() === '') {
+      return undefined
+    }
+
+    const date = new Date(value)
+    // Check if the date is valid
+    if (isNaN(date.getTime())) {
+      return undefined
+    }
+    return date
+  }
+
+  return undefined
+}