@sphereon/ssi-sdk.data-store 0.19.1-next.2 → 0.19.1-unstable.63

package/src/migrations/postgres/1708797018115-CreateXStateStore.ts

@@ -0,0 +1,29 @@
+import { enablePostgresUuidExtension } from '@sphereon/ssi-sdk.core'
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class CreateXStateStore1708797018115 implements MigrationInterface {
+  name = 'CreateXStateStore1708797018115'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await enablePostgresUuidExtension(queryRunner)
+    await queryRunner.query(`
+            CREATE TABLE "StateEntity" (
+                "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+                "state_name" character varying NOT NULL,
+                "machine_type" character varying NOT NULL,
+                "xstate_event_type" character varying NOT NULL,
+                "state" text NOT NULL,
+                "created_at" TIMESTAMP NOT NULL DEFAULT now(),
+                "updated_at" TIMESTAMP NOT NULL DEFAULT now(),
+                "expires_at" TIMESTAMP,
+                "completed_at" TIMESTAMP,
+                "tenant_id" character varying,
+                CONSTRAINT "PK_StateEntity_id" PRIMARY KEY ("id")
+            )
+        `)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "StateEntity"`)
+  }
+}

package/src/migrations/sqlite/1708525189002-CreateDigitalCredential.ts

@@ -0,0 +1,34 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class CreateDigitalCredential1708525189002 implements MigrationInterface {
+  name = 'CreateDigitalCredential1708525189002'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+            CREATE TABLE "DigitalCredential" (
+                "id" varchar PRIMARY KEY NOT NULL,
+                "document_type" varchar CHECK( "document_type" IN ('VC', 'VP', 'C', 'P') ) NOT NULL,
+                "document_format" varchar CHECK( "document_format" IN ('JSON_LD', 'JWT', 'SD_JWT', 'MDOC') ) NOT NULL,
+                "raw_document" text NOT NULL,
+                "uniform_document" text NOT NULL,
+                "hash" text NOT NULL UNIQUE,
+                "issuer_correlation_type" varchar CHECK( "issuer_correlation_type" IN ('DID') ) NOT NULL,
+                "subject_correlation_type" varchar CHECK( "subject_correlation_type" IN ('DID') ),
+                "issuer_correlation_id" text NOT NULL,
+                "subject_correlation_id" text,
+                "verified_state" varchar CHECK( "verified_state" IN ('REVOKED', 'VERIFIED', 'EXPIRED') ),
+                "tenant_id" text,
+                "created_at" datetime NOT NULL DEFAULT (datetime('now')),
+                "last_updated_at" datetime NOT NULL DEFAULT (datetime('now')),
+                "valid_from" datetime,
+                "valid_until" datetime,
+                "verified_at" datetime,
+                "revoked_at" datetime
+            )
+        `)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "DigitalCredential"`)
+  }
+}

package/src/migrations/sqlite/1708796002272-CreateXStateStore.ts

@@ -0,0 +1,26 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+export class CreateXStateStore1708796002272 implements MigrationInterface {
+  name = 'CreateXStateStore1708796002272'
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+            CREATE TABLE "StateEntity" (
+                "id" varchar PRIMARY KEY NOT NULL,
+                "state_name" varchar NOT NULL,
+                "machine_type" varchar NOT NULL,
+                "xstate_event_type" varchar NOT NULL,
+                "state" text NOT NULL,
+                "created_at" datetime NOT NULL DEFAULT (datetime('now')),
+                "updated_at" datetime NOT NULL DEFAULT (datetime('now')),
+                "expires_at" datetime,
+                "completed_at" datetime,
+                "tenant_id" varchar
+            )
+        `)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "StateEntity"`)
+  }
+}

package/src/types/digitalCredential/IAbstractDigitalCredentialStore.ts

@@ -0,0 +1,37 @@
+import { CredentialCorrelationType, CredentialStateType, DigitalCredential } from './digitalCredential'
+import { Hasher } from '@sphereon/ssi-types'
+import { FindOptionsOrder } from 'typeorm'
+import { DigitalCredentialEntity } from '../../entities/digitalCredential/DigitalCredentialEntity'
+
+export type GetCredentialArgs = { id: string } | { hash: string }
+
+export type FindDigitalCredentialArgs = Array<Partial<DigitalCredential>>
+
+export type GetCredentialsArgs = {
+  filter?: FindDigitalCredentialArgs
+  offset?: number
+  limit?: number
+  order?: string | FindOptionsOrder<DigitalCredentialEntity>
+}
+
+export type GetCredentialsResponse = {
+  data: Array<DigitalCredential>
+  total: number
+}
+
+export type AddCredentialArgs = {
+  rawDocument: string
+  issuerCorrelationType: CredentialCorrelationType
+  subjectCorrelationType?: CredentialCorrelationType
+  issuerCorrelationId: string
+  subjectCorrelationId?: string
+  tenantId?: string
+  state?: CredentialStateType
+  verifiedAt?: Date
+  revokedAt?: Date
+  opts?: { maxTimeSkewInMS?: number; hasher?: Hasher }
+}
+
+export type UpdateCredentialStateArgs = GetCredentialArgs & { verifiedState: CredentialStateType; verifiedAt?: Date; revokedAt?: Date }
+
+export type RemoveCredentialArgs = GetCredentialArgs

package/src/types/digitalCredential/digitalCredential.ts

@@ -0,0 +1,46 @@
+export type NonPersistedDigitalCredential = Omit<DigitalCredential, 'id'>
+
+export type DigitalCredential = {
+  id: string
+  documentType: DocumentType
+  documentFormat: CredentialDocumentFormat
+  rawDocument: string
+  uniformDocument: string
+  hash: string
+  issuerCorrelationType: CredentialCorrelationType
+  subjectCorrelationType?: CredentialCorrelationType
+  issuerCorrelationId: string
+  subjectCorrelationId?: string
+  verifiedState?: CredentialStateType
+  tenantId?: string
+  createdAt: Date
+  lastUpdatedAt: Date
+  validUntil?: Date
+  validFrom?: Date
+  verifiedAt?: Date
+  revokedAt?: Date
+}
+
+export enum DocumentType {
+  VC = 'VC',
+  VP = 'VP',
+  P = 'P',
+  C = 'C',
+}
+
+export enum CredentialDocumentFormat {
+  JSON_LD = 'JSON_LD',
+  JWT = 'JWT',
+  SD_JWT = 'SD_JWT',
+  MDOC = 'MDOC',
+}
+
+export enum CredentialCorrelationType {
+  DID = 'DID',
+}
+
+export enum CredentialStateType {
+  REVOKED = 'REVOKED',
+  VERIFIED = 'VERIFIED',
+  EXPIRED = 'EXPIRED',
+}

package/src/types/index.ts

@@ -7,3 +7,4 @@ export * from './statusList/statusList'
 export * from './statusList/IAbstractStatusListStore'
 export * from './eventLogger/IAbstractEventLoggerStore'
 export * from './eventLogger/eventLogger'
+export * from './xstate/IAbstractXStateStore'

package/src/types/xstate/IAbstractXStateStore.ts

@@ -0,0 +1,39 @@
+export type SaveStateArgs = Omit<State, 'id' | 'createdAt' | 'updatedAt'>
+
+export type GetActiveStateArgs = Pick<State, 'machineType' | 'tenantId'>
+
+export type FindStatesArgs = Array<Partial<Omit<State, 'state'>>>
+
+export type GetStatesArgs = {
+  filter: FindStatesArgs
+}
+
+export type NonPersistedXStateStoreEvent = SaveStateArgs
+
+export type DeleteStateArgs = { id: string }
+export type DeleteExpiredStateArgs = { machineType?: string }
+
+export type State = {
+  id: string
+  /**
+   * value of the state's name. top level of event type. examples: acceptAgreement, enterPersonalDetails
+   */
+  stateName: string
+  /**
+   * Machine type/id
+   */
+  machineType: string
+  /**
+   * event types like SET_TOC, SET_FIRSTNAME, ...
+   */
+  xStateEventType: string
+  /**
+   * state of the machine in this snapshot
+   */
+  state: unknown
+  createdAt: Date
+  expiresAt?: Date
+  updatedAt: Date
+  completedAt?: Date
+  tenantId?: string
+}

package/src/utils/SortingUtils.ts

@@ -0,0 +1,16 @@
+import { BaseEntity, FindOptionsOrder } from 'typeorm'
+
+export const parseAndValidateOrderOptions = <T extends BaseEntity>(order: string): FindOptionsOrder<T> => {
+  const orderPairs = order.split(',').map((pair) => pair.trim().split('.'))
+  const orderOptions: FindOptionsOrder<T> = {}
+
+  orderPairs.forEach(([field, direction]) => {
+    const dir = direction.toUpperCase()
+    if (dir !== 'ASC' && dir !== 'DESC') {
+      throw new Error(`Invalid order direction: '${direction}'. Must be 'asc' or 'desc'.`)
+    }
+    ;(orderOptions as any)[field] = dir
+  })
+
+  return orderOptions
+}

package/src/utils/digitalCredential/MappingUtils.ts

@@ -0,0 +1,122 @@
+import { AddCredentialArgs } from '../../types/digitalCredential/IAbstractDigitalCredentialStore'
+import { DigitalCredentialEntity } from '../../entities/digitalCredential/DigitalCredentialEntity'
+import {
+  CredentialMapper,
+  decodeSdJwtVc,
+  DocumentFormat,
+  IVerifiableCredential,
+  IVerifiablePresentation,
+  OriginalVerifiableCredential,
+  OriginalVerifiablePresentation,
+  SdJwtDecodedVerifiableCredentialPayload,
+} from '@sphereon/ssi-types'
+import {
+  CredentialDocumentFormat,
+  DocumentType,
+  DigitalCredential,
+  NonPersistedDigitalCredential,
+} from '../../types/digitalCredential/digitalCredential'
+import { computeEntryHash } from '@veramo/utils'
+
+function determineDocumentType(raw: string): DocumentType {
+  const rawDocument = parseRawDocument(raw)
+  if (!rawDocument) {
+    throw new Error(`Couldn't parse the credential: ${raw}`)
+  }
+
+  const hasProof = CredentialMapper.hasProof(rawDocument)
+  const isCredential = CredentialMapper.isCredential(rawDocument)
+  const isPresentation = CredentialMapper.isPresentation(rawDocument)
+
+  if (isCredential) {
+    return hasProof ? DocumentType.VC : DocumentType.C
+  } else if (isPresentation) {
+    return hasProof ? DocumentType.VP : DocumentType.P
+  }
+  throw new Error(`Couldn't determine the type of the credential: ${raw}`)
+}
+
+function parseRawDocument(raw: string): OriginalVerifiableCredential | OriginalVerifiablePresentation {
+  if (CredentialMapper.isJwtEncoded(raw) || CredentialMapper.isSdJwtEncoded(raw)) {
+    return raw
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    throw new Error(`Can't parse the raw credential: ${raw}`)
+  }
+}
+
+function determineCredentialDocumentFormat(documentFormat: DocumentFormat): CredentialDocumentFormat {
+  switch (documentFormat) {
+    case DocumentFormat.JSONLD:
+      return CredentialDocumentFormat.JSON_LD
+    case DocumentFormat.JWT:
+      return CredentialDocumentFormat.JWT
+    case DocumentFormat.SD_JWT_VC:
+      return CredentialDocumentFormat.SD_JWT
+    default:
+      throw new Error(`Not supported document format: ${documentFormat}`)
+  }
+}
+
+function getValidUntil(uniformDocument: IVerifiableCredential | IVerifiablePresentation | SdJwtDecodedVerifiableCredentialPayload): Date | undefined {
+  if ('expirationDate' in uniformDocument) {
+    return new Date(uniformDocument.expirationDate)
+  } else if ('validUntil' in uniformDocument) {
+    return new Date(uniformDocument.validUntil)
+  } else if ('exp' in uniformDocument) {
+    return new Date(uniformDocument.exp)
+  }
+  return undefined
+}
+
+function getValidFrom(uniformDocument: IVerifiableCredential | IVerifiablePresentation | SdJwtDecodedVerifiableCredentialPayload): Date | undefined {
+  if ('issuanceDate' in uniformDocument) {
+    return new Date(uniformDocument.issuanceDate)
+  } else if ('validFrom' in uniformDocument) {
+    return new Date(uniformDocument['validFrom'])
+  } else if ('nbf' in uniformDocument) {
+    return new Date(uniformDocument['nbf'] * 1000)
+  } else if ('iat' in uniformDocument) {
+    return new Date(uniformDocument['iat'] * 1000)
+  }
+  return undefined
+}
+
+export const nonPersistedDigitalCredentialEntityFromAddArgs = (addCredentialArgs: AddCredentialArgs): NonPersistedDigitalCredential => {
+  const documentType: DocumentType = determineDocumentType(addCredentialArgs.rawDocument)
+  const documentFormat: DocumentFormat = CredentialMapper.detectDocumentType(addCredentialArgs.rawDocument)
+  if (documentFormat === DocumentFormat.SD_JWT_VC && !addCredentialArgs.opts?.hasher) {
+    throw new Error('No hasher function is provided for SD_JWT credential.')
+  }
+  const uniformDocument =
+    documentFormat === DocumentFormat.SD_JWT_VC
+      ? decodeSdJwtVc(addCredentialArgs.rawDocument, addCredentialArgs.opts!.hasher!).decodedPayload
+      : documentType === DocumentType.VC || documentType === DocumentType.C
+      ? CredentialMapper.toUniformCredential(addCredentialArgs.rawDocument)
+      : CredentialMapper.toUniformPresentation(addCredentialArgs.rawDocument)
+  const validFrom: Date | undefined = getValidFrom(uniformDocument)
+  const validUntil: Date | undefined = getValidUntil(uniformDocument)
+  return {
+    ...addCredentialArgs,
+    documentType,
+    documentFormat: determineCredentialDocumentFormat(documentFormat),
+    createdAt: new Date(),
+    hash: computeEntryHash(addCredentialArgs.rawDocument),
+    uniformDocument: JSON.stringify(uniformDocument),
+    validFrom,
+    validUntil,
+    lastUpdatedAt: new Date(),
+  }
+}
+
+export const digitalCredentialFrom = (credentialEntity: DigitalCredentialEntity): DigitalCredential => {
+  return {
+    ...credentialEntity,
+  }
+}
+
+export const digitalCredentialsFrom = (credentialEntities: Array<DigitalCredentialEntity>): DigitalCredential[] => {
+  return credentialEntities.map((credentialEntity) => digitalCredentialFrom(credentialEntity))
+}

package/src/xstate/IAbstractXStateStore.ts

@@ -0,0 +1,9 @@
+import { DeleteExpiredStateArgs, DeleteStateArgs, GetActiveStateArgs, GetStatesArgs, SaveStateArgs, State } from '../types'
+
+export abstract class IAbstractXStateStore {
+  abstract saveState(state: SaveStateArgs): Promise<State>
+  abstract getActiveState(args: GetActiveStateArgs): Promise<State>
+  abstract getStates(args?: GetStatesArgs): Promise<Array<State>>
+  abstract deleteState(args: DeleteStateArgs): Promise<boolean>
+  abstract deleteExpiredStates(args: DeleteExpiredStateArgs): Promise<boolean>
+}

package/src/xstate/XStateStore.ts

@@ -0,0 +1,107 @@
+import { OrPromise } from '@sphereon/ssi-types'
+import Debug from 'debug'
+import { Brackets, DataSource, FindOptionsWhere, LessThan } from 'typeorm'
+
+import { StateEntity } from '../entities/xstate/StateEntity'
+import { DeleteExpiredStateArgs, DeleteStateArgs, GetActiveStateArgs, GetStatesArgs, SaveStateArgs, State } from '../types'
+import { IAbstractXStateStore } from './IAbstractXStateStore'
+
+const debug = Debug('sphereon:ssi-sdk:xstate')
+
+export class XStateStore extends IAbstractXStateStore {
+  private readonly dbConnection: OrPromise<DataSource>
+
+  constructor(dbConnection: OrPromise<DataSource>) {
+    super()
+    this.dbConnection = dbConnection
+  }
+
+  async saveState(state: SaveStateArgs): Promise<State> {
+    const connection: DataSource = await this.dbConnection
+    debug(`Executing saveState with state: ${JSON.stringify(state)}`)
+    return connection.getRepository(StateEntity).save(XStateStore.stateEntityFrom(state))
+  }
+
+  async getActiveState(args: GetActiveStateArgs): Promise<State> {
+    const { tenantId, machineType } = args
+    const connection: DataSource = await this.dbConnection
+    debug(`Executing getActiveState query with machineType: ${machineType}, tenantId: ${tenantId}`)
+
+    const queryBuilder = connection
+      .getRepository(StateEntity)
+      .createQueryBuilder('state')
+      .where('state.completedAt IS NULL')
+      .andWhere(
+        new Brackets((qb) => {
+          qb.where('state.expiresAt IS NULL').orWhere('state.expiresAt > :now', { now: new Date() })
+        })
+      )
+      .orderBy('state.updatedAt', 'DESC')
+
+    if (tenantId) {
+      queryBuilder.andWhere('state.tenantId = :tenantId', { tenantId })
+    }
+    if (machineType) {
+      queryBuilder.andWhere('state.machineType = :machineType', { machineType })
+    }
+
+    const result = await queryBuilder.getOne()
+
+    if (!result) {
+      throw new Error(`No active state found for machineType: ${machineType}, tenantId: ${tenantId}`)
+    }
+    return XStateStore.stateFrom(result)
+  }
+
+  async getStates(args?: GetStatesArgs): Promise<Array<State>> {
+    const connection: DataSource = await this.dbConnection
+    debug('Getting states', args)
+    const result: Array<StateEntity> = await connection.getRepository(StateEntity).find({
+      ...(args?.filter && { where: args?.filter }),
+    })
+
+    return result.map((event: StateEntity) => XStateStore.stateFrom(event))
+  }
+
+  async deleteState(args: DeleteStateArgs): Promise<boolean> {
+    if (!args.id) {
+      throw new Error('No id parameter is provided.')
+    }
+    try {
+      const connection: DataSource = await this.dbConnection
+      debug(`Executing deleteState query with id: ${args.id}`)
+      const result = await connection.getRepository(StateEntity).delete(args.id)
+      return result.affected != null && result.affected > 0
+    } catch (error) {
+      debug(`Error deleting state: ${error}`)
+      return false
+    }
+  }
+
+  async deleteExpiredStates(args: DeleteExpiredStateArgs): Promise<boolean> {
+    try {
+      const connection: DataSource = await this.dbConnection
+      debug(`Executing deleteExpiredStates query with params: ${JSON.stringify(args)}`)
+      const deleteCriteria: FindOptionsWhere<StateEntity> = { expiresAt: LessThan(new Date()), ...(args.machineType && { type: args.machineType }) }
+      const result = await connection.getRepository(StateEntity).delete(deleteCriteria)
+      return result.affected != null && result.affected > 0
+    } catch (error) {
+      debug(`Error deleting state: ${error}`)
+      return false
+    }
+  }
+
+  public static stateFrom = (stateEntity: StateEntity): State => {
+    return {
+      ...stateEntity,
+      state: JSON.parse(stateEntity.state),
+    }
+  }
+
+  public static stateEntityFrom = (state: State | SaveStateArgs): StateEntity => {
+    const entity = new StateEntity()
+    Object.assign(entity, state)
+    entity.state = JSON.stringify(state.state)
+    return entity
+  }
+}