CRYPTOGRAPHIC SECRETS ENGINE

Secrets Never Sleep

HeadyVault is the cryptographic backbone of the Heady ecosystem. Zero plaintext secrets. Ed25519 signing. AES-256-GCM encryption at rest. φ-scheduled key rotation. Every secret has a lifecycle, every rotation has a receipt.

HeadyKey Auth → Architecture

🔐

Secret Versioning

Every secret is versioned with SHA-256 content hashing. Rollback to any previous version. Audit trail with Ed25519-signed receipts for every mutation.

🔄

φ-Scheduled Rotation

Automatic key rotation at phi-derived intervals: signing keys every 21 days (fib(8)), encryption keys every 89 days (fib(11)), root keys every 377 days (fib(14)).

🛡️

Envelope Encryption

Data Encryption Keys (DEKs) encrypted by Key Encryption Keys (KEKs). KEKs stored in GCP Secret Manager. Zero plaintext key material in application memory.

📜

Audit Receipts

Every secret access, rotation, and revocation emits an Ed25519-signed trust receipt to the immutable audit log. Tamper-evident Merkle chain.

🌐

Multi-Service Distribution

Secrets distributed to Cloud Run services, Cloudflare Workers, and edge nodes via encrypted channels. Per-service scoping prevents lateral movement.

⚡

Hot/Warm/Cold Tiers

Hot secrets in Upstash Redis (sub-ms access). Warm secrets in Neon PostgreSQL. Cold secrets archived with AES-256-GCM. Fibonacci-tiered TTLs.

φ-Scheduled Rotation Intervals

Key Type	Rotation Period	Derivation	Grace Period
Signing Keys (Ed25519)	21 days	fib(8)	34 hours (fib(9) hours)
Encryption Keys (AES-256)	89 days	fib(11)	55 hours (fib(10) hours)
API Keys (hdy_)	Optional TTL	User-configured	Immediate revocation
Session Tokens	8 hours	fib(6)	—
Root Keys	377 days	fib(14)	89 days (fib(11))
JWT Secret	144 days	fib(12)	21 days overlap

// Deprecation workflow for key rotation:
// 1. warn(34 days before expiry)
// 2. soft-fail(55 days — log warnings, still accept)
// 3. hard-fail(89 days — reject, force rotation)
// All intervals are Fibonacci-derived. Zero arbitrary constants.

Architecture

┌─────────────────────────────────────────────────────────┐
│  HeadyVault — Secrets Engine                            │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Secret Store │  │ Key Manager  │  │ Audit Chain  │  │
│  │ ─ Versioned  │  │ ─ Ed25519    │  │ ─ Merkle     │  │
│  │ ─ Encrypted  │  │ ─ AES-256    │  │ ─ Ed25519    │  │
│  │ ─ Scoped     │  │ ─ Rotation   │  │ ─ Append     │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                  │                  │          │
│  ┌──────┴──────────────────┴──────────────────┴───────┐ │
│  │ Backing: GCP Secret Manager + Neon + Upstash Redis │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Integration Points:
  HeadyKey   → JWT secrets, session keys, API key hashes
  HeadyAuth  → OAuth client secrets, provider credentials
  HeadyMCP   → Tool execution tokens, MCP transport keys
  HeadyBuddy → User encryption keys, memory tier keys
  CloudRun   → Service account keys, deployment secrets
  Workers    → Edge secrets, KV encryption keys