feat(components): protect .env files in the operations API

[dawsontoth]

What & why

Component .env files are exposed verbatim through the operations API: get_component_file returns the raw bytes (secrets and all) and get_components lists them, so anyone browsing a component in the editor/Studio can read every secret value.

This adds editor-facing, smoke-and-mirrors protection on the read path, plus merge-preserving write operations — enough to prevent accidental disclosure, not a real security boundary (you can still console.log(process.env) at runtime). The runtime loader resources/loadEnv.ts is deliberately untouched, so config.yaml/components still load the real values.

New operations (all super_user)

Operation	Behavior
get_env_keys	Returns key names only ({ file, keys, size, mtime }), never values
set_env_value	Upsert one (key+value) or many (values:{}) — merges in place, preserving other keys, comments and formatting; creates the file if absent
delete_env_value	Remove one (key) or many (keys:[]), leaving the rest intact

Modified operations

• get_component_file on a protected .env → { protected: true, keys, message } where message is a value-free KEY=******** rendering instead of raw secrets.
• get_components → tags protected .env entries with protected: true, so clients can detect them.

set_component_file is intentionally not restricted: it writes .env files verbatim like any other component file. A client (the Studio UI) detects a protected .env via the protected flag / get_env_keys and decides how to edit — the merge-preserving set_env_value, or a full set_component_file write if the user wants it. (An earlier revision hard-blocked set_component_file on .env; that block was removed — see the "allow set_component_file to write .env files" commit.)

Notes / decisions

• Read masking, not write blocking. Protection is on display (get_component_file / get_components never reveal values) and on the convenience of safe edits (set_env_value / delete_env_value). Whole-file writes stay open; clients decide.
• Template files (.env.example, .env.sample, .env.template, case-insensitive) are not secret and are exempted from masking/flagging — read verbatim.
• .env matching is case-insensitive so a stray .ENV isn't masked-around (favors over-protection on case-insensitive filesystems).
• Core parsing/serialisation lives in a new pure module utility/envFile.ts, built around dotenv 16's exact parse semantics so written values round-trip and reported keys match what the runtime loads. Values that need it are quoted (a value containing both ' and " is unrepresentable via dotenv round-trip and is rejected rather than silently corrupted).
• Env-key charset locked to [\w.-] to prevent key injection (e.g. a key with a newline writing extra assignments).
• Not exposed via MCP by default — the new get_* / set_* names fall outside the default read-only MCP allow-list, matching the existing posture for get_component_file.

Tests

Plain-assert suites (no sinon/rewire):

• unitTests/utility/envFile.test.js — pure parse / mask / upsert / remove logic + round-trips through dotenv.parse (proves the runtime still reads the real value)
• unitTests/components/envOperationsValidation.test.js — validator shape, xor logic, key-injection rejection
• unitTests/components/envOperations.test.js — handlers end-to-end against a temp components root (masking, merge-preserving set / delete, template pass-through, and set_component_file writing a .env verbatim)

oxlint, prettier, and tsc pass; the env suites (65 tests) are green.

🤖 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 #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 #1528 — dormant enc:v1: decrypt hook + envelope contract (stacked on feat(components): protect .env files in the operations API #1527)
• Self-hosted provider:
  • feat(security): Pro env-secrets component for .env encryption harper-pro#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)

[gemini-code-assist]

Code Review

This pull request introduces new operations (get_env_keys, set_env_value, and delete_env_value) to securely manage .env files, including value masking for protected environment files and validation schemas. The reviewer identified three critical issues: first, the setEnvValue and deleteEnvValue operations in operation_authorization.ts are missing their API name mapping, which will block them for users with restricted operation allowlists; second, getEnvKeysValidator lacks project name validation, exposing a potential path traversal vulnerability; and third, sensitive secrets from set_env_value requests are at risk of being leaked in plain text within the operation logs because value and values are not excluded from logging.

[claude]

Reviewed; no blockers found.

[kriszyp]

Are we going to add the ability to manage env values through Fabric (bypassing op API for security) and an op API mechanism?

[dawsontoth]

Two questions:

1. What do you think about the shape of the operations?
2. Do we want this feature for non-Fabric clusters too?

[dawsontoth]

@kriszyp I'd also say that, since we already support .env files as a part of components, this PR is a good enhancement for the platform. It protects the files a bit, and lets us build out a nice UX that will feel good for people. That same web-side component can drive what you're talking about with secrets set at a higher level that have real protections. So we could abandon #1528 if that's not the direction you want us to go, and proceed with this PR.

[dawsontoth]

@kriszyp I removed the set_component_file protections, I can draft a Studio PR for this too so we can visualize it better if you'd like.

[kriszyp]

What do you think about the shape of the operations?

This looks good.

Do we want this feature for non-Fabric clusters too?

Yes, I think that makes sense.

So we could abandon #1528 if that's not the direction you want us to go, and proceed with this PR.

Why? I really liked #1528 and am already trying to build other PRs on it (using its security mechanism), why close it?

[kriszyp]

This looks good. Note, that I think this should go in 5.2 (and I assigned that milestone).