@sphereon/ssi-types 0.17.6-unstable.8 → 0.18.0

package/src/mapper/credential-mapper.ts

@@ -12,17 +12,49 @@ import {
   OriginalType,
   OriginalVerifiableCredential,
   OriginalVerifiablePresentation,
-  PresentationFormat,
   UniformVerifiablePresentation,
   W3CVerifiableCredential,
   W3CVerifiablePresentation,
   WrappedVerifiableCredential,
   WrappedVerifiablePresentation,
+  SdJwtDecodedVerifiableCredential,
+  SdJwtDecodedVerifiableCredentialPayload,
+  ICredential,
+  WrappedSdJwtVerifiableCredential,
+  WrappedW3CVerifiableCredential,
+  isWrappedSdJwtVerifiableCredential,
+  isWrappedSdJwtVerifiablePresentation,
+  isWrappedW3CVerifiableCredential,
+  isWrappedW3CVerifiablePresentation,
+  Hasher,
+  decodeSdJwtVc,
+  decodeSdJwtVcAsync,
+  AsyncHasher,
 } from '../types'
 import { ObjectUtils } from '../utils'
 
 export class CredentialMapper {
-  static decodeVerifiablePresentation(presentation: OriginalVerifiablePresentation): JwtDecodedVerifiablePresentation | IVerifiablePresentation {
+  /**
+   * Decodes a compact SD-JWT vc to it's decoded variant. This method can be used when the hasher implementation used is Async, and therefore not suitable for usage
+   * with the other decode methods.
+   */
+  static decodeSdJwtVcAsync(compactSdJwtVc: string, hasher: AsyncHasher) {
+    return decodeSdJwtVcAsync(compactSdJwtVc, hasher)
+  }
+
+  /**
+   * Decodes a Verifiable Presentation to a uniform format.
+   *
+   * When decoding SD-JWT credentials, a hasher implementation must be provided. The hasher implementation must be sync. When using
+   * an async hasher implementation, use the decodeSdJwtVcAsync method instead and you can provide the decoded payload to methods
+   * instead of the compact SD-JWT.
+   *
+   * @param hasher Hasher implementation to use for SD-JWT decoding.
+   */
+  static decodeVerifiablePresentation(
+    presentation: OriginalVerifiablePresentation,
+    hasher?: Hasher
+  ): JwtDecodedVerifiablePresentation | IVerifiablePresentation | SdJwtDecodedVerifiableCredential {
     if (CredentialMapper.isJwtEncoded(presentation)) {
       const payload = jwt_decode(presentation as string) as JwtDecodedVerifiablePresentation
       const header = jwt_decode(presentation as string, { header: true }) as Record<string, any>
@@ -37,6 +69,13 @@ export class CredentialMapper {
       return payload
     } else if (CredentialMapper.isJwtDecodedPresentation(presentation)) {
       return presentation as JwtDecodedVerifiablePresentation
+    } else if (CredentialMapper.isSdJwtEncoded(presentation)) {
+      if (!hasher) {
+        throw new Error('Hasher implementation is required to decode SD-JWT')
+      }
+      return decodeSdJwtVc(presentation, hasher)
+    } else if (CredentialMapper.isSdJwtDecodedCredential(presentation)) {
+      return presentation as SdJwtDecodedVerifiableCredential
     } else if (CredentialMapper.isJsonLdAsString(presentation)) {
       return JSON.parse(presentation as string) as IVerifiablePresentation
     } else {
@@ -44,7 +83,19 @@ export class CredentialMapper {
     }
   }
 
-  static decodeVerifiableCredential(credential: OriginalVerifiableCredential): JwtDecodedVerifiableCredential | IVerifiableCredential {
+  /**
+   * Decodes a Verifiable Credential to a uniform format.
+   *
+   * When decoding SD-JWT credentials, a hasher implementation must be provided. The hasher implementation must be sync. When using
+   * an async hasher implementation, use the decodeSdJwtVcAsync method instead and you can provide the decoded payload to methods
+   * instead of the compact SD-JWT.
+   *
+   * @param hasher Hasher implementation to use for SD-JWT decoding
+   */
+  static decodeVerifiableCredential(
+    credential: OriginalVerifiableCredential,
+    hasher?: Hasher
+  ): JwtDecodedVerifiableCredential | IVerifiableCredential | SdJwtDecodedVerifiableCredential {
     if (CredentialMapper.isJwtEncoded(credential)) {
       const payload = jwt_decode(credential as string) as JwtDecodedVerifiableCredential
       const header = jwt_decode(credential as string, { header: true }) as Record<string, any>
@@ -57,18 +108,57 @@ export class CredentialMapper {
       }
       return payload
     } else if (CredentialMapper.isJwtDecodedCredential(credential)) {
-      return credential as JwtDecodedVerifiableCredential
+      return credential
     } else if (CredentialMapper.isJsonLdAsString(credential)) {
       return JSON.parse(credential as string) as IVerifiableCredential
+    } else if (CredentialMapper.isSdJwtEncoded(credential)) {
+      if (!hasher) {
+        throw new Error('Hasher implementation is required to decode SD-JWT')
+      }
+      return decodeSdJwtVc(credential, hasher)
+    } else if (CredentialMapper.isSdJwtDecodedCredential(credential)) {
+      return credential
     } else {
       return credential as IVerifiableCredential
     }
   }
 
+  /**
+   * Converts a presentation to a wrapped presentation.
+   *
+   * When decoding SD-JWT credentials, a hasher implementation must be provided. The hasher implementation must be sync. When using
+   * an async hasher implementation, use the decodeSdJwtVcAsync method instead and you can provide the decoded payload to methods
+   * instead of the compact SD-JWT.
+   *
+   * @param hasher Hasher implementation to use for SD-JWT decoding
+   */
   static toWrappedVerifiablePresentation(
     originalPresentation: OriginalVerifiablePresentation,
-    opts?: { maxTimeSkewInMS?: number }
+    opts?: { maxTimeSkewInMS?: number; hasher?: Hasher }
   ): WrappedVerifiablePresentation {
+    // SD-JWT
+    if (CredentialMapper.isSdJwtDecodedCredential(originalPresentation) || CredentialMapper.isSdJwtEncoded(originalPresentation)) {
+      let decodedPresentation: SdJwtDecodedVerifiableCredential
+      if (CredentialMapper.isSdJwtEncoded(originalPresentation)) {
+        if (!opts?.hasher) {
+          throw new Error('Hasher implementation is required to decode SD-JWT')
+        }
+        decodedPresentation = decodeSdJwtVc(originalPresentation, opts.hasher)
+      } else {
+        decodedPresentation = originalPresentation
+      }
+      return {
+        type: CredentialMapper.isSdJwtDecodedCredential(originalPresentation) ? OriginalType.SD_JWT_VC_DECODED : OriginalType.SD_JWT_VC_ENCODED,
+        format: 'vc+sd-jwt',
+        original: originalPresentation,
+        presentation: decodedPresentation,
+        decoded: decodedPresentation.decodedPayload,
+        // NOTE: we also include the SD-JWT VC as the VC, as the SD-JWT acts as both the VC and the VP
+        vcs: [CredentialMapper.toWrappedVerifiableCredential(originalPresentation, opts) as WrappedSdJwtVerifiableCredential],
+      }
+    }
+
+    // If the VP is not an encoded/decoded SD-JWT, we assume it will be a W3C VC
     const proof = CredentialMapper.getFirstProof(originalPresentation)
     const original =
       typeof originalPresentation !== 'string' && CredentialMapper.hasJWTProofType(originalPresentation) ? proof?.jwt : originalPresentation
@@ -77,12 +167,12 @@ export class CredentialMapper {
         'Could not determine original presentation, probably it was a converted JWT presentation, that is now missing the JWT value in the proof'
       )
     }
-    const decoded = CredentialMapper.decodeVerifiablePresentation(original)
+    const decoded = CredentialMapper.decodeVerifiablePresentation(original) as IVerifiablePresentation | JwtDecodedVerifiablePresentation
     const isJwtEncoded: boolean = CredentialMapper.isJwtEncoded(original)
     const isJwtDecoded: boolean = CredentialMapper.isJwtDecodedPresentation(original)
 
     const type = isJwtEncoded ? OriginalType.JWT_ENCODED : isJwtDecoded ? OriginalType.JWT_DECODED : OriginalType.JSONLD
-    const format: PresentationFormat = isJwtDecoded || isJwtEncoded ? 'jwt_vp' : 'ldp_vp'
+    const format = isJwtDecoded || isJwtEncoded ? 'jwt_vp' : ('ldp_vp' as const)
 
     let vp: OriginalVerifiablePresentation
     if (isJwtEncoded || isJwtDecoded) {
@@ -93,10 +183,10 @@ export class CredentialMapper {
     if (!vp || !('verifiableCredential' in vp) || !vp.verifiableCredential || vp.verifiableCredential.length === 0) {
       throw Error(`VP needs to have at least one verifiable credential at this point`)
     }
-    const vcs: WrappedVerifiableCredential[] = CredentialMapper.toWrappedVerifiableCredentials(
+    const vcs = CredentialMapper.toWrappedVerifiableCredentials(
       vp.verifiableCredential /*.map(value => value.original)*/,
       opts
-    )
+    ) as WrappedW3CVerifiableCredential[]
 
     const presentation = {
       ...vp,
@@ -112,17 +202,57 @@ export class CredentialMapper {
     }
   }
 
+  /**
+   * Converts a list of credentials to a list of wrapped credentials.
+   *
+   * When decoding SD-JWT credentials, a hasher implementation must be provided. The hasher implementation must be sync. When using
+   * an async hasher implementation, use the decodeSdJwtVcAsync method instead and you can provide the decoded payload to methods
+   * instead of the compact SD-JWT.
+   *
+   * @param hasher Hasher implementation to use for SD-JWT decoding
+   */
   static toWrappedVerifiableCredentials(
     verifiableCredentials: OriginalVerifiableCredential[],
-    opts?: { maxTimeSkewInMS?: number }
+    opts?: { maxTimeSkewInMS?: number; hasher?: Hasher }
   ): WrappedVerifiableCredential[] {
     return verifiableCredentials.map((vc) => CredentialMapper.toWrappedVerifiableCredential(vc, opts))
   }
 
+  /**
+   * Converts a credential to a wrapped credential.
+   *
+   * When decoding SD-JWT credentials, a hasher implementation must be provided. The hasher implementation must be sync. When using
+   * an async hasher implementation, use the decodeSdJwtVcAsync method instead and you can provide the decoded payload to methods
+   * instead of the compact SD-JWT.
+   *
+   * @param hasher Hasher implementation to use for SD-JWT decoding
+   */
   static toWrappedVerifiableCredential(
     verifiableCredential: OriginalVerifiableCredential,
-    opts?: { maxTimeSkewInMS?: number }
+    opts?: { maxTimeSkewInMS?: number; hasher?: Hasher }
   ): WrappedVerifiableCredential {
+    // SD-JWT
+    if (CredentialMapper.isSdJwtDecodedCredential(verifiableCredential) || CredentialMapper.isSdJwtEncoded(verifiableCredential)) {
+      let decodedCredential: SdJwtDecodedVerifiableCredential
+      if (CredentialMapper.isSdJwtEncoded(verifiableCredential)) {
+        if (!opts?.hasher) {
+          throw new Error('Hasher implementation is required to decode SD-JWT')
+        }
+        decodedCredential = decodeSdJwtVc(verifiableCredential, opts.hasher)
+      } else {
+        decodedCredential = verifiableCredential
+      }
+
+      return {
+        type: CredentialMapper.isSdJwtDecodedCredential(verifiableCredential) ? OriginalType.SD_JWT_VC_DECODED : OriginalType.SD_JWT_VC_ENCODED,
+        format: 'vc+sd-jwt',
+        original: verifiableCredential,
+        credential: decodedCredential,
+        decoded: decodedCredential.decodedPayload,
+      }
+    }
+
+    // If the VC is not an encoded/decoded SD-JWT, we assume it will be a W3C VC
     const proof = CredentialMapper.getFirstProof(verifiableCredential)
     const original = CredentialMapper.hasJWTProofType(verifiableCredential) && proof ? proof.jwt ?? verifiableCredential : verifiableCredential
     if (!original) {
@@ -130,7 +260,7 @@ export class CredentialMapper {
         'Could not determine original credential, probably it was a converted JWT credential, that is now missing the JWT value in the proof'
       )
     }
-    const decoded = CredentialMapper.decodeVerifiableCredential(original)
+    const decoded = CredentialMapper.decodeVerifiableCredential(original) as JwtDecodedVerifiableCredential | IVerifiableCredential
 
     const isJwtEncoded = CredentialMapper.isJwtEncoded(original)
     const isJwtDecoded = CredentialMapper.isJwtDecodedCredential(original)
@@ -141,7 +271,7 @@ export class CredentialMapper {
         ? CredentialMapper.jwtDecodedCredentialToUniformCredential(decoded as JwtDecodedVerifiableCredential, opts)
         : (decoded as IVerifiableCredential)
 
-    const format = isJwtEncoded || isJwtDecoded ? 'jwt_vc' : 'ldp_vc'
+    const format = isJwtEncoded || isJwtDecoded ? ('jwt_vc' as const) : ('ldp_vc' as const)
     return {
       original,
       decoded,
@@ -151,22 +281,65 @@ export class CredentialMapper {
     }
   }
 
-  public static isJwtEncoded(original: OriginalVerifiableCredential | OriginalVerifiablePresentation) {
-    return ObjectUtils.isString(original) && (original as string).startsWith('ey')
+  public static isJwtEncoded(original: OriginalVerifiableCredential | OriginalVerifiablePresentation): original is string {
+    return ObjectUtils.isString(original) && original.startsWith('ey') && !original.includes('~')
   }
 
-  private static isJsonLdAsString(original: OriginalVerifiableCredential | OriginalVerifiablePresentation) {
-    return ObjectUtils.isString(original) && (original as string).includes('@context')
+  public static isSdJwtEncoded(original: OriginalVerifiableCredential | OriginalVerifiablePresentation): original is string {
+    return ObjectUtils.isString(original) && original.startsWith('ey') && original.includes('~')
   }
 
-  public static isJwtDecodedCredential(original: OriginalVerifiableCredential): boolean {
-    return (<JwtDecodedVerifiableCredential>original)['vc'] !== undefined && (<JwtDecodedVerifiableCredential>original)['iss'] !== undefined
+  public static isW3cCredential(credential: ICredential | SdJwtDecodedVerifiableCredential): credential is ICredential {
+    return '@context' in credential && ((credential as ICredential).type?.includes('VerifiableCredential') || false)
   }
 
-  public static isJwtDecodedPresentation(original: OriginalVerifiablePresentation): boolean {
-    return (<JwtDecodedVerifiablePresentation>original)['vp'] !== undefined && (<JwtDecodedVerifiablePresentation>original)['iss'] !== undefined
+  public static isW3cPresentation(
+    presentation: UniformVerifiablePresentation | IPresentation | SdJwtDecodedVerifiableCredential
+  ): presentation is IPresentation {
+    return '@context' in presentation && ((presentation as IPresentation).type?.includes('VerifiablePresentation') || false)
   }
 
+  public static isSdJwtDecodedCredentialPayload(
+    credential: ICredential | SdJwtDecodedVerifiableCredentialPayload
+  ): credential is SdJwtDecodedVerifiableCredentialPayload {
+    return 'vct' in credential
+  }
+
+  public static areOriginalVerifiableCredentialsEqual(firstOriginal: OriginalVerifiableCredential, secondOriginal: OriginalVerifiableCredential) {
+    // String (e.g. encoded jwt or SD-JWT)
+    if (typeof firstOriginal === 'string' || typeof secondOriginal === 'string') {
+      return firstOriginal === secondOriginal
+    } else if (CredentialMapper.isSdJwtDecodedCredential(firstOriginal) || CredentialMapper.isSdJwtDecodedCredential(secondOriginal)) {
+      return firstOriginal.compactSdJwtVc === secondOriginal.compactSdJwtVc
+    } else {
+      // JSON-LD or decoded JWT. (should we compare the signatures instead?)
+      return JSON.stringify(secondOriginal.proof) === JSON.stringify(firstOriginal.proof)
+    }
+  }
+
+  private static isJsonLdAsString(original: OriginalVerifiableCredential | OriginalVerifiablePresentation): original is string {
+    return ObjectUtils.isString(original) && original.includes('@context')
+  }
+
+  public static isSdJwtDecodedCredential(
+    original: OriginalVerifiableCredential | OriginalVerifiablePresentation | ICredential | IPresentation
+  ): original is SdJwtDecodedVerifiableCredential {
+    return (<SdJwtDecodedVerifiableCredential>original).compactSdJwtVc !== undefined
+  }
+
+  public static isJwtDecodedCredential(original: OriginalVerifiableCredential): original is JwtDecodedVerifiableCredential {
+    return (<JwtDecodedVerifiableCredential>original).vc !== undefined && (<JwtDecodedVerifiableCredential>original).iss !== undefined
+  }
+
+  public static isJwtDecodedPresentation(original: OriginalVerifiablePresentation): original is JwtDecodedVerifiablePresentation {
+    return (<JwtDecodedVerifiablePresentation>original).vp !== undefined && (<JwtDecodedVerifiablePresentation>original).iss !== undefined
+  }
+
+  public static isWrappedSdJwtVerifiableCredential = isWrappedSdJwtVerifiableCredential
+  public static isWrappedSdJwtVerifiablePresentation = isWrappedSdJwtVerifiablePresentation
+  public static isWrappedW3CVerifiableCredential = isWrappedW3CVerifiableCredential
+  public static isWrappedW3CVerifiablePresentation = isWrappedW3CVerifiablePresentation
+
   static jwtEncodedPresentationToUniformPresentation(
     jwt: string,
     makeCredentialsUniform: boolean = true,
@@ -226,6 +399,9 @@ export class CredentialMapper {
       maxTimeSkewInMS?: number
     }
   ): IVerifiableCredential {
+    if (CredentialMapper.isSdJwtDecodedCredential(verifiableCredential)) {
+      throw new Error('Converting SD-JWT VC to uniform VC is not supported.')
+    }
     const original =
       typeof verifiableCredential !== 'string' && CredentialMapper.hasJWTProofType(verifiableCredential)
         ? CredentialMapper.getFirstProof(verifiableCredential)?.jwt
@@ -251,6 +427,10 @@ export class CredentialMapper {
     presentation: OriginalVerifiablePresentation,
     opts?: { maxTimeSkewInMS?: number; addContextIfMissing?: boolean }
   ): IVerifiablePresentation {
+    if (CredentialMapper.isSdJwtDecodedCredential(presentation)) {
+      throw new Error('Converting SD-JWT VC to uniform VP is not supported.')
+    }
+
     const proof = CredentialMapper.getFirstProof(presentation)
     const original = typeof presentation !== 'string' && CredentialMapper.hasJWTProofType(presentation) ? proof?.jwt : presentation
     if (!original) {
@@ -459,11 +639,21 @@ export class CredentialMapper {
   }
 
   static detectDocumentType(
-    document: W3CVerifiableCredential | W3CVerifiablePresentation | JwtDecodedVerifiableCredential | JwtDecodedVerifiablePresentation
+    document:
+      | W3CVerifiableCredential
+      | W3CVerifiablePresentation
+      | JwtDecodedVerifiableCredential
+      | JwtDecodedVerifiablePresentation
+      | SdJwtDecodedVerifiableCredential
   ): DocumentFormat {
-    if (typeof document === 'string') {
-      return this.isJsonLdAsString(document) ? DocumentFormat.JSONLD : DocumentFormat.JWT
+    if (this.isJsonLdAsString(document)) {
+      return DocumentFormat.JSONLD
+    } else if (this.isJwtEncoded(document)) {
+      return DocumentFormat.JWT
+    } else if (this.isSdJwtEncoded(document) || this.isSdJwtDecodedCredential(document as any)) {
+      return DocumentFormat.SD_JWT_VC
     }
+
     const proofs = 'vc' in document ? document.vc.proof : 'vp' in document ? document.vp.proof : (<IVerifiableCredential>document).proof
     const proof: IProof = Array.isArray(proofs) ? proofs[0] : proofs
 

package/src/types/generic.ts

@@ -4,3 +4,5 @@
  * @internal
  */
 export type OrPromise<T> = T | Promise<T>
+
+export type BearerTokenArg = (() => Promise<string>) | string

package/src/types/index.ts

@@ -2,3 +2,5 @@ export * from './did'
 export * from './pex'
 export * from './vc'
 export * from './generic'
+export * from './sd-jwt-vc'
+export * from './w3c-vc'

package/src/types/sd-jwt-vc.ts

@@ -0,0 +1,248 @@
+import { OriginalType, WrappedVerifiableCredential, WrappedVerifiablePresentation } from './vc'
+import { SdJwtVc } from '@sd-jwt/core'
+import { swapClaims } from '@sd-jwt/core/build/sdJwt/swapClaim'
+type JsonValue = string | number | boolean | { [x: string]: JsonValue | undefined } | Array<JsonValue>
+
+type SdJwtJsonValue =
+  | string
+  | number
+  | boolean
+  | {
+      [x: string]: SdJwtJsonValue | undefined
+      _sd?: string[]
+    }
+  | Array<SdJwtJsonValue | { '...': string }>
+
+/**
+ * Decoded 'pretty' SD JWT Verifiable Credential. This representation has all the `_sd` properties
+ * removed, and includes the disclosures directly within the payload.
+ */
+export interface SdJwtDecodedVerifiableCredentialPayload {
+  vct: string
+  iss: string
+  iat: number
+  nbf?: number
+  exp?: number
+  cnf?: {
+    jwk?: any
+    kid?: string
+  }
+  status?: {
+    idx: number
+    uri: string
+  }
+  sub?: string
+
+  [key: string]: JsonValue | undefined
+}
+
+/**
+ * Represents a selective disclosure JWT vc in compact form.
+ */
+export type CompactSdJwtVc = string
+
+/**
+ * The signed payload of an SD-JWT. Includes fields such as `_sd`, `...` and `_sd_alg`
+ */
+interface SdJwtSignedVerifiableCredentialPayload extends SdJwtDecodedVerifiableCredentialPayload {
+  // Only present if there are any selectively discloseable claims
+  _sd?: string[]
+  _sd_alg?: string
+
+  [x: string]: SdJwtJsonValue | undefined
+}
+
+type SdJwtFrameValue = boolean | Array<SdJwtFrameValue> | { [x: string]: SdJwtFrameValue }
+export type SdJwtDisclosureFrame = Record<string, SdJwtFrameValue>
+export type SdJwtPresentationFrame = Record<string, SdJwtFrameValue>
+
+/**
+ * Input for creating a SD JWT Verifiable Credential. This representation optionally includes the disclosure frame,
+ * (as `__disclosureFrame`) to indicate which fields in the signed SD-JWT should be selectively discloseable
+ */
+export interface SdJwtCredentialInput extends SdJwtDecodedVerifiableCredentialPayload {
+  /**
+   * Disclosure frame, indicating which fields in the signed SD-JWT should be selectively discloseable
+   * Will be removed from the actual SD-JWT payload before signing
+   */
+  __disclosureFrame?: SdJwtDisclosureFrame
+}
+
+export type SdJwtDecodedDisclosure = [string, string, JsonValue] | [string, JsonValue]
+export interface SdJwtDisclosure {
+  // The encoded disclosure
+  encoded: string
+
+  // The decoded disclosure, in format [salt, claim, value] or in case of array entry [salt, value]
+  decoded: SdJwtDecodedDisclosure
+
+  // Digest over disclosure, can be used to match against a value within the SD JWT payload
+  digest: string
+}
+
+/**
+ * The decoded SD JWT Verifiable Credential. This representation includes multiple representations of the
+ * same SD-JWT, and allows to fully process an SD-JWT, as well as create a presentation SD-JWT  (minus the KB-JWT) by removing
+ * certain disclosures from the compact SD-JWT.
+ *
+ * This representation is useful as it doesn't require a hasher implementation to match the different digests in the signed SD-JWT
+ * payload, with the different disclosures.
+ */
+export interface SdJwtDecodedVerifiableCredential {
+  /**
+   * The compact sd jwt is the sd-jwt encoded as string. It is a normal JWT,
+   * with the disclosures and kb-jwt appended separated by ~ */
+  compactSdJwtVc: string
+
+  /**
+   * The disclosures included within the SD-JWT in both encoded and decoded format.
+   * The digests are also included, and allows the disclosures to be linked against
+   * the digests in the signed payload.
+   */
+  disclosures: Array<SdJwtDisclosure>
+
+  /**
+   * The signed payload is the payload of the sd-jwt that is actually signed, and that includes
+   * the `_sd` and `...` digests.
+   */
+  signedPayload: SdJwtSignedVerifiableCredentialPayload
+
+  /**
+   * The decoded payload is the payload when all `_sd` and `...` digests have been replaced
+   * by the actual values from the disclosures. This format could also be seen as the 'pretty`
+   * version of the SD JWT payload.
+   *
+   * This is useful for displaying the contents of the SD JWT VC to the user, or for example
+   * for querying the contents of the SD JWT VC using a PEX presentation definition path.
+   */
+  decodedPayload: SdJwtDecodedVerifiableCredentialPayload
+}
+
+export interface WrappedSdJwtVerifiableCredential {
+  /**
+   * Original VC that we've received. Can be either the encoded or decoded variant.
+   */
+  original: SdJwtDecodedVerifiableCredential | CompactSdJwtVc
+  /**
+   * Decoded version of the SD-JWT payload. This is the decoded payload, rather than the whole SD-JWT as the `decoded` property
+   * is used in e.g. PEX to check for path filters from fields. The full decoded credential can be found in the `credential` field.
+   */
+  decoded: SdJwtDecodedVerifiableCredentialPayload
+  /**
+   * Type of this credential.
+   */
+  type: OriginalType.SD_JWT_VC_DECODED | OriginalType.SD_JWT_VC_ENCODED
+  /**
+   * The claim format, typically used during exchange transport protocols
+   */
+  format: 'vc+sd-jwt'
+  /**
+   * Internal stable representation of a Credential
+   */
+  credential: SdJwtDecodedVerifiableCredential
+}
+
+export interface WrappedSdJwtVerifiablePresentation {
+  /**
+   * Original VP that we've received. Can be either the encoded or decoded variant.
+   */
+  original: SdJwtDecodedVerifiableCredential | CompactSdJwtVc
+  /**
+   * Decoded version of the SD-JWT payload. This is the decoded payload, rather than the whole SD-JWT.
+   */
+  decoded: SdJwtDecodedVerifiableCredentialPayload
+  /**
+   * Type of this Presentation.
+   */
+  type: OriginalType.SD_JWT_VC_DECODED | OriginalType.SD_JWT_VC_ENCODED
+  /**
+   * The claim format, typically used during exchange transport protocols
+   */
+  format: 'vc+sd-jwt'
+  /**
+   * Internal stable representation of a Presentation
+   */
+  presentation: SdJwtDecodedVerifiableCredential
+  /**
+   * Wrapped Verifiable Credentials belonging to the Presentation. Will always be an array
+   * with a single SdJwtVerifiableCredential entry.
+   */
+  vcs: [WrappedSdJwtVerifiableCredential]
+}
+
+export function isWrappedSdJwtVerifiableCredential(vc: WrappedVerifiableCredential): vc is WrappedSdJwtVerifiableCredential {
+  return vc.format === 'vc+sd-jwt'
+}
+
+export function isWrappedSdJwtVerifiablePresentation(vp: WrappedVerifiablePresentation): vp is WrappedSdJwtVerifiablePresentation {
+  return vp.format === 'vc+sd-jwt'
+}
+
+export type Hasher = (data: string, alg: string) => Uint8Array
+export type AsyncHasher = (data: string, alg: string) => Promise<Uint8Array>
+
+/**
+ * Decode an SD-JWT vc from its compact format (string) to an object containing the disclosures,
+ * signed payload, decoded payload and the compact SD-JWT vc.
+ *
+ * Both the input and output interfaces of this method are defined in `@sphereon/ssi-types`, so
+ * this method hides the actual implementation of SD-JWT (which is currently based on @sd-jwt/core)
+ */
+export function decodeSdJwtVc(compactSdJwtVc: CompactSdJwtVc, hasher: Hasher): SdJwtDecodedVerifiableCredential {
+  const sdJwtVc = SdJwtVc.fromCompact(compactSdJwtVc)
+
+  // Default (should be handled by the sd-jwt library)
+  let sdAlg = 'sha-256'
+  try {
+    sdAlg = sdJwtVc.getClaimInPayload('_sd_alg')
+  } catch {
+    /* no-op */
+  }
+
+  const disclosuresWithDigests = sdJwtVc.disclosures?.map((d) => d.withCalculateDigest((data: string) => hasher(data, sdAlg))) ?? []
+
+  return {
+    compactSdJwtVc: compactSdJwtVc,
+    decodedPayload: swapClaims(sdJwtVc.payload, disclosuresWithDigests) as SdJwtDecodedVerifiableCredentialPayload,
+    disclosures: disclosuresWithDigests.map((d) => ({
+      decoded: d.decoded as SdJwtDecodedDisclosure,
+      digest: d.digest,
+      encoded: d.encoded,
+    })),
+    signedPayload: sdJwtVc.payload as SdJwtDecodedVerifiableCredentialPayload,
+  }
+}
+
+/**
+ * Decode an SD-JWT vc from its compact format (string) to an object containing the disclosures,
+ * signed payload, decoded payload and the compact SD-JWT vc.
+ *
+ * Both the input and output interfaces of this method are defined in `@sphereon/ssi-types`, so
+ * this method hides the actual implementation of SD-JWT (which is currently based on @sd-jwt/core)
+ */
+export async function decodeSdJwtVcAsync(compactSdJwtVc: CompactSdJwtVc, hasher: AsyncHasher): Promise<SdJwtDecodedVerifiableCredential> {
+  const sdJwtVc = SdJwtVc.fromCompact(compactSdJwtVc)
+
+  // Default (should be handled by the sd-jwt library)
+  let sdAlg = 'sha-256'
+  try {
+    sdAlg = sdJwtVc.getClaimInPayload('_sd_alg')
+  } catch {
+    /* no-op */
+  }
+
+  const disclosuresWithDigests = await Promise.all(
+    sdJwtVc.disclosures?.map((d) => d.withCalculateDigest((data: string) => hasher(data, sdAlg))) ?? []
+  )
+
+  return {
+    compactSdJwtVc: compactSdJwtVc,
+    decodedPayload: swapClaims(sdJwtVc.payload, disclosuresWithDigests) as SdJwtDecodedVerifiableCredentialPayload,
+    disclosures: disclosuresWithDigests.map((d) => ({
+      decoded: d.decoded as SdJwtDecodedDisclosure,
+      digest: d.digest,
+      encoded: d.encoded,
+    })),
+    signedPayload: sdJwtVc.payload as SdJwtDecodedVerifiableCredentialPayload,
+  }
+}