@jazzmind/busibox-app 3.0.18

package/dist/lib/authz/auth-state-manager.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Auth State Manager for client-side apps.
+ *
+ * Provides centralized authentication state management including:
+ * - Proactive token refresh before expiration
+ * - Auth state change detection and broadcasting
+ * - Automatic redirect to portal when re-authentication is required
+ * - Event-based architecture for loose coupling
+ *
+ * This acts as a "service worker-like" auth listener that monitors
+ * authentication state and prevents users from discovering expired
+ * tokens only after submitting a request.
+ *
+ * Usage:
+ * ```typescript
+ * const authManager = createAuthStateManager({
+ *   refreshEndpoint: '/api/auth/session',
+ *   sessionEndpoint: '/api/auth/session',
+ *   portalUrl: 'https://portal.example.com',
+ *   appId: 'busibox-agents',
+ * });
+ *
+ * // Start monitoring
+ * authManager.start();
+ *
+ * // Subscribe to auth state changes
+ * authManager.on('authStateChanged', (state) => {
+ *   console.log('Auth state:', state.isAuthenticated);
+ * });
+ *
+ * // Subscribe to re-auth requirements
+ * authManager.on('requiresReauth', () => {
+ *   // Will auto-redirect if autoRedirect is true
+ * });
+ * ```
+ */
+export type AuthState = {
+    isAuthenticated: boolean;
+    user: {
+        id: string;
+        email: string;
+        roles: string[];
+        displayName?: string;
+        firstName?: string;
+        lastName?: string;
+        avatarUrl?: string;
+        favoriteColor?: string;
+    } | null;
+    tokenExpiresAt: number | null;
+    lastChecked: number;
+};
+export type AuthStateManagerConfig = {
+    /**
+     * Endpoint to refresh authentication tokens (POST with empty body).
+     * Should return { success: true, token: string, expiresIn: number }
+     * or { requiresReauth: true } on failure.
+     * Typically the same as sessionEndpoint (/api/auth/session).
+     */
+    refreshEndpoint: string;
+    /**
+     * Endpoint to get current session state (GET).
+     * Should return { success: true, data: { user: {...} } }
+     * Typically /api/auth/session.
+     */
+    sessionEndpoint: string;
+    /**
+     * URL of the Busibox Portal for re-authentication.
+     */
+    portalUrl: string;
+    /**
+     * App identifier for return URL construction.
+     */
+    appId?: string;
+    /**
+     * How often to check auth state (ms). Default: 30 seconds.
+     */
+    checkIntervalMs?: number;
+    /**
+     * How long before token expiry to trigger refresh (ms). Default: 5 minutes.
+     */
+    refreshBufferMs?: number;
+    /**
+     * Whether to automatically redirect to portal on auth failure. Default: true.
+     */
+    autoRedirect?: boolean;
+    /**
+     * Callback to get the current token (if stored client-side).
+     */
+    getToken?: () => string | null;
+    /**
+     * Callback to set/update the token.
+     */
+    setToken?: (token: string | null) => void;
+    /**
+     * Optional: Base path for the app (e.g., '/agents').
+     */
+    basePath?: string;
+    /**
+     * Optional: URL of the portal's SSO token refresh endpoint.
+     * When the local SSO token expires, the auth manager will call this URL
+     * to silently obtain a fresh SSO token from the portal (using the portal's
+     * session cookie, which the browser sends automatically for same-origin requests).
+     *
+     * Defaults to: `${portalUrl}/api/auth/sso/refresh` (constructed from portalUrl minus '/home' suffix)
+     */
+    silentRefreshUrl?: string;
+    /**
+     * Optional: Local endpoint to exchange an SSO token for session cookies
+     * (POST with {token}).
+     * Used during silent refresh to store the fresh SSO token.
+     * Default: '/api/auth/session'
+     */
+    exchangeEndpoint?: string;
+    /**
+     * Testing only: Override the token lifetime in ms.
+     * When set, the auth manager pretends the token expires this many ms after
+     * it was first seen, regardless of the actual JWT `exp` claim.
+     * E.g., set to 60000 (60s) to test refresh after 1 minute.
+     *
+     * Combined with refreshBufferMs, the refresh will trigger at:
+     *   tokenExpiresOverrideMs - refreshBufferMs after the token is received.
+     *
+     * Do NOT use in production.
+     */
+    tokenExpiresOverrideMs?: number;
+};
+export type AuthEventType = 'authStateChanged' | 'tokenRefreshed' | 'tokenRefreshFailed' | 'requiresReauth' | 'sessionExpired';
+export type AuthEventCallback<T = unknown> = (data: T) => void;
+export type AuthStateManager = {
+    /**
+     * Start monitoring auth state.
+     */
+    start(): void;
+    /**
+     * Stop monitoring auth state.
+     */
+    stop(): void;
+    /**
+     * Get current auth state.
+     */
+    getState(): AuthState;
+    /**
+     * Force an immediate auth state check.
+     */
+    checkNow(): Promise<void>;
+    /**
+     * Force a token refresh.
+     */
+    refreshNow(): Promise<boolean>;
+    /**
+     * Subscribe to auth events.
+     */
+    on<T = unknown>(event: AuthEventType, callback: AuthEventCallback<T>): () => void;
+    /**
+     * Unsubscribe from auth events.
+     */
+    off(event: AuthEventType, callback: AuthEventCallback): void;
+    /**
+     * Redirect to portal for re-authentication.
+     */
+    redirectToPortal(reason?: string): void;
+    /**
+     * Handle a 401 response from an API call.
+     * Returns true if the request should be retried with a new token.
+     */
+    handle401Response(): Promise<boolean>;
+    /**
+     * Check if we're currently authenticated.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Perform a system-wide logout.
+     * Clears local tokens, calls logout endpoints, and redirects to portal login.
+     */
+    logout(): Promise<void>;
+};
+/**
+ * Create an auth state manager instance.
+ */
+export declare function createAuthStateManager(config: AuthStateManagerConfig): AuthStateManager;
+/**
+ * Get or create the global auth state manager.
+ * Use this when you need app-wide auth state monitoring.
+ */
+export declare function getGlobalAuthManager(config?: AuthStateManagerConfig): AuthStateManager | null;
+/**
+ * Set the global auth state manager.
+ */
+export declare function setGlobalAuthManager(manager: AuthStateManager): void;
+/**
+ * Clear the global auth state manager.
+ */
+export declare function clearGlobalAuthManager(): void;
+/**
+ * Check if auth is currently initializing (token exchange in progress).
+ * When true, 401 responses should NOT trigger redirects - just return them as-is.
+ */
+export declare function isAuthInitializing(): boolean;
+/**
+ * Set the auth initializing flag.
+ * Call with `true` before token exchange, `false` after.
+ */
+export declare function setAuthInitializing(initializing: boolean): void;
+//# sourceMappingURL=auth-state-manager.d.ts.map

package/dist/lib/authz/auth-state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-state-manager.d.ts","sourceRoot":"","sources":["../../../src/lib/authz/auth-state-manager.ts"],"names":[],"mappings":"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"}