RFC: Native Encryption Support in Varlock .env files

[gunta]

Proposal

This proposal introduces native encryption capabilities to Varlock, inspired by the dotenvx white paper and implementation. This feature would enable developers to commit encrypted secrets directly to their repositories while maintaining security through separated key management, enabling new workflows and use cases that aren't currently possible with Varlock.

Background

The encryption model

Dotenvx implements a hybrid cryptographic solution that splits secrets management into two components:

• Encrypted secrets file (.env): Contains values encrypted with a public key, safe to commit
• Decryption keys file (.env.keys): Contains private keys, never committed to source control

Their approach uses the secp256k1 elliptic curve (the same curve used by Bitcoin) with the ECIES (Elliptic Curve Integrated Encryption Scheme) algorithm for encryption/decryption.

Current Varlock Limitations

While Varlock excels at schema validation, type safety, and runtime security for environment variables, it currently lacks native encryption support. This means:

• Secrets must be managed through external systems (cloud providers, CI/CD secrets)
• Sharing development environments requires manual secret distribution
• No support for encrypted-by-default workflows
• Limited options for local development with sensitive data

This is perfectly fine for some use cases, but a limiting factor for other useful use-cases.

Proposed Implementation

1. Core Encryption Features

Encrypted Value Format

# Standard dotenvx format
DATABASE_URL="encrypted:BG8M6U+GKJGwpGA42ml2erb9+T2NBX6Z2JkBLynDy21poz..."

# With Varlock decorators
# Production database connection string
# @type=string @required @sensitive @encrypted
DATABASE_URL="encrypted:BG8M6U+GKJGwpGA42ml2erb9+T2NBX6Z2JkBLynDy21poz..."

Key File Structure

# .env (safe to commit)
#/-------------------[VARLOCK_PUBLIC_KEY]--------------------/
#/            public-key encryption for .env files          /
#/----------------------------------------------------------/
VARLOCK_PUBLIC_KEY="03eaf2142ab3d55bdf108962334e06696db798e7412cfc51d75e74b4f87f299bba"

# .env.keys (NEVER commit)
#/------------------!VARLOCK_PRIVATE_KEYS!-------------------/
#/ private decryption keys. DO NOT commit to source control /
#/----------------------------------------------------------/
VARLOCK_PRIVATE_KEY="ec9e80073d7ace817d35acb8b7293cbf8e5981b4d2f5708ee5be405122993cd1"

2. New Decorator: @encrypted

Introduce a new decorator specifically for encryption:

# @encrypted @type=string @required
API_KEY="encrypted:BG8M6U+GKJGwpGA42ml2erb9+T2NBX6Z2JkBLynDy21poz..."

# Short version
# @encrypted
SIMPLE_SECRET="encrypted:ABC123..."

3. CLI Commands

Encryption Commands

# Initialize encryption for an environment
varlock encrypt init [--env .env.production]

# Encrypt all values in a file
varlock encrypt [--env .env.production]

# Encrypt specific values
varlock encrypt --key API_KEY --key DATABASE_URL

# Decrypt values for viewing
varlock decrypt [--env .env.production]

# Rotate encryption keys
varlock rotate-keys [--env .env.production]

# Import from dotenvx (migration path)
varlock import-dotenvx [--env .env] [--keys .env.keys]

Integration with Existing Commands

# Load command automatically decrypts when keys are available
varlock load --decrypt

# Run command decrypts at runtime
varlock run --decrypt -- npm start

# Doctor command validates encryption setup
varlock doctor --check-encryption

4. Runtime Behavior

Key Resolution Strategy

1. Check for explicit private key in options
2. Look for VARLOCK_PRIVATE_KEY environment variable
3. Read from .env.keys file

5. Security Enhancements

Leak Prevention

Extend existing runtime patches to prevent encrypted value leaks:

// Prevent logging of encrypted values
console.log(ENV.API_KEY); // "[ENCRYPTED]" in logs

Use Cases Enabled by Encryption

1. Vibe Coding & Rapid Prototyping

• Share entire repositories with encrypted secrets
• Quick setup for new team members
• No need for complex secret distribution of all variables

2. Open Source Project Templates

• Provide working examples with real (encrypted) API keys
• Users only need to get their own keys
• Reduced friction for getting started

3. CI/CD Simplification

• Store encrypted production secrets in the repository
• Only inject private keys in CI/CD environment
• Simplified secret rotation process

4. Development Environment Parity

• Same encrypted values across all environments
• Different keys per environment
• Easier debugging of environment-specific issues

5. Compliance & Auditing

• Track which keys have access to which secrets
• Audit trail of decryption events
• Easier key rotation for compliance

6. Disaster Recovery

• Encrypted backups in version control
• Quick restoration with appropriate keys
• No dependency on external secret stores

Smooth Migration Path from Dotenvx

Seamless Transition

# Import existing dotenvx setup
varlock import-dotenvx

# Validate imported configuration
varlock doctor --check-encryption

# Add Varlock schema decorators (optional)
varlock init --enhance-encrypted

Compatibility Features

• Full support for encrypted: prefix format
• Compatible .env.keys file structure
• Support for DOTENV_PUBLIC_KEY naming convention along the new VARLOCK_PUBLIC_KEY key
• Backward compatible with dotenvx decryption

Migration Benefits

• Add schema validation to encrypted values
• Type safety for decrypted values
• Runtime leak prevention
• Enhanced error messages
• Integration with Varlock's system

Implementation Details

Dependencies

{
  "dependencies": {
    "eciesjs": "^0.4.10"  // Same as dotenvx for compatibility
  }
}

Core Modules

1. Encryption Service

// packages/varlock/src/services/encryption.ts
export class EncryptionService {
  generateKeypair(): { publicKey: string; privateKey: string }
  encryptValue(value: string, publicKey: string): string
  decryptValue(encrypted: string, privateKey: string): string
  isEncrypted(value: string): boolean
}

2. Key Management

// packages/varlock/src/services/key-manager.ts
export class KeyManager {
  loadKeys(envFile: string): Keys
  saveKeys(keys: Keys, envFile: string): void
  rotateKeys(envFile: string): void
  findPrivateKey(envFile: string): string | null
}

3. Parser Extension

// packages/env-spec-parser/src/encrypted.ts
export interface EncryptedDecorator {
  type: 'encrypted';
  algorithm?: 'secp256k1';  // Future: support multiple algorithms with a decorator such as @encryptionAlgorithm
}

Integration Points

With EnvGraph

• Add decryption step to value resolution
• Cache decrypted values in memory
• Support encrypted values in dependencies

With Optional Runtime Patches

• Extend leak prevention to encrypted values
• Add encryption status to telemetry
• Enhanced error messages for decryption failures

With Type Generation

// Generated types understand encryption
export interface ProcessEnv {
  API_KEY: string;  // Decrypted at runtime
  DATABASE_URL: string;  // Decrypted at runtime
}

Security Considerations

Threat Model

1. Repository Compromise: Encrypted values are safe without keys
2. Key Compromise: Only affects specific environment
3. Runtime Compromise: Same as current unencrypted model

Best Practices

1. Never commit .env.keys files
2. Use different keys per environment
3. Rotate keys regularly
4. Audit decryption events
5. Use strong key generation (cryptographically secure random)
6. Add to .gitignore .env.keys automatically to prevent any disaster

Comparison with Alternatives

Approach	Pros	Cons
Varlock + Encryption	Single tool, type safety, seamless integration	New complexity
External Secret Manager	Centralized, audit trails	Network dependency, complexity
CI/CD Secrets	Platform integrated	Platform lock-in, local dev challenges
git-crypt	Transparent	Binary files, merge conflicts

Development Plan

Phase 1: Core Encryption

• Implement ECIES encryption/decryption
• Add keypair generation
• Support encrypted: prefix format
• Basic CLI commands (encrypt, decrypt)

Phase 2: Dotenvx Compatibility

• Import/export dotenvx format
• Support .env.keys structure
• Multi-key support
• Migration tooling

Phase 3: Varlock Integration

• Add @encrypted decorator
• Integrate with EnvGraph
• Extend runtime patches
• Update type generation

Phase 4: Advanced Features

• Key rotation automation
• Audit logging
• Performance optimizations
• Documentation and examples

Testing Strategy

Unit Tests

• Encryption/decryption correctness
• Key generation entropy
• Parser support for encrypted values
• Compatibility with dotenvx format

Integration Tests

• Full workflow testing
• Migration scenarios
• Multi-environment setups
• Framework integrations (Next.js, Vite, Astro)

Security Tests

• Key strength validation
• Leak prevention verification
• Error message sanitization
• Side-channel resistance

Documentation Requirements

User Guide

• Getting started with encryption
• Migration from dotenvx
• Security best practices
• Troubleshooting guide

API Documentation

• New CLI commands
• Configuration options
• Event hooks
• TypeScript interfaces

Examples

• Basic encryption setup
• Multi-environment configuration
• CI/CD integration
• Framework-specific examples

Possible Success Metrics

1. Adoption: % of users enabling encryption
2. Migration: Successful migrations from dotenvx
3. Security: Zero reported key leaks
4. Performance: <10ms decryption overhead
5. Developer Experience: Positive feedback on ease of use

Open Questions

1. Should we support alternative encryption algorithms beyond secp256k1?
2. How should we handle encrypted values in the VS Code extension?
3. What's the best way to handle key distribution in teams?

What does this mean?

Adding native encryption support to Varlock following the dotenvx model would:

• Enable new workflows and use cases
• Provide a smooth migration path for dotenvx users
• Maintain Varlock's focus on developer experience and type safety
• Position Varlock as a total comprehensive solution for environment management

This feature would demonstrate that Varlock "plays well with the ecosystem" while adding unique value through its schema validation, type generation, and runtime security features.

References

• Dotenvx White Paper
• Dotenvx GitHub Repository
• ECIES Specification
• secp256k1 Curve

[philmillman]

Thanks for this @gunta, this is something we're already thinking about as we supported encrypted vaults in dmno. Our implementation will use the function syntax we introduced in @env-spec instead of magic strings and decorators.

[gunta]

Sounds good!

[theoephraim]

yeah so you can imagine a function, could be encrypted or varlock which references which "vault" (encryption key) to use, and then the encrypted value. You can also imagine fetching the encrypted value from somewhere remote, rather than including in git (tradeoffs there...)

Keys can be personal only - and we have a mac app that would store a key within the secure enclave, protected by biometric unlock. Or they could be shared keys, but we are trying to avoid an awkward exchange mechanism, in favor of some kind of trustless hosted solution. The shared keys will likely be stored encrypted, rather than sitting in plaintext, and be re-encrypted using your personal key within the app - again gated behind biometric unlock.

Lots of exciting things coming here!

# value encrypted using personal key
SOME_VAL=encrypted('[email protected]', 'abc123-encrypted-val-...`)

# value encrypted using shared team key
SOME_VAL=encrypted('org-name/some-key-id', 'abc123-encrypted-val-...`)

[gunta]

Wow that sounds pretty powerful.
Also maybe can be combined with something like the upcoming Bun's secrets? https://x.com/jarredsumner/status/1957748098383695930

[theoephraim]

Thanks for pointing that out - hadn't seen it yet. Yeah hopefully we'd be providing similar functionality but not coupled to bun. Once our plugin system is done, it shouldn't be too hard to make something that works together though.