@dainprotocol/oauth2-token-manager 0.1.0

package/README.md

@@ -0,0 +1,786 @@
+# OAuth2 Token Manager
+
+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.
+
+## 🚀 Features
+
+- **🔌 Storage Agnostic**: Use any storage backend (In-Memory, PostgreSQL, or build your own adapter)
+- **🏢 Multi-System Support**: Manage tokens across multiple applications/systems
+- **🔐 Advanced Security**: PKCE support, state validation, token encryption
+- **⚡ High Performance**: Efficient token validation, caching, and refresh strategies
+- **🔄 Auto-Refresh**: Automatic token refresh with configurable buffers
+- **👤 User Management**: Comprehensive user lifecycle with email/external ID support
+- **📧 Profile Integration**: Automatic profile fetching from OAuth providers
+- **🎯 Flexible Scoping**: Fine-grained permission management
+- **💡 Developer Friendly**: Both context-managed and granular APIs
+- **🧪 Fully Tested**: Comprehensive test coverage with Vitest
+
+## 📦 Installation
+
+```bash
+npm install @dainprotocol/oauth2-token-manager
+```
+
+### Storage Adapters
+
+```bash
+# PostgreSQL adapter
+npm install @dainprotocol/oauth2-storage-postgres
+```
+
+## 🚀 Quick Start
+
+### Simple Setup
+
+```typescript
+import { OAuth2Client } from '@dainprotocol/oauth2-token-manager';
+
+// Quick setup for common use cases
+const oauth = await OAuth2Client.quickSetup('MyApp', {
+  google: {
+    clientId: 'your-google-client-id',
+    clientSecret: 'your-google-client-secret',
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    redirectUri: 'http://localhost:3000/auth/callback',
+    scopes: ['profile', 'email'],
+  },
+  github: {
+    clientId: 'your-github-client-id',
+    clientSecret: 'your-github-client-secret',
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    redirectUri: 'http://localhost:3000/auth/callback',
+    scopes: ['user:email'],
+  },
+});
+
+// Create or get a user
+const user = await oauth.getOrCreateUser({
+  email: 'user@example.com',
+  metadata: { role: 'user' },
+});
+
+// Start OAuth flow
+const { url, state } = await oauth.authorize({
+  provider: 'google',
+  scopes: ['profile', 'email'],
+});
+
+// Handle callback
+const result = await oauth.handleCallback(code, state);
+console.log('User authenticated:', result.userId);
+```
+
+### Advanced Setup with Custom Storage
+
+```typescript
+import { OAuth2Client } from '@dainprotocol/oauth2-token-manager';
+import { PostgresStorageFactory } from '@dainprotocol/oauth2-storage-postgres';
+
+// Custom storage adapter
+const storage = await PostgresStorageFactory.create({
+  host: 'localhost',
+  port: 5432,
+  username: 'oauth2_user',
+  password: 'secure_password',
+  database: 'oauth2_db',
+});
+
+const oauth = new OAuth2Client({
+  storage,
+  providers: {
+    google: {
+      /* config */
+    },
+    github: {
+      /* config */
+    },
+  },
+});
+
+// Create system and scopes
+const system = await oauth.createSystem('MyApp');
+const scope = await oauth.createScope('api-access', {
+  type: 'access',
+  permissions: ['read:profile', 'write:data'],
+  isolated: true,
+});
+```
+
+## 🏗️ Architecture
+
+### Core Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     OAuth2Client                            │
+│  ┌─────────────────┐    ┌─────────────────────────────────┐ │
+│  │  Context API    │    │      Granular API              │ │
+│  │  (Simplified)   │    │  (Full Control)                │ │
+│  └─────────────────┘    └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+    ┌─────────▼────────┐ ┌───▼────────┐ ┌───▼─────────┐
+    │   Providers      │ │  Storage   │ │   Profile   │
+    │   (OAuth2)       │ │  Adapter   │ │  Fetchers   │
+    └──────────────────┘ └────────────┘ └─────────────┘
+```
+
+### Data Model & Token Hierarchy
+
+**Important**: Users can have multiple tokens for the same provider within the same scope. This allows for scenarios like different email accounts or token refresh cycles.
+
+```typescript
+// Systems: Top-level applications/services
+interface System {
+  id: string;
+  name: string;
+  description?: string;
+  scopes: Scope[];
+  metadata?: Record<string, any>;
+}
+
+// Scopes: Permission boundaries within systems
+interface Scope {
+  id: string;
+  systemId: string;
+  name: string;
+  type: 'authentication' | 'access' | 'custom';
+  permissions: string[];
+  isolated: boolean; // Whether tokens are isolated to this scope
+}
+
+// Users: Identity within a system
+interface User {
+  id: string;
+  systemId: string;
+  metadata?: Record<string, any>;
+}
+
+// User Tokens: OAuth2 tokens tied to user/system/scope/provider
+// A user can have MULTIPLE tokens for the same provider/scope combination
+interface UserToken {
+  id: string;
+  userId: string;
+  systemId: string;
+  scopeId: string;
+  provider: string;
+  token: OAuth2Token;
+}
+```
+
+### Token Hierarchy Rules
+
+1. **One User** belongs to **One System**
+2. **One User** can have tokens in **Multiple Scopes** within their system
+3. **One User** in **One Scope** can have tokens from **Multiple Providers**
+4. **One User** in **One Scope** from **One Provider** can have **Multiple Tokens**
+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
+
+## 📚 API Reference
+
+### OAuth2Client
+
+The main client class providing both context-managed and granular APIs.
+
+#### Context-Managed API (Recommended)
+
+```typescript
+// System management
+await oauth.createSystem('MyApp');
+await oauth.useSystem(systemId);
+
+// User management
+const user = await oauth.getOrCreateUser({ email: 'user@example.com' });
+await oauth.useUser(userId);
+
+// Authorization flow
+const { url, state } = await oauth.authorize({ provider: 'google' });
+const result = await oauth.handleCallback(code, state);
+
+// Token operations (uses current context + default scope)
+// Note: When multiple tokens exist, these methods use the first (most recent) token
+const accessToken = await oauth.getAccessToken('google');
+const validToken = await oauth.ensureValidToken('google');
+
+// Get all user tokens with auto-refresh (for current user)
+const userTokens = await oauth.getUserTokens();
+
+// Get all valid tokens for a specific user
+const allTokens = await oauth.getAllValidTokensForUser(userId);
+// Returns: { provider: string; scopeId: string; token: OAuth2Token; userToken: UserToken }[]
+
+// Revoke tokens (uses current context)
+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
+
+```typescript
+import { InMemoryStorageAdapter } from '@dainprotocol/oauth2-token-manager';
+
+const storage = new InMemoryStorageAdapter();
+const oauth = new OAuth2Client({ storage });
+```
+
+#### PostgreSQL Adapter
+
+```typescript
+import { PostgresStorageFactory } from '@dainprotocol/oauth2-storage-postgres';
+
+const storage = await PostgresStorageFactory.create({
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || '5432'),
+  username: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_NAME,
+  ssl: process.env.NODE_ENV === 'production',
+});
+```
+
+#### Custom Storage Adapter
+
+```typescript
+import { StorageAdapter } from '@dainprotocol/oauth2-token-manager';
+
+class MyCustomAdapter implements StorageAdapter {
+  async createSystem(system) {
+    /* implement */
+  }
+  async getSystem(id) {
+    /* implement */
+  }
+  // ... implement all required methods
+}
+```
+
+### Provider Configuration
+
+#### Google OAuth2
+
+```typescript
+{
+  google: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    redirectUri: 'http://localhost:3000/auth/callback',
+    scopes: ['profile', 'email'],
+    profileUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
+    usePKCE: true, // Recommended for security
+  }
+}
+```
+
+#### GitHub OAuth2
+
+```typescript
+{
+  github: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    redirectUri: 'http://localhost:3000/auth/callback',
+    scopes: ['user:email'],
+    profileUrl: 'https://api.github.com/user',
+  }
+}
+```
+
+#### Generic Provider
+
+```typescript
+{
+  custom: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret',
+    authorizationUrl: 'https://provider.com/oauth/authorize',
+    tokenUrl: 'https://provider.com/oauth/token',
+    redirectUri: 'http://localhost:3000/auth/callback',
+    scopes: ['read', 'write'],
+    profileUrl: 'https://provider.com/api/user',
+    additionalParams: {
+      audience: 'api.example.com'
+    },
+    responseRootKey: 'data' // For nested responses
+  }
+}
+```
+
+#### 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
+
+```typescript
+const accessToken = await oauth.getAccessToken('google', {
+  autoRefresh: true,
+  refreshBuffer: 5, // Refresh 5 minutes before expiry
+  expirationBuffer: 30, // Consider expired 30 seconds early
+});
+```
+
+### Profile-Based Token Management
+
+```typescript
+const result = await oauth.handleCallback(code, state, {
+  profileOptions: {
+    checkProfileEmail: true, // Fetch and check email conflicts
+    replaceConflictingTokens: true, // Replace existing tokens with same email
+    mergeUserData: true, // Merge profile data into user metadata
+  },
+});
+```
+
+### 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
+// Enable PKCE for enhanced security
+const { url, state } = await oauth.authorize({
+  provider: 'google',
+  usePKCE: true, // Enables PKCE flow
+});
+```
+
+### Token Validation
+
+```typescript
+// Check if token is expired
+const isExpired = oauth.isTokenExpired(token, {
+  expirationBuffer: 60, // Consider expired 60 seconds early
+});
+
+// Ensure valid token (auto-refresh if needed)
+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:
+
+```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
+```
+
+## 🏢 Multi-System Examples
+
+### SaaS Platform with Multiple Apps
+
+```typescript
+// Create systems for different applications
+const crmSystem = await oauth.createSystem('CRM App');
+const analyticsSystem = await oauth.createSystem('Analytics Dashboard');
+
+// Create scopes for different access levels
+await oauth.useSystem(crmSystem.id);
+const readScope = await oauth.createScope('read-only', {
+  type: 'access',
+  permissions: ['read:contacts', 'read:deals'],
+  isolated: true,
+});
+
+const adminScope = await oauth.createScope('admin', {
+  type: 'access',
+  permissions: ['*'],
+  isolated: true,
+});
+
+// Users can have different permissions per system
+const user = await oauth.getOrCreateUser({ email: 'user@company.com' });
+
+// Authorize for specific system/scope
+const { url } = await oauth.authorize({
+  provider: 'google',
+  scopes: ['profile', 'email'],
+});
+```
+
+### 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
+
+```typescript
+const oauth = new OAuth2Client({
+  storage: await PostgresStorageFactory.create({
+    host: process.env.DB_HOST,
+    port: parseInt(process.env.DB_PORT || '5432'),
+    username: process.env.DB_USER,
+    password: process.env.DB_PASSWORD,
+    database: process.env.DB_NAME,
+    ssl: {
+      rejectUnauthorized: process.env.NODE_ENV === 'production',
+    },
+    poolSize: 20,
+    logging: process.env.NODE_ENV === 'development',
+  }),
+  sealKey: process.env.OAUTH2_SEAL_KEY, // For token encryption
+  providers: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      redirectUri: process.env.GOOGLE_REDIRECT_URI,
+      // ... other config
+    },
+  },
+});
+```
+
+### Performance Optimization
+
+```typescript
+// Use token caching for high-traffic scenarios
+const accessToken = await oauth.getAccessToken('google', {
+  autoRefresh: true,
+  refreshBuffer: 10, // Refresh early to avoid expiry
+});
+
+// Batch operations for efficiency
+const allTokens = await oauth.getAllValidTokensForUser(userId);
+
+// Clean up expired states regularly
+setInterval(
+  async () => {
+    await oauth.cleanup(10 * 60 * 1000); // 10 minutes
+  },
+  5 * 60 * 1000,
+); // Every 5 minutes
+```
+
+### Error Handling
+
+```typescript
+try {
+  const token = await oauth.getAccessToken('google');
+} catch (error) {
+  if (error.message.includes('Token expired')) {
+    // Handle token expiry
+    const { url } = await oauth.authorize({ provider: 'google' });
+    // Redirect to re-authorization
+  } else if (error.message.includes('Provider not found')) {
+    // Handle missing provider
+  }
+}
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Build the project
+npm run build
+
+# Lint and format
+npm run lint:fix
+npm run format
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙋‍♂️ 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)