Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(review): enforce public toolkit fallback policy

jkomyno35f46c567bf7
diff --git a/docs/decisions/toolkit-page-availability.md b/docs/decisions/toolkit-page-availability.md
index b606a7737..71a493034 100644
--- a/docs/decisions/toolkit-page-availability.md
+++ b/docs/decisions/toolkit-page-availability.md
@@ -36,7 +36,8 @@ block toolkit, OpenAPI, API index, or meta-tool generation.
- A snapshot hit renders without a production catalog request.
- A snapshot miss may issue one production lookup for the validated slug. An
- invalid or unknown slug still returns 404.
+ invalid, excluded, disabled, custom, or unknown slug still returns 404. The
+ fallback only publishes enabled, Composio-managed toolkits.
- Landing, sitemap, search, KB verification, and build behavior remain
snapshot-backed.
- `/llms.mdx/toolkits/<slug>` parity is deferred. A toolkit available only
diff --git a/docs/lib/public-toolkit-policy.ts b/docs/lib/public-toolkit-policy.ts
new file mode 100644
index 000000000..e49f316e9
--- /dev/null
+++ b/docs/lib/public-toolkit-policy.ts
@@ -0,0 +1,9 @@
+const EXCLUDED_PUBLIC_TOOLKIT_SLUGS = new Set(['test_app']);
+
+export function normalizeToolkitSlug(slug: string): string {
+ return slug.toLowerCase();
+}
+
+export function isPublicToolkitSlug(slug: string): boolean {
+ return !EXCLUDED_PUBLIC_TOOLKIT_SLUGS.has(normalizeToolkitSlug(slug));
+}
diff --git a/docs/lib/toolkit-api.ts b/docs/lib/toolkit-api.ts
index 6a9c452aa..2c5f15ed9 100644
--- a/docs/lib/toolkit-api.ts
+++ b/docs/lib/toolkit-api.ts
@@ -1,12 +1,16 @@
import { z } from 'zod';
+import { isPublicToolkitSlug, normalizeToolkitSlug } from '@/lib/public-toolkit-policy';
import { PRODUCTION_API_V3_URL } from '@/scripts/production-api.mjs';
import type { AuthConfigDetail, AuthConfigField, Toolkit } from '@/types/toolkit';
const NEGATIVE_CACHE_TTL_MS = 60_000;
const NEGATIVE_CACHE_MAX_ENTRIES = 1_024;
+const IN_FLIGHT_LOOKUP_MAX_ENTRIES = 1_024;
+const PRODUCTION_REQUEST_TIMEOUT_MS = 15_000;
const TOOLKIT_SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
const negativeCache = new Map<string, number>();
+const inFlightLookups = new Map<string, Promise<Toolkit | null>>();
function filteredArray<T>(schema: z.ZodType<T>) {
return z
@@ -69,6 +73,8 @@ const rawToolkitSchema = z
.object({
slug: z.string().catch(''),
name: optionalString,
+ type: z.enum(['native', 'custom']).optional().catch(undefined),
+ enabled: z.boolean().optional().catch(undefined),
composio_managed_auth_schemes: stringArray,
auth_config_details: filteredArray(rawAuthConfigDetailSchema),
meta: z
@@ -92,6 +98,8 @@ const rawToolkitSchema = z
.catch({
slug: '',
name: undefined,
+ type: undefined,
+ enabled: undefined,
composio_managed_auth_schemes: [],
auth_config_details: [],
meta: {
@@ -217,8 +225,9 @@ export async function fetchToolkitFromProduction(slug: string): Promise<Toolkit
return null;
}
- const normalizedSlug = slug.toLowerCase();
+ const normalizedSlug = normalizeToolkitSlug(slug);
if (!TOOLKIT_SLUG_PATTERN.test(normalizedSlug)) return null;
+ if (!isPublicToolkitSlug(normalizedSlug)) return null;
const negativeUntil = negativeCache.get(normalizedSlug);
if (negativeUntil !== undefined) {
@@ -226,6 +235,27 @@ export async function fetchToolkitFromProduction(slug: string): Promise<Toolkit
negativeCache.delete(normalizedSlug);
}
+ const inFlightLookup = inFlightLookups.get(normalizedSlug);
+ if (inFlightLookup) return inFlightLookup;
+
+ const request = fetchAndMapToolkit(normalizedSlug, apiKey);
+ let trackedRequest: Promise<Toolkit | null>;
+ trackedRequest = request.finally(() => {
+ if (inFlightLookups.get(normalizedSlug) === trackedRequest) {
+ inFlightLookups.delete(normalizedSlug);
+ }
+ });
+
+ if (inFlightLookups.size >= IN_FLIGHT_LOOKUP_MAX_ENTRIES) {
+ const oldestSlug = inFlightLookups.keys().next().value;
+ if (oldestSlug !== undefined) inFlightLookups.delete(oldestSlug);
+ }
+ inFlightLookups.set(normalizedSlug, trackedRequest);
+
+ return trackedRequest;
+}
+
+async function fetchAndMapToolkit(normalizedSlug: string, apiKey: string): Promise<Toolkit | null> {
try {
const response = await fetch(`${PRODUCTION_API_V3_URL}/toolkits/${normalizedSlug}`, {
headers: {
@@ -233,6 +263,7 @@ export async function fetchToolkitFromProduction(slug: string): Promise<Toolkit
'x-api-key': apiKey,
},
next: { revalidate: 3600 },
+ signal: AbortSignal.timeout(PRODUCTION_REQUEST_TIMEOUT_MS),
});
if (!response.ok) {
@@ -244,6 +275,13 @@ export async function fetchToolkitFromProduction(slug: string): Promise<Toolkit
}
const payload = rawToolkitSchema.parse(await response.json());
+ if (payload.type !== 'native' || payload.enabled !== true) {
+ recordNegative(normalizedSlug);
+ console.warn(
+ `[Toolkits] Production toolkit lookup rejected non-public toolkit "${normalizedSlug}"`
+ );
+ return null;
+ }
return toolkitFromRaw(payload, normalizedSlug);
} catch (error) {
recordNegative(normalizedSlug);
diff --git a/docs/lib/toolkit-resolution.ts b/docs/lib/toolkit-resolution.ts
index 9f6a14cbf..51992672e 100644
--- a/docs/lib/toolkit-resolution.ts
+++ b/docs/lib/toolkit-resolution.ts
@@ -1,8 +1,11 @@
import { fetchToolkitFromProduction } from '@/lib/toolkit-api';
import { getToolkitBySlug } from '@/lib/toolkit-data';
+import { isPublicToolkitSlug } from '@/lib/public-toolkit-policy';
import type { Toolkit } from '@/types/toolkit';
export async function resolveToolkit(slug: string): Promise<Toolkit | null> {
+ if (!isPublicToolkitSlug(slug)) return null;
+
const snapshotToolkit = await getToolkitBySlug(slug);
if (snapshotToolkit) return snapshotToolkit;
diff --git a/docs/scripts/generate-toolkits.ts b/docs/scripts/generate-toolkits.ts
index 5f13b984e..da4c9b157 100644
--- a/docs/scripts/generate-toolkits.ts
+++ b/docs/scripts/generate-toolkits.ts
@@ -13,14 +13,13 @@ import { join } from 'path';
import { fetchWithRetry } from './fetch-with-retry';
import { requireProductionApiV3Url, stripStagingHosts } from './production-api.mjs';
import { applyToolkitVersions, fetchProductionToolkitVersions } from './toolkit-versions';
+import { isPublicToolkitSlug } from '../lib/public-toolkit-policy';
import { z } from 'zod';
const API_BASE = requireProductionApiV3Url(process.env.COMPOSIO_API_BASE);
const API_KEY = process.env.COMPOSIO_API_KEY;
const OUTPUT_DIR = join(process.cwd(), 'public/data');
-const EXCLUDED_PUBLIC_TOOLKIT_SLUGS = new Set(['test_app']);
-
interface Tool {
slug: string;
name: string;
@@ -375,7 +374,7 @@ export function transformToolkit(raw: unknown): Toolkit {
}
export function shouldPublishToolkit(raw: unknown): boolean {
- return !EXCLUDED_PUBLIC_TOOLKIT_SLUGS.has(transformToolkit(raw).slug);
+ return isPublicToolkitSlug(transformToolkit(raw).slug);
}
async function main() {
diff --git a/docs/tests/static/toolkit-api.test.ts b/docs/tests/static/toolkit-api.test.ts
index 5df9eff49..b076abc52 100644
--- a/docs/tests/static/toolkit-api.test.ts
+++ b/docs/tests/static/toolkit-api.test.ts
@@ -12,6 +12,8 @@ const originalFetch = globalThis.fetch;
const productionPayload = {
slug: 'GitHub',
name: 'GitHub',
+ type: 'native',
+ enabled: true,
composio_managed_auth_schemes: ['oauth2', 'API_KEY'],
auth_config_details: [
{
@@ -118,6 +120,7 @@ describe('fetchToolkitFromProduction', () => {
expect(fetcher.mock.calls[0]?.[1]).toEqual({
headers: { 'Content-Type': 'application/json', 'x-api-key': 'test-key' },
next: { revalidate: 3600 },
+ signal: expect.any(AbortSignal),
});
});
@@ -151,6 +154,8 @@ describe('fetchToolkitFromProduction', () => {
Response.json({
slug: snapshot.slug,
name: snapshot.name,
+ type: 'native',
+ enabled: true,
composio_managed_auth_schemes: snapshot.composioManagedAuthSchemes,
auth_config_details: snapshot.authConfigDetails,
meta: {
@@ -182,6 +187,8 @@ describe('fetchToolkitFromProduction', () => {
Response.json({
slug: 'LENIENT',
name: 'Lenient',
+ type: 'native',
+ enabled: true,
auth_config_details: [
null,
'junk',
@@ -233,6 +240,45 @@ describe('fetchToolkitFromProduction', () => {
}
);
+ test('rejects excluded public toolkit slugs before fetch', async () => {
+ useApiKey();
+ const fetcher = mock(async () => Response.json(productionPayload));
+ globalThis.fetch = fetcher;
+
+ expect(await fetchToolkitFromProduction('TEST_APP')).toBeNull();
+ expect(fetcher).not.toHaveBeenCalled();
+ });
+
+ test.each([
+ ['custom toolkit', { ...productionPayload, slug: 'custom-only', type: 'custom' }],
+ ['disabled toolkit', { ...productionPayload, slug: 'disabled-only', enabled: false }],
+ [
+ 'toolkit without public flags',
+ { slug: 'missing-public-flags', name: 'Missing public flags' },
+ ],
+ ])('rejects a %s returned by the public endpoint', async (_label, payload) => {
+ useApiKey();
+ const fetcher = mock(async () => Response.json(payload));
+ globalThis.fetch = fetcher;
+ spyOn(console, 'warn').mockImplementation(() => {});
+
+ expect(await fetchToolkitFromProduction(payload.slug)).toBeNull();
+ expect(fetcher).toHaveBeenCalledTimes(1);
+ });
+
+ test('bounds the production request to 15 seconds', async () => {
+ useApiKey();
+ const controller = new AbortController();
+ const timeout = spyOn(AbortSignal, 'timeout').mockReturnValue(controller.signal);
+ const fetcher = mock(async () => Response.json(productionPayload));
+ globalThis.fetch = fetcher;
+
+ await fetchToolkitFromProduction('github');
+
+ expect(timeout).toHaveBeenCalledWith(15_000);
+ expect(fetcher.mock.calls[0]?.[1]?.signal).toBe(controller.signal);
+ });
+
test('requires an API key and warns without fetching', async () => {
delete process.env.COMPOSIO_API_KEY;
delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;
@@ -284,6 +330,51 @@ describe('fetchToolkitFromProduction', () => {
expect(warning).toHaveBeenCalledTimes(2);
});
+ test('coalesces concurrent identical live misses into one request', async () => {
+ useApiKey();
+ let release: (() => void) | undefined;
+ const fetcher = mock(async () => {
+ await new Promise<void>(resolve => {
+ release = resolve;
+ });
+ return new Response(null, { status: 404 });
+ });
+ globalThis.fetch = fetcher;
+ spyOn(console, 'warn').mockImplementation(() => {});
+
+ const lookups = Array.from({ length: 20 }, () =>
+ fetchToolkitFromProduction('concurrent-miss')
+ );
+ expect(fetcher).toHaveBeenCalledTimes(1);
+
+ release?.();
+ expect(await Promise.all(lookups)).toEqual(Array.from({ length: 20 }, () => null));
+ expect(fetcher).toHaveBeenCalledTimes(1);
+ });
+
+ test('bounds concurrent lookup bookkeeping', async () => {
+ useApiKey();
+ let release: (() => void) | undefined;
+ const gate = new Promise<void>(resolve => {
+ release = resolve;
+ });
+ const fetcher = mock(async () => {
+ await gate;
+ return new Response(null, { status: 404 });
+ });
+ globalThis.fetch = fetcher;
+ spyOn(console, 'warn').mockImplementation(() => {});
+
+ const lookups = Array.from({ length: 1_025 }, (_, index) =>
+ fetchToolkitFromProduction(`bounded-flight-${index}`)
+ );
+ const evictedLookup = fetchToolkitFromProduction('bounded-flight-0');
+ expect(fetcher).toHaveBeenCalledTimes(1_026);
+
+ release?.();
+ await Promise.all([...lookups, evictedLookup]);
+ });
+
test('bounds negative-cache entries for unique missing slugs', async () => {
useApiKey();
const fetcher = mock(async () => new Response(null, { status: 404 }));
diff --git a/docs/tests/static/toolkit-fallback.test.ts b/docs/tests/static/toolkit-fallback.test.ts
index 337b97443..6c52cce77 100644
--- a/docs/tests/static/toolkit-fallback.test.ts
+++ b/docs/tests/static/toolkit-fallback.test.ts
@@ -66,4 +66,10 @@ describe('resolveToolkit', () => {
expect(await resolveToolkit('__definitely-not-a-toolkit__')).toBeNull();
});
+
+ test('rejects test_app without reading the snapshot or production', async () => {
+ expect(await resolveToolkit('TEST_APP')).toBeNull();
+ expect(getToolkitBySlug).not.toHaveBeenCalled();
+ expect(fetchToolkitFromProduction).not.toHaveBeenCalled();
+ });
});