This working is highly inspired by working of Unkey. I read their codebase to understand many concepts and adopted few of them.

Token Vault Technical Architecture

Token Vault implements a secure secret management system with end-to-end encryption and request proxying capabilities. This document outlines the technical implementation details for enterprise customers.

Encryption Architecture

Key Hierarchy

Token Vault uses a hierarchical key management system with three levels:

1. Root Key (KEK): Master encryption key loaded from environment variables
2. Project DEK: Data Encryption Key unique per project, encrypted with Root Key
3. Secret Data: Individual secrets encrypted with Project DEK

Encryption Implementation

Algorithm: AES-256-GCM with authenticated encryption
Key Derivation: Cryptographically secure random key generation
Additional Authenticated Data (AAD): Context metadata for integrity verification

// Encryption process uses authenticated encryption with context metadata
const aad = Buffer.from(JSON.stringify(encryptionContext), "utf8");
const { nonce, ciphertext } = aesGcmEncrypt(dek.key, data, aad);

Project and Organization Creation

Database Transaction Flow

When a new project is created, the system performs an atomic transaction:

Key Generation Process

1. DEK Creation: Generate cryptographically secure 256-bit random key
2. Root Key Encryption: Encrypt DEK using Root Key with AES-256-GCM
3. S3 Storage: Store encrypted DEK in S3 with project-specific path
4. Database Reference: Store DEK metadata in PostgreSQL

// DEK creation and storage
const dek = await vault.createDEK(projectIdentifier);
await tx.insert(decryptionKeys).values({
  id: dek.id,
  projectId: newProject.id,
  organizationId: org.id,
});

Secret Encryption and Storage

Secret Creation Process

Encryption Details

• Project Identifier: Unique identifier per project for key isolation
• DEK Retrieval: Always uses latest DEK for encryption (supports key rotation)
• AAD Structure: Context metadata ensuring encryption integrity
• Storage Format: Standard authenticated encryption format

Request Proxying and Secret Injection

Proxy Request Flow

Secret Injection Methods

1. HTTP Headers: Direct header injection
2. Query Parameters: URL parameter injection
3. Request Body: JSON path-based injection using dot-prop library

// Secret injection examples
if (secret.location === "header") {
  requestBody.headers[secret.headerName] = decryptedValue;
}
if (secret.location === "query") {
  url.searchParams.set(secret.queryName, decryptedValue);
}
if (secret.location === "body") {
  setProperty(body.body, secret.jsonPath, decryptedValue);
}

Security Model

Isolation Guarantees

• Project Isolation: Each project has unique encryption keys
• Organization Boundaries: Cross-organization access is prevented
• API Key Scope: API keys are scoped to specific projects
• Audit Logging: All operations are logged with user context

Key Management

• Root Key: Loaded from environment variables at startup
• DEK Rotation: Supports key rotation without data migration
• Secure Storage: All keys encrypted at rest in S3
• No Key Recovery: Keys cannot be recovered without Root Key

Cryptographic Properties

• Authenticated Encryption: AES-256-GCM prevents tampering
• Nonce Uniqueness: Each encryption uses unique 96-bit nonce
• AAD Integrity: Additional authenticated data prevents context confusion
• Forward Secrecy: Compromised keys don't affect historical data

API Authentication

API Key System

• Key Format: Prefixed keys with configurable prefixes
• Rate Limiting: Configurable per-key rate limits
• Project Binding: Keys are bound to specific projects
• Permission System: Fine-grained permission controls

Session Management

• Session Tokens: JWT-based session management
• Organization Context: Sessions maintain active organization
• Permission Verification: Real-time permission checking
• Audit Integration: All auth events logged

Monitoring and Observability

Audit Logging

All operations generate audit logs with:

• User identification
• IP address and user agent
• Timestamp and operation type
• Resource identifiers
• Success/failure status

Usage Tracking

• Request Counting: Per-organization request metrics
• Secret Operations: Creation, access, and deletion tracking
• Performance Metrics: Response times and error rates
• Billing Integration: Usage data for cost calculation