Keychain & Credential Storage
When you first launch Cate, your operating system may prompt you to allow keychain or credential manager access. This page explains what that prompt means, why it appears, and how Cate protects your credentials.
Why Cate needs keychain access
Section titled “Why Cate needs keychain access”Cate stores credentials — OAuth tokens, personal access tokens, and API keys — for the services it connects to on your behalf (GitHub, Jira, Linear, and others). As an Electron application, Cate follows Electron’s recommended best practice for secret storage by using the safeStorage API, which delegates encryption to your operating system’s native credential manager. This is the same mechanism that browsers, Git, and other desktop apps use to protect sensitive data.
The keychain prompt appears once, the first time Cate encrypts or decrypts a credential. After you grant access, subsequent reads and writes happen silently.
Where credentials are stored
Section titled “Where credentials are stored”All credentials are persisted in a single encrypted file:
<data-dir>/credentials.binThe data directory defaults to:
| Platform | Default path |
|---|---|
| macOS | ~/Library/Application Support/Cate/ |
| Windows | %APPDATA%\Cate\ |
| Linux | ~/.config/Cate/ |
You can override this with the --data-dir CLI flag.
What gets stored
Section titled “What gets stored”| Provider | Secrets stored | Auth method |
|---|---|---|
| GitHub | Access token, refresh token, expiry | OAuth or PAT |
| Jira | Email, API token, refresh token, cloud ID, expiry | OAuth or PAT |
| GitLab | Access token, refresh token, expiry | OAuth or PAT |
| Azure DevOps | Access token, refresh token, expiry | OAuth |
| Bitbucket Cloud | Access token, refresh token, expiry | OAuth |
| Linear | Access token, refresh token, expiry | OAuth or PAT |
OAuth client IDs and client secrets are not stored in the credentials file — they are bundled into the application at build time.
How encryption works
Section titled “How encryption works”Primary: OS-native encryption
Section titled “Primary: OS-native encryption”Cate uses Electron’s safeStorage API, which delegates to the platform’s native secret store:
| Platform | Backend |
|---|---|
| macOS | Keychain Services — the encryption key lives in your login keychain |
| Windows | DPAPI (Data Protection API) — the key is bound to your Windows user profile |
| Linux | libsecret — uses GNOME Keyring, KWallet, or a compatible secrets service |
This is the encryption path that triggers the one-time keychain prompt on macOS. On Windows and Linux, access is typically granted automatically for the logged-in user.
Fallback: AES-256-GCM
Section titled “Fallback: AES-256-GCM”If native encryption is unavailable (for example, a Linux server without a desktop keyring), Cate falls back to software encryption:
| Property | Detail |
|---|---|
| Algorithm | AES-256-GCM (authenticated encryption) |
| Key derivation | SHA-256 hash of machine hostname and OS username |
| IV | 12 random bytes, generated fresh for each encryption operation |
| Tamper protection | 16-byte GCM authentication tag prevents undetected modification |
| Portability | Device-specific — the key is derived from machine identity, so the credentials file cannot be copied to another machine |
The fallback activates automatically. No configuration is required.
Read and write flow
Section titled “Read and write flow”Saving a credential:
Credential → serialize → encode as base64 → encrypt → write to credentials.binLoading a credential:
Read credentials.bin → decrypt → decode base64 → deserialize → credentialIf decryption fails — for example, after a machine migration or a corrupted file — Cate deletes the credentials file and prompts you to re-authenticate. No partial or garbled data is returned.
Token refresh
Section titled “Token refresh”OAuth providers issue time-limited access tokens alongside a refresh token. When an access token expires, Cate automatically exchanges the refresh token for a new one and persists the updated credential. This happens transparently — you do not need to re-authenticate unless the refresh token itself is revoked.
Security summary
Section titled “Security summary”- Credentials are encrypted at rest using OS-native encryption when available
- The credentials file never leaves your machine — it is not synced, committed, or transmitted to Blue Ghost
- OAuth client secrets are not stored in the credentials file
- The fallback encryption key is device-specific and cannot be used on another machine
- Failed decryption results in deletion, not exposure — you re-authenticate from scratch
Revoking access
Section titled “Revoking access”To remove all stored credentials:
- Open Settings → Issue Tracker in Cate and disconnect each provider, or
- Delete the
credentials.binfile directly from the data directory listed above
Cate will prompt you to re-authenticate the next time it needs to access a provider.