@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, 06:00 UTC

next
md 235 lines 13.8 KB
Rendered Raw
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.