Secrets / env-var management for Fabric-deployed applications

[kriszyp]

Today there is no supported mechanism to securely configure environment variables (API keys, secrets) for applications deployed to Harper Fabric via the CLI.

loadEnv: .env works locally, but Fabric deployments lack:

• A UI or CLI mechanism to define environment variables
• A secure secret store for runtime configuration
• A way to inject environment variables at deploy time

Customer ask (ESS Request)

Originated from a customer; flagged as a Q2 2026 product roadmap item. From CORE-3024 discussion (bari):

Sub-asks identified:

• CLI arguments for env vars at deploy time (so customers using harperdb deploy against a GitHub repo without secrets in source can supply them at deploy time).
• Better template for the deployment workflow.
• Studio UI for adding secrets (significantly larger; several weeks of focused dev).
• A "write your .env" prompt in Studio that ends up calling set component with .env content.
• Allow users to upload a .env file directly. (Note: through Fabric Connect, the secret transits Harper servers — recommend warning users / encouraging direct connect.)
• Audit/logging policy for secret storage (separate security discussion).
• Compose-level env vars (Q2 roadmap, separately tracked).
• harper_ prefix directive for Harper-specific env vars to avoid customer conflicts.

Scope split

This umbrella issue tracks the engineering-side work in harper-pro / core:

• Deploy-time env-var injection mechanism (CLI + Operations API).
• Storage model for secrets at rest in Fabric (encrypted, audited).
• harper_* directive parsing for Harper-internal env-vars.

Studio UI work belongs in HarperFast/studio. Cross-link when the UI ticket is filed.

Not Ready

Needs product/UX alignment on the secrets storage model (where do secrets live? how are they encrypted? what's the audit posture?) before engineering can scope concrete acceptance criteria. The discussion captured in the Jira ticket is a starting point.

---

Tracked in Jira: CORE-3024

🤖 Filed by Claude on behalf of Kris.

[kriszyp]

Adopting this as the tracking ticket for the Pro key-custody layer (phase 2 of the secrets-management plan).

Scope:

• One KeyCustody seam that registers the decryptor + public key into core's registerSecretDecryptor hook (landed in harper#1528). Interface exposes decrypt + publicKey only — never the raw private key.
• file provider (self-hosted default): the feat(security): Pro env-secrets component for .env encryption #505 shape — generate on first boot, persist 0600, clone via get_key. feat(security): Pro env-secrets component for .env encryption #505 gets absorbed here rather than merged standalone.
• injected provider (Fabric default): read the private key from an env var at boot, cache in memory, scrub from process.env immediately (so npm/child spawns never inherit it), propagate to workers via workerData (mirrors the existing ticketKeys pattern — needs a small coordinated core PR for manageThreads).
• kid→key map (not a single key) so rotation doesn't invalidate existing ciphertext.
• KMS provider is deliberately later (hardening phase).

🤖 Posted by Claude (Fable 5) on Kris's behalf.

[kriszyp]

Scope addition for the injected custody provider, from the key-delivery review: env-var delivery alone leaves the private key readable in /proc/self/environ for the process lifetime (a JS-level delete process.env[...] only mutates the JS copy, and components run as worker threads in the same process — an environ self-read needs no privileges). So the injected provider should support, in preference order:

1. fd/file ingestion (primary, used by the managed platform): the container entrypoint moves the key out of the environment before execing node — read-once pipe fd, or a 0400 tmpfs file owned by the app uid. The provider reads the fd/file at boot on the main thread, caches in memory, and propagates to workers via workerData (mirroring the existing ticketKeys pattern; needs the small coordinated core change in manageThreads). After execve, no process retains the key in its environ block.
2. env-var ingestion (fallback for plain docker users): read, cache, delete process.env[...] immediately (still worth doing — it stops child-process inheritance, e.g. npm spawns), documented as the weaker delivery because of the environ residue.

The threat-model framing to carry into the code docs: in-process code can always reach the registered decryptor, so key-delivery hardening targets generic environment scrapers and child-process inheritance, not resident attackers — containers/uids remain the tenant boundary.

🤖 Drafted by Claude (Fable 5) on Kris's behalf.