@cas-system/react-cas-client 1.0.0 → 1.0.1

package/dist/CasProvider.d.ts

@@ -0,0 +1,63 @@
+import { type ReactNode } from 'react';
+import type { CasConfig, CasContextValue, CasUser } from './types';
+/**
+ * React Context for CAS authentication state and actions.
+ *
+ * Access this through the {@link useCasAuth} or {@link useCasUser} hooks
+ * rather than consuming it directly.
+ */
+export declare const CasContext: import("react").Context<CasContextValue | null>;
+/**
+ * Props for the {@link CasProvider} component.
+ */
+export interface CasProviderProps {
+    /** CAS configuration (server URL, client ID, etc.). */
+    config: CasConfig;
+    /** Child components that need access to CAS auth state. */
+    children: ReactNode;
+    /**
+     * Callback invoked after successful authentication.
+     * Useful for analytics, redirects, or syncing with app state.
+     */
+    onAuthSuccess?: (user: CasUser) => void;
+    /**
+     * Callback invoked when an authentication error occurs.
+     * Useful for error reporting or showing notifications.
+     */
+    onAuthError?: (error: string) => void;
+}
+/**
+ * CAS Authentication Provider.
+ *
+ * Wrap your application (or a subtree) in `<CasProvider>` to enable CAS
+ * authentication. On mount the provider will:
+ *
+ * 1. Check `sessionStorage` for an existing user session.
+ * 2. If the URL contains a `?token=` parameter (i.e. the CAS redirect
+ *    callback), automatically validate it via the backend and establish
+ *    a session.
+ *
+ * @example
+ * ```tsx
+ * import { CasProvider } from '@cas-system/react-cas-client';
+ *
+ * function App() {
+ *   return (
+ *     <CasProvider
+ *       config={{
+ *         serverUrl: 'https://cas.example.com',
+ *         clientId: 'my-app',
+ *         callbackUrl: 'https://myapp.com/auth/callback',
+ *         backendValidateUrl: '/api/auth/validate',
+ *       }}
+ *       onAuthSuccess={(user) => console.log('Logged in:', user.username)}
+ *       onAuthError={(err) => console.error('Auth failed:', err)}
+ *     >
+ *       <YourApp />
+ *     </CasProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function CasProvider({ config, children, onAuthSuccess, onAuthError, }: CasProviderProps): import("react").JSX.Element;
+//# sourceMappingURL=CasProvider.d.ts.map

package/dist/CasProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CasProvider.d.ts","sourceRoot":"","sources":["../src/CasProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,UAAU,iDAA8C,CAAC;AAGtE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,SAAS,CAAC;IAElB,2DAA2D;IAC3D,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,aAAa,EACb,WAAW,GACZ,EAAE,gBAAgB,+BAqHlB"}

package/dist/CasProvider.js

@@ -0,0 +1,133 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { CasClient } from './cas-client';
+/**
+ * React Context for CAS authentication state and actions.
+ *
+ * Access this through the {@link useCasAuth} or {@link useCasUser} hooks
+ * rather than consuming it directly.
+ */
+export const CasContext = createContext(null);
+CasContext.displayName = 'CasContext';
+/**
+ * CAS Authentication Provider.
+ *
+ * Wrap your application (or a subtree) in `<CasProvider>` to enable CAS
+ * authentication. On mount the provider will:
+ *
+ * 1. Check `sessionStorage` for an existing user session.
+ * 2. If the URL contains a `?token=` parameter (i.e. the CAS redirect
+ *    callback), automatically validate it via the backend and establish
+ *    a session.
+ *
+ * @example
+ * ```tsx
+ * import { CasProvider } from '@cas-system/react-cas-client';
+ *
+ * function App() {
+ *   return (
+ *     <CasProvider
+ *       config={{
+ *         serverUrl: 'https://cas.example.com',
+ *         clientId: 'my-app',
+ *         callbackUrl: 'https://myapp.com/auth/callback',
+ *         backendValidateUrl: '/api/auth/validate',
+ *       }}
+ *       onAuthSuccess={(user) => console.log('Logged in:', user.username)}
+ *       onAuthError={(err) => console.error('Auth failed:', err)}
+ *     >
+ *       <YourApp />
+ *     </CasProvider>
+ *   );
+ * }
+ * ```
+ */
+export function CasProvider({ config, children, onAuthSuccess, onAuthError, }) {
+    const [user, setUser] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Stable reference to the CAS client — recreated only when config changes
+    const client = useMemo(() => new CasClient(config), [config]);
+    // Guard to ensure the callback is handled at most once (React strict-mode safe)
+    const callbackHandled = useRef(false);
+    // -------------------------------------------------------------------------
+    // Initialisation
+    // -------------------------------------------------------------------------
+    useEffect(() => {
+        let cancelled = false;
+        async function init() {
+            try {
+                // 1. If there is a ?token= in the URL, handle the callback
+                const token = client.extractTokenFromUrl();
+                if (token && !callbackHandled.current) {
+                    callbackHandled.current = true;
+                    const validatedUser = await client.handleCallback();
+                    if (!cancelled && validatedUser) {
+                        setUser(validatedUser);
+                        setError(null);
+                        onAuthSuccess?.(validatedUser);
+                    }
+                }
+                else {
+                    // 2. Otherwise, try to restore a session from sessionStorage
+                    const existingUser = client.getUser();
+                    if (!cancelled && existingUser) {
+                        setUser(existingUser);
+                    }
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    const message = err instanceof Error ? err.message : 'Authentication failed';
+                    setError(message);
+                    setUser(null);
+                    onAuthError?.(message);
+                }
+            }
+            finally {
+                if (!cancelled) {
+                    setIsLoading(false);
+                }
+            }
+        }
+        init();
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client]);
+    // -------------------------------------------------------------------------
+    // Actions
+    // -------------------------------------------------------------------------
+    const login = useCallback((returnUrl) => {
+        client.login(returnUrl);
+    }, [client]);
+    const logout = useCallback(async (redirectUrl) => {
+        await client.logout(redirectUrl);
+        setUser(null);
+        setError(null);
+    }, [client]);
+    const hasRole = useCallback((role) => {
+        return user?.roles?.includes(role) ?? false;
+    }, [user]);
+    const hasAnyRole = useCallback((roles) => {
+        if (!user?.roles)
+            return false;
+        return roles.some((role) => user.roles.includes(role));
+    }, [user]);
+    // -------------------------------------------------------------------------
+    // Context value
+    // -------------------------------------------------------------------------
+    const value = useMemo(() => ({
+        user,
+        isAuthenticated: user !== null,
+        isLoading,
+        error,
+        login,
+        logout,
+        hasRole,
+        hasAnyRole,
+    }), [user, isLoading, error, login, logout, hasRole, hasAnyRole]);
+    return _jsx(CasContext.Provider, { value: value, children: children });
+}
+//# sourceMappingURL=CasProvider.js.map

package/dist/CasProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CasProvider.js","sourceRoot":"","sources":["../src/CasProvider.tsx"],"names":[],"mappings":"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"}

package/dist/cas-client.d.ts

@@ -0,0 +1,161 @@
+import type { CasConfig, CasUser } from './types';
+/**
+ * Core CAS (Central Authentication System) client for browser-side operations.
+ *
+ * This class handles the SSO redirect flow, token extraction from callback URLs,
+ * session management via `sessionStorage`, and role-based access checks.
+ *
+ * **Security note:** Token validation is ALWAYS delegated to your backend.
+ * This client never sends `client_secret` or validates JWTs in the browser.
+ *
+ * @example
+ * ```ts
+ * import { CasClient } from '@cas-system/react-cas-client';
+ *
+ * const client = new CasClient({
+ *   serverUrl: 'https://cas.example.com',
+ *   clientId: 'my-app',
+ *   callbackUrl: 'https://myapp.com/auth/callback',
+ *   backendValidateUrl: '/api/auth/validate',
+ * });
+ *
+ * // Redirect to CAS login
+ * client.login();
+ *
+ * // Handle the callback (after redirect back)
+ * const user = await client.handleCallback();
+ * ```
+ */
+export declare class CasClient {
+    private readonly config;
+    /**
+     * Create a new CAS client instance.
+     * @param config - The CAS configuration object.
+     */
+    constructor(config: CasConfig);
+    /**
+     * Build the full CAS SSO login URL.
+     *
+     * @param returnUrl - Optional URL to return to after authentication.
+     *   Falls back to `config.callbackUrl`, then to `window.location.href`.
+     * @returns The complete login URL including query parameters.
+     *
+     * @example
+     * ```ts
+     * const url = client.getLoginUrl('/dashboard');
+     * // => "https://cas.example.com/sso/login?client_id=my-app&response_type=token&redirect_uri=https://myapp.com/dashboard"
+     * ```
+     */
+    getLoginUrl(returnUrl?: string): string;
+    /**
+     * Redirect the browser to the CAS SSO login page.
+     *
+     * @param returnUrl - Optional URL to return to after authentication.
+     */
+    login(returnUrl?: string): void;
+    /**
+     * Extract the JWT token from the current URL's `?token=` query parameter.
+     *
+     * After the CAS server authenticates the user, it redirects back to
+     * `callbackUrl?token=JWT_TOKEN`. This method reads that parameter.
+     *
+     * @returns The JWT token string, or `null` if not present.
+     */
+    extractTokenFromUrl(): string | null;
+    /**
+     * Send the token to your backend for validation.
+     *
+     * Your backend should forward the token to
+     * `POST {casServerUrl}/api/validate-token` along with `client_id` and
+     * `client_secret` — values that must **never** be exposed to the browser.
+     *
+     * @param token - The JWT token to validate.
+     * @returns The validated {@link CasUser} object.
+     * @throws {Error} If `backendValidateUrl` is not configured or the request fails.
+     *
+     * @example
+     * ```ts
+     * const user = await client.validateTokenViaBackend(token);
+     * console.log(user.username); // 'john_doe'
+     * ```
+     */
+    validateTokenViaBackend(token: string): Promise<CasUser>;
+    /**
+     * Full callback handler: extract the token from the URL, validate it via the
+     * backend, persist the user in `sessionStorage`, and clean the URL.
+     *
+     * Call this on the page the CAS server redirects to after login.
+     *
+     * @returns The validated {@link CasUser}, or `null` if no `?token=` param is present.
+     * @throws {Error} If token validation fails.
+     */
+    handleCallback(): Promise<CasUser | null>;
+    /**
+     * Retrieve the currently stored user from `sessionStorage`.
+     *
+     * @returns The stored {@link CasUser}, or `null` if no session exists.
+     */
+    getUser(): CasUser | null;
+    /**
+     * Retrieve the currently stored JWT token from `sessionStorage`.
+     *
+     * @returns The stored token string, or `null` if no session exists.
+     */
+    getToken(): string | null;
+    /**
+     * Check whether a user session currently exists.
+     *
+     * @returns `true` if a user is stored in `sessionStorage`.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Persist a {@link CasUser} in `sessionStorage`.
+     * @internal
+     */
+    private setUser;
+    /**
+     * Persist a JWT token in `sessionStorage`.
+     * @internal
+     */
+    private setToken;
+    /**
+     * Clear all CAS-related data from `sessionStorage`.
+     * @internal
+     */
+    private clearSession;
+    /**
+     * Log the user out by clearing the local session, calling the CAS server's
+     * logout endpoint, and optionally redirecting.
+     *
+     * @param redirectUrl - URL to navigate to after logout. If omitted, the
+     *   page is reloaded at the current location.
+     */
+    logout(redirectUrl?: string): Promise<void>;
+    /**
+     * Check whether the current user has a specific role.
+     *
+     * @param role - The role to check (case-sensitive).
+     * @returns `true` if the stored user has the given role.
+     */
+    userHasRole(role: string): boolean;
+    /**
+     * Check whether the current user has **at least one** of the given roles.
+     *
+     * @param roles - The roles to check.
+     * @returns `true` if the user has any of the specified roles.
+     */
+    userHasAnyRole(roles: string[]): boolean;
+    /**
+     * Check whether the current user has **all** of the given roles.
+     *
+     * @param roles - The roles to check.
+     * @returns `true` if the user has every specified role.
+     */
+    userHasAllRoles(roles: string[]): boolean;
+    /**
+     * Remove the `token` query parameter from the browser URL without reloading.
+     * @internal
+     */
+    private cleanUrl;
+}
+//# sourceMappingURL=cas-client.d.ts.map

package/dist/cas-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cas-client.d.ts","sourceRoot":"","sources":["../src/cas-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAQlD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC;;;OAGG;gBACS,MAAM,EAAE,SAAS;IAQ7B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAiBvC;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAU/B;;;;;;;OAOG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAOpC;;;;;;;;;;;;;;;;OAgBG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4B9D;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAoB/C;;;;OAIG;IACH,OAAO,IAAI,OAAO,GAAG,IAAI;IAWzB;;;;OAIG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAUzB;;;;OAIG;IACH,eAAe,IAAI,OAAO;IAI1B;;;OAGG;IACH,OAAO,CAAC,OAAO;IAKf;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;OAMG;IACG,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BjD;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKlC;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO;IAMxC;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO;IAUzC;;;OAGG;IACH,OAAO,CAAC,QAAQ;CASjB"}

package/dist/cas-client.js

@@ -0,0 +1,309 @@
+/** Key used to persist user data in sessionStorage. */
+const STORAGE_KEY = 'cas_user';
+/** Key used to persist the JWT token in sessionStorage. */
+const TOKEN_STORAGE_KEY = 'cas_token';
+/**
+ * Core CAS (Central Authentication System) client for browser-side operations.
+ *
+ * This class handles the SSO redirect flow, token extraction from callback URLs,
+ * session management via `sessionStorage`, and role-based access checks.
+ *
+ * **Security note:** Token validation is ALWAYS delegated to your backend.
+ * This client never sends `client_secret` or validates JWTs in the browser.
+ *
+ * @example
+ * ```ts
+ * import { CasClient } from '@cas-system/react-cas-client';
+ *
+ * const client = new CasClient({
+ *   serverUrl: 'https://cas.example.com',
+ *   clientId: 'my-app',
+ *   callbackUrl: 'https://myapp.com/auth/callback',
+ *   backendValidateUrl: '/api/auth/validate',
+ * });
+ *
+ * // Redirect to CAS login
+ * client.login();
+ *
+ * // Handle the callback (after redirect back)
+ * const user = await client.handleCallback();
+ * ```
+ */
+export class CasClient {
+    /**
+     * Create a new CAS client instance.
+     * @param config - The CAS configuration object.
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    // ---------------------------------------------------------------------------
+    // Login / Redirect
+    // ---------------------------------------------------------------------------
+    /**
+     * Build the full CAS SSO login URL.
+     *
+     * @param returnUrl - Optional URL to return to after authentication.
+     *   Falls back to `config.callbackUrl`, then to `window.location.href`.
+     * @returns The complete login URL including query parameters.
+     *
+     * @example
+     * ```ts
+     * const url = client.getLoginUrl('/dashboard');
+     * // => "https://cas.example.com/sso/login?client_id=my-app&response_type=token&redirect_uri=https://myapp.com/dashboard"
+     * ```
+     */
+    getLoginUrl(returnUrl) {
+        const redirectUri = returnUrl ??
+            this.config.callbackUrl ??
+            (typeof window !== 'undefined'
+                ? window.location.href
+                : '');
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            response_type: 'token',
+            redirect_uri: redirectUri,
+        });
+        return `${this.config.serverUrl}/sso/login?${params.toString()}`;
+    }
+    /**
+     * Redirect the browser to the CAS SSO login page.
+     *
+     * @param returnUrl - Optional URL to return to after authentication.
+     */
+    login(returnUrl) {
+        if (typeof window !== 'undefined') {
+            window.location.href = this.getLoginUrl(returnUrl);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Token Handling
+    // ---------------------------------------------------------------------------
+    /**
+     * Extract the JWT token from the current URL's `?token=` query parameter.
+     *
+     * After the CAS server authenticates the user, it redirects back to
+     * `callbackUrl?token=JWT_TOKEN`. This method reads that parameter.
+     *
+     * @returns The JWT token string, or `null` if not present.
+     */
+    extractTokenFromUrl() {
+        if (typeof window === 'undefined')
+            return null;
+        const params = new URLSearchParams(window.location.search);
+        return params.get('token');
+    }
+    /**
+     * Send the token to your backend for validation.
+     *
+     * Your backend should forward the token to
+     * `POST {casServerUrl}/api/validate-token` along with `client_id` and
+     * `client_secret` — values that must **never** be exposed to the browser.
+     *
+     * @param token - The JWT token to validate.
+     * @returns The validated {@link CasUser} object.
+     * @throws {Error} If `backendValidateUrl` is not configured or the request fails.
+     *
+     * @example
+     * ```ts
+     * const user = await client.validateTokenViaBackend(token);
+     * console.log(user.username); // 'john_doe'
+     * ```
+     */
+    async validateTokenViaBackend(token) {
+        const { backendValidateUrl } = this.config;
+        if (!backendValidateUrl) {
+            throw new Error('[CAS Client] backendValidateUrl is not configured. ' +
+                'Token validation must be performed by your backend server.');
+        }
+        const response = await fetch(backendValidateUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token }),
+            credentials: 'include',
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new Error(`[CAS Client] Token validation failed (${response.status}): ${errorText}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Full callback handler: extract the token from the URL, validate it via the
+     * backend, persist the user in `sessionStorage`, and clean the URL.
+     *
+     * Call this on the page the CAS server redirects to after login.
+     *
+     * @returns The validated {@link CasUser}, or `null` if no `?token=` param is present.
+     * @throws {Error} If token validation fails.
+     */
+    async handleCallback() {
+        const token = this.extractTokenFromUrl();
+        if (!token)
+            return null;
+        const user = await this.validateTokenViaBackend(token);
+        // Persist user and token in sessionStorage
+        this.setUser(user);
+        this.setToken(token);
+        // Remove the token from the URL to prevent accidental leakage
+        this.cleanUrl();
+        return user;
+    }
+    // ---------------------------------------------------------------------------
+    // Session Management
+    // ---------------------------------------------------------------------------
+    /**
+     * Retrieve the currently stored user from `sessionStorage`.
+     *
+     * @returns The stored {@link CasUser}, or `null` if no session exists.
+     */
+    getUser() {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            const raw = sessionStorage.getItem(STORAGE_KEY);
+            return raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Retrieve the currently stored JWT token from `sessionStorage`.
+     *
+     * @returns The stored token string, or `null` if no session exists.
+     */
+    getToken() {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            return sessionStorage.getItem(TOKEN_STORAGE_KEY);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check whether a user session currently exists.
+     *
+     * @returns `true` if a user is stored in `sessionStorage`.
+     */
+    isAuthenticated() {
+        return this.getUser() !== null;
+    }
+    /**
+     * Persist a {@link CasUser} in `sessionStorage`.
+     * @internal
+     */
+    setUser(user) {
+        if (typeof window === 'undefined')
+            return;
+        sessionStorage.setItem(STORAGE_KEY, JSON.stringify(user));
+    }
+    /**
+     * Persist a JWT token in `sessionStorage`.
+     * @internal
+     */
+    setToken(token) {
+        if (typeof window === 'undefined')
+            return;
+        sessionStorage.setItem(TOKEN_STORAGE_KEY, token);
+    }
+    /**
+     * Clear all CAS-related data from `sessionStorage`.
+     * @internal
+     */
+    clearSession() {
+        if (typeof window === 'undefined')
+            return;
+        sessionStorage.removeItem(STORAGE_KEY);
+        sessionStorage.removeItem(TOKEN_STORAGE_KEY);
+    }
+    // ---------------------------------------------------------------------------
+    // Logout
+    // ---------------------------------------------------------------------------
+    /**
+     * Log the user out by clearing the local session, calling the CAS server's
+     * logout endpoint, and optionally redirecting.
+     *
+     * @param redirectUrl - URL to navigate to after logout. If omitted, the
+     *   page is reloaded at the current location.
+     */
+    async logout(redirectUrl) {
+        // Clear local session first
+        this.clearSession();
+        // Call the CAS server logout endpoint (fire-and-forget)
+        try {
+            await fetch(`${this.config.serverUrl}/api/logout`, {
+                method: 'POST',
+                credentials: 'include',
+            });
+        }
+        catch {
+            // Swallow network errors — the local session is already cleared
+        }
+        // Redirect
+        if (typeof window !== 'undefined') {
+            if (redirectUrl) {
+                window.location.href = redirectUrl;
+            }
+            else {
+                window.location.reload();
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Role Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Check whether the current user has a specific role.
+     *
+     * @param role - The role to check (case-sensitive).
+     * @returns `true` if the stored user has the given role.
+     */
+    userHasRole(role) {
+        const user = this.getUser();
+        return user?.roles?.includes(role) ?? false;
+    }
+    /**
+     * Check whether the current user has **at least one** of the given roles.
+     *
+     * @param roles - The roles to check.
+     * @returns `true` if the user has any of the specified roles.
+     */
+    userHasAnyRole(roles) {
+        const user = this.getUser();
+        if (!user?.roles)
+            return false;
+        return roles.some((role) => user.roles.includes(role));
+    }
+    /**
+     * Check whether the current user has **all** of the given roles.
+     *
+     * @param roles - The roles to check.
+     * @returns `true` if the user has every specified role.
+     */
+    userHasAllRoles(roles) {
+        const user = this.getUser();
+        if (!user?.roles)
+            return false;
+        return roles.every((role) => user.roles.includes(role));
+    }
+    // ---------------------------------------------------------------------------
+    // Internal Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Remove the `token` query parameter from the browser URL without reloading.
+     * @internal
+     */
+    cleanUrl() {
+        if (typeof window === 'undefined')
+            return;
+        const url = new URL(window.location.href);
+        url.searchParams.delete('token');
+        const cleanedUrl = url.pathname + (url.search || '') + url.hash;
+        window.history.replaceState({}, document.title, cleanedUrl);
+    }
+}
+//# sourceMappingURL=cas-client.js.map