feat(oauth2): support for refresh tokens

Signed-off-by: Henrique Dias <mail@hacdias.com>

Author: hacdias

.changeset/rare-oranges-eat.md

@@ -0,0 +1,5 @@
+---
+"@openid4vc/oauth2": patch
+---
+
+Add authorization server support for refresh tokens, as well as verifying requests with refresh token grants.

packages/oauth2/src/Oauth2AuthorizationServer.ts

@@ -1,4 +1,4 @@
-import { parseWithErrorHandling } from '@openid4vc/utils'
+import { encodeToBase64Url, parseWithErrorHandling } from '@openid4vc/utils'
 import { type CreateAccessTokenOptions, createAccessTokenJwt } from './access-token/create-access-token'
 import {
   type CreateAccessTokenResponseOptions,
@@ -8,8 +8,10 @@ import { type ParseAccessTokenRequestOptions, parseAccessTokenRequest } from './
 import {
   type VerifyAuthorizationCodeAccessTokenRequestOptions,
   type VerifyPreAuthorizedCodeAccessTokenRequestOptions,
+  type VerifyRefreshTokenAccessTokenRequestOptions,
   verifyAuthorizationCodeAccessTokenRequest,
   verifyPreAuthorizedCodeAccessTokenRequest,
+  verifyRefreshTokenAccessTokenRequest,
 } from './access-token/verify-access-token-request'
 import {
   type CreateAuthorizationChallengeErrorResponseOptions,
@@ -95,12 +97,22 @@ export class Oauth2AuthorizationServer {
     })
   }
 
+  public verifyRefreshTokenAccessTokenRequest(options: Omit<VerifyRefreshTokenAccessTokenRequestOptions, 'callbacks'>) {
+    return verifyRefreshTokenAccessTokenRequest({
+      ...options,
+      callbacks: this.options.callbacks,
+    })
+  }
+
   /**
    * Create an access token response.
    *
    * The `sub` claim can be used to identify the resource owner is subsequent requests.
    * For pre-auth flow this can be the pre-authorized_code but there are no requirements
    * on the value.
+   *
+   * To generate a refresh token, set the `refreshToken` option to `true`. You can
+   * also provide a custom refresh token string.
    */
   public async createAccessTokenResponse(
     options: Pick<
@@ -118,6 +130,7 @@ export class Oauth2AuthorizationServer {
       Pick<CreateAccessTokenResponseOptions, 'cNonce' | 'cNonceExpiresIn'> & {
         additionalAccessTokenPayload?: CreateAccessTokenOptions['additionalPayload']
         additionalAccessTokenResponsePayload?: CreateAccessTokenResponseOptions['additionalPayload']
+        refreshToken?: boolean | string
       }
   ) {
     const { jwt: accessToken } = await createAccessTokenJwt({
@@ -136,6 +149,12 @@ export class Oauth2AuthorizationServer {
 
     return createAccessTokenResponse({
       accessToken,
+      refreshToken:
+        typeof options.refreshToken === 'string'
+          ? options.refreshToken
+          : options.refreshToken
+            ? encodeToBase64Url(await this.options.callbacks.generateRandom(32))
+            : undefined,
       callbacks: this.options.callbacks,
       expiresInSeconds: options.expiresInSeconds,
       tokenType: options.dpop ? 'DPoP' : 'Bearer',

packages/oauth2/src/access-token/__tests__/parse-access-token-request.test.mts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from 'vitest'
 import { Oauth2ServerErrorResponseError } from '../../error/Oauth2ServerErrorResponseError.js'
-import { authorizationCodeGrantIdentifier, preAuthorizedCodeGrantIdentifier } from '../../z-grant-type.js'
+import {
+  authorizationCodeGrantIdentifier,
+  preAuthorizedCodeGrantIdentifier,
+  refreshTokenGrantIdentifier,
+} from '../../z-grant-type.js'
 import { parseAccessTokenRequest } from '../parse-access-token-request.js'
 
 describe('Parse Access Token Request', () => {
@@ -47,7 +51,7 @@ describe('Parse Access Token Request', () => {
     ).toThrow(`The grant type 'something' is not supported`)
   })
 
-  test('handles mising pre-authorized_code for pre-auth grant_type', () => {
+  test('handles missing pre-authorized_code for pre-auth grant_type', () => {
     expect(() =>
       parseAccessTokenRequest({
         accessTokenRequest: {
@@ -62,7 +66,7 @@ describe('Parse Access Token Request', () => {
     ).toThrow(`Missing required 'pre-authorized_code' for grant type '${preAuthorizedCodeGrantIdentifier}'`)
   })
 
-  test('handles mising code for authorization_code grant_type', () => {
+  test('handles missing code for authorization_code grant_type', () => {
     expect(() =>
       parseAccessTokenRequest({
         accessTokenRequest: {
@@ -168,7 +172,34 @@ describe('Parse Access Token Request', () => {
     })
   })
 
-  test('handles invalid dpop jwt', () => {
+  test('handles refresh token grant', () => {
+    expect(
+      parseAccessTokenRequest({
+        accessTokenRequest: {
+          grant_type: refreshTokenGrantIdentifier,
+          refresh_token: 'mamma-mia',
+        },
+        request: {
+          headers: new Headers({}),
+          method: 'POST',
+          url: 'https://request.com/token',
+        },
+      })
+    ).toEqual({
+      accessTokenRequest: {
+        grant_type: refreshTokenGrantIdentifier,
+        refresh_token: 'mamma-mia',
+      },
+      grant: {
+        grantType: refreshTokenGrantIdentifier,
+        refreshToken: 'mamma-mia',
+      },
+      dpopJwt: undefined,
+      pkceCodeVerifier: undefined,
+    })
+  })
+
+  test('handles invalid dpop jwt', () =>
     expect(() =>
       parseAccessTokenRequest({
         accessTokenRequest: {
@@ -193,10 +224,9 @@ describe('Parse Access Token Request', () => {
         error: 'invalid_dpop_proof',
         error_description: `Request contains a 'DPoP' header, but the value is not a valid DPoP jwt`,
       })
-    )
-  })
+    ))
 
-  test('handles invalid client attestation jwt', () => {
+  test('handles invalid client attestation jwt', () =>
     expect(() =>
       parseAccessTokenRequest({
         accessTokenRequest: {
@@ -220,6 +250,5 @@ describe('Parse Access Token Request', () => {
         error_description:
           'Request contains client attestation header, but the values are not valid client attestation and client attestation PoP header.',
       })
-    )
-  })
+    ))
 })