spry-apps-dropdown 2.0.2 → 3.0.0

package/README.md

@@ -1,4 +1,57 @@
 # spry-apps-dropdown
+## Integration Guide
+
+### 1. OIDC/Keycloak Setup
+
+This package requires OIDC authentication. Use `react-oidc-context` or `@react-keycloak/web` for best results.
+
+**Example OIDC config:**
+
+```tsx
+const oidcConfig = {
+  authority: 'https://auth.sprylogin.com/realms/sprylogin',
+  client_id: 'my-app-client',
+  redirect_uri: window.location.origin,
+  post_logout_redirect_uri: window.location.origin,
+  onSigninCallback: () => {
+    window.history.replaceState({}, document.title, window.location.pathname)
+  },
+}
+```
+
+### 2. Multi-Account Management
+
+The package supports multi-account switching, add-account, and soft logout. All account state is stored in localStorage for cross-app/iframe sync.
+
+**Syncing across apps/iframe:**
+- Use the same localStorage key (`spry_accounts`) in all apps.
+- When an account is added, removed, or switched, update localStorage and reload state in all apps.
+- For iframe/bridge integration, use a shared localStorage or a custom syncBridge client.
+
+### 3. Add Another Account Flow
+
+When adding another account:
+- A flag (`spry_add_account_pending`) is set in localStorage.
+- After soft logout, the app checks this flag and triggers OIDC login for the new account.
+- On callback, the new account is added and set as active.
+
+### 4. Cross-App Sync
+
+To sync active account and account removal across apps:
+- Listen for changes to `spry_accounts` in localStorage (using the `storage` event or polling).
+- When the accounts state changes, update your app's state and UI.
+- If using an iframe bridge, ensure the bridge propagates account changes to all connected apps.
+
+### 5. Troubleshooting
+
+- If new accounts are not added after login, ensure your OIDC provider updates the user context before the callback runs.
+- If cross-app sync is not working, check that all apps use the same localStorage key and listen for changes.
+- For CORS or redirect issues, verify your OIDC config and Keycloak setup.
+
+### 6. Example Integration
+
+See the Quick Start and Usage sections below for full code examples.
+
 
 A React component library for displaying Spry apps dropdown and profile menu with dynamic API integration. Features a Google-style UI with beautiful animations.
 
@@ -11,16 +64,53 @@ A React component library for displaying Spry apps dropdown and profile menu wit
 - 📱 Responsive layout
 - 🎯 TypeScript support
 - 🔌 Easy integration
-- 👤 Profile menu with avatar, account management, and sign out
+- 👤 Profile menu with avatar, account management, and sign out (always shows Manage your Account)
 - 🎛️ Combined TopBar component with both apps dropdown and profile menu
 
 ## Installation
 
 ```bash
-npm install spry-apps-dropdown
+npm install spry-apps-dropdown react-oidc-context oidc-client-ts
 ```
 
-That's it! All dependencies are included. Just make sure your project already has React installed (any React project does).
+This package expects `react`, `react-dom`, `react-oidc-context`, and `oidc-client-ts` to be provided by the consuming app.
+
+## React OIDC Quick Start (Lowest Effort)
+
+```tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { SpryAuthProvider, TopBar, useSpryAccountManager } from 'spry-apps-dropdown'
+
+const oidcConfig = {
+  authority: 'https://auth.sprylogin.com/realms/sprylogin',
+  client_id: 'my-app-client',
+  redirect_uri: window.location.origin,
+  post_logout_redirect_uri: window.location.origin,
+  onSigninCallback: () => {
+    window.history.replaceState({}, document.title, window.location.pathname)
+  },
+}
+
+function App() {
+  const accountManager = useSpryAccountManager()
+
+  return (
+    <TopBar
+      apiUrl="https://your-api.com"
+      accountManager={accountManager}
+    />
+  )
+}
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <SpryAuthProvider config={oidcConfig}>
+      <App />
+    </SpryAuthProvider>
+  </React.StrictMode>
+)
+```
 
 ## Usage
 
@@ -177,12 +267,20 @@ Profile menu component with automatic API integration.
 |------|------|----------|---------|-------------|
 | `apiUrl` | `string` | Yes | - | Base URL for profile API |
 | `onSignOut` | `() => void` | No | - | Callback when user signs out |
-| `onManageAccount` | `() => void` | No | - | Callback for manage account button |
+| `onManageAccount` | `() => void` | No | - | Callback for Manage your Account button. If not provided, it redirects to `https://sprylogin.com/my-account/` |
 | `getAuthToken` | `() => string \| null \| Promise<string \| null>` | No | - | Function to get auth token |
 | `headers` | `Record<string, string>` | No | - | Custom headers for API requests |
 | `refetchInterval` | `number` | No | `300000` (5 min) | Auto-refetch interval in ms |
 | `cacheTime` | `number` | No | `300000` (5 min) | Cache duration in ms |
 
+### Manage Account behavior
+
+The Manage your Account button is always shown. It uses this order:
+
+1. `onManageAccount` callback (if provided)
+2. `profile.manageAccountUrl` (if present)
+3. Default: `https://sprylogin.com/my-account/`
+
 ### `AppsDropdownConnected`
 
 The main component with automatic API integration.

package/dist/AccountList.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AccountList Component
+ * Renders a dropdown list of stored accounts with ability to switch or remove
+ * Shows stale account badges for expired refresh tokens
+ */
+import React from 'react';
+import type { StoredAccount } from './types';
+export interface AccountListProps {
+    accounts: StoredAccount[];
+    activeAccountId: string | null;
+    isLoading?: boolean;
+    onSwitchAccount: (accountId: string) => Promise<void>;
+    onAddAccount: () => Promise<void>;
+    onRemoveAccount: (accountId: string) => Promise<void>;
+    onRefreshAccount: (accountId: string) => Promise<void>;
+}
+/**
+ * AccountList component
+ * Renders all stored accounts with switching, adding, and removal UI
+ */
+export declare const AccountList: React.ForwardRefExoticComponent<AccountListProps & React.RefAttributes<HTMLDivElement>>;

package/dist/ProfileMenu.d.ts

@@ -1,2 +1,5 @@
-import type { ProfileMenuProps } from './types';
-export declare function ProfileMenu({ profile, isLoading, onSignOut, onManageAccount, }: ProfileMenuProps): import("react/jsx-runtime").JSX.Element;
+import type { ProfileMenuProps, UseAccountManagerReturn } from './types';
+export interface ProfileMenuWithAccountsProps extends ProfileMenuProps {
+    accountManager?: UseAccountManagerReturn;
+}
+export declare function ProfileMenu({ profile, isLoading, onSignOut, onManageAccount, accountManager, }: ProfileMenuWithAccountsProps): import("react/jsx-runtime").JSX.Element;

package/dist/ProfileMenuConnected.d.ts

@@ -1,8 +1,9 @@
-import type { UseProfileDataOptions } from './types';
+import type { UseProfileDataOptions, UseAccountManagerReturn } from './types';
 interface ProfileMenuConnectedProps extends UseProfileDataOptions {
     apiUrl: string;
     onSignOut?: () => void;
     onManageAccount?: () => void;
+    accountManager?: UseAccountManagerReturn;
 }
-export declare function ProfileMenuConnected({ apiUrl, onSignOut, onManageAccount, ...options }: ProfileMenuConnectedProps): import("react/jsx-runtime").JSX.Element;
+export declare function ProfileMenuConnected({ apiUrl, onSignOut, onManageAccount, accountManager, ...options }: ProfileMenuConnectedProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/SpryAuthProvider.d.ts

@@ -0,0 +1,15 @@
+import type { AuthProviderBaseProps } from 'react-oidc-context';
+import { UserManager, type UserManagerSettings } from 'oidc-client-ts';
+import type { KeycloakConfig } from './types';
+interface SpryAuthContextValue {
+    keycloakConfig: KeycloakConfig;
+    userManager: UserManager;
+    syncBridgeUrl?: string;
+}
+export interface SpryAuthProviderProps extends AuthProviderBaseProps {
+    config: UserManagerSettings;
+    syncBridgeUrl?: string;
+}
+export declare function SpryAuthProvider({ children, config, syncBridgeUrl, onSigninCallback, matchSignoutCallback, onSignoutCallback, onRemoveUser, skipSigninCallback, }: SpryAuthProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useSpryAuthContext(): SpryAuthContextValue;
+export {};

package/dist/TopBar.d.ts

@@ -6,4 +6,5 @@ import type { TopBarProps } from './types';
 export declare function TopBar({ apiUrl, profileApiUrl, onSignOut, getAuthToken, profileHeaders, showAppsDropdown, showProfileMenu, appsRefetchInterval, // 5 minutes
 appsCacheTime, // 5 minutes
 profileRefetchInterval, // 5 minutes
-profileCacheTime, }: TopBarProps): import("react/jsx-runtime").JSX.Element;
+profileCacheTime, // 5 minutes
+accountManager, }: TopBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/accountStorage.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Account storage utilities for multi-account management
+ *
+ * ⚠️ SECURITY WARNING: Uses localStorage for cross-app/cross-tab persistence.
+ *
+ * Tokens are stored in localStorage which persists across browser sessions and tabs.
+ * This enables multi-account switching across 20+ apps in the Spry ecosystem.
+ *
+ * XSS RISK: localStorage is vulnerable to XSS attacks. Consuming applications MUST:
+ * - Implement strict Content Security Policy (CSP) headers
+ * - Avoid eval(), inline scripts, and dangerous DOM manipulation
+ * - Sanitize all user inputs
+ * - Use trusted dependencies only
+ * - Regularly audit for XSS vulnerabilities
+ *
+ * See INTEGRATION.md for complete security recommendations.
+ */
+import type { AccountsState, StoredAccount, OIDCUser, StoredAccountMetadata } from './types';
+/**
+ * Retrieve accounts state from localStorage
+ */
+export declare function getAccountsState(): AccountsState;
+/**
+ * Retrieve all stored accounts from localStorage
+ */
+export declare function getAccounts(): StoredAccount[];
+/**
+ * Persist accounts state to localStorage
+ */
+export declare function saveAccountsState(state: AccountsState): void;
+/**
+ * Persist accounts to localStorage
+ */
+export declare function saveAccounts(accounts: StoredAccount[], activeAccountId?: string | null): void;
+/**
+ * Add a new account to storage
+ * Returns the generated account ID
+ */
+export declare function addAccount(user: OIDCUser): string;
+/**
+ * Remove an account from storage
+ */
+export declare function removeAccount(accountId: string): void;
+/**
+ * Set an account as the active account
+ */
+export declare function setActiveAccount(accountId: string | null): void;
+/**
+ * Get the currently active account
+ */
+export declare function getActiveAccount(): StoredAccount | null;
+/**
+ * Get the active account ID
+ */
+export declare function getActiveAccountId(): string | null;
+/**
+ * Update tokens for a specific account
+ */
+export declare function updateAccountTokens(accountId: string, user: OIDCUser): void;
+/**
+ * Mark an account as stale (refresh token expired)
+ */
+export declare function markAccountStale(accountId: string): void;
+/**
+ * Clear ALL stored accounts (used on logout or manual reset)
+ */
+export declare function clearAllAccounts(): void;
+/**
+ * Get account metadata without the user object
+ * Useful for debugging or display
+ */
+export declare function getAccountMetadata(accountId: string): StoredAccountMetadata | null;
+/**
+ * Set flag indicating add account flow is in progress
+ */
+export declare function setAddAccountInProgress(inProgress: boolean): void;
+/**
+ * Check if add account flow is in progress
+ */
+export declare function isAddAccountInProgress(): boolean;
+/**
+ * Save return URL for redirect flow
+ */
+export declare function setReturnUrl(url: string): void;
+/**
+ * Get return URL from redirect flow
+ */
+export declare function getReturnUrl(): string | null;
+/**
+ * Clear return URL
+ */
+export declare function clearReturnUrl(): void;
+/**
+ * Save current user temporarily before redirect
+ */
+export declare function saveTempCurrentUser(user: OIDCUser): void;
+/**
+ * Get temporarily saved current user
+ */
+export declare function getTempCurrentUser(): OIDCUser | null;
+/**
+ * Clear temporarily saved current user
+ */
+export declare function clearTempCurrentUser(): void;

package/dist/constants.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Storage keys for multi-account management
+ *
+ * ⚠️ SECURITY WARNING: Using localStorage for cross-app/cross-tab persistence.
+ * Tokens are stored in localStorage which is vulnerable to XSS attacks.
+ * Consuming applications MUST implement Content Security Policy (CSP) headers
+ * and other XSS mitigations. See INTEGRATION.md for security recommendations.
+ */
+export declare const STORAGE_KEYS: {
+    readonly ACCOUNTS: "spry_accounts";
+    readonly BRIDGE_ACCOUNTS: "spry_accounts_shared_state";
+    readonly ADD_ACCOUNT_IN_PROGRESS: "spry_add_account_in_progress";
+    readonly RETURN_URL: "spry_return_url";
+    readonly TEMP_CURRENT_USER: "spry_temp_current_user";
+};
+/**
+ * Token validation and refresh configuration
+ */
+export declare const TOKEN_VALIDATION: {
+    readonly ACCESS_TOKEN_BUFFER_SECONDS: 60;
+    readonly REFRESH_TOKEN_BUFFER_SECONDS: 300;
+    readonly STALE_CHECK_INTERVAL_MS: 1000;
+};
+/**
+ * Error messages
+ */
+export declare const ERROR_MESSAGES: {
+    readonly INVALID_TOKEN: "Invalid or malformed token";
+    readonly TOKEN_DECODE_FAILED: "Failed to decode token";
+    readonly ACCOUNT_NOT_FOUND: "Account not found";
+    readonly SIGNIN_REDIRECT_FAILED: "Failed to initiate sign-in redirect";
+    readonly LOGOUT_FAILED: "Failed to logout from Keycloak, but account will be removed locally.";
+    readonly TOKEN_REFRESH_FAILED: "Failed to refresh token for account";
+    readonly SSO_CLEAR_FAILED: "Failed to clear SSO session. Please sign out first if prompted by Keycloak.";
+};
+/**
+ * Warning/Info messages
+ */
+export declare const INFO_MESSAGES: {
+    readonly LOCALSTORAGE_XSS_WARNING: "⚠️ Tokens stored in localStorage are vulnerable to XSS. Ensure CSP headers are configured.";
+    readonly ACCOUNT_MARKED_STALE: "Account refresh token expired. Click to re-authenticate.";
+    readonly NO_ACCOUNTS: "No additional accounts stored. Your primary auth remains active.";
+    readonly REDIRECT_IN_PROGRESS: "Redirecting to Keycloak for authentication...";
+};