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

Re-implement well known configuration and abstract into reusable package
  - Remove internal re-export file (wellknown.api.ts)
  - Import directly from source packages in internal modules
  - Keep consumer-facing exports in types.ts as the single public API
  - Add IPv6 localhost comment explaining design decision
  - Remove redundant inline comments (JSDoc is sufficient)

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`.

.changeset/wellknown-only-config.md

@@ -0,0 +1,45 @@
+---
+'@forgerock/journey-client': major
+---
+
+BREAKING: Unify journey-client around wellknown-only configuration
+
+This release simplifies the configuration API by requiring the `wellknown` URL and automatically inferring `baseUrl` and `realmPath`.
+
+## Breaking Changes
+
+- **Removed `baseUrl` from `JourneyServerConfig`**: The `baseUrl` is now always inferred from the wellknown URL. If inference fails (non-AM server), an error is returned.
+- **Removed `hasWellknownConfig` export**: This type guard is no longer needed since all configs use wellknown.
+
+## Migration
+
+**Before:**
+
+```typescript
+journey({
+  config: {
+    serverConfig: { baseUrl: 'https://am.example.com/am/' },
+    realmPath: 'alpha',
+  },
+});
+```
+
+**After:**
+
+```typescript
+journey({
+  config: {
+    serverConfig: {
+      wellknown: 'https://am.example.com/am/oauth2/alpha/.well-known/openid-configuration',
+    },
+    // realmPath is now optional - inferred from wellknown issuer
+  },
+});
+```
+
+## Features
+
+- Automatic `baseUrl` inference from wellknown URL (extracts path before `/oauth2/`)
+- Automatic `realmPath` inference from wellknown issuer
+- Improved error messages for non-AM servers, guiding users to appropriate clients
+- Updated README with comprehensive API documentation

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/am-mock-api/src/app/routes.auth.js

@@ -668,6 +668,11 @@ export default function (app) {
     res.send(wellKnownForgeRock);
   });
 
+  // Standard AM wellknown endpoint path (used by journey-client wellknown discovery)
+  app.get('/am/oauth2/realms/root/.well-known/openid-configuration', (req, res) => {
+    res.send(wellKnownForgeRock);
+  });
+
   app.get('/as/.well-known/new-oidc-configuration', (req, res) => {
     res.send(newPiWellKnown);
   });

e2e/journey-app/main.ts

@@ -6,7 +6,7 @@
  */
 import './style.css';
 
-import { journey } from '@forgerock/journey-client';
+import { journey, isJourneyClient } from '@forgerock/journey-client';
 
 import type { RequestMiddleware } from '@forgerock/journey-client/types';
 
@@ -51,12 +51,23 @@ if (searchParams.get('middleware') === 'true') {
 }
 
 (async () => {
-  const journeyClient = await journey({ config: config, requestMiddleware });
-
   const errorEl = document.getElementById('error') as HTMLDivElement;
   const formEl = document.getElementById('form') as HTMLFormElement;
   const journeyEl = document.getElementById('journey') as HTMLDivElement;
 
+  const journeyClientResult = await journey({ config: config, requestMiddleware });
+  if (!isJourneyClient(journeyClientResult)) {
+    console.error('Failed to initialize journey client:', journeyClientResult.message);
+    errorEl.textContent = journeyClientResult.message ?? 'Unknown error';
+    return;
+  }
+  /**
+   * Re-assign to a new const after type narrowing.
+   * TypeScript's type narrowing doesn't persist into closures (event handlers, callbacks)
+   * because it can't prove the variable wasn't reassigned between the guard and closure execution.
+   * Creating a new const binding after the guard preserves the narrowed type for nested functions.
+   */
+  const journeyClient = journeyClientResult;
   let step = await journeyClient.start({ journey: journeyName });
 
   function renderComplete() {

e2e/journey-app/server-configs.ts

@@ -6,17 +6,27 @@
  */
 import type { JourneyClientConfig } from '@forgerock/journey-client/types';
 
+/**
+ * Server configurations for E2E tests.
+ *
+ * Both baseUrl and realmPath are automatically inferred from the wellknown URL:
+ * - baseUrl: extracted from the path before `/oauth2/`
+ * - realmPath: extracted from the issuer URL in the wellknown response
+ */
 export const serverConfigs: Record<string, JourneyClientConfig> = {
   basic: {
     serverConfig: {
-      baseUrl: 'http://localhost:9443/am',
+      wellknown: 'http://localhost:9443/am/oauth2/realms/root/.well-known/openid-configuration',
+      // baseUrl inferred: http://localhost:9443/am/
+      // realmPath inferred from issuer: 'root'
     },
-    realmPath: 'root',
   },
   tenant: {
     serverConfig: {
-      baseUrl: 'https://openam-sdks.forgeblocks.com/am',
+      wellknown:
+        'https://openam-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
+      // baseUrl inferred: https://openam-sdks.forgeblocks.com/am/
+      // realmPath inferred from issuer: 'alpha'
     },
-    realmPath: 'alpha',
   },
 };

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>({