Secret Variables & A/B Rolls

Secret Variables and A/B Rolls are the core data entities within the Barekey vault. They represent encrypted configuration data managed within specific project stages (environments) like development, staging, or production. While "secrets" represent standard key-value pairs, "A/B rolls" are designed to facilitate experimentation by returning different values based on a defined probability.

The system ensures that all sensitive values are encrypted at rest using envelope encryption. Access is scoped by Organization and Project, with variables being further partitioned into Stages. Developers interact with these entities through a draft-based UI that supports bulk updates and imports.

Sources: AGENTS.md:12-14, AGENTS.md:89-91, pkg/convex/project_variables.ts:54-57

Architecture & Data Model

The data model for variables is hierarchical. A variable belongs to a Project, and within that project, it is associated with a specific Stage Slug. This structure allows for identical variable names (e.g., DATABASE_URL) to exist with different values across different environments.

Variable Kinds

The project defines variable types through a kind field. Currently, the system focuses on classic secrets, but the architecture is designed to support more complex types.

Sources: AGENTS.md:91-105, pkg/convex/project_variables.ts:28-39

Entity Relationships

The following diagram illustrates how variables relate to organizations, projects, and encryption keys.

The diagram shows that while variables are scoped to stages for organizational purposes, their lifecycle and encryption are tied directly to the Project entity.
Sources: AGENTS.md:73-81, pkg/convex/projects.ts:114-131

Encryption Lifecycle (Envelope Encryption)

Barekey implements envelope encryption to secure variable values. The actual secret value is encrypted using a Project Data Encryption Key (DEK). The DEK itself is never stored in plaintext; it is encrypted (wrapped) by a Master Key Encryption Key (KEK).

Encryption Flow

1. KEK Retrieval: The Master KEK is retrieved from environment variables (BAREKEY_MASTER_KEY_B64).
2. DEK Unwrapping: The system fetches the projectKeys entry and decrypts the encryptedDek using the KEK.
3. Data Encryption: The unwrapped DEK is used to encrypt the variable plaintext.
4. Storage: The resulting ciphertext and IV are stored in the projectVariables table.

The DEK is derived on-demand and is intended to be ephemeral in memory, never cached or persisted in plaintext.
Sources: AGENTS.md:83-87, pkg/convex/lib/encryption.ts:122-154

Management Operations

Bulk Draft System

The UI manages variables using a "Draft" state. This allows users to perform multiple operations—creating new variables, updating existing ones, and marking others for deletion—before committing them to the database in a single atomic mutation.

• Creates: Validates variable names (required, max 160 chars) and encrypts the new value.
• Updates: Re-encrypts the new value using the project's current DEK and updates the updatedAtMs timestamp.
• Deletes: Removes the variable record from the database.

Sources: pkg/convex/project_variables.ts:14-26, pkg/convex/project_variables.ts:107-217, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:55-75

Secret Reveal & Decryption

For security, variable values are never returned in plaintext during list operations. Decryption is an explicit, request-scoped action.

Data Import

The system supports bulk import of secrets via .env file uploads or clipboard pasting.

• Parsing: The system parses the text to extract keys and values.
• Conflict Resolution: If a name matches an existing variable or a current draft item, the value is updated in the draft (overwritten) rather than creating a duplicate.
• Validation: Invalid lines are flagged as "issues" but do not block the rest of the import.

Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:288-348

Summary

Secret Variables and A/B Rolls provide a secure, environment-aware configuration layer for projects. By combining envelope encryption with a draft-based management system, Barekey allows teams to safely manage sensitive data across different stages of development while preparing for advanced experimentation features like probability-based A/B rolls. Key operations such as reveal and bulk update are governed by strict Organization and Project scoping to ensure data isolation.

Sources: AGENTS.md:12-25, pkg/convex/project_variables.ts:68-100