@nextsparkjs/plugin-social-media-publisher 0.1.0-beta.1

package/docs/02-core-features/03-token-management.md

@@ -0,0 +1,661 @@
+# Token Management
+
+## Overview
+
+The Social Media Publisher plugin implements a comprehensive token management system that ensures OAuth tokens are securely encrypted, automatically refreshed, and never exposed. This system is critical for maintaining continuous publishing capabilities without user intervention.
+
+**Key Features:**
+- AES-256-GCM encryption for all tokens
+- Automatic refresh before expiration
+- Versioned encryption keys
+- Immutable audit trail
+- Zero downtime token rotation
+
+## Token Lifecycle
+
+### 1. Token Acquisition (OAuth)
+
+**When:** User connects account via OAuth  
+**Process:** Facebook returns access token  
+**Token Type:** Long-lived (60 days)
+
+```typescript
+// OAuth callback receives token
+const { access_token, expires_in } = await exchangeCodeForToken(authCode)
+
+// Calculate expiration
+const expiresAt = new Date(Date.now() + expires_in * 1000)
+// Result: 60 days from now
+```
+
+### 2. Token Encryption
+
+**When:** Immediately after acquisition  
+**Process:** Encrypt with AES-256-GCM  
+**Storage Format:** `encrypted:iv:keyId`
+
+```typescript
+import { TokenEncryption } from '@/core/lib/oauth/encryption'
+
+// Plain text token from Facebook
+const accessToken = "EAABwzLixnjYBAA..."
+
+// Encrypt
+const { encrypted, iv, keyId } = await TokenEncryption.encrypt(accessToken)
+
+// Format for storage
+const storedToken = `${encrypted}:${iv}:${keyId}`
+// Example: a3f9b2c8...d4e5:9f7e3a...b5c2:key_2024_01
+```
+
+**Encryption Details:**
+- **Algorithm:** AES-256-GCM (Advanced Encryption Standard)
+- **Key Size:** 256 bits (32 bytes)
+- **IV (Initialization Vector):** 96 bits, unique per token
+- **Authentication Tag:** 128 bits (prevents tampering)
+- **Key Derivation:** Direct from `OAUTH_ENCRYPTION_KEY` environment variable
+
+### 3. Token Storage
+
+**Where:** `clients_social_platforms` table  
+**Column:** `accessToken` (TEXT)  
+**Format:** `encrypted:iv:keyId`
+
+```sql
+INSERT INTO "clients_social_platforms" (
+  "parentId",
+  platform,
+  "platformAccountId",
+  "platformAccountName",
+  "accessToken",
+  "tokenExpiresAt"
+) VALUES (
+  '550e8400-e29b-41d4-a716-446655440000',
+  'instagram_business',
+  '17841401234567890',
+  '@brandname',
+  'a3f9b2c8d1e3f4a5b6c7d8e9f0a1b2c3:9f7e3ab5c2:key_2024_01',
+  '2024-03-15 10:30:00+00'
+);
+```
+
+**Security:**
+- ✅ Never stored in plain text
+- ✅ Unique IV per token (prevents pattern analysis)
+- ✅ Key versioning (allows key rotation)
+- ✅ At-rest encryption
+- ✅ RLS policies restrict access
+
+### 4. Token Decryption (On Use)
+
+**When:** Before making API calls  
+**Process:** Decrypt in memory only  
+**Lifetime:** Exists only during request
+
+```typescript
+// Read encrypted token from database
+const account = await query(`
+  SELECT "accessToken" FROM "clients_social_platforms"
+  WHERE id = $1
+`, [accountId])
+
+// Decrypt
+const [encrypted, iv, keyId] = account.accessToken.split(':')
+const decryptedToken = await TokenEncryption.decrypt(encrypted, iv, keyId)
+
+// Use for API call
+await InstagramAPI.publishPhoto({
+  accessToken: decryptedToken,  // Used here
+  // ...
+})
+
+// Token discarded after request (not stored)
+```
+
+**Security:**
+- ✅ Decrypted only when needed
+- ✅ Never logged
+- ✅ Never sent to client
+- ✅ Exists only in server memory
+- ✅ Garbage collected after use
+
+### 5. Token Refresh
+
+**When:** < 10 minutes until expiration  
+**Trigger:** Automatic before publish operation  
+**Process:** Exchange old token for new long-lived token
+
+```typescript
+// Check if refresh needed
+const now = new Date()
+const expiresAt = new Date(account.tokenExpiresAt)
+const minutesUntilExpiry = (expiresAt.getTime() - now.getTime()) / (1000 * 60)
+
+if (minutesUntilExpiry < 10) {
+  console.log('🔄 Token expiring soon, refreshing...')
+  
+  // Call Meta token exchange endpoint
+  const response = await fetch(
+    `https://graph.facebook.com/v18.0/oauth/access_token?` +
+    `grant_type=fb_exchange_token&` +
+    `client_id=${FACEBOOK_CLIENT_ID}&` +
+    `client_secret=${FACEBOOK_CLIENT_SECRET}&` +
+    `fb_exchange_token=${currentToken}`
+  )
+  
+  const { access_token, expires_in } = await response.json()
+  
+  // Re-encrypt new token
+  const { encrypted, iv, keyId } = await TokenEncryption.encrypt(access_token)
+  const newEncryptedToken = `${encrypted}:${iv}:${keyId}`
+  const newExpiresAt = new Date(Date.now() + expires_in * 1000)
+  
+  // Update database
+  await query(`
+    UPDATE "clients_social_platforms"
+    SET "accessToken" = $1,
+        "tokenExpiresAt" = $2,
+        "updatedAt" = NOW()
+    WHERE id = $3
+  `, [newEncryptedToken, newExpiresAt, accountId])
+  
+  // Create audit log
+  await query(`
+    INSERT INTO "audit_logs" ("userId", "accountId", action, details)
+    VALUES ($1, $2, 'token_refreshed', $3)
+  `, [userId, accountId, { oldExpiry: expiresAt, newExpiry: newExpiresAt }])
+  
+  console.log('✅ Token refreshed successfully')
+}
+```
+
+### 6. Token Expiration
+
+**Expiration Time:** 60 days (5,184,000 seconds)  
+**Warning Threshold:** 10 minutes before expiration  
+**Action:** Automatic refresh or require reconnection
+
+**If Refresh Fails:**
+```typescript
+// Publish endpoint blocks operation
+return NextResponse.json({
+  error: 'Token expired and refresh failed',
+  details: 'OAuth token could not be refreshed',
+  suggestion: 'Please reconnect your social media account'
+}, { status: 403 })
+```
+
+**User Must:**
+1. Go to client social platforms page
+2. Disconnect expired account
+3. Reconnect via OAuth
+4. New 60-day token issued
+
+## Token Encryption Deep Dive
+
+### AES-256-GCM Algorithm
+
+**Why GCM (Galois/Counter Mode)?**
+- ✅ **Authenticated Encryption** - Prevents tampering
+- ✅ **Performance** - Faster than CBC mode
+- ✅ **Parallel Processing** - Can decrypt in parallel
+- ✅ **NIST Approved** - Industry standard
+
+**Encryption Process:**
+```typescript
+import crypto from 'crypto'
+
+export class TokenEncryption {
+  static async encrypt(plainText: string): Promise<{
+    encrypted: string
+    iv: string
+    keyId: string
+  }> {
+    // Get encryption key from environment
+    const encryptionKey = Buffer.from(process.env.OAUTH_ENCRYPTION_KEY!, 'hex')
+    
+    // Generate random IV (96 bits)
+    const iv = crypto.randomBytes(12)
+    
+    // Create cipher
+    const cipher = crypto.createCipheriv('aes-256-gcm', encryptionKey, iv)
+    
+    // Encrypt
+    let encrypted = cipher.update(plainText, 'utf8', 'hex')
+    encrypted += cipher.final('hex')
+    
+    // Get authentication tag
+    const authTag = cipher.getAuthTag()
+    
+    // Combine encrypted + authTag
+    const combined = encrypted + authTag.toString('hex')
+    
+    return {
+      encrypted: combined,
+      iv: iv.toString('hex'),
+      keyId: 'key_2024_01'  // Version identifier
+    }
+  }
+  
+  static async decrypt(
+    encryptedWithTag: string,
+    ivHex: string,
+    keyId: string
+  ): Promise<string> {
+    // Get encryption key
+    const encryptionKey = Buffer.from(process.env.OAUTH_ENCRYPTION_KEY!, 'hex')
+    
+    // Separate encrypted data and auth tag
+    const authTag = Buffer.from(encryptedWithTag.slice(-32), 'hex')
+    const encrypted = encryptedWithTag.slice(0, -32)
+    
+    // Create decipher
+    const decipher = crypto.createDecipheriv(
+      'aes-256-gcm',
+      encryptionKey,
+      Buffer.from(ivHex, 'hex')
+    )
+    
+    // Set auth tag
+    decipher.setAuthTag(authTag)
+    
+    // Decrypt
+    let decrypted = decipher.update(encrypted, 'hex', 'utf8')
+    decrypted += decipher.final('utf8')
+    
+    return decrypted
+  }
+}
+```
+
+### Token Format Breakdown
+
+```
+Format: encrypted:iv:keyId
+
+Example:
+a3f9b2c8d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9:9f7e3ab5c2d4e6:key_2024_01
+
+Part 1: encrypted (variable length)
+  - Encrypted token + authentication tag
+  - Hex encoded
+  - Length depends on token length
+
+Part 2: iv (24 hex characters)
+  - Initialization Vector (96 bits)
+  - Unique per encryption
+  - Required for decryption
+
+Part 3: keyId (version identifier)
+  - Identifies which encryption key was used
+  - Allows key rotation
+  - Example: key_2024_01, key_2024_02
+```
+
+## Token Refresh Mechanism
+
+### Refresh Triggers
+
+**1. Pre-Publish Check (Primary)**
+```typescript
+// Every publish operation checks token expiration
+if (minutesUntilExpiry < 10) {
+  await refreshToken()
+}
+```
+
+**2. Scheduled Cron Job (Recommended - Not Implemented)**
+```typescript
+// Run daily at 2 AM
+// Refresh all tokens expiring within 7 days
+async function refreshExpiringTokens() {
+  const expiringAccounts = await query(`
+    SELECT * FROM "clients_social_platforms"
+    WHERE "tokenExpiresAt" < NOW() + INTERVAL '7 days'
+    AND "isActive" = true
+  `)
+  
+  for (const account of expiringAccounts) {
+    await refreshAccountToken(account.id)
+  }
+}
+```
+
+### Meta Token Exchange API
+
+**Endpoint:**
+```
+GET https://graph.facebook.com/v18.0/oauth/access_token
+```
+
+**Parameters:**
+```typescript
+{
+  grant_type: 'fb_exchange_token',
+  client_id: FACEBOOK_CLIENT_ID,
+  client_secret: FACEBOOK_CLIENT_SECRET,
+  fb_exchange_token: currentToken  // Old token
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "EAABwzLixnjY...",  // New token
+  "token_type": "bearer",
+  "expires_in": 5184000  // 60 days (seconds)
+}
+```
+
+**Token Characteristics:**
+- **Old Token:** Remains valid for ~24 hours after exchange
+- **New Token:** Valid for 60 days from exchange
+- **Limit:** Can exchange once per day per token
+- **Rate Limit:** Subject to app rate limits
+
+### Refresh Threshold Configuration
+
+**Current Setting:** 10 minutes
+
+**Why 10 Minutes?**
+- ✅ Prevents last-second failures
+- ✅ Allows time for retry if refresh fails
+- ✅ Minimal unnecessary refreshes
+- ✅ User unaware of refresh process
+
+**Alternative Thresholds:**
+
+```typescript
+// Conservative (1 hour)
+const REFRESH_THRESHOLD_MINUTES = 60
+// More API calls, but very safe
+
+// Balanced (10 minutes) - Default
+const REFRESH_THRESHOLD_MINUTES = 10
+
+// Aggressive (1 minute)
+const REFRESH_THRESHOLD_MINUTES = 1
+// Riskier, might miss some edge cases
+```
+
+### Refresh Failure Handling
+
+**If Refresh Fails:**
+
+1. **Block Publish Operation:**
+   ```typescript
+   return NextResponse.json({
+     error: 'Token expired and refresh failed',
+     details: refreshError,
+     suggestion: 'Please reconnect your social media account'
+   }, { status: 403 })
+   ```
+
+2. **Create Audit Log:**
+   ```typescript
+   await query(`
+     INSERT INTO "audit_logs" 
+     ("userId", "accountId", action, details)
+     VALUES ($1, $2, 'token_refresh_failed', $3)
+   `, [userId, accountId, { error: refreshError }])
+   ```
+
+3. **Optional: Deactivate Account:**
+   ```typescript
+   // Mark account as inactive (requires reconnection)
+   await query(`
+     UPDATE "clients_social_platforms"
+     SET "isActive" = false
+     WHERE id = $1
+   `, [accountId])
+   ```
+
+4. **Notify User:**
+   ```typescript
+   // Send notification (email, in-app)
+   await sendNotification(userId, {
+     type: 'token_expired',
+     message: 'Social media account needs reconnection',
+     accountName: account.platformAccountName
+   })
+   ```
+
+## Token Versioning & Key Rotation
+
+### Key Versioning
+
+**Purpose:** Allow encryption key rotation without invalidating existing tokens
+
+**Implementation:**
+```typescript
+// Store key version with encrypted token
+const keyId = 'key_2024_01'
+
+// During decryption, use appropriate key
+const decryptionKey = getKeyById(keyId)
+```
+
+**Key Rotation Process:**
+
+1. **Generate New Key:**
+   ```bash
+   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+   ```
+
+2. **Add to Environment:**
+   ```bash
+   # Keep old key
+   OAUTH_ENCRYPTION_KEY_2024_01=old_key_here
+   
+   # Add new key
+   OAUTH_ENCRYPTION_KEY=new_key_here
+   OAUTH_ENCRYPTION_KEY_ID=key_2024_02
+   ```
+
+3. **Update Encryption Function:**
+   ```typescript
+   static async encrypt(plainText: string) {
+     const keyId = process.env.OAUTH_ENCRYPTION_KEY_ID || 'key_2024_02'
+     const encryptionKey = process.env.OAUTH_ENCRYPTION_KEY
+     // ... rest of encryption
+   }
+   ```
+
+4. **Update Decryption Function:**
+   ```typescript
+   static async decrypt(encrypted: string, iv: string, keyId: string) {
+     // Get key based on keyId
+     const keyEnvVar = keyId === 'key_2024_01' 
+       ? 'OAUTH_ENCRYPTION_KEY_2024_01'
+       : 'OAUTH_ENCRYPTION_KEY'
+     
+     const encryptionKey = process.env[keyEnvVar]
+     // ... rest of decryption
+   }
+   ```
+
+5. **Gradual Migration:**
+   ```typescript
+   // Migrate old tokens to new key
+   async function migrateTokens() {
+     const oldTokens = await query(`
+       SELECT * FROM "clients_social_platforms"
+       WHERE "accessToken" LIKE '%:key_2024_01'
+     `)
+     
+     for (const account of oldTokens) {
+       // Decrypt with old key
+       const [encrypted, iv, oldKeyId] = account.accessToken.split(':')
+       const plainToken = await TokenEncryption.decryptWithKey(
+         encrypted, iv, oldKeyId
+       )
+       
+       // Re-encrypt with new key
+       const { encrypted: newEncrypted, iv: newIv, keyId: newKeyId } 
+         = await TokenEncryption.encrypt(plainToken)
+       
+       // Update database
+       await query(`
+         UPDATE "clients_social_platforms"
+         SET "accessToken" = $1
+         WHERE id = $2
+       `, [`${newEncrypted}:${newIv}:${newKeyId}`, account.id])
+     }
+   }
+   ```
+
+## Security Best Practices
+
+### Do's ✅
+
+**1. Never Log Decrypted Tokens:**
+```typescript
+// ✅ Good
+console.log('Using token for API call')
+
+// ❌ Bad
+console.log('Token:', decryptedToken)
+```
+
+**2. Decrypt Only When Needed:**
+```typescript
+// ✅ Good
+const token = await decrypt(...)
+await makeAPICall(token)
+// Token discarded
+
+// ❌ Bad
+const token = await decrypt(...)
+this.token = token  // Stored in memory
+```
+
+**3. Validate Before Decryption:**
+```typescript
+// ✅ Good
+if (!account.accessToken.includes(':')) {
+  throw new Error('Invalid token format')
+}
+
+// ❌ Bad
+const token = await decrypt(account.accessToken)  // Might fail
+```
+
+**4. Use RLS Policies:**
+```sql
+-- ✅ Good: Users can only access own clients' tokens
+CREATE POLICY "rls_social_platforms"
+ON "clients_social_platforms"
+USING ("parentId" IN (
+  SELECT id FROM "clients" WHERE "userId" = current_user_id()
+));
+```
+
+**5. Rotate Keys Periodically:**
+```
+Every 6-12 months:
+1. Generate new key
+2. Deploy with both keys
+3. Migrate tokens
+4. Remove old key
+```
+
+### Don'ts ❌
+
+**1. Don't Store Plain Text Tokens:**
+```typescript
+// ❌ Bad
+await query(`INSERT INTO accounts VALUES ($1)`, [plainTextToken])
+
+// ✅ Good
+const encrypted = await encrypt(plainTextToken)
+await query(`INSERT INTO accounts VALUES ($1)`, [encrypted])
+```
+
+**2. Don't Send Tokens to Client:**
+```typescript
+// ❌ Bad
+return NextResponse.json({ token: decryptedToken })
+
+// ✅ Good
+// Never send to client - use on server only
+```
+
+**3. Don't Reuse IVs:**
+```typescript
+// ❌ Bad
+const iv = Buffer.from('same_iv_always')
+
+// ✅ Good
+const iv = crypto.randomBytes(12)  // Unique each time
+```
+
+**4. Don't Skip Token Validation:**
+```typescript
+// ❌ Bad
+const token = await decrypt(dbToken)
+
+// ✅ Good
+if (isTokenExpired(expiresAt)) {
+  await refreshToken()
+}
+const token = await decrypt(dbToken)
+```
+
+## Monitoring & Alerts
+
+### Key Metrics to Track
+
+**1. Token Refresh Success Rate:**
+```sql
+SELECT 
+  COUNT(*) FILTER (WHERE action = 'token_refreshed') as successful,
+  COUNT(*) FILTER (WHERE action = 'token_refresh_failed') as failed,
+  ROUND(
+    COUNT(*) FILTER (WHERE action = 'token_refreshed')::decimal / 
+    NULLIF(COUNT(*), 0) * 100, 
+    2
+  ) as success_rate
+FROM "audit_logs"
+WHERE action IN ('token_refreshed', 'token_refresh_failed')
+AND "createdAt" > NOW() - INTERVAL '30 days';
+```
+
+**2. Token Expiration Distribution:**
+```sql
+SELECT 
+  CASE
+    WHEN "tokenExpiresAt" < NOW() THEN 'Expired'
+    WHEN "tokenExpiresAt" < NOW() + INTERVAL '7 days' THEN 'Expiring Soon'
+    WHEN "tokenExpiresAt" < NOW() + INTERVAL '30 days' THEN 'Expiring This Month'
+    ELSE 'Healthy'
+  END as status,
+  COUNT(*) as count
+FROM "clients_social_platforms"
+WHERE "isActive" = true
+GROUP BY status;
+```
+
+**3. Failed Publish Attempts Due to Token Issues:**
+```sql
+SELECT DATE("createdAt") as date, COUNT(*) as failures
+FROM "audit_logs"
+WHERE action = 'post_failed'
+AND details->>'error' LIKE '%token%'
+GROUP BY DATE("createdAt")
+ORDER BY date DESC
+LIMIT 30;
+```
+
+### Alerting Rules
+
+**Alert if:**
+- Token refresh failure rate > 5%
+- More than 10 tokens expire without refresh
+- Encryption/decryption errors
+- API rate limits hit
+
+## Next Steps
+
+- **[Audit Logging](./04-audit-logging.md)** - Track all token operations
+- **[Provider APIs](../03-advanced-usage/01-provider-apis.md)** - Use tokens in API calls
+- **[Publishing](./02-publishing.md)** - Token usage in publishing