Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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'; |