@opensourcekd/ng-common-libs 2.0.9 → 2.0.11

package/dist/index.d.ts

@@ -198,6 +198,10 @@ declare function setStorageItem(key: string, value: string, storageType?: 'local
  */
 declare function removeStorageItem(key: string, storageType?: 'localStorage' | 'sessionStorage'): void;
 
+/**
+ * Type definitions for AuthService
+ * Framework-agnostic interfaces for authentication state management
+ */
 /**
  * User information from ID token
  * Standard OIDC claims compatible with Auth0
@@ -305,19 +309,88 @@ interface StorageKeys {
     USER_INFO: string;
     DECODED_TOKEN: string;
 }
+
+/**
+ * Decode a JWT access token and store its payload in storage
+ *
+ * Note: This only decodes the JWT structure without verifying the signature.
+ * The token signature is already validated by the Auth0 SDK when obtained.
+ * The stored payload is for informational use only (e.g. checking expiration,
+ * reading scopes). Do NOT use it for authorization decisions — always validate
+ * on the backend.
+ *
+ * @param token - Raw JWT access token string
+ * @param storageKeys - Storage key names configuration
+ * @param storageConfig - Storage type (localStorage / sessionStorage) configuration
+ */
+declare function decodeAndStoreToken(token: string, storageKeys: StorageKeys, storageConfig: StorageConfig): void;
+/**
+ * Retrieve and parse the decoded token payload from storage
+ *
+ * Note: This data is for informational purposes only (e.g. checking expiration,
+ * viewing scopes). Do NOT use it for authorization decisions — always validate
+ * permissions on the backend.
+ *
+ * @param storageKeys - Storage key names configuration
+ * @param storageConfig - Storage type (localStorage / sessionStorage) configuration
+ * @returns Decoded {@link TokenPayload} or `null` if not present or unparseable
+ */
+declare function getDecodedToken(storageKeys: StorageKeys, storageConfig: StorageConfig): TokenPayload | null;
+
+/**
+ * User data extraction utilities
+ * Pure functions for parsing user claims and constructing user data objects
+ */
+
+/**
+ * Standard OIDC and JWT claims excluded from custom/namespaced claim detection
+ */
+declare const STANDARD_JWT_CLAIMS: readonly string[];
+/**
+ * Determine whether a claim key is a namespaced Auth0 custom claim
+ * @param key - Claim key to inspect
+ * @returns `true` if the key starts with `http://` or `https://`
+ */
+declare function isNamespacedClaim(key: string): boolean;
+/**
+ * Extract namespaced (Auth0 custom) claim keys from a user info object
+ * @param user - {@link UserInfo} object to inspect
+ * @returns Array of claim keys that are URL-namespaced
+ */
+declare function getCustomClaims(user: UserInfo): string[];
+/**
+ * Resolve the first matching primitive claim value from a {@link UserInfo} object
+ *
+ * Checks direct claims first, then falls back to namespaced (Auth0 custom) claims
+ * whose keys contain the requested name as a substring.
+ *
+ * @param userInfo - The user info object to search
+ * @param claimNames - Single claim name or ordered array of names to check
+ * @param defaultValue - Value to return when no matching claim is found
+ * @returns Resolved string value or `defaultValue`
+ * @example
+ * const role = extractClaimValue(userInfo, ['role', 'user_role'], 'user');
+ */
+declare function extractClaimValue(userInfo: UserInfo, claimNames: string | string[], defaultValue: string): string;
+/**
+ * Build a simplified {@link UserData} object from a full {@link UserInfo} object
+ * @param userInfo - Full user info from the ID token
+ * @returns Simplified user data with id, name, email, role, and org
+ */
+declare function buildUserData(userInfo: UserInfo): UserData;
+
 /**
  * Pure TypeScript Authentication Service for Auth0 integration
- * Framework-agnostic - works with any JavaScript framework (Angular, React, Vue, etc.)
+ * Framework-agnostic — works with any JavaScript framework (Angular, React, Vue, etc.)
  *
- * Handles login, logout, token management, and user session
- * Uses configurable storage (sessionStorage/localStorage) for sensitive data
- * Emits authentication events via EventBus for cross-application communication
+ * Handles login, logout, token management, and user session.
+ * Uses configurable storage (sessionStorage/localStorage) for sensitive data.
+ * Emits authentication events via EventBus for cross-application communication.
  *
  * @example
  * ```typescript
  * import { AuthService, EventBus } from '@opensourcekd/ng-common-libs';
  *
- * // Create instances
  * const eventBus = new EventBus();
  * const authConfig = {
  *   domain: 'your-domain.auth0.com',
@@ -328,25 +401,23 @@ interface StorageKeys {
  * };
  * const authService = new AuthService(authConfig, eventBus);
  *
- * // Or create with an identifier
+ * // With an identifier for MFE scenarios
  * const authService = new AuthService(authConfig, eventBus, undefined, undefined, { id: 'MFE' });
  *
- * // Use the service
  * await authService.login();
  * const user = authService.getUser();
  * const token = await authService.getToken();
- *
- * // Get the identifier
  * const id = authService.getId(); // 'MFE' or undefined
  * ```
  */
 declare class AuthService {
-    private readonly STANDARD_JWT_CLAIMS;
     private auth0Client;
     private initializationPromise;
+    /** Remains false if callback processing fails, allowing the callback to be retried. */
     private callbackHandled;
     private callbackPromise;
     private userSubject;
+    /** Observable stream of the currently authenticated user */
     user$: Observable<UserInfo | null>;
     private config;
     private storageConfig;
@@ -355,145 +426,169 @@ declare class AuthService {
     private id?;
     /**
      * Create a new AuthService instance
-     * @param config - Auth0 configuration
+     * @param config - Auth0 configuration (domain, clientId, redirectUri, etc.)
      * @param eventBus - EventBus instance for emitting auth events
-     * @param storageConfig - Storage configuration (optional, defaults to sessionStorage)
-     * @param storageKeys - Storage keys (optional, defaults to standard keys)
-     * @param options - Optional configuration with an id to identify the instance
+     * @param storageConfig - Storage configuration (defaults to sessionStorage for both token and user)
+     * @param storageKeys - Storage key names (defaults to standard auth0_* keys)
+     * @param options - Optional settings; supply `id` to label this instance in MFE scenarios
      */
     constructor(config: Auth0Config, eventBus: EventBus, storageConfig?: StorageConfig, storageKeys?: StorageKeys, options?: AuthServiceOptions);
     /**
      * Get the identifier of this AuthService instance
-     * @returns The id if provided during initialization, undefined otherwise
+     * @returns The id supplied via options during construction, or `undefined`
      */
     getId(): string | undefined;
     /**
-     * Get effective audience value (with fallback to defaultAudience)
-     * @private
+     * Resolve the effective audience value, falling back to defaultAudience when audience is unset
+     * @returns The audience string, or `undefined` if neither field is set
      */
     private getEffectiveAudience;
     /**
-     * Initialize Auth0 client
+     * Initialize the Auth0 SPA client
+     * @throws {Error} When required config fields (domain, clientId) are missing
      */
     private initializeAuth0;
     /**
-     * Ensure Auth0 client is initialized before use
+     * Ensure the Auth0 client instance is created, without triggering callback detection.
+     * Used internally by {@link handleCallback} to avoid a circular async dependency:
+     * `ensureInitialized` → `checkAndHandleCallback` → `handleCallback` → `ensureInitialized`.
+     * @throws {Error} When the Auth0 client fails to initialize
+     */
+    private ensureAuth0Client;
+    /**
+     * Ensure the Auth0 client is initialized before use
+     * Lazy-initializes on the first call and auto-handles OAuth callbacks when detected
+     * @throws {Error} When the Auth0 client fails to initialize
      */
     private ensureInitialized;
     /**
-     * Check for OAuth callback parameters in URL and auto-handle if present
-     * Note: The Auth0 SDK's handleRedirectCallback() validates the state parameter
-     * to prevent CSRF attacks. This method only checks for the presence of callback
-     * parameters before delegating to the Auth0 SDK for secure processing.
+     * Check for OAuth callback parameters in the URL and auto-handle them
+     *
+     * The Auth0 SDK's `handleRedirectCallback` validates the `state` parameter
+     * to prevent CSRF attacks. This method only detects presence of callback
+     * params before delegating securely to the SDK.
+     *
+     * Uses an async IIFE to store the in-flight promise for concurrency deduplication
+     * (concurrent callers await the same promise) while still using async/await
+     * internally instead of `.then()/.catch()` chains.
      */
     private checkAndHandleCallback;
     /**
-     * Login with Auth0
+     * Redirect the user to Auth0 Universal Login
+     * @param user - Optional username hint (for logging/debugging only)
+     * @param options - Optional invitation or organization parameters
+     * @throws {Error} When the Auth0 redirect fails
      */
     login(user?: string, options?: {
         invitation?: string;
         organization?: string;
     }): Promise<void>;
     /**
-     * Handle OAuth2 callback after successful authorization
+     * Handle the OAuth2 redirect callback after successful authorization
+     * Stores the user info and access token, then cleans up the callback URL
+     *
+     * Uses {@link ensureAuth0Client} (not {@link ensureInitialized}) to avoid a circular
+     * async dependency: `ensureInitialized` → `checkAndHandleCallback` → `handleCallback`
+     * → `ensureInitialized`. Only the Auth0 client instance is needed here.
+     * @returns {@link CallbackResult} with `success` flag and optional `appState`
      */
     handleCallback(): Promise<CallbackResult>;
     /**
-     * Log all user claims for debugging
-     */
-    private logUserClaims;
-    private logStandardClaims;
-    private logClaims;
-    private getCustomClaims;
-    private getAdditionalClaims;
-    private isNamespacedClaim;
-    /**
-     * Logout user and clear authentication state
+     * Log the user out, clear all stored auth data, and redirect to the logout URI
+     *
+     * Uses {@link ensureAuth0Client} (not {@link ensureInitialized}) to avoid triggering
+     * callback detection during logout. Calling `ensureInitialized` here would invoke
+     * `checkAndHandleCallback`, which re-authenticates the user if callback URL params
+     * are present, causing them to be sent back to Auth0 instead of the logout URI.
      */
     logout(): Promise<void>;
     /**
-     * Get current access token
+     * Get the current access token asynchronously
+     * Returns from storage first; falls back to a silent Auth0 token refresh
+     * @returns The access token string, or `null` on failure
      */
     getToken(): Promise<string | null>;
     /**
-     * Get current access token synchronously from storage only
+     * Get the current access token synchronously from storage only
+     * @returns The stored token string, or `null` if not present
      */
     getTokenSync(): string | null;
     /**
-     * Set access token in storage and emit event
-     */
-    private setToken;
-    /**
-     * Decode JWT token and store its payload
-     * Note: This only decodes the JWT structure without verifying the signature.
-     * The token signature is already validated by Auth0 SDK when obtained.
-     * This decoded data is for informational purposes (e.g., checking expiration, viewing scopes).
-     * Do NOT use decoded token data for authorization decisions - always validate on the backend.
-     */
-    private decodeAndStoreToken;
-    /**
-     * Get decoded token payload from storage
-     * Note: This data is for informational purposes only (checking expiration, viewing scopes, etc.).
-     * Do NOT use this for authorization decisions - always validate permissions on the backend.
-     * The token signature is validated by Auth0 SDK when the token is obtained.
+     * Get the decoded access token payload from storage
+     *
+     * Note: For informational use only (checking expiration, viewing scopes, etc.).
+     * Do NOT use for authorization decisions — always validate on the backend.
+     *
+     * @returns Decoded {@link TokenPayload} or `null` if not present
      */
     getDecodedToken(): TokenPayload | null;
     /**
-     * Check if user is authenticated
+     * Check whether the user is authenticated via the Auth0 SDK
+     * @returns `true` if the Auth0 session is valid; falls back to storage check on error
      */
     isAuthenticated(): Promise<boolean>;
     /**
-     * Check if user is authenticated synchronously
+     * Check whether the user is authenticated synchronously based on stored token presence
+     * @returns `true` when an access token exists in storage
      */
     isAuthenticatedSync(): boolean;
     /**
-     * Get current user information
+     * Get the current authenticated user's info
+     * @returns {@link UserInfo} object or `null` if not authenticated
      */
     getUser(): UserInfo | null;
     /**
-     * Get simplified user data from token
+     * Get a simplified view of the current user's data
+     * @returns {@link UserData} with id, name, email, role, and org — or `null` if not authenticated
      */
     getUserData(): UserData | null;
-    private extractClaimValue;
     /**
-     * Get user information from storage
+     * Read and parse user info from storage on initialization
+     * @returns Stored {@link UserInfo} or `null` if absent
      */
     private getUserInfoFromStorage;
     /**
-     * Set user information in storage and update observable
+     * Persist user info to storage and update the user observable
+     * @param userInfo - The {@link UserInfo} object to store
      */
     private setUserInfo;
     /**
-     * Emit authentication event for cross-application communication
+     * Persist the access token to storage, decode and cache its payload
+     * @param token - Raw JWT access token string
+     */
+    private setToken;
+    /**
+     * Emit an authentication event via the shared EventBus
+     * @param eventType - Short event type suffix (e.g. `'login_success'`, `'logout'`)
+     * @param payload - Arbitrary metadata payload, or `null`
      */
     private emitAuthEvent;
     /**
-     * Clean up OAuth callback parameters from URL after successful authentication
-     * Removes 'code' and 'state' parameters while preserving other query parameters
+     * Remove OAuth callback parameters (`code`, `state`) from the browser URL
+     * while preserving all other query parameters and the hash fragment.
+     * Uses `history.replaceState` to avoid adding an entry to browser history.
      */
     private cleanupCallbackUrl;
 }
 /**
- * Create AuthService instance using AUTH0_CONFIG
- * Helper function for creating AuthService with default configuration from AUTH0_CONFIG
+ * Create an {@link AuthService} instance pre-configured from the shared {@link AUTH0_CONFIG}
  *
- * Note: Make sure to call configureAuth0() before using this helper
+ * Note: Call {@link configureAuth0} before using this helper so that `AUTH0_CONFIG`
+ * is populated with the correct values for your environment.
  *
  * @param eventBus - EventBus instance for auth events
- * @returns Configured AuthService instance
+ * @returns Fully configured {@link AuthService} instance
  *
  * @example
  * ```typescript
  * import { createAuthService, EventBus, configureAuth0, APP_CONFIG } from '@opensourcekd/ng-common-libs';
  *
- * // Configure Auth0 first
  * configureAuth0({
  *   domain: APP_CONFIG.auth0Domain,
  *   clientId: APP_CONFIG.auth0ClientId,
  *   audience: APP_CONFIG.apiUrl,
  * });
  *
- * // Create instances
  * const eventBus = new EventBus();
  * const authService = createAuthService(eventBus);
  * ```
@@ -699,5 +794,5 @@ declare class Logger {
     }): void;
 }
 
-export { APP_CONFIG, AUTH0_CONFIG, AuthService, EventBus, LogSeverity, Logger, STORAGE_CONFIG, STORAGE_KEYS, configureAuth0, createAuthService, getStorageItem, removeStorageItem, resetAuth0Config, setStorageItem };
+export { APP_CONFIG, AUTH0_CONFIG, AuthService, EventBus, LogSeverity, Logger, STANDARD_JWT_CLAIMS, STORAGE_CONFIG, STORAGE_KEYS, buildUserData, configureAuth0, createAuthService, decodeAndStoreToken, extractClaimValue, getCustomClaims, getDecodedToken, getStorageItem, isNamespacedClaim, removeStorageItem, resetAuth0Config, setStorageItem };
 export type { AppState, Auth0Config, Auth0ConfigOptions, AuthServiceOptions, AuthorizationParams, CallbackResult, EventBusOptions, EventPayload, LogAttributes, LogRecord, LoggerOptions, StorageConfig, StorageKeys, TokenPayload, UserData, UserInfo };