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 | * 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 | } |