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

package/docs/02-core-features/01-oauth-integration.md

@@ -0,0 +1,501 @@
+# OAuth Integration
+
+## Overview
+
+The Social Media Publisher plugin uses **Facebook OAuth 2.0** to connect Instagram Business and Facebook Page accounts. OAuth connections are managed per-client, with tokens encrypted and stored securely in the database.
+
+**Key Features:**
+- Popup-based OAuth flow (no full-page redirects)
+- Per-client account management
+- Automatic token encryption
+- Multi-account support
+- CSRF protection via state parameter
+- PostMessage communication between popup and parent window
+
+## OAuth Flow Diagram
+
+```
+┌─────────────┐
+│   User      │
+│  (Client    │
+│   Context)  │
+└──────┬──────┘
+       │ 1. Clicks "Connect Instagram"
+       ↓
+┌──────────────────────────────┐
+│  /api/v1/plugin/social-      │
+│   media-publisher/social/    │
+│   connect?platform=          │
+│   instagram_business&        │
+│   clientId={uuid}            │
+└──────┬───────────────────────┘
+       │ 2. Generates OAuth URL
+       ↓
+┌──────────────────────────────┐
+│  OAuth Popup Window          │
+│  facebook.com/dialog/oauth   │
+└──────┬───────────────────────┘
+       │ 3. User authorizes
+       ↓
+┌──────────────────────────────┐
+│  /api/v1/plugin/social-      │
+│   media-publisher/social/    │
+│   connect/callback?          │
+│   code={code}&state={state}  │
+└──────┬───────────────────────┘
+       │ 4. Exchange code for token
+       ↓
+┌──────────────────────────────┐
+│  Facebook Graph API          │
+│  - Get access token          │
+│  - Fetch user's Pages        │
+│  - Get Instagram accounts    │
+└──────┬───────────────────────┘
+       │ 5. Encrypt tokens
+       ↓
+┌──────────────────────────────┐
+│  Database                    │
+│  clients_social_platforms    │
+│  (encrypted tokens stored)   │
+└──────┬───────────────────────┘
+       │ 6. Return success HTML
+       ↓
+┌──────────────────────────────┐
+│  Popup window.postMessage    │
+│  { type: 'oauth-success',    │
+│    connectedCount: 2 }       │
+└──────┬───────────────────────┘
+       │ 7. Parent receives message
+       ↓
+┌──────────────────────────────┐
+│  Parent Window               │
+│  - Refresh page              │
+│  - Show new accounts         │
+│  - Close popup (auto)        │
+└──────────────────────────────┘
+```
+
+## Step-by-Step Flow
+
+### Step 1: Initiate OAuth
+
+**User Action:** Clicks "Connect Instagram Business" or "Connect Facebook Page"
+
+**Frontend Code:**
+```typescript
+'use client'
+
+import { useRouter } from 'next/navigation'
+
+export function ConnectSocialButton({ 
+  clientId, 
+  platform 
+}: { 
+  clientId: string
+  platform: 'instagram_business' | 'facebook_page'
+}) {
+  const router = useRouter()
+
+  const handleConnect = () => {
+    // Build OAuth initiation URL
+    const baseUrl = process.env.NEXT_PUBLIC_APP_URL || window.location.origin
+    const oauthUrl = `${baseUrl}/api/v1/plugin/social-media-publisher/social/connect?platform=${platform}&clientId=${clientId}`
+
+    // Open popup window
+    const popup = window.open(
+      oauthUrl,
+      'oauth-popup',
+      'width=600,height=700,scrollbars=yes'
+    )
+
+    // Listen for success message from popup
+    const handleMessage = (event: MessageEvent) => {
+      // Verify origin
+      if (event.origin !== window.location.origin) return
+
+      if (event.data.type === 'oauth-success') {
+        console.log(`✅ Connected ${event.data.connectedCount} account(s)`)
+        
+        // Cleanup
+        window.removeEventListener('message', handleMessage)
+        
+        // Refresh to show new accounts
+        router.refresh()
+      }
+    }
+
+    window.addEventListener('message', handleMessage)
+
+    // Cleanup if popup closes without success
+    const checkPopup = setInterval(() => {
+      if (popup?.closed) {
+        clearInterval(checkPopup)
+        window.removeEventListener('message', handleMessage)
+      }
+    }, 1000)
+  }
+
+  return (
+    <button onClick={handleConnect}>
+      Connect {platform === 'instagram_business' ? 'Instagram' : 'Facebook Page'}
+    </button>
+  )
+}
+```
+
+### Step 2: Generate OAuth URL
+
+**Endpoint:** `GET /api/v1/plugin/social-media-publisher/social/connect`
+
+**Query Parameters:**
+- `platform` - `'instagram_business'` or `'facebook_page'`
+- `clientId` - UUID of client to connect accounts to
+
+**What Happens:**
+1. Generates random state value (CSRF protection)
+2. Constructs state parameter: `{randomState}&platform={platform}&clientId={clientId}`
+3. Builds Facebook OAuth URL with required scopes
+4. Redirects user to Facebook authorization page
+
+**OAuth URL Format:**
+```
+https://www.facebook.com/v18.0/dialog/oauth
+  ?client_id={FACEBOOK_CLIENT_ID}
+  &redirect_uri={callback_url}
+  &state={encoded_state}
+  &scope={permissions}
+```
+
+**Scopes for Instagram Business:**
+```
+pages_show_list,instagram_basic,instagram_content_publish,instagram_manage_insights
+```
+
+**Scopes for Facebook Pages:**
+```
+pages_show_list,pages_manage_posts,pages_read_engagement,read_insights
+```
+
+### Step 3: User Authorization
+
+**What User Sees:**
+1. Facebook authorization page opens in popup
+2. Shows app name, icon, and requested permissions
+3. User can choose which Pages to grant access to
+4. User clicks "Continue" or "Cancel"
+
+**User Can:**
+- ✅ Grant all permissions
+- ✅ Grant partial permissions (select specific Pages)
+- ❌ Deny all permissions
+
+### Step 4: OAuth Callback
+
+**Endpoint:** `GET /api/v1/plugin/social-media-publisher/social/connect/callback`
+
+**Success Parameters:**
+```
+code: Authorization code from Facebook
+state: CSRF token + platform + clientId
+```
+
+**Error Parameters:**
+```
+error: Error code (e.g., 'access_denied')
+error_description: Human-readable error
+```
+
+**Callback Processing:**
+
+1. **Validate State Parameter:**
+   ```typescript
+   const [randomState, platformParam, clientIdParam] = state.split('&')
+   // Verify state matches expected format
+   ```
+
+2. **Exchange Code for Access Token:**
+   ```typescript
+   const tokenUrl = `https://graph.facebook.com/v18.0/oauth/access_token`
+   const params = new URLSearchParams({
+     client_id: FACEBOOK_CLIENT_ID,
+     client_secret: FACEBOOK_CLIENT_SECRET,
+     redirect_uri: callbackUrl,
+     code: authorizationCode
+   })
+   
+   const response = await fetch(`${tokenUrl}?${params.toString()}`)
+   const { access_token } = await response.json()
+   ```
+
+3. **Fetch User's Facebook Pages:**
+   ```typescript
+   const pages = await FacebookAPI.getUserPages(access_token)
+   // Returns array of Pages with Page-specific tokens
+   ```
+
+4. **For Each Page:**
+   ```typescript
+   if (platform === 'instagram_business') {
+     // Check if Page has Instagram Business Account
+     const igAccount = await FacebookAPI.getInstagramBusinessAccount(
+       page.id,
+       page.accessToken
+     )
+     
+     if (igAccount) {
+       await saveToDatabase({
+         parentId: clientId,
+         platform: 'instagram_business',
+         platformAccountId: igAccount.id,
+         platformAccountName: igAccount.username,
+         accessToken: await encrypt(page.accessToken),
+         ...
+       })
+     }
+   } else {
+     // Save Facebook Page directly
+     await saveToDatabase({
+       parentId: clientId,
+       platform: 'facebook_page',
+       platformAccountId: page.id,
+       platformAccountName: page.name,
+       accessToken: await encrypt(page.accessToken),
+       ...
+     })
+   }
+   ```
+
+5. **Encrypt and Store Tokens:**
+   ```typescript
+   // Encrypt access token
+   const { encrypted, iv, keyId } = await TokenEncryption.encrypt(accessToken)
+   const encryptedToken = `${encrypted}:${iv}:${keyId}`
+   
+   // Calculate expiration (60 days for long-lived tokens)
+   const expiresAt = new Date(Date.now() + 60 * 24 * 60 * 60 * 1000)
+   
+   // Store in database
+   await query(`
+     INSERT INTO "clients_social_platforms" (
+       "parentId", platform, "platformAccountId", 
+       "platformAccountName", "accessToken", "tokenExpiresAt"
+     ) VALUES ($1, $2, $3, $4, $5, $6)
+   `, [clientId, platform, accountId, accountName, encryptedToken, expiresAt])
+   ```
+
+6. **Create Audit Log:**
+   ```typescript
+   await query(`
+     INSERT INTO "audit_logs" (
+       "userId", "accountId", action, details
+     ) VALUES ($1, $2, 'account_connected', $3)
+   `, [userId, accountId, { platform, accountName }])
+   ```
+
+7. **Return Success HTML:**
+   ```html
+   <!DOCTYPE html>
+   <html>
+   <head>
+     <title>Authorization Successful</title>
+   </head>
+   <body>
+     <h1>✅ Successfully Connected</h1>
+     <p>Connected 2 Instagram Business account(s)</p>
+     <p>This window will close automatically...</p>
+     <script>
+       // Send success message to parent window
+       window.opener.postMessage({
+         type: 'oauth-success',
+         platform: 'instagram_business',
+         connectedCount: 2
+       }, window.location.origin)
+       
+       // Auto-close after 2 seconds
+       setTimeout(() => window.close(), 2000)
+     </script>
+   </body>
+   </html>
+   ```
+
+### Step 5: PostMessage Communication
+
+**Popup Window:**
+```javascript
+// Send message to parent window
+window.opener.postMessage({
+  type: 'oauth-success',
+  platform: 'instagram_business',
+  connectedCount: 2
+}, window.location.origin)
+```
+
+**Parent Window:**
+```javascript
+window.addEventListener('message', (event) => {
+  // Verify origin (security)
+  if (event.origin !== window.location.origin) return
+
+  if (event.data.type === 'oauth-success') {
+    // Refresh page to show new accounts
+    router.refresh()
+  }
+})
+```
+
+## Security Features
+
+### CSRF Protection (State Parameter)
+
+**State Format:**
+```
+{randomString}&platform={platform}&clientId={clientId}
+
+Example:
+a7f9b2c8d1e3f4a5&platform=instagram_business&clientId=550e8400-e29b-41d4-a716-446655440000
+```
+
+**Validation:**
+1. Generate random state before redirect
+2. Include platform and clientId in state
+3. Facebook returns state unchanged
+4. Verify state format and extract data
+5. Reject if state is invalid
+
+### Token Encryption
+
+**All tokens encrypted before storage:**
+```typescript
+// Plain text token from Facebook
+const accessToken = "EAABwzLixnjY..."
+
+// Encrypt
+const { encrypted, iv, keyId } = await TokenEncryption.encrypt(accessToken)
+
+// Store format: encrypted:iv:keyId
+const storedToken = `${encrypted}:${iv}:${keyId}`
+```
+
+**Decryption (only when needed):**
+```typescript
+const [encrypted, iv, keyId] = storedToken.split(':')
+const decryptedToken = await TokenEncryption.decrypt(encrypted, iv, keyId)
+// Use for API call
+// Never log or store decrypted token
+```
+
+### Origin Validation
+
+**PostMessage security:**
+```javascript
+window.addEventListener('message', (event) => {
+  // ✅ Validate origin
+  if (event.origin !== window.location.origin) {
+    console.warn('Rejected message from untrusted origin:', event.origin)
+    return
+  }
+
+  // Process message
+})
+```
+
+## Error Handling
+
+### User Denies Permission
+
+**Error Response:**
+```
+?error=access_denied
+&error_description=The+user+denied+your+request
+```
+
+**Handling:**
+```typescript
+if (error === 'access_denied') {
+  return NextResponse.html(`
+    <html>
+      <body>
+        <h1>Authorization Cancelled</h1>
+        <p>You chose not to connect your account.</p>
+        <button onclick="window.close()">Close</button>
+      </body>
+    </html>
+  `)
+}
+```
+
+### Invalid OAuth Code
+
+**Cause:** Code expired or already used
+
+**Solution:** Restart OAuth flow
+
+### No Instagram Account Found
+
+**Cause:** Facebook Page not linked to Instagram Business
+
+**Solution:**
+1. Show clear error message
+2. Provide link to Facebook Page settings
+3. Guide user to connect Instagram
+
+**Error HTML:**
+```html
+<html>
+  <body>
+    <h1>⚠️ No Instagram Business Account Found</h1>
+    <p>None of your Facebook Pages have an Instagram Business Account connected.</p>
+    <h3>How to Connect Instagram:</h3>
+    <ol>
+      <li>Go to your Facebook Page Settings</li>
+      <li>Click "Instagram" in the sidebar</li>
+      <li>Click "Connect Account"</li>
+      <li>Log in to Instagram and authorize</li>
+      <li>Try connecting again</li>
+    </ol>
+    <button onclick="window.close()">Close</button>
+  </body>
+</html>
+```
+
+## Multi-Account Support
+
+### Connecting Multiple Accounts
+
+**Same Platform, Different Accounts:**
+```typescript
+// User connects Instagram account @brand1
+// Then connects Instagram account @brand2
+// Both stored under same client
+```
+
+**Database:**
+```sql
+SELECT * FROM "clients_social_platforms" WHERE "parentId" = '{clientId}'
+
+-- Results:
+id | platform | platformAccountName | isActive
+---|----------|---------------------|----------
+1  | instagram_business | @brand1 | true
+2  | instagram_business | @brand2 | true
+```
+
+### Preventing Duplicates
+
+**Unique Constraint:**
+```sql
+UNIQUE("parentId", "platformAccountId") 
+WHERE "platformAccountId" IS NOT NULL
+```
+
+**On Duplicate:**
+- Update existing record
+- Refresh token
+- Update metadata
+- Don't create new record
+
+## Next Steps
+
+- **[Publishing](./02-publishing.md)** - Use connected accounts to publish
+- **[Token Management](./03-token-management.md)** - Understand token lifecycle
+- **[Audit Logging](./04-audit-logging.md)** - Track all OAuth events