@chemmangat/msal-next 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 All notable changes to this project will be documented in this file.
 
+## [5.1.0] - 2026-03-17
+
+### ✨ New Features
+
+#### 1. Multi-Tenant Support — `multiTenant` config
+
+Pass a `multiTenant` object to `MSALProvider` to control which tenants can access your app:
+
+```tsx
+<MSALProvider
+  clientId="..."
+  multiTenant={{
+    type: 'multi',           // 'single' | 'multi' | 'organizations' | 'consumers' | 'common'
+    allowList: ['contoso.com', 'fabrikam.com'],
+    blockList: ['competitor.com'],
+    requireType: 'Member',   // block B2B guests
+    requireMFA: true,
+  }}
+  onTenantDenied={(reason) => router.push(`/denied?reason=${reason}`)}
+>
+```
+
+- `type` maps to the MSAL authority (`single` → tenant, `multi`/`common` → common, etc.)
+- `allowList` / `blockList` accept tenant IDs or domain names
+- `requireType: 'Member'` blocks B2B guests; `'Guest'` allows only guests
+- `requireMFA` checks the `amr` claim for MFA evidence
+- Tenant validation runs automatically after redirect authentication
+
+#### 2. `useTenant()` Hook
+
+```tsx
+import { useTenant } from '@chemmangat/msal-next';
+
+const { tenantId, tenantDomain, isGuestUser, homeTenantId, resourceTenantId, claims } = useTenant();
+```
+
+Returns tenant context for the current user including B2B guest detection.
+
+#### 3. Per-Page Tenant Restrictions
+
+```tsx
+// app/admin/page.tsx
+export const auth = {
+  required: true,
+  tenant: {
+    allowList: ['contoso.com'],
+    requireMFA: true,
+  },
+};
+```
+
+#### 4. Middleware Tenant Validation
+
+```ts
+// middleware.ts
+export const middleware = createAuthMiddleware({
+  protectedRoutes: ['/dashboard'],
+  tenantConfig: { allowList: ['contoso.com'] },
+  tenantDeniedPath: '/unauthorized',
+});
+```
+
+#### 5. Cross-Tenant Token Acquisition
+
+```tsx
+const { acquireTokenForTenant } = useMsalAuth();
+const token = await acquireTokenForTenant('target-tenant-id', ['User.Read']);
+```
+
+#### 6. `useTenantConfig()` Hook
+
+Access the `multiTenant` config from anywhere in the component tree:
+
+```tsx
+import { useTenantConfig } from '@chemmangat/msal-next';
+const config = useTenantConfig();
+```
+
+### 🔧 Internal
+
+- `createMsalConfig` now maps `multiTenant.type` to the correct MSAL authority (takes precedence over legacy `authorityType`)
+- `validateTenantAccess` utility exported for advanced use cases
+- `TenantAuthConfig` type exported for per-page tenant config
+
+---
+
 ## [5.0.0] - 2026-03-16
 
 ### ⚠️ Breaking Changes

package/README.md

@@ -6,7 +6,7 @@ Microsoft/Azure AD authentication for Next.js App Router. Minimal setup, full Ty
 [![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.2.1**
+**Current version: 5.1.0**
 
 ---
 
@@ -16,6 +16,20 @@ Microsoft/Azure AD authentication for Next.js App Router. Minimal setup, full Ty
 npm install @chemmangat/msal-next @azure/msal-browser @azure/msal-react
 ```
 
+Or scaffold everything automatically with the CLI (Node.js 18+ required):
+
+```bash
+npx @chemmangat/msal-next-cli init
+```
+
+The `init` command interactively asks for your client ID, tenant ID, authority type, and cache location, then creates `.env.local`, updates `app/layout.tsx` with `MSALProvider`, and generates a starter `app/auth/page.tsx`.
+
+To migrate an existing project from popup-based auth to redirect:
+
+```bash
+npx @chemmangat/msal-next-cli migrate
+```
+
 ---
 
 ## Quick Start
@@ -179,6 +193,12 @@ Protects content and redirects unauthenticated users to login.
   onSwitch={(account) => {}}
   onAdd={() => {}}
   onRemove={(account) => {}}
+  // v5.0.0 — custom account row rendering
+  renderAccount={(account, isActive) => (
+    <div style={{ fontWeight: isActive ? 'bold' : 'normal' }}>
+      {account.name} ({account.username})
+    </div>
+  )}
 />
 ```
 
@@ -192,11 +212,71 @@ Protects content and redirects unauthenticated users to login.
   clickToSwitch
   orientation="vertical"  // 'vertical' | 'horizontal'
   onAccountClick={(account) => {}}
+  // v5.0.0 — custom account row rendering
+  renderAccount={(account, isActive) => (
+    <div style={{ color: isActive ? 'blue' : 'black' }}>
+      {account.name} — {account.username}
+    </div>
+  )}
 />
 ```
 
 ---
 
+## Multi-Tenant Support (v5.1.0)
+
+### Provider Configuration
+
+```tsx
+<MSALProvider
+  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
+  multiTenant={{
+    type: 'multi',
+    allowList: ['contoso.com', 'fabrikam.com'],
+    blockList: ['competitor.com'],
+    requireType: 'Member',
+    requireMFA: true,
+  }}
+  onTenantDenied={(reason) => router.push(`/denied?reason=${encodeURIComponent(reason)}`)}
+>
+```
+
+### `useTenant()` Hook
+
+```tsx
+import { useTenant } from '@chemmangat/msal-next';
+
+const { tenantId, tenantDomain, isGuestUser, homeTenantId, resourceTenantId, claims } = useTenant();
+```
+
+### Per-Page Tenant Restrictions
+
+```tsx
+export const auth = {
+  required: true,
+  tenant: { allowList: ['contoso.com'], requireMFA: true },
+};
+```
+
+### Middleware Tenant Validation
+
+```ts
+export const middleware = createAuthMiddleware({
+  protectedRoutes: ['/dashboard'],
+  tenantConfig: { allowList: ['contoso.com'] },
+  tenantDeniedPath: '/unauthorized',
+});
+```
+
+### Cross-Tenant Token Acquisition
+
+```tsx
+const { acquireTokenForTenant } = useMsalAuth();
+const token = await acquireTokenForTenant('target-tenant-id', ['User.Read']);
+```
+
+---
+
 ### Hooks
 
 #### useMsalAuth()
@@ -213,6 +293,7 @@ const {
   acquireTokenSilent,   // (scopes: string[]) => Promise<string>  — silent only
   acquireTokenRedirect, // (scopes: string[]) => Promise<void>
   clearSession,         // () => Promise<void>  — clears cache without Microsoft logout
+  acquireTokenForTenant,// (tenantId: string, scopes: string[]) => Promise<string>  — cross-tenant (v5.1.0)
 } = useMsalAuth();
 ```
 

package/dist/index.d.mts

@@ -292,13 +292,66 @@ interface MsalAuthConfig {
      * Only used when autoRefreshToken is enabled.
      *
      * @defaultValue 300 (5 minutes)
+     */
+    refreshBeforeExpiry?: number;
+    /**
+     * Multi-tenant configuration (v5.1.0)
+     *
+     * @remarks
+     * Controls which tenants are allowed to access the application and how
+     * cross-tenant token acquisition is handled.
      *
      * @example
      * ```tsx
-     * refreshBeforeExpiry={600} // Refresh 10 minutes before expiry
+     * <MSALProvider
+     *   clientId="..."
+     *   multiTenant={{
+     *     type: 'multi',
+     *     allowList: ['contoso.com', 'fabrikam.com'],
+     *     requireMFA: true,
+     *   }}
+     * >
      * ```
      */
-    refreshBeforeExpiry?: number;
+    multiTenant?: MultiTenantConfig;
+}
+/**
+ * Multi-tenant configuration for v5.1.0
+ */
+interface MultiTenantConfig {
+    /**
+     * Tenant mode
+     * - 'single'        — only your own tenant (maps to authorityType 'tenant')
+     * - 'multi'         — any Azure AD tenant (maps to authorityType 'common')
+     * - 'organizations' — any organisational tenant, no personal accounts
+     * - 'consumers'     — Microsoft personal accounts only
+     * - 'common'        — alias for 'multi'
+     *
+     * @defaultValue 'common'
+     */
+    type?: 'single' | 'multi' | 'organizations' | 'consumers' | 'common';
+    /**
+     * Tenant allow-list — only users from these tenant IDs or domains are permitted.
+     * Checked after authentication; users from other tenants are shown an error.
+     *
+     * @example ['contoso.com', '72f988bf-86f1-41af-91ab-2d7cd011db47']
+     */
+    allowList?: string[];
+    /**
+     * Tenant block-list — users from these tenant IDs or domains are denied.
+     * Takes precedence over allowList.
+     */
+    blockList?: string[];
+    /**
+     * Require a specific tenant type ('Member' | 'Guest').
+     * Useful to block B2B guests or to allow only guests.
+     */
+    requireType?: 'Member' | 'Guest';
+    /**
+     * Require MFA claim in the token (amr claim must contain 'mfa').
+     * @defaultValue false
+     */
+    requireMFA?: boolean;
 }
 /**
  * Props for MsalAuthProvider component
@@ -318,13 +371,38 @@ interface MsalAuthProviderProps extends MsalAuthConfig {
  * @returns The MSAL instance or null if not initialized
  */
 declare function getMsalInstance(): PublicClientApplication | null;
-declare function MsalAuthProvider({ children, loadingComponent, onInitialized, autoRefreshToken, refreshBeforeExpiry, ...config }: MsalAuthProviderProps): react_jsx_runtime.JSX.Element;
+declare function MsalAuthProvider({ children, loadingComponent, onInitialized, autoRefreshToken, refreshBeforeExpiry, onTenantDenied, ...config }: MsalAuthProviderProps & {
+    onTenantDenied?: (reason: string) => void;
+}): react_jsx_runtime.JSX.Element;
 
 /**
  * Zero-Config Protected Routes - Type Definitions
  * v4.0.0 Killer Feature
  */
 
+/**
+ * Per-page tenant access configuration (v5.1.0)
+ */
+interface TenantAuthConfig {
+    /**
+     * Only users from these tenant IDs or domains are permitted on this page.
+     * @example ['contoso.com', '72f988bf-86f1-41af-91ab-2d7cd011db47']
+     */
+    allowList?: string[];
+    /**
+     * Users from these tenant IDs or domains are denied on this page.
+     * Takes precedence over allowList.
+     */
+    blockList?: string[];
+    /**
+     * Require a specific account type ('Member' | 'Guest').
+     */
+    requireType?: 'Member' | 'Guest';
+    /**
+     * Require MFA claim in the token (amr must contain 'mfa').
+     */
+    requireMFA?: boolean;
+}
 /**
  * Page-level auth configuration
  * Export this from your page to enable protection
@@ -334,109 +412,81 @@ declare function MsalAuthProvider({ children, loadingComponent, onInitialized, a
  * // app/dashboard/page.tsx
  * export const auth = { required: true };
  *
- * export default function Dashboard() {
- *   return <div>Protected content</div>;
- * }
+ * // With tenant restriction (v5.1.0)
+ * export const auth = {
+ *   required: true,
+ *   tenant: { allowList: ['contoso.com'], requireMFA: true }
+ * };
  * ```
  */
 interface PageAuthConfig {
-    /**
-     * Whether authentication is required for this page
-     * @default false
-     */
+    /** Whether authentication is required for this page */
     required?: boolean;
     /**
      * Required roles for access (checks account.idTokenClaims.roles)
      * User must have at least one of these roles
-     *
-     * @example
-     * ```tsx
-     * export const auth = {
-     *   required: true,
-     *   roles: ['admin', 'editor']
-     * };
-     * ```
      */
     roles?: string[];
-    /**
-     * Custom redirect path when auth fails
-     * @default '/login'
-     */
+    /** Custom redirect path when auth fails */
     redirectTo?: string;
-    /**
-     * Custom loading component while checking auth
-     */
+    /** Custom loading component while checking auth */
     loading?: ReactNode;
-    /**
-     * Custom unauthorized component (shown instead of redirect)
-     */
+    /** Custom unauthorized component (shown instead of redirect) */
     unauthorized?: ReactNode;
     /**
-     * Custom validation function
-     * Return true to allow access, false to deny
-     *
-     * @example
-     * ```tsx
-     * export const auth = {
-     *   required: true,
-     *   validate: (account) => account.username.endsWith('@company.com')
-     * };
-     * ```
+     * Custom validation function.
+     * Return true to allow access, false to deny.
      */
     validate?: (account: any) => boolean | Promise<boolean>;
+    /**
+     * Per-page tenant access restrictions (v5.1.0).
+     * Checked after role validation.
+     */
+    tenant?: TenantAuthConfig;
 }
 /**
  * Global auth configuration for the provider
  */
 interface AuthProtectionConfig {
-    /**
-     * Default redirect path for unauthenticated users
-     * @default '/login'
-     */
+    /** Default redirect path for unauthenticated users */
     defaultRedirectTo?: string;
-    /**
-     * Default loading component
-     */
+    /** Default loading component */
     defaultLoading?: ReactNode;
-    /**
-     * Default unauthorized component
-     */
+    /** Default unauthorized component */
     defaultUnauthorized?: ReactNode;
-    /**
-     * Enable debug logging
-     * @default false
-     */
+    /** Enable debug logging */
     debug?: boolean;
 }
 
 interface MSALProviderProps extends MsalAuthProviderProps {
     /**
      * Zero-Config Protected Routes configuration (v4.0.0)
-     * @example
-     * ```tsx
-     * <MSALProvider
-     *   clientId="..."
-     *   protection={{
-     *     defaultRedirectTo: '/login',
-     *     defaultLoading: <Spinner />,
-     *     debug: true
-     *   }}
-     * >
-     * ```
      */
     protection?: AuthProtectionConfig;
+    /**
+     * Called when a user's tenant is denied access (v5.1.0)
+     */
+    onTenantDenied?: (reason: string) => void;
 }
+/**
+ * Access the multi-tenant configuration from anywhere in the tree (v5.1.0).
+ *
+ * @example
+ * ```tsx
+ * const tenantConfig = useTenantConfig();
+ * console.log(tenantConfig?.allowList);
+ * ```
+ */
+declare function useTenantConfig(): MultiTenantConfig | undefined;
 /**
  * Pre-configured MSALProvider component for Next.js App Router layouts.
  *
  * @remarks
- * This component is already marked as 'use client' internally, so you can import
- * and use it directly in your server-side layout.tsx without adding 'use client'
- * to your layout file.
+ * Already marked as 'use client' internally — safe to import in server layouts.
  *
  * @example
  * ```tsx
- * // app/layout.tsx (Server Component - no 'use client' needed!)
+ * // app/layout.tsx (Server Component)
  * import { MSALProvider } from '@chemmangat/msal-next'
  *
  * export default function RootLayout({ children }) {
@@ -446,6 +496,7 @@ interface MSALProviderProps extends MsalAuthProviderProps {
  *         <MSALProvider
  *           clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
  *           tenantId={process.env.NEXT_PUBLIC_AZURE_AD_TENANT_ID!}
+ *           multiTenant={{ type: 'multi', allowList: ['contoso.com'] }}
  *         >
  *           {children}
  *         </MSALProvider>
@@ -454,15 +505,8 @@ interface MSALProviderProps extends MsalAuthProviderProps {
  *   )
  * }
  * ```
- *
- * @security
- * - All authentication happens client-side (browser)
- * - Tokens are never sent to your Next.js server
- * - Uses Microsoft's official MSAL library
- * - Supports secure token storage (sessionStorage/localStorage)
- * - No server-side token handling required
  */
-declare function MSALProvider({ children, protection, ...props }: MSALProviderProps): react_jsx_runtime.JSX.Element;
+declare function MSALProvider({ children, protection, onTenantDenied, ...props }: MSALProviderProps): react_jsx_runtime.JSX.Element;
 
 interface MicrosoftSignInButtonProps {
     /**
@@ -921,9 +965,62 @@ interface UseMsalAuthReturn {
      * Clear MSAL session without triggering Microsoft logout
      */
     clearSession: () => Promise<void>;
+    /**
+     * Acquire an access token for a specific tenant (cross-tenant, v5.1.0).
+     * Uses acquireTokenSilent with an explicit authority for the target tenant.
+     */
+    acquireTokenForTenant: (tenantId: string, scopes: string[]) => Promise<string>;
 }
 declare function useMsalAuth(defaultScopes?: string[]): UseMsalAuthReturn;
 
+interface TenantInfo {
+    /** The tenant ID from the current account's token claims */
+    tenantId: string | null;
+    /** The tenant domain (e.g. contoso.onmicrosoft.com) derived from the UPN */
+    tenantDomain: string | null;
+    /**
+     * Whether the current user is a B2B guest in this tenant.
+     * True when the home tenant (iss claim) differs from the resource tenant (tid claim).
+     */
+    isGuestUser: boolean;
+    /** The user's home tenant ID (where their identity lives) */
+    homeTenantId: string | null;
+    /** The resource tenant ID (the tenant the token was issued for) */
+    resourceTenantId: string | null;
+    /** Raw idTokenClaims for advanced usage */
+    claims: Record<string, any> | null;
+}
+interface UseTenantReturn extends TenantInfo {
+    /** Whether the user is authenticated */
+    isAuthenticated: boolean;
+}
+/**
+ * Hook that exposes tenant context for the currently authenticated user.
+ *
+ * @remarks
+ * Detects B2B guest users by comparing the `iss` (issuer / home tenant) claim
+ * against the `tid` (resource tenant) claim. When they differ the user is a
+ * cross-tenant guest.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { useTenant } from '@chemmangat/msal-next';
+ *
+ * export default function TenantBadge() {
+ *   const { tenantDomain, isGuestUser, tenantId } = useTenant();
+ *
+ *   return (
+ *     <div>
+ *       <span>{tenantDomain}</span>
+ *       {isGuestUser && <span className="badge">Guest</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTenant(): UseTenantReturn;
+
 interface GraphApiOptions extends RequestInit {
     /**
      * Scopes required for the API call
@@ -1798,6 +1895,16 @@ interface AuthMiddlewareConfig {
      * Custom authentication check function
      */
     isAuthenticated?: (request: NextRequest) => boolean | Promise<boolean>;
+    /**
+     * Tenant access configuration (v5.1.0).
+     * Validated against the account stored in the session cookie.
+     */
+    tenantConfig?: MultiTenantConfig;
+    /**
+     * Path to redirect to when tenant access is denied (v5.1.0).
+     * @default '/unauthorized'
+     */
+    tenantDeniedPath?: string;
     /**
      * Enable debug logging
      * @default false
@@ -1845,4 +1952,4 @@ interface ServerSession {
     accessToken?: string;
 }
 
-export { AccountList, type AccountListProps, AccountSwitcher, type AccountSwitcherProps, AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, type AuthProtectionConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, MsalError, type PageAuthConfig, ProtectedPage, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type UseGraphApiReturn, type UseMsalAuthReturn, type UseMultiAccountReturn, type UseRolesReturn, type UseTokenRefreshOptions, type UseTokenRefreshReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type ValidationError, type ValidationResult, type ValidationWarning, type WithAuthOptions, createAuthMiddleware, createMissingEnvVarError, createMsalConfig, createRetryWrapper, createScopedLogger, displayValidationResults, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useMultiAccount, useRoles, useTokenRefresh, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };
+export { AccountList, type AccountListProps, AccountSwitcher, type AccountSwitcherProps, AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, type AuthProtectionConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, MsalError, type MultiTenantConfig, type PageAuthConfig, ProtectedPage, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type TenantAuthConfig, type TenantInfo, type UseGraphApiReturn, type UseMsalAuthReturn, type UseMultiAccountReturn, type UseRolesReturn, type UseTenantReturn, type UseTokenRefreshOptions, type UseTokenRefreshReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type ValidationError, type ValidationResult, type ValidationWarning, type WithAuthOptions, createAuthMiddleware, createMissingEnvVarError, createMsalConfig, createRetryWrapper, createScopedLogger, displayValidationResults, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useMultiAccount, useRoles, useTenant, useTenantConfig, useTokenRefresh, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };