@sphereon/ssi-sdk.vc-status-list 0.32.1-next.54 → 0.33.1-feature.jose.vcdm.55

package/src/impl/IStatusList.ts

@@ -0,0 +1,42 @@
+import type { IAgentContext, ICredentialPlugin } from '@veramo/core'
+import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
+import type {
+  CheckStatusIndexArgs,
+  CreateStatusListArgs,
+  Status2021,
+  StatusListResult,
+  StatusOAuth,
+  ToStatusListDetailsArgs,
+  UpdateStatusListFromEncodedListArgs,
+  UpdateStatusListIndexArgs,
+} from '../types'
+
+export interface IStatusList {
+  /**
+   * Creates a new status list of the specific type
+   */
+  createNewStatusList(args: CreateStatusListArgs, context: IAgentContext<ICredentialPlugin & IIdentifierResolution>): Promise<StatusListResult>
+
+  /**
+   * Updates a status at the given index in the status list
+   */
+  updateStatusListIndex(args: UpdateStatusListIndexArgs, context: IAgentContext<ICredentialPlugin & IIdentifierResolution>): Promise<StatusListResult>
+
+  /**
+   * Updates a status list using a base64 encoded list of statuses
+   */
+  updateStatusListFromEncodedList(
+    args: UpdateStatusListFromEncodedListArgs,
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListResult>
+
+  /**
+   * Checks the status at a given index in the status list
+   */
+  checkStatusIndex(args: CheckStatusIndexArgs): Promise<number | Status2021 | StatusOAuth>
+
+  /**
+   * Collects the status list details
+   */
+  toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult>
+}

package/src/impl/OAuthStatusList.ts

@@ -0,0 +1,206 @@
+import type { IAgentContext, ICredentialPlugin, IKeyManager } from '@veramo/core'
+import { type CompactJWT, type CWT, type CredentialProofFormat, StatusListType } from '@sphereon/ssi-types'
+import type {
+  CheckStatusIndexArgs,
+  CreateStatusListArgs,
+  SignedStatusListData,
+  StatusListResult,
+  StatusOAuth,
+  ToStatusListDetailsArgs,
+  UpdateStatusListFromEncodedListArgs,
+  UpdateStatusListIndexArgs,
+} from '../types'
+import { determineProofFormat, getAssertedValue, getAssertedValues } from '../utils'
+import type { 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'
+
+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_LIST_LENGTH = 250000
+export const DEFAULT_PROOF_FORMAT = 'jwt' as CredentialProofFormat
+
+export class OAuthStatusListImplementation implements IStatusList {
+  async createNewStatusList(args: CreateStatusListArgs, context: IRequiredContext): Promise<StatusListResult> {
+    if (!args.oauthStatusList) {
+      throw new Error('OAuthStatusList options are required for type OAuthStatusList')
+    }
+
+    const proofFormat = args?.proofFormat ?? DEFAULT_PROOF_FORMAT
+    const { issuer, id, oauthStatusList, keyRef } = args
+    const { bitsPerStatus, expiresAt } = oauthStatusList
+    const length = args.length ?? DEFAULT_LIST_LENGTH
+    const issuerString = typeof issuer === 'string' ? issuer : issuer.id
+    const correlationId = getAssertedValue('correlationId', args.correlationId)
+
+    const statusList = new StatusList(new Array(length).fill(0), bitsPerStatus ?? DEFAULT_BITS_PER_STATUS)
+    const encodedList = statusList.compressStatusList()
+    const { statusListCredential } = await this.createSignedStatusList(proofFormat, context, statusList, issuerString, id, expiresAt, keyRef)
+
+    return {
+      encodedList,
+      statusListCredential,
+      oauthStatusList: { bitsPerStatus },
+      length,
+      type: StatusListType.OAuthStatusList,
+      proofFormat,
+      id,
+      correlationId,
+      issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  async updateStatusListIndex(args: UpdateStatusListIndexArgs, context: IRequiredContext): Promise<StatusListResult> {
+    const { statusListCredential, value, expiresAt, keyRef } = args
+    if (typeof statusListCredential !== 'string') {
+      return Promise.reject('statusListCredential in neither JWT nor CWT')
+    }
+
+    const proofFormat = determineProofFormat(statusListCredential)
+    const decoded = proofFormat === 'jwt' ? decodeStatusListJWT(statusListCredential) : decodeStatusListCWT(statusListCredential)
+    const { statusList, issuer, id } = decoded
+
+    const index = typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex)
+    if (index < 0 || index >= statusList.statusList.length) {
+      throw new Error('Status list index out of bounds')
+    }
+
+    statusList.setStatus(index, value)
+    const { statusListCredential: signedCredential, encodedList } = await this.createSignedStatusList(
+      proofFormat,
+      context,
+      statusList,
+      issuer,
+      id,
+      expiresAt,
+      keyRef,
+    )
+
+    return {
+      statusListCredential: signedCredential,
+      encodedList,
+      oauthStatusList: {
+        bitsPerStatus: statusList.getBitsPerStatus(),
+      },
+      length: statusList.statusList.length,
+      type: StatusListType.OAuthStatusList,
+      proofFormat,
+      id,
+      issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  // FIXME: This still assumes only two values (boolean), whilst this list supports 8 bits max
+  async updateStatusListFromEncodedList(args: UpdateStatusListFromEncodedListArgs, context: IRequiredContext): Promise<StatusListResult> {
+    if (!args.oauthStatusList) {
+      throw new Error('OAuthStatusList options are required for type OAuthStatusList')
+    }
+    const { proofFormat, oauthStatusList, keyRef } = args
+    const { bitsPerStatus, expiresAt } = oauthStatusList
+
+    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)
+
+    const { statusListCredential, encodedList } = await this.createSignedStatusList(
+      proofFormat ?? DEFAULT_PROOF_FORMAT,
+      context,
+      listToUpdate,
+      issuerString,
+      id,
+      expiresAt,
+      keyRef,
+    )
+
+    return {
+      encodedList,
+      statusListCredential,
+      oauthStatusList: {
+        bitsPerStatus,
+        expiresAt,
+      },
+      length: listToUpdate.statusList.length,
+      type: StatusListType.OAuthStatusList,
+      proofFormat: proofFormat ?? DEFAULT_PROOF_FORMAT,
+      id,
+      issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  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') {
+      return Promise.reject('statusListCredential in neither JWT nor CWT')
+    }
+
+    const proofFormat = determineProofFormat(statusListCredential)
+    const { statusList } = proofFormat === 'jwt' ? decodeStatusListJWT(statusListCredential) : decodeStatusListCWT(statusListCredential)
+
+    const index = typeof statusListIndex === 'number' ? statusListIndex : parseInt(statusListIndex)
+    if (index < 0 || index >= statusList.statusList.length) {
+      throw new Error('Status list index out of bounds')
+    }
+
+    return statusList.getStatus(index)
+  }
+
+  async toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult> {
+    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
+
+    return {
+      id,
+      encodedList: statusList.compressStatusList(),
+      issuer,
+      type: StatusListType.OAuthStatusList,
+      proofFormat,
+      length: statusList.statusList.length,
+      statusListCredential: statusListPayload,
+      statuslistContentType: this.buildContentType(proofFormat),
+      oauthStatusList: {
+        bitsPerStatus: statusList.getBitsPerStatus(),
+        ...(exp && { expiresAt: new Date(exp * 1000) }),
+      },
+      ...(args.correlationId && { correlationId: args.correlationId }),
+      ...(args.driverType && { driverType: args.driverType }),
+    }
+  }
+
+  private async createSignedStatusList(
+    proofFormat: 'jwt' | 'lds' | 'EthereumEip712Signature2021' | 'cbor',
+    context: IAgentContext<ICredentialPlugin & IJwtService & IIdentifierResolution & IKeyManager>,
+    statusList: StatusList,
+    issuerString: string,
+    id: string,
+    expiresAt?: Date,
+    keyRef?: string,
+  ): Promise<SignedStatusListData> {
+    switch (proofFormat) {
+      case 'jwt': {
+        return await createSignedJwt(context, statusList, issuerString, id, expiresAt, keyRef)
+      }
+      case 'cbor': {
+        return await createSignedCbor(context, statusList, issuerString, id, expiresAt, keyRef)
+      }
+      default:
+        throw new Error(`Invalid proof format '${proofFormat}' for OAuthStatusList`)
+    }
+  }
+}

package/src/impl/StatusList2021.ts

@@ -0,0 +1,249 @@
+import type { IAgentContext, ICredentialPlugin, ProofFormat as VeramoProofFormat } from '@veramo/core'
+import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
+import {
+  CredentialMapper,
+  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 {
+  CheckStatusIndexArgs,
+  CreateStatusListArgs,
+  StatusListResult,
+  ToStatusListDetailsArgs,
+  UpdateStatusListFromEncodedListArgs,
+  UpdateStatusListIndexArgs,
+} from '../types'
+
+import { Status2021 } from '../types'
+import { assertValidProofType, getAssertedProperty, getAssertedValue, getAssertedValues } from '../utils'
+
+export const DEFAULT_LIST_LENGTH = 250000
+export const DEFAULT_PROOF_FORMAT = 'lds' as VeramoProofFormat
+
+export class StatusList2021Implementation implements IStatusList {
+  async createNewStatusList(
+    args: CreateStatusListArgs,
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListResult> {
+    const length = args?.length ?? DEFAULT_LIST_LENGTH
+    const proofFormat: CredentialProofFormat = args?.proofFormat ?? DEFAULT_PROOF_FORMAT
+    assertValidProofType(StatusListType.StatusList2021, proofFormat)
+    const veramoProofFormat: VeramoProofFormat = proofFormat as VeramoProofFormat
+
+    const { issuer, id } = args
+    const correlationId = getAssertedValue('correlationId', args.correlationId)
+
+    const list = new StatusList({ length })
+    const encodedList = await list.encode()
+    const statusPurpose = 'revocation'
+
+    const statusListCredential = await this.createVerifiableCredential(
+      {
+        ...args,
+        encodedList,
+        proofFormat: veramoProofFormat,
+      },
+      context,
+    )
+
+    return {
+      encodedList,
+      statusListCredential: statusListCredential,
+      statusList2021: {
+        statusPurpose,
+        indexingDirection: 'rightToLeft',
+      },
+      length,
+      type: StatusListType.StatusList2021,
+      proofFormat,
+      id,
+      correlationId,
+      issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  async updateStatusListIndex(
+    args: UpdateStatusListIndexArgs,
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListResult> {
+    const credential = args.statusListCredential
+    const uniform = CredentialMapper.toUniformCredential(credential)
+    const { issuer, credentialSubject } = uniform
+    const id = getAssertedValue('id', uniform.id)
+    const origEncodedList = getAssertedProperty('encodedList', credentialSubject)
+
+    const index = typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex)
+    const statusList = await StatusList.decode({ encodedList: origEncodedList })
+    statusList.setStatus(index, args.value != 0)
+    const encodedList = await statusList.encode()
+
+    const proofFormat = CredentialMapper.detectDocumentType(credential) === DocumentFormat.JWT ? 'jwt' : 'lds'
+    const updatedCredential = await this.createVerifiableCredential(
+      {
+        ...args,
+        id,
+        issuer,
+        encodedList,
+        proofFormat: proofFormat,
+      },
+      context,
+    )
+
+    return {
+      statusListCredential: updatedCredential,
+      encodedList,
+      statusList2021: {
+        ...('statusPurpose' in credentialSubject ? { statusPurpose: credentialSubject.statusPurpose } : {}),
+        indexingDirection: 'rightToLeft',
+      },
+      length: statusList.length - 1,
+      type: StatusListType.StatusList2021,
+      proofFormat: proofFormat,
+      id,
+      issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  async updateStatusListFromEncodedList(
+    args: UpdateStatusListFromEncodedListArgs,
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListResult> {
+    if (!args.statusList2021) {
+      throw new Error('statusList2021 options required for type StatusList2021')
+    }
+    const proofFormat: CredentialProofFormat = args?.proofFormat ?? DEFAULT_PROOF_FORMAT
+    assertValidProofType(StatusListType.StatusList2021, proofFormat)
+    const veramoProofFormat: VeramoProofFormat = proofFormat as VeramoProofFormat
+
+    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)
+
+    const newEncodedList = await statusList.encode()
+    const credential = await this.createVerifiableCredential(
+      {
+        id,
+        issuer,
+        encodedList: newEncodedList,
+        proofFormat: veramoProofFormat,
+        keyRef: args.keyRef,
+      },
+      context,
+    )
+
+    return {
+      type: StatusListType.StatusList2021,
+      statusListCredential: credential,
+      encodedList: newEncodedList,
+      statusList2021: {
+        statusPurpose: args.statusList2021.statusPurpose,
+        indexingDirection: 'rightToLeft',
+      },
+      length: statusList.length,
+      proofFormat: args.proofFormat ?? 'lds',
+      id: id,
+      issuer: issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  async checkStatusIndex(args: CheckStatusIndexArgs): Promise<number | Status2021> {
+    const uniform = CredentialMapper.toUniformCredential(args.statusListCredential)
+    const { credentialSubject } = uniform
+    const encodedList = getAssertedProperty('encodedList', credentialSubject)
+
+    const statusList = await StatusList.decode({ encodedList })
+    const status = statusList.getStatus(typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex))
+    return status ? Status2021.Invalid : Status2021.Valid
+  }
+
+  async toStatusListDetails(args: ToStatusListDetailsArgs): Promise<StatusListResult> {
+    const { statusListPayload } = args
+    const uniform = CredentialMapper.toUniformCredential(statusListPayload)
+    const { issuer, credentialSubject } = uniform
+    const id = getAssertedValue('id', uniform.id)
+    const encodedList = getAssertedProperty('encodedList', credentialSubject)
+    const proofFormat: CredentialProofFormat = CredentialMapper.detectDocumentType(statusListPayload) === DocumentFormat.JWT ? 'jwt' : 'lds'
+
+    const statusPurpose = getAssertedProperty('statusPurpose', credentialSubject)
+    const list = await StatusList.decode({ encodedList })
+
+    return {
+      id,
+      encodedList,
+      issuer,
+      type: StatusListType.StatusList2021,
+      proofFormat,
+      length: list.length,
+      statusListCredential: statusListPayload,
+      statuslistContentType: this.buildContentType(proofFormat),
+      statusList2021: {
+        indexingDirection: 'rightToLeft',
+        statusPurpose,
+      },
+      ...(args.correlationId && { correlationId: args.correlationId }),
+      ...(args.driverType && { driverType: args.driverType }),
+    }
+  }
+
+  private async createVerifiableCredential(
+    args: {
+      id: string
+      issuer: string | IIssuer
+      encodedList: string
+      proofFormat: VeramoProofFormat
+      keyRef?: string
+    },
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListCredential> {
+    const identifier = await context.agent.identifierManagedGet({
+      identifier: typeof args.issuer === 'string' ? args.issuer : args.issuer.id,
+      vmRelationship: 'assertionMethod',
+      offlineWhenNoDIDRegistered: true,
+    })
+
+    const credential = {
+      '@context': ['https://www.w3.org/2018/credentials/v1', 'https://w3id.org/vc/status-list/2021/v1'],
+      id: args.id,
+      issuer: args.issuer,
+      type: ['VerifiableCredential', 'StatusList2021Credential'],
+      credentialSubject: {
+        id: args.id,
+        type: 'StatusList2021',
+        statusPurpose: 'revocation',
+        encodedList: args.encodedList,
+      },
+    }
+
+    const verifiableCredential = await context.agent.createVerifiableCredential({
+      credential,
+      keyRef: args.keyRef ?? identifier.kmsKeyRef,
+      proofFormat: args.proofFormat,
+      fetchRemoteContexts: true,
+    })
+
+    return CredentialMapper.toWrappedVerifiableCredential(verifiableCredential as StatusListCredential).original as StatusListCredential
+  }
+
+  private buildContentType(proofFormat: 'jwt' | 'lds' | 'EthereumEip712Signature2021' | 'cbor' | undefined) {
+    switch (proofFormat) {
+      case 'jwt':
+        return `application/statuslist+jwt`
+      case 'cbor':
+        return `application/statuslist+cwt`
+      case 'lds':
+        return 'application/statuslist+ld+json'
+      default:
+        throw Error(`Unsupported content type '${proofFormat}' for status lists`)
+    }
+  }
+}

package/src/impl/StatusListFactory.ts

@@ -0,0 +1,34 @@
+import type { IStatusList } from './IStatusList'
+import { StatusList2021Implementation } from './StatusList2021'
+import { OAuthStatusListImplementation } from './OAuthStatusList'
+import { StatusListType } from '@sphereon/ssi-types'
+
+export class StatusListFactory {
+  private static instance: StatusListFactory
+  private implementations: Map<StatusListType, IStatusList>
+
+  private constructor() {
+    this.implementations = new Map()
+    this.implementations.set(StatusListType.StatusList2021, new StatusList2021Implementation())
+    this.implementations.set(StatusListType.OAuthStatusList, new OAuthStatusListImplementation())
+  }
+
+  public static getInstance(): StatusListFactory {
+    if (!StatusListFactory.instance) {
+      StatusListFactory.instance = new StatusListFactory()
+    }
+    return StatusListFactory.instance
+  }
+
+  public getByType(type: StatusListType): IStatusList {
+    const statusList = this.implementations.get(type)
+    if (!statusList) {
+      throw new Error(`No implementation found for status list type: ${type}`)
+    }
+    return statusList
+  }
+}
+
+export function getStatusListImplementation(type: StatusListType): IStatusList {
+  return StatusListFactory.getInstance().getByType(type)
+}