Secrets & Environment Management

MicroFly provides a built-in, authenticated encryption engine for application secrets and a dynamic configuration store for environment variables.

---

1. Post-Quantum Encrypted Secrets Store

Secrets are protected using NIST FIPS 203 ML-KEM-768 Hybrid Authenticated Encryption (combining quantum-resistant lattice key encapsulation with AES-256-GCM).

• Quantum Resistance: Uses ML-KEM-768 (Module-Lattice-Based Key-Encapsulation Mechanism, formerly Kyber) to ensure application secrets remain secure even against future quantum computers running Shor's algorithm.
• Dual-Security Hybrid Combiner: For each application, MicroFly deterministically derives an ML-KEM-768 seed from /etc/microfly/master.key via HKDF-SHA256, generates an ephemeral lattice key encapsulation, and combines the 32-byte post-quantum shared secret with a classical 256-bit symmetric key: $$\text{HybridKey} = \text{HKDF}(\text{ClassicalKey}, \text{PQSharedKey}, \text{"microfly-secrets-pq-hybrid:"} + \text{app}, 32)$$
• Authenticated Symmetric Cipher: Payloads are encrypted with AES-256-GCM using unique 12-byte initialization vectors (nonces) and Additional Authenticated Data (microfly-secrets-pq:<app>) to bind ciphertexts to specific applications.
• Memory Safety: All plaintext secrets, decapsulation seeds, and intermediate keys are explicitly wiped with zero-fill memory buffers before returning.
• Zero Exposure: Secrets are never written to disk in plain text and are not visible in ps, systemctl, or filesystem listings. Workloads receive decrypted secrets strictly in memory as injected environment variables.

Storing a Secret

To prevent secret values from being logged in shell history, pass them via standard input:

printf '%s' 'production-db-password-12345' | sudo microfly secrets set my-app DB_PASSWORD

Set multiple secrets simultaneously:

printf '%s\n' 'STRIPE_KEY=sk_live_xyz' 'JWT_SECRET=supersecret' | sudo microfly secrets set my-app -

Listing Secrets

Secret keys can be listed at any time, but values are always masked for safety:

sudo microfly secrets list my-app

Output:

DB_PASSWORD=******
JWT_SECRET=******
STRIPE_KEY=******

Deleting a Secret

sudo microfly secrets unset my-app STRIPE_KEY

Automatic Rolling Restart: Whenever secrets are added, modified, or removed, MicroFly automatically performs a zero-downtime rolling restart to inject the updated values into the active workload.

---

2. Dynamic Environment Variables

For non-sensitive configuration (log levels, feature toggles, cache settings), use the dynamic environment store:

Setting Environment Variables

sudo microfly env set my-app LOG_LEVEL=debug CACHE_TTL=300

Listing Environment Variables

sudo microfly env list my-app

Output:

CACHE_TTL=300
LOG_LEVEL=debug

Unsetting Environment Variables

sudo microfly env unset my-app CACHE_TTL

---

3. Online Master Key Rotation

Security best practices require rotating encryption keys periodically or after personnel departures. MicroFly supports zero-downtime, online master key rotation:

sudo microfly secrets rotate-key

Output:

master key rotated successfully; 4 application(s) re-encrypted

How Atomic Rotation Works

1. Generates a new cryptographically secure 256-bit random key.
2. Acquires exclusive locks across /etc/microfly/master.key and all application secret stores.
3. Decrypts all existing secrets using the old key and re-encrypts them with the newly derived keys.
4. Writes updated ciphertext to atomic temporary files.
5. Performs atomic filesystem renames (renameat2). If any application fails to re-encrypt, the entire operation rolls back immediately, restoring the original master key without data loss.

---

4. Environment Precedence & Variable Interpolation

When MicroFly launches a process, environment variables are merged in the following order of precedence (highest priority first):

1. Reserved System Injections (PORT, MICROFLY_APP, MICROFLY_RELEASE, etc.)
                      │
                      ▼
2. Encrypted Application Secrets (microfly secrets set)
                      │
                      ▼
3. Dynamic Environment Store (microfly env set)
                      │
                      ▼
4. Release `.env` file (staged in the project directory)
                      │
                      ▼
5. Static `app.toml` runtime.env definitions
                      │
                      ▼
6. Default System Fallbacks (PATH, LANG, HOME)

Variable Expansion

Environment variables can reference earlier variables using ${VARIABLE} syntax:

[runtime.env]
BASE_URL = "https://${MICROFLY_DOMAIN}"
API_URL = "${BASE_URL}/api"

MicroFly resolves variable expansions deterministically during process preparation.