chore: small-pr-updates

Author: ryanbas21

packages/sdk-effects/iframe-manager/README.md

@@ -1,11 +1,67 @@
-# iframe-manager
+# @forgerock/iframe-manager
 
-This library was generated with [Nx](https://nx.dev).
+This package provides a utility for making background requests using hidden iframes, primarily intended for scenarios like silent authentication or token renewal in OAuth/OIDC flows. It extracts specified URL parameters from the final redirect URL within the iframe.
 
-## Building
+## Overview
 
-Run `nx build iframe-manager` to build the library.
+The package exports a single initialization function, `iframeManagerInit`. Calling this function returns an object containing the core API method: `getParamsFromIFrame`.
 
-## Running unit tests
+## Installation
 
-Run `nx test iframe-manager` to execute the unit tests via [Vitest](https://vitest.dev/).
+This package is typically used within the Ping Identity JavaScript SDK monorepo. If used standalone, you would install it via npm or yarn:
+
+```bash
+npm install @forgerock/iframe-manager
+# or
+yarn add @forgerock/iframe-manager
+```
+
+## Usage
+
+Import the initializer, call it, and then use the returned `getParamsFromIFrame` method.
+
+```typescript
+import iframeManagerInit from '@forgerock/iframe-manager';
+import type { AuthorizeUrl } from '@forgerock/sdk-types';
+
+// Initialize the iframe manager
+const iframeManager = iframeManagerInit();
+
+// Define the request options
+const options = {
+  url: 'https://authorization-server.com/authorize?client_id=...' as AuthorizeUrl, // Replace with your actual authorize URL
+  requestTimeout: 5000, // Timeout in milliseconds (e.g., 5 seconds)
+  urlParams: ['code', 'state', 'error', 'error_description'], // Specify the parameters you expect to parse
+};
+
+// Make the request
+iframeManager
+  .getParamsFromIFrame(options)
+  .then((params) => {
+    console.log('Successfully received parameters:', params);
+    // Example: { code: '...', state: '...' }
+    // Handle the received parameters (e.g., exchange code for tokens)
+  })
+  .catch((error) => {
+    console.error('Iframe request failed:', error.message);
+    // Handle the error (e.g., timeout, authorization error)
+  });
+```
+
+## API
+
+### `iframeManagerInit()`
+
+- **Description:** Initializes the iframe manager effect. Currently, it takes no configuration, but this might change in future versions.
+- **Returns:** `object` - An object containing the API methods.
+  - `getParamsFromIFrame`: `(options: { urlParams: string[]; url: AuthorizeUrl; requestTimeout: number; }) => Promise<Record<string, string>>`
+
+### `getParamsFromIFrame(options)`
+
+- **Description:** Creates a hidden iframe, navigates it to the specified `url`, and waits for it to redirect. It then attempts to parse specified query parameters (`urlParams`) from the final URL loaded in the iframe. It rejects if the request times out, if specific OAuth error parameters (`error`, `error_description`) are found in the redirect URL, or if there's an issue accessing the iframe's content (e.g., cross-origin errors before the final expected redirect).
+- **Parameters:**
+  - `options`: `object`
+    - `url`: `AuthorizeUrl` (string) - The initial URL to load in the iframe.
+    - `requestTimeout`: `number` - The maximum time in milliseconds to wait for the iframe to load and provide parameters before rejecting with a timeout error.
+    - `urlParams`: `string[]` - An array of query parameter keys to extract from the final redirect URL. Only parameters listed here will be included in the resolved object.
+- **Returns:** `Promise<Record<string, string>>` - A promise that resolves with an object containing the key-value pairs of the extracted query parameters. It rejects with an `Error` if the operation times out, encounters an OAuth error in the URL parameters, or fails for other reasons (like cross-origin access errors).

packages/sdk-effects/iframe-manager/src/lib/iframe-manager.effects.ts

@@ -39,11 +39,12 @@ export default function iframeManagerInit(/*config: OAuthConfig*/) {
    * @param options - The options for the iframe request (URL, timeout).
    * @returns A Promise that resolves with the query parameters from the redirect URL or rejects on timeout or error.
    */
-  const getAuthCodeByIFrame = (options: {
+  const getParamsFromIFrame = (options: {
+    urlParams: string[];
     url: AuthorizeUrl;
     requestTimeout: number;
   }): Promise<ResolvedParams<string>> => {
-    const { url, requestTimeout } = options;
+    const { url, requestTimeout, urlParams } = options;
 
     return new Promise((resolve, reject) => {
       let iframe: HTMLIFrameElement | null = document.createElement('iframe');
@@ -79,20 +80,18 @@ export default function iframeManagerInit(/*config: OAuthConfig*/) {
           if (iframe && iframe.contentWindow) {
             const newHref = iframe.contentWindow.location.href;
 
-            // Avoid processing 'about:blank' or initial load if it's not the target URL
-            if (
-              newHref === 'about:blank' ||
-              !newHref.startsWith(options.url.substring(0, options.url.indexOf('?')))
-            ) {
-              // Check if the newHref origin matches expected redirect_uri origin if possible
-              // Or simply check if it contains expected parameters.
-              // For now, we proceed assuming any load could be the redirect.
-            }
-
             const redirectUrl = new URL(newHref);
             const params: ResolvedParams<string> = {};
             redirectUrl.searchParams.forEach((value, key) => {
-              params[key] = value;
+              /**
+               * We want to match url params in the url,
+               * to params being passed into the iframe manager
+               * so we will ignore params that we are not explicitly
+               * asked to parse
+               */
+              if (urlParams.includes(key)) {
+                params[key] = value;
+              }
             });
 
             // Check for standard OAuth error parameters
@@ -144,6 +143,6 @@ export default function iframeManagerInit(/*config: OAuthConfig*/) {
 
   // Return the public API
   return {
-    getAuthCodeByIFrame,
+    getParamsFromIFrame,
   };
 }

packages/sdk-types/src/index.ts

@@ -8,5 +8,7 @@
 export * from './lib/am-callback.types.js';
 export * from './lib/legacy-config.types.js';
 export * from './lib/legacy-mware.types.js';
-export * from './lib/tokens.types.js';
 export * from './lib/branded.types.js';
+export * from './lib/authorize.types.js';
+export * from './lib/tokens.types.js';
+export * from './lib/config.types.js';

packages/sdk-types/src/lib/config.types.ts

@@ -4,8 +4,7 @@
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
  */
-import { AsyncServerConfig } from './legacy-config.types.js';
-import { TokenStoreObject } from './tokens.types.js';
+import { CustomStorageObject } from './tokens.types.js';
 
 /**
  * Union of possible OAuth Configs
@@ -15,7 +14,7 @@ export type OAuthConfig = DavinciOAuthConfig;
 
 export interface DavinciOAuthConfig extends BaseConfig {
   clientId: string;
-  tokenStore: TokenStoreObject | 'sessionStorage' | 'localStorage';
+  tokenStore: CustomStorageObject | 'sessionStorage' | 'localStorage';
   redirectUri: string;
   scope: string;
 }

tsconfig.json

@@ -39,6 +39,9 @@
     },
     {
       "path": "./packages/sdk-effects/storage"
+    },
+    {
+      "path": "./packages/sdk-effects/iframe-manager"
     }
   ]
 }