tenneo-auth-gateway-plugin 1.0.7

package/README.md

@@ -0,0 +1,422 @@
+# tenneo-auth-plugin
+
+Production-ready React authentication plugin with OAuth 2.0 PKCE support for enterprise applications.
+
+[![npm version](https://img.shields.io/npm/v/tenneo-auth-plugin)](https://www.npmjs.com/package/tenneo-auth-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/tenneo-auth-plugin)](https://www.npmjs.com/package/tenneo-auth-plugin)
+[![license](https://img.shields.io/npm/l/tenneo-auth-plugin)](https://www.npmjs.com/package/tenneo-auth-plugin)
+
+## Overview
+
+tenneo-auth-plugin is a comprehensive authentication solution designed for modern React applications. It implements the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange), providing secure authentication without exposing client secrets in browser-based applications.
+
+The plugin features a robust multi-tenant architecture that automatically resolves tenant configuration based on tenant codes. This makes it ideal for SaaS platforms and enterprise applications where multiple tenants share the same codebase but require isolated authentication contexts.
+
+Built with TypeScript and following clean architecture principles, the plugin handles the complete token lifecycle including automatic refresh, secure storage, and session management. The React Context API integration provides a seamless developer experience with hooks-based access to authentication state and methods.
+
+## Installation
+
+```bash
+npm install tenneo-auth-plugin
+```
+
+### Requirements
+
+- React 18 or higher
+- React DOM 18 or higher
+- React Router (recommended for callback handling)
+
+## Quick Start
+
+### 1. Wrap your application with AuthProvider
+
+```tsx
+import { AuthProvider } from 'tenneo-auth-plugin';
+
+function App() {
+  return (
+    <AuthProvider tenantCode="your-tenant-code">
+      <YourApplication />
+    </AuthProvider>
+  );
+}
+```
+
+### 2. Access authentication state with useAuth
+
+```tsx
+import { useAuth } from 'tenneo-auth-plugin';
+
+function Dashboard() {
+  const { isAuthenticated, isLoading, accessToken, logout } = useAuth();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!isAuthenticated) {
+    return <div>Please log in to continue.</div>;
+  }
+
+  return (
+    <div>
+      <h1>Welcome to Dashboard</h1>
+      <button onClick={logout}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### 3. Handle OAuth callback
+
+```tsx
+import { AuthCallback } from 'tenneo-auth-plugin';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <AuthProvider tenantCode="your-tenant-code">
+      <BrowserRouter>
+        <Routes>
+          <Route 
+            path="/callback" 
+            element={
+              <AuthCallback 
+                successPath="/dashboard" 
+                loginPath="/login" 
+              />
+            } 
+          />
+          <Route path="/dashboard" element={<Dashboard />} />
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```
+
+### 4. Protect routes
+
+```tsx
+import { ProtectedRoute } from 'tenneo-auth-plugin';
+
+function App() {
+  return (
+    <AuthProvider tenantCode="your-tenant-code">
+      <BrowserRouter>
+        <Routes>
+          <Route path="/callback" element={<AuthCallback />} />
+          <Route 
+            path="/dashboard" 
+            element={
+              <ProtectedRoute fallback={<div>Authenticating...</div>}>
+                <Dashboard />
+              </ProtectedRoute>
+            } 
+          />
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```
+
+## Features
+
+- OAuth 2.0 PKCE flow for secure browser-based authentication
+- Automatic token refresh before expiration
+- Multi-tenant support with automatic tenant resolution
+- Pluggable storage adapters (session, cookie, memory)
+- Authentication event system for observability
+- Strict TypeScript definitions throughout
+- Host-driven configuration (props / `setConfig()`)
+- Clean layered architecture
+- Tree-shakeable ESM and CJS builds
+- React 18+ compatibility
+
+## AuthProvider Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `config` | `SDKConfig` | No | - | Pass all configuration as a single object (alternative to individual props) |
+| `tenantCode` | `string` | No | - | Tenant code for configuration resolution |
+| `apiBaseUrl` | `string` | Yes | - | Tenant resolution service base URL |
+| `authServerUrl` | `string` | Yes | - | Authorization server base URL (OIDC authorize) |
+| `callbackUrl` | `string` | Yes | - | Full callback/redirect URL |
+| `appId` | `string` | No | `''` | Application identifier for storage namespacing |
+| `autoInit` | `boolean` | No | `true` | Automatically initialize authentication on mount |
+| `storageAdapter` | `StorageAdapter` | No | `null` | Custom storage adapter instance |
+
+## Hooks API
+
+### useAuth()
+
+Primary hook for accessing authentication state and methods.
+
+```tsx
+import { useAuth } from 'tenneo-auth-plugin';
+
+function Component() {
+  const {
+    isAuthenticated,  // boolean - Current authentication status
+    accessToken,      // string | null - Current access token
+    isLoading,        // boolean - Loading state during auth operations
+    error,            // string | null - Error message if any
+    login,            // () => Promise<void> - Trigger login flow
+    logout,           // () => Promise<void> - Sign out and clear session
+    refreshToken,     // () => Promise<string> - Manually refresh token
+    getAccessToken,   // () => Promise<string> - Get valid token (auto-refresh)
+  } = useAuth();
+}
+```
+
+### useAuthInit()
+
+Hook for manual authentication initialization.
+
+```tsx
+import { useAuthInit } from 'tenneo-auth-plugin';
+
+function Component() {
+  const {
+    isLoading,  // boolean - Initialization in progress
+    error,      // string | null - Initialization error
+    init,       // () => Promise<void> - Trigger initialization
+  } = useAuthInit();
+
+  useEffect(() => {
+    init();
+  }, [init]);
+}
+```
+
+## Components
+
+### AuthCallback
+
+Handles OAuth authorization callback and token exchange.
+
+```tsx
+import { AuthCallback } from 'tenneo-auth-plugin';
+
+<AuthCallback 
+  loginPath="/login"       // Redirect on error (default: '/login')
+  successPath="/dashboard" // Redirect on success (default: '/dashboard')
+  homePath="/"             // Fallback path (default: '/')
+/>
+```
+
+### ProtectedRoute
+
+Wrapper component that ensures authentication before rendering children.
+
+```tsx
+import { ProtectedRoute } from 'tenneo-auth-plugin';
+
+<ProtectedRoute 
+  fallback={<LoadingSpinner />}  // Shown while checking auth
+  autoLogin={true}               // Auto-redirect to login (default: true)
+>
+  <ProtectedContent />
+</ProtectedRoute>
+```
+
+## Core API
+
+### bootstrap()
+
+Initializes the authentication flow. Called automatically by AuthProvider when `autoInit` is true.
+
+```tsx
+import { bootstrap } from 'tenneo-auth-plugin';
+
+await bootstrap();
+```
+
+### getAccessToken()
+
+Retrieves a valid access token, automatically refreshing if expired.
+
+```tsx
+import { getAccessToken } from 'tenneo-auth-plugin';
+
+const token = await getAccessToken();
+```
+
+### logout()
+
+Signs out the user and clears all authentication data.
+
+```tsx
+import { logout } from 'tenneo-auth-plugin';
+
+await logout();
+```
+
+### createAuthEngine()
+
+Creates an authentication engine instance for advanced use cases.
+
+```tsx
+import { createAuthEngine } from 'tenneo-auth-plugin';
+
+const engine = createAuthEngine(runtime);
+
+// Subscribe to state changes
+const unsubscribe = engine.subscribe((state) => {
+  console.log('Status:', state.status);
+  console.log('Token:', state.accessToken);
+});
+
+// Initialize
+await engine.init();
+
+// Operations
+await engine.login();
+await engine.logout();
+const token = await engine.getAccessToken();
+```
+
+## Configuration
+
+### Host app configuration (required)
+
+This SDK does **not** read `.env` or `window.__AUTH_CONFIG__`. Provide configuration from your host app:
+
+```tsx
+import { AuthProvider } from 'tenneo-auth-plugin';
+
+<AuthProvider
+  tenantCode="your-tenant-code"
+  apiBaseUrl="https://tenant-service.example.com"
+  authServerUrl="https://auth.example.com"
+  callbackUrl="https://app.example.com/callback"
+  appId="myapp"
+>
+  <App />
+</AuthProvider>
+```
+
+### Programmatic Configuration
+
+```tsx
+import { setConfig, Config } from 'tenneo-auth-plugin';
+
+// Override configuration (host-driven)
+setConfig({
+  tenantCode: 'your-tenant-code',
+  apiBaseUrl: 'https://tenant-service.example.com',
+  authServerUrl: 'https://auth.example.com',
+  callbackUrl: 'https://app.example.com/callback',
+});
+
+// Access resolved configuration
+const authServerUrl = Config.getAuthServerUrl();
+const allConfig = Config.getAll();
+```
+
+
+## Security
+
+### PKCE Protection
+
+The plugin implements PKCE (Proof Key for Code Exchange) to prevent authorization code interception attacks. A cryptographically random code verifier is generated for each authentication request and never transmitted to the authorization server.
+
+### CSRF Protection
+
+OAuth state parameter validation prevents cross-site request forgery attacks. Each authentication request includes a unique state value that is verified during the callback.
+
+### Token Isolation
+
+Authentication tokens are stored with tenant-specific namespacing, ensuring complete isolation between different tenants in multi-tenant deployments.
+
+### HTTPS Enforcement
+
+Production environments automatically enforce HTTPS for all authentication-related requests and redirects.
+
+### Session Security
+
+Tokens are stored in sessionStorage by default, ensuring they are cleared when the browser tab is closed. For enhanced security requirements, custom storage adapters can be configured.
+
+## Storage Adapters
+
+```tsx
+import { 
+  createSecureSessionStorageAdapter,
+  createCookieStorageAdapter,
+  createMemoryStorageAdapter,
+} from 'tenneo-auth-plugin';
+
+// Session storage (default, cleared on tab close)
+const sessionAdapter = createSecureSessionStorageAdapter({ 
+  tenantId: 'tenant-123', 
+  appId: 'my-app' 
+});
+
+// Cookie storage (persistent)
+const cookieAdapter = createCookieStorageAdapter({ 
+  tenantId: 'tenant-123', 
+  appId: 'my-app' 
+});
+
+// Memory storage (testing)
+const memoryAdapter = createMemoryStorageAdapter({ 
+  tenantId: 'tenant-123', 
+  appId: 'my-app' 
+});
+
+// Use custom adapter
+<AuthProvider tenantCode="abc" storageAdapter={sessionAdapter}>
+  <App />
+</AuthProvider>
+```
+
+## Events
+
+Subscribe to authentication events for logging, analytics, or custom behavior.
+
+```tsx
+import { subscribeAuthEvent, AuthEventNames } from 'tenneo-auth-plugin';
+
+// Subscribe to login events
+const unsubscribe = subscribeAuthEvent(AuthEventNames.LOGIN, (payload) => {
+  console.log('User authenticated');
+});
+
+// Available events
+AuthEventNames.LOGIN   // User successfully authenticated
+AuthEventNames.LOGOUT  // User signed out
+AuthEventNames.REFRESH // Token refreshed
+AuthEventNames.ERROR   // Authentication error occurred
+```
+
+## TypeScript Support
+
+All types are exported for use in TypeScript applications.
+
+```tsx
+import type {
+  TenantConfig,
+  TokenResponse,
+  AuthState,
+  AuthContextValue,
+  AuthTokens,
+  StorageAdapter,
+  AuthEngine,
+  AuthEngineState,
+  SDKConfig,
+} from 'tenneo-auth-plugin';
+```
+
+## Versioning
+
+This package follows Semantic Versioning (SemVer):
+
+- **Major versions** contain breaking changes
+- **Minor versions** add backward-compatible features
+- **Patch versions** include backward-compatible bug fixes
+- **Beta versions** are pre-release versions for testing
+
+## License
+
+MIT