Secret Support in Superposition

[knutties]

We need Github like Secret support in Superposition for use in functions and webhook invocations.

[sauraww]

Secret Management for Superposition

Problem

Need to add user-facing secrets feature:

• Users create secrets per workspace
• Secrets are encrypted before storage
• Used in functions as SECRETS.key_name
• Used in webhooks as {{SECRETS.key_name}}
• Cannot be read via API (write-only)

HashiCorp Vault (Self-Hosted) / AWS KMS

How it works:

• Deploy Vault server separately
• Master Key stored in Vault
• Superposition calls Vault to encrypt/decrypt DEKs
• Data Encryption Keys per workspace
• Instances don't need shared storage

Pros:

• Built for secret management
• Handles rotation natively
• Works across instances seamlessly

Cons:

• Extra infrastructure
• Additional service to manage

Database Schema

CREATE TABLE {{workspace}}.secrets (
    name VARCHAR(255) PRIMARY KEY,
    encrypted_value TEXT NOT NULL,        -- AES-256-GCM encrypted
    description TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    last_modified_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    created_by VARCHAR(255) NOT NULL,
    last_modified_by VARCHAR(255) NOT NULL,
    change_reason TEXT,
    is_active BOOLEAN DEFAULT true,
);

CREATE INDEX idx_secrets_active ON secrets(is_active);

---

API Design (Same as Variables, No Read)

POST   /admin/{org}/{workspace}/secrets
       Create secret
       Body: { "name": "DB_PASSWORD", "value": "...", "description": "..." }
       Response: 201 (metadata only, NO value)

PATCH  /admin/{org}/{workspace}/secrets/{name}
       Update secret
       Body: { "value": "...", "change_reason": "..." }
       Response: 200 (metadata only)

DELETE /admin/{org}/{workspace}/secrets/{name}
       Delete secret (soft delete)
       Response: 204

GET    /admin/{org}/{workspace}/secrets
       List secrets (metadata only)
       Response: [{ name, description, created_at, ... }]

NO GET /secrets/{name}  (secrets not readable via API)


## Implementation Strategy

**Encryption/Decryption:**
- Master Key: Vault 
- Per-workspace DEK: Generated on workspace creation, encrypted with Master Key
- Secret values: Encrypted with workspace DEK, stored in DB

**Caching:**
- Lazy-loaded HashMap for decrypted secrets
- Redis publish on create/update to invalidate cache across instances
- TTL-based refresh (5-10 min)

**Rotation:**
- Workspace-level: Rotate workspace DEK, re-encrypt its secrets
- Master Key: Rare, requires re-encrypting all DEKs

---

## Open Questions

1. Should we support rotation in MVP, or keep it simple?
2. Should old secrets be retained for recovery?