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

next
ts 576 lines 19.1 KB
Raw
1 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
2 import * as fs from 'node:fs';
3 import * as os from 'node:os';
4 import * as path from 'node:path';
5 import { Auth } from '@composio/client';
6 import {
7 getSDKConfig,
8 getUserApiKeyHeader,
9 resolveCredentialHeaders,
10 resolveSDKCredentials,
11 toClientAuth,
12 toClientScope,
13 withoutSDKOwnedHeaders,
14 } from '../../src/utils/sdk';
15 import { ComposioError } from '../../src/errors/ComposioError';
16 import {
17 ComposioAPIKeyKindError,
18 ComposioNoAPIKeyError,
19 SDKErrorCodes,
20 } from '../../src/errors/SDKErrors';
21 import { DEFAULT_BASE_URL } from '../../src/utils/constants';
22
23 const USER_KEY = 'uak_cliUserKeyValue';
24 const ORG_KEY = 'oak_orgKeyValue';
25 const PROJECT_KEY = 'ak_projectKeyValue';
26 const ENV_KEY = 'ak_envKeyValue';
27 const EXPLICIT_KEY = 'ak_explicitKeyValue';
28
29 describe('getSDKConfig credential resolution', () => {
30 let home: string;
31
32 const userDataPath = () => path.join(home, '.composio', 'user_data.json');
33
34 const writeUserData = (contents: string | Record<string, unknown>) => {
35 fs.mkdirSync(path.dirname(userDataPath()), { recursive: true });
36 fs.writeFileSync(
37 userDataPath(),
38 typeof contents === 'string' ? contents : JSON.stringify(contents)
39 );
40 };
41
42 beforeEach(() => {
43 home = fs.mkdtempSync(path.join(os.tmpdir(), 'composio-sdk-config-'));
44 vi.stubEnv('HOME', home);
45 vi.stubEnv('COMPOSIO_API_KEY', undefined);
46 vi.stubEnv('COMPOSIO_BASE_URL', undefined);
47 vi.stubEnv('COMPOSIO_USER_API_KEY', undefined);
48 vi.stubEnv('COMPOSIO_ORG_API_KEY', undefined);
49 });
50
51 afterEach(() => {
52 vi.unstubAllEnvs();
53 fs.rmSync(home, { recursive: true, force: true });
54 });
55
56 describe('explicit project key', () => {
57 it('wins over the environment and the user config file', () => {
58 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
59 writeUserData({ api_key: PROJECT_KEY });
60
61 expect(getSDKConfig(undefined, EXPLICIT_KEY).apiKey).toBe(EXPLICIT_KEY);
62 });
63
64 it('still works when the user config file holds a CLI user key', () => {
65 writeUserData({ api_key: USER_KEY });
66
67 expect(getSDKConfig(undefined, EXPLICIT_KEY).apiKey).toBe(EXPLICIT_KEY);
68 });
69 });
70
71 describe('omitted project key', () => {
72 it('reads COMPOSIO_API_KEY before the user config file', () => {
73 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
74 writeUserData({ api_key: PROJECT_KEY });
75
76 expect(getSDKConfig().apiKey).toBe(ENV_KEY);
77 });
78
79 it('treats an empty string like an omitted key', () => {
80 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
81
82 expect(getSDKConfig(undefined, '').apiKey).toBe(ENV_KEY);
83 });
84
85 it('falls back to a legacy project key stored in the user config file', () => {
86 writeUserData({ api_key: PROJECT_KEY, base_url: 'https://disk.example.com' });
87
88 expect(getSDKConfig()).toEqual({
89 baseURL: 'https://disk.example.com',
90 apiKey: PROJECT_KEY,
91 });
92 });
93
94 it('keeps accepting stored keys with unfamiliar prefixes', () => {
95 writeUserData({ api_key: 'legacy-format-key' });
96
97 expect(getSDKConfig().apiKey).toBe('legacy-format-key');
98 });
99
100 it('prefers the environment when the user config file only holds a CLI user key', () => {
101 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
102 writeUserData({ api_key: USER_KEY });
103
104 expect(getSDKConfig().apiKey).toBe(ENV_KEY);
105 });
106
107 it('rejects a CLI user key as the only candidate with a redacted kind error', () => {
108 writeUserData({ api_key: USER_KEY });
109
110 let caught: unknown;
111 try {
112 getSDKConfig();
113 } catch (error) {
114 caught = error;
115 }
116
117 expect(caught).toBeInstanceOf(ComposioAPIKeyKindError);
118 const error = caught as ComposioAPIKeyKindError;
119 expect(error.code).toContain(SDKErrorCodes.API_KEY_KIND_MISMATCH);
120 expect(error.possibleFixes.length).toBeGreaterThan(0);
121 const serialized = JSON.stringify({
122 message: error.message,
123 cause: error.cause,
124 possibleFixes: error.possibleFixes,
125 meta: error.meta,
126 });
127 expect(serialized).not.toContain(USER_KEY);
128 expect(serialized).toContain('user_data.json');
129 expect(serialized).toContain('user API key');
130 expect(serialized).toContain('userApiKey');
131 });
132
133 it('does not let a configured user API key rescue an omitted project key', () => {
134 // Omitting the project key keeps its historical meaning: the project key
135 // is required. Only an explicit `null` opts into user-key-only auth.
136 expect(() => getSDKConfig(undefined, undefined, { userApiKey: USER_KEY })).toThrow(
137 ComposioNoAPIKeyError
138 );
139 });
140
141 it('throws the no-key error when nothing is configured', () => {
142 expect(() => getSDKConfig()).toThrow(ComposioNoAPIKeyError);
143 });
144
145 it('reports a malformed user config file without leaking its contents', () => {
146 writeUserData('{"api_key": "' + PROJECT_KEY + '"'); // truncated JSON
147
148 let caught: unknown;
149 try {
150 getSDKConfig();
151 } catch (error) {
152 caught = error;
153 }
154
155 expect(caught).toBeInstanceOf(ComposioNoAPIKeyError);
156 const error = caught as ComposioNoAPIKeyError;
157 expect(String(error.cause)).toContain(userDataPath());
158 expect(String(error.cause)).toMatch(/could not be parsed/i);
159 expect(String(error.cause)).not.toContain(PROJECT_KEY);
160 });
161
162 it('reports an unexpected user config shape without leaking its contents', () => {
163 writeUserData({ api_key: { nested: PROJECT_KEY } });
164
165 let caught: unknown;
166 try {
167 getSDKConfig();
168 } catch (error) {
169 caught = error;
170 }
171
172 expect(caught).toBeInstanceOf(ComposioNoAPIKeyError);
173 const error = caught as ComposioNoAPIKeyError;
174 expect(String(error.cause)).toContain(userDataPath());
175 expect(String(error.cause)).toMatch(/unexpected shape/i);
176 expect(String(error.cause)).not.toContain(PROJECT_KEY);
177 });
178 });
179
180 describe('explicit null project key', () => {
181 it('reads neither the environment nor the user config file', () => {
182 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
183 writeUserData({ api_key: PROJECT_KEY });
184
185 let caught: unknown;
186 try {
187 getSDKConfig(undefined, null);
188 } catch (error) {
189 caught = error;
190 }
191
192 expect(caught).toBeInstanceOf(ComposioNoAPIKeyError);
193 const error = caught as ComposioNoAPIKeyError;
194 expect(error.message).toMatch(/disabled/i);
195 expect(JSON.stringify(error.possibleFixes)).toContain('userApiKey');
196 expect(JSON.stringify(error.possibleFixes)).toContain('x-user-api-key');
197 });
198
199 it('resolves to a null project key when a user API key option is configured', () => {
200 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
201 writeUserData({ api_key: PROJECT_KEY });
202
203 expect(getSDKConfig(undefined, null, { userApiKey: USER_KEY })).toEqual({
204 baseURL: DEFAULT_BASE_URL,
205 apiKey: null,
206 });
207 });
208
209 it('resolves to a null project key when an organization API key option is configured', () => {
210 expect(getSDKConfig(undefined, null, { orgApiKey: ORG_KEY }).apiKey).toBeNull();
211 });
212
213 it('accepts the user API key the client will read from COMPOSIO_USER_API_KEY', () => {
214 vi.stubEnv('COMPOSIO_USER_API_KEY', USER_KEY);
215
216 expect(getSDKConfig(undefined, null).apiKey).toBeNull();
217 });
218
219 it('accepts the organization API key the client will read from COMPOSIO_ORG_API_KEY', () => {
220 vi.stubEnv('COMPOSIO_ORG_API_KEY', ORG_KEY);
221
222 expect(getSDKConfig(undefined, null).apiKey).toBeNull();
223 });
224
225 it('does not read COMPOSIO_USER_API_KEY when the user API key option is null', () => {
226 vi.stubEnv('COMPOSIO_USER_API_KEY', USER_KEY);
227
228 expect(() => getSDKConfig(undefined, null, { userApiKey: null })).toThrow(
229 ComposioNoAPIKeyError
230 );
231 });
232
233 it('does not accept an empty user API key option', () => {
234 expect(() => getSDKConfig(undefined, null, { userApiKey: '' })).toThrow(
235 ComposioNoAPIKeyError
236 );
237 });
238
239 it('resolves to a null project key when a user API key header is configured', () => {
240 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
241 writeUserData({ api_key: PROJECT_KEY });
242
243 expect(
244 getSDKConfig(undefined, null, { defaultHeaders: { 'x-user-api-key': USER_KEY } })
245 ).toEqual({ baseURL: DEFAULT_BASE_URL, apiKey: null });
246 });
247
248 it('resolves to a null project key when an organization API key header is configured', () => {
249 vi.stubEnv('COMPOSIO_API_KEY', ENV_KEY);
250
251 expect(
252 getSDKConfig(undefined, null, { defaultHeaders: { 'X-Org-Api-Key': 'oak_headerKey' } })
253 ).toEqual({ baseURL: DEFAULT_BASE_URL, apiKey: null });
254 expect(() =>
255 getSDKConfig(undefined, null, { defaultHeaders: { 'x-org-api-key': '' } })
256 ).toThrow(ComposioNoAPIKeyError);
257 });
258
259 it('matches the user API key header name case-insensitively', () => {
260 expect(
261 getSDKConfig(undefined, null, { defaultHeaders: { 'X-User-Api-Key': USER_KEY } }).apiKey
262 ).toBeNull();
263 });
264
265 it('does not accept an empty user API key header', () => {
266 expect(() =>
267 getSDKConfig(undefined, null, { defaultHeaders: { 'x-user-api-key': '' } })
268 ).toThrow(ComposioNoAPIKeyError);
269 });
270
271 it('does not treat other default headers as a credential', () => {
272 expect(() =>
273 getSDKConfig(undefined, null, {
274 defaultHeaders: { authorization: `Bearer ${PROJECT_KEY}` },
275 })
276 ).toThrow(ComposioNoAPIKeyError);
277 });
278
279 it('rejects a raw project key header even when a user API key is configured', () => {
280 let caught: unknown;
281 try {
282 getSDKConfig(undefined, null, {
283 userApiKey: USER_KEY,
284 defaultHeaders: { 'x-api-key': PROJECT_KEY },
285 });
286 } catch (error) {
287 caught = error;
288 }
289
290 expect(caught).toBeInstanceOf(ComposioNoAPIKeyError);
291 const error = caught as ComposioNoAPIKeyError;
292 expect(error.message).toBe(
293 'Project API key resolution is disabled, but `defaultHeaders` carries a `x-api-key` entry'
294 );
295 expect(error.possibleFixes[0]).toBe(
296 'Pass the project API key via `apiKey` instead of a raw `x-api-key` default header'
297 );
298 expect(JSON.stringify(error)).not.toContain(PROJECT_KEY);
299 });
300
301 it('matches a raw project key header name case-insensitively', () => {
302 expect(() =>
303 getSDKConfig(undefined, null, {
304 defaultHeaders: { 'X-Api-Key': PROJECT_KEY, 'x-user-api-key': USER_KEY },
305 })
306 ).toThrow(
307 'Project API key resolution is disabled, but `defaultHeaders` carries a `X-Api-Key` entry'
308 );
309 });
310 });
311
312 describe('base URL', () => {
313 it('prefers the explicit value, then the environment, then the user config file', () => {
314 vi.stubEnv('COMPOSIO_BASE_URL', 'https://env.example.com');
315 writeUserData({ api_key: PROJECT_KEY, base_url: 'https://disk.example.com' });
316
317 expect(getSDKConfig('https://explicit.example.com', EXPLICIT_KEY).baseURL).toBe(
318 'https://explicit.example.com'
319 );
320 expect(getSDKConfig(undefined, EXPLICIT_KEY).baseURL).toBe('https://env.example.com');
321
322 vi.stubEnv('COMPOSIO_BASE_URL', undefined);
323 expect(getSDKConfig(undefined, EXPLICIT_KEY).baseURL).toBe('https://disk.example.com');
324 });
325
326 it('falls back to the default base URL', () => {
327 expect(getSDKConfig(undefined, EXPLICIT_KEY).baseURL).toBe(DEFAULT_BASE_URL);
328 });
329 });
330 });
331
332 describe('getUserApiKeyHeader', () => {
333 it('matches the header name case-insensitively and keeps the original key', () => {
334 expect(getUserApiKeyHeader({ 'X-User-Api-Key': USER_KEY })).toEqual({
335 name: 'X-User-Api-Key',
336 value: USER_KEY,
337 });
338 });
339
340 it('ignores a header whose value is not a non-empty string', () => {
341 const untyped = (value: unknown) =>
342 ({ 'x-user-api-key': value }) as unknown as Record<string, string>;
343
344 expect(getUserApiKeyHeader(untyped(''))).toBeUndefined();
345 expect(getUserApiKeyHeader(untyped(undefined))).toBeUndefined();
346 expect(getUserApiKeyHeader(untyped(null))).toBeUndefined();
347 expect(getUserApiKeyHeader(untyped(42))).toBeUndefined();
348 expect(getUserApiKeyHeader(untyped([USER_KEY]))).toBeUndefined();
349 expect(getUserApiKeyHeader(undefined)).toBeUndefined();
350 });
351 });
352
353 describe('resolveCredentialHeaders', () => {
354 it('prefers the x-user-api-key default header over the configured keys', () => {
355 expect(
356 resolveCredentialHeaders({
357 apiKey: PROJECT_KEY,
358 userApiKey: USER_KEY,
359 defaultHeaders: { 'X-User-Api-Key': 'uak_headerKey' },
360 })
361 ).toEqual({ 'x-user-api-key': 'uak_headerKey' });
362 });
363
364 it('sends the project key when no credential header is placed', () => {
365 expect(
366 resolveCredentialHeaders({ apiKey: PROJECT_KEY, userApiKey: USER_KEY, defaultHeaders: {} })
367 ).toEqual({ 'x-api-key': PROJECT_KEY });
368 });
369
370 it('sends the resolved user key when the project key is disabled', () => {
371 expect(
372 resolveCredentialHeaders({ apiKey: null, userApiKey: USER_KEY, defaultHeaders: undefined })
373 ).toEqual({ 'x-user-api-key': USER_KEY });
374 });
375
376 it('sends the organization key only when no project or user key is held', () => {
377 expect(
378 resolveCredentialHeaders({
379 apiKey: null,
380 userApiKey: null,
381 orgApiKey: 'oak_orgKey',
382 defaultHeaders: undefined,
383 })
384 ).toEqual({ 'x-org-api-key': 'oak_orgKey' });
385 expect(
386 resolveCredentialHeaders({
387 apiKey: null,
388 userApiKey: USER_KEY,
389 orgApiKey: 'oak_orgKey',
390 defaultHeaders: undefined,
391 })
392 ).toEqual({ 'x-user-api-key': USER_KEY });
393 });
394
395 it('ignores an empty credential header and returns nothing without a credential', () => {
396 expect(
397 resolveCredentialHeaders({
398 apiKey: null,
399 userApiKey: null,
400 defaultHeaders: { 'x-user-api-key': '' },
401 })
402 ).toEqual({});
403 });
404 });
405
406 describe('resolveSDKCredentials', () => {
407 beforeEach(() => {
408 vi.stubEnv('COMPOSIO_USER_API_KEY', undefined);
409 vi.stubEnv('COMPOSIO_ORG_API_KEY', undefined);
410 });
411
412 afterEach(() => {
413 vi.unstubAllEnvs();
414 });
415
416 it('keeps the resolved project key and the explicit alternate keys', () => {
417 expect(
418 resolveSDKCredentials({ apiKey: PROJECT_KEY, userApiKey: USER_KEY, orgApiKey: ORG_KEY })
419 ).toEqual({ apiKey: PROJECT_KEY, userApiKey: USER_KEY, orgApiKey: ORG_KEY });
420 });
421
422 it('falls back to the environment for omitted alternate keys, and not for null ones', () => {
423 vi.stubEnv('COMPOSIO_USER_API_KEY', 'uak_env');
424 vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_env');
425
426 expect(resolveSDKCredentials({ apiKey: PROJECT_KEY })).toEqual({
427 apiKey: PROJECT_KEY,
428 userApiKey: 'uak_env',
429 orgApiKey: 'oak_env',
430 });
431 expect(
432 resolveSDKCredentials({ apiKey: PROJECT_KEY, userApiKey: null, orgApiKey: null })
433 ).toEqual({ apiKey: PROJECT_KEY, userApiKey: null, orgApiKey: null });
434 });
435
436 it('folds an x-user-api-key header in as the only user credential', () => {
437 expect(
438 resolveSDKCredentials({
439 apiKey: PROJECT_KEY,
440 userApiKey: 'uak_option',
441 orgApiKey: ORG_KEY,
442 defaultHeaders: { 'X-User-Api-Key': USER_KEY },
443 })
444 ).toEqual({ apiKey: null, userApiKey: USER_KEY, orgApiKey: ORG_KEY });
445 });
446
447 it('folds an x-org-api-key header in as the only credential', () => {
448 expect(
449 resolveSDKCredentials({
450 apiKey: PROJECT_KEY,
451 userApiKey: USER_KEY,
452 defaultHeaders: { 'x-org-api-key': ORG_KEY },
453 })
454 ).toEqual({ apiKey: null, userApiKey: null, orgApiKey: ORG_KEY });
455 });
456
457 it('folds an x-api-key header in as the project key', () => {
458 expect(
459 resolveSDKCredentials({
460 apiKey: EXPLICIT_KEY,
461 userApiKey: USER_KEY,
462 defaultHeaders: { 'x-api-key': PROJECT_KEY },
463 })
464 ).toEqual({ apiKey: PROJECT_KEY, userApiKey: USER_KEY, orgApiKey: null });
465 });
466
467 it('ignores empty credential headers', () => {
468 expect(
469 resolveSDKCredentials({
470 apiKey: PROJECT_KEY,
471 defaultHeaders: { 'x-user-api-key': '', 'x-org-api-key': '' },
472 })
473 ).toEqual({ apiKey: PROJECT_KEY, userApiKey: null, orgApiKey: null });
474 });
475
476 it('rejects two credential headers without echoing either value', () => {
477 const resolve = () =>
478 resolveSDKCredentials({
479 apiKey: PROJECT_KEY,
480 defaultHeaders: { 'x-user-api-key': USER_KEY, 'X-Org-Api-Key': ORG_KEY },
481 });
482
483 expect(resolve).toThrow(ComposioError);
484 expect(resolve).toThrow('`defaultHeaders` carries more than one credential header');
485 const error = (() => {
486 try {
487 resolve();
488 } catch (caught) {
489 return caught as ComposioError;
490 }
491 })();
492 expect(JSON.stringify({ message: error?.message, cause: error?.cause })).not.toMatch(
493 /uak_|oak_/
494 );
495 });
496 });
497
498 describe('toClientAuth', () => {
499 it.each([
500 [
501 'a project key alone',
502 { apiKey: PROJECT_KEY, userApiKey: null, orgApiKey: null },
503 Auth.project(PROJECT_KEY),
504 ],
505 [
506 'a project key and a user key',
507 { apiKey: PROJECT_KEY, userApiKey: USER_KEY, orgApiKey: null },
508 Auth.auto({ project: PROJECT_KEY, user: USER_KEY }),
509 ],
510 [
511 'a project key and an organization key',
512 { apiKey: PROJECT_KEY, userApiKey: null, orgApiKey: ORG_KEY },
513 Auth.auto({ project: PROJECT_KEY, organization: ORG_KEY }),
514 ],
515 [
516 'all three keys',
517 { apiKey: PROJECT_KEY, userApiKey: USER_KEY, orgApiKey: ORG_KEY },
518 Auth.auto({ project: PROJECT_KEY, user: USER_KEY, organization: ORG_KEY }),
519 ],
520 [
521 'a user key without a project key',
522 { apiKey: null, userApiKey: USER_KEY, orgApiKey: null },
523 Auth.user(USER_KEY),
524 ],
525 [
526 'a user and an organization key without a project key',
527 { apiKey: null, userApiKey: USER_KEY, orgApiKey: ORG_KEY },
528 Auth.user(USER_KEY),
529 ],
530 [
531 'an organization key alone',
532 { apiKey: null, userApiKey: null, orgApiKey: ORG_KEY },
533 Auth.organization(ORG_KEY),
534 ],
535 ])('maps %s', (_name, credentials, expected) => {
536 expect(toClientAuth(credentials)).toEqual(expected);
537 });
538
539 it('refuses to build auth without any credential', () => {
540 expect(() => toClientAuth({ apiKey: null, userApiKey: null, orgApiKey: null })).toThrow(
541 ComposioNoAPIKeyError
542 );
543 });
544 });
545
546 describe('toClientScope', () => {
547 it('maps a resolved scope to the client scope', () => {
548 expect(toClientScope({ orgId: 'org_1', projectId: 'proj_1' })).toEqual({
549 organizationId: 'org_1',
550 projectId: 'proj_1',
551 });
552 });
553
554 it('leaves an unscoped instance unscoped', () => {
555 expect(toClientScope({})).toBeUndefined();
556 });
557 });
558
559 describe('withoutSDKOwnedHeaders', () => {
560 it('drops credential and scope headers in any letter case and keeps the rest', () => {
561 expect(
562 withoutSDKOwnedHeaders({
563 'X-Api-Key': PROJECT_KEY,
564 'x-user-api-key': USER_KEY,
565 'X-ORG-API-KEY': ORG_KEY,
566 'x-org-id': 'org_1',
567 'X-Project-Id': 'proj_1',
568 'x-request-id': 'req-1',
569 })
570 ).toEqual({ 'x-request-id': 'req-1' });
571 });
572
573 it('keeps undefined as undefined', () => {
574 expect(withoutSDKOwnedHeaders(undefined)).toBeUndefined();
575 });
576 });