@forgerock/login-widget 2.0.0 → 2.1.0

package/README.md

@@ -36,7 +36,6 @@
   - [Journey](#journey)
   - [Component](#component)
   - [User](#user)
-  - [Request](#request)
   - [Styling Configuration](#styling-configuration)
   - [Links Configuration](#links-configuration)
   - [Content Configuration](#content-configuration)
@@ -48,7 +47,7 @@
 
 The Login Widget is an all-inclusive UI component for handling login, registration, and related user flows in any modern JavaScript app. It works with React, Vue, Angular, Svelte, or vanilla JavaScript — it does not currently support Node.js or server-side rendering (SSR).
 
-The widget uses [Journey Client](https://developer.pingidentity.com/orchsdks/journey/usage/javascript/index.html) for journey execution, and the [ForgeRock SDK for JavaScript](https://docs.pingidentity.com/sdks/latest/sdks/tutorials/javascript/index.html) for OAuth/OIDC tokens, user info, and request utilities. It adds a UI rendering layer on top of these SDKs to eliminate the need to develop and maintain UI components for complex authentication flows. Although this rendering layer is developed with Svelte and Tailwind, both are "compiled away" and have no runtime dependencies. The resulting widget is library- and framework-agnostic.
+The widget uses [Journey Client](https://developer.pingidentity.com/orchsdks/journey/usage/javascript/index.html) for journey execution, and [OIDC Client](https://developer.pingidentity.com/orchsdks/oidc/usage/javascript-centralized-login.html) for OAuth/OIDC tokens and user info. It adds a UI rendering layer on top of these SDKs to eliminate the need to develop and maintain UI components for complex authentication flows. Although this rendering layer is developed with Svelte and Tailwind, both are "compiled away" and have no runtime dependencies. The resulting widget is library- and framework-agnostic.
 
 The widget can be rendered in two form factors:
 
@@ -139,12 +138,15 @@ import Widget, { configure, journey } from '@forgerock/login-widget';
 // 1. Configure — async; awaiting it ensures both clients are ready before use
 await configure({
   // REQUIRED — the well-known URL, shared by the journey and OIDC clients
-  wellknown: 'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+  serverConfig: {
+    wellknown:
+      'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+  },
   // REQUIRED if you use OAuth/OIDC tokens, user info, or logout
   oidcClient: {
     clientId: 'YourOauthClient',
     redirectUri: `${window.location.origin}/callback`,
-    scope: 'openid profile email',
+    scope: 'openid profile email', // OPTIONAL — defaults to 'openid'
   },
 });
 
@@ -259,14 +261,23 @@ import { configure } from '@forgerock/login-widget';
 // configure() is async — await it before calling any other Widget API
 await configure({
   // REQUIRED — the well-known URL, shared by the journey and OIDC clients
-  wellknown:
-    'https://your-tenant.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
+  serverConfig: {
+    wellknown:
+      'https://your-tenant.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
+  },
   // REQUIRED if you use OAuth/OIDC tokens, user info, or logout
   oidcClient: {
     clientId: 'WebOAuthClient',
     redirectUri: `${window.location.origin}/callback`,
     scope: 'openid profile email',
   },
+  // OPTIONAL — logger for both clients; `level` gates verbosity and `custom`
+  // redirects SDK log output to your own sink. See the full example below.
+  logger: { level: 'warn' },
+  // OPTIONAL — request middleware for both clients; see the full example below
+  middleware: [],
+  // OPTIONAL — token storage config; see Storage section below
+  storage: { type: 'sessionStorage', name: 'tokens' },
   // OPTIONAL — see dedicated sections below
   content: {},
   links: {},
@@ -275,9 +286,115 @@ await configure({
 ```
 
 > **Migration note (2.0.0):** The `forgerock` config object has been replaced by `oidcClient`.
-> Endpoint discovery is now driven by a single top-level `wellknown` URL, shared by the
-> journey and OIDC clients — `baseUrl`, `realmPath`, `timeout`, and `support` are no longer
-> used. `clientId`, `redirectUri`, and `scope` are now required when configuring `oidcClient`.
+> Endpoint discovery is now driven by `serverConfig.wellknown`, shared by the journey and OIDC
+> clients — `baseUrl`, `realmPath`, `timeout`, and `support` are no longer used. `clientId` and
+> `redirectUri` are required when configuring `oidcClient`; `scope` defaults to `'openid'`. `tokenStore` has
+> moved to a top-level `storage` option.
+
+#### Logger
+
+The top-level `logger` option is forwarded to both the journey and OIDC clients.
+
+| Property | Type                                               | Default   | Description                                                                             |
+| -------- | -------------------------------------------------- | --------- | --------------------------------------------------------------------------------------- |
+| `level`  | `'none' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'error'` | Gates SDK log verbosity. `'none'` silences all SDK logs.                                |
+| `custom` | `{ error, warn, info, debug }`                     | —         | Sink for SDK log output. When set, the SDK calls your methods instead of the `console`. |
+
+```js
+await configure({
+  serverConfig: {
+    wellknown:
+      'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+  },
+  logger: {
+    level: 'debug',
+    // OPTIONAL — route SDK logs to your own sink instead of the console.
+    custom: {
+      error: (...args) => myLogger.error(...args),
+      warn: (...args) => myLogger.warn(...args),
+      info: (...args) => myLogger.info(...args),
+      debug: (...args) => myLogger.debug(...args),
+    },
+  },
+  oidcClient: {
+    clientId: 'WebOAuthClient',
+    redirectUri: `${window.location.origin}/callback`,
+    scope: 'openid profile email',
+  },
+});
+```
+
+#### OIDC Client Options
+
+All properties are nested inside `oidcClient`.
+
+| Property         | Type                     | Default    | Description                                                                                                                                                                                                        |
+| ---------------- | ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `clientId`       | `string`                 | —          | **Required.** OAuth 2.0 client ID.                                                                                                                                                                                 |
+| `redirectUri`    | `string`                 | —          | **Required.** URI AM redirects to after authorization.                                                                                                                                                             |
+| `scope`          | `string`                 | `'openid'` | OAuth 2.0 scopes.                                                                                                                                                                                                  |
+| `oauthThreshold` | `number`                 | `30000`    | Milliseconds before expiry to trigger background renewal.                                                                                                                                                          |
+| `par`            | `boolean`                | auto       | Use Pushed Authorization Requests. When omitted, the SDK auto-detects from the authorization server's `require_pushed_authorization_requests` metadata. Setting `false` while the server requires PAR is an error. |
+| `loginHint`      | `string`                 | —          | Pre-fills the login identifier; bridged onto silent token renewal.                                                                                                                                                 |
+| `acrValues`      | `string`                 | —          | Requested ACR values; bridged onto silent token renewal.                                                                                                                                                           |
+| `query`          | `Record<string, string>` | —          | Extra authorize query params; bridged onto silent token renewal.                                                                                                                                                   |
+
+Example with all optional OIDC options:
+
+```js
+await configure({
+  serverConfig: {
+    wellknown:
+      'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
+  },
+  logger: { level: 'debug' },
+  middleware: [
+    (req, action, next) => {
+      console.log('[middleware]', action.type, req.url);
+      next();
+    },
+  ],
+  storage: { type: 'sessionStorage', name: 'tokens', prefix: 'myapp' },
+  oidcClient: {
+    clientId: 'WebOAuthClient',
+    redirectUri: `${window.location.origin}/callback`,
+    scope: 'openid profile email',
+    oauthThreshold: 60000,
+    par: true,
+    loginHint: 'user@example.com',
+    acrValues: 'urn:acr:2fa',
+    query: { ui_locales: 'en-US' },
+  },
+});
+```
+
+#### Storage
+
+The top-level `storage` option configures where the OIDC client persists tokens. It mirrors
+the SDK's `StorageConfig` union — `type` selects a browser store or a custom sink.
+
+| Property | Type                                             | Default          | Description                                                             |
+| -------- | ------------------------------------------------ | ---------------- | ----------------------------------------------------------------------- |
+| `type`   | `'localStorage' \| 'sessionStorage' \| 'custom'` | `'localStorage'` | Storage backend. `'custom'` requires a `custom` sink.                   |
+| `name`   | `string`                                         | —                | **Required.** Storage key name.                                         |
+| `prefix` | `string`                                         | `'pic'`          | Key prefix for storage entries.                                         |
+| `custom` | `{ get, set, remove }`                           | —                | **Required when `type: 'custom'`.** Async functions for your own store. |
+
+```js
+// Browser store
+storage: { type: 'sessionStorage', name: 'tokens', prefix: 'myapp' },
+
+// Custom store
+storage: {
+  type: 'custom',
+  name: 'tokens',
+  custom: {
+    get: async (key) => myStore.read(key),
+    set: async (key, value) => myStore.write(key, value),
+    remove: async (key) => myStore.delete(key),
+  },
+},
+```
 
 ### Journey
 

package/dist/core/oauth/oauth.store.d.ts

@@ -6,10 +6,13 @@
  * of the MIT license. See the LICENSE file for details.
  *
  **/
-import type { GetTokensOptions, OauthTokens, OidcClient } from '@forgerock/oidc-client/types';
+import type { GetAuthorizationUrlOptions, GetTokensOptions, OauthTokens, OidcClient, StorageConfig } from '@forgerock/oidc-client/types';
 import type { Readable, Writable } from 'svelte/store';
 import type { Maybe } from '../interfaces';
+import type { OidcClientConfig } from '../oidc/oidc.store';
 export interface OAuthStore extends Pick<Writable<OAuthTokenStoreValue>, 'subscribe'> {
+    background: (options?: GetAuthorizationUrlOptions) => void;
+    exchange: (options?: Partial<StorageConfig>) => void;
     get: (getOptions?: GetTokensOptions) => Promise<OAuthTokenStoreValue>;
     reset: () => void;
 }
@@ -22,12 +25,14 @@ export interface OAuthTokenStoreValue {
     }>;
     loading: boolean;
     successful: boolean;
+    code: Maybe<string>;
+    state: Maybe<string>;
     response: Maybe<OauthTokens> | void;
 }
 /**
  * @function initialize - Initializes the OAuth store with a get function and a reset function
  * @param {Readable<OidcClient | null>} oidcClientStore - The OIDC client store to read the client from
- * @param {GetTokensOptions} initOptions - Default options to pass to `token.get`
+ * @param {OidcClientConfig} oidcConfig - The OIDC client config; used to build authorizeOptions for token.get
  * @returns {OAuthStore} - The OAuth store
  */
-export declare function initialize(oidcClientStore: Readable<OidcClient | null> | undefined, initOptions?: GetTokensOptions): OAuthStore;
+export declare function initialize(oidcClientStore: Readable<OidcClient | null> | undefined, oidcConfig?: Omit<OidcClientConfig, 'serverConfig'>): OAuthStore;

package/dist/core/oidc/oidc.store.d.ts

@@ -7,10 +7,12 @@
  *
  **/
 import { z } from 'zod';
-import type { OidcClient } from '@forgerock/oidc-client/types';
+import type { CustomLogger, LogLevel, OidcClient, RequestMiddleware, StorageConfig } from '@forgerock/oidc-client/types';
 import type { Readable } from 'svelte/store';
 /**
- * Configure the OIDC Client.
+ * Validates the OIDC client config passed to the widget. Accepts the fields from
+ * OidcConfig that have a clear consumer use case. serverConfig is injected by the
+ * widget from its own wellknown; log is omitted in favour of the top-level logger option.
  */
 export declare const oidcClientConfigSchema: z.ZodObject<{
     clientId: z.ZodString;
@@ -19,6 +21,11 @@ export declare const oidcClientConfigSchema: z.ZodObject<{
     serverConfig: z.ZodObject<{
         wellknown: z.ZodString;
     }, z.core.$strict>;
+    par: z.ZodOptional<z.ZodBoolean>;
+    loginHint: z.ZodOptional<z.ZodString>;
+    acrValues: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    oauthThreshold: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type OidcClientConfig = z.infer<typeof oidcClientConfigSchema>;
 export type OidcClientStore = Readable<OidcClient | null> & {
@@ -40,6 +47,12 @@ export type OidcClientStore = Readable<OidcClient | null> & {
  * client instance without module-level state.
  *
  * @param {OidcClientConfig} config — OIDC client configuration (validated by Zod).
+ * @param {RequestMiddleware[]} [requestMiddleware] — optional request middleware forwarded to `oidc()`.
+ * @param {{ level: LogLevel; custom?: CustomLogger }} [logger] — optional logger (level + custom sink) forwarded to `oidc()`.
+ * @param {StorageConfig} [storage] — optional token storage config forwarded to `oidc()`.
  * @returns {OidcClientStore}
  */
-export declare function createOidcClientStore(config: OidcClientConfig): OidcClientStore;
+export declare function createOidcClientStore(config: OidcClientConfig, requestMiddleware?: RequestMiddleware[], logger?: {
+    level: LogLevel;
+    custom?: CustomLogger;
+}, storage?: StorageConfig): OidcClientStore;