@dainprotocol/oauth2-token-manager 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,25 @@
 
 A powerful, storage-agnostic OAuth2 token management library built for scalable multi-system architectures. This library provides comprehensive token lifecycle management with pluggable storage adapters, built-in security features, and support for multiple OAuth2 providers.
 
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Granular API (Advanced)](#-granular-api-advanced)
+  - [Context-Aware Resolution](#context-aware-resolution)
+  - [User Management](#user-management)
+  - [Token Operations](#token-operations)
+  - [Bulk Operations](#bulk-operations)
+  - [System & Scope Management](#system--scope-management)
+- [Architecture](#-architecture)
+- [API Reference](#-api-reference)
+- [Storage Adapters](#storage-adapters)
+- [Provider Configuration](#provider-configuration)
+- [Advanced Features](#-advanced-features)
+- [Examples](#-examples)
+- [Production Deployment](#-production-deployment)
+
 ## 🚀 Features
 
 - **🔌 Storage Agnostic**: Use any storage backend (In-Memory, PostgreSQL, or build your own adapter)
@@ -12,6 +31,7 @@ A powerful, storage-agnostic OAuth2 token management library built for scalable
 - **👤 User Management**: Comprehensive user lifecycle with email/external ID support
 - **📧 Profile Integration**: Automatic profile fetching from OAuth providers
 - **🎯 Flexible Scoping**: Fine-grained permission management
+- **🎨 Default Configuration**: Automatic default system and scope creation
 - **💡 Developer Friendly**: Both context-managed and granular APIs
 - **🧪 Fully Tested**: Comprehensive test coverage with Vitest
 
@@ -26,6 +46,9 @@ npm install @dainprotocol/oauth2-token-manager
 ```bash
 # PostgreSQL adapter
 npm install @dainprotocol/oauth2-storage-postgres
+
+# Drizzle adapter (supports PostgreSQL, MySQL, SQLite)
+npm install @dainprotocol/oauth2-storage-drizzle
 ```
 
 ## 🚀 Quick Start
@@ -70,44 +93,219 @@ const { url, state } = await oauth.authorize({
 // Handle callback
 const result = await oauth.handleCallback(code, state);
 console.log('User authenticated:', result.userId);
+
+// === NEW: Simplified Granular API (V2) ===
+// Access tokens without specifying system/scope IDs
+const accessToken = await oauth.granularV2.getAccessToken({
+  email: 'user@example.com',
+  provider: 'google',
+});
 ```
 
-### Advanced Setup with Custom Storage
+## 🎯 Granular API (Advanced)
+
+The granular API (`oauth.granularV2`) provides full control over the token hierarchy with intelligent system and scope resolution. It's the recommended way to interact with tokens when you need fine-grained control.
+
+### Context-Aware Resolution
+
+The API follows this priority order for resolving system and scope:
+
+1. **Explicit parameters** - If you provide systemId/scopeId in the method call, those are used
+2. **Context from OAuth2Client** - If not provided, it checks the current context (useSystem/setDefaultScope)
+3. **Default system/scope** - If no context is set, it falls back to the default system and scope
 
 ```typescript
-import { OAuth2Client } from '@dainprotocol/oauth2-token-manager';
-import { PostgresStorageFactory } from '@dainprotocol/oauth2-storage-postgres';
+// === Context-Aware Usage ===
 
-// Custom storage adapter
-const storage = await PostgresStorageFactory.create({
-  host: 'localhost',
-  port: 5432,
-  username: 'oauth2_user',
-  password: 'secure_password',
-  database: 'oauth2_db',
+// Set context in main client
+await oauth.useSystem('production-system');
+oauth.setDefaultScope('api-access');
+
+// Granular V2 will now use this context automatically
+const user = await oauth.granularV2.getOrCreateUser({
+  email: 'user@example.com',
+  options: { metadata: { role: 'user' } },
+  // No need to specify systemId - uses 'production-system' from context
 });
 
-const oauth = new OAuth2Client({
-  storage,
-  providers: {
-    google: {
-      /* config */
-    },
-    github: {
-      /* config */
-    },
+// Token operations use the context scope
+const token = await oauth.granularV2.getAccessToken({
+  email: 'user@example.com',
+  provider: 'google',
+  // No need to specify scopeId - uses 'api-access' from context
+});
+
+// Override with explicit parameters when needed
+const differentToken = await oauth.granularV2.getAccessToken({
+  email: 'user@example.com',
+  provider: 'google',
+  systemId: 'another-system', // This takes precedence
+  scopeId: 'different-scope', // This takes precedence
+});
+```
+
+### User Management
+
+```typescript
+// Create or get users with optional system specification
+const user = await oauth.granularV2.getOrCreateUser({
+  email: 'user@example.com',
+  options: { metadata: { role: 'admin' } },
+  // systemId is optional - uses context or defaults
+});
+
+// Find users by various criteria
+const userByEmail = await oauth.granularV2.findUserByEmail({
+  email: 'user@example.com',
+});
+
+const userByExternalId = await oauth.granularV2.findUserByExternalId({
+  externalId: 'external-123',
+});
+
+// Get all users in a system
+const systemUsers = await oauth.granularV2.getUsersBySystem();
+// Or specify a different system
+const otherSystemUsers = await oauth.granularV2.getUsersBySystem('other-system-id');
+```
+
+### Token Operations
+
+```typescript
+// Save new tokens
+const savedToken = await oauth.granularV2.saveToken({
+  userId: user.id,
+  provider: 'google',
+  email: 'user@example.com',
+  token: oauthToken,
+  // systemId and scopeId are optional
+});
+
+// Query tokens with flexible parameters
+const userTokens = await oauth.granularV2.getTokens({
+  userId: user.id,
+});
+
+const providerTokens = await oauth.granularV2.getTokens({
+  userId: user.id,
+  provider: 'google',
+});
+
+const emailTokens = await oauth.granularV2.getTokens({
+  email: 'user@example.com',
+  // systemId resolved from context or defaults
+});
+
+// Get valid tokens with auto-refresh
+const validToken = await oauth.granularV2.getValidToken({
+  email: 'user@example.com',
+  provider: 'google',
+  options: {
+    autoRefresh: true,
+    refreshBuffer: 5, // Refresh 5 minutes before expiry
+  },
+});
+
+// Get access token directly
+const accessToken = await oauth.granularV2.getAccessToken({
+  userId: user.id,
+  provider: 'google',
+});
+
+// Execute with valid token
+await oauth.granularV2.withValidToken(
+  {
+    email: 'user@example.com',
+    provider: 'google',
   },
+  async (accessToken) => {
+    // Make API calls with the token
+    const response = await fetch('https://api.example.com/data', {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    return response.json();
+  },
+);
+```
+
+### Bulk Operations
+
+```typescript
+// Get all valid tokens for a user
+const allUserTokens = await oauth.granularV2.getAllValidTokens({
+  userId: user.id,
+  options: { autoRefresh: true },
+});
+
+// Get all valid tokens for an email
+const allEmailTokens = await oauth.granularV2.getAllValidTokens({
+  email: 'user@example.com',
+});
+
+// Filter by provider
+const googleTokens = await oauth.granularV2.getAllValidTokens({
+  email: 'user@example.com',
+  provider: 'google',
+});
+
+// Check token existence
+const hasToken = await oauth.granularV2.hasToken({
+  email: 'user@example.com',
+  provider: 'google',
+});
+
+// Delete tokens
+await oauth.granularV2.deleteTokens({
+  email: 'user@example.com',
+  provider: 'google',
+});
+
+// Delete all tokens for a user
+await oauth.granularV2.deleteTokens({
+  userId: user.id,
 });
+```
+
+### System & Scope Management
 
-// Create system and scopes
-const system = await oauth.createSystem('MyApp');
-const scope = await oauth.createScope('api-access', {
+```typescript
+// Get current defaults
+const defaultSystem = await oauth.granularV2.getSystem();
+const defaultScope = await oauth.granularV2.getScope();
+
+// Create new scope in current/default system
+const newScope = await oauth.granularV2.createScope({
+  name: 'api-access',
   type: 'access',
-  permissions: ['read:profile', 'write:data'],
+  permissions: ['read', 'write'],
   isolated: true,
 });
+
+// Create scope in specific system
+const anotherScope = await oauth.granularV2.createScope({
+  systemId: 'specific-system-id',
+  name: 'admin-access',
+  type: 'access',
+  permissions: ['*'],
+});
+
+// Get all scopes in current system
+const scopes = await oauth.granularV2.getScopesBySystem();
+
+// Initialize defaults explicitly if needed
+const { system, scope } = await oauth.granularV2.ensureDefaults();
 ```
 
+### Why Use Granular API?
+
+The granular API is ideal for:
+
+- **Single-system applications** - Simplified usage with automatic defaults
+- **Multi-tenant applications** - Easy context switching between systems
+- **Backend services** - Stateless operations with explicit parameters
+- **Complex token management** - Full control over token lifecycle
+- **Gradual migration** - Start simple, add complexity as needed
+
 ## 🏗️ Architecture
 
 ### Core Components
@@ -116,8 +314,8 @@ const scope = await oauth.createScope('api-access', {
 ┌─────────────────────────────────────────────────────────────┐
 │                     OAuth2Client                            │
 │  ┌─────────────────┐    ┌─────────────────────────────────┐ │
-│  │  Context API    │    │      Granular API              │ │
-│  │  (Simplified)   │    │  (Full Control)                │ │
+│  │  Context API    │    │    Granular API V2             │ │
+│  │  (Simplified)   │    │  (Full Control + Smart)        │ │
 │  └─────────────────┘    └─────────────────────────────────┘ │
 └─────────────────────────────────────────────────────────────┘
                               │
@@ -181,19 +379,67 @@ interface UserToken {
 5. **Email Uniqueness**: For the same provider, a user cannot have multiple tokens with the same email (validated via profile fetcher)
 6. **Cross-Provider Emails**: The same email can exist across different providers
 
+### Default System and Scope
+
+The library provides automatic initialization of a default system and scope for simplified usage:
+
+```typescript
+import {
+  DEFAULT_SYSTEM_NAME,
+  DEFAULT_SCOPE_NAME,
+  initializeDefaults,
+} from '@dainprotocol/oauth2-token-manager';
+
+// Automatic initialization
+const oauth = new OAuth2Client({
+  providers: {
+    /* ... */
+  },
+});
+
+// If no system/scope is set, they will be automatically initialized on first use
+const { url, state } = await oauth.authorize({ provider: 'google' });
+
+// Or manually initialize defaults
+await oauth.initializeDefaults();
+
+// Check if defaults exist
+const defaultSystem = await oauth.getDefaultSystem();
+const defaultScope = await oauth.getDefaultScope();
+
+// Default constants
+console.log(DEFAULT_SYSTEM_NAME); // 'oauth2-token-manager-default-system'
+console.log(DEFAULT_SCOPE_NAME); // 'oauth2-token-manager-default-scope'
+```
+
+The default system and scope are created with:
+
+- **System**: Name-based identification, includes metadata `{ isDefault: true }`
+- **Scope**: Type 'access', permissions ['read', 'write'], not isolated
+
 ## 📚 API Reference
 
 ### OAuth2Client
 
 The main client class providing both context-managed and granular APIs.
 
-#### Context-Managed API (Recommended)
+#### Context-Managed API (Recommended for Simple Use Cases)
 
 ```typescript
 // System management
 await oauth.createSystem('MyApp');
+await oauth.getOrCreateSystem('MyApp'); // Idempotent - returns existing if found
 await oauth.useSystem(systemId);
 
+// Scope management
+await oauth.createScope('api-access');
+await oauth.getOrCreateScope('api-access'); // Idempotent - returns existing if found
+
+// Default system/scope (automatic initialization)
+await oauth.initializeDefaults(); // Creates default system and scope if they don't exist
+const defaultSystem = await oauth.getDefaultSystem();
+const defaultScope = await oauth.getDefaultScope();
+
 // User management
 const user = await oauth.getOrCreateUser({ email: 'user@example.com' });
 await oauth.useUser(userId);
@@ -218,89 +464,6 @@ const allTokens = await oauth.getAllValidTokensForUser(userId);
 await oauth.revokeTokens('google'); // Revokes for current user/scope/provider
 ```
 
-#### Granular API (Advanced)
-
-The granular API provides full control over the token hierarchy:
-
-```typescript
-// === User-Centric Token Queries (Primary Key: User) ===
-
-// Get ALL tokens for a user across all scopes/providers
-const userTokens = await oauth.granular.getTokensByUser(userId);
-
-// Get tokens for user in specific scope (across all providers)
-const scopeTokens = await oauth.granular.getTokensByUserAndScope(userId, scopeId);
-
-// Get tokens for user with specific provider (across all scopes)
-const providerTokens = await oauth.granular.getTokensByUserAndProvider(userId, 'google');
-
-// Get tokens for user/scope/provider combination (can be multiple!)
-const specificTokens = await oauth.granular.getTokensByUserScopeProvider(userId, scopeId, 'google');
-
-// === Cross-User Queries (System/Scope Level) ===
-
-// Get all tokens in a scope across all users
-const scopeAllTokens = await oauth.granular.getTokensByScope(systemId, scopeId);
-
-// Get all tokens for a provider across all users in system
-const providerAllTokens = await oauth.granular.getTokensByProvider(systemId, 'google');
-
-// Get all tokens in a system
-const systemTokens = await oauth.granular.getTokensBySystem(systemId);
-
-// === Email-Based Queries ===
-
-// Find tokens by email (cross-user, cross-provider)
-const emailTokens = await oauth.granular.findTokensByEmail('user@example.com', systemId);
-
-// Find tokens by email in specific scope
-const emailScopeTokens = await oauth.granular.findTokensByEmailAndScope(
-  'user@example.com',
-  systemId,
-  scopeId,
-);
-
-// Find tokens by email for specific provider
-const emailProviderTokens = await oauth.granular.findTokensByEmailAndProvider(
-  'user@example.com',
-  systemId,
-  'google',
-);
-
-// Find specific token by email/scope/provider (returns single token or null)
-const specificToken = await oauth.granular.findTokenByEmailScopeProvider(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-);
-
-// === Token Operations ===
-
-// Get valid token for user (auto-refresh, takes first if multiple exist)
-const validToken = await oauth.granular.getValidTokenForUser(userId, scopeId, 'google');
-
-// Get access token for user (convenience method)
-const accessToken = await oauth.granular.getAccessTokenForUser(userId, scopeId, 'google');
-
-// Save new token for user
-const savedToken = await oauth.granular.saveTokenForUser(
-  userId,
-  systemId,
-  scopeId,
-  'google',
-  'user@example.com',
-  oauthToken,
-);
-
-// === Token Management ===
-
-// Delete tokens by different criteria
-await oauth.granular.deleteTokensByUser(userId); // All tokens for user
-await oauth.granular.deleteTokensByUserAndScope(userId, scopeId); // User's tokens in scope
-await oauth.granular.deleteTokensByUserAndProvider(userId, 'google'); // User's tokens for provider
-```
-
 ### Storage Adapters
 
 #### Built-in Memory Adapter
@@ -327,18 +490,77 @@ const storage = await PostgresStorageFactory.create({
 });
 ```
 
+#### Drizzle Adapter (Multi-Database)
+
+```typescript
+import { DrizzleStorageFactory } from '@dainprotocol/oauth2-storage-drizzle';
+
+// PostgreSQL
+const pgStorage = await DrizzleStorageFactory.create({
+  type: 'postgresql',
+  config: {
+    host: 'localhost',
+    port: 5432,
+    user: 'oauth2_user',
+    password: 'password',
+    database: 'oauth2_db',
+  },
+});
+
+// MySQL
+const mysqlStorage = await DrizzleStorageFactory.create({
+  type: 'mysql',
+  config: {
+    host: 'localhost',
+    port: 3306,
+    user: 'oauth2_user',
+    password: 'password',
+    database: 'oauth2_db',
+  },
+});
+
+// SQLite
+const sqliteStorage = await DrizzleStorageFactory.create({
+  type: 'sqlite',
+  config: {
+    filename: './oauth2.db',
+  },
+});
+```
+
 #### Custom Storage Adapter
 
 ```typescript
 import { StorageAdapter } from '@dainprotocol/oauth2-token-manager';
 
 class MyCustomAdapter implements StorageAdapter {
+  // System operations
   async createSystem(system) {
     /* implement */
   }
+  async getOrCreateSystem(system) {
+    // Find by name, create if not exists
+    /* implement */
+  }
   async getSystem(id) {
     /* implement */
   }
+
+  // Scope operations
+  async createScope(scope) {
+    /* implement */
+  }
+  async getOrCreateScope(scope) {
+    // Find by systemId + name, create if not exists
+    /* implement */
+  }
+
+  // User operations
+  async getOrCreateUser(input) {
+    // Find by email or externalId, create if not exists
+    /* implement */
+  }
+
   // ... implement all required methods
 }
 ```
@@ -398,64 +620,6 @@ class MyCustomAdapter implements StorageAdapter {
 }
 ```
 
-#### Google OAuth2 with Offline Access
-
-```typescript
-const oauth = new OAuth2Client({
-  providers: {
-    google: {
-      clientId: 'your-client-id',
-      clientSecret: 'your-client-secret',
-      redirectUri: 'http://localhost:3000/auth/callback',
-      scopes: ['profile', 'email'],
-      // Override default offline access parameters
-      extraAuthParams: {
-        access_type: 'offline',     // Request refresh token
-        prompt: 'consent',          // Force consent screen
-        include_granted_scopes: 'true'  // Include previously granted scopes
-      }
-    }
-  }
-});
-
-// The library automatically handles refresh tokens
-const token = await oauth.getAccessToken('google', {
-  autoRefresh: true,
-  refreshBuffer: 5  // Refresh 5 minutes before expiry
-});
-```
-
-#### Customizing Authorization Parameters
-
-Each provider supports customization through `extraAuthParams` and `additionalParams`:
-
-```typescript
-{
-  google: {
-    // ... other config ...
-    extraAuthParams: {
-      access_type: 'offline',    // For refresh tokens
-      prompt: 'select_account',  // Force account selection
-      hd: 'yourdomain.com'      // Limit to specific Google Workspace domain
-    }
-  },
-  microsoft: {
-    // ... other config ...
-    extraAuthParams: {
-      prompt: 'select_account',
-      domain_hint: 'yourdomain.com'
-    }
-  }
-}
-```
-
-Available parameters for Google OAuth2:
-- `access_type`: 'online' (default) or 'offline' (for refresh tokens)
-- `prompt`: 'none', 'consent', 'select_account'
-- `include_granted_scopes`: 'true' or 'false'
-- `login_hint`: User's email address
-- `hd`: Google Workspace domain restriction
-
 ## 🔧 Advanced Features
 
 ### Token Auto-Refresh
@@ -463,7 +627,7 @@ Available parameters for Google OAuth2:
 ```typescript
 const accessToken = await oauth.getAccessToken('google', {
   autoRefresh: true,
-  refreshBuffer: 5, // Refresh 5 minutes before expiry
+  refreshBuffer: 10, // Refresh early to avoid expiry
   expirationBuffer: 30, // Consider expired 30 seconds early
 });
 ```
@@ -480,86 +644,6 @@ const result = await oauth.handleCallback(code, state, {
 });
 ```
 
-### Email-Based Operations
-
-```typescript
-// Get all valid tokens for an email across all providers in a system
-// Note: This returns an array since one email can have tokens from multiple providers
-const emailTokens = await oauth.getAllValidTokensForEmail('user@example.com', systemId);
-// Returns: { provider: string; scopeId: string; token: OAuth2Token; userToken: UserToken }[]
-
-// Get specific token by email (returns single token or null)
-// This enforces the email uniqueness rule within provider/scope
-const token = await oauth.getTokenForEmail('user@example.com', systemId, scopeId, 'google');
-
-// Get valid token for email with auto-refresh
-const validToken = await oauth.getValidTokenForEmail(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-  { autoRefresh: true },
-);
-
-// Get access token for email
-const accessToken = await oauth.getAccessTokenForEmail(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-);
-
-// Execute with valid token for email
-await oauth.withValidTokenForEmail(
-  'user@example.com',
-  systemId,
-  scopeId,
-  'google',
-  async (accessToken) => {
-    console.log('Using token for email:', accessToken);
-  },
-);
-
-// Check if email has token for specific provider/scope
-const hasToken = await oauth.hasTokenForEmail('user@example.com', systemId, scopeId, 'google');
-
-// Revoke tokens for email
-await oauth.revokeTokensForEmail('user@example.com', systemId, scopeId, 'google');
-```
-
-### User-Centric Operations (Stateless)
-
-For backend APIs where you have explicit user IDs:
-
-```typescript
-// Get access token for specific user/scope/provider
-// Note: Takes the first (most recent) token if multiple exist
-const accessToken = await oauth.getAccessTokenForUser(userId, systemId, scopeId, 'google', {
-  autoRefresh: true,
-});
-
-// Execute with valid token for specific user
-await oauth.withValidTokenForUser(userId, systemId, scopeId, 'google', async (accessToken) => {
-  // Make API calls with the token
-  return apiResponse;
-});
-
-// Get all valid tokens for a user with auto-refresh
-const userTokens = await oauth.getAllValidTokensForUser(userId, {
-  autoRefresh: true,
-  refreshBuffer: 5, // Refresh 5 minutes before expiry
-});
-
-// Check if user has tokens for specific provider/scope
-const hasToken = await oauth.hasTokenForUser(userId, systemId, scopeId, 'google');
-
-// Get user token entity (includes metadata)
-const userToken = await oauth.getUserTokenForUser(userId, systemId, scopeId, 'google');
-
-// Revoke specific tokens
-await oauth.revokeTokensForUser(userId, systemId, scopeId, 'google');
-```
-
 ### PKCE Support
 
 ```typescript
@@ -582,52 +666,25 @@ const isExpired = oauth.isTokenExpired(token, {
 const validToken = await oauth.ensureValidToken('google');
 ```
 
-## 🔒 Security Features
-
-### State Management
-
-- Cryptographically secure state generation
-- Automatic state validation and cleanup
-- Configurable state expiration
-
-### PKCE (Proof Key for Code Exchange)
-
-- Built-in PKCE support for public clients
-- Automatic code verifier generation
-- Enhanced security for mobile and SPA applications
-
-### Token Encryption
-
-- Secure token storage with optional encryption
-- Configurable seal keys for sensitive data
-- Protection against token theft
-
-### Email Validation
-
-- Automatic email conflict detection
-- Profile-based user validation
-- Cross-provider email consistency
-
-## 🧪 Testing
-
-The library includes comprehensive tests using Vitest:
+## 🏢 Examples
 
-```bash
-# Run tests
-npm test
+### Multi-Tenant Application
 
-# Run tests with UI
-npm run test:ui
+```typescript
+// Each tenant gets their own system
+const tenantSystem = await oauth.createSystem(`Tenant-${tenantId}`);
 
-# Run tests with coverage
-npm run test:coverage
+// Tenant-specific user management
+await oauth.useSystem(tenantSystem.id);
+const tenantUser = await oauth.getOrCreateUser({
+  email: userEmail,
+  metadata: { tenantId, role: 'admin' },
+});
 
-# Watch mode
-npm run test:watch
+// Tenant-isolated tokens
+const tokens = await oauth.granularV2.getTokens({ systemId: tenantSystem.id });
 ```
 
-## 🏢 Multi-System Examples
-
 ### SaaS Platform with Multiple Apps
 
 ```typescript
@@ -659,23 +716,6 @@ const { url } = await oauth.authorize({
 });
 ```
 
-### Multi-Tenant Application
-
-```typescript
-// Each tenant gets their own system
-const tenantSystem = await oauth.createSystem(`Tenant-${tenantId}`);
-
-// Tenant-specific user management
-await oauth.useSystem(tenantSystem.id);
-const tenantUser = await oauth.getOrCreateUser({
-  email: userEmail,
-  metadata: { tenantId, role: 'admin' },
-});
-
-// Tenant-isolated tokens
-const tokens = await oauth.granular.getTokensBySystem(tenantSystem.id);
-```
-
 ## 🚀 Production Deployment
 
 ### Environment Configuration
@@ -743,6 +783,50 @@ try {
 }
 ```
 
+## 🔒 Security Features
+
+### State Management
+
+- Cryptographically secure state generation
+- Automatic state validation and cleanup
+- Configurable state expiration
+
+### PKCE (Proof Key for Code Exchange)
+
+- Built-in PKCE support for public clients
+- Automatic code verifier generation
+- Enhanced security for mobile and SPA applications
+
+### Token Encryption
+
+- Secure token storage with optional encryption
+- Configurable seal keys for sensitive data
+- Protection against token theft
+
+### Email Validation
+
+- Automatic email conflict detection
+- Profile-based user validation
+- Cross-provider email consistency
+
+## 🧪 Testing
+
+The library includes comprehensive tests using Vitest:
+
+```bash
+# Run tests
+npm test
+
+# Run tests with UI
+npm run test:ui
+
+# Run tests with coverage
+npm run test:coverage
+
+# Watch mode
+npm run test:watch
+```
+
 ## 🤝 Contributing
 
 1. Fork the repository
@@ -777,10 +861,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🙋‍♂️ Support
 
-- 📚 [Documentation](https://github.com/blureffect/oauth2-token-manager#readme)
-- 🐛 [Issue Tracker](https://github.com/blureffect/oauth2-token-manager/issues)
-- 💬 [Discussions](https://github.com/blureffect/oauth2-token-manager/discussions)
-
-## 🏆 Credits
-
-Created with ❤️ by [Blureffect](https://blureffect.co)
+- 📚 [Documentation](https://github.com/dainprotocol/oauth2-token-manager#readme)
+- 🐛 [Issue Tracker](https://github.com/dainprotocol/oauth2-token-manager/issues)
+- 💬 [Discussions](https://github.com/dainprotocol/oauth2-token-manager/discussions)