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

package/src/impl/BitstringStatusListImplementation.ts

@@ -0,0 +1,334 @@
+import type { IAgentContext, ICredentialPlugin, ProofFormat as VeramoProofFormat } from '@veramo/core'
+import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
+import {
+  type BitstringStatusPurpose,
+  CredentialMapper,
+  type CredentialProofFormat,
+  DocumentFormat,
+  type IIssuer,
+  type StatusListCredential,
+  StatusListType,
+} from '@sphereon/ssi-types'
+
+import type { IStatusList } from './IStatusList'
+import {
+  BitstringStatus,
+  BitstringStatusResult,
+  CheckStatusIndexArgs,
+  CreateStatusListArgs,
+  StatusListResult,
+  ToStatusListDetailsArgs,
+  UpdateStatusListFromEncodedListArgs,
+  UpdateStatusListIndexArgs,
+} from '../types'
+
+import { assertValidProofType, getAssertedProperty, getAssertedValue, getAssertedValues } from '../utils'
+import { createList, decodeList } from '@digitalbazaar/vc-bitstring-status-list'
+import { IBitstringStatusList } from '../types/BitstringStatusList'
+
+export const DEFAULT_LIST_LENGTH = 131072 // W3C spec minimum
+export const DEFAULT_PROOF_FORMAT = 'lds' as CredentialProofFormat
+export const DEFAULT_STATUS_SIZE = 1
+export const DEFAULT_STATUS_PURPOSE: BitstringStatusPurpose = 'revocation'
+
+export class BitstringStatusListImplementation implements IStatusList {
+  async createNewStatusList(
+    args: CreateStatusListArgs,
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListResult> {
+    if (!args.bitstringStatusList) {
+      throw new Error('BitstringStatusList options are required for type BitstringStatusList')
+    }
+
+    const length = args?.length ?? DEFAULT_LIST_LENGTH
+    const proofFormat: CredentialProofFormat = args?.proofFormat ?? DEFAULT_PROOF_FORMAT
+    assertValidProofType(StatusListType.BitstringStatusList, proofFormat)
+    const veramoProofFormat: VeramoProofFormat = proofFormat as VeramoProofFormat
+
+    const { issuer, id } = args
+    const correlationId = getAssertedValue('correlationId', args.correlationId)
+    const { statusPurpose, statusSize, statusMessage, ttl } = args.bitstringStatusList
+    const list = (await createList({ length })) as IBitstringStatusList
+    const encodedList = await list.encode()
+
+    const statusListCredential = await this.createVerifiableCredential(
+      {
+        ...args,
+        encodedList,
+        proofFormat: veramoProofFormat,
+        statusPurpose: statusPurpose ?? DEFAULT_STATUS_PURPOSE,
+        statusSize: statusSize ?? DEFAULT_STATUS_SIZE,
+        statusMessage: statusMessage,
+        ttl,
+      },
+      context,
+    )
+
+    return {
+      encodedList,
+      statusListCredential: statusListCredential,
+      bitstringStatusList: {
+        statusPurpose: statusPurpose ?? DEFAULT_STATUS_PURPOSE,
+        ttl,
+      },
+      length,
+      type: StatusListType.BitstringStatusList,
+      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 decodeList({ encodedList: origEncodedList })) as IBitstringStatusList
+    statusList.setStatus(index, args.value != 0)
+    const encodedList = await statusList.encode()
+
+    const proofFormat = CredentialMapper.detectDocumentType(credential) === DocumentFormat.JWT ? 'jwt' : 'lds'
+
+    const credSubject = Array.isArray(credentialSubject) ? credentialSubject[0] : credentialSubject
+
+    const statusPurpose = getAssertedProperty('statusPurpose', credSubject)
+
+    const validFrom = uniform.validFrom ? new Date(uniform.validFrom) : undefined
+    const validUntil = uniform.validUntil ? new Date(uniform.validUntil) : undefined
+    const ttl = credSubject.ttl
+
+    const updatedCredential = await this.createVerifiableCredential(
+      {
+        ...args,
+        id,
+        issuer,
+        encodedList,
+        proofFormat: proofFormat,
+        statusPurpose,
+        ttl,
+        validFrom,
+        validUntil,
+      },
+      context,
+    )
+
+    return {
+      statusListCredential: updatedCredential,
+      encodedList,
+      bitstringStatusList: {
+        statusPurpose,
+        validFrom,
+        validUntil,
+        ttl,
+      },
+      length: statusList.length - 1,
+      type: StatusListType.BitstringStatusList,
+      proofFormat: proofFormat,
+      id,
+      issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  async updateStatusListFromEncodedList(
+    args: UpdateStatusListFromEncodedListArgs,
+    context: IAgentContext<ICredentialPlugin & IIdentifierResolution>,
+  ): Promise<StatusListResult> {
+    if (!args.bitstringStatusList) {
+      throw new Error('bitstringStatusList options required for type BitstringStatusList')
+    }
+    const proofFormat: CredentialProofFormat = args?.proofFormat ?? DEFAULT_PROOF_FORMAT
+    assertValidProofType(StatusListType.BitstringStatusList, proofFormat)
+    const veramoProofFormat: VeramoProofFormat = proofFormat as VeramoProofFormat
+
+    const { issuer, id } = getAssertedValues(args)
+    const statusList = (await decodeList({ encodedList: args.encodedList })) as IBitstringStatusList
+    const index = typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex)
+    statusList.setStatus(index, args.value)
+
+    const newEncodedList = await statusList.encode()
+    const { statusPurpose, statusSize, statusMessage, ttl, validFrom, validUntil } = args.bitstringStatusList
+
+    const credential = await this.createVerifiableCredential(
+      {
+        id,
+        issuer,
+        encodedList: newEncodedList,
+        proofFormat: veramoProofFormat,
+        keyRef: args.keyRef,
+        statusPurpose,
+        statusSize,
+        statusMessage,
+        validFrom,
+        validUntil,
+        ttl,
+      },
+      context,
+    )
+
+    return {
+      type: StatusListType.BitstringStatusList,
+      statusListCredential: credential,
+      encodedList: newEncodedList,
+      bitstringStatusList: {
+        statusPurpose,
+        validFrom,
+        validUntil,
+        ttl,
+      },
+      length: statusList.length,
+      proofFormat: args.proofFormat ?? 'lds',
+      id: id,
+      issuer: issuer,
+      statuslistContentType: this.buildContentType(proofFormat),
+    }
+  }
+
+  async checkStatusIndex(args: CheckStatusIndexArgs): Promise<BitstringStatusResult> {
+    const uniform = CredentialMapper.toUniformCredential(args.statusListCredential)
+    const { credentialSubject } = uniform
+    const encodedList = getAssertedProperty('encodedList', credentialSubject)
+
+    const subject = Array.isArray(credentialSubject) ? credentialSubject[0] : credentialSubject
+    const messageList = (subject as any).statusMessage as Array<Partial<BitstringStatus>>
+
+    const numIndex = typeof args.statusListIndex === 'number' ? args.statusListIndex : parseInt(args.statusListIndex)
+    const hexIndex = `0x${numIndex.toString(16)}`
+    const statusMessage = messageList.find((statMsg) => statMsg.status === hexIndex)
+
+    const statusList = (await decodeList({ encodedList })) as IBitstringStatusList
+    if (statusList.length <= numIndex) {
+      throw new Error(`Status list index out of bounds, has ${messageList.length} messages, requested ${numIndex}`)
+    }
+    const value = statusList.getStatus(numIndex)
+    return {
+      index: numIndex,
+      status: hexIndex,
+      message: statusMessage?.message,
+      set: value,
+    } satisfies BitstringStatusResult
+  }
+
+  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 credSubject = Array.isArray(credentialSubject) ? credentialSubject[0] : credentialSubject
+    const statusPurpose = getAssertedProperty('statusPurpose', credSubject)
+    const validFrom = uniform.validFrom ? new Date(uniform.validFrom) : undefined
+    const validUntil = uniform.validUntil ? new Date(uniform.validUntil) : undefined
+    const ttl = credSubject.ttl
+    const list = (await decodeList({ encodedList })) as IBitstringStatusList
+
+    return {
+      id,
+      encodedList,
+      issuer,
+      type: StatusListType.BitstringStatusList,
+      proofFormat,
+      length: list.length,
+      statusListCredential: statusListPayload,
+      statuslistContentType: this.buildContentType(proofFormat),
+      bitstringStatusList: {
+        statusPurpose,
+        validFrom,
+        validUntil,
+        ttl,
+      },
+      ...(args.correlationId && { correlationId: args.correlationId }),
+      ...(args.driverType && { driverType: args.driverType }),
+    }
+  }
+
+  private async createVerifiableCredential(
+    args: {
+      id: string
+      issuer: string | IIssuer
+      encodedList: string
+      proofFormat: VeramoProofFormat
+      statusPurpose: BitstringStatusPurpose
+      statusSize?: number
+      statusMessage?: Array<BitstringStatus>
+      validFrom?: Date
+      validUntil?: Date
+      ttl?: number
+      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 credentialSubject: any = {
+      id: args.id,
+      type: 'BitstringStatusList',
+      statusPurpose: args.statusPurpose,
+      encodedList: args.encodedList,
+    }
+
+    if (args.statusSize && args.statusSize > 1) {
+      credentialSubject.statusSize = args.statusSize
+    }
+
+    if (args.statusMessage) {
+      credentialSubject.statusMessage = args.statusMessage
+    }
+
+    if (args.validFrom) {
+      credentialSubject.validFrom = args.validFrom
+    }
+
+    if (args.validUntil) {
+      credentialSubject.validUntil = args.validUntil
+    }
+
+    if (args.ttl) {
+      credentialSubject.ttl = args.ttl
+    }
+
+    const credential = {
+      '@context': ['https://www.w3.org/2018/credentials/v1', 'https://www.w3.org/ns/credentials/status/v1'],
+      id: args.id,
+      issuer: args.issuer,
+      type: ['VerifiableCredential', 'BitstringStatusListCredential'],
+      credentialSubject,
+    }
+
+    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: CredentialProofFormat | 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/IStatusList.ts

@@ -1,6 +1,7 @@
 import type { IAgentContext, ICredentialPlugin } from '@veramo/core'
 import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
-import type {
+import {
+  BitstringStatusResult,
   CheckStatusIndexArgs,
   CreateStatusListArgs,
   Status2021,
@@ -33,7 +34,7 @@ export interface IStatusList {
   /**
    * Checks the status at a given index in the status list
    */
-  checkStatusIndex(args: CheckStatusIndexArgs): Promise<number | Status2021 | StatusOAuth>
+  checkStatusIndex(args: CheckStatusIndexArgs): Promise<number | Status2021 | StatusOAuth | BitstringStatusResult>
 
   /**
    * Collects the status list details

package/src/impl/OAuthStatusList.ts

@@ -20,7 +20,7 @@ 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_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
 
@@ -70,6 +70,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,
@@ -138,7 +142,7 @@ export class OAuthStatusListImplementation implements IStatusList {
     }
   }
 
-  private buildContentType(proofFormat: 'jwt' | 'lds' | 'EthereumEip712Signature2021' | 'cbor' | undefined) {
+  private buildContentType(proofFormat: CredentialProofFormat | undefined) {
     return `application/statuslist+${proofFormat === 'cbor' ? 'cwt' : 'jwt'}`
   }
 
@@ -153,7 +157,7 @@ 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)
@@ -184,7 +188,7 @@ export class OAuthStatusListImplementation implements IStatusList {
   }
 
   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

@@ -24,7 +24,7 @@ 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 const DEFAULT_PROOF_FORMAT = 'lds' as CredentialProofFormat
 
 export class StatusList2021Implementation implements IStatusList {
   async createNewStatusList(
@@ -234,7 +234,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,42 @@
+export type BitstringConstructorOptions = {
+  length?: number
+  buffer?: Uint8Array
+  leftToRightIndexing?: boolean
+  littleEndianBits?: boolean // deprecated
+}
+
+export type IBitstring = {
+  bits: Uint8Array
+  length: number
+  leftToRightIndexing: boolean
+
+  set(position: number, on: boolean): void
+  get(position: number): boolean
+  encodeBits(): Promise<string>
+  compressBits(): Promise<Uint8Array>
+}
+
+export type BitstringStatic = {
+  new (options?: BitstringConstructorOptions): IBitstring
+  decodeBits(options: { encoded: string }): Promise<Uint8Array>
+  uncompressBits(options: { compressed: Uint8Array }): Promise<Uint8Array>
+}
+
+export type BitstringStatusListConstructorOptions = {
+  length?: number
+  buffer?: Uint8Array
+}
+
+export type IBitstringStatusList = {
+  bitstring: IBitstring
+  length: number
+
+  setStatus(index: number, status: boolean): void
+  getStatus(index: number): boolean
+  encode(): Promise<string>
+}
+
+export type BitstringStatusListStatic = {
+  new (options?: BitstringStatusListConstructorOptions): IBitstringStatusList
+  decode(options: { encodedList: string }): Promise<IBitstringStatusList>
+}

package/src/types/index.ts

@@ -1,11 +1,12 @@
 import type { IIdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
 import {
+  BitstringStatusPurpose,
+  type CredentialProofFormat,
   type ICredential,
   type ICredentialStatus,
   type IIssuer,
   type IVerifiableCredential,
   type OrPromise,
-  type CredentialProofFormat,
   type StatusListCredential,
   StatusListCredentialIdMode,
   StatusListDriverType,
@@ -38,6 +39,20 @@ export enum Status2021 {
   Invalid = 1,
 }
 
+export type BitstringStatus = {
+  status: string
+  message?: string
+  [x: string]: any
+}
+
+export type BitstringStatusResult = BitstringStatus & {
+  index: number
+  status: string
+  set: boolean
+  message?: string
+  [x: string]: any
+}
+
 export type StatusList2021Args = {
   indexingDirection: StatusListIndexingDirection
   statusPurpose?: StatusPurpose2021
@@ -49,6 +64,15 @@ export type OAuthStatusListArgs = {
   expiresAt?: Date
 }
 
+export type BitstringStatusListArgs = {
+  statusPurpose: BitstringStatusPurpose
+  statusSize?: number
+  statusMessage?: Array<BitstringStatus>
+  ttl?: number
+  validFrom?: Date
+  validUntil?: Date
+}
+
 export type BaseCreateNewStatusListArgs = {
   type: StatusListType
   id: string
@@ -71,6 +95,15 @@ export type UpdateOAuthStatusListArgs = {
   expiresAt?: Date
 }
 
+export type UpdateBitstringStatusListArgs = {
+  statusPurpose: BitstringStatusPurpose
+  statusSize?: number
+  statusMessage?: Array<BitstringStatus>
+  validFrom?: Date
+  validUntil?: Date
+  ttl?: number
+}
+
 export interface UpdateStatusListFromEncodedListArgs {
   type?: StatusListType
   statusListIndex: number | string
@@ -83,13 +116,14 @@ 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 {
@@ -103,6 +137,7 @@ export interface StatusListResult {
   issuer: string | IIssuer
   statusList2021?: StatusList2021Details
   oauthStatusList?: OAuthStatusDetails
+  bitstringStatusList?: BitstringStatusDetails
 
   // These cannot be deduced from the VC, so they are present when callers pass in these values as params
   correlationId?: string
@@ -120,6 +155,13 @@ interface OAuthStatusDetails {
   expiresAt?: Date
 }
 
+interface BitstringStatusDetails {
+  statusPurpose: BitstringStatusPurpose
+  validFrom?: Date
+  validUntil?: Date
+  ttl?: number
+}
+
 export interface StatusList2021EntryCredentialStatus extends ICredentialStatus {
   type: 'StatusList2021Entry'
   statusPurpose: StatusPurpose2021
@@ -135,6 +177,16 @@ export interface StatusListOAuthEntryCredentialStatus extends ICredentialStatus
   expiresAt?: Date
 }
 
+export interface BitstringStatusListEntryCredentialStatus extends ICredentialStatus {
+  type: 'BitstringStatusListEntry'
+  statusPurpose: BitstringStatusPurpose | BitstringStatusPurpose[]
+  statusListIndex: string
+  statusListCredential: string
+  statusSize?: number
+  statusMessage?: Array<BitstringStatus>
+  statusReference?: string | string[]
+}
+
 export interface StatusList2021ToVerifiableCredentialArgs {
   issuer: string | IIssuer
   id: string
@@ -154,12 +206,13 @@ 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
   keyRef?: string
   expiresAt?: Date
 }

package/src/utils.ts

@@ -39,7 +39,7 @@ 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']],
 ])