@chemmangat/msal-next 4.2.0 → 4.2.2

package/README.md

@@ -1,108 +1,29 @@
 # @chemmangat/msal-next
 
-Production-grade MSAL authentication library for Next.js App Router with minimal boilerplate.
+Microsoft/Azure AD authentication for Next.js App Router. Minimal setup, full TypeScript support, production-ready.
 
 [![npm version](https://badge.fury.io/js/@chemmangat%2Fmsal-next.svg)](https://www.npmjs.com/package/@chemmangat/msal-next)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Security](https://img.shields.io/badge/Security-A+-green.svg)](./SECURITY.md)
 
-> **📦 Current Version: 4.1.1** - Production-ready with automatic token refresh and enhanced security
+**Current version: 4.2.1**
 
 ---
 
-## ⭐ Why Choose @chemmangat/msal-next?
-
-### 🚀 **5-Minute Setup**
-Get Azure AD authentication running in your Next.js app in just 5 minutes. No complex configuration, no boilerplate.
-
-### 🔒 **Enterprise Security**
-Built on Microsoft's official MSAL library. All authentication happens client-side - tokens never touch your server. [Read Security Policy →](./SECURITY.md)
-
-### 🎯 **Production-Ready**
-Used by 2,200+ developers in production. Automatic token refresh prevents unexpected logouts. Complete TypeScript support.
-
-### 🤖 **AI-Friendly**
-Complete documentation optimized for AI assistants. Setup instructions that work on the first try.
-
-### ⚡ **Zero Boilerplate**
-```tsx
-<MSALProvider clientId="...">
-  <MicrosoftSignInButton />
-</MSALProvider>
-```
-That's it. You're done.
-
----
-
-## 🎯 Top Features
-
-| Feature | Description | Status |
-|---------|-------------|--------|
-| **Automatic Token Refresh** | Prevents unexpected logouts | ✅ v4.1.0 |
-| **Complete TypeScript Types** | 30+ user profile fields | ✅ v4.0.2 |
-| **Actionable Error Messages** | Fix instructions included | ✅ v4.0.2 |
-| **Configuration Validation** | Catches mistakes in dev mode | ✅ v4.0.2 |
-| **Zero-Config Protected Routes** | One line to protect pages | ✅ v4.0.1 |
-| **Server Components Support** | Works in Next.js layouts | ✅ Always |
-| **Microsoft Graph Integration** | Pre-configured API client | ✅ Always |
-| **Role-Based Access Control** | Built-in RBAC support | ✅ Always |
-
----
-
-## 🔒 Security First
-
-**Your tokens never leave the browser:**
-- ✅ Client-side authentication only
-- ✅ No server-side token storage
-- ✅ Microsoft's official MSAL library
-- ✅ Secure token storage (sessionStorage/localStorage)
-- ✅ Automatic error sanitization
-- ✅ HTTPS enforcement in production
-
-**[Read Complete Security Policy →](./SECURITY.md)**
-
----
-
-## 🚀 Quick Start (5 Minutes)
-
-### Step 1: Install the Package
+## Install
 
 ```bash
 npm install @chemmangat/msal-next @azure/msal-browser @azure/msal-react
 ```
 
-### Step 2: Get Your Azure AD Credentials
-
-1. Go to [Azure Portal](https://portal.azure.com)
-2. Navigate to **Azure Active Directory** → **App registrations**
-3. Click **New registration**
-4. Enter a name (e.g., "My Next.js App")
-5. Select **Single-page application (SPA)**
-6. Add redirect URI: `http://localhost:3000` (for development)
-7. Click **Register**
-8. Copy the **Application (client) ID** and **Directory (tenant) ID**
-
-### Step 3: Configure Environment Variables
-
-Create `.env.local` in your project root:
-
-```bash
-# .env.local
-NEXT_PUBLIC_AZURE_AD_CLIENT_ID=your-client-id-here
-NEXT_PUBLIC_AZURE_AD_TENANT_ID=your-tenant-id-here
-```
-
-**Important:** 
-- Replace `your-client-id-here` and `your-tenant-id-here` with actual values from Azure Portal
-- Never commit `.env.local` to version control
-- Variables starting with `NEXT_PUBLIC_` are exposed to the browser (this is correct for MSAL)
+---
 
-**Security Note:** All authentication happens in the browser. Your tokens never touch your Next.js server. [Learn more →](./SECURITY.md)
+## Quick Start
 
-### Step 4: Add Provider to Layout
+### 1. Add the provider to your layout
 
 ```tsx
-// app/layout.tsx (Server Component - no 'use client' needed!)
+// app/layout.tsx (Server Component — no 'use client' needed)
 import { MSALProvider } from '@chemmangat/msal-next';
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -121,489 +42,274 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-**Note:** MSALProvider is already marked as 'use client' internally. You don't need to add 'use client' to your layout.tsx!
+`MSALProvider` is already marked `'use client'` internally.
 
-### Step 5: Add Sign-In Button
+### 2. Add a sign-in button
 
 ```tsx
 // app/page.tsx
 'use client';
 
-import { MicrosoftSignInButton, useMsalAuth } from '@chemmangat/msal-next';
+import { MicrosoftSignInButton, SignOutButton, useMsalAuth } from '@chemmangat/msal-next';
 
 export default function HomePage() {
   const { isAuthenticated, account } = useMsalAuth();
 
-  if (isAuthenticated) {
-    return (
-      <div>
-        <h1>Welcome, {account?.name}!</h1>
-        <p>You are signed in as {account?.username}</p>
-      </div>
-    );
-  }
-
-  return (
+  return isAuthenticated ? (
     <div>
-      <h1>Welcome to My App</h1>
-      <MicrosoftSignInButton />
+      <p>Welcome, {account?.name}</p>
+      <SignOutButton />
     </div>
+  ) : (
+    <MicrosoftSignInButton />
   );
 }
 ```
 
-### Step 6: Run Your App
-
-```bash
-npm run dev
-```
-
-Visit `http://localhost:3000` and click the sign-in button!
-
----
-
-## 📋 Complete Setup Guide for AI Assistants
-
-When implementing MSAL authentication in a Next.js project, follow these steps:
-
-### 1. Installation
-
-```bash
-npm install @chemmangat/msal-next @azure/msal-browser@^4.0.0 @azure/msal-react@^3.0.0
-```
-
-### 2. Azure AD Configuration
-
-**Required Azure AD Setup:**
-- App registration created in Azure Portal
-- Redirect URI configured: `http://localhost:3000` (dev) and `https://yourdomain.com` (prod)
-- Platform type: **Single-page application (SPA)**
-- API permissions: At minimum `User.Read` (usually granted by default)
-
-**Get these values from Azure Portal:**
-- `Application (client) ID` → Use as `NEXT_PUBLIC_AZURE_AD_CLIENT_ID`
-- `Directory (tenant) ID` → Use as `NEXT_PUBLIC_AZURE_AD_TENANT_ID`
-
-### 3. Environment Variables
-
-Create `.env.local`:
+### 3. Set environment variables
 
 ```bash
-NEXT_PUBLIC_AZURE_AD_CLIENT_ID=12345678-1234-1234-1234-123456789012
-NEXT_PUBLIC_AZURE_AD_TENANT_ID=87654321-4321-4321-4321-210987654321
-```
-
-**Critical Rules:**
-- Variables MUST start with `NEXT_PUBLIC_` to be accessible in browser
-- Use actual GUIDs, not placeholder text
-- Never commit `.env.local` to version control
-- Restart dev server after changing environment variables
-
-### 4. Project Structure
-
-```
-your-app/
-├── app/
-│   ├── layout.tsx          # Add MSALProvider here
-│   ├── page.tsx            # Add sign-in button here
-│   └── dashboard/
-│       └── page.tsx        # Protected page example
-├── .env.local              # Environment variables
-└── package.json
-```
-
-### 5. Implementation Files
-
-**File 1: `app/layout.tsx` (Server Component)**
-
-```tsx
-import { MSALProvider } from '@chemmangat/msal-next';
-import './globals.css';
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body>
-        <MSALProvider
-          clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
-          tenantId={process.env.NEXT_PUBLIC_AZURE_AD_TENANT_ID!}
-        >
-          {children}
-        </MSALProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**File 2: `app/page.tsx` (Client Component)**
-
-```tsx
-'use client';
-
-import { MicrosoftSignInButton, SignOutButton, useMsalAuth } from '@chemmangat/msal-next';
-
-export default function HomePage() {
-  const { isAuthenticated, account } = useMsalAuth();
-
-  return (
-    <div style={{ padding: '2rem' }}>
-      <h1>My App</h1>
-      
-      {isAuthenticated ? (
-        <div>
-          <p>Welcome, {account?.name}!</p>
-          <p>Email: {account?.username}</p>
-          <SignOutButton />
-        </div>
-      ) : (
-        <div>
-          <p>Please sign in to continue</p>
-          <MicrosoftSignInButton />
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-**File 3: `app/dashboard/page.tsx` (Protected Page)**
-
-```tsx
-'use client';
-
-import { AuthGuard, useUserProfile } from '@chemmangat/msal-next';
-
-export default function DashboardPage() {
-  return (
-    <AuthGuard>
-      <DashboardContent />
-    </AuthGuard>
-  );
-}
-
-function DashboardContent() {
-  const { profile, loading } = useUserProfile();
-
-  if (loading) return <div>Loading profile...</div>;
-
-  return (
-    <div style={{ padding: '2rem' }}>
-      <h1>Dashboard</h1>
-      <p>Name: {profile?.displayName}</p>
-      <p>Email: {profile?.mail}</p>
-      <p>Job Title: {profile?.jobTitle}</p>
-      <p>Department: {profile?.department}</p>
-    </div>
-  );
-}
-```
-
-### 6. Common Patterns
-
-**Pattern 1: Check Authentication Status**
-
-```tsx
-'use client';
-
-import { useMsalAuth } from '@chemmangat/msal-next';
-
-export default function MyComponent() {
-  const { isAuthenticated, account, inProgress } = useMsalAuth();
-
-  if (inProgress) return <div>Loading...</div>;
-  if (!isAuthenticated) return <div>Please sign in</div>;
-
-  return <div>Hello, {account?.name}!</div>;
-}
-```
-
-**Pattern 2: Get Access Token**
-
-```tsx
-'use client';
-
-import { useMsalAuth } from '@chemmangat/msal-next';
-import { useEffect, useState } from 'react';
-
-export default function DataComponent() {
-  const { acquireToken, isAuthenticated } = useMsalAuth();
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    async function fetchData() {
-      if (!isAuthenticated) return;
-
-      try {
-        const token = await acquireToken(['User.Read']);
-        
-        const response = await fetch('https://graph.microsoft.com/v1.0/me', {
-          headers: { Authorization: `Bearer ${token}` },
-        });
-        
-        const result = await response.json();
-        setData(result);
-      } catch (error) {
-        console.error('Error fetching data:', error);
-      }
-    }
-
-    fetchData();
-  }, [isAuthenticated, acquireToken]);
-
-  return <div>{/* Render data */}</div>;
-}
-```
-
-**Pattern 3: Protect Routes**
-
-```tsx
-'use client';
-
-import { AuthGuard } from '@chemmangat/msal-next';
-
-export default function ProtectedPage() {
-  return (
-    <AuthGuard
-      loadingComponent={<div>Checking authentication...</div>}
-      fallbackComponent={<div>Redirecting to login...</div>}
-    >
-      <div>This content is protected</div>
-    </AuthGuard>
-  );
-}
-```
-
-### 7. Configuration Options
-
-```tsx
-<MSALProvider
-  // Required
-  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
-  
-  // Optional - for single-tenant apps
-  tenantId={process.env.NEXT_PUBLIC_AZURE_AD_TENANT_ID}
-  
-  // Optional - for multi-tenant apps (default: 'common')
-  authorityType="common" // or "organizations", "consumers", "tenant"
-  
-  // Optional - default scopes (default: ['User.Read'])
-  scopes={['User.Read', 'Mail.Read']}
-  
-  // Optional - enable debug logging (default: false)
-  enableLogging={true}
-  
-  // Optional - custom redirect URI (default: window.location.origin)
-  redirectUri="https://yourdomain.com"
-  
-  // Optional - cache location (default: 'sessionStorage')
-  cacheLocation="sessionStorage" // or "localStorage", "memoryStorage"
-  
-  // NEW in v4.1.0 - automatic token refresh
-  autoRefreshToken={true}        // Prevents unexpected logouts
-  refreshBeforeExpiry={300}      // Refresh 5 min before expiry
->
-  {children}
-</MSALProvider>
+# .env.local
+NEXT_PUBLIC_AZURE_AD_CLIENT_ID=your-client-id
+NEXT_PUBLIC_AZURE_AD_TENANT_ID=your-tenant-id
 ```
 
-### 8. Troubleshooting Checklist
-
-**If authentication doesn't work:**
-
-1. ✅ Check environment variables are set correctly
-2. ✅ Restart dev server after adding `.env.local`
-3. ✅ Verify redirect URI in Azure Portal matches your app URL
-4. ✅ Ensure `'use client'` is at the TOP of files using hooks
-5. ✅ Check browser console for errors
-6. ✅ Enable debug logging: `enableLogging={true}`
-7. ✅ Verify client ID and tenant ID are valid GUIDs
-
-**Common Errors:**
+### 4. Azure AD setup
 
-- **"createContext only works in Client Components"** → Use `MSALProvider` (not `MsalAuthProvider`) in layout.tsx
-- **"AADSTS50011: Redirect URI mismatch"** → Add your URL to Azure Portal → Authentication → Redirect URIs
-- **"No active account"** → User needs to sign in first before calling `acquireToken()`
-- **Environment variables undefined** → Restart dev server after creating `.env.local`
+1. Go to [Azure Portal](https://portal.azure.com) → Azure Active Directory → App registrations
+2. Create a new registration, platform type: **Single-page application (SPA)**
+3. Add redirect URI: `http://localhost:3000` (dev) and your production URL
+4. Copy the **Application (client) ID** and **Directory (tenant) ID**
 
 ---
 
-## 🎯 Key Features
-
-- ✅ **Zero-Config Setup** - Works out of the box with minimal configuration
-- ✅ **Automatic Token Refresh** - Prevents unexpected logouts (NEW in v4.1.0)
-- ✅ **TypeScript First** - Complete type safety with 30+ user profile fields
-- ✅ **Next.js 14+ Ready** - Built for App Router with Server Components support
-- ✅ **Automatic Validation** - Catches configuration mistakes in development
-- ✅ **Actionable Errors** - Clear error messages with fix instructions
-- ✅ **Production Ready** - Used by 2,200+ developers in production
-- ✅ **Fixed Interaction Issues** - No more "interaction in progress" errors (v4.1.0)
-
----
-
-## 📚 API Reference
+## API Reference
 
 ### Components
 
 #### MSALProvider
-Wrap your app to provide authentication context.
 
 ```tsx
-<MSALProvider clientId="..." tenantId="...">
+<MSALProvider
+  clientId="..."
+  tenantId="..."
+  authorityType="common"
+  scopes={['User.Read']}
+  redirectUri="https://myapp.com"
+  cacheLocation="sessionStorage"
+  enableLogging={false}
+  autoRefreshToken={true}
+  refreshBeforeExpiry={300}
+  allowedRedirectUris={['https://myapp.com']}
+  protection={{ defaultRedirectTo: '/login' }}
+>
   {children}
 </MSALProvider>
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `clientId` | `string` | required | Azure AD Application (client) ID |
+| `tenantId` | `string` | — | Directory (tenant) ID, single-tenant only |
+| `authorityType` | `'common' \| 'organizations' \| 'consumers' \| 'tenant'` | `'common'` | Authority type |
+| `redirectUri` | `string` | `window.location.origin` | Redirect URI after auth |
+| `postLogoutRedirectUri` | `string` | `redirectUri` | Redirect URI after logout |
+| `scopes` | `string[]` | `['User.Read']` | Default scopes |
+| `cacheLocation` | `'sessionStorage' \| 'localStorage' \| 'memoryStorage'` | `'sessionStorage'` | Token cache location |
+| `enableLogging` | `boolean` | `false` | Debug logging |
+| `autoRefreshToken` | `boolean` | `false` | Auto-refresh tokens before expiry |
+| `refreshBeforeExpiry` | `number` | `300` | Seconds before expiry to refresh |
+| `allowedRedirectUris` | `string[]` | — | Whitelist of allowed redirect URIs |
+| `protection` | `AuthProtectionConfig` | — | Zero-config route protection config |
+
 #### MicrosoftSignInButton
-Pre-styled sign-in button with Microsoft branding.
 
 ```tsx
 <MicrosoftSignInButton
-  variant="dark" // or "light"
-  size="medium"  // "small", "medium", "large"
-  onSuccess={() => console.log('Signed in!')}
+  variant="dark"        // 'dark' | 'light'
+  size="medium"         // 'small' | 'medium' | 'large'
+  text="Sign in with Microsoft"
+  scopes={['User.Read']}
+  onSuccess={() => {}}
+  onError={(error) => {}}
 />
 ```
 
 #### SignOutButton
-Pre-styled sign-out button.
 
 ```tsx
 <SignOutButton
   variant="light"
   size="medium"
-  onSuccess={() => console.log('Signed out!')}
+  onSuccess={() => {}}
+  onError={(error) => {}}
 />
 ```
 
 #### AuthGuard
-Protect components that require authentication.
+
+Protects content and redirects unauthenticated users to login.
 
 ```tsx
 <AuthGuard
   loadingComponent={<div>Loading...</div>}
-  fallbackComponent={<div>Please sign in</div>}
+  fallbackComponent={<div>Redirecting...</div>}
+  scopes={['User.Read']}
+  onAuthRequired={() => {}}
 >
   <ProtectedContent />
 </AuthGuard>
 ```
 
 #### UserAvatar
-Display user photo from Microsoft Graph.
 
 ```tsx
-<UserAvatar
-  size={48}
-  showTooltip={true}
-  fallbackImage="/default-avatar.png"
+<UserAvatar size={48} showTooltip fallbackImage="/avatar.png" />
+```
+
+#### AccountSwitcher
+
+```tsx
+<AccountSwitcher
+  variant="default"     // 'default' | 'compact' | 'minimal'
+  maxAccounts={5}
+  showAvatars
+  showAddButton
+  showRemoveButton
+  onSwitch={(account) => {}}
+  onAdd={() => {}}
+  onRemove={(account) => {}}
+/>
+```
+
+#### AccountList
+
+```tsx
+<AccountList
+  showAvatars
+  showDetails
+  showActiveIndicator
+  clickToSwitch
+  orientation="vertical"  // 'vertical' | 'horizontal'
+  onAccountClick={(account) => {}}
 />
 ```
 
+---
+
 ### Hooks
 
 #### useMsalAuth()
-Main authentication hook.
 
 ```tsx
 const {
-  account,           // Current user account
-  accounts,          // All cached accounts
-  isAuthenticated,   // Boolean: is user signed in?
-  inProgress,        // Boolean: is auth in progress?
-  loginRedirect,     // Function: sign in
-  logoutRedirect,    // Function: sign out
-  acquireToken,      // Function: get access token
+  account,              // AccountInfo | null
+  accounts,             // AccountInfo[]
+  isAuthenticated,      // boolean
+  inProgress,           // boolean
+  loginRedirect,        // (scopes?: string[]) => Promise<void>
+  logoutRedirect,       // () => Promise<void>
+  acquireToken,         // (scopes: string[]) => Promise<string>  — silent with redirect fallback
+  acquireTokenSilent,   // (scopes: string[]) => Promise<string>  — silent only
+  acquireTokenRedirect, // (scopes: string[]) => Promise<void>
+  clearSession,         // () => Promise<void>  — clears cache without Microsoft logout
 } = useMsalAuth();
 ```
 
 #### useUserProfile()
-Fetch user profile from Microsoft Graph.
+
+Fetches user profile from Microsoft Graph `/me` (30+ fields).
 
 ```tsx
 const {
-  profile,    // User profile with 30+ fields
-  loading,    // Boolean: is loading?
-  error,      // Error object if failed
-  refetch,    // Function: refetch profile
-  clearCache, // Function: clear cached profile
+  profile,    // UserProfile | null
+  loading,    // boolean
+  error,      // Error | null
+  refetch,    // () => Promise<void>
+  clearCache, // () => void
 } = useUserProfile();
 
-// Access profile fields
-console.log(profile?.displayName);
-console.log(profile?.department);
-console.log(profile?.preferredLanguage);
-console.log(profile?.employeeId);
+// With custom fields
+interface MyProfile extends UserProfile { customField: string }
+const { profile } = useUserProfile<MyProfile>();
 ```
 
 #### useGraphApi()
-Pre-configured Microsoft Graph API client.
 
 ```tsx
 const graph = useGraphApi();
 
-// GET request
-const user = await graph.get('/me');
-
-// POST request
-const message = await graph.post('/me/messages', {
-  subject: 'Hello',
-  body: { content: 'World' }
-});
+const user   = await graph.get('/me');
+const result = await graph.post('/me/messages', body);
+await graph.put('/me/photo/$value', blob);
+await graph.patch('/me', { displayName: 'New Name' });
+await graph.delete('/me/messages/{id}');
+const data   = await graph.request('/me', { version: 'beta' });
 ```
 
 #### useRoles()
-Access user's Azure AD roles.
 
 ```tsx
 const {
-  roles,        // Array of role names
-  groups,       // Array of group IDs
-  hasRole,      // Function: check single role
-  hasAnyRole,   // Function: check multiple roles
-  hasAllRoles,  // Function: check all roles
+  roles,       // string[]
+  groups,      // string[]
+  loading,     // boolean
+  error,       // Error | null
+  hasRole,     // (role: string) => boolean
+  hasGroup,    // (groupId: string) => boolean
+  hasAnyRole,  // (roles: string[]) => boolean
+  hasAllRoles, // (roles: string[]) => boolean
+  refetch,     // () => Promise<void>
 } = useRoles();
-
-if (hasRole('Admin')) {
-  // Show admin content
-}
 ```
 
----
-
-## 🎓 Advanced Usage
-
-### Automatic Token Refresh (NEW in v4.1.0)
+#### useTokenRefresh()
 
-Prevent unexpected logouts by automatically refreshing tokens before they expire:
+Monitors token expiry and optionally refreshes tokens automatically in the background. Use this when you want to show a session-expiry warning or trigger a manual refresh without relying solely on `MSALProvider`'s `autoRefreshToken` prop.
 
 ```tsx
-<MSALProvider
-  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
-  autoRefreshToken={true}        // Enable automatic refresh
-  refreshBeforeExpiry={300}      // Refresh 5 minutes before expiry
->
-  {children}
-</MSALProvider>
+useTokenRefresh(options?: UseTokenRefreshOptions): UseTokenRefreshReturn
 ```
 
-**Monitor token expiry:**
+Options (`UseTokenRefreshOptions`):
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable automatic background refresh |
+| `refreshBeforeExpiry` | `number` | `300` | Seconds before expiry to trigger refresh |
+| `scopes` | `string[]` | `['User.Read']` | Scopes to refresh |
+| `onRefresh` | `(expiresIn: number) => void` | — | Called after a successful refresh |
+| `onError` | `(error: Error) => void` | — | Called when refresh fails |
+
+Return values (`UseTokenRefreshReturn`):
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `expiresIn` | `number \| null` | Seconds until the current token expires |
+| `isExpiringSoon` | `boolean` | `true` when within `refreshBeforeExpiry` window |
+| `refresh` | `() => Promise<void>` | Manually trigger a token refresh |
+| `lastRefresh` | `Date \| null` | Timestamp of the last successful refresh |
 
 ```tsx
 'use client';
 
 import { useTokenRefresh } from '@chemmangat/msal-next';
 
-export default function SessionWarning() {
-  const { expiresIn, isExpiringSoon } = useTokenRefresh();
+export default function SessionBanner() {
+  const { expiresIn, isExpiringSoon, refresh, lastRefresh } = useTokenRefresh({
+    enabled: true,
+    refreshBeforeExpiry: 300,       // warn/refresh 5 min before expiry
+    scopes: ['User.Read'],
+    onRefresh: (expiresIn) => console.log(`Refreshed — expires in ${expiresIn}s`),
+    onError: (error) => console.error('Refresh failed', error),
+  });
 
   if (isExpiringSoon) {
     return (
-      <div className="warning">
-        ⚠️ Your session will expire in {Math.floor(expiresIn / 60)} minutes
+      <div className="session-warning">
+        Session expires in {Math.floor((expiresIn ?? 0) / 60)} minutes.{' '}
+        <button onClick={refresh}>Stay signed in</button>
+        {lastRefresh && <span> Last refreshed: {lastRefresh.toLocaleTimeString()}</span>}
       </div>
     );
   }
@@ -612,35 +318,217 @@ export default function SessionWarning() {
 }
 ```
 
-### Multi-Tenant Applications
+#### useMultiAccount()
 
-For apps that support any Azure AD tenant:
+Manages multiple simultaneously signed-in Microsoft accounts. Use this when your app needs to support users who work across multiple tenants or have both personal and work accounts. Accepts an optional `defaultScopes` argument used when adding a new account.
 
 ```tsx
-<MSALProvider
-  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
-  authorityType="common"  // No tenantId needed
->
-  {children}
-</MSALProvider>
+useMultiAccount(defaultScopes?: string[]): UseMultiAccountReturn
+```
+
+Return values (`UseMultiAccountReturn`):
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `accounts` | `AccountInfo[]` | All accounts currently in the MSAL cache |
+| `activeAccount` | `AccountInfo \| null` | The currently active account |
+| `hasMultipleAccounts` | `boolean` | `true` when more than one account is cached |
+| `accountCount` | `number` | Total number of cached accounts |
+| `inProgress` | `boolean` | `true` while an MSAL interaction is running |
+| `switchAccount` | `(account: AccountInfo) => void` | Set a different account as active |
+| `addAccount` | `(scopes?: string[]) => Promise<void>` | Sign in with an additional account |
+| `removeAccount` | `(account: AccountInfo) => Promise<void>` | Remove an account from the cache |
+| `signOutAccount` | `(account: AccountInfo) => Promise<void>` | Sign out a specific account |
+| `signOutAll` | `() => Promise<void>` | Sign out all accounts |
+| `getAccountByUsername` | `(username: string) => AccountInfo \| undefined` | Look up an account by username |
+| `getAccountById` | `(homeAccountId: string) => AccountInfo \| undefined` | Look up an account by home account ID |
+| `isActiveAccount` | `(account: AccountInfo) => boolean` | Check whether a given account is active |
+
+```tsx
+'use client';
+
+import { useMultiAccount } from '@chemmangat/msal-next';
+
+export default function AccountManager() {
+  const {
+    accounts,
+    activeAccount,
+    hasMultipleAccounts,
+    accountCount,
+    inProgress,
+    switchAccount,
+    addAccount,
+    signOutAccount,
+    signOutAll,
+    isActiveAccount,
+  } = useMultiAccount(['User.Read']);
+
+  return (
+    <div>
+      <p>Signed in as: {activeAccount?.name} ({activeAccount?.username})</p>
+      <p>{accountCount} account{accountCount !== 1 ? 's' : ''} cached</p>
+
+      {hasMultipleAccounts && (
+        <ul>
+          {accounts.map((account) => (
+            <li key={account.homeAccountId}>
+              {account.name}
+              {isActiveAccount(account) && ' (active)'}
+              <button onClick={() => switchAccount(account)} disabled={isActiveAccount(account)}>
+                Switch
+              </button>
+              <button onClick={() => signOutAccount(account)}>Sign out</button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <button onClick={() => addAccount()} disabled={inProgress}>
+        Add another account
+      </button>
+      <button onClick={() => signOutAll()} disabled={inProgress}>
+        Sign out all
+      </button>
+    </div>
+  );
+}
 ```
 
-### Custom Scopes
+---
+
+### Higher-Order Components
 
-Request additional Microsoft Graph permissions:
+#### withAuth
 
 ```tsx
-<MSALProvider
-  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
-  scopes={['User.Read', 'Mail.Read', 'Calendars.Read', 'Files.Read']}
+const ProtectedPage = withAuth(MyPage, {
+  loadingComponent: <Spinner />,
+  scopes: ['User.Read'],
+});
+```
+
+#### withPageAuth
+
+Wraps a page component with authentication and optional role-based access control. Returns a new component that checks auth before rendering. Takes a `PageAuthConfig` as the second argument and an optional `AuthProtectionConfig` as the third for global defaults.
+
+```tsx
+withPageAuth<P>(
+  Component: ComponentType<P>,
+  authConfig: PageAuthConfig,
+  globalConfig?: AuthProtectionConfig
+): ComponentType<P>
+```
+
+`PageAuthConfig` options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `required` | `boolean` | `false` | Whether authentication is required |
+| `roles` | `string[]` | — | User must have at least one of these roles (from `idTokenClaims.roles`) |
+| `redirectTo` | `string` | `'/login'` | Where to redirect unauthenticated users |
+| `loading` | `ReactNode` | — | Component shown while auth state is resolving |
+| `unauthorized` | `ReactNode` | — | Component shown instead of redirecting when access is denied |
+| `validate` | `(account: any) => boolean \| Promise<boolean>` | — | Custom access check; return `true` to allow, `false` to deny |
+
+`AuthProtectionConfig` options (global defaults, third argument):
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultRedirectTo` | `string` | `'/login'` | Fallback redirect for unauthenticated users |
+| `defaultLoading` | `ReactNode` | — | Fallback loading component |
+| `defaultUnauthorized` | `ReactNode` | — | Fallback unauthorized component |
+| `debug` | `boolean` | `false` | Log auth decisions to the console |
+
+```tsx
+// app/dashboard/page.tsx
+'use client';
+
+import { withPageAuth } from '@chemmangat/msal-next';
+
+function Dashboard() {
+  return <div>Dashboard — only admins and editors can see this</div>;
+}
+
+export default withPageAuth(
+  Dashboard,
+  {
+    required: true,
+    roles: ['Admin', 'Editor'],
+    redirectTo: '/login',
+    loading: <div>Checking access...</div>,
+    unauthorized: <div>You do not have permission to view this page.</div>,
+  },
+  {
+    debug: process.env.NODE_ENV === 'development',
+  }
+);
+```
+
+Custom `validate` — restrict by email domain:
+
+```tsx
+export default withPageAuth(Dashboard, {
+  required: true,
+  validate: (account) => account.username.endsWith('@company.com'),
+  unauthorized: <div>Only company accounts are allowed.</div>,
+});
+```
+
+#### ProtectedPage
+
+The underlying component that `withPageAuth` uses internally. Use it directly when you need to protect arbitrary JSX rather than a whole page component — for example inside a layout or a slot.
+
+```tsx
+<ProtectedPage
+  config={PageAuthConfig}
+  defaultRedirectTo="/login"
+  defaultLoading={<Spinner />}
+  defaultUnauthorized={<div>Access denied</div>}
+  debug={false}
 >
   {children}
-</MSALProvider>
+</ProtectedPage>
 ```
 
-### Server-Side Session
+Props (`ProtectedPageProps`):
 
-Access authentication state in Server Components:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Content to render when access is granted |
+| `config` | `PageAuthConfig` | required | Per-page auth rules (same shape as `withPageAuth` second arg) |
+| `defaultRedirectTo` | `string` | `'/login'` | Redirect path when unauthenticated |
+| `defaultLoading` | `ReactNode` | — | Loading component while auth resolves |
+| `defaultUnauthorized` | `ReactNode` | — | Component shown when access is denied |
+| `debug` | `boolean` | `false` | Log auth decisions to the console |
+
+```tsx
+// app/settings/layout.tsx
+'use client';
+
+import { ProtectedPage } from '@chemmangat/msal-next';
+
+export default function SettingsLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <ProtectedPage
+      config={{
+        required: true,
+        roles: ['Admin'],
+        redirectTo: '/login',
+      }}
+      defaultLoading={<div>Loading...</div>}
+      defaultUnauthorized={<div>Admins only.</div>}
+    >
+      {children}
+    </ProtectedPage>
+  );
+}
+```
+
+---
+
+### Server Utilities
+
+#### getServerSession
 
 ```tsx
 // app/profile/page.tsx (Server Component)
@@ -649,33 +537,48 @@ import { redirect } from 'next/navigation';
 
 export default async function ProfilePage() {
   const session = await getServerSession();
+  if (!session.isAuthenticated) redirect('/login');
+  return <div>Welcome, {session.username}</div>;
+}
+```
 
-  if (!session.isAuthenticated) {
-    redirect('/login');
-  }
+---
 
-  return (
-    <div>
-      <h1>Profile</h1>
-      <p>Welcome, {session.username}</p>
-    </div>
-  );
-}
+### Middleware
+
+#### createAuthMiddleware
+
+Creates a Next.js Edge middleware function that enforces authentication at the routing level — before any page or API route renders. Use this to protect entire route groups without adding `AuthGuard` or `withPageAuth` to every page.
+
+The middleware reads a session cookie (`msal.account` by default) to determine auth state. Because MSAL runs in the browser, the cookie must be set client-side after login (e.g. via `setServerSessionCookie` from `@chemmangat/msal-next/server`). You can also supply a custom `isAuthenticated` function to integrate your own session store.
+
+```tsx
+createAuthMiddleware(config?: AuthMiddlewareConfig): (request: NextRequest) => Promise<NextResponse>
 ```
 
-### Middleware Protection
+`AuthMiddlewareConfig` options:
 
-Protect routes at the edge:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `protectedRoutes` | `string[]` | — | Paths that require authentication. Unauthenticated requests redirect to `loginPath` |
+| `publicOnlyRoutes` | `string[]` | — | Paths only accessible when NOT authenticated (e.g. `/login`). Authenticated users are redirected to `redirectAfterLogin` |
+| `loginPath` | `string` | `'/login'` | Where to redirect unauthenticated users |
+| `redirectAfterLogin` | `string` | `'/'` | Where to redirect authenticated users away from `publicOnlyRoutes` |
+| `sessionCookie` | `string` | `'msal.account'` | Cookie name used to detect an active session |
+| `isAuthenticated` | `(request: NextRequest) => boolean \| Promise<boolean>` | — | Custom auth check; overrides the default cookie check |
+| `debug` | `boolean` | `false` | Log routing decisions to the console |
 
 ```tsx
 // middleware.ts
 import { createAuthMiddleware } from '@chemmangat/msal-next';
 
 export const middleware = createAuthMiddleware({
-  protectedRoutes: ['/dashboard', '/profile', '/api/protected'],
-  publicOnlyRoutes: ['/login'],
+  protectedRoutes: ['/dashboard', '/profile', '/settings', '/api/protected'],
+  publicOnlyRoutes: ['/login', '/signup'],
   loginPath: '/login',
-  debug: true,
+  redirectAfterLogin: '/dashboard',
+  sessionCookie: 'msal.account',
+  debug: process.env.NODE_ENV === 'development',
 });
 
 export const config = {
@@ -683,174 +586,140 @@ export const config = {
 };
 ```
 
-### Error Handling
-
-Use enhanced error handling for better debugging:
+Custom `isAuthenticated` — use your own session store:
 
 ```tsx
-'use client';
-
-import { useMsalAuth, wrapMsalError } from '@chemmangat/msal-next';
+// middleware.ts
+import { createAuthMiddleware } from '@chemmangat/msal-next';
+import { verifySession } from './lib/session';
 
-export default function LoginPage() {
-  const { loginRedirect } = useMsalAuth();
-
-  const handleLogin = async () => {
-    try {
-      await loginRedirect();
-    } catch (error) {
-      const msalError = wrapMsalError(error);
-      
-      // Check if user cancelled (not a real error)
-      if (msalError.isUserCancellation()) {
-        return;
-      }
-      
-      // Display actionable error message
-      console.error(msalError.toConsoleString());
-    }
-  };
+export const middleware = createAuthMiddleware({
+  protectedRoutes: ['/dashboard'],
+  loginPath: '/login',
+  isAuthenticated: async (request) => {
+    const token = request.cookies.get('session-token')?.value;
+    if (!token) return false;
+    return verifySession(token);
+  },
+});
 
-  return <button onClick={handleLogin}>Sign In</button>;
-}
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
 ```
 
-### Custom Profile Fields
+---
+
+## Common Patterns
 
-Extend UserProfile with organization-specific fields:
+### Protect a page with AuthGuard
 
 ```tsx
 'use client';
 
-import { useUserProfile, UserProfile } from '@chemmangat/msal-next';
+import { AuthGuard, useUserProfile } from '@chemmangat/msal-next';
 
-interface MyCompanyProfile extends UserProfile {
-  customField: string;
+export default function DashboardPage() {
+  return (
+    <AuthGuard>
+      <DashboardContent />
+    </AuthGuard>
+  );
 }
 
-export default function ProfilePage() {
-  const { profile } = useUserProfile<MyCompanyProfile>();
-
+function DashboardContent() {
+  const { profile, loading } = useUserProfile();
+  if (loading) return <div>Loading...</div>;
   return (
     <div>
-      <p>Department: {profile?.department}</p>
-      <p>Custom Field: {profile?.customField}</p>
+      <p>{profile?.displayName}</p>
+      <p>{profile?.mail}</p>
+      <p>{profile?.department}</p>
     </div>
   );
 }
 ```
 
----
-
-## 🔧 Configuration Reference
-
-### MSALProvider Props
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `clientId` | `string` | ✅ Yes | - | Azure AD Application (client) ID |
-| `tenantId` | `string` | No | - | Azure AD Directory (tenant) ID (for single-tenant) |
-| `authorityType` | `'common' \| 'organizations' \| 'consumers' \| 'tenant'` | No | `'common'` | Authority type |
-| `redirectUri` | `string` | No | `window.location.origin` | Redirect URI after authentication |
-| `scopes` | `string[]` | No | `['User.Read']` | Default scopes |
-| `cacheLocation` | `'sessionStorage' \| 'localStorage' \| 'memoryStorage'` | No | `'sessionStorage'` | Token cache location |
-| `enableLogging` | `boolean` | No | `false` | Enable debug logging |
-
-### Authority Types
+### Acquire a token for API calls
 
-- **`common`** - Multi-tenant (any Azure AD tenant or Microsoft account)
-- **`organizations`** - Any organizational Azure AD tenant
-- **`consumers`** - Microsoft personal accounts only
-- **`tenant`** - Single-tenant (requires `tenantId`)
-
----
-
-## 📖 Additional Resources
-
-### Documentation
-- [SECURITY.md](./SECURITY.md) - **Security policy and best practices** ⭐
-- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Common issues and solutions
-- [CHANGELOG.md](./CHANGELOG.md) - Version history
-- [MIGRATION_GUIDE_v3.md](./MIGRATION_GUIDE_v3.md) - Migrating from v2.x
-- [EXAMPLES_v4.0.2.md](./EXAMPLES_v4.0.2.md) - Code examples
-
-### Security
-- 🔒 [Security Policy](./SECURITY.md) - Complete security documentation
-- 🛡️ [Best Practices](./SECURITY.md#-best-practices) - Security guidelines
-- ⚠️ [Common Mistakes](./SECURITY.md#-common-security-mistakes) - What to avoid
-- ✅ [Security Checklist](./SECURITY.md#-security-checklist) - Pre-deployment checklist
-
-### Links
-- 📦 [npm Package](https://www.npmjs.com/package/@chemmangat/msal-next)
-- 🚀 [Live Demo](https://github.com/Chemmangat/msal-next-demo) - Sample implementation
-- 🐛 [Report Issues](https://github.com/chemmangat/msal-next/issues)
-- 💬 [Discussions](https://github.com/chemmangat/msal-next/discussions)
-- ⭐ [GitHub Repository](https://github.com/chemmangat/msal-next)
-
-### Microsoft Resources
-- [Azure AD Documentation](https://learn.microsoft.com/en-us/azure/active-directory/)
-- [MSAL.js Documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/msal-overview)
-- [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview)
-
----
+```tsx
+'use client';
 
-## ❓ FAQ
+import { useMsalAuth } from '@chemmangat/msal-next';
 
-**Q: Do I need to create an Azure AD app registration?**  
-A: Yes, you need an app registration in Azure Portal to get the client ID and tenant ID.
+export default function DataComponent() {
+  const { acquireToken, isAuthenticated } = useMsalAuth();
 
-**Q: Can I use this with Next.js Pages Router?**  
-A: This package is designed for App Router. For Pages Router, use v2.x or consider migrating to App Router.
+  const fetchData = async () => {
+    if (!isAuthenticated) return;
+    const token = await acquireToken(['User.Read']);
+    const res = await fetch('https://graph.microsoft.com/v1.0/me', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    return res.json();
+  };
+}
+```
 
-**Q: Is this free to use?**  
-A: Yes, the package is MIT licensed and free. Azure AD has a free tier for up to 50,000 users.
+### Error handling
 
-**Q: Can I use this for multi-tenant SaaS apps?**  
-A: Yes! Set `authorityType="common"` and omit `tenantId`.
+```tsx
+import { useMsalAuth, wrapMsalError } from '@chemmangat/msal-next';
 
-**Q: How do I get additional user information?**  
-A: Use `useUserProfile()` hook which provides 30+ fields from Microsoft Graph.
+const { loginRedirect } = useMsalAuth();
 
-**Q: Can I customize the sign-in button?**  
-A: Yes, `MicrosoftSignInButton` accepts `variant`, `size`, `className`, and `style` props.
+const handleLogin = async () => {
+  try {
+    await loginRedirect();
+  } catch (error) {
+    const msalError = wrapMsalError(error);
+    if (msalError.isUserCancellation()) return;
+    console.error(msalError.toConsoleString());
+  }
+};
+```
 
-**Q: Does this work with Azure AD B2C?**  
-A: This package is designed for Azure AD. For B2C, you may need additional configuration.
+### Automatic token refresh
 
-**Q: How do I protect API routes?**  
-A: Use `getServerSession()` in API routes or `createAuthMiddleware()` for edge protection.
+```tsx
+<MSALProvider
+  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
+  autoRefreshToken={true}
+  refreshBeforeExpiry={300}
+>
+  {children}
+</MSALProvider>
+```
 
 ---
 
-## 🤝 Contributing
-
-Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+## Troubleshooting
 
----
-
-## 📄 License
+- **"createContext only works in Client Components"** — use `MSALProvider` (not `MsalAuthProvider`) in layout.tsx
+- **"AADSTS50011: Redirect URI mismatch"** — add your URL to Azure Portal → Authentication → Redirect URIs
+- **"No active account"** — user must sign in before calling `acquireToken()`
+- **Environment variables undefined** — restart the dev server after creating `.env.local`
 
-MIT © [Chemmangat](https://github.com/chemmangat)
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for more.
 
 ---
 
-## 🙏 Acknowledgments
+## Additional Resources
 
-Built with:
-- [@azure/msal-browser](https://github.com/AzureAD/microsoft-authentication-library-for-js)
-- [@azure/msal-react](https://github.com/AzureAD/microsoft-authentication-library-for-js)
-- [Next.js](https://nextjs.org/)
+- [SECURITY.md](./SECURITY.md) — security policy and best practices
+- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — common issues
+- [CHANGELOG.md](./CHANGELOG.md) — version history
+- [MIGRATION_GUIDE_v3.md](./MIGRATION_GUIDE_v3.md) — migrating from v2.x
+- [npm package](https://www.npmjs.com/package/@chemmangat/msal-next)
+- [GitHub](https://github.com/chemmangat/msal-next)
+- [Report issues](https://github.com/chemmangat/msal-next/issues)
 
 ---
 
-## 📊 Stats
+## Contributing
 
-- 📦 2,200+ weekly downloads
-- ⭐ Used in production by developers worldwide
-- 🔒 Security-focused with regular updates
-- 📚 Comprehensive documentation
-- 🎯 TypeScript-first with complete type safety
+See [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
----
+## License
 
-**Need help?** Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) or [open an issue](https://github.com/chemmangat/msal-next/issues)!
+MIT © [Chemmangat](https://github.com/chemmangat)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemmangat/msal-next",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "Production-ready Microsoft/Azure AD authentication for Next.js App Router. Zero-config setup, TypeScript-first, multi-account support, auto token refresh. The easiest way to add Microsoft login to your Next.js app.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",