@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-flutter-v6-production/SKILL.md

@@ -0,0 +1,632 @@
+---
+name: cometchat-flutter-v6-production
+description: >
+  Production readiness for CometChat Flutter UIKit v6 — server-side auth tokens,
+  user management, Android ProGuard/R8, iOS Info.plist, minSdk, release build
+  checklist, environment configuration, and security hardening. Use when preparing
+  a CometChat Flutter app for production deployment.
+license: "MIT"
+compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
+allowed-tools: "executeBash, readFile, readCode, fileSearch, listDirectory, grepSearch"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat flutter production release auth-token proguard security"
+---
+
+# CometChat Flutter UIKit v6 — Production Readiness
+
+Everything you need to move a CometChat Flutter app from development to production. Covers authentication, platform configuration, environment management, and security hardening.
+
+---
+
+## 1. Dev Mode vs Production
+
+CometChat supports two authentication modes. Understanding the difference is critical before shipping.
+
+### Dev Mode (authKey — development only)
+
+The `authKey` is embedded in client code and lets any user log in by UID alone. Convenient for prototyping, but **anyone who decompiles your app can impersonate any user**.
+
+```dart
+// ✅ Dev mode — fine for prototyping, NEVER ship this
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'APP_ID'
+      ..region = 'us'
+      ..authKey = 'AUTH_KEY'  // Client-side secret — dev only
+      ..subscriptionType = CometChatSubscriptionType.allUsers)
+    .build();
+
+await CometChatUIKit.init(uiKitSettings: settings);
+
+// Login with authKey (SDK uses the key from UIKitSettings internally)
+await CometChatUIKit.login('user_uid',
+  onSuccess: (user) => debugPrint('Logged in: ${user.name}'),
+  onError: (e) => debugPrint('Login failed: ${e.message}'),
+);
+```
+
+### Production Mode (authToken — server-minted)
+
+Your backend generates a short-lived `authToken` for each authenticated user. The client never sees the `authKey`.
+
+```dart
+// ✅ Production — authKey is NOT in client code
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'APP_ID'
+      ..region = 'us'
+      // No authKey here — tokens come from your server
+      ..subscriptionType = CometChatSubscriptionType.allUsers)
+    .build();
+
+await CometChatUIKit.init(uiKitSettings: settings);
+
+// Login with server-provided token
+final authToken = await yourBackend.getCometChatToken(currentUserId);
+await CometChatUIKit.loginWithAuthToken(authToken,
+  onSuccess: (user) => debugPrint('Logged in: ${user.name}'),
+  onError: (e) => debugPrint('Login failed: ${e.message}'),
+);
+```
+
+**Rule**: If `authKey` appears anywhere in your production build, you have a security vulnerability.
+
+---
+
+## 2. Server-Side Auth Token Flow
+
+### How It Works
+
+```
+┌──────────┐     1. Authenticate      ┌──────────────┐
+│  Flutter  │ ──────────────────────>  │  Your Server │
+│   App     │                          │  (Backend)   │
+│           │  4. Return authToken     │              │
+│           │ <──────────────────────  │              │
+└──────────┘                          └──────────────┘
+     │                                       │
+     │ 5. loginWithAuthToken(token)          │ 2. Verify user identity
+     │                                       │ 3. POST /auth-tokens
+     v                                       v
+┌──────────┐                          ┌──────────────┐
+│ CometChat│                          │  CometChat   │
+│   SDK    │                          │  REST API    │
+└──────────┘                          └──────────────┘
+```
+
+### Step 1: Your Backend Generates the Token
+
+Your server calls the CometChat REST API with the `authKey` (which stays server-side):
+
+```bash
+curl -X POST "https://API_REGION.cometchat.io/v3/users/USER_UID/auth_tokens" \
+  -H "appId: YOUR_APP_ID" \
+  -H "apiKey: YOUR_AUTH_KEY" \
+  -H "Content-Type: application/json"
+```
+
+Response:
+```json
+{
+  "data": {
+    "uid": "user_uid",
+    "authToken": "user_uid_1a2b3c4d5e6f7a8b9c0d1e2f",
+    "createdAt": 1700000000
+  }
+}
+```
+
+Replace `API_REGION` with your region endpoint:
+- US: `api-us.cometchat.io`
+- EU: `api-eu.cometchat.io`
+- IN: `api-in.cometchat.io`
+
+### Step 2: Your Backend Returns the Token to the Client
+
+Your Flutter app calls your own backend (after the user authenticates with your auth system), and your backend returns the CometChat `authToken`.
+
+### Step 3: Flutter Client Logs In with the Token
+
+```dart
+Future<void> loginWithToken(String uid) async {
+  // 1. Call YOUR backend to get a CometChat auth token
+  final response = await http.post(
+    Uri.parse('https://your-api.com/cometchat/token'),
+    headers: {'Authorization': 'Bearer ${yourJwt}'},
+    body: jsonEncode({'uid': uid}),
+  );
+  final authToken = jsonDecode(response.body)['authToken'];
+
+  // 2. Login to CometChat with the token
+  CometChatUIKit.loginWithAuthToken(authToken,
+    onSuccess: (user) {
+      // CometChatUIKit.loggedInUser is now set
+      debugPrint('Logged in as ${user.name}');
+    },
+    onError: (e) {
+      debugPrint('CometChat login failed: ${e.message}');
+    },
+  );
+}
+```
+
+**Note**: `loginWithAuthToken` populates `CometChatUIKit.loggedInUser` before calling `onSuccess` — same as `login()` and `init()`. No need to call `getLoggedInUser()` afterward.
+
+---
+
+## 3. User Management
+
+### Creating Users
+
+```dart
+final user = User(
+  uid: 'user_123',
+  name: 'Jane Doe',
+  avatar: 'https://example.com/avatar.png',
+);
+
+await CometChatUIKit.createUser(user,
+  onSuccess: (created) => debugPrint('Created: ${created.uid}'),
+  onError: (e) => debugPrint('Create failed: ${e.message}'),
+);
+```
+
+### Updating Users
+
+```dart
+final user = User(
+  uid: 'user_123',
+  name: 'Jane Smith',  // Updated name
+);
+
+await CometChatUIKit.updateUser(user,
+  onSuccess: (updated) => debugPrint('Updated: ${updated.name}'),
+  onError: (e) => debugPrint('Update failed: ${e.message}'),
+);
+```
+
+### Production Warning
+
+`createUser()` and `updateUser()` require the `authKey` (set in UIKitSettings). In production:
+
+- **Move user creation to your backend** — call the CometChat REST API server-side
+- **Move user updates to your backend** — same approach
+- The Flutter client should only call `loginWithAuthToken()` — never create or update users directly
+
+Server-side user creation:
+```bash
+curl -X POST "https://API_REGION.cometchat.io/v3/users" \
+  -H "appId: YOUR_APP_ID" \
+  -H "apiKey: YOUR_AUTH_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"uid": "user_123", "name": "Jane Doe"}'
+```
+
+---
+
+## 4. Android Build Requirements
+
+These are required for CometChat UIKit v6 on Android. Without them, debug builds may work but release builds will crash.
+
+### gradle.properties
+
+Ensure these are in `android/gradle.properties`:
+
+```properties
+android.useAndroidX=true
+android.enableJetifier=true
+```
+
+`enableJetifier` resolves old Android Support Library conflicts from transitive dependencies in the CometChat SDK.
+
+### minSdk 26
+
+In `android/app/build.gradle` (Groovy) or `build.gradle.kts` (Kotlin DSL):
+
+```kotlin
+// build.gradle.kts
+android {
+    defaultConfig {
+        minSdk = 26  // Required by cometchat_calls_sdk
+    }
+}
+```
+
+```groovy
+// build.gradle (Groovy)
+android {
+    defaultConfig {
+        minSdkVersion 26
+    }
+}
+```
+
+If your `minSdk` is lower than 26, the build will fail with a manifest merger error referencing `cometchat_calls_sdk`.
+
+### ProGuard / R8 Keep Rules
+
+Create `android/app/proguard-rules.pro` with these exact contents:
+
+```proguard
+# CometChat — prevent R8 from stripping SDK classes used via reflection
+-keep class com.cometchat.** { *; }
+-keep interface com.cometchat.** { *; }
+
+# Suppress warnings for Calls SDK classes referenced cross-module
+-dontwarn com.cometchat.calls.CometChatRTCView$CometChatRTCViewBuilder
+-dontwarn com.cometchat.calls.CometChatRTCView
+-dontwarn com.cometchat.calls.CometChatRTCViewListener
+-dontwarn com.cometchat.calls.model.AnalyticsSettings
+-dontwarn com.cometchat.calls.model.RTCCallback
+-dontwarn com.cometchat.calls.model.RTCReceiver
+```
+
+Reference the ProGuard file in your release build type. In `android/app/build.gradle.kts`:
+
+```kotlin
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+}
+```
+
+Or in `android/app/build.gradle` (Groovy):
+
+```groovy
+android {
+    buildTypes {
+        release {
+            minifyEnabled true
+            shrinkResources true
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+}
+```
+
+**Without these rules, release builds crash with `ClassNotFoundException` for CometChat classes.** Debug builds work fine because R8/ProGuard only runs on release.
+
+### Multidex (if targeting API < 21 elsewhere)
+
+CometChat requires minSdk 26, so multidex is not needed (it's automatic above API 21). If you have a multi-module setup where another module targets lower, ensure the app module still sets `minSdk = 26`.
+
+---
+
+## 5. iOS Build Requirements
+
+### Info.plist Permissions
+
+Add these to `ios/Runner/Info.plist` inside the top-level `<dict>`:
+
+```xml
+<!-- Camera access (video calls, sending photos) -->
+<key>NSCameraUsageDescription</key>
+<string>$(PRODUCT_NAME) needs camera access for video calls and sending photos</string>
+
+<!-- Microphone access (voice/video calls, audio messages) -->
+<key>NSMicrophoneUsageDescription</key>
+<string>$(PRODUCT_NAME) needs microphone access for voice and video calls</string>
+
+<!-- Photo library access (sending images from gallery) -->
+<key>NSPhotoLibraryUsageDescription</key>
+<string>$(PRODUCT_NAME) needs photo library access to send images</string>
+```
+
+Without these, the app crashes when the user taps the camera/gallery/mic button — iOS terminates apps that access protected APIs without a usage description.
+
+### VoIP Background Mode (for CallKit)
+
+If using CometChat calling with CallKit (incoming call notifications when app is backgrounded), add to `Info.plist`:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+    <string>voip</string>
+    <string>remote-notification</string>
+</array>
+```
+
+Or enable via Xcode: Target → Signing & Capabilities → + Background Modes → check "Voice over IP" and "Remote notifications".
+
+### App Transport Security
+
+CometChat uses HTTPS by default, so no ATS exceptions are needed. If you're loading user avatars or media from HTTP URLs (not recommended), add:
+
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+    <key>NSAllowsArbitraryLoads</key>
+    <true/>
+</dict>
+```
+
+**Avoid this in production** — it disables all transport security. Instead, ensure all media URLs use HTTPS.
+
+### Minimum iOS Deployment Target
+
+In `ios/Podfile`, ensure:
+
+```ruby
+platform :ios, '13.0'
+```
+
+CometChat UIKit v6 requires iOS 13.0+. If your Podfile has a lower target, `pod install` will fail.
+
+---
+
+## 6. Environment Configuration
+
+Never hardcode credentials in source code. The `AppCredentials` pattern used in development:
+
+```dart
+// ❌ DON'T ship this — credentials visible in decompiled binary
+class AppCredentials {
+  static const String appId = '26580020f03ff346';
+  static const String region = 'in';
+  static const String authKey = '4152b0366478871f0fa8d19a287dd6f5ed5f8eff';
+}
+```
+
+### Option A: Dart Defines (recommended for simple setups)
+
+Pass credentials at build time:
+
+```bash
+flutter run \
+  --dart-define=COMETCHAT_APP_ID=your_app_id \
+  --dart-define=COMETCHAT_REGION=us
+```
+
+Read them in code:
+
+```dart
+class CometChatConfig {
+  static const appId = String.fromEnvironment('COMETCHAT_APP_ID');
+  static const region = String.fromEnvironment('COMETCHAT_REGION');
+  // No authKey in production builds — use authToken flow
+}
+```
+
+For release builds:
+
+```bash
+flutter build apk \
+  --dart-define=COMETCHAT_APP_ID=your_app_id \
+  --dart-define=COMETCHAT_REGION=us
+
+flutter build ipa \
+  --dart-define=COMETCHAT_APP_ID=your_app_id \
+  --dart-define=COMETCHAT_REGION=us
+```
+
+### Option B: .env File with flutter_dotenv
+
+```bash
+dart pub add flutter_dotenv
+```
+
+Create `.env` (add to `.gitignore`):
+
+```
+COMETCHAT_APP_ID=your_app_id
+COMETCHAT_REGION=us
+```
+
+Load in code:
+
+```dart
+import 'package:flutter_dotenv/flutter_dotenv.dart';
+
+Future<void> main() async {
+  await dotenv.load(fileName: '.env');
+  runApp(const MyApp());
+}
+
+class CometChatConfig {
+  static String get appId => dotenv.env['COMETCHAT_APP_ID'] ?? '';
+  static String get region => dotenv.env['COMETCHAT_REGION'] ?? 'us';
+}
+```
+
+**Note**: `.env` files bundled in the app asset can still be extracted. For true secret protection, fetch config from your backend at runtime.
+
+### Option C: Flavor-Based Configuration
+
+For apps with dev/staging/prod environments:
+
+```dart
+enum Environment { dev, staging, prod }
+
+class CometChatConfig {
+  final String appId;
+  final String region;
+  final bool useAuthToken; // true for staging/prod
+
+  const CometChatConfig._({
+    required this.appId,
+    required this.region,
+    required this.useAuthToken,
+  });
+
+  static CometChatConfig of(Environment env) {
+    switch (env) {
+      case Environment.dev:
+        return const CometChatConfig._(
+          appId: 'dev_app_id',
+          region: 'us',
+          useAuthToken: false,
+        );
+      case Environment.staging:
+        return const CometChatConfig._(
+          appId: 'staging_app_id',
+          region: 'us',
+          useAuthToken: true,
+        );
+      case Environment.prod:
+        return const CometChatConfig._(
+          appId: 'prod_app_id',
+          region: 'us',
+          useAuthToken: true,
+        );
+    }
+  }
+}
+```
+
+---
+
+## 7. Release Build Checklist
+
+### Authentication
+- [ ] `authKey` is NOT in any client-side code for production builds
+- [ ] Server-side auth token generation is implemented and tested
+- [ ] `CometChatUIKit.loginWithAuthToken()` is used instead of `CometChatUIKit.login()`
+- [ ] User creation/update calls are server-side, not client-side
+
+### Android
+- [ ] `minSdk = 26` in `android/app/build.gradle`
+- [ ] `android.enableJetifier=true` in `gradle.properties`
+- [ ] `proguard-rules.pro` created with CometChat keep rules
+- [ ] Release build type references `proguard-rules.pro`
+- [ ] `isMinifyEnabled = true` and `isShrinkResources = true` for release
+- [ ] Release APK/AAB tested on a real device (not just debug)
+- [ ] Push notification provider ID configured (FCM)
+
+### iOS
+- [ ] `NSCameraUsageDescription` in Info.plist
+- [ ] `NSMicrophoneUsageDescription` in Info.plist
+- [ ] `NSPhotoLibraryUsageDescription` in Info.plist
+- [ ] VoIP background mode enabled (if using CallKit)
+- [ ] Minimum deployment target is iOS 13.0+
+- [ ] Release build tested on a real device
+- [ ] Push notification entitlements configured (APNs)
+
+### Environment
+- [ ] No hardcoded credentials in source code
+- [ ] Credentials passed via dart-define, .env, or flavor config
+- [ ] `.env` files are in `.gitignore`
+- [ ] Production app ID and region are correct (not dev/staging)
+
+### CometChat Configuration
+- [ ] `CometChatUIKit.init()` called before any login or component usage
+- [ ] `subscriptionType` set in UIKitSettingsBuilder (or presence events won't fire)
+- [ ] `region` is lowercase (`'us'`, `'eu'`, `'in'`)
+- [ ] Logout properly calls `CometChatUIKit.logout()` and clears local state
+
+### Testing
+- [ ] Release build tested end-to-end: init → login → send message → receive message → logout
+- [ ] Tested on both Android and iOS physical devices
+- [ ] Tested with ProGuard/R8 enabled (Android release)
+- [ ] Tested push notifications in production environment
+- [ ] Tested calling features if enabled (audio + video)
+- [ ] Tested app kill → reopen → session restore (cached login via `CometChatUIKit.loggedInUser`)
+
+---
+
+## 8. Security Hardening
+
+### Never Ship authKey in Production
+
+The `authKey` allows anyone to:
+- Log in as any user
+- Create users
+- Update user profiles
+
+If it's in your APK/IPA, it can be extracted in minutes with standard decompilation tools.
+
+```dart
+// ❌ SECURITY VULNERABILITY — authKey in client code
+final settings = (UIKitSettingsBuilder()
+      ..appId = 'APP_ID'
+      ..region = 'us'
+      ..authKey = 'AUTH_KEY_VISIBLE_TO_ATTACKERS')
+    .build();
+
+// ✅ SECURE — no authKey, use server-minted tokens
+final settings = (UIKitSettingsBuilder()
+      ..appId = appId   // App ID is not secret (it's in network requests anyway)
+      ..region = region
+      ..subscriptionType = CometChatSubscriptionType.allUsers)
+    .build();
+```
+
+### Don't Log Sensitive Data
+
+```dart
+// ❌ WRONG — auth tokens in logs
+debugPrint('Token: $authToken');
+debugPrint('User: ${user.toJson()}'); // May contain tokens
+
+// ✅ CORRECT — log only non-sensitive identifiers
+debugPrint('Logged in as uid: ${user.uid}');
+```
+
+In release builds, consider disabling debug prints entirely:
+
+```dart
+// In main.dart for release
+if (kReleaseMode) {
+  debugPrint = (String? message, {int? wrapWidth}) {};
+}
+```
+
+### ProGuard Obfuscation
+
+The ProGuard rules in Section 4 keep CometChat classes intact (required for the SDK to work), but R8 will still obfuscate your own application code. This makes reverse engineering harder.
+
+Ensure `isMinifyEnabled = true` is set for release builds — it enables both code shrinking and obfuscation.
+
+### Token Expiry and Refresh
+
+CometChat auth tokens don't expire by default, but you can configure token expiry in the CometChat dashboard. If you enable expiry:
+
+```dart
+CometChatUIKit.loginWithAuthToken(authToken,
+  onSuccess: (user) {
+    // Token accepted, proceed
+  },
+  onError: (e) {
+    if (e.code == 'ERR_AUTH_TOKEN_NOT_FOUND' || e.code == 'AUTH_ERR_AUTH_TOKEN_NOT_FOUND') {
+      // Token expired or invalid — fetch a new one from your backend
+      refreshAndRetryLogin();
+    }
+  },
+);
+```
+
+### Network Security
+
+- CometChat SDK uses HTTPS/WSS by default — no additional configuration needed
+- Don't add `NSAllowsArbitraryLoads` to Info.plist unless absolutely necessary
+- If using a proxy or custom certificate pinning, ensure CometChat domains are whitelisted:
+  - `*.cometchat.io`
+  - `*.cometchat.com`
+
+### Session Management
+
+```dart
+// Always logout when user signs out of your app
+Future<void> signOut() async {
+  // 1. Logout from CometChat
+  CometChatUIKit.logout(
+    onSuccess: (_) => debugPrint('CometChat logout success'),
+    onError: (e) => debugPrint('CometChat logout failed: ${e.message}'),
+  );
+
+  // 2. Clear your own auth state
+  await yourAuthService.signOut();
+
+  // 3. Navigate to login screen
+  navigator.pushReplacementNamed('/login');
+}
+```
+
+Don't just navigate away — always call `CometChatUIKit.logout()` to clear the SDK session, disconnect WebSocket, and remove cached credentials.