@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 128 lines 5.19 KB
Raw
1 /**
2 * Error model for `@composio/cli-keyring`.
3 *
4 * Mirrors the 11-variant enum from `keyring-core/src/error.rs` in
5 * https://github.com/open-source-cooperative/keyring-core so that this
6 * package can act as a structural TypeScript port of keyring-rs for the
7 * backends we care about (macOS Keychain via `security`, Linux Secret
8 * Service via `secret-tool`).
9 */
10
11 import type { Entry } from './entry';
12
13 /**
14 * Discriminated union of every error condition a `CredentialStore` may
15 * surface. Prefer pattern-matching on `kind` rather than catching
16 * `KeyringError` generically so handlers remain explicit about what they
17 * tolerate (`NoEntry` on first login, for example).
18 */
19 export type KeyringErrorDetails =
20 /** The underlying store returned an unexpected runtime failure. */
21 | { readonly kind: 'PlatformFailure'; readonly cause: unknown }
22 /**
23 * The store is present but inaccessible: keychain locked, D-Bus
24 * session missing, user declined an unlock prompt, `secret-tool`
25 * not installed, etc. Callers should treat this as "try a fallback
26 * or warn the user" rather than "retry".
27 */
28 | { readonly kind: 'NoStorageAccess'; readonly cause: unknown }
29 /** No credential exists for the (service, user) specifier. */
30 | { readonly kind: 'NoEntry' }
31 /** Retrieved bytes were not valid UTF-8 (only raised by `getPassword`). */
32 | { readonly kind: 'BadEncoding'; readonly bytes: Uint8Array }
33 /** Retrieved bytes didn't match the store's expected blob format. */
34 | { readonly kind: 'BadDataFormat'; readonly bytes: Uint8Array; readonly cause: unknown }
35 /** Store metadata itself is corrupted. */
36 | { readonly kind: 'BadStoreFormat'; readonly detail: string }
37 /** An attribute value exceeded the platform length limit. */
38 | { readonly kind: 'TooLong'; readonly attr: string; readonly limit: number }
39 /**
40 * A parameter violated a store-specific rule — e.g. an empty `service`
41 * or `user` on macOS (empty strings act as wildcards in Keychain
42 * Services and must be rejected locally before we spawn).
43 */
44 | { readonly kind: 'Invalid'; readonly param: string; readonly reason: string }
45 /**
46 * Multiple credentials matched the (service, user) specifier. Only
47 * possible on Secret Service; generic-password items on macOS are
48 * unique per (service, account, keychain).
49 */
50 | { readonly kind: 'Ambiguous'; readonly matches: readonly Entry[] }
51 /** No process-global default store has been registered. */
52 | { readonly kind: 'NoDefaultStore' }
53 /** The active store does not implement the requested operation. */
54 | { readonly kind: 'NotSupportedByStore'; readonly operation: string };
55
56 export type KeyringErrorKind = KeyringErrorDetails['kind'];
57
58 /**
59 * The single error type thrown by every operation on `Entry` or a
60 * `CredentialStore`. `details` carries the variant-specific payload;
61 * the base `message` is derived for human logs but callers should
62 * branch on `details.kind`.
63 */
64 export class KeyringError extends Error {
65 readonly details: KeyringErrorDetails;
66
67 constructor(details: KeyringErrorDetails) {
68 super(KeyringError.formatMessage(details));
69 this.name = 'KeyringError';
70 this.details = details;
71 // Preserve the original cause chain for PlatformFailure / NoStorageAccess
72 // so `console.error(err)` prints the underlying reason.
73 if ('cause' in details && details.cause !== undefined) {
74 (this as { cause?: unknown }).cause = details.cause;
75 }
76 }
77
78 get kind(): KeyringErrorKind {
79 return this.details.kind;
80 }
81
82 /**
83 * Convenience predicate — avoids `err instanceof KeyringError && err.kind === 'NoEntry'`
84 * at every call site.
85 */
86 is<K extends KeyringErrorKind>(
87 kind: K
88 ): this is KeyringError & { readonly details: Extract<KeyringErrorDetails, { kind: K }> } {
89 return this.details.kind === kind;
90 }
91
92 private static formatMessage(d: KeyringErrorDetails): string {
93 switch (d.kind) {
94 case 'NoEntry':
95 return 'No matching credential was found in the store.';
96 case 'NoDefaultStore':
97 return 'No default keyring store has been registered for this process.';
98 case 'PlatformFailure':
99 return `Keyring store failure: ${describe(d.cause)}`;
100 case 'NoStorageAccess':
101 return `Keyring store is unavailable: ${describe(d.cause)}`;
102 case 'BadEncoding':
103 return `Stored credential is not valid UTF-8 (${d.bytes.byteLength} bytes).`;
104 case 'BadDataFormat':
105 return `Stored credential is malformed: ${describe(d.cause)}`;
106 case 'BadStoreFormat':
107 return `Credential store metadata is corrupted: ${d.detail}`;
108 case 'TooLong':
109 return `Attribute "${d.attr}" exceeds the platform limit of ${d.limit} bytes.`;
110 case 'Invalid':
111 return `Invalid parameter "${d.param}": ${d.reason}`;
112 case 'Ambiguous':
113 return `Credential specifier matched ${d.matches.length} items; expected exactly one.`;
114 case 'NotSupportedByStore':
115 return `Operation "${d.operation}" is not supported by the active keyring store.`;
116 }
117 }
118 }
119
120 function describe(cause: unknown): string {
121 if (cause instanceof Error) return cause.message;
122 if (typeof cause === 'string') return cause;
123 try {
124 return JSON.stringify(cause);
125 } catch {
126 return String(cause);
127 }
128 }