feat: support multi-presentation submission for transaction data (dcql multiple feature) (#82)

TimoGlastra · web-flow · commit 79040884ad19 · 2025-07-14T11:00:59.000+02:00
Signed-off-by: Timo Glastra &lt;timo@animo.id&gt;
diff --git a/.changeset/better-donuts-help.md b/.changeset/better-donuts-help.md
@@ -0,0 +1,5 @@
+---
+"@openid4vc/openid4vp": minor
+---
+
+feat: support multi-presentation submission for transaction data (dcql multiple feature)
diff --git a/packages/openid4vp/src/Openid4vpVerifier.ts b/packages/openid4vp/src/Openid4vpVerifier.ts
@@ -60,6 +60,14 @@ export class Openid4vpVerifier {
     return parseTransactionData(options)
   }
 
+  /**
+   * Verify transaction data against submitted credentials.
+   *
+   * NOTE: this expects transaction data based authorization based on hashes. This is the method defined
+   * for SD-JWT VC, but for mDOCs it's much more generic. If you're using transaction data with mDOCs based
+   * on hashes, you can extract the values from the DeviceResponse, otherwise you must verify the transaction data
+   * manually.
+   */
   public verifyTransactionData(options: Omit<VerifyTransactionDataOptions, 'callbacks'>) {
     return verifyTransactionData({
       ...options,
diff --git a/packages/openid4vp/src/transaction-data/verify-transaction-data.test.mts b/packages/openid4vp/src/transaction-data/verify-transaction-data.test.mts
@@ -17,21 +17,41 @@ describe('Verify transaction data', () => {
       callbacks,
       transactionData: [transactionData],
       credentials: {
-        one: {
-          transaction_data_hashes: [
-            Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-          ],
-          transaction_data_hashes_alg: 'sha-256',
-        },
+        one: [
+          {
+            transaction_data_hashes: [
+              'random',
+              Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+            ],
+            transaction_data_hashes_alg: 'sha-256',
+          },
+          {
+            transaction_data_hashes: [
+              Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+            ],
+            transaction_data_hashes_alg: 'sha-256',
+          },
+        ],
       },
     })
 
     expect(verifiedMatches).toEqual([
       {
-        credentialHashIndex: 0,
         credentialId: 'one',
-        hash: Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-        hashAlg: 'sha-256',
+        presentations: [
+          {
+            presentationIndex: 0,
+            credentialHashIndex: 1,
+            hash: Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+            hashAlg: 'sha-256',
+          },
+          {
+            presentationIndex: 1,
+            credentialHashIndex: 0,
+            hash: Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+            hashAlg: 'sha-256',
+          },
+        ],
         transactionDataEntry: {
           transactionDataIndex: 0,
           encoded: transactionData,
@@ -45,7 +65,7 @@ describe('Verify transaction data', () => {
     ])
   })
 
-  test('succesfully matches with multiple credential credential and multiple transaction data entries', async () => {
+  test('succesfully matches with multiple credentials and multiple transaction data entries', async () => {
     const transactionData = Buffer.from(
       JSON.stringify({
         type: 'qes',
@@ -65,27 +85,36 @@ describe('Verify transaction data', () => {
       callbacks,
       transactionData: [transactionData, transactionData2],
       credentials: {
-        three: {
-          transaction_data_hashes: [
-            Buffer.from(callbacks.hash(Buffer.from(transactionData2), HashAlgorithm.Sha256)).toString('base64url'),
-          ],
-        },
-        two: {
-          transaction_data_hashes: [
-            'random',
-            Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-          ],
-          transaction_data_hashes_alg: 'sha-256',
-        },
+        three: [
+          {
+            transaction_data_hashes: [
+              Buffer.from(callbacks.hash(Buffer.from(transactionData2), HashAlgorithm.Sha256)).toString('base64url'),
+            ],
+          },
+        ],
+        two: [
+          {
+            transaction_data_hashes: [
+              'random',
+              Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+            ],
+            transaction_data_hashes_alg: 'sha-256',
+          },
+        ],
       },
     })
 
     expect(verifiedMatches).toEqual([
       {
-        credentialHashIndex: 1,
         credentialId: 'two',
-        hash: Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-        hashAlg: 'sha-256',
+        presentations: [
+          {
+            presentationIndex: 0,
+            credentialHashIndex: 1,
+            hash: Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+            hashAlg: 'sha-256',
+          },
+        ],
         transactionDataEntry: {
           transactionDataIndex: 0,
           encoded: transactionData,
@@ -97,10 +126,17 @@ describe('Verify transaction data', () => {
         },
       },
       {
-        credentialHashIndex: 0,
         credentialId: 'three',
-        hash: Buffer.from(callbacks.hash(Buffer.from(transactionData2), HashAlgorithm.Sha256)).toString('base64url'),
-        hashAlg: 'sha-256',
+        presentations: [
+          {
+            presentationIndex: 0,
+            credentialHashIndex: 0,
+            hash: Buffer.from(callbacks.hash(Buffer.from(transactionData2), HashAlgorithm.Sha256)).toString(
+              'base64url'
+            ),
+            hashAlg: 'sha-256',
+          },
+        ],
         transactionDataEntry: {
           transactionDataIndex: 1,
           encoded: transactionData2,
@@ -134,20 +170,22 @@ describe('Verify transaction data', () => {
         callbacks,
         transactionData: [transactionData, transactionData2],
         credentials: {
-          two: {
-            transaction_data_hashes: [
-              'random',
-              Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-            ],
-            transaction_data_hashes_alg: 'sha-256',
-          },
+          two: [
+            {
+              transaction_data_hashes: [
+                'random',
+                Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+              ],
+              transaction_data_hashes_alg: 'sha-256',
+            },
+          ],
         },
       })
     ).rejects.toThrow(
       new Oauth2ServerErrorResponseError({
         error: Oauth2ErrorCodes.InvalidTransactionData,
         error_description:
-          'Transaction data entry with index 1 does not have a matching hash in any of the submitted credentials',
+          'Transaction data entry with index 1 for presentation two with index 0 does not have a matching hash in the transaction_data_hashes',
       })
     )
   })
@@ -173,20 +211,22 @@ describe('Verify transaction data', () => {
         callbacks,
         transactionData: [transactionData, transactionData2],
         credentials: {
-          two: {
-            transaction_data_hashes: [
-              'random',
-              Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-            ],
-            transaction_data_hashes_alg: 'random',
-          },
+          two: [
+            {
+              transaction_data_hashes: [
+                'random',
+                Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+              ],
+              transaction_data_hashes_alg: 'random',
+            },
+          ],
         },
       })
     ).rejects.toThrow(
       new Oauth2ServerErrorResponseError({
         error: Oauth2ErrorCodes.InvalidTransactionData,
         error_description:
-          "Transaction data entry with index 0 is hashed using alg 'random'. However transaction data only allows alg values sha-256.",
+          "Transaction data entry with index 0 for presentation two with index 0 is hashed using alg 'random'. However transaction data only allows alg values sha-256.",
       })
     )
   })
@@ -212,20 +252,22 @@ describe('Verify transaction data', () => {
         callbacks,
         transactionData: [transactionData, transactionData2],
         credentials: {
-          two: {
-            transaction_data_hashes: [
-              'random',
-              Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
-            ],
-            transaction_data_hashes_alg: 'random',
-          },
+          two: [
+            {
+              transaction_data_hashes: [
+                'random',
+                Buffer.from(callbacks.hash(Buffer.from(transactionData), HashAlgorithm.Sha256)).toString('base64url'),
+              ],
+              transaction_data_hashes_alg: 'random',
+            },
+          ],
         },
       })
     ).rejects.toThrow(
       new Oauth2ServerErrorResponseError({
         error: Oauth2ErrorCodes.InvalidTransactionData,
         error_description:
-          "Transaction data entry with index 0 is hashed using unsupported alg 'random'. This library only supports verification of transaction data hashes using alg values sha-256, sha-384, sha-512. Either verify the hashes outside of this library, or limit the allowed alg values to the ones supported by this library.",
+          "Transaction data entry with index 0 for presentation two with index 0 is hashed using unsupported alg 'random'. This library only supports verification of transaction data hashes using alg values sha-256, sha-384, sha-512. Either verify the hashes outside of this library, or limit the allowed alg values to the ones supported by this library.",
       })
     )
   })
diff --git a/packages/openid4vp/src/transaction-data/verify-transaction-data.ts b/packages/openid4vp/src/transaction-data/verify-transaction-data.ts
@@ -4,18 +4,18 @@ import {
   Oauth2ErrorCodes,
   Oauth2ServerErrorResponseError,
 } from '@openid4vc/oauth2'
-import { decodeUtf8String, encodeToBase64Url } from '@openid4vc/utils'
+import { type NonEmptyArray, decodeUtf8String, encodeToBase64Url } from '@openid4vc/utils'
 import { type ParsedTransactionDataEntry, parseTransactionData } from './parse-transaction-data'
 
 export interface TransactionDataHashesCredentials {
   /**
    * credentialId is the pex input descriptor id
-   * or dcql credential query id
+   * or dcql credential query id.
    *
    * The values must be an array of transaction data hashes
    */
   [credentialId: string]:
-    | {
+    | NonEmptyArray<{
         /**
          * The hashes of the transaction data
          */
@@ -27,7 +27,7 @@ export interface TransactionDataHashesCredentials {
          * is used.
          */
         transaction_data_hashes_alg?: string
-      }
+      }>
     | undefined
 }
 
@@ -61,9 +61,13 @@ export async function verifyTransactionData(
 export interface VerifiedTransactionDataEntry {
   transactionDataEntry: ParsedTransactionDataEntry
   credentialId: string
-  hash: string
-  hashAlg: HashAlgorithm
-  credentialHashIndex: number
+
+  presentations: NonEmptyArray<{
+    presentationIndex: number
+    hash: string
+    hashAlg: HashAlgorithm
+    credentialHashIndex: number
+  }>
 }
 
 async function verifyTransactionDataEntry({
@@ -86,36 +90,53 @@ async function verifyTransactionDataEntry({
   }
 
   for (const credentialId of entry.transactionData.credential_ids) {
-    const transactionDataHashesCredential = credentials[credentialId]
-    if (!transactionDataHashesCredential) continue
+    const transactionDataHashesCredentials = credentials[credentialId]
+    if (!transactionDataHashesCredentials) continue
 
-    const alg = transactionDataHashesCredential.transaction_data_hashes_alg ?? 'sha-256'
-    const hash = hashes[alg as HashAlgorithm]
+    const presentations: VerifiedTransactionDataEntry['presentations'][number][] = []
 
-    if (!allowedAlgs.includes(alg)) {
-      throw new Oauth2ServerErrorResponseError({
-        error: Oauth2ErrorCodes.InvalidTransactionData,
-        error_description: `Transaction data entry with index ${entry.transactionDataIndex} is hashed using alg '${alg}'. However transaction data only allows alg values ${allowedAlgs.join(', ')}.`,
-      })
-    }
+    for (const transactionDataHashesCredential of transactionDataHashesCredentials) {
+      const alg = transactionDataHashesCredential.transaction_data_hashes_alg ?? 'sha-256'
+      const hash = hashes[alg as HashAlgorithm]
+      const presentationIndex = transactionDataHashesCredentials.indexOf(transactionDataHashesCredential)
 
-    // This is an error of this library.
-    if (!hash) {
-      throw new Oauth2ServerErrorResponseError({
-        error: Oauth2ErrorCodes.InvalidTransactionData,
-        error_description: `Transaction data entry with index ${entry.transactionDataIndex} is hashed using unsupported alg '${alg}'. This library only supports verification of transaction data hashes using alg values ${Object.values(HashAlgorithm).join(', ')}. Either verify the hashes outside of this library, or limit the allowed alg values to the ones supported by this library.`,
-      })
-    }
+      if (!allowedAlgs.includes(alg)) {
+        throw new Oauth2ServerErrorResponseError({
+          error: Oauth2ErrorCodes.InvalidTransactionData,
+          error_description: `Transaction data entry with index ${entry.transactionDataIndex} for presentation ${credentialId} with index ${presentationIndex} is hashed using alg '${alg}'. However transaction data only allows alg values ${allowedAlgs.join(', ')}.`,
+        })
+      }
+
+      if (!hash) {
+        // This is an error of this library.
+        throw new Oauth2ServerErrorResponseError({
+          error: Oauth2ErrorCodes.InvalidTransactionData,
+          error_description: `Transaction data entry with index ${entry.transactionDataIndex} for presentation ${credentialId} with index ${presentationIndex} is hashed using unsupported alg '${alg}'. This library only supports verification of transaction data hashes using alg values ${Object.values(HashAlgorithm).join(', ')}. Either verify the hashes outside of this library, or limit the allowed alg values to the ones supported by this library.`,
+        })
+      }
 
-    const credentialHashIndex = transactionDataHashesCredential.transaction_data_hashes.indexOf(hash)
-    if (credentialHashIndex !== -1) {
-      return {
-        transactionDataEntry: entry,
-        credentialId,
+      const credentialHashIndex = transactionDataHashesCredential.transaction_data_hashes.indexOf(hash)
+
+      if (credentialHashIndex === -1) {
+        // No matches were found
+        throw new Oauth2ServerErrorResponseError({
+          error: Oauth2ErrorCodes.InvalidTransactionData,
+          error_description: `Transaction data entry with index ${entry.transactionDataIndex} for presentation ${credentialId} with index ${presentationIndex} does not have a matching hash in the transaction_data_hashes`,
+        })
+      }
+
+      presentations.push({
+        credentialHashIndex,
         hash,
         hashAlg: alg as HashAlgorithm,
-        credentialHashIndex,
-      }
+        presentationIndex,
+      })
+    }
+
+    return {
+      transactionDataEntry: entry,
+      credentialId,
+      presentations: presentations as VerifiedTransactionDataEntry['presentations'],
     }
   }
 
diff --git a/packages/openid4vp/src/transaction-data/z-transaction-data.ts b/packages/openid4vp/src/transaction-data/z-transaction-data.ts
@@ -4,7 +4,9 @@ export const zTransactionEntry = z
   .object({
     type: z.string(),
     credential_ids: z.array(z.string()).nonempty(),
-    transaction_data_hashes_alg: z.array(z.string()).optional(),
+
+    // SD-JWT VC specific
+    transaction_data_hashes_alg: z.array(z.string()).nonempty().optional(),
   })
   .passthrough()
 export type TransactionDataEntry = z.infer<typeof zTransactionEntry>
diff --git a/packages/utils/src/index.ts b/packages/utils/src/index.ts
@@ -32,7 +32,7 @@ export {
   type InferOutputUnion,
 } from './parse'
 export { joinUriParts } from './path'
-export type { Optional, OrPromise, Simplify, StringWithAutoCompletion } from './type'
+export type { Optional, OrPromise, Simplify, StringWithAutoCompletion, NonEmptyArray } from './type'
 export { getQueryParams, objectToQueryParams } from './url'
 export { type ZodFetcher, createZodFetcher, createFetcher } from './fetcher'
 export {
diff --git a/packages/utils/src/type.ts b/packages/utils/src/type.ts
@@ -2,3 +2,4 @@ export type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {}
 export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
 export type StringWithAutoCompletion<T extends string> = T | (string & {})
 export type OrPromise<T> = T | Promise<T>
+export type NonEmptyArray<T> = [T, ...T[]]

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@openid4vc/openid4vp": minor
 +---
++
 +feat: support multi-presentation submission for transaction data (dcql multiple feature)