feat: improve Composio tool description with service categories and u…

CLAUDE.md

@@ -143,6 +143,45 @@ export async function selectTableName({
 - All API routes should have JSDoc comments
 - Run `pnpm lint` before committing
 
+## Authentication
+
+**Never use `account_id` in request bodies or tool schemas.** Always derive the account ID from authentication:
+
+- **API routes**: Use `x-api-key` header via `getApiKeyAccountId()`
+- **MCP tools**: Use `extra.authInfo` via `resolveAccountId()`
+
+Both API keys and Privy access tokens resolve to an `accountId`. Never accept `account_id` as user input.
+
+### API Routes
+
+```typescript
+import { getApiKeyAccountId } from "@/lib/auth/getApiKeyAccountId";
+
+const accountIdOrError = await getApiKeyAccountId(request);
+if (accountIdOrError instanceof NextResponse) {
+  return accountIdOrError;
+}
+const accountId = accountIdOrError;
+```
+
+### MCP Tools
+
+```typescript
+import { resolveAccountId } from "@/lib/mcp/resolveAccountId";
+import type { McpAuthInfo } from "@/lib/mcp/verifyApiKey";
+
+const authInfo = extra.authInfo as McpAuthInfo | undefined;
+const { accountId, error } = await resolveAccountId({
+  authInfo,
+  accountIdOverride: undefined,
+});
+```
+
+This ensures:
+- Callers cannot impersonate other accounts
+- Authentication is always enforced
+- Account ID is derived from validated credentials
+
 ## Input Validation
 
 All API endpoints should use a **validate function** for input parsing. Use Zod for schema validation.

app/api/connectors/authorize/route.ts

@@ -0,0 +1,67 @@
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { authorizeConnector } from "@/lib/composio/connectors";
+import { getApiKeyAccountId } from "@/lib/auth/getApiKeyAccountId";
+import { validateAuthorizeConnectorBody } from "@/lib/composio/connectors/validateAuthorizeConnectorBody";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 200,
+    headers: getCorsHeaders(),
+  });
+}
+
+/**
+ * POST /api/connectors/authorize
+ *
+ * Generate an OAuth authorization URL for a specific connector.
+ *
+ * Authentication: x-api-key header required.
+ * The account ID is inferred from the API key.
+ *
+ * Request body:
+ * - connector: The connector slug, e.g., "googlesheets" (required)
+ * - callback_url: Optional custom callback URL after OAuth
+ *
+ * @returns The redirect URL for OAuth authorization
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const headers = getCorsHeaders();
+
+  try {
+    const accountIdOrError = await getApiKeyAccountId(request);
+    if (accountIdOrError instanceof NextResponse) {
+      return accountIdOrError;
+    }
+
+    const accountId = accountIdOrError;
+    const body = await request.json();
+
+    const validated = validateAuthorizeConnectorBody(body);
+    if (validated instanceof NextResponse) {
+      return validated;
+    }
+
+    const { connector, callback_url } = validated;
+    const result = await authorizeConnector(accountId, connector, callback_url);
+
+    return NextResponse.json(
+      {
+        success: true,
+        data: {
+          connector: result.connector,
+          redirectUrl: result.redirectUrl,
+        },
+      },
+      { status: 200, headers },
+    );
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Failed to authorize connector";
+    return NextResponse.json({ error: message }, { status: 500, headers });
+  }
+}

app/api/connectors/route.ts

@@ -0,0 +1,109 @@
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { getConnectors } from "@/lib/composio/connectors";
+import { disconnectConnector } from "@/lib/composio/connectors/disconnectConnector";
+import { validateDisconnectConnectorBody } from "@/lib/composio/connectors/validateDisconnectConnectorBody";
+import { verifyConnectorOwnership } from "@/lib/composio/connectors/verifyConnectorOwnership";
+import { getApiKeyAccountId } from "@/lib/auth/getApiKeyAccountId";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 200,
+    headers: getCorsHeaders(),
+  });
+}
+
+/**
+ * GET /api/connectors
+ *
+ * List all available connectors and their connection status for a user.
+ *
+ * Authentication: x-api-key header required.
+ *
+ * @returns List of connectors with connection status
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const headers = getCorsHeaders();
+
+  try {
+    const accountIdOrError = await getApiKeyAccountId(request);
+    if (accountIdOrError instanceof NextResponse) {
+      return accountIdOrError;
+    }
+
+    const accountId = accountIdOrError;
+
+    const connectors = await getConnectors(accountId);
+
+    return NextResponse.json(
+      {
+        success: true,
+        data: {
+          connectors,
+        },
+      },
+      { status: 200, headers },
+    );
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Failed to fetch connectors";
+    return NextResponse.json({ error: message }, { status: 500, headers });
+  }
+}
+
+/**
+ * DELETE /api/connectors
+ *
+ * Disconnect a connected account from Composio.
+ *
+ * Authentication: x-api-key header required.
+ *
+ * Body: { connected_account_id: string }
+ */
+export async function DELETE(request: NextRequest): Promise<NextResponse> {
+  const headers = getCorsHeaders();
+
+  try {
+    const accountIdOrError = await getApiKeyAccountId(request);
+    if (accountIdOrError instanceof NextResponse) {
+      return accountIdOrError;
+    }
+
+    const accountId = accountIdOrError;
+    const body = await request.json();
+
+    const validated = validateDisconnectConnectorBody(body);
+    if (validated instanceof NextResponse) {
+      return validated;
+    }
+
+    const { connected_account_id } = validated;
+
+    // Verify the connected account belongs to the authenticated user
+    const isOwner = await verifyConnectorOwnership(accountId, connected_account_id);
+    if (!isOwner) {
+      return NextResponse.json(
+        { error: "Connected account not found or does not belong to this user" },
+        { status: 403, headers }
+      );
+    }
+
+    const result = await disconnectConnector(connected_account_id);
+
+    return NextResponse.json(
+      {
+        success: true,
+        data: result,
+      },
+      { status: 200, headers },
+    );
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Failed to disconnect connector";
+    return NextResponse.json({ error: message }, { status: 500, headers });
+  }
+}

lib/composio/connectors/authorizeConnector.ts

@@ -0,0 +1,45 @@
+import { getComposioClient } from "../client";
+import { getCallbackUrl } from "../getCallbackUrl";
+
+/**
+ * Result of authorizing a connector.
+ */
+export interface AuthorizeResult {
+  connector: string;
+  redirectUrl: string;
+}
+
+/**
+ * Generate an OAuth authorization URL for a connector.
+ *
+ * Why: Used by the /api/connectors/authorize endpoint to let users
+ * connect from the settings page (not in-chat).
+ *
+ * @param userId - The user's account ID
+ * @param connector - The connector slug (e.g., "googlesheets", "gmail")
+ * @param customCallbackUrl - Optional custom callback URL after OAuth
+ * @returns The redirect URL for OAuth
+ */
+export async function authorizeConnector(
+  userId: string,
+  connector: string,
+  customCallbackUrl?: string,
+): Promise<AuthorizeResult> {
+  const composio = getComposioClient();
+
+  const callbackUrl =
+    customCallbackUrl || getCallbackUrl({ destination: "connectors" });
+
+  const session = await composio.create(userId, {
+    manageConnections: {
+      callbackUrl,
+    },
+  });
+
+  const connectionRequest = await session.authorize(connector);
+
+  return {
+    connector,
+    redirectUrl: connectionRequest.redirectUrl,
+  };
+}

lib/composio/connectors/disconnectConnector.ts

@@ -0,0 +1,36 @@
+import { getComposioApiKey } from "../getComposioApiKey";
+
+/**
+ * Disconnect a connected account from Composio.
+ *
+ * Why: Composio's Tool Router SDK doesn't expose a disconnect method,
+ * so we call the REST API directly to delete the connection.
+ *
+ * @param connectedAccountId - The ID of the connected account to disconnect
+ * @returns Success status
+ */
+export async function disconnectConnector(
+  connectedAccountId: string,
+): Promise<{ success: boolean }> {
+  const apiKey = getComposioApiKey();
+
+  // Composio v3 API uses DELETE method
+  const url = `https://backend.composio.dev/api/v3/connected_accounts/${connectedAccountId}`;
+
+  const response = await fetch(url, {
+    method: "DELETE",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `Failed to disconnect (${response.status}): ${errorText}`,
+    );
+  }
+
+  return { success: true };
+}

lib/composio/connectors/getConnectors.ts

@@ -0,0 +1,30 @@
+import { getComposioClient } from "../client";
+
+/**
+ * Connector info returned by Composio.
+ */
+export interface ConnectorInfo {
+  slug: string;
+  name: string;
+  isConnected: boolean;
+  connectedAccountId?: string;
+}
+
+/**
+ * Get all connectors and their connection status for a user.
+ *
+ * @param userId - The user's account ID
+ * @returns List of connectors with connection status
+ */
+export async function getConnectors(userId: string): Promise<ConnectorInfo[]> {
+  const composio = getComposioClient();
+  const session = await composio.create(userId);
+  const toolkits = await session.toolkits();
+
+  return toolkits.items.map((toolkit) => ({
+    slug: toolkit.slug,
+    name: toolkit.name,
+    isConnected: toolkit.connection?.isActive ?? false,
+    connectedAccountId: toolkit.connection?.connectedAccount?.id,
+  }));
+}

lib/composio/connectors/index.ts

@@ -0,0 +1,3 @@
+export { getConnectors, type ConnectorInfo } from "./getConnectors";
+export { authorizeConnector, type AuthorizeResult } from "./authorizeConnector";
+export { disconnectConnector } from "./disconnectConnector";

lib/composio/connectors/validateAuthorizeConnectorBody.ts

@@ -0,0 +1,41 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { z } from "zod";
+
+export const authorizeConnectorBodySchema = z.object({
+  connector: z
+    .string({ message: "connector is required" })
+    .min(1, "connector cannot be empty (e.g., 'googlesheets', 'gmail')"),
+  callback_url: z.string().url("callback_url must be a valid URL").optional(),
+});
+
+export type AuthorizeConnectorBody = z.infer<
+  typeof authorizeConnectorBodySchema
+>;
+
+/**
+ * Validates request body for POST /api/connectors/authorize.
+ *
+ * @param body - The request body
+ * @returns A NextResponse with an error if validation fails, or the validated body if validation passes.
+ */
+export function validateAuthorizeConnectorBody(
+  body: unknown
+): NextResponse | AuthorizeConnectorBody {
+  const result = authorizeConnectorBodySchema.safeParse(body);
+
+  if (!result.success) {
+    const firstError = result.error.issues[0];
+    return NextResponse.json(
+      {
+        error: firstError.message,
+      },
+      {
+        status: 400,
+        headers: getCorsHeaders(),
+      }
+    );
+  }
+
+  return result.data;
+}