tenneo-auth-plugin 0.1.0 → 0.1.2

package/README.md

@@ -1,214 +1,76 @@
-# @tenneo/auth-plugin
+# tenneo-auth-plugin
 
-Production-ready ReactJS authentication plugin using TypeScript with full OAuth 2.0 PKCE lifecycle support.
+Production-ready React authentication plugin with OAuth 2.0 PKCE support for enterprise applications.
 
-> **Note:** This is an internal scoped package with restricted access.
+[![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)
 
-## 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
-```
+## Overview
 
-### Installation with npm pack
+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.
 
-Use this method to create a distributable package from the source:
+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.
 
-**Step 1: Build the plugin**
+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.
 
-```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:
+## Installation
 
 ```bash
-npm install
+npm install tenneo-auth-plugin
 ```
 
-**Method 3: Direct file install**
-
-```bash
-npm install ../tenneo-auth-plugin
-```
+### Requirements
 
-> **Note:** For local development methods, ensure you run `npm run build` in the plugin directory whenever you make changes to the plugin source code.
+- React 18 or higher
+- React DOM 18 or higher
+- React Router (recommended for callback handling)
 
 ## Quick Start
 
-### 1. Wrap your app with AuthProvider
-
-**Basic Usage:**
+### 1. Wrap your application with AuthProvider
 
 ```tsx
-import { AuthProvider } from '@tenneo/auth-plugin';
+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 />
+      <YourApplication />
     </AuthProvider>
   );
 }
 ```
 
-### 2. Use authentication in your components
+### 2. Access authentication state with useAuth
 
 ```tsx
-import { useAuth } from '@tenneo/auth-plugin';
+import { useAuth } from 'tenneo-auth-plugin';
 
-function MyComponent() {
-  const { isAuthenticated, accessToken, isLoading, logout } = useAuth();
+function Dashboard() {
+  const { isAuthenticated, isLoading, accessToken, logout } = useAuth();
 
   if (isLoading) {
     return <div>Loading...</div>;
   }
 
   if (!isAuthenticated) {
-    return <div>Not authenticated</div>;
+    return <div>Please log in to continue.</div>;
   }
 
   return (
     <div>
-      <p>Authenticated!</p>
-      <button onClick={logout}>Logout</button>
+      <h1>Welcome to Dashboard</h1>
+      <button onClick={logout}>Sign Out</button>
     </div>
   );
 }
 ```
 
-### 3. Setup callback route
-
-Add the `AuthCallback` component to handle OAuth redirects:
+### 3. Handle OAuth callback
 
 ```tsx
-import { AuthCallback } from '@tenneo/auth-plugin';
+import { AuthCallback } from 'tenneo-auth-plugin';
 import { BrowserRouter, Routes, Route } from 'react-router-dom';
 
 function App() {
@@ -216,9 +78,16 @@ function App() {
     <AuthProvider tenantCode="your-tenant-code">
       <BrowserRouter>
         <Routes>
-          <Route path="/callback" element={<AuthCallback successPath="/dashboard" />} />
+          <Route 
+            path="/callback" 
+            element={
+              <AuthCallback 
+                successPath="/dashboard" 
+                loginPath="/login" 
+              />
+            } 
+          />
           <Route path="/dashboard" element={<Dashboard />} />
-          {/* ... other routes */}
         </Routes>
       </BrowserRouter>
     </AuthProvider>
@@ -226,10 +95,10 @@ function App() {
 }
 ```
 
-### 4. Protect routes (optional)
+### 4. Protect routes
 
 ```tsx
-import { ProtectedRoute } from '@tenneo/auth-plugin';
+import { ProtectedRoute } from 'tenneo-auth-plugin';
 
 function App() {
   return (
@@ -240,7 +109,7 @@ function App() {
           <Route 
             path="/dashboard" 
             element={
-              <ProtectedRoute fallback={<div>Loading...</div>}>
+              <ProtectedRoute fallback={<div>Authenticating...</div>}>
                 <Dashboard />
               </ProtectedRoute>
             } 
@@ -252,305 +121,298 @@ function App() {
 }
 ```
 
-## AuthProvider Props
+## Features
 
-| 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) |
+- 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
+- Runtime configuration override support
+- Window-based configuration injection
+- Clean layered architecture
+- Tree-shakeable ESM and CJS builds
+- React 18+ compatibility
 
-### 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
+## AuthProvider Props
 
-## API Reference
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `tenantCode` | `string` | No | - | Tenant code for configuration resolution |
+| `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
+## Hooks API
 
-#### `useAuth()`
+### useAuth()
 
-Returns authentication state and methods:
+Primary hook for accessing 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();
+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()`
+### useAuthInit()
 
-Manual initialization hook for advanced use cases:
+Hook for manual authentication initialization.
 
 ```tsx
-const { isLoading, error, init } = useAuthInit();
-
-// Manually trigger initialization
-await init();
+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
+## Components
 
-#### `AuthCallback`
+### AuthCallback
 
-Handles OAuth callback and token exchange:
+Handles OAuth authorization callback and token exchange.
 
 ```tsx
+import { AuthCallback } from 'tenneo-auth-plugin';
+
 <AuthCallback 
-  loginPath="/login"      // Redirect path on error (default: '/login')
-  successPath="/dashboard" // Redirect path on success (default: '/dashboard')
-  homePath="/"            // Home path fallback (default: '/')
+  loginPath="/login"       // Redirect on error (default: '/login')
+  successPath="/dashboard" // Redirect on success (default: '/dashboard')
+  homePath="/"             // Fallback path (default: '/')
 />
 ```
 
-#### `ProtectedRoute`
+### ProtectedRoute
 
-Wraps components that require authentication:
+Wrapper component that ensures authentication before rendering children.
 
 ```tsx
+import { ProtectedRoute } from 'tenneo-auth-plugin';
+
 <ProtectedRoute 
-  fallback={<Loading />}  // Component to show while checking auth
-  autoLogin={true}        // Auto-trigger login if not authenticated (default: true)
+  fallback={<LoadingSpinner />}  // Shown while checking auth
+  autoLogin={true}               // Auto-redirect to login (default: true)
 >
   <ProtectedContent />
 </ProtectedRoute>
 ```
 
-### Core Functions
+## Core API
 
-#### `bootstrap()`
+### bootstrap()
 
-Initializes authentication flow (called automatically by AuthProvider):
+Initializes the authentication flow. Called automatically by AuthProvider when `autoInit` is true.
 
 ```tsx
-import { bootstrap } from '@tenneo/auth-plugin';
+import { bootstrap } from 'tenneo-auth-plugin';
+
 await bootstrap();
 ```
 
-#### `getAccessToken()`
+### getAccessToken()
 
-Gets current access token (auto-refreshes if expired):
+Retrieves a valid access token, automatically refreshing if expired.
 
 ```tsx
-import { getAccessToken } from '@tenneo/auth-plugin';
+import { getAccessToken } from 'tenneo-auth-plugin';
+
 const token = await getAccessToken();
 ```
 
-#### `logout()`
+### logout()
 
-Logs out user and clears session:
+Signs out the user and clears all authentication data.
 
 ```tsx
-import { logout } from '@tenneo/auth-plugin';
+import { logout } from 'tenneo-auth-plugin';
+
 await logout();
 ```
 
-### Configuration
-
-#### `Config` Object
+### createAuthEngine()
 
-Access resolved configuration values:
+Creates an authentication engine instance for advanced use cases.
 
 ```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
+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
+
+### Environment Variables
+
+Configure the plugin using environment variables. For Vite applications, use the `VITE_` prefix.
+
+```env
+# OAuth Server URL
+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 Configuration
+VITE_CLIENT_ID=your-client-id
+VITE_TENANT_ID=your-tenant-id
+VITE_CLIENTCODE=your-tenant-code
+```
+
+### Window Runtime Configuration
+
+Inject configuration at runtime without rebuilding the application.
+
+```html
+<script>
+  window.__AUTH_CONFIG__ = {
+    clientId: 'runtime-client-id',
+    tenantId: 'runtime-tenant-id',
+    basePath: '/app',
+  };
+</script>
 ```
 
-#### `setConfig()`
+### Configuration Priority
 
-Override runtime configuration:
+Configuration is resolved in the following order (highest priority first):
+
+1. Props passed to AuthProvider
+2. Window configuration (`window.__AUTH_CONFIG__`)
+3. Environment variables
+4. Built-in defaults
+
+### Programmatic Configuration
 
 ```tsx
-import { setConfig } from '@tenneo/auth-plugin';
+import { setConfig, Config } from 'tenneo-auth-plugin';
 
+// Override configuration
 setConfig({
   clientId: 'custom-client-id',
   tenantId: 'custom-tenant-id',
   basePath: '/my-app',
-  redirectUri: 'https://myapp.com/callback',
 });
+
+// Access resolved configuration
+const authServerUrl = Config.getAuthServerUrl();
+const clientId = Config.getClientId();
+const allConfig = Config.getAll();
 ```
 
-### Storage Adapters
 
-Create custom storage adapters or use built-in ones:
+## 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,
-  setStorageContext,
-} from '@tenneo/auth-plugin';
+} from 'tenneo-auth-plugin';
 
-// Session storage (default)
+// Session storage (default, cleared on tab close)
 const sessionAdapter = createSecureSessionStorageAdapter({ 
   tenantId: 'tenant-123', 
   appId: 'my-app' 
 });
 
-// Cookie storage
+// Cookie storage (persistent)
 const cookieAdapter = createCookieStorageAdapter({ 
   tenantId: 'tenant-123', 
   appId: 'my-app' 
 });
 
-// Memory storage (for testing)
+// Memory storage (testing)
 const memoryAdapter = createMemoryStorageAdapter({ 
   tenantId: 'tenant-123', 
   appId: 'my-app' 
 });
 
 // Use custom adapter
-<AuthProvider tenantCode="abc" storageAdapter={cookieAdapter}>
+<AuthProvider tenantCode="abc" storageAdapter={sessionAdapter}>
   <App />
 </AuthProvider>
 ```
 
-### Auth Engine (Advanced)
+## Events
 
-For advanced use cases, create and manage auth engine directly:
+Subscribe to authentication events for logging, analytics, or custom behavior.
 
 ```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
+import { subscribeAuthEvent, AuthEventNames } from 'tenneo-auth-plugin';
 
-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');
+// Subscribe to login events
+const unsubscribe = subscribeAuthEvent(AuthEventNames.LOGIN, (payload) => {
+  console.log('User authenticated');
 });
 
 // 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
+AuthEventNames.LOGIN   // User successfully authenticated
+AuthEventNames.LOGOUT  // User signed out
+AuthEventNames.REFRESH // Token refreshed
+AuthEventNames.ERROR   // Authentication error occurred
 ```
 
-See `.env.example` for a complete template.
+## TypeScript Support
 
-## 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:
+All types are exported for use in TypeScript applications.
 
 ```tsx
 import type {
@@ -565,31 +427,17 @@ import type {
   AuthEngineState,
   SDKConfig,
   RuntimeConfigOverrides,
-} from '@tenneo/auth-plugin';
+} from 'tenneo-auth-plugin';
 ```
 
-## Security
+## Versioning
+
+This package follows Semantic Versioning (SemVer):
 
-- 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
+- **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenneo-auth-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Production-ready ReactJS authentication plugin with OAuth PKCE support",
   "main": "./dist/index.js",