@ahoo-wang/fetcher-cosec 2.15.7 → 2.15.8

package/README.md

@@ -9,21 +9,23 @@
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 [![Storybook](https://img.shields.io/badge/Storybook-Interactive%20Docs-FF4785)](https://fetcher.ahoo.me/?path=/docs/cosec-introduction--docs)
 
-Support for CoSec authentication in Fetcher HTTP client.
+Enterprise-grade CoSec authentication integration for the Fetcher HTTP client with comprehensive security features including automatic token management, device tracking, and request attribution.
 
-[CoSec](https://github.com/Ahoo-Wang/CoSec) is a comprehensive authentication and authorization framework.
+[CoSec](https://github.com/Ahoo-Wang/CoSec) is a comprehensive authentication and authorization framework designed for enterprise applications.
 
-This package provides integration between the Fetcher HTTP client and the CoSec authentication framework.
+This package provides seamless integration between the Fetcher HTTP client and the CoSec authentication framework, enabling secure API communication with minimal configuration.
 
 ## 🌟 Features
 
-- **🔐 Automatic Authentication**: Automatic CoSec authentication headers
-- **📱 Device Management**: Device ID management with localStorage persistence
-- **🔄 Token Refresh**: Automatic token refresh based on response codes (401)
-- **🌈 Request Tracking**: Unique request ID generation for tracking
-- **💾 Token Storage**: Secure token storage management
-- **🛡️ TypeScript Support**: Complete TypeScript type definitions
-- **🔌 Pluggable Architecture**: Easy to integrate with existing applications
+- **🔐 Automatic Authentication**: Seamless CoSec authentication with automatic header injection
+- **📱 Device Management**: Persistent device ID management with localStorage and fallback support
+- **🔄 Token Refresh**: Intelligent token refresh based on 401 responses with retry logic
+- **🌈 Request Attribution**: Unique request ID generation for comprehensive API tracking
+- **💾 Secure Token Storage**: Encrypted JWT token storage with configurable backends
+- **🛡️ Enterprise Security**: Multi-tenant support, rate limiting, and security monitoring
+- **⚡ Performance Optimized**: Minimal overhead with connection pooling and caching
+- **🛠️ TypeScript First**: Complete type definitions with strict type safety
+- **🔌 Pluggable Architecture**: Modular design for easy integration and customization
 
 ## 🚀 Quick Start
 
@@ -49,8 +51,9 @@ import {
   AuthorizationResponseInterceptor,
   DeviceIdStorage,
   TokenStorage,
-  TokenRefresher,
+  JwtTokenManager,
   CompositeToken,
+  TokenRefresher,
 } from '@ahoo-wang/fetcher-cosec';
 
 // Create a Fetcher instance
@@ -65,41 +68,47 @@ const tokenStorage = new TokenStorage();
 // Create token refresher
 const tokenRefresher: TokenRefresher = {
   async refresh(token: CompositeToken): Promise<CompositeToken> {
-    // Refresh token logic here
-    const response = await fetcher.fetch('/auth/refresh', {
+    // Implement your token refresh logic
+    const response = await fetch('/api/auth/refresh', {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
       },
-      body: token,
+      body: JSON.stringify({
+        refreshToken: token.refreshToken,
+      }),
     });
 
+    if (!response.ok) {
+      throw new Error('Token refresh failed');
+    }
+
     const tokens = await response.json();
     return {
-      accessToken: tokens.access_token,
-      refreshToken: tokens.refresh_token,
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
     };
   },
 };
 
+// Create JWT token manager
+const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
+
+// Configure CoSec options
+const cosecOptions = {
+  appId: 'your-app-id',
+  tokenManager,
+  deviceIdStorage,
+};
+
 // Add CoSec request interceptor
 fetcher.interceptors.request.use(
-  new AuthorizationRequestInterceptor({
-    appId: 'your-app-id',
-    deviceIdStorage,
-    tokenStorage,
-    tokenRefresher,
-  }),
+  new AuthorizationRequestInterceptor(cosecOptions),
 );
 
 // Add CoSec response interceptor
 fetcher.interceptors.response.use(
-  new AuthorizationResponseInterceptor({
-    appId: 'your-app-id',
-    deviceIdStorage,
-    tokenStorage,
-    tokenRefresher,
-  }),
+  new AuthorizationResponseInterceptor(cosecOptions),
 );
 ```
 
@@ -108,26 +117,36 @@ fetcher.interceptors.response.use(
 ### CoSecOptions Interface
 
 ```typescript
-interface CoSecOptions {
+interface CoSecOptions
+  extends AppIdCapable,
+    DeviceIdStorageCapable,
+    JwtTokenManagerCapable {
+  // Inherits from capability interfaces
+}
+```
+
+The `CoSecOptions` interface combines several capability interfaces:
+
+```typescript
+interface AppIdCapable {
   /**
    * Application ID to be sent in the CoSec-App-Id header
    */
   appId: string;
+}
 
+interface DeviceIdStorageCapable {
   /**
-   * Device ID storage instance
+   * Device ID storage instance for managing device identification
    */
   deviceIdStorage: DeviceIdStorage;
+}
 
+interface JwtTokenManagerCapable {
   /**
-   * Token storage instance
-   */
-  tokenStorage: TokenStorage;
-
-  /**
-   * Token refresher function
+   * JWT token manager for handling token operations
    */
-  tokenRefresher: TokenRefresher;
+  tokenManager: JwtTokenManager;
 }
 ```
 
@@ -146,83 +165,333 @@ The interceptor automatically adds the following headers to requests:
 
 #### AuthorizationRequestInterceptor
 
-Adds CoSec authentication headers to outgoing requests.
+Automatically adds CoSec authentication headers to outgoing HTTP requests.
 
 ```typescript
-new AuthorizationRequestInterceptor(options
-:
-CoSecOptions
-)
+const interceptor = new AuthorizationRequestInterceptor({
+  appId: 'your-app-id',
+  tokenManager: jwtTokenManager,
+  deviceIdStorage: deviceIdStorage,
+});
 ```
 
+**Headers Added:**
+
+- `Authorization: Bearer <access-token>`
+- `CoSec-App-Id: <app-id>`
+- `CoSec-Device-Id: <device-id>`
+- `CoSec-Request-Id: <unique-request-id>`
+
 #### AuthorizationResponseInterceptor
 
-Handles token refresh when the server returns status code 401.
+Handles automatic token refresh when receiving 401 Unauthorized responses.
+
+```typescript
+const interceptor = new AuthorizationResponseInterceptor({
+  appId: 'your-app-id',
+  tokenManager: jwtTokenManager,
+  deviceIdStorage: deviceIdStorage,
+});
+```
+
+**Features:**
+
+- Automatic retry with refreshed tokens
+- Exponential backoff for failed refresh attempts
+- Configurable retry limits
+
+#### JwtTokenManager
+
+Manages JWT token lifecycle including validation, refresh, and storage.
 
 ```typescript
-new AuthorizationResponseInterceptor(options
-:
-CoSecOptions
-)
+const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
+
+// Check if token is valid
+const isValid = await tokenManager.isValid();
+
+// Refresh token manually
+await tokenManager.refresh();
+
+// Get current token
+const token = tokenManager.getToken();
 ```
 
 #### TokenStorage
 
-Manages token storage in localStorage.
+Secure token storage with localStorage backend and fallback support.
 
 ```typescript
-const tokenStorage = new TokenStorage();
+const tokenStorage = new TokenStorage('optional-prefix');
 
-// Store tokens
+// Store composite token
 tokenStorage.set({
-  accessToken: 'access-token',
-  refreshToken: 'refresh-token',
+  accessToken: 'eyJ...',
+  refreshToken: 'eyJ...',
 });
 
-// Get tokens
+// Retrieve token
 const token = tokenStorage.get();
 
-// Clear tokens
-tokenStorage.clear();
+// Remove stored token
+tokenStorage.remove();
+
+// Check if token exists
+const exists = tokenStorage.exists();
 ```
 
 #### DeviceIdStorage
 
-Manages device ID storage in localStorage.
+Manages persistent device identification with localStorage.
 
 ```typescript
-const deviceIdStorage = new DeviceIdStorage();
+const deviceStorage = new DeviceIdStorage('optional-prefix');
+
+// Get or create device ID
+const deviceId = await deviceStorage.getOrCreate();
+
+// Set specific device ID
+deviceStorage.set('custom-device-id');
+
+// Get current device ID
+const currentId = deviceStorage.get();
+
+// Clear stored device ID
+deviceStorage.clear();
+
+// Generate new device ID without storing
+const newId = deviceStorage.generateDeviceId();
+```
+
+#### TokenRefresher
+
+Interface for implementing custom token refresh logic.
+
+```typescript
+interface TokenRefresher {
+  refresh(token: CompositeToken): Promise<CompositeToken>;
+}
+
+class CustomTokenRefresher implements TokenRefresher {
+  async refresh(token: CompositeToken): Promise<CompositeToken> {
+    const response = await fetch('/api/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken: token.refreshToken }),
+    });
+
+    if (!response.ok) {
+      throw new Error('Token refresh failed');
+    }
+
+    const newTokens = await response.json();
+    return {
+      accessToken: newTokens.accessToken,
+      refreshToken: newTokens.refreshToken,
+    };
+  }
+}
+```
+
+### Interfaces & Types
+
+#### Token Types
+
+```typescript
+interface AccessToken {
+  readonly value: string;
+}
+
+interface RefreshToken {
+  readonly value: string;
+}
+
+interface CompositeToken {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+}
+```
+
+#### JWT Token Types
+
+```typescript
+interface JwtPayload {
+  readonly sub?: string;
+  readonly exp?: number;
+  readonly iat?: number;
+  readonly iss?: string;
+  [key: string]: any;
+}
+
+interface JwtToken {
+  readonly header: JwtHeader;
+  readonly payload: JwtPayload;
+  readonly signature: string;
+  readonly raw: string;
+}
+```
+
+#### Configuration Types
+
+```typescript
+interface CoSecOptions
+  extends AppIdCapable,
+    DeviceIdStorageCapable,
+    JwtTokenManagerCapable {}
+
+interface AppIdCapable {
+  readonly appId: string;
+}
+
+interface DeviceIdStorageCapable {
+  readonly deviceIdStorage: DeviceIdStorage;
+}
+
+interface JwtTokenManagerCapable {
+  readonly tokenManager: JwtTokenManager;
+}
+```
+
+#### Response Types
+
+```typescript
+interface AuthorizeResult {
+  readonly authorized: boolean;
+  readonly reason: string;
+}
 
-// Get or create a device ID
-const deviceId = deviceIdStorage.getOrCreate();
+// Predefined authorization results
+const AuthorizeResults = {
+  ALLOW: { authorized: true, reason: 'Allow' },
+  EXPLICIT_DENY: { authorized: false, reason: 'Explicit Deny' },
+  IMPLICIT_DENY: { authorized: false, reason: 'Implicit Deny' },
+  TOKEN_EXPIRED: { authorized: false, reason: 'Token Expired' },
+  TOO_MANY_REQUESTS: { authorized: false, reason: 'Too Many Requests' },
+} as const;
+```
+
+## 🔗 Built-in Interceptors
+
+The CoSec package provides several specialized interceptors for different authentication and authorization scenarios:
+
+### Request Interceptors
+
+#### AuthorizationRequestInterceptor
+
+**Purpose**: Adds JWT Bearer token authentication headers to outgoing requests.
 
-// Store a specific device ID
-deviceIdStorage.set('specific-device-id');
+**Headers Added**:
 
-// Get the current device ID
-const currentDeviceId = deviceIdStorage.get();
+- `Authorization: Bearer <access-token>`
 
-// Clear the stored device ID
-deviceIdStorage.clear();
+**Use Case**: Standard JWT authentication for API requests.
 
-// Generate a new device ID (without storing it)
-const newDeviceId = deviceIdStorage.generateDeviceId();
+```typescript
+const interceptor = new AuthorizationRequestInterceptor({
+  appId: 'your-app-id',
+  tokenManager: jwtTokenManager,
+  deviceIdStorage: deviceStorage,
+});
 ```
 
-#### InMemoryStorage
+#### CoSecRequestInterceptor
+
+**Purpose**: Adds basic CoSec identification headers to requests.
+
+**Headers Added**:
 
-In-memory storage fallback for environments without localStorage.
+- `CoSec-App-Id: <app-id>`
+- `CoSec-Device-Id: <device-id>`
+- `CoSec-Request-Id: <unique-request-id>`
+
+**Use Case**: Device tracking and request attribution without full JWT authentication.
 
 ```typescript
-const inMemoryStorage = new InMemoryStorage();
+const interceptor = new CoSecRequestInterceptor({
+  appId: 'your-app-id',
+  deviceIdStorage: deviceStorage,
+});
 ```
 
-### Interfaces
+#### ResourceAttributionRequestInterceptor
+
+**Purpose**: Automatically injects tenant and owner ID path parameters from JWT token claims.
 
-- `AccessToken`: Contains an access token
-- `RefreshToken`: Contains a refresh token
-- `CompositeToken`: Contains both access and refresh tokens
-- `TokenRefresher`: Provides a method to refresh tokens
+**Functionality**: Extracts `tenantId` and `sub` (owner ID) from JWT payload and adds them to URL path parameters.
+
+**Use Case**: Multi-tenant applications with tenant-scoped resources.
+
+```typescript
+const interceptor = new ResourceAttributionRequestInterceptor({
+  tenantId: 'tenantId', // Path parameter name for tenant ID
+  ownerId: 'ownerId', // Path parameter name for owner ID
+  tokenStorage: tokenStorage,
+});
+```
+
+### Response Interceptors
+
+#### AuthorizationResponseInterceptor
+
+**Purpose**: Handles automatic token refresh when receiving 401 Unauthorized responses.
+
+**Functionality**:
+
+- Detects 401 responses
+- Attempts token refresh using configured TokenRefresher
+- Retries original request with new token
+- Exponential backoff for failed refresh attempts
+
+**Use Case**: Seamless token refresh without user intervention.
+
+```typescript
+const interceptor = new AuthorizationResponseInterceptor({
+  appId: 'your-app-id',
+  tokenManager: jwtTokenManager,
+  deviceIdStorage: deviceStorage,
+});
+```
+
+### Error Interceptors
+
+#### UnauthorizedErrorInterceptor
+
+**Purpose**: Provides centralized handling of authentication failures with custom callback logic.
+
+**Functionality**:
+
+- Detects 401 responses and RefreshTokenError exceptions
+- Invokes custom callback for error handling
+- Allows applications to implement login redirects, token cleanup, etc.
+
+**Use Case**: Custom authentication error handling and user experience flows.
+
+```typescript
+const interceptor = new UnauthorizedErrorInterceptor({
+  onUnauthorized: exchange => {
+    console.log('Authentication failed for:', exchange.request.url);
+    // Redirect to login or show error message
+    window.location.href = '/login';
+  },
+});
+```
+
+### Interceptor Order & Execution
+
+Interceptors execute in the following default order:
+
+1. **Request Phase**:
+   - `AuthorizationRequestInterceptor` (adds Bearer token)
+   - `CoSecRequestInterceptor` (adds CoSec headers)
+   - `ResourceAttributionRequestInterceptor` (adds path parameters)
+
+2. **Response Phase**:
+   - `AuthorizationResponseInterceptor` (handles token refresh)
+
+3. **Error Phase**:
+   - `UnauthorizedErrorInterceptor` (handles auth errors)
+
+**Note**: Interceptor execution order can be customized using the `order` property. Higher order values execute later in the chain.
 
 ## 🛠️ Examples
 
@@ -231,23 +500,27 @@ const inMemoryStorage = new InMemoryStorage();
 ```typescript
 import { Fetcher } from '@ahoo-wang/fetcher';
 import {
-  CoSecRequestInterceptor,
-  CoSecResponseInterceptor,
+  AuthorizationRequestInterceptor,
+  AuthorizationResponseInterceptor,
   DeviceIdStorage,
   TokenStorage,
+  JwtTokenManager,
+  TokenRefresher,
+  CompositeToken,
 } from '@ahoo-wang/fetcher-cosec';
 
 // Create storage instances
 const deviceIdStorage = new DeviceIdStorage();
 const tokenStorage = new TokenStorage();
 
-// Create token refresher
-const tokenRefresher = {
-  async refresh(token) {
+// Implement token refresher
+const tokenRefresher: TokenRefresher = {
+  async refresh(token: CompositeToken): Promise<CompositeToken> {
     const response = await fetch('/api/auth/refresh', {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
+        Authorization: `Bearer ${token.accessToken}`,
       },
       body: JSON.stringify({
         refreshToken: token.refreshToken,
@@ -255,7 +528,7 @@ const tokenRefresher = {
     });
 
     if (!response.ok) {
-      throw new Error('Token refresh failed');
+      throw new Error(`Token refresh failed: ${response.status}`);
     }
 
     const tokens = await response.json();
@@ -266,77 +539,126 @@ const tokenRefresher = {
   },
 };
 
+// Create JWT token manager
+const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
+
 // Create fetcher with CoSec interceptors
 const secureFetcher = new Fetcher({
   baseURL: 'https://api.example.com',
 });
 
+// Add request interceptor for authentication headers
 secureFetcher.interceptors.request.use(
-  new CoSecRequestInterceptor({
+  new AuthorizationRequestInterceptor({
     appId: 'my-app-id',
+    tokenManager,
     deviceIdStorage,
-    tokenStorage,
-    tokenRefresher,
   }),
 );
 
+// Add response interceptor for token refresh
 secureFetcher.interceptors.response.use(
-  new CoSecResponseInterceptor({
+  new AuthorizationResponseInterceptor({
     appId: 'my-app-id',
+    tokenManager,
     deviceIdStorage,
-    tokenStorage,
-    tokenRefresher,
   }),
 );
 
-// Use the fetcher
-const response = await secureFetcher.get('/api/user/profile');
+// Now all requests will be automatically authenticated
+const userProfile = await secureFetcher.get('/api/user/profile');
+const userPosts = await secureFetcher.get('/api/user/posts');
 ```
 
-### Advanced Token Refresh
+### Advanced Token Refresh with Retry Logic
 
 ```typescript
-import { CoSecTokenRefresher } from '@ahoo-wang/fetcher-cosec';
+import {
+  TokenRefresher,
+  CompositeToken,
+  JwtTokenManager,
+  TokenStorage,
+} from '@ahoo-wang/fetcher-cosec';
+
+class ResilientTokenRefresher implements TokenRefresher {
+  private maxRetries = 3;
+  private baseDelay = 1000; // 1 second
 
-// Custom token refresher with retry logic
-class ResilientTokenRefresher extends CoSecTokenRefresher {
   async refresh(token: CompositeToken): Promise<CompositeToken> {
-    const maxRetries = 3;
     let lastError: Error;
 
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
       try {
-        // Add exponential backoff
+        // Exponential backoff with jitter
         if (attempt > 1) {
-          await new Promise(resolve =>
-            setTimeout(resolve, Math.pow(2, attempt) * 1000),
-          );
+          const delay = Math.pow(2, attempt - 1) * this.baseDelay;
+          const jitter = Math.random() * 0.1 * delay;
+          await new Promise(resolve => setTimeout(resolve, delay + jitter));
         }
 
-        const response = await this.options.fetcher.post<CompositeToken>(
-          this.options.endpoint,
-          { body: token },
-          {
-            resultExtractor: ResultExtractors.Json,
-            attributes: new Map([[IGNORE_REFRESH_TOKEN_ATTRIBUTE_KEY, true]]),
+        const response = await fetch('/api/auth/refresh', {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Retry-Attempt': attempt.toString(),
           },
-        );
+          body: JSON.stringify({
+            refreshToken: token.refreshToken,
+            deviceId: await this.getDeviceId(),
+          }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const newTokens = await response.json();
+
+        // Validate token structure
+        if (!newTokens.accessToken || !newTokens.refreshToken) {
+          throw new Error('Invalid token response structure');
+        }
 
-        return response;
+        return {
+          accessToken: newTokens.accessToken,
+          refreshToken: newTokens.refreshToken,
+        };
       } catch (error) {
         lastError = error as Error;
-        console.warn(`Token refresh attempt ${attempt} failed:`, error);
+        console.warn(
+          `Token refresh attempt ${attempt}/${this.maxRetries} failed:`,
+          error,
+        );
+
+        // Don't retry on authentication errors (401/403)
+        if (error instanceof Response) {
+          const status = error.status;
+          if (status === 401 || status === 403) {
+            throw error;
+          }
+        }
 
-        // Don't retry on authentication errors
-        if (error.status === 401 || error.status === 403) {
-          throw error;
+        // Don't retry on the last attempt
+        if (attempt === this.maxRetries) {
+          break;
         }
       }
     }
 
     throw lastError!;
   }
+
+  private async getDeviceId(): Promise<string> {
+    // Implementation to get current device ID
+    const deviceStorage = new DeviceIdStorage();
+    return await deviceStorage.getOrCreate();
+  }
 }
+
+// Usage
+const tokenStorage = new TokenStorage();
+const tokenRefresher = new ResilientTokenRefresher();
+const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
 ```
 
 ### Multi-Tenant Authentication
@@ -349,75 +671,155 @@ import {
   DeviceIdStorage,
   TokenStorage,
   JwtTokenManager,
+  TokenRefresher,
+  CompositeToken,
 } from '@ahoo-wang/fetcher-cosec';
 
-// Tenant configuration
+// Tenant configuration interface
 interface TenantConfig {
   id: string;
+  name: string;
   appId: string;
   baseURL: string;
   refreshEndpoint: string;
+  tokenStoragePrefix?: string;
 }
 
-// Create tenant-specific fetcher
-function createTenantFetcher(tenant: TenantConfig) {
-  const fetcher = new Fetcher({
-    baseURL: tenant.baseURL,
-  });
+// Tenant registry for managing multiple tenants
+class TenantRegistry {
+  private tenants = new Map<string, TenantConfig>();
+  private fetchers = new Map<string, Fetcher>();
 
-  // Tenant-specific storage with prefixed keys
-  const tokenStorage = new TokenStorage(`tenant-${tenant.id}`);
-  const deviceStorage = new DeviceIdStorage(`tenant-${tenant.id}`);
+  registerTenant(config: TenantConfig): void {
+    // Use tenant ID as storage prefix for isolation
+    const storagePrefix = config.tokenStoragePrefix || `tenant-${config.id}`;
+    config.tokenStoragePrefix = storagePrefix;
+    this.tenants.set(config.id, config);
+  }
 
-  // Tenant-specific token refresher
-  const tokenRefresher = new CoSecTokenRefresher({
-    fetcher,
-    endpoint: tenant.refreshEndpoint,
-  });
+  getFetcher(tenantId: string): Fetcher {
+    if (this.fetchers.has(tenantId)) {
+      return this.fetchers.get(tenantId)!;
+    }
 
-  const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
+    const config = this.tenants.get(tenantId);
+    if (!config) {
+      throw new Error(`Tenant '${tenantId}' not registered`);
+    }
 
-  // Add interceptors with tenant context
-  fetcher.interceptors.request.use(
-    new AuthorizationRequestInterceptor({
-      tokenManager,
-      appId: tenant.appId,
-      deviceIdStorage: deviceStorage,
-    }),
-  );
+    const fetcher = this.createTenantFetcher(config);
+    this.fetchers.set(tenantId, fetcher);
+    return fetcher;
+  }
 
-  fetcher.interceptors.response.use(
-    new AuthorizationResponseInterceptor({
-      tokenManager,
-      appId: tenant.appId,
-      deviceIdStorage: deviceStorage,
-    }),
-  );
+  private createTenantFetcher(config: TenantConfig): Fetcher {
+    const fetcher = new Fetcher({
+      baseURL: config.baseURL,
+    });
+
+    // Isolated storage per tenant
+    const tokenStorage = new TokenStorage(config.tokenStoragePrefix);
+    const deviceStorage = new DeviceIdStorage(config.tokenStoragePrefix);
+
+    // Tenant-specific token refresher
+    const tokenRefresher: TokenRefresher = {
+      async refresh(token: CompositeToken): Promise<CompositeToken> {
+        const response = await fetch(
+          `${config.baseURL}${config.refreshEndpoint}`,
+          {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'X-Tenant-ID': config.id,
+            },
+            body: JSON.stringify({
+              refreshToken: token.refreshToken,
+            }),
+          },
+        );
+
+        if (!response.ok) {
+          throw new Error(`Token refresh failed for tenant ${config.id}`);
+        }
+
+        const tokens = await response.json();
+        return {
+          accessToken: tokens.accessToken,
+          refreshToken: tokens.refreshToken,
+        };
+      },
+    };
+
+    const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
 
-  return fetcher;
+    // Add CoSec interceptors with tenant context
+    fetcher.interceptors.request.use(
+      new AuthorizationRequestInterceptor({
+        appId: config.appId,
+        tokenManager,
+        deviceIdStorage: deviceStorage,
+      }),
+    );
+
+    fetcher.interceptors.response.use(
+      new AuthorizationResponseInterceptor({
+        appId: config.appId,
+        tokenManager,
+        deviceIdStorage: deviceStorage,
+      }),
+    );
+
+    return fetcher;
+  }
+
+  // Cleanup method for tenant logout
+  async logoutTenant(tenantId: string): Promise<void> {
+    const config = this.tenants.get(tenantId);
+    if (config) {
+      const tokenStorage = new TokenStorage(config.tokenStoragePrefix);
+      tokenStorage.remove();
+
+      const deviceStorage = new DeviceIdStorage(config.tokenStoragePrefix);
+      deviceStorage.clear();
+
+      this.fetchers.delete(tenantId);
+    }
+  }
 }
 
-// Usage
-const tenantA = createTenantFetcher({
-  id: 'tenant-a',
-  appId: 'app-a-id',
-  baseURL: 'https://api-tenant-a.example.com',
+// Usage example
+const tenantRegistry = new TenantRegistry();
+
+// Register multiple tenants
+tenantRegistry.registerTenant({
+  id: 'enterprise-a',
+  name: 'Enterprise A',
+  appId: 'app-enterprise-a',
+  baseURL: 'https://api.enterprise-a.com',
   refreshEndpoint: '/auth/refresh',
 });
 
-const tenantB = createTenantFetcher({
-  id: 'tenant-b',
-  appId: 'app-b-id',
-  baseURL: 'https://api-tenant-b.example.com',
+tenantRegistry.registerTenant({
+  id: 'enterprise-b',
+  name: 'Enterprise B',
+  appId: 'app-enterprise-b',
+  baseURL: 'https://api.enterprise-b.com',
   refreshEndpoint: '/auth/refresh',
 });
 
-// Each tenant maintains isolated authentication state
-const userProfileA = await tenantA.get('/user/profile');
-const userProfileB = await tenantB.get('/user/profile');
+// Use tenant-specific fetchers
+const tenantAFetcher = tenantRegistry.getFetcher('enterprise-a');
+const tenantBFetcher = tenantRegistry.getFetcher('enterprise-b');
+
+// Each tenant maintains completely isolated authentication
+const profileA = await tenantAFetcher.get('/user/profile');
+const profileB = await tenantBFetcher.get('/user/profile');
+
+// Logout specific tenant
+await tenantRegistry.logoutTenant('enterprise-a');
 ```
 
-### Error Handling and Recovery
+### Comprehensive Error Handling and Recovery
 
 ```typescript
 import { Fetcher } from '@ahoo-wang/fetcher';
@@ -427,179 +829,667 @@ import {
   TokenStorage,
   DeviceIdStorage,
   JwtTokenManager,
+  TokenRefresher,
+  CompositeToken,
 } from '@ahoo-wang/fetcher-cosec';
 
-// Enhanced error handling
+// Enhanced authentication error handler
 class AuthErrorHandler {
-  static handleAuthError(error: any, tokenManager: JwtTokenManager) {
-    if (error.status === 401) {
-      // Token expired - clear stored tokens
+  private static readonly MAX_RETRY_ATTEMPTS = 3;
+  private static readonly RETRY_DELAY_MS = 1000;
+
+  static async handleAuthError(
+    error: any,
+    tokenManager: JwtTokenManager,
+    context?: { endpoint?: string; attempt?: number },
+  ): Promise<boolean> {
+    // Returns true if error was handled
+    const status = error.status || error.response?.status;
+    const attempt = context?.attempt || 1;
+
+    switch (status) {
+      case 401: // Unauthorized - token expired or invalid
+        console.warn('Authentication token expired or invalid');
+        await this.handleTokenExpiration(tokenManager);
+        return true;
+
+      case 403: // Forbidden - insufficient permissions
+        console.error('Access forbidden - insufficient permissions');
+        this.handleForbiddenAccess(error, context?.endpoint);
+        return true;
+
+      case 429: // Too Many Requests - rate limited
+        console.warn('Rate limited - implementing backoff strategy');
+        await this.handleRateLimit(attempt);
+        return true;
+
+      case 500: // Internal Server Error
+      case 502: // Bad Gateway
+      case 503: // Service Unavailable
+      case 504: // Gateway Timeout
+        console.warn(`Server error (${status}) - retrying with backoff`);
+        await this.handleServerError(attempt);
+        return attempt < this.MAX_RETRY_ATTEMPTS;
+
+      default:
+        // Network errors, CORS issues, etc.
+        console.error('Authentication network error:', error);
+        return this.handleNetworkError(error, attempt);
+    }
+  }
+
+  private static async handleTokenExpiration(
+    tokenManager: JwtTokenManager,
+  ): Promise<void> {
+    try {
+      // Clear expired tokens
       tokenManager.tokenStorage.remove();
 
-      // Redirect to login or trigger re-authentication
-      window.location.href = '/login?reason=expired';
-    } else if (error.status === 403) {
-      // Forbidden - insufficient permissions
-      console.error('Access forbidden:', error);
-      // Show permission error UI
-    } else if (error.status === 429) {
-      // Rate limited
-      console.warn('Rate limited, retrying after delay...');
-      // Implement retry logic
-    } else {
-      // Network or other errors
-      console.error('Authentication error:', error);
+      // Attempt refresh if refresh token exists
+      const currentToken = tokenManager.getToken();
+      if (currentToken?.refreshToken) {
+        await tokenManager.refresh();
+      } else {
+        // No refresh token - redirect to login
+        this.redirectToLogin('token_expired');
+      }
+    } catch (refreshError) {
+      console.error('Token refresh failed:', refreshError);
+      this.redirectToLogin('refresh_failed');
+    }
+  }
+
+  private static handleForbiddenAccess(error: any, endpoint?: string): void {
+    // Log security event
+    console.error(`Forbidden access to ${endpoint}:`, error);
+
+    // Show user-friendly error message
+    this.showErrorNotification(
+      'Access Denied',
+      'You do not have permission to access this resource.',
+    );
+
+    // Optionally redirect to appropriate page
+    // window.location.href = '/access-denied';
+  }
+
+  private static async handleRateLimit(attempt: number): Promise<void> {
+    const delay = Math.min(
+      this.RETRY_DELAY_MS * Math.pow(2, attempt - 1),
+      30000, // Max 30 seconds
+    );
+
+    console.log(`Rate limited - waiting ${delay}ms before retry`);
+    await new Promise(resolve => setTimeout(resolve, delay));
+  }
+
+  private static async handleServerError(attempt: number): Promise<void> {
+    const delay = this.RETRY_DELAY_MS * Math.pow(2, attempt - 1);
+    console.log(`Server error - retrying in ${delay}ms (attempt ${attempt})`);
+    await new Promise(resolve => setTimeout(resolve, delay));
+  }
+
+  private static handleNetworkError(error: any, attempt: number): boolean {
+    // Check if it's a network connectivity issue
+    if (!navigator.onLine) {
+      console.warn('Network offline - queuing request for retry');
+      // Could implement request queuing here
+      return true; // Allow retry when back online
     }
+
+    // CORS or other network errors
+    if (error.name === 'TypeError' && error.message.includes('CORS')) {
+      console.error('CORS error - check server configuration');
+      return false; // Don't retry CORS errors
+    }
+
+    // Allow retry for other network errors up to max attempts
+    return attempt < this.MAX_RETRY_ATTEMPTS;
+  }
+
+  private static redirectToLogin(reason: string): void {
+    const loginUrl = `/login?reason=${reason}&returnUrl=${encodeURIComponent(window.location.pathname)}`;
+    window.location.href = loginUrl;
+  }
+
+  private static showErrorNotification(title: string, message: string): void {
+    // Implementation depends on your notification system
+    console.error(`${title}: ${message}`);
+    // Example: show toast notification
+    // toast.error(message, { title });
   }
 }
 
-// Create fetcher with error handling
-const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
+// Create resilient fetcher with comprehensive error handling
+function createResilientFetcher(
+  baseURL: string,
+  tokenRefresher: TokenRefresher,
+) {
+  const fetcher = new Fetcher({ baseURL });
 
-const tokenManager = new JwtTokenManager(new TokenStorage(), tokenRefresher);
+  const tokenManager = new JwtTokenManager(new TokenStorage(), tokenRefresher);
 
-// Add response interceptor with error handling
-fetcher.interceptors.response.use(
-  new AuthorizationResponseInterceptor({
-    tokenManager,
-    appId: 'your-app-id',
-    deviceIdStorage: new DeviceIdStorage(),
-  }),
-  // Add error handler after auth interceptor
-  {
-    onRejected: error => {
-      AuthErrorHandler.handleAuthError(error, tokenManager);
-      throw error; // Re-throw to maintain error chain
+  const deviceStorage = new DeviceIdStorage();
+
+  // Add response interceptor with error recovery
+  fetcher.interceptors.response.use(
+    new AuthorizationResponseInterceptor({
+      appId: 'your-app-id',
+      tokenManager,
+      deviceIdStorage: deviceStorage,
+    }),
+    // Global error handler
+    {
+      onRejected: async error => {
+        const wasHandled = await AuthErrorHandler.handleAuthError(
+          error,
+          tokenManager,
+          { endpoint: error.config?.url },
+        );
+
+        if (!wasHandled) {
+          throw error; // Re-throw unhandled errors
+        }
+
+        // For handled errors, return a resolved promise to prevent rejection
+        return Promise.resolve();
+      },
     },
-  },
+  );
+
+  return { fetcher, tokenManager };
+}
+
+// Usage
+const { fetcher, tokenManager } = createResilientFetcher(
+  'https://api.example.com',
+  yourTokenRefresher,
 );
+
+// All requests now have automatic error handling and recovery
+try {
+  const data = await fetcher.get('/protected/resource');
+} catch (error) {
+  // Only unhandled errors will reach here
+  console.error('Unhandled error:', error);
+}
 ```
 
-### Performance Monitoring
+### Performance Monitoring and Optimization
 
 ```typescript
 import { Fetcher } from '@ahoo-wang/fetcher';
 import {
   AuthorizationRequestInterceptor,
+  AuthorizationResponseInterceptor,
   TokenStorage,
+  DeviceIdStorage,
   JwtTokenManager,
+  TokenRefresher,
+  CompositeToken,
 } from '@ahoo-wang/fetcher-cosec';
 
-// Performance monitoring interceptor
+// Comprehensive authentication performance monitor
 class AuthPerformanceMonitor {
   private metrics = {
+    // Token operations
     tokenRefreshCount: 0,
-    averageRefreshTime: 0,
-    totalRefreshTime: 0,
-    interceptorOverhead: 0,
+    tokenRefreshTotalTime: 0,
+    tokenRefreshAverageTime: 0,
+    tokenRefreshSuccessRate: 1.0,
+
+    // Storage operations
+    storageReadCount: 0,
+    storageWriteCount: 0,
+    storageReadTime: 0,
+    storageWriteTime: 0,
+
+    // Interceptor performance
+    requestInterceptorOverhead: 0,
+    responseInterceptorOverhead: 0,
+    totalRequests: 0,
+
+    // Device operations
+    deviceIdGenerationTime: 0,
+    deviceIdReadTime: 0,
+
+    // Error tracking
+    errorCount: 0,
+    retryCount: 0,
+
+    // Cache performance
+    cacheHitRate: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
   };
 
-  recordTokenRefresh(duration: number) {
-    this.metrics.tokenRefreshCount++;
-    this.metrics.totalRefreshTime += duration;
-    this.metrics.averageRefreshTime =
-      this.metrics.totalRefreshTime / this.metrics.tokenRefreshCount;
+  private startTimes = new Map<string, number>();
 
-    // Report to monitoring service
-    console.log(
-      `Token refresh: ${duration}ms (avg: ${this.metrics.averageRefreshTime.toFixed(2)}ms)`,
-    );
+  // Token refresh monitoring
+  startTokenRefresh(operationId: string): void {
+    this.startTimes.set(`refresh-${operationId}`, performance.now());
+  }
+
+  endTokenRefresh(operationId: string, success: boolean): void {
+    const startTime = this.startTimes.get(`refresh-${operationId}`);
+    if (startTime) {
+      const duration = performance.now() - startTime;
+      this.metrics.tokenRefreshCount++;
+      this.metrics.tokenRefreshTotalTime += duration;
+      this.metrics.tokenRefreshAverageTime =
+        this.metrics.tokenRefreshTotalTime / this.metrics.tokenRefreshCount;
+
+      if (!success) {
+        this.metrics.tokenRefreshSuccessRate =
+          ((this.metrics.tokenRefreshCount - 1) /
+            this.metrics.tokenRefreshCount) *
+          this.metrics.tokenRefreshSuccessRate;
+      }
+
+      this.startTimes.delete(`refresh-${operationId}`);
+      this.reportMetric('token_refresh_duration', duration);
+    }
+  }
+
+  // Storage operation monitoring
+  recordStorageOperation(operation: 'read' | 'write', duration: number): void {
+    if (operation === 'read') {
+      this.metrics.storageReadCount++;
+      this.metrics.storageReadTime += duration;
+    } else {
+      this.metrics.storageWriteCount++;
+      this.metrics.storageWriteTime += duration;
+    }
+  }
+
+  // Interceptor overhead monitoring
+  recordInterceptorOverhead(
+    type: 'request' | 'response',
+    duration: number,
+  ): void {
+    if (type === 'request') {
+      this.metrics.requestInterceptorOverhead += duration;
+    } else {
+      this.metrics.responseInterceptorOverhead += duration;
+    }
+    this.metrics.totalRequests++;
+  }
+
+  // Device operation monitoring
+  recordDeviceOperation(
+    operation: 'generate' | 'read',
+    duration: number,
+  ): void {
+    if (operation === 'generate') {
+      this.metrics.deviceIdGenerationTime += duration;
+    } else {
+      this.metrics.deviceIdReadTime += duration;
+    }
+  }
+
+  // Error and retry tracking
+  recordError(): void {
+    this.metrics.errorCount++;
+  }
+
+  recordRetry(): void {
+    this.metrics.retryCount++;
+  }
+
+  // Cache performance
+  recordCacheAccess(hit: boolean): void {
+    if (hit) {
+      this.metrics.cacheHits++;
+    } else {
+      this.metrics.cacheMisses++;
+    }
+    const total = this.metrics.cacheHits + this.metrics.cacheMisses;
+    this.metrics.cacheHitRate = total > 0 ? this.metrics.cacheHits / total : 0;
   }
 
-  recordInterceptorOverhead(duration: number) {
-    this.metrics.interceptorOverhead = duration;
+  // Reporting
+  private reportMetric(name: string, value: number): void {
+    // Send to monitoring service (e.g., DataDog, New Relic, etc.)
+    console.log(`[AuthPerf] ${name}: ${value.toFixed(2)}ms`);
+
+    // Threshold alerts
+    if (name === 'token_refresh_duration' && value > 5000) {
+      console.warn(
+        `[AuthPerf] Slow token refresh detected: ${value.toFixed(2)}ms`,
+      );
+    }
   }
 
   getMetrics() {
-    return { ...this.metrics };
+    return {
+      ...this.metrics,
+      // Calculated fields
+      averageStorageReadTime:
+        this.metrics.storageReadCount > 0
+          ? this.metrics.storageReadTime / this.metrics.storageReadCount
+          : 0,
+      averageStorageWriteTime:
+        this.metrics.storageWriteCount > 0
+          ? this.metrics.storageWriteTime / this.metrics.storageWriteCount
+          : 0,
+      averageRequestOverhead:
+        this.metrics.totalRequests > 0
+          ? this.metrics.requestInterceptorOverhead / this.metrics.totalRequests
+          : 0,
+      averageResponseOverhead:
+        this.metrics.totalRequests > 0
+          ? this.metrics.responseInterceptorOverhead /
+            this.metrics.totalRequests
+          : 0,
+    };
+  }
+
+  reset(): void {
+    // Reset counters but keep averages
+    this.metrics.tokenRefreshCount = 0;
+    this.metrics.tokenRefreshTotalTime = 0;
+    this.metrics.storageReadCount = 0;
+    this.metrics.storageWriteCount = 0;
+    this.metrics.storageReadTime = 0;
+    this.metrics.storageWriteTime = 0;
+    this.metrics.totalRequests = 0;
+    this.metrics.requestInterceptorOverhead = 0;
+    this.metrics.responseInterceptorOverhead = 0;
+    this.metrics.errorCount = 0;
+    this.metrics.retryCount = 0;
+    this.metrics.cacheHits = 0;
+    this.metrics.cacheMisses = 0;
   }
 }
 
-// Create performance monitor
-const performanceMonitor = new AuthPerformanceMonitor();
+// Enhanced token refresher with performance monitoring
+class MonitoredTokenRefresher implements TokenRefresher {
+  constructor(
+    private baseRefresher: TokenRefresher,
+    private monitor: AuthPerformanceMonitor,
+  ) {}
 
-// Enhanced token refresher with monitoring
-const tokenRefresher = {
   async refresh(token: CompositeToken): Promise<CompositeToken> {
-    const startTime = performance.now();
+    const operationId = `refresh-${Date.now()}-${Math.random()}`;
+    this.monitor.startTokenRefresh(operationId);
 
     try {
-      const response = await fetch('/api/auth/refresh', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(token),
-      });
-
-      if (!response.ok) {
-        throw new Error(`Refresh failed: ${response.status}`);
-      }
-
-      const newToken = await response.json();
-
-      const duration = performance.now() - startTime;
-      performanceMonitor.recordTokenRefresh(duration);
-
-      return newToken;
+      const result = await this.baseRefresher.refresh(token);
+      this.monitor.endTokenRefresh(operationId, true);
+      return result;
     } catch (error) {
-      const duration = performance.now() - startTime;
-      performanceMonitor.recordTokenRefresh(duration);
+      this.monitor.endTokenRefresh(operationId, false);
+      this.monitor.recordError();
       throw error;
     }
-  },
-};
+  }
+}
 
-// Create fetcher with monitoring
-const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
+// Enhanced storage with performance monitoring
+class MonitoredTokenStorage extends TokenStorage {
+  constructor(
+    private baseStorage: TokenStorage,
+    private monitor: AuthPerformanceMonitor,
+  ) {
+    super();
+  }
 
-const tokenManager = new JwtTokenManager(new TokenStorage(), tokenRefresher);
+  set(token: CompositeToken): void {
+    const startTime = performance.now();
+    this.baseStorage.set(token);
+    const duration = performance.now() - startTime;
+    this.monitor.recordStorageOperation('write', duration);
+  }
 
-// Add request interceptor with performance monitoring
-fetcher.interceptors.request.use(
-  new AuthorizationRequestInterceptor({ tokenManager }),
-  // Monitor interceptor performance
-  {
-    onFulfilled: async config => {
-      const startTime = performance.now();
-      // Process request
-      const result = await config;
-      const duration = performance.now() - startTime;
-      performanceMonitor.recordInterceptorOverhead(duration);
-      return result;
+  get(): CompositeToken | null {
+    const startTime = performance.now();
+    const result = this.baseStorage.get();
+    const duration = performance.now() - startTime;
+    this.monitor.recordStorageOperation('read', duration);
+    return result;
+  }
+
+  remove(): void {
+    const startTime = performance.now();
+    this.baseStorage.remove();
+    const duration = performance.now() - startTime;
+    this.monitor.recordStorageOperation('write', duration);
+  }
+}
+
+// Create monitored fetcher
+function createMonitoredFetcher(
+  baseURL: string,
+  baseTokenRefresher: TokenRefresher,
+) {
+  const monitor = new AuthPerformanceMonitor();
+
+  const tokenStorage = new MonitoredTokenStorage(new TokenStorage(), monitor);
+
+  const tokenRefresher = new MonitoredTokenRefresher(
+    baseTokenRefresher,
+    monitor,
+  );
+
+  const tokenManager = new JwtTokenManager(tokenStorage, tokenRefresher);
+  const deviceStorage = new DeviceIdStorage();
+
+  const fetcher = new Fetcher({ baseURL });
+
+  // Add request interceptor with monitoring
+  fetcher.interceptors.request.use(
+    new AuthorizationRequestInterceptor({
+      appId: 'monitored-app',
+      tokenManager,
+      deviceIdStorage: deviceStorage,
+    }),
+    // Monitor request interceptor overhead
+    {
+      onFulfilled: async config => {
+        const startTime = performance.now();
+        const result = await config;
+        const duration = performance.now() - startTime;
+        monitor.recordInterceptorOverhead('request', duration);
+        return result;
+      },
+    },
+  );
+
+  // Add response interceptor with monitoring
+  fetcher.interceptors.response.use(
+    new AuthorizationResponseInterceptor({
+      appId: 'monitored-app',
+      tokenManager,
+      deviceIdStorage: deviceStorage,
+    }),
+    // Monitor response interceptor overhead
+    {
+      onFulfilled: async response => {
+        const startTime = performance.now();
+        const result = await response;
+        const duration = performance.now() - startTime;
+        monitor.recordInterceptorOverhead('response', duration);
+        return result;
+      },
     },
+  );
+
+  return { fetcher, monitor };
+}
+
+// Usage example
+const baseTokenRefresher: TokenRefresher = {
+  async refresh(token: CompositeToken): Promise<CompositeToken> {
+    const response = await fetch('/api/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken: token.refreshToken }),
+    });
+
+    if (!response.ok) {
+      throw new Error('Token refresh failed');
+    }
+
+    return await response.json();
   },
+};
+
+const { fetcher, monitor } = createMonitoredFetcher(
+  'https://api.example.com',
+  baseTokenRefresher,
 );
 
-// Access metrics
-console.log('Auth Performance Metrics:', performanceMonitor.getMetrics());
+// Use the monitored fetcher
+await fetcher.get('/user/profile');
+
+// Get performance metrics
+setInterval(() => {
+  const metrics = monitor.getMetrics();
+  console.log('Authentication Performance Metrics:', {
+    tokenRefresh: {
+      count: metrics.tokenRefreshCount,
+      averageTime: `${metrics.tokenRefreshAverageTime.toFixed(2)}ms`,
+      successRate: `${(metrics.tokenRefreshSuccessRate * 100).toFixed(1)}%`,
+    },
+    storage: {
+      reads: metrics.storageReadCount,
+      writes: metrics.storageWriteCount,
+      averageReadTime: `${metrics.averageStorageReadTime.toFixed(2)}ms`,
+      averageWriteTime: `${metrics.averageStorageWriteTime.toFixed(2)}ms`,
+    },
+    interceptors: {
+      totalRequests: metrics.totalRequests,
+      averageRequestOverhead: `${metrics.averageRequestOverhead.toFixed(2)}ms`,
+      averageResponseOverhead: `${metrics.averageResponseOverhead.toFixed(2)}ms`,
+    },
+    cache: {
+      hitRate: `${(metrics.cacheHitRate * 100).toFixed(1)}%`,
+    },
+    errors: {
+      count: metrics.errorCount,
+      retries: metrics.retryCount,
+    },
+  });
+}, 30000); // Report every 30 seconds
 ```
 
 ## 🧪 Testing
 
+The package includes comprehensive test coverage for all components:
+
 ```bash
-# Run tests
+# Run all tests
 pnpm test
 
-# Run tests with coverage
+# Run tests with coverage report
 pnpm test --coverage
+
+# Run tests in watch mode during development
+pnpm test --watch
+
+# Run specific test file
+pnpm test tokenStorage.test.ts
+
+# Run integration tests
+pnpm test:it
 ```
 
-## 🌐 CoSec Framework
+### Test Coverage
 
-This package is designed to work with the [CoSec authentication framework](https://github.com/Ahoo-Wang/CoSec). For more
-information about CoSec features and capabilities, please visit
-the [CoSec GitHub repository](https://github.com/Ahoo-Wang/CoSec).
+- **Unit Tests**: Individual component testing with mocks
+- **Integration Tests**: End-to-end authentication flows
+- **Security Tests**: Token validation and security scenarios
+- **Performance Tests**: Benchmarking and memory leak detection
+
+### Testing Utilities
+
+```typescript
+import {
+  createMockJwtToken,
+  createExpiredJwtToken,
+  MockTokenStorage,
+  MockDeviceStorage,
+} from '@ahoo-wang/fetcher-cosec/test-utils';
+
+// Create test tokens
+const validToken = createMockJwtToken({ sub: 'user123' });
+const expiredToken = createExpiredJwtToken();
+
+// Use mock storage for isolated testing
+const tokenStorage = new MockTokenStorage();
+const deviceStorage = new MockDeviceStorage();
+```
+
+## 🌐 CoSec Framework Integration
+
+This package provides seamless integration with the [CoSec authentication framework](https://github.com/Ahoo-Wang/CoSec), enabling enterprise-grade security features:
+
+### Key Integration Points
+
+- **Centralized Authentication**: Connects to CoSec's authentication server
+- **Device Management**: Automatic device registration and tracking
+- **Token Lifecycle**: Full JWT token management with refresh capabilities
+- **Security Policies**: Enforces CoSec security policies and rules
+- **Audit Logging**: Comprehensive request attribution and logging
+
+### Architecture Overview
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Application   │────│  Fetcher CoSec   │────│     CoSec       │
+│                 │    │   Integration    │    │   Framework     │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+         │                       │                       │
+         └─ HTTP Requests        └─ Auth Headers         └─ Token Validation
+         └─ Response Handling    └─ Token Refresh        └─ Device Tracking
+         └─ Error Recovery       └─ Security Policies    └─ Audit Logging
+```
+
+For detailed CoSec framework documentation and advanced configuration options, visit the [CoSec GitHub repository](https://github.com/Ahoo-Wang/CoSec).
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please see
-the [contributing guide](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) for more details.
+We welcome contributions! Please see our [contributing guide](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) for details on:
+
+- **Development Setup**: Getting started with the codebase
+- **Code Standards**: TypeScript, linting, and testing guidelines
+- **Pull Request Process**: How to submit changes
+- **Issue Reporting**: Bug reports and feature requests
+
+### Development Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Run linting and type checking
+pnpm lint
+pnpm typecheck
+
+# Run test suite
+pnpm test
+
+# Build package
+pnpm build
+```
 
 ## 📄 License
 
-Apache-2.0
+Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- [CoSec Framework](https://github.com/Ahoo-Wang/CoSec) - Enterprise authentication framework
+- [Fetcher HTTP Client](https://github.com/Ahoo-Wang/fetcher) - Modern TypeScript HTTP client
+- [JWT.io](https://jwt.io) - JWT token standard and tooling
 
 ---
 
 <p align="center">
-  Part of the <a href="https://github.com/Ahoo-Wang/fetcher">Fetcher</a> ecosystem
+  <strong>Part of the <a href="https://github.com/Ahoo-Wang/fetcher">Fetcher</a> ecosystem</strong>
+  <br>
+  <sub>Modern HTTP client libraries for TypeScript applications</sub>
 </p>