feat(journey-client): wellknown-endpoint-config-support

Re-implement well known configuration and abstract into reusable package

Author: ryanbas21

.changeset/rich-cows-try.md

@@ -0,0 +1,47 @@
+---
+'@forgerock/journey-client': minor
+'@forgerock/sdk-oidc': minor
+'@forgerock/sdk-utilities': minor
+'@forgerock/davinci-client': patch
+'@forgerock/oidc-client': patch
+---
+
+### @forgerock/journey-client
+
+Add well-known OIDC endpoint discovery support. The journey client can now fetch configuration from the `.well-known/openid-configuration` endpoint:
+
+```typescript
+const client = await journey({
+  serverConfig: {
+    baseUrl: 'https://am.example.com/am/',
+    wellknown:
+      'https://am.example.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
+  },
+});
+```
+
+The realm path can be automatically inferred from the well-known issuer URL.
+
+### @forgerock/sdk-oidc
+
+Add shared well-known module with RTK Query API for OIDC endpoint discovery:
+
+- `wellknownApi` - RTK Query API for fetching well-known configuration
+- `createWellknownSelector` - Selector factory for cached well-known data
+- `createWellknownError` - Typed error creation from fetch failures
+- Re-exports pure utilities from `@forgerock/sdk-utilities`
+
+### @forgerock/sdk-utilities
+
+Add pure well-known utilities:
+
+- `inferRealmFromIssuer` - Extract realm path from AM issuer URLs
+- `isValidWellknownUrl` - Validate well-known URLs (HTTPS required, HTTP allowed for localhost)
+
+### @forgerock/davinci-client
+
+Refactored to use shared well-known module from `@forgerock/sdk-oidc`.
+
+### @forgerock/oidc-client
+
+Refactored to use shared well-known module from `@forgerock/sdk-oidc`.

e2e/am-mock-api/package.json

@@ -16,6 +16,6 @@
     "uuid": "^13.0.0"
   },
   "devDependencies": {
-    "@types/express": "^4.17.17"
+    "@types/express": "^5.0.0"
   }
 }

e2e/mock-api-v2/package.json

@@ -26,7 +26,8 @@
     "nanoid": "5.1.6"
   },
   "devDependencies": {
-    "@effect/vitest": "catalog:effect"
+    "@effect/vitest": "catalog:effect",
+    "vitest": "catalog:vitest"
   },
   "nx": {
     "tags": ["scope:e2e"],

packages/davinci-client/src/lib/client.store.ts

@@ -15,7 +15,7 @@ import { createClientStore, handleUpdateValidateError, RootState } from './clien
 import { nodeSlice } from './node.slice.js';
 import { davinciApi } from './davinci.api.js';
 import { configSlice } from './config.slice.js';
-import { wellknownApi } from './wellknown.api.js';
+import { wellknownApi, createWellknownError } from '@forgerock/sdk-oidc';
 
 import type { ActionTypes, RequestMiddleware } from '@forgerock/sdk-request-middleware';
 /**
@@ -88,14 +88,14 @@ export async function davinci<ActionType extends ActionTypes = ActionTypes>({
     throw error;
   }
 
-  const { data: openIdResponse } = await store.dispatch(
-    wellknownApi.endpoints.wellknown.initiate(config.serverConfig.wellknown),
+  const { data: openIdResponse, error: fetchError } = await store.dispatch(
+    wellknownApi.endpoints.configuration.initiate(config.serverConfig.wellknown),
   );
 
-  if (!openIdResponse) {
-    const error = new Error('error fetching `wellknown` response for OpenId Configuration');
-    log.error(error.message);
-    throw error;
+  if (fetchError || !openIdResponse) {
+    const genericError = createWellknownError(fetchError);
+    log.error(`${genericError.error}: ${genericError.message}`);
+    throw new Error(genericError.message);
   }
 
   store.dispatch(configSlice.actions.set({ ...config, wellknownResponse: openIdResponse }));
@@ -249,11 +249,11 @@ export async function davinci<ActionType extends ActionTypes = ActionTypes>({
 
         return node;
       } catch (err) {
-        const error = err as Error;
-        log.error(error.message);
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        log.error(errorMessage);
         return {
           error: {
-            message: error.message ?? 'An unexpected error occurred during resume operation',
+            message: errorMessage || 'An unexpected error occurred during resume operation',
             type: 'internal_error',
           },
           type: 'internal_error',
@@ -336,10 +336,10 @@ export async function davinci<ActionType extends ActionTypes = ActionTypes>({
           store.dispatch(nodeSlice.actions.update({ id, value, index }));
           return null;
         } catch (err) {
-          const error = err as Error;
+          const errorMessage = err instanceof Error ? err.message : String(err);
           return {
             type: 'internal_error',
-            error: { message: error.message, type: 'internal_error' },
+            error: { message: errorMessage, type: 'internal_error' },
           };
         }
       };

packages/davinci-client/src/lib/client.store.utils.ts

@@ -13,7 +13,7 @@ import { configSlice } from './config.slice.js';
 import { nodeSlice } from './node.slice.js';
 import { davinciApi } from './davinci.api.js';
 import { ErrorNode, ContinueNode, StartNode, SuccessNode } from '../types.js';
-import { wellknownApi } from './wellknown.api.js';
+import { wellknownApi } from '@forgerock/sdk-oidc';
 import { InternalErrorResponse } from './client.types.js';
 
 export function createClientStore<ActionType extends ActionTypes>({

packages/davinci-client/src/lib/config.types.test-d.ts

@@ -6,8 +6,7 @@
  */
 import { describe, expectTypeOf, it } from 'vitest';
 import type { DaVinciConfig, InternalDaVinciConfig } from './config.types.js';
-import type { AsyncLegacyConfigOptions } from '@forgerock/sdk-types';
-import type { WellknownResponse } from './wellknown.types.js';
+import type { AsyncLegacyConfigOptions, WellknownResponse } from '@forgerock/sdk-types';
 
 describe('Config Types', () => {
   describe('DaVinciConfig', () => {
@@ -51,30 +50,9 @@ describe('Config Types', () => {
           authorization_endpoint: 'https://example.com/auth',
           token_endpoint: 'https://example.com/token',
           userinfo_endpoint: 'https://example.com/userinfo',
-          jwks_uri: 'https://example.com/jwks',
-          revocation_endpoint: 'https://example.com/register',
           end_session_endpoint: 'https://example.com/logout',
-          pushed_authorization_request_endpoint: '',
-          check_session_iframe: '',
-          introspection_endpoint: '',
-          device_authorization_endpoint: '',
-          claims_parameter_supported: '',
-          request_parameter_supported: '',
-          request_uri_parameter_supported: '',
-          require_pushed_authorization_requests: '',
-          scopes_supported: [],
-          response_types_supported: [],
-          response_modes_supported: [],
-          grant_types_supported: [],
-          subject_types_supported: [],
-          id_token_signing_alg_values_supported: [],
-          userinfo_signing_alg_values_supported: [],
-          request_object_signing_alg_values_supported: [],
-          token_endpoint_auth_methods_supported: [],
-          token_endpoint_auth_signing_alg_values_supported: [],
-          claim_types_supported: [],
-          claims_supported: [],
-          code_challenge_methods_supported: [],
+          introspection_endpoint: 'https://example.com/introspect',
+          revocation_endpoint: 'https://example.com/revoke',
         },
         responseType: 'code',
         serverConfig: {},
@@ -85,7 +63,6 @@ describe('Config Types', () => {
 
     it('should combine DaVinciConfig and wellknownResponse', () => {
       const config: InternalDaVinciConfig = {
-        // DaVinciConfig properties
         clientId: 'test-client',
         scope: 'openid profile',
         serverConfig: {
@@ -94,36 +71,16 @@ describe('Config Types', () => {
         },
         redirectUri: 'https://app.example.com/callback',
         responseType: 'code',
-        // InternalDaVinciConfig specific property
         wellknownResponse: {
           issuer: 'https://example.com',
           authorization_endpoint: 'https://example.com/auth',
           token_endpoint: 'https://example.com/token',
           userinfo_endpoint: 'https://example.com/userinfo',
-          jwks_uri: 'https://example.com/jwks',
-          revocation_endpoint: 'https://example.com/revoke',
           end_session_endpoint: 'https://example.com/logout',
-          pushed_authorization_request_endpoint: '',
-          check_session_iframe: '',
-          introspection_endpoint: '',
-          device_authorization_endpoint: '',
-          claims_parameter_supported: '',
-          request_parameter_supported: '',
-          request_uri_parameter_supported: '',
-          require_pushed_authorization_requests: '',
-          scopes_supported: [],
-          response_types_supported: [],
-          response_modes_supported: [],
-          grant_types_supported: [],
-          subject_types_supported: [],
-          id_token_signing_alg_values_supported: [],
-          userinfo_signing_alg_values_supported: [],
-          request_object_signing_alg_values_supported: [],
-          token_endpoint_auth_methods_supported: [],
-          token_endpoint_auth_signing_alg_values_supported: [],
-          claim_types_supported: [],
-          claims_supported: [],
-          code_challenge_methods_supported: [],
+          introspection_endpoint: 'https://example.com/introspect',
+          revocation_endpoint: 'https://example.com/revoke',
+          jwks_uri: 'https://example.com/jwks',
+          scopes_supported: ['openid', 'profile'],
         },
       };
       expectTypeOf(config).toMatchTypeOf<InternalDaVinciConfig>();
@@ -132,45 +89,24 @@ describe('Config Types', () => {
 });
 
 describe('WellknownResponse', () => {
-  it('should have all required OIDC properties', () => {
+  it('should have required OIDC properties', () => {
     const wellknown: WellknownResponse = {
       issuer: 'https://example.com',
       authorization_endpoint: 'https://example.com/auth',
       token_endpoint: 'https://example.com/token',
       userinfo_endpoint: 'https://example.com/userinfo',
-      jwks_uri: 'https://example.com/jwks',
-      revocation_endpoint: 'https://example.com/revoke',
       end_session_endpoint: 'https://example.com/logout',
-      pushed_authorization_request_endpoint: '',
-      check_session_iframe: '',
-      introspection_endpoint: '',
-      device_authorization_endpoint: '',
-      claims_parameter_supported: '',
-      request_parameter_supported: '',
-      request_uri_parameter_supported: '',
-      require_pushed_authorization_requests: '',
-      scopes_supported: [],
-      response_types_supported: [],
-      response_modes_supported: [],
-      grant_types_supported: [],
-      subject_types_supported: [],
-      id_token_signing_alg_values_supported: [],
-      userinfo_signing_alg_values_supported: [],
-      request_object_signing_alg_values_supported: [],
-      token_endpoint_auth_methods_supported: [],
-      token_endpoint_auth_signing_alg_values_supported: [],
-      claim_types_supported: [],
-      claims_supported: [],
-      code_challenge_methods_supported: [],
+      introspection_endpoint: 'https://example.com/introspect',
+      revocation_endpoint: 'https://example.com/revoke',
     };
 
     expectTypeOf<WellknownResponse>().toHaveProperty('issuer').toBeString();
     expectTypeOf<WellknownResponse>().toHaveProperty('authorization_endpoint').toBeString();
     expectTypeOf<WellknownResponse>().toHaveProperty('token_endpoint').toBeString();
     expectTypeOf<WellknownResponse>().toHaveProperty('userinfo_endpoint').toBeString();
-    expectTypeOf<WellknownResponse>().toHaveProperty('jwks_uri').toBeString();
-    expectTypeOf<WellknownResponse>().toHaveProperty('revocation_endpoint').toBeString();
     expectTypeOf<WellknownResponse>().toHaveProperty('end_session_endpoint').toBeString();
+    expectTypeOf<WellknownResponse>().toHaveProperty('introspection_endpoint').toBeString();
+    expectTypeOf<WellknownResponse>().toHaveProperty('revocation_endpoint').toBeString();
 
     expectTypeOf(wellknown).toMatchTypeOf<WellknownResponse>();
   });
@@ -181,93 +117,58 @@ describe('WellknownResponse', () => {
       authorization_endpoint: 'https://example.com/auth',
       token_endpoint: 'https://example.com/token',
       userinfo_endpoint: 'https://example.com/userinfo',
-      jwks_uri: 'https://example.com/jwks',
-      revocation_endpoint: 'https://example.com/revoke',
       end_session_endpoint: 'https://example.com/logout',
-      // Optional properties
+      introspection_endpoint: 'https://example.com/introspect',
+      revocation_endpoint: 'https://example.com/revoke',
+      jwks_uri: 'https://example.com/jwks',
       scopes_supported: ['openid', 'profile', 'email'],
       response_types_supported: ['code', 'token'],
       grant_types_supported: ['authorization_code', 'refresh_token'],
       subject_types_supported: ['public'],
       id_token_signing_alg_values_supported: ['RS256'],
       token_endpoint_auth_methods_supported: ['client_secret_basic'],
-      pushed_authorization_request_endpoint: '',
-      check_session_iframe: '',
-      introspection_endpoint: '',
-      device_authorization_endpoint: '',
-      claims_parameter_supported: '',
-      request_parameter_supported: '',
-      request_uri_parameter_supported: '',
-      require_pushed_authorization_requests: '',
-      response_modes_supported: [],
-      userinfo_signing_alg_values_supported: [],
-      request_object_signing_alg_values_supported: [],
-      token_endpoint_auth_signing_alg_values_supported: [],
-      claim_types_supported: [],
-      claims_supported: [],
-      code_challenge_methods_supported: [],
     };
 
-    // Test optional properties are allowed but not required
     expectTypeOf<WellknownResponse>().toHaveProperty('scopes_supported');
     expectTypeOf<WellknownResponse>().toHaveProperty('response_types_supported');
     expectTypeOf<WellknownResponse>().toHaveProperty('grant_types_supported');
+    expectTypeOf<WellknownResponse>().toHaveProperty('jwks_uri');
 
     expectTypeOf(wellknownWithOptionals).toMatchTypeOf<WellknownResponse>();
   });
 
-  it('should validate property types', () => {
-    // Test that array properties must contain strings
-    expectTypeOf<WellknownResponse['scopes_supported']>().toEqualTypeOf<string[]>();
-    expectTypeOf<WellknownResponse['response_types_supported']>().toEqualTypeOf<string[]>();
-    expectTypeOf<WellknownResponse['grant_types_supported']>().toEqualTypeOf<string[]>();
-    expectTypeOf<WellknownResponse['subject_types_supported']>().toEqualTypeOf<string[]>();
+  it('should validate optional array property types', () => {
+    expectTypeOf<WellknownResponse['scopes_supported']>().toEqualTypeOf<string[] | undefined>();
+    expectTypeOf<WellknownResponse['response_types_supported']>().toEqualTypeOf<
+      string[] | undefined
+    >();
+    expectTypeOf<WellknownResponse['grant_types_supported']>().toEqualTypeOf<
+      string[] | undefined
+    >();
+    expectTypeOf<WellknownResponse['subject_types_supported']>().toEqualTypeOf<
+      string[] | undefined
+    >();
     expectTypeOf<WellknownResponse['id_token_signing_alg_values_supported']>().toEqualTypeOf<
-      string[]
+      string[] | undefined
     >();
     expectTypeOf<WellknownResponse['token_endpoint_auth_methods_supported']>().toEqualTypeOf<
-      string[]
+      string[] | undefined
     >();
   });
 
-  it('should enforce URL format for endpoint properties', () => {
+  it('should enforce URL format for required endpoint properties', () => {
     const wellknown: WellknownResponse = {
       issuer: 'https://example.com',
       authorization_endpoint: 'https://example.com/auth',
       token_endpoint: 'https://example.com/token',
       userinfo_endpoint: 'https://example.com/userinfo',
-      jwks_uri: 'https://example.com/jwks',
-      revocation_endpoint: 'https://example.com/register',
       end_session_endpoint: 'https://example.com/logout',
-      pushed_authorization_request_endpoint: '',
-      check_session_iframe: '',
-      introspection_endpoint: '',
-      device_authorization_endpoint: '',
-      claims_parameter_supported: '',
-      request_parameter_supported: '',
-      request_uri_parameter_supported: '',
-      require_pushed_authorization_requests: '',
-      scopes_supported: [],
-      response_types_supported: [],
-      response_modes_supported: [],
-      grant_types_supported: [],
-      subject_types_supported: [],
-      id_token_signing_alg_values_supported: [],
-      userinfo_signing_alg_values_supported: [],
-      request_object_signing_alg_values_supported: [],
-      token_endpoint_auth_methods_supported: [],
-      token_endpoint_auth_signing_alg_values_supported: [],
-      claim_types_supported: [],
-      claims_supported: [],
-      code_challenge_methods_supported: [],
+      introspection_endpoint: 'https://example.com/introspect',
+      revocation_endpoint: 'https://example.com/revoke',
     };
 
-    // Type assertion to ensure all endpoint properties are strings (URLs)
     expectTypeOf(wellknown.authorization_endpoint).toBeString();
     expectTypeOf(wellknown.token_endpoint).toBeString();
     expectTypeOf(wellknown.userinfo_endpoint).toBeString();
-    expectTypeOf(wellknown.jwks_uri).toBeString();
-    expectTypeOf(wellknown.revocation_endpoint).toBeString();
-    expectTypeOf(wellknown.end_session_endpoint).toBeString();
   });
 });