@devries-cameron20 / composio Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
ts 107 lines 4.17 KB
Raw
1 /**
2 * `@composio/cli-keyring` — cross-platform OS credential storage for
3 * the Composio CLI. Structurally modeled after
4 * [keyring-rs](https://github.com/open-source-cooperative/keyring-rs)
5 * but implemented as a thin shell over OS primitives so we own every
6 * byte of the execution surface and never depend on a third-party
7 * native module.
8 *
9 * Backends:
10 * - **macOS (Bun runtime)**: direct Security.framework calls via
11 * `bun:ffi`. ~1ms reads, no subprocess overhead, ACL = allow-any
12 * (upgrade-stable; identical threat model to the subprocess
13 * backend until the CLI is Developer ID-signed).
14 * - **macOS (Node runtime / fallback)**: `/usr/bin/security`
15 * subprocess. Same semantics, ~25ms reads.
16 * - **Linux**: `secret-tool` subprocess against the freedesktop
17 * Secret Service API, with keyring-rs-compatible attribute names.
18 * - **Windows (Bun runtime)**: Credential Manager via `bun:ffi`
19 * calls into `advapi32.dll`. There is no Node fallback.
20 *
21 * Typical usage:
22 *
23 * ```ts
24 * import { Entry, setDefaultStore, createDefaultStore } from '@composio/cli-keyring';
25 *
26 * setDefaultStore(await createDefaultStore());
27 *
28 * const entry = new Entry('com.composio.cli', 'default');
29 * await entry.setPassword(apiKey);
30 * const stored = await entry.getPassword();
31 * await entry.deleteCredential();
32 * ```
33 */
34
35 export { Entry } from './core/entry';
36 export { KeyringError, type KeyringErrorDetails, type KeyringErrorKind } from './core/errors';
37 export { CredentialPersistence } from './core/persistence';
38 export {
39 type CredentialStore,
40 type EntryModifiers,
41 setDefaultStore,
42 unsetDefaultStore,
43 getDefaultStore,
44 hasDefaultStore,
45 } from './core/store';
46
47 import type { CredentialStore } from './core/store';
48 import { createMacOSStore, createMacOSStoreSync, type MacOSBackend } from './stores/macos-security';
49 import { LinuxSecretToolStore } from './stores/linux-secret-tool';
50 import { UnsupportedPlatformStore } from './stores/unsupported';
51
52 /**
53 * Instantiate the native store for the current platform (async). On
54 * macOS under Bun this resolves to the fast FFI backend; under Node
55 * (typically tests or tools that import this package without Bun) it
56 * falls back to the `/usr/bin/security` subprocess backend. On Linux
57 * it always returns the `secret-tool` subprocess backend. On Windows
58 * under Bun it returns the Credential Manager backend. Unsupported
59 * platforms, and Windows under Node, return a store whose operations
60 * throw `NoStorageAccess`.
61 *
62 * Call this once at process startup, pass the result to
63 * `setDefaultStore`, and use `new Entry(service, user)` everywhere.
64 */
65 export async function createDefaultStore(
66 options: { macOSBackend?: MacOSBackend } = {}
67 ): Promise<CredentialStore> {
68 switch (process.platform) {
69 case 'darwin':
70 return await createMacOSStore(options.macOSBackend ?? 'auto');
71 case 'linux':
72 return new LinuxSecretToolStore();
73 case 'win32': {
74 if (typeof (globalThis as { Bun?: unknown }).Bun === 'undefined') {
75 return new UnsupportedPlatformStore('win32 without Bun');
76 }
77 const mod = await import('./stores/windows-credential-ffi');
78 return new mod.WindowsCredentialFFIStore();
79 }
80 default:
81 return new UnsupportedPlatformStore(process.platform);
82 }
83 }
84
85 /**
86 * Synchronous fallback that never returns an FFI backend, so Windows is
87 * unsupported here —
88 * useful for callers that can't await at construction time (e.g. the
89 * Effect.ts `Layer.sync` variant) and are willing to accept the
90 * subprocess overhead. The async `createDefaultStore()` is strongly
91 * preferred in the CLI's hot path.
92 */
93 export function createDefaultStoreSync(): CredentialStore {
94 switch (process.platform) {
95 case 'darwin':
96 return createMacOSStoreSync();
97 case 'linux':
98 return new LinuxSecretToolStore();
99 default:
100 return new UnsupportedPlatformStore(process.platform);
101 }
102 }
103
104 export { createMacOSStore, createMacOSStoreSync, type MacOSBackend } from './stores/macos-security';
105 export { MacOSSecuritySubprocessStore } from './stores/macos-security-subprocess';
106 export { LinuxSecretToolStore } from './stores/linux-secret-tool';
107 export { UnsupportedPlatformStore } from './stores/unsupported';