feat(security): Pro env-secrets component for .env encryption

[dawsontoth]

Pro companion to harper#1528 (core contract: the dormant enc:v1: decrypt hook). This PR provides the cryptography, the cluster-shared keypair, and the get_secrets_public_key operation that fill that hook.

Where this fits (the full picture)

Harper's env-secret feature is one client contract (public key + enc:v1: envelope) with a swappable provider per deployment tier:

• Self-hosted (this PR + core): the node holds an on-disk keypair and decrypts .env locally. Great for air-gapped / hands-off; the private key lives on the container disk.
  • Core contract: feat(env): dormant decrypt hook + enc:v1 contract for env-secret encryption harper#1528 — the dormant enc:v1: recognition + decrypt hook (Apache).
  • This PR: the Pro provider that fills that hook.
• Fabric (managed): the control plane holds the key and the secrets outside the container and injects decrypted values at container start — the container holds neither the key nor the ciphertext (closes the on-disk-key gap). Same enc:v1 client contract.
  • HarperFast/central-manager#405 — Fabric secret store, per-cluster keypair, SecretsPublicKey / DeploymentSecrets / ResolveDeploymentEnv ops.
  • HarperFast/host-manager#128 — injects the decrypted env into the container at start.

Important

Depends on harper#1528. It imports registerEnvSecretDecryptor and ENV_ENCRYPTED_PREFIX from core, which land in #1528. To build/integration-test, bump the core/ submodule to a commit that includes #1528 (currently pinned older). Left unbumped here to avoid pointing the submodule at an unmerged sha.

What this adds

• security/envSecrets.ts — a built-in component:
  • generates a cluster-shared RSA-4096 env-secrets keypair on first boot (leader), persists it to the keys/ dir, and registers the private key in core's key store so the existing get_key op can serve it to cloning nodes;
  • startOnMainThread() registers get_secrets_public_key (returns public key + fingerprint + scheme — no sensitive material) and the decryptor;
  • start() (per worker) loads the key and registers the hybrid RSA-OAEP-SHA256 + AES-256-GCM decryptor into core's loadEnv hook, so enc:v1: values decrypt into process.env at runtime.
• cloneNode/cloneNode.ts — cloneEnvSecretsKeys() clones the shared private key from the leader (mirrors cloneJWTKeys) so every node decrypts the same ciphertext. This is what makes the "dedicated cluster-shared keypair" model work.
• bin/harper.js — registers envSecrets as a built-in component.

Gating

Component presence (the existing idiomatic Pro gate, like replication/license/analytics). Without harper-pro, no decryptor is registered and core's hook is dormant — encrypted values are skipped with a warning.

Verification

The cryptography — the only novel, must-be-correct logic — is verified end-to-end by a standalone round-trip (client-encrypt per the documented envelope ↔ envSecrets decrypt):

• round-trips short values, a >2 KB PEM (proves the hybrid envelope is required), unicode, embedded quotes, and empty;
• rejects a wrong kid;
• rejects a tampered ciphertext (GCM auth).

oxlint and prettier pass on the changed files. Full tsc/integration is pending the core submodule bump (see note above) — the wiring (imports, server.registerOperation, startOnMainThread/start, get_key clone) is modeled directly on keyService.ts, usageLicensing.ts, and cloneJWTKeys.

Envelope / client format

Documented in core/docs/env-secret-encryption.md (added in #1528): enc:v1:<base64url(JSON{kid,k,iv,ct,tag})>.

🤖 Generated with Claude Code

---

Related PRs — env-secret encryption

One enc:v1: client contract across tiers (public key + envelope; values encrypted before they leave the client):

• Core (Apache):
  • feat(components): protect .env files in the operations API harper#1527 — .env protection in the operations API (masking + get_env_keys / set_env_value / delete_env_value)
  • feat(env): dormant decrypt hook + enc:v1 contract for env-secret encryption harper#1528 — dormant enc:v1: decrypt hook + envelope contract (stacked on #1527)
• Self-hosted provider:
  • feat(security): Pro env-secrets component for .env encryption #505 — Pro env-secrets component (cluster-shared keypair, get_secrets_public_key, runtime decryptor)
• Fabric (managed) provider:
  • HarperFast/central-manager#405 — control-plane secret store + ClusterSecrets ops (key/secrets never on the container)
  • HarperFast/host-manager#128 — inject decrypted env into the container at start
• UI:
  • feat(secrets): cluster secrets page on the hdb_secret store studio#1402 — secrets management UI (cluster-level page + client-side enc:v1 encryption)

---

Follow-up prototype: #509 hardens the private key + env vars against compromised customer code (plugin / SSR RCE) by keeping the key in host scope and exposing secrets only through a config-declared, per-component scope.secrets accessor — grounded in how Harper isolates components (node:vm + SES), so no extra process is needed.

[gemini-code-assist]

Code Review

This pull request introduces the envSecrets component to handle cluster-shared env-secret encryption and decryption. It includes logic to clone the shared private key from the leader node during bootstrapping and registers a decryptor to handle encrypted .env values at runtime. The review feedback highlights two important improvements: first, the cloned private key file should be written with restrictive permissions (0o600) to prevent unauthorized local access; second, the parsed envelope JSON should be validated before accessing its properties to prevent runtime type errors when processing malformed envelopes.

[claude]

Reviewed; no blockers found.

[kriszyp]

This seems like the crux of this pair of PRs and the part that undermines the goal of making the secrets inaccessible through the filesystem within the container and inaccessible via the operations API. I think we fundamentally have to have this be Fabric owner and orchestrated to achieve this goal.