@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/integration/oauth-token-management.md

@@ -0,0 +1,461 @@
+# OAuth Token Management
+
+## Zoho OAuth Token Lifecycle
+
+> **CRITICAL:** Zoho access tokens expire in exactly 1 hour (3600 seconds). You MUST implement refresh logic for any standalone application. Deluge Connections handle this automatically.
+
+```
+Authorization Flow:
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│ User grants  │ →  │ Auth code    │ →  │ Access token │
+│ permission   │    │ (10 min TTL) │    │ (1 hour TTL) │
+└──────────────┘    └──────────────┘    └──────┬───────┘
+                                                │ Expires
+                                                ↓
+                                        ┌──────────────┐
+                                        │ Refresh token│ → New access token
+                                        │ (no expiry*) │
+                                        └──────────────┘
+* Refresh tokens don't expire but can be revoked
+```
+
+## Using Connections in Deluge (Preferred)
+
+Connections handle token refresh automatically. This is always the preferred approach within Zoho apps:
+
+```deluge
+// Connections manage the full OAuth lifecycle
+// You NEVER see or handle tokens directly
+response = invokeUrl [
+    url: "https://www.zohoapis.com/crm/v5/Deals"
+    type: GET
+    connection: "zoho-crm-connection"
+];
+
+// The connection handles:
+// 1. Storing the access token
+// 2. Detecting expiry
+// 3. Using refresh token to get new access token
+// 4. Retrying the request with new token
+```
+
+### Creating a Connection
+
+1. Go to Setup > Developer > Connections
+2. Select service (Zoho CRM, Books, etc.) or Custom OAuth
+3. Define required scopes
+4. Click "Create and Connect"
+5. Authorize in popup
+6. Use connection name in `invokeUrl`
+
+### Connection Scopes (Minimum Necessary)
+
+| Zoho App | Common Scopes | When Needed |
+|----------|---------------|-------------|
+| CRM | `ZohoCRM.modules.ALL` | Full module access |
+| CRM | `ZohoCRM.modules.READ` | Read-only reporting |
+| Books | `ZohoBooks.fullaccess.all` | Full Books access |
+| Books | `ZohoBooks.invoices.READ` | Invoice queries only |
+| Creator | `ZohoCreator.form.CREATE` | Form submissions |
+| Analytics | `ZohoAnalytics.fullaccess.all` | Reports and data |
+
+> **WARNING:** Use the minimum scopes needed. Over-scoping creates security risk. For SOC2 clients, document scope justification.
+
+### When Connections Fail
+
+```deluge
+try
+{
+    response = invokeUrl [
+        url: "https://www.zohoapis.com/crm/v5/Deals"
+        type: GET
+        connection: "zoho-crm-connection"
+    ];
+}
+catch (e)
+{
+    errorStr = e.toString();
+
+    if (errorStr.contains("INVALID_TOKEN") || errorStr.contains("INVALID_OAUTH"))
+    {
+        // Connection needs reauthorization
+        sendmail [
+            from: zoho.adminuserid
+            to: "admin@company.com"
+            subject: "[URGENT] Zoho Connection Expired - Reauthorize Required"
+            message: "Connection 'zoho-crm-connection' needs reauthorization. Go to Setup > Connections to fix."
+        ];
+    }
+    else
+    {
+        info "API error (non-auth): " + errorStr;
+    }
+}
+```
+
+## Manual Refresh Token Flow (Standalone Apps)
+
+For Node.js, Python, or other standalone applications outside Zoho:
+
+### Step 1: Initial Authorization
+
+```
+GET https://accounts.zoho.com/oauth/v2/auth?
+    scope=ZohoCRM.modules.ALL&
+    client_id=YOUR_CLIENT_ID&
+    response_type=code&
+    access_type=offline&
+    redirect_uri=https://your-app.com/callback&
+    prompt=consent
+```
+
+### Step 2: Exchange Code for Tokens
+
+```javascript
+const axios = require("axios");
+
+async function exchangeCodeForTokens(authCode) {
+    const response = await axios.post("https://accounts.zoho.com/oauth/v2/token", null, {
+        params: {
+            grant_type: "authorization_code",
+            client_id: process.env.ZOHO_CLIENT_ID,
+            client_secret: process.env.ZOHO_CLIENT_SECRET,
+            redirect_uri: process.env.ZOHO_REDIRECT_URI,
+            code: authCode
+        }
+    });
+
+    // Response contains:
+    // { access_token, refresh_token, expires_in: 3600, token_type: "Bearer" }
+    return response.data;
+}
+```
+
+### Step 3: Refresh Token (Automated)
+
+```javascript
+class ZohoTokenManager {
+    constructor(clientId, clientSecret, refreshToken, dcDomain = "com") {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.refreshToken = refreshToken;
+        this.accountsUrl = `https://accounts.zoho.${dcDomain}/oauth/v2/token`;
+        this.accessToken = null;
+        this.expiresAt = 0;
+    }
+
+    async getAccessToken() {
+        // Refresh proactively at 50 minutes (before 60-minute expiry)
+        const bufferMs = 10 * 60 * 1000; // 10-minute buffer
+        if (this.accessToken && Date.now() < this.expiresAt - bufferMs) {
+            return this.accessToken;
+        }
+
+        try {
+            const response = await axios.post(this.accountsUrl, null, {
+                params: {
+                    refresh_token: this.refreshToken,
+                    client_id: this.clientId,
+                    client_secret: this.clientSecret,
+                    grant_type: "refresh_token"
+                }
+            });
+
+            if (response.data.error) {
+                throw new Error(`Token refresh failed: ${response.data.error}`);
+            }
+
+            this.accessToken = response.data.access_token;
+            this.expiresAt = Date.now() + (response.data.expires_in * 1000);
+
+            return this.accessToken;
+        } catch (error) {
+            console.error("Token refresh error:", error.message);
+            throw error;
+        }
+    }
+
+    // Make authenticated API call
+    async apiCall(url, method = "GET", data = null) {
+        const token = await this.getAccessToken();
+
+        const config = {
+            method,
+            url,
+            headers: {
+                "Authorization": `Zoho-oauthtoken ${token}`,
+                "Content-Type": "application/json"
+            }
+        };
+
+        if (data) config.data = data;
+
+        try {
+            return await axios(config);
+        } catch (error) {
+            // If 401, force token refresh and retry once
+            if (error.response && error.response.status === 401) {
+                this.accessToken = null; // Force refresh
+                const newToken = await this.getAccessToken();
+                config.headers["Authorization"] = `Zoho-oauthtoken ${newToken}`;
+                return await axios(config);
+            }
+            throw error;
+        }
+    }
+}
+
+// Usage
+const zoho = new ZohoTokenManager(
+    process.env.ZOHO_CLIENT_ID,
+    process.env.ZOHO_CLIENT_SECRET,
+    process.env.ZOHO_REFRESH_TOKEN,
+    process.env.ZOHO_DC || "com"
+);
+
+const deals = await zoho.apiCall("https://www.zohoapis.com/crm/v5/Deals");
+```
+
+## Token Storage Best Practices
+
+### Where to Store Tokens
+
+| Storage | Appropriate For | Security Level |
+|---------|----------------|----------------|
+| Catalyst Segments | Catalyst functions | Encrypted at rest |
+| Environment variables | Server-side apps | Process-level isolation |
+| Secret Manager (GCP/AWS) | Production systems | Full audit trail |
+| .env file (local) | Development only | Gitignored |
+
+### Where NEVER to Store Tokens
+
+- Deluge variables or Creator fields
+- Git repositories (even private)
+- Client-side JavaScript
+- Browser localStorage/cookies
+- Log files
+- Email or chat messages
+- Hard-coded in source code
+
+### Catalyst Segments Storage
+
+```javascript
+// Store token in Catalyst Segments (encrypted key-value store)
+const catalyst = require("zcatalyst-sdk-node");
+
+async function storeToken(context, key, tokenData) {
+    const app = catalyst.initialize(context);
+    const segment = app.cache().segment();
+
+    await segment.put(key, JSON.stringify({
+        access_token: tokenData.access_token,
+        expires_at: Date.now() + (tokenData.expires_in * 1000),
+        stored_at: new Date().toISOString()
+    }), tokenData.expires_in); // TTL matches token expiry
+
+    return true;
+}
+
+async function getToken(context, key) {
+    const app = catalyst.initialize(context);
+    const segment = app.cache().segment();
+
+    const cached = await segment.get(key);
+    if (cached) {
+        const data = JSON.parse(cached.cache_value);
+        if (Date.now() < data.expires_at) {
+            return data.access_token;
+        }
+    }
+    return null; // Token expired or not found
+}
+```
+
+## Multi-DC Token Management
+
+Zoho operates in multiple data centers. Tokens are DC-specific:
+
+| DC | Accounts URL | API Domain | Region |
+|----|-------------|------------|--------|
+| com | accounts.zoho.com | zohoapis.com | US |
+| eu | accounts.zoho.eu | zohoapis.eu | Europe |
+| in | accounts.zoho.in | zohoapis.in | India |
+| com.au | accounts.zoho.com.au | zohoapis.com.au | Australia |
+| jp | accounts.zoho.jp | zohoapis.jp | Japan |
+| com.cn | accounts.zoho.com.cn | zohoapis.com.cn | China |
+| ca | accounts.zohocloud.ca | zohoapis.ca | Canada |
+
+### Multi-DC Implementation
+
+```javascript
+// Determine correct DC based on client configuration
+function getZohoUrls(dc) {
+    const dcMap = {
+        "com": { accounts: "accounts.zoho.com", api: "zohoapis.com" },
+        "eu": { accounts: "accounts.zoho.eu", api: "zohoapis.eu" },
+        "in": { accounts: "accounts.zoho.in", api: "zohoapis.in" },
+        "com.au": { accounts: "accounts.zoho.com.au", api: "zohoapis.com.au" },
+        "jp": { accounts: "accounts.zoho.jp", api: "zohoapis.jp" },
+        "ca": { accounts: "accounts.zohocloud.ca", api: "zohoapis.ca" }
+    };
+
+    if (!dcMap[dc]) {
+        throw new Error(`Unknown Zoho DC: ${dc}. Valid: ${Object.keys(dcMap).join(", ")}`);
+    }
+
+    return {
+        tokenUrl: `https://${dcMap[dc].accounts}/oauth/v2/token`,
+        authUrl: `https://${dcMap[dc].accounts}/oauth/v2/auth`,
+        apiBase: `https://www.${dcMap[dc].api}`
+    };
+}
+
+// Per-client token manager
+class MultiDCTokenManager {
+    constructor(clientConfigs) {
+        // clientConfigs: { clientId: { dc, clientId, clientSecret, refreshToken } }
+        this.managers = {};
+
+        for (const [id, config] of Object.entries(clientConfigs)) {
+            this.managers[id] = new ZohoTokenManager(
+                config.clientId,
+                config.clientSecret,
+                config.refreshToken,
+                config.dc
+            );
+        }
+    }
+
+    async getClientToken(clientId) {
+        if (!this.managers[clientId]) {
+            throw new Error(`No token manager for client: ${clientId}`);
+        }
+        return await this.managers[clientId].getAccessToken();
+    }
+}
+```
+
+## Error Handling for Expired Tokens
+
+### Common Token Errors
+
+| Error Code | Meaning | Action |
+|-----------|---------|--------|
+| INVALID_TOKEN | Access token expired | Refresh using refresh token |
+| INVALID_OAUTH_TOKEN | Token malformed | Check token storage, regenerate |
+| OAUTH_SCOPE_MISMATCH | Insufficient scope | Re-authorize with correct scopes |
+| INVALID_CLIENT | Client ID/Secret wrong | Verify API console credentials |
+| INVALID_CODE | Auth code expired (>10 min) | Restart auth flow |
+| ACCESS_DENIED | User revoked access | Re-authorize, user must grant again |
+
+### Handling Token Errors in Production
+
+```javascript
+async function handleTokenError(error, clientId) {
+    const errorCode = error.response?.data?.code || error.message;
+
+    switch (errorCode) {
+        case "INVALID_TOKEN":
+            // Normal expiry - auto-refresh handles this
+            console.log("Token expired, refreshing...");
+            return await tokenManager.forceRefresh(clientId);
+
+        case "INVALID_OAUTH_TOKEN":
+        case "INVALID_CLIENT":
+            // Credentials issue - needs human intervention
+            await notifyAdmin({
+                subject: `[CRITICAL] OAuth credentials invalid for ${clientId}`,
+                message: `Error: ${errorCode}. Manual reauthorization required.`
+            });
+            throw new Error("OAuth credentials invalid - manual fix required");
+
+        case "OAUTH_SCOPE_MISMATCH":
+            // Scope changed - need new authorization
+            await notifyAdmin({
+                subject: `[ACTION] OAuth scope change needed for ${clientId}`,
+                message: `Current scopes insufficient. Re-authorize with updated scopes.`
+            });
+            throw new Error("Insufficient OAuth scopes");
+
+        case "ACCESS_DENIED":
+            // User revoked - completely broken until re-authorized
+            await notifyAdmin({
+                subject: `[CRITICAL] OAuth access revoked for ${clientId}`,
+                message: `User has revoked access. All API calls will fail until re-authorized.`
+            });
+            throw new Error("OAuth access revoked by user");
+
+        default:
+            throw error;
+    }
+}
+```
+
+## Multi-Org Token Management (Consultancy Pattern)
+
+For CloudStream with multiple client orgs:
+
+```javascript
+// .env.client file structure (gitignored)
+// ZOHO_DC=com
+// ZOHO_CLIENT_ID=1000.ABC123...
+// ZOHO_CLIENT_SECRET=xyz789...
+// ZOHO_REFRESH_TOKEN=1000.refresh...
+// ZOHO_ORG_ID=12345678
+
+// Client switch loads correct credentials
+// Use /client-switch command to swap active client context
+
+// Token isolation: Each client has completely separate OAuth app
+// Never share refresh tokens between clients
+// Store per-client in separate env files or secret manager keys
+```
+
+### Token Rotation Schedule
+
+For SOC2/HIPAA compliance:
+
+```
+Monthly:
+  1. Generate new client_secret in Zoho API Console
+  2. Update all applications using that secret
+  3. Verify token refresh works with new secret
+  4. Revoke old secret after 24-hour verification period
+  5. Document rotation in change log
+
+On Incident:
+  1. Immediately revoke compromised refresh token
+  2. Generate new OAuth application if client_secret exposed
+  3. Re-authorize all connections
+  4. Audit access logs for unauthorized use
+```
+
+## Testing Token Management
+
+```javascript
+// Verify token management is working correctly
+async function tokenHealthCheck(clientId) {
+    try {
+        const token = await tokenManager.getAccessToken(clientId);
+
+        // Test the token with a simple API call
+        const response = await axios.get(
+            `${getZohoUrls(clientDC).apiBase}/crm/v5/org`,
+            { headers: { "Authorization": `Zoho-oauthtoken ${token}` } }
+        );
+
+        return {
+            status: "healthy",
+            org_name: response.data.org[0].company_name,
+            token_prefix: token.substring(0, 10) + "...",
+            dc: clientDC
+        };
+    } catch (error) {
+        return {
+            status: "unhealthy",
+            error: error.message,
+            action_required: true
+        };
+    }
+}
+```