Skip to content

ADR 009: Multi-Platform Credential Management

Status

Accepted

Context

The system manages sensitive credentials for multiple platforms: - Polymarket: Ethereum private keys for signing blockchain transactions - Kalshi: API Key ID + RSA private keys for REST API authentication - Users: API keys for system access

These credentials have different security requirements: - Private keys: Must never be exposed, single compromise affects all user funds - API keys: Can be rotated, limited blast radius - User credentials: Standard web application security model

Decision

Implement encrypted credential storage with AES-256-GCM encryption and optional HSM support for production deployments.

Credential Types

Platform Credential Storage Method
Polymarket Ethereum Private Key AES-256-GCM encrypted
Kalshi API Key ID + RSA Private Key AES-256-GCM encrypted
Users API Keys Hashed (bcrypt)

Key Hierarchy

Master Key (env var or AWS KMS)
    │
    ├── User Encryption Key (derived per user)
    │       │
    │       ├── Polymarket Private Key (encrypted)
    │       └── Kalshi Private Key (encrypted)
    │
    └── API Key Signing Key

Security Properties

  • Key derivation: HKDF from master key with user-specific salt
  • Encryption: AES-256-GCM with random nonce per encryption
  • At-rest: Encrypted in PostgreSQL, never stored plaintext
  • In-memory: Use zeroize crate for sensitive data cleanup
  • HSM option: AWS KMS or local HSM for master key in production

Alternatives Considered

Approach Pros Cons Verdict
AES-256-GCM + HSM option Strong encryption, flexible HSM adds cost Chosen
Environment variables only Simple Doesn't scale, no user isolation Rejected (dev only)
Vault/Secrets Manager Industry standard Additional dependency, latency Future enhancement
Hardware wallet integration Maximum security UX complexity Future enhancement

Consequences

Positive

  • Strong encryption for all sensitive credentials
  • Per-user key isolation limits blast radius
  • HSM option for high-security deployments
  • Memory zeroization prevents credential leaks

Negative

  • Credential security complexity increases operational burden
  • HSM integration requires additional infrastructure
  • Key rotation requires careful coordination

Neutral

  • Current implementation uses environment variables for development
  • Production deployment guide must include HSM setup

Security Considerations

  1. Master key protection: Must be stored in HSM or KMS in production
  2. Key rotation: Support for rotating encryption keys without downtime
  3. Audit logging: All credential access must be logged
  4. Backup: Encrypted backups with separate key management

References

Linked Requirements

  • NFR-SEC-008: Encrypt credentials with AES-256-GCM, HSM optional
  • NFR-SEC-001: Encrypted private key storage
  • NFR-SEC-002: No private keys in logs