tenneo-auth-plugin 0.1.0

package/README.md

@@ -0,0 +1,596 @@
+# @tenneo/auth-plugin
+
+Production-ready ReactJS authentication plugin using TypeScript with full OAuth 2.0 PKCE lifecycle support.
+
+> **Note:** This is an internal scoped package with restricted access.
+
+## Features
+
+- Full OAuth 2.0 PKCE flow implementation
+- Multi-tenant support via tenant code resolution
+- Automatic token refresh
+- Session-based storage with namespacing
+- React hooks and Context API integration
+- TypeScript with strict typing
+- Configurable storage adapters (session, cookie, memory)
+- Auth engine architecture for advanced use cases
+- Protected route component
+- Callback handling component
+
+## Installation
+
+### Installation from npm registry (stable)
+
+```bash
+npm install @tenneo/auth-plugin
+```
+
+### Installation from npm registry (beta)
+
+```bash
+npm install @tenneo/auth-plugin@beta
+```
+
+### Installation from hosted .tgz file (without pack)
+
+If the plugin is hosted on a server as a `.tgz` file, install directly from the URL:
+
+```bash
+npm install https://your-server.com/path/tenneo-auth-plugin-0.1.0-beta.1.tgz
+```
+
+Or add it to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@tenneo/auth-plugin": "https://your-server.com/path/tenneo-auth-plugin-0.1.0-beta.1.tgz"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm install
+```
+
+### Installation with npm pack
+
+Use this method to create a distributable package from the source:
+
+**Step 1: Build the plugin**
+
+```bash
+cd tenneo-auth-plugin
+npm install
+npm run build
+```
+
+**Step 2: Create the package**
+
+```bash
+npm pack
+```
+
+This creates a file like `tenneo-auth-plugin-0.1.0-beta.1.tgz` in the current directory.
+
+**Step 3: Install in your application**
+
+Copy the `.tgz` file to your application directory and install:
+
+```bash
+npm install ./tenneo-auth-plugin-0.1.0-beta.1.tgz
+```
+
+Or specify the full path:
+
+```bash
+npm install /path/to/tenneo-auth-plugin-0.1.0-beta.1.tgz
+```
+
+### Installation with local source (development)
+
+Use this method during development to link the plugin directly without packing:
+
+**Method 1: npm link (recommended for development)**
+
+```bash
+# In the plugin directory
+cd tenneo-auth-plugin
+npm install
+npm run build
+npm link
+
+# In your application directory
+cd your-application
+npm link @tenneo/auth-plugin
+```
+
+To unlink when done:
+
+```bash
+# In your application directory
+npm unlink @tenneo/auth-plugin
+
+# In the plugin directory
+npm unlink
+```
+
+**Method 2: File path in package.json**
+
+Add the local path to your application's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@tenneo/auth-plugin": "file:../tenneo-auth-plugin"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm install
+```
+
+**Method 3: Direct file install**
+
+```bash
+npm install ../tenneo-auth-plugin
+```
+
+> **Note:** For local development methods, ensure you run `npm run build` in the plugin directory whenever you make changes to the plugin source code.
+
+## Quick Start
+
+### 1. Wrap your app with AuthProvider
+
+**Basic Usage:**
+
+```tsx
+import { AuthProvider } from '@tenneo/auth-plugin';
+
+function App() {
+  return (
+    <AuthProvider tenantCode="your-tenant-code">
+      <YourApp />
+    </AuthProvider>
+  );
+}
+```
+
+**With App ID (for storage namespacing):**
+
+```tsx
+import { AuthProvider } from '@tenneo/auth-plugin';
+
+function App() {
+  return (
+    <AuthProvider 
+      tenantCode="your-tenant-code"
+      appId="my-app"
+    >
+      <YourApp />
+    </AuthProvider>
+  );
+}
+```
+
+### 2. Use authentication in your components
+
+```tsx
+import { useAuth } from '@tenneo/auth-plugin';
+
+function MyComponent() {
+  const { isAuthenticated, accessToken, isLoading, logout } = useAuth();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!isAuthenticated) {
+    return <div>Not authenticated</div>;
+  }
+
+  return (
+    <div>
+      <p>Authenticated!</p>
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+### 3. Setup callback route
+
+Add the `AuthCallback` component to handle OAuth redirects:
+
+```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" />} />
+          <Route path="/dashboard" element={<Dashboard />} />
+          {/* ... other routes */}
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```
+
+### 4. Protect routes (optional)
+
+```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>Loading...</div>}>
+                <Dashboard />
+              </ProtectedRoute>
+            } 
+          />
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```
+
+## AuthProvider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tenantCode` | `string` | - | Tenant code used to resolve tenant configuration via API |
+| `appId` | `string` | `''` | App identifier for storage namespacing |
+| `autoInit` | `boolean` | `true` | Auto-initialize authentication on mount |
+| `storageAdapter` | `StorageAdapter` | `null` | Custom storage adapter (defaults to secure session storage) |
+
+### Configuration Priority
+
+1. **Props** - Values passed to `AuthProvider`
+2. **Window config** - `window.__AUTH_CONFIG__` or `window.__APP_CONFIG__`
+3. **Environment variables** - `VITE_*` prefixed variables
+4. **Defaults** - Built-in fallback values
+
+## API Reference
+
+### Hooks
+
+#### `useAuth()`
+
+Returns authentication state and methods:
+
+```tsx
+const {
+  isAuthenticated: boolean;      // Whether user is authenticated
+  accessToken: string | null;    // Current access token
+  isLoading: boolean;            // Loading state
+  error: string | null;          // Error message if any
+  login: () => Promise<void>;    // Trigger login flow
+  logout: () => Promise<void>;   // Logout and clear session
+  refreshToken: () => Promise<string>;  // Refresh access token
+  getAccessToken: () => Promise<string>; // Get valid token (auto-refresh)
+} = useAuth();
+```
+
+#### `useAuthInit()`
+
+Manual initialization hook for advanced use cases:
+
+```tsx
+const { isLoading, error, init } = useAuthInit();
+
+// Manually trigger initialization
+await init();
+```
+
+### Components
+
+#### `AuthCallback`
+
+Handles OAuth callback and token exchange:
+
+```tsx
+<AuthCallback 
+  loginPath="/login"      // Redirect path on error (default: '/login')
+  successPath="/dashboard" // Redirect path on success (default: '/dashboard')
+  homePath="/"            // Home path fallback (default: '/')
+/>
+```
+
+#### `ProtectedRoute`
+
+Wraps components that require authentication:
+
+```tsx
+<ProtectedRoute 
+  fallback={<Loading />}  // Component to show while checking auth
+  autoLogin={true}        // Auto-trigger login if not authenticated (default: true)
+>
+  <ProtectedContent />
+</ProtectedRoute>
+```
+
+### Core Functions
+
+#### `bootstrap()`
+
+Initializes authentication flow (called automatically by AuthProvider):
+
+```tsx
+import { bootstrap } from '@tenneo/auth-plugin';
+await bootstrap();
+```
+
+#### `getAccessToken()`
+
+Gets current access token (auto-refreshes if expired):
+
+```tsx
+import { getAccessToken } from '@tenneo/auth-plugin';
+const token = await getAccessToken();
+```
+
+#### `logout()`
+
+Logs out user and clears session:
+
+```tsx
+import { logout } from '@tenneo/auth-plugin';
+await logout();
+```
+
+### Configuration
+
+#### `Config` Object
+
+Access resolved configuration values:
+
+```tsx
+import { Config } from '@tenneo/auth-plugin';
+
+Config.getAuthServerUrl();   // OAuth server URL
+Config.getClientId();        // OAuth client ID
+Config.getTenantId();        // Resolved tenant ID
+Config.getClientCode();      // Tenant code
+Config.getRedirectUri();     // OAuth redirect URI
+Config.getBasePath();        // App base path
+Config.getAll();             // All config as object
+```
+
+#### `setConfig()`
+
+Override runtime configuration:
+
+```tsx
+import { setConfig } from '@tenneo/auth-plugin';
+
+setConfig({
+  clientId: 'custom-client-id',
+  tenantId: 'custom-tenant-id',
+  basePath: '/my-app',
+  redirectUri: 'https://myapp.com/callback',
+});
+```
+
+### Storage Adapters
+
+Create custom storage adapters or use built-in ones:
+
+```tsx
+import { 
+  createSecureSessionStorageAdapter,
+  createCookieStorageAdapter,
+  createMemoryStorageAdapter,
+  setStorageContext,
+} from '@tenneo/auth-plugin';
+
+// Session storage (default)
+const sessionAdapter = createSecureSessionStorageAdapter({ 
+  tenantId: 'tenant-123', 
+  appId: 'my-app' 
+});
+
+// Cookie storage
+const cookieAdapter = createCookieStorageAdapter({ 
+  tenantId: 'tenant-123', 
+  appId: 'my-app' 
+});
+
+// Memory storage (for testing)
+const memoryAdapter = createMemoryStorageAdapter({ 
+  tenantId: 'tenant-123', 
+  appId: 'my-app' 
+});
+
+// Use custom adapter
+<AuthProvider tenantCode="abc" storageAdapter={cookieAdapter}>
+  <App />
+</AuthProvider>
+```
+
+### Auth Engine (Advanced)
+
+For advanced use cases, create and manage auth engine directly:
+
+```tsx
+import { createAuthEngine, type AuthEngine } from '@tenneo/auth-plugin';
+
+const engine = createAuthEngine(runtime);
+
+// Subscribe to state changes
+const unsubscribe = engine.subscribe((state) => {
+  console.log('Auth state:', state.status);
+});
+
+// Initialize
+await engine.init();
+
+// Get current state
+const state = engine.getState();
+
+// Manual operations
+await engine.login();
+await engine.logout();
+await engine.refresh();
+const token = await engine.getAccessToken();
+```
+
+### Events
+
+Subscribe to authentication events:
+
+```tsx
+import { 
+  subscribeAuthEvent, 
+  emitAuthEvent,
+  AuthEventNames 
+} from '@tenneo/auth-plugin';
+
+// Subscribe to events
+const unsubscribe = subscribeAuthEvent('auth:login', (payload) => {
+  console.log('User logged in');
+});
+
+// Available events
+AuthEventNames.LOGIN      // 'auth:login'
+AuthEventNames.LOGOUT     // 'auth:logout'
+AuthEventNames.REFRESH    // 'auth:refresh'
+AuthEventNames.ERROR      // 'auth:error'
+```
+
+## Environment Variables
+
+Configure the plugin via environment variables (Vite apps use `VITE_` prefix):
+
+```env
+# Auth Server URL - Your OAuth authorization server
+VITE_AUTH_SERVER_URL=https://auth.example.com
+
+# API base URLs
+VITE_API_TENANT_RESOLUTION_BASE_URL=https://api.example.com/api/v1
+VITE_API_AUTH_BASE_URL=https://auth.example.com
+
+# Default values (optional)
+VITE_CLIENT_ID=your-client-id
+VITE_TENANT_ID=your-tenant-id
+VITE_CLIENTCODE=your-tenant-code
+```
+
+See `.env.example` for a complete template.
+
+## Window Configuration
+
+For runtime configuration without rebuilding:
+
+```html
+<script>
+  window.__AUTH_CONFIG__ = {
+    clientId: 'runtime-client-id',
+    tenantId: 'runtime-tenant-id',
+    basePath: '/my-app',
+  };
+</script>
+```
+
+## Architecture
+
+```
+@tenneo/auth-plugin/
+└── src/
+    ├── index.ts                 # Main exports
+    ├── application/             # Application layer (bootstrap, flows, engine)
+    │   ├── bootstrap.ts         # Auth initialization
+    │   ├── engine/              # Auth state machine
+    │   ├── flows/               # OAuth flow implementations
+    │   └── events/              # Event system
+    ├── infrastructure/          # Infrastructure adapters
+    │   ├── storage/             # Storage adapters
+    │   ├── runtime/             # Runtime context
+    │   ├── tenant/              # Tenant resolution
+    │   └── watchers/            # Storage/cookie watchers
+    ├── strategies/              # Auth strategies
+    │   └── oauth2-pkce/         # OAuth 2.0 PKCE implementation
+    ├── context/                 # React Context
+    ├── components/              # React components
+    ├── hooks/                   # React hooks
+    ├── config/                  # Configuration
+    ├── domain/                  # Domain types
+    └── utils/                   # Utilities
+```
+
+## Storage Keys
+
+Authentication data is stored with namespaced keys (`auth_{tenantId}_{appId}_*`):
+
+- `*_access_token` - Current access token
+- `*_refresh_token` - Refresh token
+- `*_expires_at` - Token expiration timestamp
+- `*_id_token` - ID token (if provided)
+- `*_tenant_id` - Resolved tenant ID
+- `*_tenant_key` - Tenant code/key
+- `*_code_verifier` - PKCE code verifier (temporary)
+- `*_state` - OAuth state parameter (temporary)
+
+## TypeScript Types
+
+All types are exported for use in your application:
+
+```tsx
+import type {
+  TenantConfig,
+  TokenResponse,
+  AuthState,
+  AuthContextValue,
+  EnvConfig,
+  AuthTokens,
+  StorageAdapter,
+  AuthEngine,
+  AuthEngineState,
+  SDKConfig,
+  RuntimeConfigOverrides,
+} from '@tenneo/auth-plugin';
+```
+
+## Security
+
+- PKCE (Proof Key for Code Exchange) prevents authorization code interception
+- Tokens stored in sessionStorage (cleared on tab close)
+- Automatic HTTPS enforcement in production
+- State parameter validation prevents CSRF attacks
+- Secure cookie options for cookie-based storage
+
+npm run clean          # Remove dist/
+npm run build          # Build with tsup
+npm run dev            # Watch mode
+npm run type-check     # TypeScript check
+npm run release:beta   # Publish beta version (restricted)
+npm run release:minor  # Publish minor version (restricted)
+npm run release:major  # Publish major version (restricted)
+
+Publishing
+npm login
+npm run release:beta   # First beta release
+
+Consumers install via:
+npm install @tenneo/auth-plugin@beta
+
+## License
+
+MIT