Merge pull request #525 from ForgeRock/well-known

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

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

@@ -8,12 +8,14 @@
   "author": "",
   "main": "./index.js",
   "dependencies": {
-    "@types/express": "^4.17.17",
-    "body-parser": "^2.2.0",
+    "body-parser": "^2.2.2",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
-    "express": "^4.21.2",
+    "express": "^5.2.1",
     "superagent": "^10.2.3",
     "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@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/am-mock-api/src/app/routes.resource.js

@@ -63,7 +63,7 @@ async function authorization(req, res, next) {
 
 export default function (app) {
   // Passthrough route that enforces authentication
-  app.all('/resource/*', async (req, res, next) => {
+  app.all('/resource/{*splat}', async (req, res, next) => {
     if (env.NODE_ENV === 'LIVE' && req.hostname === FORGEOPS) {
       // Only enforce authentication if IG is not used
       // In other words, the call comes directly from app
@@ -156,7 +156,7 @@ export default function (app) {
     }
   });
 
-  app.get('/resource/rest/*', wait, authorization, async (req, res) => {
+  app.get('/resource/rest/{*splat}', wait, authorization, async (req, res) => {
     if (env.NODE_ENV === 'live') {
       if (req.access.actions && req.access.actions.GET) {
         res.json({ message: 'Successfully retrieved resource!' });

e2e/davinci-app/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@forgerock/davinci-app",
   "version": "0.0.0",
+  "private": true,
   "description": "Ping DaVinci Client Test App",
   "type": "module",
-  "private": true,
-  "nx": {
-    "tags": ["scope:e2e"]
-  },
   "scripts": {
     "build": "pnpm nx nxBuild",
     "lint": "pnpm nx nxLint",
@@ -16,8 +13,11 @@
   "dependencies": {
     "@forgerock/davinci-client": "workspace:*",
     "@forgerock/javascript-sdk": "4.7.0",
-    "@forgerock/sdk-logger": "workspace:*",
-    "@forgerock/protect": "workspace:*"
+    "@forgerock/protect": "workspace:*",
+    "@forgerock/sdk-logger": "workspace:*"
   },
-  "devDependencies": {}
+  "devDependencies": {},
+  "nx": {
+    "tags": ["scope:e2e"]
+  }
 }

e2e/davinci-app/tsconfig.json

@@ -14,15 +14,6 @@
     "skipLibCheck": true
   },
   "references": [
-    {
-      "path": "../../packages/sdk-effects/logger"
-    },
-    {
-      "path": "../../packages/protect"
-    },
-    {
-      "path": "../../packages/davinci-client"
-    },
     {
       "path": "./tsconfig.app.json"
     },

e2e/device-client-app/package.json

@@ -13,10 +13,10 @@
     "@forgerock/javascript-sdk": "4.7.0",
     "effect": "^3.12.7"
   },
-  "nx": {
-    "tags": ["scope:e2e"]
-  },
   "devDependencies": {
     "@effect/language-service": "^0.20.0"
+  },
+  "nx": {
+    "tags": ["scope:e2e"]
   }
 }

e2e/device-client-app/tsconfig.json

@@ -3,9 +3,6 @@
   "files": [],
   "include": [],
   "references": [
-    {
-      "path": "../../packages/device-client"
-    },
     {
       "path": "./tsconfig.app.json"
     }

e2e/journey-app/main.ts

@@ -8,7 +8,7 @@ import './style.css';
 
 import { journey } from '@forgerock/journey-client';
 
-import type { RequestMiddleware } from '@forgerock/journey-client/types';
+import type { JourneyClient, RequestMiddleware } from '@forgerock/journey-client/types';
 
 import { renderCallbacks } from './callback-map.js';
 import { renderQRCodeStep } from './components/qr-code.js';
@@ -40,7 +40,7 @@ if (searchParams.get('middleware') === 'true') {
     },
     (req, action, next) => {
       switch (action.type) {
-        case 'END_SESSION':
+        case 'JOURNEY_TERMINATE':
           req.url.searchParams.set('end-session-middleware', 'end-session');
           req.headers.append('x-end-session-middleware', 'end-session');
           break;
@@ -51,12 +51,19 @@ 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;
 
+  let journeyClient: JourneyClient;
+  try {
+    journeyClient = await journey({ config: config, requestMiddleware });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    console.error('Failed to initialize journey client:', message);
+    errorEl.textContent = message;
+    return;
+  }
   let step = await journeyClient.start({ journey: journeyName });
 
   function renderComplete() {