@sphereon/ssi-sdk.vc-status-list/src/types/index.ts

Sphereon SSI-SDK plugin for Status List management, like StatusList2021.

import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
import {
  type CredentialProofFormat,
  type ICredential,
  type ICredentialStatus,
  type IIssuer,
  type IVerifiableCredential,
  type OrPromise,
  type StatusListCredential,
  StatusListCredentialIdMode,
  StatusListDriverType,
  type StatusListIndexingDirection,
  StatusListType,
  type StatusPurpose2021,
} from '@sphereon/ssi-types'
import type { CredentialPayload, IAgentContext, ICredentialIssuer, ICredentialVerifier, IKeyManager, IPluginMethodMap } from '@veramo/core'
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'
import { IVcdmCredentialPlugin } from '@sphereon/ssi-sdk.credential-vcdm'
import { IExtractedCredentialDetails } from '../impl/IStatusList'
import { BitstringStatusListArgs, IStatusListEntity } from '@sphereon/ssi-sdk.data-store'

export enum StatusOAuth {
  Valid = 0,
  Invalid = 1,
  Suspended = 2,
}

export enum Status2021 {
  Valid = 0,
  Invalid = 1,
}

export type StatusList2021Args = {
  indexingDirection: StatusListIndexingDirection
  statusPurpose?: StatusPurpose2021
  // todo: validFrom and validUntil
}

export type OAuthStatusListArgs = {
  bitsPerStatus: BitsPerStatus
  expiresAt?: Date
}

export type BaseCreateNewStatusListArgs = {
  type: StatusListType
  id: string
  issuer: string | IIssuer
  correlationId?: string
  length?: number
  proofFormat?: CredentialProofFormat
  keyRef?: string
  statusList2021?: StatusList2021Args
  oauthStatusList?: OAuthStatusListArgs
  bitstringStatusList?: BitstringStatusListArgs
  driverType?: StatusListDriverType
}

export type UpdateStatusList2021Args = {
  statusPurpose: StatusPurpose2021
}

export type UpdateOAuthStatusListArgs = {
  bitsPerStatus: BitsPerStatus
  expiresAt?: Date
}

export type UpdateBitstringStatusListArgs = {
  statusPurpose: BitstringStatusPurpose
  bitsPerStatus: number
  validFrom?: Date
  validUntil?: Date
  ttl?: number
}

export interface UpdateStatusListFromEncodedListArgs {
  type?: StatusListType
  statusListIndex: number | string
  value: number
  proofFormat?: CredentialProofFormat
  keyRef?: string
  correlationId?: string
  encodedList: string
  issuer: string | IIssuer
  id: string
  statusList2021?: UpdateStatusList2021Args
  oauthStatusList?: UpdateOAuthStatusListArgs
  bitstringStatusList?: UpdateBitstringStatusListArgs
}

export interface UpdateStatusListFromStatusListCredentialArgs {
  statusListCredential: StatusListCredential // | CompactJWT
  keyRef?: string
  statusListIndex: number | string
  value: number | Status2021 | StatusOAuth
}

export interface StatusListResult {
  id: string
  encodedList: string
  issuer: string | IIssuer
  type: StatusListType
  proofFormat: CredentialProofFormat
  length: number
  statusListCredential: StatusListCredential
  statuslistContentType: string
  correlationId?: string
  driverType?: StatusListDriverType

  statusList2021?: {
    indexingDirection: StatusListIndexingDirection
    statusPurpose: StatusPurpose2021
    credentialIdMode: StatusListCredentialIdMode
  }
  oauthStatusList?: {
    bitsPerStatus: number
    expiresAt?: Date
  }
  bitstringStatusList?: {
    statusPurpose: BitstringStatusPurpose | BitstringStatusPurpose[]
    bitsPerStatus?: number
    validFrom?: Date
    validUntil?: Date
    ttl?: number
  }
}

export interface StatusList2021EntryCredentialStatus extends ICredentialStatus {
  type: 'StatusList2021Entry'
  statusPurpose: StatusPurpose2021
  statusListIndex: string
  statusListCredential: string
}

export interface StatusListOAuthEntryCredentialStatus extends ICredentialStatus {
  type: 'OAuthStatusListEntry'
  bitsPerStatus: number
  statusListIndex: string
  statusListCredential: string
  expiresAt?: Date
}

export interface StatusList2021ToVerifiableCredentialArgs {
  issuer: string | IIssuer
  id: string
  type?: StatusListType
  proofFormat?: CredentialProofFormat
  keyRef?: string
  encodedList: string
  statusPurpose: StatusPurpose2021
}

export interface CreateStatusListArgs {
  issuer: string | IIssuer
  id: string
  proofFormat?: CredentialProofFormat
  keyRef?: string
  correlationId?: string
  length?: number
  statusList2021?: StatusList2021Args
  oauthStatusList?: OAuthStatusListArgs
  bitstringStatusList?: BitstringStatusListArgs
}

export interface UpdateStatusListIndexArgs {
  statusListCredential: StatusListCredential // | CompactJWT
  statusListIndex: number | string
  value: number | Status2021 | StatusOAuth
  bitsPerStatus?: number
  keyRef?: string
  expiresAt?: Date
}

export interface CheckStatusIndexArgs {
  statusListCredential: StatusListCredential // | CompactJWT
  statusListIndex: string | number
  bitsPerStatus?: number
}

// For the CREATE and READ contexts
export interface IToDetailsFromCredentialArgs {
  // The source credential we are converting
  statusListCredential: StatusListCredential

  // The required metadata that is NOT in the credential itself
  statusListType: StatusListType
  bitsPerStatus?: number
  correlationId?: string
  driverType?: StatusListDriverType
}

// For the UPDATE context
export interface IMergeDetailsWithEntityArgs {
  extractedDetails: IExtractedCredentialDetails
  statusListEntity: IStatusListEntity
}

/**
 * The interface definition for a plugin that can add statuslist info to a credential
 *
 * @remarks Please see {@link https://www.w3.org/TR/vc-data-model | W3C Verifiable Credentials data model}
 *
 * @beta This API is likely to change without a BREAKING CHANGE notice
 */
export interface IStatusListPlugin extends IPluginMethodMap {
  /**
   * Create a new status list
   *
   * @param args Status list information like type and size
   * @param context - This reserved param is automatically added and handled by the framework, *do not override*
   *
   * @returns - The details of the newly created status list
   */
  slCreateStatusList(args: CreateNewStatusListArgs, context: IRequiredContext): Promise<StatusListResult>

  /**
   * Ensures status list info like index and list id is added to a credential
   *
   * @param args - Arguments necessary to add the statuslist info.
   * @param context - This reserved param is automatically added and handled by the framework, *do not override*
   *
   * @returns - a promise that resolves to the credential now with status support
   *
   * @beta This API is likely to change without a BREAKING CHANGE notice
   */
  slAddStatusToCredential(args: IAddStatusToCredentialArgs, context: IRequiredContext): Promise<CredentialWithStatusSupport>

  slAddStatusToSdJwtCredential(args: IAddStatusToSdJwtCredentialArgs, context: IRequiredContext): Promise<SdJwtVcPayload>

  /**
   * Get the status list using the configured driver for the SL. Normally a correlationId or id should suffice. Optionally accepts a dbName/datasource
   * @param args
   * @param context
   */
  slGetStatusList(args: GetStatusListArgs, context: IRequiredContext): Promise<StatusListResult>

  /**
   * Import status lists when noy yet present
   *
   * @param imports Array of status list information like type and size
   * @param context - This reserved param is automatically added and handled by the framework, *do not override*
   */
  slImportStatusLists(imports: Array<CreateNewStatusListArgs>, context: IRequiredContext): Promise<boolean>
}

export type CreateNewStatusListFuncArgs = BaseCreateNewStatusListArgs

export type CreateNewStatusListArgs = BaseCreateNewStatusListArgs & {
  dbName?: string
  dataSource?: OrPromise<DataSource>
  isDefault?: boolean
}

export type IAddStatusToCredentialArgs = Omit<IIssueCredentialStatusOpts, 'dataSource'> & {
  credential: CredentialWithStatusSupport
}

export type IAddStatusToSdJwtCredentialArgs = Omit<IIssueCredentialStatusOpts, 'dataSource'> & {
  credential: SdJwtVcPayload
}

export interface IIssueCredentialStatusOpts {
  dataSource?: DataSource
  statusLists?: Array<StatusListOpts>
  credentialId?: string // An id to use for the credential. Normally should be set as the crdential.id value
  value?: string
}

export type GetStatusListArgs = {
  id?: string
  correlationId?: string
  dataSource?: OrPromise<DataSource>
  dbName?: string
}

export type CredentialWithStatusSupport = ICredential | CredentialPayload | IVerifiableCredential

export type SignedStatusListData = {
  statusListCredential: StatusListCredential
  encodedList: string
}

export type IRequiredPlugins = IVcdmCredentialPlugin & IIdentifierResolution
export type IRequiredContext = IAgentContext<ICredentialIssuer & ICredentialVerifier & IIdentifierResolution & IKeyManager & IVcdmCredentialPlugin>