Merge pull request #262 from TimoGlastra/fix/oid4vp-error-response

feat: support authorization error  response for oid4vp response

Author: marsouin

.changeset/openid4vp-authorization-error-response.md

@@ -0,0 +1,5 @@
+---
+"@openid4vc/openid4vp": patch
+---
+
+Support parsing OpenID4VP Authorization Error Responses. When the wallet returns an authorization error response (e.g. it detected an error with the request, or is unavailable) instead of a successful response containing a `vp_token`, `parseOpenid4VpAuthorizationResponsePayload` (and `parseOpenid4vpAuthorizationResponse`) now throws an `Openid4vpAuthorizationResponseError` with the parsed `errorResponse`, instead of a confusing zod error about the missing `vp_token`.

packages/openid4vp/src/authorization-response/Openid4vpAuthorizationResponseError.ts

@@ -0,0 +1,17 @@
+import { Oauth2Error, type Oauth2ErrorOptions } from '@openid4vc/oauth2'
+import type { Openid4vpAuthorizationErrorResponse } from './z-authorization-response'
+
+/**
+ * Error thrown when the wallet returns an OpenID4VP Authorization Error Response
+ * (e.g. the wallet detected an error with the request, or is unavailable) instead
+ * of a successful Authorization Response containing a `vp_token`.
+ */
+export class Openid4vpAuthorizationResponseError extends Oauth2Error {
+  public constructor(
+    message: string,
+    public readonly errorResponse: Openid4vpAuthorizationErrorResponse,
+    options?: Oauth2ErrorOptions
+  ) {
+    super(`${message}\n${JSON.stringify(errorResponse, null, 2)}`, options)
+  }
+}

packages/openid4vp/src/authorization-response/__tests__/parse-authorization-response-payload.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'vitest'
+import { Openid4vpAuthorizationResponseError } from '../Openid4vpAuthorizationResponseError'
 import { parseOpenid4VpAuthorizationResponsePayload } from '../parse-authorization-response-payload'
 
 describe('parseOpenid4VpAuthorizationResponsePayload', () => {
@@ -26,4 +27,41 @@ describe('parseOpenid4VpAuthorizationResponsePayload', () => {
       },
     })
   })
+
+  test('should throw an Openid4vpAuthorizationResponseError when the wallet returns an authorization error response', () => {
+    // Non-normative example of an Authorization Error Response from the OpenID4VP spec.
+    const parsedPayload = Object.fromEntries(
+      new URLSearchParams(
+        'error=invalid_request&error_description=unsupported%20client_id_prefix&state=eyJhb...6-sVA'
+      ).entries()
+    )
+
+    let error: unknown
+    try {
+      parseOpenid4VpAuthorizationResponsePayload(parsedPayload)
+    } catch (e) {
+      error = e
+    }
+
+    expect(error).toBeInstanceOf(Openid4vpAuthorizationResponseError)
+    expect((error as Openid4vpAuthorizationResponseError).errorResponse).toEqual({
+      error: 'invalid_request',
+      error_description: 'unsupported client_id_prefix',
+      state: 'eyJhb...6-sVA',
+    })
+  })
+
+  test('should throw an Openid4vpAuthorizationResponseError for an error response without additional parameters', () => {
+    let error: unknown
+    try {
+      parseOpenid4VpAuthorizationResponsePayload({ error: 'wallet_unavailable' })
+    } catch (e) {
+      error = e
+    }
+
+    expect(error).toBeInstanceOf(Openid4vpAuthorizationResponseError)
+    expect((error as Openid4vpAuthorizationResponseError).errorResponse).toEqual({
+      error: 'wallet_unavailable',
+    })
+  })
 })

packages/openid4vp/src/authorization-response/parse-authorization-response-payload.ts

@@ -1,7 +1,25 @@
 import { parseWithErrorHandling } from '@openid4vc/utils'
-import { zOpenid4vpAuthorizationResponse } from './z-authorization-response'
+import { Openid4vpAuthorizationResponseError } from './Openid4vpAuthorizationResponseError'
+import { zOpenid4vpAuthorizationErrorResponse, zOpenid4vpAuthorizationResponse } from './z-authorization-response'
 
 export function parseOpenid4VpAuthorizationResponsePayload(payload: Record<string, unknown>) {
+  // A wallet can return an authorization error response (e.g. if it detected an error
+  // with the request, or is unavailable) instead of a successful authorization response.
+  // We detect this based on the presence of the `error` parameter and throw a dedicated
+  // error, instead of a confusing zod error about the missing `vp_token`.
+  if (typeof payload.error === 'string') {
+    const errorResponse = parseWithErrorHandling(
+      zOpenid4vpAuthorizationErrorResponse,
+      payload,
+      'Failed to parse openid4vp authorization error response.'
+    )
+
+    throw new Openid4vpAuthorizationResponseError(
+      'The wallet returned an openid4vp authorization error response.',
+      errorResponse
+    )
+  }
+
   return parseWithErrorHandling(
     zOpenid4vpAuthorizationResponse,
     payload,

packages/openid4vp/src/authorization-response/z-authorization-response.ts

@@ -1,3 +1,4 @@
+import { zOauth2ErrorResponse } from '@openid4vc/oauth2'
 import { zStringToJson } from '@openid4vc/utils'
 import { z } from 'zod'
 import { zPexPresentationSubmission } from '../models/z-pex'
@@ -13,6 +14,20 @@ export const zOpenid4vpAuthorizationResponse = z
     token_type: z.string().optional(),
     access_token: z.string().optional(),
     expires_in: z.coerce.number().optional(),
+
+    // This allows for discriminating between error and success responses.
+    error: z.optional(z.never()),
   })
   .loose()
 export type Openid4vpAuthorizationResponse = z.infer<typeof zOpenid4vpAuthorizationResponse>
+
+export const zOpenid4vpAuthorizationErrorResponse = z
+  .object({
+    ...zOauth2ErrorResponse.shape,
+    state: z.string().optional(),
+
+    // This allows for discriminating between error and success responses.
+    vp_token: z.optional(z.never()),
+  })
+  .loose()
+export type Openid4vpAuthorizationErrorResponse = z.infer<typeof zOpenid4vpAuthorizationErrorResponse>

packages/openid4vp/src/index.ts

@@ -38,6 +38,7 @@ export {
   type CreateOpenid4vpAuthorizationResponseResult,
   createOpenid4vpAuthorizationResponse,
 } from './authorization-response/create-authorization-response'
+export { Openid4vpAuthorizationResponseError } from './authorization-response/Openid4vpAuthorizationResponseError'
 export {
   type ParsedOpenid4vpAuthorizationResponse,
   type ParseOpenid4vpAuthorizationResponseOptions,
@@ -62,7 +63,9 @@ export type {
   ValidateOpenid4VpPexAuthorizationResponseResult,
 } from './authorization-response/validate-authorization-response-result'
 export {
+  type Openid4vpAuthorizationErrorResponse,
   type Openid4vpAuthorizationResponse,
+  zOpenid4vpAuthorizationErrorResponse,
   zOpenid4vpAuthorizationResponse,
 } from './authorization-response/z-authorization-response'
 export {