{"_id":"@conemlabs/msal-auth-library","name":"@conemlabs/msal-auth-library","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@conemlabs/msal-auth-library","version":"1.0.0","description":"Production-ready MSAL authentication library for React and Angular applications","type":"module","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.esm.js","require":"./dist/index.js","types":"./dist/index.d.ts"},"./angular":{"import":"./dist/angular/index.js","types":"./dist/angular/index.d.ts"},"./core":{"import":"./dist/core/index.js","types":"./dist/core/index.d.ts"}},"scripts":{"build":"rollup -c","dev":"rollup -c -w","clean":"rimraf dist","prebuild":"npm run clean","lint":"eslint src --ext .ts,.tsx","lint:fix":"eslint src --ext .ts,.tsx --fix","prepublishOnly":"npm run build"},"keywords":["msal","authentication","react","angular","microsoft","azure-ad","oauth","typescript"],"author":{"name":"Conem Labs"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/conemlabs/msal-auth-library.git"},"bugs":{"url":"https://github.com/conemlabs/msal-auth-library/issues"},"homepage":"https://github.com/conemlabs/msal-auth-library#readme","peerDependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0","react-dom":"^16.8.0 || ^17.0.0 || ^18.0.0","@angular/core":">=12.0.0","@angular/common":">=12.0.0","@angular/router":">=12.0.0","rxjs":">=6.0.0"},"peerDependenciesMeta":{"@angular/core":{"optional":true},"@angular/common":{"optional":true},"@angular/router":{"optional":true},"rxjs":{"optional":true},"react":{"optional":true},"react-dom":{"optional":true}},"dependencies":{"@azure/msal-browser":"^3.7.0"},"devDependencies":{"@angular/common":"^17.0.0","@angular/core":"^17.0.0","@angular/platform-browser":"^17.0.0","@angular/router":"^17.0.0","@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-node-resolve":"^15.2.3","@rollup/plugin-typescript":"^11.1.5","@types/react":"^18.2.45","@types/react-dom":"^18.2.18","@typescript-eslint/eslint-plugin":"^6.14.0","@typescript-eslint/parser":"^6.14.0","eslint":"^8.55.0","eslint-plugin-react":"^7.33.2","eslint-plugin-react-hooks":"^4.6.0","react":"^18.2.0","react-dom":"^18.2.0","rimraf":"^5.0.5","rollup":"^4.9.0","rollup-plugin-peer-deps-external":"^2.2.4","rxjs":"^7.8.1","tslib":"^2.6.2","typescript":"^5.3.3","zone.js":"^0.14.2"},"_id":"@conemlabs/msal-auth-library@1.0.0","gitHead":"9800996a05898ac2cc9d49f450d0d8946efdca6e","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-M8IS2BIZ5cVTI/pVV7Y3OyNrWZtbgp8VCQt4a5DBneWaNRxJ5Vsf4L/WZN6J7NHdCEIhH1ed6Cfub22zzutyWQ==","shasum":"63296fd01f7f9fe46b8ece40f203e1ade4b3dda0","tarball":"https://registry.npmjs.org/@conemlabs/msal-auth-library/-/msal-auth-library-1.0.0.tgz","fileCount":33,"unpackedSize":217202,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDmxOIk2isX5BjD/h9htOPZl4CicUgNjJ362XXIqNeNcQIgThhTTbd9wKZC8auOhSv5eKZlgaVsAVd1FesSs/iPjls="}]},"_npmUser":{"name":"mihirjoshi2103","email":"mihirjoshi2103@gmail.com"},"directories":{},"maintainers":[{"name":"mihirjoshi2103","email":"mihirjoshi2103@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/msal-auth-library_1.0.0_1765398920595_0.8289527504368459"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-10T20:35:20.522Z","1.0.0":"2025-12-10T20:35:20.766Z","modified":"2025-12-10T20:35:21.048Z"},"maintainers":[{"name":"mihirjoshi2103","email":"mihirjoshi2103@gmail.com"}],"description":"Production-ready MSAL authentication library for React and Angular applications","homepage":"https://github.com/conemlabs/msal-auth-library#readme","keywords":["msal","authentication","react","angular","microsoft","azure-ad","oauth","typescript"],"repository":{"type":"git","url":"git+https://github.com/conemlabs/msal-auth-library.git"},"author":{"name":"Conem Labs"},"bugs":{"url":"https://github.com/conemlabs/msal-auth-library/issues"},"license":"MIT","readme":"# MSAL Auth Library\n\nProduction-ready authentication library for **React** and **Angular** applications using Microsoft Authentication Library (MSAL). Simplifies Azure AD authentication with automatic token refresh, route protection, and customizable UI.\n\n[![npm version](https://img.shields.io/npm/v/@conemlabs/msal-auth-library.svg)](https://www.npmjs.com/package/@conemlabs/msal-auth-library)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## ✨ Features\n\n- ✅ **Automatic Token Refresh** - Users stay logged in without re-authentication\n- ✅ **React & Angular Support** - Framework-specific implementations\n- ✅ **Custom UI Support** - Complete control over authentication UI\n- ✅ **Route Protection** - Guards for authenticated routes\n- ✅ **HTTP Interceptor** - Auto-inject bearer tokens (Angular)\n- ✅ **TypeScript** - Full type safety\n- ✅ **Popup & Redirect Flows** - Choose what works best\n- ✅ **Error Recovery** - Graceful handling of auth failures\n\n## 📦 Installation\n\n```bash\nnpm install @conemlabs/msal-auth-library\n```\n\n### Peer Dependencies\n\n**React:**\n```bash\nnpm install react react-dom\n```\n\n**Angular:**\n```bash\nnpm install @angular/core @angular/common @angular/router @angular/common/http rxjs\n```\n\n## 🚀 Quick Start\n\n### React\n\n```tsx\nimport { AuthenticationWrapper } from '@conemlabs/msal-auth-library';\n\nconst config = {\n  clientId: 'YOUR_CLIENT_ID',\n  tenantId: 'YOUR_TENANT_ID',\n  redirectUri: window.location.origin,\n  scopes: ['api://YOUR_CLIENT_ID/access_as_user'],\n  flowType: 'popup',\n};\n\nfunction App() {\n  return (\n    <AuthenticationWrapper config={config}>\n      <YourApp />\n    </AuthenticationWrapper>\n  );\n}\n```\n\n### Angular\n\n```typescript\nimport { MsalAuthModule } from '@conemlabs/msal-auth-library/angular';\n\n@NgModule({\n  imports: [\n    MsalAuthModule.forRoot({\n      clientId: 'YOUR_CLIENT_ID',\n      tenantId: 'YOUR_TENANT_ID',\n      redirectUri: window.location.origin,\n      scopes: ['api://YOUR_CLIENT_ID/access_as_user'],\n      flowType: 'popup',\n    })\n  ]\n})\nexport class AppModule { }\n```\n\n[See QUICKSTART.md for detailed examples →](QUICKSTART.md)\n\n## 📖 Usage Examples\n\n### React with Custom UI\n\n```tsx\nimport { AuthenticationWrapper, WrapperComponentProps } from '@conemlabs/msal-auth-library';\n\nconst CustomWrapper: React.FC<WrapperComponentProps> = ({\n  isInitializing,\n  isAuthenticated,\n  needsLogin,\n  authError,\n  onLogin,\n  onLogout,\n  children,\n}) => {\n  if (isInitializing) return <LoadingSpinner />;\n  if (needsLogin) return <CustomLoginPage onLogin={onLogin} error={authError} />;\n  return (\n    <>\n      <Header onLogout={onLogout} />\n      {children}\n      <Footer />\n    </>\n  );\n};\n\nfunction App() {\n  return (\n    <AuthenticationWrapper\n      config={config}\n      wrapperComponent={CustomWrapper}\n    >\n      <YourApp />\n    </AuthenticationWrapper>\n  );\n}\n```\n\n### React Hook\n\n```tsx\nimport { useAuthentication } from '@conemlabs/msal-auth-library';\n\nfunction MyComponent() {\n  const { authState, actions } = useAuthentication(config);\n\n  if (authState.isInitializing) return <div>Loading...</div>;\n  if (!authState.isAuthenticated) {\n    return <button onClick={actions.handleLogin}>Sign In</button>;\n  }\n\n  return (\n    <div>\n      <p>Welcome! Token: {authState.jwtToken}</p>\n      <button onClick={actions.handleLogout}>Sign Out</button>\n    </div>\n  );\n}\n```\n\n### Angular with Route Guard\n\n```typescript\nimport { MsalAuthGuard } from '@conemlabs/msal-auth-library/angular';\n\nconst routes: Routes = [\n  {\n    path: 'dashboard',\n    component: DashboardComponent,\n    canActivate: [MsalAuthGuard], // Protected route\n  }\n];\n```\n\n### Angular HTTP Calls (Auto Token Injection)\n\n```typescript\nimport { HttpClient } from '@angular/common/http';\n\n@Component({...})\nexport class DataComponent {\n  constructor(private http: HttpClient) {}\n\n  loadData() {\n    // Bearer token automatically added!\n    this.http.get('https://api.example.com/data')\n      .subscribe(data => console.log(data));\n  }\n}\n```\n\n### Getting Access Token\n\n**React:**\n```tsx\nimport { authService } from '@conemlabs/msal-auth-library';\n\nconst token = await authService.getAccessToken();\n```\n\n**Angular:**\n```typescript\nimport { MsalAuthService } from '@conemlabs/msal-auth-library/angular';\n\nconstructor(private authService: MsalAuthService) {}\n\nasync callAPI() {\n  const token = await this.authService.getAccessTokenAsync();\n  // Use token...\n}\n```\n\n## ⚙️ Configuration\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `clientId` | string | ✅ | - | Azure AD application/client ID |\n| `tenantId` | string | ✅ | - | Azure AD tenant ID |\n| `redirectUri` | string | ✅ | - | Redirect URI after authentication |\n| `scopes` | string[] | ✅ | - | OAuth scopes to request |\n| `flowType` | `'popup'` \\| `'redirect'` | ❌ | `'popup'` | Authentication flow type |\n| `cacheLocation` | `'sessionStorage'` \\| `'localStorage'` | ❌ | `'sessionStorage'` | Token cache location |\n| `enableLogging` | boolean | ❌ | `false` | Enable debug logging |\n| `prompt` | string | ❌ | `'select_account'` | Login prompt behavior |\n| `tokenRenewalOffsetSeconds` | number | ❌ | `300` | Token refresh offset (5 min) |\n\n## 🔄 Automatic Token Refresh\n\nTokens are automatically refreshed **every 30 minutes** in the background. Users stay logged in without interruption unless:\n\n- They haven't used the app for an extended period (Microsoft session expires)\n- They explicitly sign out\n- All sessions are invalidated by an administrator\n\n**How it works:**\n1. Token is cached with 55-minute expiry (5 minutes before actual expiry)\n2. Background timer refreshes token every 30 minutes\n3. Silent refresh happens without user interaction\n4. User never sees login screen unless necessary\n\n## 🎨 Custom UI Components\n\n### React\n\n```tsx\n<AuthenticationWrapper\n  config={config}\n  loadingComponent={<CustomLoader />}\n  loginComponent={<CustomLoginPage />}\n  errorComponent={(error, retry) => <CustomError error={error} onRetry={retry} />}\n>\n  <YourApp />\n</AuthenticationWrapper>\n```\n\nOr use a **custom wrapper** for complete control:\n\n```tsx\n<AuthenticationWrapper\n  config={config}\n  wrapperComponent={YourCustomWrapper}\n>\n  <YourApp />\n</AuthenticationWrapper>\n```\n\n[See examples/custom-wrapper.tsx for full example →](examples/custom-wrapper.tsx)\n\n## 📚 API Reference\n\n### React\n\n| Component / Hook | Description |\n|-----------------|-------------|\n| `AuthenticationWrapper` | Main wrapper component |\n| `useAuthentication(config)` | Hook for auth state and actions |\n| `authService` | Core service singleton |\n\n### Angular\n\n| Service / Guard | Description |\n|----------------|-------------|\n| `MsalAuthService` | Injectable authentication service |\n| `MsalAuthGuard` | Route guard for protected routes |\n| `MsalAuthInterceptor` | HTTP interceptor for token injection |\n| `MsalAuthModule` | Main module to import |\n\n### Core Service Methods\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `initialize(config)` | Initialize MSAL | `Promise<void>` |\n| `loginInteractive()` | Perform login | `Promise<AuthenticationResult>` |\n| `logout()` | Log out user | `Promise<void>` |\n| `getAccessToken()` | Get access token with auto-refresh | `Promise<string>` |\n| `acquireTokenSilent()` | Silent token acquisition | `Promise<TokenResult>` |\n| `isLoggedIn()` | Check if user is logged in | `boolean` |\n| `forceRefreshToken()` | Force token refresh | `Promise<string>` |\n| `clearAuthenticationState()` | Clear auth state (error recovery) | `Promise<void>` |\n\n## 🛡️ Security Best Practices\n\n- ✅ Tokens are cached in `sessionStorage` by default (cleared on tab close)\n- ✅ Automatic token refresh prevents token expiry\n- ✅ Silent refresh with no user interruption\n- ✅ Graceful error handling and recovery\n- ✅ Support for Azure AD multi-factor authentication\n\n## 🏗️ Project Structure\n\n```\n@conemlabs/msal-auth-library/\n├── core/              # Platform-agnostic core (MSAL wrapper)\n│   ├── auth-service.ts\n│   └── types.ts\n├── react/             # React-specific components and hooks\n│   ├── authentication-wrapper.tsx\n│   ├── use-authentication.ts\n│   └── types.ts\n└── angular/           # Angular services, guards, interceptors\n    ├── msal-auth.service.ts\n    ├── msal-auth.guard.ts\n    ├── msal-auth.interceptor.ts\n    └── msal-auth.module.ts\n```\n\n## 🧪 Testing Locally\n\n```bash\n# Build the library\nnpm run build\n\n# Link globally\nnpm link\n\n# In your test project\nnpm link @conemlabs/msal-auth-library\n```\n\n## 📝 Examples\n\n- [Basic React App](examples/basic-react-app.tsx)\n- [Custom Wrapper Component](examples/custom-wrapper.tsx)\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on GitHub.\n\n## 📄 License\n\nMIT © Conem Labs\n\n## 🔗 Links\n\n- [Azure AD Documentation](https://docs.microsoft.com/en-us/azure/active-directory/)\n- [MSAL.js Documentation](https://github.com/AzureAD/microsoft-authentication-library-for-js)\n\n## 💬 Support\n\n- 📧 Email: support@conemlabs.com\n- 🐛 Issues: [GitHub Issues](https://github.com/conemlabs/msal-auth-library/issues)\n- 📖 Docs: [Documentation](https://github.com/conemlabs/msal-auth-library#readme)\n\n## 📦 Publishing\n\nThe repository uses GitHub Actions to automatically publish to npm on pushes to `main`. The workflow:\n- Builds the package with `npm run build`\n- Bumps the patch version (e.g., `v1.0.1`)\n- Creates a git tag and pushes it\n- Publishes to npm using the `NPM_TOKEN` secret\n\n**Setup:** Add an `NPM_TOKEN` secret in your GitHub repository settings with a scoped npm automation token.\n\n---\n\n**Made with ❤️ by Conem Labs**\n","readmeFilename":"README.md","_rev":"1-de8158f521325c9c40ea909e46a8ff30"}