feat: require a PKCE-style code challenge and verifier for ORCID sign-up

GetOrcidSignUpAuthorizationUrl now takes a codeChallenge (base64url SHA-256
of a random code verifier), and ConnectOrcidForSignUp sends the matching
codeVerifier, as required by IQSS/dataverse#12858.

Author: ChengShi-1

docs/useCases.md

@@ -2792,7 +2792,9 @@ _See [use case](../src/users/domain/useCases/GetCurrentApiToken.ts) implementati
 
 Returns the ORCID authorization URL that sends a new user to ORCID to authenticate their ORCID iD while signing up. Send the user's browser to this URL; after they sign in, ORCID redirects back to `redirectUri` with `code` and `state` query parameters, which are then passed to [Connect ORCID For Sign-Up](#connect-orcid-for-sign-up).
 
-No credentials are sent, so this works for anonymous users. The installation needs an ORCID OAuth2 provider (it can be disabled for login), and `redirectUri` must be listed in its `dataverse.api.signup.orcid-redirect-uris` setting.
+No credentials are sent, so this works for anonymous users. The installation needs an ORCID OAuth2 provider (it can be disabled for login), and `redirectUri` must be allowed by the installation: by default, its site URL followed by `/modern/sign-up`, or a URL listed in its `dataverse.api.signup.orcid-redirect-uris` setting.
+
+As with PKCE, create a random code verifier first and keep it (for example in `sessionStorage`). Pass its base64url-encoded SHA-256 hash as `codeChallenge`, and the verifier itself to [Connect ORCID For Sign-Up](#connect-orcid-for-sign-up). An ORCID response can then only be used by the browser that started the flow.
 
 ##### Example call:
 
@@ -2801,18 +2803,32 @@ import { getOrcidSignUpAuthorizationUrl } from '@iqss/dataverse-client-javascrip
 
 /* ... */
 
-const redirectUri = 'https://dataverse.example.edu/spa/sign-up'
+const redirectUri = 'https://dataverse.example.edu/modern/sign-up'
 
-getOrcidSignUpAuthorizationUrl.execute(redirectUri).then((authorizationUrl: string) => {
-  window.location.assign(authorizationUrl)
-})
+const toBase64Url = (bytes: Uint8Array) =>
+  btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+
+const codeVerifier = toBase64Url(crypto.getRandomValues(new Uint8Array(32)))
+sessionStorage.setItem('orcidCodeVerifier', codeVerifier)
+const codeChallenge = toBase64Url(
+  new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier)))
+)
+
+getOrcidSignUpAuthorizationUrl
+  .execute(redirectUri, codeChallenge)
+  .then((authorizationUrl: string) => {
+    window.location.assign(authorizationUrl)
+  })
 
 /* ... */
 ```
 
 _See [use case](../src/users/domain/useCases/GetOrcidSignUpAuthorizationUrl.ts) implementation_.
 
-The use case throws a `ReadError` with `statusCode` 404 when no ORCID provider is configured, and 400 when the redirect URI is not allowed.
+The use case throws a `ReadError` with `statusCode` 404 when no ORCID provider is configured, and 400 when the redirect URI is not allowed or the code challenge is missing or invalid.
 
 ### Users write use cases
 
@@ -2927,7 +2943,7 @@ The [SignUpResult](../src/users/domain/models/SignUpResult.ts) is `{ status: 'cr
 
 ### Connect ORCID For Sign-Up
 
-Exchanges the `code` and `state` that ORCID returns to the redirect URI for the user's authenticated ORCID iD, given an [OrcidSignUpCallbackDTO](../src/users/domain/dtos/OrcidSignUpCallbackDTO.ts). Use the same `redirectUri` that was passed to [Get ORCID Sign-Up Authorization URL](#get-orcid-sign-up-authorization-url). No credentials are sent.
+Exchanges the `code` and `state` that ORCID returns to the redirect URI for the user's authenticated ORCID iD, given an [OrcidSignUpCallbackDTO](../src/users/domain/dtos/OrcidSignUpCallbackDTO.ts). Use the same `redirectUri` that was passed to [Get ORCID Sign-Up Authorization URL](#get-orcid-sign-up-authorization-url), and the `codeVerifier` whose hash was passed there as `codeChallenge`. No credentials are sent.
 
 Returns an [OrcidSignUpConnection](../src/users/domain/models/OrcidSignUpConnection.ts) with the ORCID iD, any details the user shares on their ORCID record (useful to pre-fill a sign-up form), and an `orcidToken` to include in [Sign Up](#sign-up). The token is valid for 30 minutes.
 
@@ -2944,7 +2960,8 @@ connectOrcidForSignUp
   .execute({
     code: params.get('code') as string,
     state: params.get('state') as string,
-    redirectUri: 'https://dataverse.example.edu/spa/sign-up'
+    redirectUri: 'https://dataverse.example.edu/modern/sign-up',
+    codeVerifier: sessionStorage.getItem('orcidCodeVerifier') as string
   })
   .then((connection: OrcidSignUpConnection) => {
     /* connection.orcid, connection.firstName, ..., connection.orcidToken */
@@ -2955,7 +2972,7 @@ connectOrcidForSignUp
 
 _See [use case](../src/users/domain/useCases/ConnectOrcidForSignUp.ts) implementation_.
 
-The use case throws a `WriteError` with `statusCode` 409 when the ORCID iD is already linked to another account, and 400 when the state is invalid or expired.
+The use case throws a `WriteError` with `statusCode` 409 when the ORCID iD is already linked to another account, and 400 when the state is invalid or expired, or the code verifier doesn't match the code challenge.
 
 ## Roles
 

src/users/domain/dtos/OrcidSignUpCallbackDTO.ts

@@ -2,4 +2,5 @@ export interface OrcidSignUpCallbackDTO {
   code: string
   state: string
   redirectUri: string
+  codeVerifier: string
 }

src/users/domain/repositories/IUsersRepository.ts

@@ -13,6 +13,6 @@ export interface IUsersRepository {
   deleteCurrentApiToken(): Promise<void>
   registerUser(userDTO: UserDTO): Promise<void>
   signUp(signUpDTO: SignUpDTO): Promise<SignUpResult>
-  getOrcidSignUpAuthorizationUrl(redirectUri: string): Promise<string>
+  getOrcidSignUpAuthorizationUrl(redirectUri: string, codeChallenge: string): Promise<string>
   connectOrcidForSignUp(callback: OrcidSignUpCallbackDTO): Promise<OrcidSignUpConnection>
 }

src/users/domain/useCases/GetOrcidSignUpAuthorizationUrl.ts

@@ -13,10 +13,11 @@ export class GetOrcidSignUpAuthorizationUrl implements UseCase<string> {
    * No authentication is used.
    *
    * @param {string} [redirectUri] - The URL ORCID redirects back to. Must be allowed by the installation's dataverse.api.signup.orcid-redirect-uris setting.
+   * @param {string} [codeChallenge] - The base64url-encoded SHA-256 hash of a random code verifier that the client keeps and later passes to connectOrcidForSignUp, as for PKCE S256.
    * @returns {Promise<string>} - The ORCID authorization URL.
-   * @throws {ReadError} - If ORCID is not configured, or the redirect URI is not allowed.
+   * @throws {ReadError} - If ORCID is not configured, or the redirect URI or code challenge is not valid.
    */
-  async execute(redirectUri: string): Promise<string> {
-    return await this.usersRepository.getOrcidSignUpAuthorizationUrl(redirectUri)
+  async execute(redirectUri: string, codeChallenge: string): Promise<string> {
+    return await this.usersRepository.getOrcidSignUpAuthorizationUrl(redirectUri, codeChallenge)
   }
 }

src/users/infra/repositories/UsersRepository.ts

@@ -77,8 +77,14 @@ export class UsersRepository extends ApiRepository implements IUsersRepository {
       })
   }
 
-  public async getOrcidSignUpAuthorizationUrl(redirectUri: string): Promise<string> {
-    return this.doGet(`/${this.usersResourceName}/signup/orcid/authorize`, false, { redirectUri })
+  public async getOrcidSignUpAuthorizationUrl(
+    redirectUri: string,
+    codeChallenge: string
+  ): Promise<string> {
+    return this.doGet(`/${this.usersResourceName}/signup/orcid/authorize`, false, {
+      redirectUri,
+      codeChallenge
+    })
       .then((response) => response.data.data.authorizationUrl)
       .catch((error) => {
         throw error

test/integration/users/UsersRepository.test.ts

@@ -201,7 +201,9 @@ describe('UsersRepository', () => {
 
     test('getOrcidSignUpAuthorizationUrl should return a 404 ReadError', async () => {
       let error: ReadError | undefined = undefined
-      await sut.getOrcidSignUpAuthorizationUrl(redirectUri).catch((e) => (error = e))
+      await sut
+        .getOrcidSignUpAuthorizationUrl(redirectUri, 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM')
+        .catch((e) => (error = e))
 
       expect(error).toBeInstanceOf(ReadError)
       expect((error as unknown as ReadError).statusCode).toBe(404)
@@ -213,7 +215,12 @@ describe('UsersRepository', () => {
     test('connectOrcidForSignUp should return a 404 WriteError', async () => {
       let error: WriteError | undefined = undefined
       await sut
-        .connectOrcidForSignUp({ code: 'code', state: 'state', redirectUri })
+        .connectOrcidForSignUp({
+          code: 'code',
+          state: 'state',
+          redirectUri,
+          codeVerifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
+        })
         .catch((e) => (error = e))
 
       expect(error).toBeInstanceOf(WriteError)

test/unit/users/ConnectOrcidForSignUp.test.ts

@@ -6,7 +6,8 @@ describe('execute', () => {
   const callback: OrcidSignUpCallbackDTO = {
     code: 'orcid-code',
     state: 'orcid-state',
-    redirectUri: 'http://127.0.0.1:8000/spa/sign-up'
+    redirectUri: 'http://127.0.0.1:8000/spa/sign-up',
+    codeVerifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
   }
 
   test('should return the ORCID connection on repository success', async () => {

test/unit/users/GetOrcidSignUpAuthorizationUrl.test.ts

@@ -4,6 +4,7 @@ import { ReadError } from '../../../src'
 
 describe('execute', () => {
   const redirectUri = 'http://127.0.0.1:8000/spa/sign-up'
+  const codeChallenge = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'
 
   test('should return the authorization URL on repository success', async () => {
     const usersRepositoryStub: IUsersRepository = {} as IUsersRepository
@@ -12,9 +13,12 @@ describe('execute', () => {
       .mockResolvedValue('https://orcid.org/oauth/authorize?client_id=APP-1')
     const sut = new GetOrcidSignUpAuthorizationUrl(usersRepositoryStub)
 
-    const actual = await sut.execute(redirectUri)
+    const actual = await sut.execute(redirectUri, codeChallenge)
 
-    expect(usersRepositoryStub.getOrcidSignUpAuthorizationUrl).toHaveBeenCalledWith(redirectUri)
+    expect(usersRepositoryStub.getOrcidSignUpAuthorizationUrl).toHaveBeenCalledWith(
+      redirectUri,
+      codeChallenge
+    )
     expect(actual).toBe('https://orcid.org/oauth/authorize?client_id=APP-1')
   })
 
@@ -25,6 +29,6 @@ describe('execute', () => {
       .mockRejectedValue(new ReadError())
     const sut = new GetOrcidSignUpAuthorizationUrl(usersRepositoryStub)
 
-    await expect(sut.execute(redirectUri)).rejects.toThrow(ReadError)
+    await expect(sut.execute(redirectUri, codeChallenge)).rejects.toThrow(ReadError)
   })
 })

test/unit/users/UsersRepository.test.ts

@@ -185,6 +185,7 @@ describe('signUp', () => {
 describe('getOrcidSignUpAuthorizationUrl', () => {
   const sut: UsersRepository = new UsersRepository()
   const redirectUri = 'http://127.0.0.1:8000/spa/sign-up'
+  const codeChallenge = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'
 
   beforeEach(() => {
     ApiConfig.init(
@@ -203,11 +204,14 @@ describe('getOrcidSignUpAuthorizationUrl', () => {
       }
     })
 
-    const actual = await sut.getOrcidSignUpAuthorizationUrl(redirectUri)
+    const actual = await sut.getOrcidSignUpAuthorizationUrl(redirectUri, codeChallenge)
 
     expect(axios.get).toHaveBeenCalledWith(
       `${TestConstants.TEST_API_URL}/users/signup/orcid/authorize`,
-      { ...TestConstants.TEST_EXPECTED_UNAUTHENTICATED_REQUEST_CONFIG, params: { redirectUri } }
+      {
+        ...TestConstants.TEST_EXPECTED_UNAUTHENTICATED_REQUEST_CONFIG,
+        params: { redirectUri, codeChallenge }
+      }
     )
     expect(actual).toBe('https://orcid.org/oauth/authorize?client_id=APP-1')
   })
@@ -221,7 +225,7 @@ describe('getOrcidSignUpAuthorizationUrl', () => {
     })
 
     let error: ReadError | undefined = undefined
-    await sut.getOrcidSignUpAuthorizationUrl(redirectUri).catch((e) => (error = e))
+    await sut.getOrcidSignUpAuthorizationUrl(redirectUri, codeChallenge).catch((e) => (error = e))
 
     expect(error).toBeInstanceOf(ReadError)
     expect((error as unknown as ReadError).statusCode).toBe(404)
@@ -234,7 +238,8 @@ describe('connectOrcidForSignUp', () => {
   const callback = {
     code: 'orcid-code',
     state: 'orcid-state',
-    redirectUri: 'http://127.0.0.1:8000/spa/sign-up'
+    redirectUri: 'http://127.0.0.1:8000/spa/sign-up',
+    codeVerifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
   }
 
   beforeEach(() => {