cometchat-native-production

--- name: cometchat-native-production description: "Production-readiness for React Native — server-minted auth tokens, user management CRUD, external-backend recipes (Express / Hono / Firebase Functions / Vercel Serverless). RN has no API routes, so the backend is always external." license: "MIT" compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5" allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion" metadata: author: "CometChat" version: "3.0.0" tags: "cometchat react-native production auth token security user-management rest-api" ---

## Purpose

Teaches Claude how to move a React Native CometChat integration from dev-mode Auth Key to production-ready server-minted auth tokens + user CRUD. Covers:

1. Why the dev `authKey` can't ship to production 2. Auth Key vs REST API Key — which lives where 3. Server endpoint recipes (Express / Hono / Firebase Functions / Vercel) 4. Client-side: `CometChatUIKit.login({ authToken })` + token refresh 5. User CRUD endpoints + auth-provider integration (Firebase Auth / Supabase / Clerk / Auth0) 6. Security checklist + rate limits

**Read `cometchat-native-core` first** (init/login/wrapper chain) before this skill — production just swaps one prop on the provider, but understanding the provider lifecycle is the prerequisite.

Ground truth: `docs/ui-kit/react-native/methods.mdx`, and the cross-platform REST API at `https://{APP_ID}.api-{REGION}.cometchat.io/v3/`.

---

## 1. Why production auth matters

In dev mode, `CometChatUIKit.login({ uid: "..." })` uses the `authKey` configured via `UIKitSettingsBuilder.setAuthKey()`. That key is embedded in your React Native bundle. For a signed iOS `.ipa` or Android `.apk`/`.aab`, anyone can extract it with standard reverse-engineering tools (unzip, strings, `apktool`, `ReverseAPK`) and use it to log in as **ANY** user in your CometChat app — read private messages, send as other users, access every conversation.

Production MUST use server-side token generation:

- Your **server** holds the REST API Key (a different key from the client Auth Key). - On user login, your server calls CometChat's REST API with the REST API Key to mint a short-lived **Auth Token** for that specific UID. - Your client receives the Auth Token and calls `CometChatUIKit.login({ authToken })`. - If the token leaks, the blast radius is one user session, not your whole app.

**Exactly the same threat model as JWTs for a REST API.** If you've built a login flow before, this is that.

---

## 2. Auth Key vs REST API Key — two different keys

Easy to confuse. Both come from the CometChat Dashboard (your app → API & Auth Keys), but they live in different places and have different privileges.

| Key | Where in dashboard | Purpose | Where it lives | |---|---|---|---| | **Auth Key** | "Auth Keys" table | Client-side SDK `login({ uid })` in dev mode | **Client bundle** — dev only. Never in production builds. | | **REST API Key** | "REST API Keys" table | Server-to-server: token generation, user CRUD, custom-message-send | **Server only.** Never in an RN bundle, `app.json extra`, `EXPO_PUBLIC_*` var, or git-committed file. |

If the project only has an Auth Key, the user needs to generate a REST API Key in the dashboard: **API & Auth Keys → REST API Keys → Add Key**. Pick "Full Access" for server-side use.

---

## 3. The token auth pattern (4 steps)

``` 1. Client logs into YOUR auth (Firebase Auth / Supabase / Clerk / Auth0 / custom) ↓ 2. Client asks YOUR backend for a CometChat auth token ↓ (POST /api/cometchat-token { uid }) 3. Backend calls CometChat REST API → gets an Auth Token for that UID ↓ POST https://{APP_ID}.api-{REGION}.cometchat.io/v3/users/{uid}/auth_tokens with header apiKey: <REST_API_KEY> ↓ 4. Client calls CometChatUIKit.login({ authToken: "..." }) ```

The RN client never sees the REST API Key. The server never ships a password or email to the client. The CometChat SDK holds the auth token, not a static key.

---

## 4. Server endpoint recipes

RN projects don't have Next.js-style API routes. You need a separate backend. Pick the one the user already has, or the simplest if they're starting fresh.

### 4a. Express (Node.js backend)

```ts // server/routes/cometchat-token.ts import { Router } from "express"; import { requireAuth } from "../middleware/auth"; // your existing auth

const router = Router(); const APP_ID = process.env.COMETCHAT_APP_ID!; const REGION = process.env.COMETCHAT_REGION!; const REST_API_KEY = process.env.COMETCHAT_REST_API_KEY!;

router.post("/cometchat-token", requireAuth, async (req, res) => { // Derive UID from authenticated session — NOT from the request body in prod. const uid = req.user.id;

const r = await fetch( `https://${APP_ID}.api-${REGION}.cometchat.io/v3/users/${encodeURIComponent(uid)}/auth_tokens`, { method: "POST", headers: { "Content-Type": "application/json", appId: APP_ID, apiKey: REST_API_KEY, }, body: JSON.stringify({}), }, );

if (!r.ok) { const error = await r.text(); console.error("CometChat token error:", error); return res.status(r.status).json({ error: "Failed to generate auth token" }); }

const data = await r.json(); return res.json({ authToken: data.data.authToken }); });

export default router; ```

### 4b. Hono (Cloudflare Workers / Bun / Node)

```ts // server/cometchat-token.ts import { Hono } from "hono";

const app = new Hono();

app.post("/api/cometchat-token", async (c) => { const user = c.get("user"); // your middleware-resolved user if (!user) return c.json({ error: "unauthorized" }, 401);

const APP_ID = c.env.COMETCHAT_APP_ID; const REGION = c.env.COMETCHAT_REGION; const REST_API_KEY = c.env.COMETCHAT_REST_API_KEY;

const r = await fetch( `https://${APP_ID}.api-${REGION}.cometchat.io/v3/users/${encodeURIComponent(user.id)}/auth_tokens`, { method: "POST", headers: { "Content-Type": "application/json", appId: APP_ID, apiKey: REST_API_KEY, }, body: JSON.stringify({}), }, );

if (!r.ok) return c.json({ error: "token mint failed" }, 502); const data = await r.json(); return c.json({ authToken: data.data.authToken }); });

export default app; ```

### 4c. Firebase Cloud Functions

```ts // functions/src/cometchat-token.ts import { onCall, HttpsError } from "firebase-functions/v2/https";

export const getCometChatToken = onCall( { secrets: ["COMETCHAT_APP_ID", "COMETCHAT_REGION", "COMETCHAT_REST_API_KEY"] }, async (request) => { if (!request.auth) throw new HttpsError("unauthenticated", "Sign in required"); const uid = request.auth.uid;

const APP_ID = process.env.COMETCHAT_APP_ID!; const REGION = process.env.COMETCHAT_REGION!; const REST_API_KEY = process.env.COMETCHAT_REST_API_KEY!;

const r = await fetch( `https://${APP_ID}.api-${REGION}.cometchat.io/v3/users/${encodeURIComponent(uid)}/auth_tokens`, { method: "POST", headers: { "Content-Type": "application/json", appId: APP_ID, apiKey: REST_API_KEY, }, body: JSON.stringify({}), }, );

if (!r.ok) throw new HttpsError("internal", "token mint failed"); const data = await r.json(); return { authToken: data.data.authToken }; }, ); ```

Client call:

```tsx import functions from "@react-native-firebase/functions"; const result = await functions().httpsCallable("getCometChatToken")(); const authToken = result.data.authToken; ```

### 4d. Vercel Serverless / Next.js API Route

Even if the RN app isn't Next.js, the user's existing web app often is. Reuse the same backend:

```ts // pages/api/cometchat-token.ts (or app/api/cometchat-token/route.ts) import type { NextApiRequest, NextApiResponse } from "next"; import { getServerSession } from "next-auth"; import { authOptions } from "./auth/[...nextauth]";

export default async function handler(req: NextApiRequest, res: NextApiResponse) { if (req.method !== "POST") return res.status(405).end();

const session = await getServerSession(req, res, authOptions); if (!session?.user) return res.status(401).json({ error: "unauthorized" });

const APP_ID = process.env.COMETCHAT_APP_ID!; const REGION = process.env.COMETCHAT_REGION!; const REST_API_KEY = process.env.COMETCHAT_REST_API_KEY!; const uid = session.user.id;

const r = await fetch( `https://${APP_ID}.api-${REGION}.cometchat.io/v3/users/${encodeURIComponent(uid)}/auth_tokens`, { method: "POST", headers: { "Content-Type": "application/json", appId: APP_ID, apiKey: REST_API_KEY }, body: JSON.stringify({}), }, );

if (!r.ok) return res.status(502).json({ error: "token mint failed" }); const data = await r.json(); return res.json({ authToken: data.data.authToken }); } ```

---

## 5. Client-side: `CometChatUIKit.login({ authToken })`

Once the server is serving tokens, update the RN client to fetch the token and use it. This is a change to the `CometChatProvider` (see `cometchat-native-core` § 6) — swap the `uid` prop for an `authToken` prop.

### 5a. Update the provider to support authToken

```tsx // CometChatProvider.tsx — production-aware version import React, { createContext, useContext, useEffect, useState, type ReactNode } from "react"; import { CometChatUIKit, UIKitSettingsBuilder, } from "@cometchat/chat-uikit-react-native";

let initialized = false; let loginInFlight: Promise<unknown> | null = null;

async function ensureLoggedIn(authToken?: string, uid?: string): Promise<void> { const existing = await CometChatUIKit.getLoggedinUser(); if (existing) return; if (loginInFlight) { await loginInFlight; return; } // Production — prefer authToken if (authToken) { loginInFlight = CometChatUIKit.login({ authToken }); } else if (uid) { loginInFlight = CometChatUIKit.login({ uid }); // dev fallback } else { return; // nothing to log in with yet } try { await loginInFlight; } finally { loginInFlight = null; } }

interface Props { appId: string; region: string; authKey?: string; // dev only; omit in production authToken?: string; // production — from your backend uid?: string; // dev only children: ReactNode; }

export function CometChatProvider({ appId, region, authKey, authToken, uid, children }: Props) { const [isReady, setIsReady] = useState(false); const [error, setError] = useState<string | null>(null);

useEffect(() => { async function setup() { try { if (!initialized) { initialized = true; const builder = new UIKitSettingsBuilder() .setAppId(appId) .setRegion(region) .subscribePresenceForAllUsers(); if (authKey) builder.setAuthKey(authKey); await CometChatUIKit.init(builder.build()); } await ensureLoggedIn(authToken, uid); setIsReady(true); } catch (e) { setError(String(e)); } } setup(); }, [appId, region, authKey, authToken, uid]);

if (!isReady) return null; return <>{children}</>; } ```

**Push registration lands here** — right after `ensureLoggedIn` resolves, before `setIsReady(true)`. The CometChat SDK scopes push tokens to the logged-in user, so registering before login associates the token with "anonymous" and the device won't receive pushes.

```tsx import { bootstrapPushAfterLogin } from "../push/bootstrap"; //... await ensureLoggedIn(authToken, uid); await bootstrapPushAfterLogin(); // registers FCM/APNs token with CometChat setIsReady(true); ```

And unregister BEFORE `CometChatUIKit.logout()` — the SDK needs the user context to dissociate the token. See `cometchat-native-push § 7` for the full `bootstrapPushAfterLogin` / `unregisterPushTokenOnLogout` helper pair.

### 5b. Fetch the token from your backend

Typical app flow: