Security model

Klef is zero-knowledge. Encryption and decryption happen only on your device. The server stores ciphertext, validates permissions, and never sees plaintext values, your password, or your keys.

What the server can and cannot see

Key names are stored in plaintext so you can list and search them. Values are always encrypted.

The key chain

Each layer of the chain encrypts the next. Your password sits at the top, and a secret value sits at the bottom.

password
   |  Argon2id
   v
key-encryption key (KEK)
   |  unwraps
   v
master key
   |  unwraps
   v
project key
   |  unwraps
   v
environment key
   |  encrypts
   v
secret value

• Your password is run through Argon2id on your device to derive a key-encryption key. The password is never sent anywhere.
• The master key is your root key. It unwraps your project keys.
• Each project key unwraps the keys for that project's environments.
• Each environment key encrypts and decrypts the secret values in that environment.

Sharing happens at the project level: a project key is re-encrypted for a recipient using their public key, so they can decrypt that project without ever learning your password.

Cryptography

• All cryptography uses libsodium, the same library on the CLI and in the web app.
• Nonces are random per operation and never reused.
• Your encryption password is never written to durable storage. The Supabase session token lives in your OS keychain (with a private 0600 file fallback for headless environments).

Recovery

Because Klef never sees your password, it cannot reset it for you. Instead, your master key carries a second, independent wrapping under a recovery code: a full-entropy value shown once at signup.

• The recovery code is a user-held secret, so recovery still happens entirely on your device. It is not a backdoor, and the operator cannot decrypt your data.
• Store it somewhere safe, such as a password manager. It is the only way back in if you forget your encryption password.
• Recover access with klef login --recover, and rotate the code anytime with klef recovery.

Session versus encryption

Signing in and unlocking are two separate layers:

• Session. Signing in establishes a session that lets the CLI reach the API. The CLI uses a browser-mediated device-auth flow, so it never handles OAuth tokens itself.
• Encryption. Your encryption password unlocks the key chain. It is never sent to the server and never seen by any sign-in provider.

A stolen session token cannot decrypt your secrets, because decryption needs your password (or recovery code), which the session layer never touches.