@forgerock/sdk-oidc 1.2.0 → 2.0.0

package/src/lib/state-pkce.effects.ts

@@ -7,9 +7,12 @@
 
 import { createVerifier, createState } from '@forgerock/sdk-utilities';
 
-import type { GetAuthorizationUrlOptions } from './authorize.types.js';
+import type {
+  GenerateAndStoreAuthUrlValues,
+  GetAuthorizationUrlOptions,
+} from '@forgerock/sdk-types';
 
-function getStorageKey(clientId: string, prefix?: string) {
+export function getStorageKey(clientId: string, prefix?: string) {
   return `${prefix || 'FR-SDK'}-authflow-${clientId}`;
 }
 
@@ -19,11 +22,6 @@ function getStorageKey(clientId: string, prefix?: string) {
  * @param {GenerateAndStoreAuthUrlValues} options - Options for generating PKCE values
  * @returns { state: string, verifier: string, GetAuthorizationUrlOptions }
  */
-interface GenerateAndStoreAuthUrlValues extends GetAuthorizationUrlOptions {
-  login?: 'redirect' | 'embedded';
-  clientId: string;
-  prefix?: string;
-}
 
 export function generateAndStoreAuthUrlValues(
   options: GenerateAndStoreAuthUrlValues,

package/src/lib/state-pkce.test.ts

@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { describe, expect, it, beforeEach } from 'vitest';
+import {
+  generateAndStoreAuthUrlValues,
+  getStorageKey,
+  getStoredAuthUrlValues,
+} from './state-pkce.effects.js';
+import type { GenerateAndStoreAuthUrlValues } from '@forgerock/sdk-types';
+
+const mockSessionStorage = (() => {
+  let store: { [key: string]: string } = {};
+  return {
+    getItem: (key: string) => store[key] || null,
+    setItem: (key: string, value: string) => {
+      store[key] = value;
+    },
+    removeItem: (key: string) => {
+      delete store[key];
+    },
+    clear: () => {
+      store = {};
+    },
+    length: 0,
+    key: (index: number) => Object.keys(store)[index] || null,
+  };
+})();
+
+describe('PKCE', () => {
+  beforeEach(() => {
+    if (typeof sessionStorage === 'undefined') {
+      global.sessionStorage = mockSessionStorage;
+    }
+
+    sessionStorage.clear();
+  });
+
+  const mockOptions: GenerateAndStoreAuthUrlValues = {
+    clientId: 'test-client',
+    redirectUri: 'http://localhost:8080',
+    scope: 'openid profile',
+    responseType: 'code',
+  };
+
+  describe('getStorageKey', () => {
+    const clientId = 'test-client-id';
+
+    it('should generate storage key with default prefix', () => {
+      const key = getStorageKey(clientId);
+      expect(key).toBe('FR-SDK-authflow-test-client-id');
+    });
+
+    it('should generate storage key with custom prefix', () => {
+      const customPrefix = 'CUSTOM';
+      const key = getStorageKey(clientId, customPrefix);
+      expect(key).toBe('CUSTOM-authflow-test-client-id');
+    });
+  });
+
+  describe('generateAndStoreAuthUrlValues', () => {
+    it('should generate PKCE values', () => {
+      const [options] = generateAndStoreAuthUrlValues(mockOptions);
+
+      expect(options).toBeDefined();
+      expect(options).toHaveProperty('state');
+      expect(options).toHaveProperty('verifier');
+    });
+
+    it('should store options in sessionStorage when storage function is called', () => {
+      const [options, storeAuthUrl] = generateAndStoreAuthUrlValues(mockOptions);
+      storeAuthUrl();
+
+      const storageKey = getStorageKey(mockOptions.clientId, mockOptions.prefix);
+      const storedValue = sessionStorage.getItem(storageKey);
+      expect(storedValue).toBeDefined();
+
+      const parsedValue = JSON.parse(storedValue as string);
+      expect(parsedValue).toEqual(options);
+    });
+  });
+
+  describe('getStoredAuthUrlValues', () => {
+    it('should retrieve and parse stored values', () => {
+      const [options, storeAuthUrl] = generateAndStoreAuthUrlValues(mockOptions);
+      storeAuthUrl();
+
+      const storedValues = getStoredAuthUrlValues(mockOptions.clientId, mockOptions.prefix);
+      expect(storedValues).toEqual(options);
+    });
+
+    it('should remove values from storage after retrieval', () => {
+      const [, storeAuthUrl] = generateAndStoreAuthUrlValues(mockOptions);
+      storeAuthUrl();
+
+      const storageKey = getStorageKey(mockOptions.clientId, mockOptions.prefix);
+
+      // Verify value exists before retrieval
+      expect(sessionStorage.getItem(storageKey)).toBeDefined();
+
+      // Retrieve values
+      getStoredAuthUrlValues(mockOptions.clientId, mockOptions.prefix);
+
+      // Verify value was removed
+      expect(sessionStorage.getItem(storageKey)).toBeNull();
+    });
+
+    it('should throw error when stored values cannot be parsed', () => {
+      const storageKey = getStorageKey(mockOptions.clientId, mockOptions.prefix);
+      sessionStorage.setItem(storageKey, 'invalid json');
+
+      expect(() => getStoredAuthUrlValues(mockOptions.clientId, mockOptions.prefix)).toThrow(
+        'Stored values for Auth URL could not be parsed',
+      );
+    });
+  });
+});

package/src/lib/wellknown.effects.test.ts

@@ -0,0 +1,182 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { isValidWellknownResponse, initWellknownQuery } from './wellknown.effects.js';
+
+import type { WellknownResponse } from '@forgerock/sdk-types';
+
+const WELLKNOWN_URL = 'https://example.com/.well-known/openid-configuration';
+
+function createMockWellknown(overrides: Partial<WellknownResponse> = {}): WellknownResponse {
+  return {
+    issuer: 'https://am.example.com/am/oauth2/alpha',
+    authorization_endpoint: 'https://am.example.com/am/oauth2/alpha/authorize',
+    token_endpoint: 'https://am.example.com/am/oauth2/alpha/access_token',
+    userinfo_endpoint: 'https://am.example.com/am/oauth2/alpha/userinfo',
+    end_session_endpoint: 'https://am.example.com/am/oauth2/alpha/connect/endSession',
+    introspection_endpoint: 'https://am.example.com/am/oauth2/alpha/introspect',
+    revocation_endpoint: 'https://am.example.com/am/oauth2/alpha/token/revoke',
+    ...overrides,
+  };
+}
+
+describe('wellknown.effects', () => {
+  describe('isValidWellknownResponse', () => {
+    describe('isValidWellknownResponse_AllRequiredFields_ReturnsTrue', () => {
+      it('should return true when all 3 required fields are present', () => {
+        const data = createMockWellknown();
+
+        const result = isValidWellknownResponse(data);
+
+        expect(result).toBe(true);
+      });
+    });
+
+    describe('isValidWellknownResponse_MissingIssuer_ReturnsFalse', () => {
+      it('should return false when issuer is missing', () => {
+        const data = {
+          authorization_endpoint: 'https://am.example.com/authorize',
+          token_endpoint: 'https://am.example.com/token',
+        };
+
+        const result = isValidWellknownResponse(data);
+
+        expect(result).toBe(false);
+      });
+    });
+
+    describe('isValidWellknownResponse_MissingAuthorizationEndpoint_ReturnsFalse', () => {
+      it('should return false when authorization_endpoint is missing', () => {
+        const data = {
+          issuer: 'https://am.example.com',
+          token_endpoint: 'https://am.example.com/token',
+        };
+
+        const result = isValidWellknownResponse(data);
+
+        expect(result).toBe(false);
+      });
+    });
+
+    describe('isValidWellknownResponse_MissingTokenEndpoint_ReturnsFalse', () => {
+      it('should return false when token_endpoint is missing', () => {
+        const data = {
+          issuer: 'https://am.example.com',
+          authorization_endpoint: 'https://am.example.com/authorize',
+        };
+
+        const result = isValidWellknownResponse(data);
+
+        expect(result).toBe(false);
+      });
+    });
+
+    describe('isValidWellknownResponse_StringInput_ReturnsFalse', () => {
+      it('should return false for string input', () => {
+        expect(isValidWellknownResponse('not an object')).toBe(false);
+      });
+    });
+
+    describe('isValidWellknownResponse_NullInput_ReturnsFalse', () => {
+      it('should return false for null input', () => {
+        expect(isValidWellknownResponse(null)).toBe(false);
+      });
+    });
+
+    describe('isValidWellknownResponse_UndefinedInput_ReturnsFalse', () => {
+      it('should return false for undefined input', () => {
+        expect(isValidWellknownResponse(undefined)).toBe(false);
+      });
+    });
+  });
+
+  describe('initWellknownQuery', () => {
+    describe('initWellknownQuery_SuccessfulCallback_ReturnsData', () => {
+      it('should return { data } when callback returns a valid response', async () => {
+        const wellknown = createMockWellknown();
+        const callback = async () => ({ data: wellknown });
+
+        const result = await initWellknownQuery(WELLKNOWN_URL).applyQuery(callback);
+
+        expect(result).toEqual({ data: wellknown });
+      });
+    });
+
+    describe('initWellknownQuery_CallbackReturnsError_PassesThroughError', () => {
+      it('should pass through the error when callback returns an error result', async () => {
+        const queryError = { status: 404, data: { message: 'Not Found' } };
+        const callback = async () => ({ error: queryError });
+
+        const result = await initWellknownQuery(WELLKNOWN_URL).applyQuery(callback);
+
+        expect(result).toEqual({ error: queryError });
+      });
+    });
+
+    describe('initWellknownQuery_CallbackThrows_ReturnsCUSTOM_ERROR', () => {
+      it('should catch thrown errors and return CUSTOM_ERROR', async () => {
+        const callback = async () => {
+          throw new Error('Network failure');
+        };
+
+        const result = await initWellknownQuery(WELLKNOWN_URL).applyQuery(callback);
+
+        expect(result.error).toBeDefined();
+        expect(result.error?.status).toBe('CUSTOM_ERROR');
+        expect(result.error?.error).toBe('Network failure');
+      });
+    });
+
+    describe('initWellknownQuery_CallbackThrowsNonError_ReturnsCUSTOM_ERROR', () => {
+      it('should handle non-Error throws with a generic message', async () => {
+        const callback = async () => {
+          throw 'string error';
+        };
+
+        const result = await initWellknownQuery(WELLKNOWN_URL).applyQuery(callback);
+
+        expect(result.error).toBeDefined();
+        expect(result.error?.status).toBe('CUSTOM_ERROR');
+        expect(result.error?.error).toBe('An unknown error occurred during well-known fetch');
+      });
+    });
+
+    describe('initWellknownQuery_InvalidResponse_ReturnsCUSTOM_ERROR', () => {
+      it('should return CUSTOM_ERROR when response is missing required fields', async () => {
+        const callback = async () => ({
+          data: {
+            issuer: 'https://am.example.com',
+            authorization_endpoint: 'https://am.example.com/authorize',
+          },
+        });
+
+        const result = await initWellknownQuery(WELLKNOWN_URL).applyQuery(callback);
+
+        expect(result.error).toBeDefined();
+        expect(result.error?.status).toBe('CUSTOM_ERROR');
+        expect(result.error?.error).toContain('missing required fields');
+      });
+    });
+
+    describe('initWellknownQuery_SetsAcceptHeader_InRequest', () => {
+      it('should pass Accept: application/json header in the request', async () => {
+        let capturedArgs: { url: string; headers: Record<string, string> } | undefined;
+        const callback = async (args: { url: string; headers: Record<string, string> }) => {
+          capturedArgs = args;
+          return { data: createMockWellknown() };
+        };
+
+        await initWellknownQuery(WELLKNOWN_URL).applyQuery(callback);
+
+        expect(capturedArgs).toBeDefined();
+        expect(capturedArgs?.headers).toEqual({ Accept: 'application/json' });
+        expect(capturedArgs?.url).toBe(WELLKNOWN_URL);
+      });
+    });
+  });
+});

package/src/lib/wellknown.effects.ts

@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import type { WellknownResponse, GenericError } from '@forgerock/sdk-types';
+
+/**
+ * Structural types compatible with RTK Query's shapes.
+ * Defined locally to keep the effects layer framework-agnostic
+ * (no dependency on @reduxjs/toolkit).
+ */
+
+/** Compatible with RTK Query's FetchArgs. */
+interface WellknownFetchArgs {
+  url: string;
+  headers: Record<string, string>;
+}
+
+/** Compatible with RTK Query's FetchBaseQueryError. */
+interface WellknownQueryError {
+  status: number | string;
+  data?: unknown;
+  error?: string;
+}
+
+/** Compatible with RTK Query's QueryReturnValue. */
+type WellknownQueryResult<T> =
+  | { data: T; error?: undefined; meta?: unknown }
+  | { data?: undefined; error: WellknownQueryError; meta?: unknown };
+
+function createError(message: string, status: number | string = 'unknown'): GenericError {
+  return {
+    error: 'Well-known configuration fetch failed',
+    message,
+    type: 'wellknown_error',
+    status,
+  };
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Validates that the response contains the minimum required OIDC well-known fields.
+ *
+ * Checks for `issuer`, `authorization_endpoint`, and `token_endpoint` — the
+ * minimum subset needed by this SDK. Note that the full OpenID Connect
+ * Discovery 1.0 spec defines additional required fields that some providers
+ * may not include.
+ */
+export function isValidWellknownResponse(data: unknown): data is WellknownResponse {
+  if (!isObject(data)) return false;
+  return (
+    typeof data.issuer === 'string' &&
+    typeof data.authorization_endpoint === 'string' &&
+    typeof data.token_endpoint === 'string'
+  );
+}
+
+/** Callback type for the query builder — wraps RTK Query's `baseQuery`. */
+type QueryCallback = (args: WellknownFetchArgs) => Promise<WellknownQueryResult<unknown>>;
+
+/**
+ * Creates a well-known query builder for use inside RTK Query `queryFn`.
+ *
+ * Constructs a request object from the URL, then exposes `applyQuery` to
+ * execute the request through the caller's `baseQuery`. Response validation
+ * uses {@link isValidWellknownResponse}.
+ *
+ * @param url - The well-known endpoint URL
+ * @returns A builder with `applyQuery(callback)` that returns a result compatible with RTK Query's `QueryReturnValue`
+ *
+ * @example
+ * ```typescript
+ * queryFn: async (url, _api, _extra, baseQuery) => {
+ *   return initWellknownQuery(url).applyQuery(async (req) => await baseQuery(req));
+ * }
+ * ```
+ */
+export function initWellknownQuery(url: string) {
+  const request: WellknownFetchArgs = {
+    url,
+    headers: { Accept: 'application/json' },
+  };
+
+  return {
+    async applyQuery(callback: QueryCallback): Promise<WellknownQueryResult<WellknownResponse>> {
+      let result: WellknownQueryResult<unknown>;
+
+      try {
+        result = await callback(request);
+      } catch (error) {
+        const message =
+          error instanceof Error
+            ? error.message
+            : 'An unknown error occurred during well-known fetch';
+        return {
+          error: {
+            status: 'CUSTOM_ERROR',
+            error: message,
+            data: createError(message),
+          },
+        };
+      }
+
+      if (result.error) {
+        return { error: result.error };
+      }
+
+      if (!isValidWellknownResponse(result.data)) {
+        return {
+          error: {
+            status: 'CUSTOM_ERROR',
+            error:
+              'Invalid well-known response: missing required fields (issuer, authorization_endpoint, token_endpoint)',
+            data: createError(
+              'Invalid well-known response: missing required fields (issuer, authorization_endpoint, token_endpoint)',
+            ),
+          },
+        };
+      }
+
+      return { data: result.data };
+    },
+  };
+}

package/tsconfig.json

@@ -3,12 +3,6 @@
   "files": [],
   "include": [],
   "references": [
-    {
-      "path": "../../sdk-utilities"
-    },
-    {
-      "path": "../../sdk-types"
-    },
     {
       "path": "./tsconfig.lib.json"
     },

package/dist/src/lib/authorize.types.d.ts

@@ -1,25 +0,0 @@
-import type { LegacyConfigOptions } from '@forgerock/sdk-types';
-/**
- * Define the options for the authorization URL
- * @param clientId The client ID of the application
- * @param redirectUri The redirect URI of the application
- * @param responseType The response type of the authorization request
- * @param scope The scope of the authorization request
- */
-export type ResponseType = 'code' | 'token';
-export interface GetAuthorizationUrlOptions extends LegacyConfigOptions {
-    /**
-     * These three properties clientid, scope and redirectUri are required
-     * when using this type, which are not required when defining Config.
-     */
-    clientId: string;
-    login?: 'redirect' | 'embedded';
-    scope: string;
-    redirectUri: string;
-    responseType: ResponseType;
-    state?: string;
-    verifier?: string;
-    query?: Record<string, string>;
-    prompt?: 'none' | 'login' | 'consent';
-}
-//# sourceMappingURL=authorize.types.d.ts.map

package/dist/src/lib/authorize.types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"authorize.types.d.ts","sourceRoot":"","sources":["../../../src/lib/authorize.types.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAC5C,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACvC"}

package/dist/src/lib/authorize.types.js

@@ -1,7 +0,0 @@
-/*
- * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
- *
- * This software may be modified and distributed under the terms
- * of the MIT license. See the LICENSE file for details.
- */
-export {};

package/dist/src/lib/index.d.ts

@@ -1,3 +0,0 @@
-export * from './authorize.effects.js';
-export * from './state-pkce.effects.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/src/lib/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAOA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC"}

package/dist/src/lib/index.js

@@ -1,8 +0,0 @@
-/*
- * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
- *
- * This software may be modified and distributed under the terms
- * of the MIT license. See the LICENSE file for details.
- */
-export * from './authorize.effects.js';
-export * from './state-pkce.effects.js';

package/src/lib/authorize.types.ts

@@ -1,32 +0,0 @@
-/*
- * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
- *
- * This software may be modified and distributed under the terms
- * of the MIT license. See the LICENSE file for details.
- */
-
-import type { LegacyConfigOptions } from '@forgerock/sdk-types';
-
-/**
- * Define the options for the authorization URL
- * @param clientId The client ID of the application
- * @param redirectUri The redirect URI of the application
- * @param responseType The response type of the authorization request
- * @param scope The scope of the authorization request
- */
-export type ResponseType = 'code' | 'token';
-export interface GetAuthorizationUrlOptions extends LegacyConfigOptions {
-  /**
-   * These three properties clientid, scope and redirectUri are required
-   * when using this type, which are not required when defining Config.
-   */
-  clientId: string;
-  login?: 'redirect' | 'embedded';
-  scope: string;
-  redirectUri: string;
-  responseType: ResponseType;
-  state?: string;
-  verifier?: string;
-  query?: Record<string, string>;
-  prompt?: 'none' | 'login' | 'consent';
-}

package/src/lib/index.ts

@@ -1,9 +0,0 @@
-/*
- * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
- *
- * This software may be modified and distributed under the terms
- * of the MIT license. See the LICENSE file for details.
- */
-
-export * from './authorize.effects.js';
-export * from './state-pkce.effects.js';