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 | # @composio/cli-keyring |
| 2 | |
| 3 | Cross-platform OS credential storage for the Composio CLI. |
| 4 | |
| 5 | Structurally modeled on [keyring-rs](https://github.com/open-source-cooperative/keyring-rs) (the `keyring-core` + per-platform store-crate split), but implemented as a thin shell over OS primitives so we own every byte of the execution surface and never depend on a third-party native module. |
| 6 | |
| 7 | ## Why this exists |
| 8 | |
| 9 | Before: `~/.composio/user_data.json` held the Composio API key as a plaintext string. Any agent (Claude Code, etc.) with file-read permission could silently `Read` the file and exfiltrate the key in a single, unobservable tool call — then use it to take actions on the Composio platform. |
| 10 | |
| 11 | After: the API key lives in the OS credential store (macOS Keychain / Linux Secret Service). Reading it requires either (a) an in-process call to Security.framework / D-Bus — which only the composio binary makes, and which agents cannot invoke from their own processes — or (b) shelling out to `/usr/bin/security` / `secret-tool`, which is a visible Bash tool call the user can deny. **Silent exfil becomes visible exfil**: the gate is the agent's shell-permission prompt, not a filesystem read that leaves no trace. |
| 12 | |
| 13 | ## Architecture |
| 14 | |
| 15 | ``` |
| 16 | src/ |
| 17 | ├── core/ # keyring-rs keyring-core port |
| 18 | │ ├── entry.ts # Entry class — (service, user, modifiers) |
| 19 | │ ├── errors.ts # KeyringError, 11-variant discriminated union |
| 20 | │ ├── persistence.ts # CredentialPersistence enum |
| 21 | │ └── store.ts # CredentialStore interface + default-store registry |
| 22 | └── stores/ # per-platform backends |
| 23 | ├── macos-security.ts # runtime picker (Bun → FFI, Node → subprocess) |
| 24 | ├── macos-security-ffi.ts # direct Security.framework via bun:ffi (fast path) |
| 25 | ├── macos-security-subprocess.ts# /usr/bin/security subprocess fallback |
| 26 | ├── linux-secret-tool.ts # secret-tool subprocess |
| 27 | ├── windows-credential-ffi.ts # Credential Manager via bun:ffi (advapi32.dll) |
| 28 | ├── unsupported.ts # BSD, Windows outside Bun, … — throws NoStorageAccess |
| 29 | └── shared.ts # subprocess helpers + base64 on-disk encoding |
| 30 | ``` |
| 31 | |
| 32 | The core is intentionally Promise-based and depends on neither Effect nor any other framework. Effect-based callers (the Composio CLI) import `@composio/cli-keyring/effect` for a `KeyringService` layer. |
| 33 | |
| 34 | ## Backends and runtime dispatch |
| 35 | |
| 36 | | platform | runtime | backend | read latency | |
| 37 | | -------- | ------- | ------------------------------------ | ------------ | |
| 38 | | macOS | Bun | `SecItem*` via `bun:ffi` | **~1.4ms** | |
| 39 | | macOS | Node | `/usr/bin/security` subprocess | ~22ms | |
| 40 | | Linux | both | `secret-tool` subprocess (libsecret) | ~15–40ms | |
| 41 | | Windows | Bun | `Cred*` via `bun:ffi` | not measured | |
| 42 | | Windows | Node | throws `NoStorageAccess` | — | |
| 43 | | BSD | both | throws `NoStorageAccess` | — | |
| 44 | |
| 45 | The Composio CLI ships as a compiled Bun binary, so production reads always hit the FFI path. Node is the fallback for vitest-under-Node, dev tools, and anyone importing the package outside the CLI's runtime. |
| 46 | |
| 47 | ## Performance |
| 48 | |
| 49 | Measured 100 iterations on an Apple Silicon Mac with a warm login keychain: |
| 50 | |
| 51 | | operation | subprocess | FFI (bun:ffi) | speedup | |
| 52 | | ------------------ | ---------- | ------------- | ------- | |
| 53 | | `getPassword` mean | 22.25ms | **1.46ms** | **15×** | |
| 54 | | `getPassword` p50 | 19.95ms | **1.14ms** | **18×** | |
| 55 | | `getPassword` p99 | 88.72ms | **7.39ms** | **12×** | |
| 56 | | `setPassword` mean | 26.61ms | **16.18ms** | 1.6× | |
| 57 | |
| 58 | For reference, the legacy plaintext read was `fs.readFileSync` + `JSON.parse` at ~0.01ms. The CLI's `ComposioUserContext` resolves the key **exactly once per process** (in-memory closure cache), so most commands pay ~1.4ms startup overhead over the plaintext baseline — well below perception, and amortized to zero for commands that do any network I/O. |
| 59 | |
| 60 | ## Security model |
| 61 | |
| 62 | ### Tagged pointers |
| 63 | |
| 64 | CoreFoundation uses tagged pointers — short `CFString` and other small types pack their data directly into the pointer bits, producing values above 2^53 that cannot round-trip through JavaScript `number`. Every CF/Sec FFI type in this package is declared as `FFIType.u64` and trafficked as `bigint` to preserve full 64-bit fidelity. See the doc block at the top of `macos-security-ffi.ts` for details. |
| 65 | |
| 66 | ### ACL story (macOS) |
| 67 | |
| 68 | Keychain items have an **Access Control List** — a per-item permission record that lists which binaries can read the item without a GUI prompt. |
| 69 | |
| 70 | | ACL populated with | upgrade-stable? | gates agents? | |
| 71 | | ------------------------------------------ | --------------------------- | ------------- | |
| 72 | | `[/usr/bin/security]` (subprocess default) | yes | no | |
| 73 | | `[composio (ad-hoc signed)]` | **no — breaks every build** | yes | |
| 74 | | `[composio (Developer ID signed)]` | yes | **yes** | |
| 75 | | **allow-any** (current FFI choice) | yes | no | |
| 76 | |
| 77 | The composio CLI is currently ad-hoc signed (`Signature=adhoc`), so a per-binary ACL would invalidate the Keychain entry on every `composio upgrade` and trigger a user dialog. To avoid that, the FFI backend builds an **allow-any** ACL (the Security.framework equivalent of `security add-generic-password -A`): `SecAccessCreate` → `SecAccessCopyACLList` → `SecACLSetSimpleContents` with `applicationList=NULL` and `selector={version=0x0101, flags=0}`. The ACL is upgrade-stable because no binary identity is recorded. |
| 78 | |
| 79 | This yields the same threat model as the subprocess backend: silent file exfil becomes visible shell-tool exfil, but the OS doesn't gate reads to our binary specifically. **Upgrading to per-binary ACLs requires the composio CLI to be signed with a stable Developer ID** — that's a separate operational change (Apple Developer Program cert, notarization, CI signing step). When it lands, `buildAllowAnyAccess` gets replaced with a `buildComposioOnlyAccess` variant in a single file; no public-API churn. |
| 80 | |
| 81 | ### Linux |
| 82 | |
| 83 | The freedesktop Secret Service API has no per-binary ACL concept at all. Any process with the same UID can read any unlocked item from the session's default collection, with zero prompting. FFI into `libsecret` would give no additional threat-model protection over the `secret-tool` subprocess — just complexity. Subprocess is the correct choice on Linux. |
| 84 | |
| 85 | ## On-disk encoding |
| 86 | |
| 87 | Both backends base64-encode every secret before handing it to the OS and prefix the encoded string with `b64:`. Reasons: |
| 88 | |
| 89 | - `security -w` takes the password on argv and cannot carry binary bytes (NUL bytes truncate; newlines break parsing). |
| 90 | - `secret-tool store` reads one line from stdin via `g_io_channel_read_line`, which can't carry NUL bytes or embedded newlines. |
| 91 | - The FFI backend stores binary-safe `CFData` directly, but encoding consistently across backends means items written by the subprocess/Node path are readable by the FFI/Bun path and vice versa. |
| 92 | |
| 93 | Downside: credentials written by this package are not readable as raw bytes by other keyring-rs consumers sharing the same keychain namespace (they'd see `b64:<base64>` instead of the original value). For the CLI's API-key use case this is irrelevant — only `@composio/cli-keyring` reads them. |
| 94 | |
| 95 | ## Linux attribute conventions (keyring-rs interop) |
| 96 | |
| 97 | When `secret-tool` creates an item, the attribute keys match keyring-rs exactly: `{service, username, target}` with `target` naming the Secret Service collection (default `"default"`). Label defaults to `keyring:{user}@{service}`. This means any other Rust tool using keyring-rs on the same system can _discover_ our items (same attribute keys, interoperable lookups), even though the stored value is our `b64:`-prefixed format. |
| 98 | |
| 99 | ## Usage |
| 100 | |
| 101 | ```ts |
| 102 | import { Entry, createDefaultStore, setDefaultStore } from '@composio/cli-keyring'; |
| 103 | |
| 104 | // One-time process startup: |
| 105 | setDefaultStore(await createDefaultStore()); |
| 106 | |
| 107 | // Anywhere: |
| 108 | const entry = new Entry('com.composio.cli', 'default'); |
| 109 | await entry.setPassword(apiKey); |
| 110 | const stored = await entry.getPassword(); |
| 111 | await entry.deleteCredential(); |
| 112 | ``` |
| 113 | |
| 114 | With Effect.ts: |
| 115 | |
| 116 | ```ts |
| 117 | import { Effect, Layer } from 'effect'; |
| 118 | import { KeyringService, KeyringLive } from '@composio/cli-keyring/effect'; |
| 119 | |
| 120 | const program = Effect.gen(function* () { |
| 121 | const keyring = yield* KeyringService; |
| 122 | yield* keyring.setPassword('com.composio.cli', 'default', apiKey); |
| 123 | }); |
| 124 | |
| 125 | program.pipe(Effect.provide(KeyringLive)); |
| 126 | ``` |
| 127 | |
| 128 | ## Error handling |
| 129 | |
| 130 | Every operation throws `KeyringError` with a discriminated `details` field. Pattern-match on the kind, don't catch generically: |
| 131 | |
| 132 | ```ts |
| 133 | try { |
| 134 | const key = await entry.getPassword(); |
| 135 | } catch (err) { |
| 136 | if (err instanceof KeyringError) { |
| 137 | switch (err.kind) { |
| 138 | case 'NoEntry': |
| 139 | /* user not logged in yet */ break; |
| 140 | case 'NoStorageAccess': |
| 141 | /* keyring unavailable — fall back */ break; |
| 142 | case 'BadEncoding': |
| 143 | /* stored bytes aren't valid UTF-8 */ break; |
| 144 | // ... |
| 145 | } |
| 146 | } |
| 147 | } |
| 148 | ``` |
| 149 | |
| 150 | Full variant list (mirroring `keyring-core/src/error.rs`): `PlatformFailure`, `NoStorageAccess`, `NoEntry`, `BadEncoding`, `BadDataFormat`, `BadStoreFormat`, `TooLong`, `Invalid`, `Ambiguous`, `NoDefaultStore`, `NotSupportedByStore`. |
| 151 | |
| 152 | ## Integration plan (Composio CLI migration) |
| 153 | |
| 154 | Tracked in a follow-up PR stacked on top of this one. Summary of the intended `ComposioUserContextLive` behavior: |
| 155 | |
| 156 | ### Caching (Option A: in-process memoization, no cross-process cache) |
| 157 | |
| 158 | - `ComposioUserContext` resolves the API key once at layer-build time via `entry.getPassword()` and holds it in a closure variable for the remainder of the process (piggybacks on the existing `userData` single-resolve pattern — no new cache layer). |
| 159 | - For short-lived commands this is ~1.4ms extra startup. For the `composio execute` / `composio run` hot path it's free after the first lookup. |
| 160 | - **No cross-process daemon**: FFI at ~1.4ms per cold process is cheap enough that tight scripting (`composio execute` in a shell loop) stays under 140ms of keychain overhead across 100 invocations. |
| 161 | - **Agent threat model**: a JavaScript closure inside the composio process is unreachable to other processes on the system without `ptrace`. The key never lands in an env var, never writes to a tempfile, never hits disk. |
| 162 | |
| 163 | ### Fallback chain |
| 164 | |
| 165 | ``` |
| 166 | login(apiKey): |
| 167 | if config.dangerouslySaveApiKeyInUserConfig === true: |
| 168 | → write apiKey to user_data.json.api_key (plaintext; skip keyring entirely) |
| 169 | else: |
| 170 | try keyring.setPassword(apiKey) |
| 171 | success: write user_data.json with api_key = null |
| 172 | NoStorageAccess: fall back to user_data.json.api_key + one-time warning |
| 173 | |
| 174 | init (read): |
| 175 | read user_data.json |
| 176 | if config.dangerouslySaveApiKeyInUserConfig === true: |
| 177 | → use user_data.json.api_key directly, never touch keyring |
| 178 | else: |
| 179 | try keyring.getPassword() |
| 180 | success: use it |
| 181 | NoEntry: |
| 182 | if user_data.json.api_key is set (legacy): |
| 183 | → use it, migrate to keyring, rewrite user_data.json with api_key = null |
| 184 | else: |
| 185 | → user is logged out |
| 186 | NoStorageAccess: |
| 187 | → fall back to user_data.json.api_key with a one-time warning |
| 188 | |
| 189 | logout: |
| 190 | best-effort keyring.deleteCredential() (swallow NoEntry / NoStorageAccess) |
| 191 | rewrite user_data.json with api_key = null |
| 192 | ``` |
| 193 | |
| 194 | ### The `dangerouslySaveApiKeyInUserConfig` escape hatch |
| 195 | |
| 196 | Lives in `CliUserConfig` (`~/.composio/config.json`), alongside existing `experimentalFeatures` / `artifactDirectory`. **Opt-in, not a CLI flag, not advertised in `--help`** — users who need it edit `config.json` themselves. |
| 197 | |
| 198 | ```json |
| 199 | { |
| 200 | "experimental_features": {}, |
| 201 | "dangerously_save_api_key_in_user_config": true |
| 202 | } |
| 203 | ``` |
| 204 | |
| 205 | Snake-case on disk (`dangerously_save_api_key_in_user_config`), camelCase in the TypeScript schema. The name follows React's `dangerouslySetInnerHTML` precedent: explicit about the risk, defaults to `false`. |
| 206 | |
| 207 | **Why it exists**: |
| 208 | |
| 209 | 1. **Headless Linux** — no D-Bus session, `secret-tool` unavailable or unreliable in containers/CI/SSH-without-forwarding. Users who can't get the keyring working should have a clean opt-out rather than fighting `DBUS_SESSION_BUS_ADDRESS`. |
| 210 | 2. **Docker / devcontainers / CI** — same story; ephemeral environments where the keyring is either absent or actively harmful. |
| 211 | 3. **Power users who audit their config** — explicit opt-in with a name that makes the risk legible in `cat config.json`. |
| 212 | |
| 213 | The `@composio/cli-keyring` package itself has no knowledge of this flag. The CLI's `ComposioUserContextLive` checks the flag at layer-build time and skips the keyring entirely when set. Package-CLI separation stays clean. |
| 214 | |
| 215 | ## Known limitations |
| 216 | |
| 217 | - **macOS ACL is allow-any until Developer ID signing lands.** Subprocess-equivalent threat model: silent exfil → visible shell-tool exfil, but not per-binary gating. See the "ACL story" section above for the path to fix this. |
| 218 | - **Linux has no per-binary ACL at any layer** of the stack. Best achievable on Linux today is the `secret-tool` Bash-prompt gate. |
| 219 | - **`getAttributes` / `updateAttributes` / `search`** from keyring-rs's API surface are not implemented; they throw `NotSupportedByStore`. Add later if a caller needs them. |
| 220 | - **macOS non-`User` keychain domains** (System, Common, Dynamic) are not supported; modifier throws `NotSupportedByStore`. |
| 221 | |
| 222 | ## Running the tests |
| 223 | |
| 224 | ```bash |
| 225 | # Unit tests (Node, no keychain access) |
| 226 | pnpm test |
| 227 | |
| 228 | # E2E against the real macOS keychain via subprocess backend (Node) |
| 229 | COMPOSIO_KEYRING_E2E=1 pnpm test |
| 230 | |
| 231 | # E2E against the real macOS keychain via FFI backend (Bun) |
| 232 | COMPOSIO_KEYRING_E2E=1 bun --bun x vitest run test/ffi.test.ts |
| 233 | ``` |
| 234 | |
| 235 | The E2E suites use UUID-suffixed service names so parallel runs and leftover entries from crashed runs never collide with real credentials. |