Encryption Model

AgentSecrets uses a strict End-to-End Encryption (E2EE) model. The central sync servers are completely blind to your data.

Cryptographic Primitives

• Encryption Algorithm: AES-256-GCM (Galois/Counter Mode)
• Key Derivation: Argon2id (for password-based keys)
• Key Exchange: ECDH over Curve25519 (for team sharing)

How it works

When you create a workspace, the CLI generates a symmetric Workspace Master Key. This key never leaves your local machine.

Pushing Secrets

When you run agentsecrets secrets push:

1. The CLI serializes your environment variables into a JSON object.
2. It encrypts the entire JSON payload using the Workspace Master Key via AES-256-GCM.
3. The resulting ciphertext, along with an authentication tag and nonce, is uploaded to the AgentSecrets API.

The server stores the blob. It cannot read the JSON keys, the values, or the number of secrets.

Double-Envelope Encryption: The Role of ENCRYPTION_KEY

A common question for zero-knowledge architectures is: "If the server cannot decrypt secrets, why does agentsecrets-server require a Fernet ENCRYPTION_KEY?"

The answer is defense-in-depth double-envelope encryption:

[ Developer Machine ]                      [ agentsecrets-server Database ]
Plaintext Secret (sk_live_...)             
       │                                   
       ▼ (Client AES-256-GCM)              
Client Ciphertext (Opaque)                 
       │                                   
       ▼ (Network Payload)                 
Received by Server ──────────────────────>  Outer Fernet Layer (ENCRYPTION_KEY)
                                                └── Inner Client Ciphertext (AES-256-GCM)

1. Client Layer (Zero-Knowledge Boundary): The agentsecrets CLI encrypts secrets using AES-256-GCM on the local machine before anything is sent over TLS.
2. Server Layer (At-Rest Database Protection): When agentsecrets-server persists records to PostgreSQL, it wraps the already-encrypted client ciphertext in a server-side Fernet layer (ENCRYPTION_KEY).
3. Cryptographic Guarantee: The server is simply encrypting an encrypted blob. Even if an adversary gains direct access to PostgreSQL and obtains the server's ENCRYPTION_KEY, decrypting the database layer only reveals the client-side AES-256-GCM ciphertext. The raw secrets remain structurally unreadable because the server never holds the client's X25519 or AES keys.

Because the server does not hold decryption keys,there is no master password reset. If you lose access to your local machine, the workspace keys can be retrieved by logging in again from a new machine (which performs a secure key exchange with other workspace members). No raw workspace keys are saved in disk-based backup files.