Secrets Architecture
Encryption at Rest — AES-256-GCM
graph TB
MK["SECRETS_ENCRYPTION_KEY<br/>32 bytes hex, 64 chars"]
SHA["sha256.update masterKey .digest"]
KEY["Derived 256-bit AES key"]
ENC["encryptValue<br/>iv = randomBytes 16<br/>createCipheriv aes-256-gcm<br/>output = iv : authTag : ciphertext"]
DEC["decryptValue<br/>split by :<br/>createDecipheriv aes-256-gcm<br/>setAuthTag authTag"]
PT["Plaintext string"]
CT["Ciphertext blob<br/>stored in PostgreSQL"]
MK --> SHA --> KEY
KEY --> ENC --> CT
CT --> DEC --> PT
KEY --> DEC
Code (src/lib/secrets-encryption.ts):
const ALGORITHM = 'aes-256-gcm';
const IV_LENGTH = 16; // 128-bit initialization vector
const AUTH_TAG_LENGTH = 16; // 128-bit GCM authentication tag
function deriveKey(masterKey: string): Buffer {
return crypto.createHash('sha256').update(masterKey).digest();
}
export function encryptValue(plaintext: string, masterKey: string): string {
const key = deriveKey(masterKey);
const iv = crypto.randomBytes(IV_LENGTH);
const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
let encrypted = cipher.update(plaintext, 'utf8', 'hex');
encrypted += cipher.final('hex');
const authTag = cipher.getAuthTag().toString('hex');
return `${iv.toString('hex')}:${authTag}:${encrypted}`;
}
export function decryptValue(encryptedPayload: string, masterKey: string): string {
const key = deriveKey(masterKey);
const parts = encryptedPayload.split(':');
if (parts.length !== 3) throw new Error('Invalid encrypted payload format');
const [ivHex, authTagHex, ciphertext] = parts;
const iv = Buffer.from(ivHex, 'hex');
const authTag = Buffer.from(authTagHex, 'hex');
const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
decipher.setAuthTag(authTag);
let decrypted = decipher.update(ciphertext, 'hex', 'utf8');
decrypted += decipher.final('utf8');
return decrypted;
}
Storage Format
The encrypted blob stored in PostgreSQL secrets.encrypted_value:
graph LR
IV["iv_hex<br/>Random IV<br/>32 hex chars = 16 bytes"]
TAG["auth_tag_hex<br/>GCM auth tag<br/>32 hex chars = 16 bytes"]
CT["ciphertext_hex<br/>AES-256-GCM<br/>encrypted payload"]
IV -- ":" --> TAG
TAG -- ":" --> CT
Example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6:7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d:4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f
Database Schema
Secret Entity (src/entities/Secret.ts)
@Entity('secrets')
export class Secret {
id: string; // UUID primary key
projectId: string; // UUID — FK to projects.id
environmentId: string | null; // UUID — FK to environments.id (null = global)
key: string; // e.g. "DATABASE_URL", "API_KEY"
encryptedValue: string; // iv:authTag:ciphertext format
version: number; // integer, starts at 1
createdById: string | null; // UUID — user who created/updated
isActive: boolean; // soft delete flag
createdAt: Date;
updatedAt: Date;
}
SecretVersion Entity (src/entities/SecretVersion.ts)
@Entity('secret_versions')
export class SecretVersion {
id: string; // UUID primary key
secretId: string; // UUID — FK to secrets.id (CASCADE delete)
encryptedValue: string; // Previous encrypted value
version: number; // The version number being archived
changedById: string | null; // UUID — user who made the change
createdAt: Date;
}
API Endpoints
graph TB
ROOT["SECRETS API ROUTES<br/>/api/projects/:projectId/secrets"]
LIST["GET /<br/>List secrets (masked values)"]
CREATE["POST /<br/>Create/update secret"]
REVEAL["POST /reveal<br/>Reveal plaintext value"]
DEL["DELETE /:secretId<br/>Soft-delete secret"]
EXPORT["GET /export/:environmentId<br/>Export as .env format"]
BULK["POST /bulk<br/>Bulk import from JSON"]
VERSIONS["GET /:secretId/versions<br/>Version history"]
ROLLBACK["POST /:secretId/rollback/:version<br/>Rollback to previous version"]
ROOT --> LIST
ROOT --> CREATE
ROOT --> REVEAL
ROOT --> DEL
ROOT --> EXPORT
ROOT --> BULK
ROOT --> VERSIONS
ROOT --> ROLLBACK
Required Permissions per Endpoint
| Endpoint | Permission | Description |
|---|---|---|
GET / |
secrets.list |
View masked secret metadata |
POST / |
secrets.create |
Create new or update existing secret |
POST /reveal |
secrets.reveal |
View plaintext value (audit-logged) |
DELETE /:id |
secrets.delete |
Soft delete |
GET /export |
secrets.export |
Export all secrets as .env (devops only) |
POST /bulk |
secrets.import |
Bulk import from JSON (devops only) |
GET /versions |
secrets.list |
View version history |
POST /rollback |
secrets.rollback |
Rollback to previous version |
Versioning Flow
stateDiagram-v2
[*] --> v1
v1 --> v2 : PATCH /secrets<br/>value = xyz
v2 --> v3 : POST /rollback/version1
v3 --> [*]
note right of v1
Secret v1
value = "abc"
end note
note right of v2
Secret v2, value = "xyz"
SecretVersion row archives v1
end note
note right of v3
Secret v3, value = "abc"
Rollback: archives v2 to SecretVersion,
restores v1 ciphertext,
version counter still increments
end note
Key observations:
- Rollback creates a new version (increment), it does not revert the version counter
- Previous encrypted values are preserved in
secret_versionsfor audit trail - CASCADE delete: removing a
Secretdeletes all associatedSecretVersionrows
Audit Trail
All secret access is logged to the audit_logs table:
// Every secret mutation logs:
await logAudit({
userId: req.user?.id,
action: 'secrets.create' | 'secrets.update' | 'secrets.delete'
| 'secrets.reveal' | 'secrets.export' | 'secrets.import'
| 'secrets.rollback',
targetType: 'Secret',
targetId: secret.id,
metadata: { key, environmentId, version },
ip: req.ip,
});
| Action | When |
|---|---|
secrets.create |
New key created (version === 1) |
secrets.update |
Existing key updated (version > 1) |
secrets.delete |
Soft delete (isActive = false) |
secrets.reveal |
Plaintext viewed (high-sensitivity) |
secrets.export |
Bulk export as .env |
secrets.import |
Bulk import from JSON |
secrets.rollback |
Rollback to previous version |
Export/Import
Export (plaintext JSON — devops only)
GET /api/projects/:projectId/secrets/export/:environmentId
{
"environmentId": "env-uuid",
"secrets": "DATABASE_URL=postgres://...\nAPI_KEY=sk-...\nREDIS_PASSWORD=..."
}
- Requires
secrets.exportpermission (onlyadminanddevopsroles) - All secrets for the given environment are decrypted and concatenated as
.envformat - Audit-logged with count of exported secrets
Import (bulk create from JSON)
POST /api/projects/:projectId/secrets/bulk
{
"environmentId": "env-uuid",
"secrets": [
{ "key": "DATABASE_URL", "value": "postgres://..." },
{ "key": "API_KEY", "value": "sk-..." }
]
}
- Requires
secrets.importpermission (onlyadminanddevopsroles) - Each item is encrypted individually and stored
- Existing keys are updated (new version created), new keys are created
- Returns status per key:
{ key: "DATABASE_URL", status: "created" | "updated", version: 1 }
Scoping
Secrets are namespaced hierarchically:
graph TB
P["Project<br/>(projectId, required)"]
E["Environment<br/>(environmentId, nullable = fallback)"]
K["Secret key<br/>unique per (project, env, key)"]
S["Secret row<br/>encryptedValue, version"]
V["SecretVersion rows<br/>full history, CASCADE on delete"]
P --> E --> K --> S --> V
- Per-project: All secrets within a project scope (
projectIdis required) - Per-environment: Optional environment scoping (
environmentIdnullable)environmentId = null→ global/fallback secretenvironmentId = 'uuid'→ environment-specific secret (overrides global)
- Per-key: Unique per (projectId, environmentId, key) combination
- Soft-delete:
isActive = falserather than hard delete
Resolution Order
When SDK requests config via GET /api/sdk/config?projectId=X&environmentId=Y:
- Query
ProjectConfigtable for project+environment key-value pairs - Query
Secrettable for all active secrets in project+environment - Decrypt each
encryptedValuewithSECRETS_ENCRYPTION_KEY - Return merged result (secrets override config if same key)
// src/routes/sdk.ts:453-465
const allSecrets = await secretRepo.find({
where: { projectId: resolvedProjectId, isActive: true },
});
for (const s of allSecrets) {
if (s.environmentId && environmentId && s.environmentId !== environmentId) continue;
result[s.key] = decryptValue(s.encryptedValue, masterKey);
}
Security Considerations
| Aspect | Implementation |
|---|---|
| Encryption algorithm | AES-256-GCM (authenticated encryption with associated data) |
| Key derivation | SHA-256 hash of SECRETS_ENCRYPTION_KEY env var |
| IV | Random 16 bytes per encryption — ensures ciphertext uniqueness |
| Authentication tag | 16-byte GCM tag — detects tampering |
| Key storage | Environment variable only (not in database) |
| In-transit | TLS via ingress-nginx (cert-manager + Let's Encrypt) |
| At-rest (DB) | Encrypted encrypted_value column; key not in database |
| Access control | RBAC — secrets.reveal restricted to admin/devops/tech_lead |
| Audit | Every reveal, create, update, delete, export, rollback logged |
| Versioning | Previous encrypted values preserved in secret_versions |
| Soft delete | isActive = false — values remain in database for recovery |
See Auth Flow for RBAC details and SDK Lifecycle for how SDKs fetch secrets at init time.