DEK (Data Encryption Key) Management

Relevant source files

The following files were used as context for generating this wiki page:

• pkg/convex/lib/encryption.ts
• pkg/convex/projects.ts
• pkg/convex/schema.ts
• pkg/convex/project_variables.ts
• AGENTS.md
• pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx

DEK (Data Encryption Key) Management is the core security subsystem of the Barekey vault. It implements envelope encryption to ensure that sensitive environment variables (secrets) are never stored in plaintext within the database. Every project within an organization is assigned a unique DEK, which is used to encrypt that project's specific secrets.

The system utilizes a hierarchical key structure where the project-specific DEK is itself encrypted (wrapped) by a Master Key Encryption Key (KEK). This architecture allows for request-scoped, ephemeral decryption of secrets while maintaining high security at rest. Key lifecycle operations, including generation and on-demand unwrapping, are managed through Convex mutations and helper libraries.

Sources: AGENTS.md:76-80, pkg/convex/lib/encryption.ts:114-118

Encryption Architecture

Barekey follows an envelope encryption model. This model separates the key used to encrypt the data from the key used to protect that encryption key.

Key Hierarchy

1. Master KEK: A global key stored as an environment variable (BAREKEY_MASTER_KEY_B64). It is used to encrypt/decrypt Project DEKs.
2. Project DEK: A per-project 32-byte key generated randomly. It is stored in the projectKeys table in an encrypted format.
3. Secret Values: Individual environment variables encrypted using the Project DEK.

Sources: AGENTS.md:82-86, pkg/convex/lib/encryption.ts:7-10

Security Flow

The following diagram illustrates the relationship between the keys and the data they protect:

Key Generation and Retrieval

The system ensures that a DEK exists for a project before any encryption or decryption operation. If a DEK does not exist, it is generated, wrapped with the Master KEK, and persisted.

The ensureProjectDek Logic

The ensureProjectDek function serves as the primary gateway for key access. It performs the following steps:

1. Check Persistence: Queries the projectKeys table for an existing record linked to the projectId.
2. Import Master Key: Retrieves the Master KEK from the environment and imports it as a CryptoKey.
3. Unwrap or Generate:
   • If a key exists: Decrypts the encryptedDek using the Master KEK.
   • If no key exists: Generates 32 random bytes, encrypts them with the Master KEK, and inserts a new record into projectKeys.
4. Return Ephemeral Key: Returns a CryptoKey object valid for the duration of the current request.

Sources: pkg/convex/lib/encryption.ts:114-149

Technical Specifications

Parameter	Value	Description
Algorithm	AES-GCM	Used for all encryption/decryption operations.
Key Length	32 Bytes	The length of the Project DEK.
IV Length	12 Bytes	Random Initialization Vector generated per encryption.
Payload Format	base64(iv).base64(ciphertext)	Format for stored encrypted strings.

Sources: pkg/convex/lib/encryption.ts:4-39

Secret Encryption and Decryption Flow

Secrets are processed using request-scoped unwrapping. The system enforces a policy where plaintext DEKs must never be cached or persisted.

Encryption Process

When a secret is created or updated, the encryptSecretValueForProject function is called. It triggers ensureProjectDek to get the key and then uses the Web Crypto API to perform AES-GCM encryption.

Decryption Process (Reveal)

To show a secret in the UI, a specific mutation decryptValueForCurrentOrgProjectStage is invoked. This function retrieves the ciphertext from projectVariables and passes it to decryptSecretValueForProject.

Sources: pkg/convex/project_variables.ts:200-244, pkg/convex/lib/encryption.ts:182-195

Data Model

The projectKeys table is the central repository for wrapped encryption keys.

Field	Type	Description
projectId	id("projects")	Reference to the project owning the key.
orgId	string	Reference to the organization.
encryptedDek	string	The DEK encrypted with the Master KEK.
dekVersion	number	Versioning for future key rotations.
rotatedAtMs	number	Timestamp of the last key rotation.

Sources: pkg/convex/schema.ts:43-52

Key Lifecycle and Deletion

Keys are managed alongside the project lifecycle. When a project is deleted, its associated DEKs must also be removed to maintain database hygiene.

1. Initialization: A project key can be generated during the first secret creation via ensureProjectDek.
2. Rotation: While the UI indicates rotation controls are "coming next," the schema supports dekVersion and rotatedAtMs to facilitate future re-encryption of secrets with a new DEK.
3. Deletion: The deleteForCurrentOrg mutation in projects.ts includes logic to collect all projectKeys associated with a projectId and delete them before the project record itself is removed.

Sources: pkg/convex/projects.ts:251-260, pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:327-336

Summary

DEK Management in Barekey provides a robust security layer by ensuring that no project data is directly accessible without the Master KEK. By utilizing envelope encryption and the Web Crypto API, the system maintains a high security posture where Project DEKs are only available in plaintext within ephemeral server memory during active mutation or query execution. This architecture supports future scalability features like key rotation and client-side encryption.

Sources: AGENTS.md:82-90, pkg/convex/lib/encryption.ts:114-118