@chemmangat/msal-next 1.2.1 → 2.0.1

package/dist/index.d.mts

@@ -1,8 +1,27 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Configuration, LogLevel, IPublicClientApplication, PublicClientApplication, AccountInfo } from '@azure/msal-browser';
-import { ReactNode, CSSProperties } from 'react';
+export { AccountInfo } from '@azure/msal-browser';
+import { ReactNode, CSSProperties, Component, ErrorInfo, ComponentType } from 'react';
+import { NextRequest, NextResponse } from 'next/server';
 export { useAccount, useIsAuthenticated, useMsal } from '@azure/msal-react';
 
+/**
+ * Custom token claims interface for TypeScript generics
+ * Extend this interface to add your custom claims
+ *
+ * @example
+ * ```tsx
+ * interface MyCustomClaims extends CustomTokenClaims {
+ *   roles: string[];
+ *   department: string;
+ * }
+ *
+ * const claims = account.idTokenClaims as MyCustomClaims;
+ * ```
+ */
+interface CustomTokenClaims {
+    [key: string]: any;
+}
 interface MsalAuthConfig {
     /**
      * Azure AD Application (client) ID
@@ -60,6 +79,12 @@ interface MsalAuthConfig {
      * Custom logger callback
      */
     loggerCallback?: (level: LogLevel, message: string, containsPii: boolean) => void;
+    /**
+     * Allowed redirect URIs for validation (optional but recommended)
+     * Helps prevent open redirect vulnerabilities
+     * @example ['https://myapp.com', 'http://localhost:3000']
+     */
+    allowedRedirectUris?: string[];
     /**
      * Loading component to show while MSAL initializes
      */
@@ -124,6 +149,207 @@ interface MicrosoftSignInButtonProps {
 }
 declare function MicrosoftSignInButton({ text, variant, size, useRedirect, scopes, className, style, onSuccess, onError, }: MicrosoftSignInButtonProps): react_jsx_runtime.JSX.Element;
 
+interface SignOutButtonProps {
+    /**
+     * Button text
+     * @default 'Sign out'
+     */
+    text?: string;
+    /**
+     * Button variant
+     * @default 'dark'
+     */
+    variant?: 'dark' | 'light';
+    /**
+     * Button size
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Use redirect flow instead of popup
+     * @default false
+     */
+    useRedirect?: boolean;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Custom styles
+     */
+    style?: CSSProperties;
+    /**
+     * Callback on successful logout
+     */
+    onSuccess?: () => void;
+    /**
+     * Callback on error
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * SignOutButton component with Microsoft branding
+ *
+ * @example
+ * ```tsx
+ * <SignOutButton variant="light" />
+ * ```
+ */
+declare function SignOutButton({ text, variant, size, useRedirect, className, style, onSuccess, onError, }: SignOutButtonProps): react_jsx_runtime.JSX.Element;
+
+interface UserAvatarProps {
+    /**
+     * Avatar size in pixels
+     * @default 40
+     */
+    size?: number;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Custom styles
+     */
+    style?: CSSProperties;
+    /**
+     * Show user name tooltip on hover
+     * @default true
+     */
+    showTooltip?: boolean;
+    /**
+     * Fallback image URL if MS Graph photo fails
+     */
+    fallbackImage?: string;
+}
+/**
+ * UserAvatar component that displays user photo from MS Graph with fallback initials
+ *
+ * @example
+ * ```tsx
+ * <UserAvatar size={48} />
+ * ```
+ */
+declare function UserAvatar({ size, className, style, showTooltip, fallbackImage, }: UserAvatarProps): react_jsx_runtime.JSX.Element;
+
+interface AuthStatusProps {
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Custom styles
+     */
+    style?: CSSProperties;
+    /**
+     * Show detailed status (includes username)
+     * @default false
+     */
+    showDetails?: boolean;
+    /**
+     * Custom render function for loading state
+     */
+    renderLoading?: () => ReactNode;
+    /**
+     * Custom render function for authenticated state
+     */
+    renderAuthenticated?: (username: string) => ReactNode;
+    /**
+     * Custom render function for unauthenticated state
+     */
+    renderUnauthenticated?: () => ReactNode;
+}
+/**
+ * AuthStatus component that shows current authentication state
+ *
+ * @example
+ * ```tsx
+ * <AuthStatus showDetails />
+ * ```
+ */
+declare function AuthStatus({ className, style, showDetails, renderLoading, renderAuthenticated, renderUnauthenticated, }: AuthStatusProps): react_jsx_runtime.JSX.Element;
+
+interface AuthGuardProps {
+    /**
+     * Content to render when authenticated
+     */
+    children: ReactNode;
+    /**
+     * Component to show while checking authentication
+     */
+    loadingComponent?: ReactNode;
+    /**
+     * Component to show when not authenticated (before redirect)
+     */
+    fallbackComponent?: ReactNode;
+    /**
+     * Use redirect flow instead of popup
+     * @default true
+     */
+    useRedirect?: boolean;
+    /**
+     * Scopes to request during authentication
+     */
+    scopes?: string[];
+    /**
+     * Callback when authentication is required
+     */
+    onAuthRequired?: () => void;
+}
+/**
+ * AuthGuard component that protects content and auto-redirects to login
+ *
+ * @example
+ * ```tsx
+ * <AuthGuard>
+ *   <ProtectedContent />
+ * </AuthGuard>
+ * ```
+ */
+declare function AuthGuard({ children, loadingComponent, fallbackComponent, useRedirect, scopes, onAuthRequired, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
+
+interface ErrorBoundaryProps {
+    /**
+     * Content to render when no error
+     */
+    children: ReactNode;
+    /**
+     * Custom error fallback component
+     */
+    fallback?: (error: Error, reset: () => void) => ReactNode;
+    /**
+     * Callback when error occurs
+     */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary for catching authentication errors
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary>
+ *   <MsalAuthProvider clientId="...">
+ *     <App />
+ *   </MsalAuthProvider>
+ * </ErrorBoundary>
+ * ```
+ */
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
 interface UseMsalAuthReturn {
     /**
      * Current authenticated account
@@ -180,4 +406,408 @@ interface UseMsalAuthReturn {
 }
 declare function useMsalAuth(defaultScopes?: string[]): UseMsalAuthReturn;
 
-export { MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, type UseMsalAuthReturn, getMsalInstance, useMsalAuth };
+interface GraphApiOptions extends RequestInit {
+    /**
+     * Scopes required for the API call
+     * @default ['User.Read']
+     */
+    scopes?: string[];
+    /**
+     * API version
+     * @default 'v1.0'
+     */
+    version?: 'v1.0' | 'beta';
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+interface UseGraphApiReturn {
+    /**
+     * Make a GET request to MS Graph API
+     */
+    get: <T = any>(endpoint: string, options?: GraphApiOptions) => Promise<T>;
+    /**
+     * Make a POST request to MS Graph API
+     */
+    post: <T = any>(endpoint: string, body?: any, options?: GraphApiOptions) => Promise<T>;
+    /**
+     * Make a PUT request to MS Graph API
+     */
+    put: <T = any>(endpoint: string, body?: any, options?: GraphApiOptions) => Promise<T>;
+    /**
+     * Make a PATCH request to MS Graph API
+     */
+    patch: <T = any>(endpoint: string, body?: any, options?: GraphApiOptions) => Promise<T>;
+    /**
+     * Make a DELETE request to MS Graph API
+     */
+    delete: <T = any>(endpoint: string, options?: GraphApiOptions) => Promise<T>;
+    /**
+     * Make a custom request to MS Graph API
+     */
+    request: <T = any>(endpoint: string, options?: GraphApiOptions) => Promise<T>;
+}
+/**
+ * Hook for making authenticated requests to MS Graph API
+ *
+ * @example
+ * ```tsx
+ * const graph = useGraphApi();
+ * const user = await graph.get('/me');
+ * ```
+ */
+declare function useGraphApi(): UseGraphApiReturn;
+
+interface UserProfile {
+    id: string;
+    displayName: string;
+    givenName: string;
+    surname: string;
+    userPrincipalName: string;
+    mail: string;
+    jobTitle?: string;
+    officeLocation?: string;
+    mobilePhone?: string;
+    businessPhones?: string[];
+    photo?: string;
+}
+interface UseUserProfileReturn {
+    /**
+     * User profile data
+     */
+    profile: UserProfile | null;
+    /**
+     * Whether profile is loading
+     */
+    loading: boolean;
+    /**
+     * Error if profile fetch failed
+     */
+    error: Error | null;
+    /**
+     * Refetch user profile
+     */
+    refetch: () => Promise<void>;
+    /**
+     * Clear cached profile
+     */
+    clearCache: () => void;
+}
+/**
+ * Hook for fetching and caching user profile from MS Graph
+ *
+ * @example
+ * ```tsx
+ * const { profile, loading } = useUserProfile();
+ * ```
+ */
+declare function useUserProfile(): UseUserProfileReturn;
+
+interface UseRolesReturn {
+    /**
+     * User's Azure AD roles
+     */
+    roles: string[];
+    /**
+     * User's Azure AD groups
+     */
+    groups: string[];
+    /**
+     * Whether roles/groups are loading
+     */
+    loading: boolean;
+    /**
+     * Error if fetch failed
+     */
+    error: Error | null;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole: (role: string) => boolean;
+    /**
+     * Check if user is in a specific group
+     */
+    hasGroup: (groupId: string) => boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole: (roles: string[]) => boolean;
+    /**
+     * Check if user has all of the specified roles
+     */
+    hasAllRoles: (roles: string[]) => boolean;
+    /**
+     * Refetch roles and groups
+     */
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook for fetching user's Azure AD roles and groups
+ *
+ * @example
+ * ```tsx
+ * const { roles, hasRole } = useRoles();
+ * if (hasRole('Admin')) {
+ *   // Show admin content
+ * }
+ * ```
+ */
+declare function useRoles(): UseRolesReturn;
+
+declare function createMsalConfig(config: MsalAuthConfig): Configuration;
+
+interface WithAuthOptions extends Omit<AuthGuardProps, 'children'> {
+    /**
+     * Display name for the wrapped component (for debugging)
+     */
+    displayName?: string;
+}
+/**
+ * Higher-order component for protecting pages/components
+ *
+ * @example
+ * ```tsx
+ * const ProtectedPage = withAuth(MyPage);
+ *
+ * // With options
+ * const ProtectedPage = withAuth(MyPage, {
+ *   useRedirect: true,
+ *   scopes: ['User.Read', 'Mail.Read']
+ * });
+ * ```
+ */
+declare function withAuth<P extends object>(Component: ComponentType<P>, options?: WithAuthOptions): ComponentType<P>;
+
+/**
+ * Retry configuration for token acquisition
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds
+     * @default 10000
+     */
+    maxDelay?: number;
+    /**
+     * Backoff multiplier
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Exponential backoff retry utility for token acquisition
+ *
+ * @example
+ * ```tsx
+ * const token = await retryWithBackoff(
+ *   () => acquireTokenSilent(scopes),
+ *   { maxRetries: 3, debug: true }
+ * );
+ * ```
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Create a retry wrapper for a function
+ *
+ * @example
+ * ```tsx
+ * const acquireTokenWithRetry = createRetryWrapper(acquireToken, {
+ *   maxRetries: 3,
+ *   debug: true
+ * });
+ *
+ * const token = await acquireTokenWithRetry(scopes);
+ * ```
+ */
+declare function createRetryWrapper<TArgs extends any[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, config?: RetryConfig): (...args: TArgs) => Promise<TReturn>;
+
+/**
+ * Debug logger configuration
+ */
+interface DebugLoggerConfig {
+    /**
+     * Enable debug mode
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Prefix for log messages
+     * @default '[MSAL-Next]'
+     */
+    prefix?: string;
+    /**
+     * Show timestamps
+     * @default true
+     */
+    showTimestamp?: boolean;
+    /**
+     * Log level
+     * @default 'info'
+     */
+    level?: 'error' | 'warn' | 'info' | 'debug';
+}
+declare class DebugLogger {
+    private config;
+    constructor(config?: DebugLoggerConfig);
+    private shouldLog;
+    private formatMessage;
+    error(message: string, data?: any): void;
+    warn(message: string, data?: any): void;
+    info(message: string, data?: any): void;
+    debug(message: string, data?: any): void;
+    group(label: string): void;
+    groupEnd(): void;
+    setEnabled(enabled: boolean): void;
+    setLevel(level: DebugLoggerConfig['level']): void;
+}
+/**
+ * Get or create the global debug logger
+ *
+ * @example
+ * ```tsx
+ * const logger = getDebugLogger({ enabled: true, level: 'debug' });
+ * logger.info('User logged in', { username: 'user@example.com' });
+ * ```
+ */
+declare function getDebugLogger(config?: DebugLoggerConfig): DebugLogger;
+/**
+ * Create a scoped logger with a custom prefix
+ *
+ * @example
+ * ```tsx
+ * const logger = createScopedLogger('GraphAPI', { enabled: true });
+ * logger.info('Fetching user profile');
+ * ```
+ */
+declare function createScopedLogger(scope: string, config?: DebugLoggerConfig): DebugLogger;
+
+/**
+ * Security utilities for input validation and sanitization
+ */
+/**
+ * Validate account data structure from cookie
+ */
+interface ValidatedAccountData {
+    homeAccountId: string;
+    username: string;
+    name?: string;
+}
+/**
+ * Safely parse and validate JSON from untrusted sources
+ */
+declare function safeJsonParse<T>(jsonString: string, validator: (data: any) => data is T): T | null;
+/**
+ * Validate account data structure
+ */
+declare function isValidAccountData(data: any): data is ValidatedAccountData;
+/**
+ * Sanitize error messages to prevent information disclosure
+ */
+declare function sanitizeError(error: unknown): string;
+/**
+ * Validate redirect URI to prevent open redirect vulnerabilities
+ */
+declare function isValidRedirectUri(uri: string, allowedOrigins: string[]): boolean;
+/**
+ * Validate scope strings to prevent injection
+ */
+declare function isValidScope(scope: string): boolean;
+/**
+ * Validate array of scopes
+ */
+declare function validateScopes(scopes: string[]): boolean;
+
+interface AuthMiddlewareConfig {
+    /**
+     * Routes that require authentication
+     * @example ['/dashboard', '/profile', '/api/protected']
+     */
+    protectedRoutes?: string[];
+    /**
+     * Routes that should be accessible only when NOT authenticated
+     * @example ['/login', '/signup']
+     */
+    publicOnlyRoutes?: string[];
+    /**
+     * Login page path
+     * @default '/login'
+     */
+    loginPath?: string;
+    /**
+     * Redirect path after login
+     * @default '/'
+     */
+    redirectAfterLogin?: string;
+    /**
+     * Cookie name for session
+     * @default 'msal.account'
+     */
+    sessionCookie?: string;
+    /**
+     * Custom authentication check function
+     */
+    isAuthenticated?: (request: NextRequest) => boolean | Promise<boolean>;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Creates authentication middleware for Next.js App Router
+ *
+ * @example
+ * ```tsx
+ * // middleware.ts
+ * import { createAuthMiddleware } from '@chemmangat/msal-next';
+ *
+ * export const middleware = createAuthMiddleware({
+ *   protectedRoutes: ['/dashboard', '/profile'],
+ *   publicOnlyRoutes: ['/login'],
+ *   loginPath: '/login',
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+ * };
+ * ```
+ */
+declare function createAuthMiddleware(config?: AuthMiddlewareConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+interface ServerSession {
+    /**
+     * Whether user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * User's account ID from MSAL cache
+     */
+    accountId?: string;
+    /**
+     * User's username/email
+     */
+    username?: string;
+    /**
+     * Access token (if available in cookie)
+     * @deprecated Storing tokens in cookies is not recommended for security reasons
+     */
+    accessToken?: string;
+}
+
+export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type UseGraphApiReturn, type UseMsalAuthReturn, type UseRolesReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type WithAuthOptions, createAuthMiddleware, createMsalConfig, createRetryWrapper, createScopedLogger, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useUserProfile, validateScopes, withAuth };