Encrypted key management

pro

Provider API keys, encrypted end-to-end between admin browser and team devices.

Pro

Pro teams share provider API keys without ever exposing plaintext to grith.ai. The encryption is end-to-end: admins encrypt keys in their browsers, team devices decrypt them locally, grith.ai stores ciphertext only.

The crypto

Team key — 256-bit AES-GCM key generated client-side at team creation. The team admin's browser holds the master copy.
Device key — Ed25519 keypair generated on each developer's device at first Pro login. Public key uploaded to the dashboard; private key stays on device.
Key envelope — provider API keys are encrypted with the team key. The team key is encrypted to each device's public key using libsodium sealed boxes.
Recovery passphrase — at team-key generation time, the admin must save a 24-word recovery passphrase. The passphrase encrypts a copy of the team key uploadable to the dashboard, so the team can recover access if all admin browsers lose state.

What's signed vs. encrypted:

Bundles (policies, profiles) are signed by the team key for integrity.
Secrets (API keys, channel secrets) are encrypted with the team key for confidentiality.

Adding a key

In the dashboard:

Settings → Keys → Add key.
Pick provider (OpenAI / Anthropic / OpenRouter / custom).
Paste the API key. The browser encrypts it with the team key and uploads the ciphertext.
The key is now in the team keystore.

Pulling on a device

grith pro sync

On first sync, the device:

Posts its public key to the dashboard.
Receives the team key, encrypted to the device public key.
Decrypts locally.
Decrypts each provider key from the team keystore.
Writes plaintext to ~/.config/grith/keys/<provider>.key (perms 0600).

Subsequent syncs only pull updated ciphertext; the team key stays on disk.

Rotation

Rotating one provider key

[dashboard] Settings → Keys → <provider> → Rotate

Enter the new key. The new ciphertext is uploaded. Every device picks up the new value on next sync. Old key is invalidated.

Rotating the team key

[dashboard] Settings → Team key → Rotate

Re-encrypts all team-keystore secrets under a new team key. Each device gets re-authorised on its next sync. A compromised device (lost laptop) loses access at the moment of rotation.

The recovery passphrase is regenerated and must be saved fresh; the old passphrase becomes invalid.

Local key file

~/.config/grith/keys/anthropic.key
~/.config/grith/keys/openai.key
~/.config/grith/keys/openrouter.key

Perms 0600. Owned by the user. Contents are raw API key strings.

The grith provider modules read these files at session start. The key never appears in grith config show output or in logs.

Threat model

What's protected:

grith.ai compromise — attacker gets ciphertext only. Without the team key (which never leaves admin/device browsers), they can't recover plaintext.
Network MITM — TLS to grith.ai plus end-to-end encryption inside.

What's not protected:

Device compromise — attacker on the developer's machine can read the plaintext key in ~/.config/grith/keys/. This is the standard "local trusted device" model.
Admin browser compromise — attacker with the admin's browser session can rotate or exfiltrate the team key. Mitigate with 2FA on the dashboard account.

For higher-assurance setups (hardware-backed keys, HSM integration), Enterprise plans add Yubikey / TPM support — see SSO/SAML (planned).