bug: extension install hooks bypass core .env schema, then break PUT /api/settings/env with 503

[yasinBursali]

Bug

When a built-in extension (e.g. librechat) is enabled via dream enable <ext> or the Custom install menu, the install hook appends extension-specific env keys to .env via the host-agent env-update path. These keys are not in the core dream-server/.env.schema.json. On subsequent calls to PUT /api/settings/env, the schema-aware validator rejects the first extension-added key with 503 {"detail":{"message":"Unknown key: <KEY>"}} before reaching any user-submitted changes.

Result: after installing any extension whose install hook writes .env keys, the dashboard Settings panel's Save button is completely broken — identical symptom to fork issue #337 (HOST_RAM_GB), different root cause.

Reproduction on integration-test install

```bash

Install at /Volumes/X/dream-server-test currently has librechat enabled.

The .env contains 6 LibreChat-specific keys:

$ grep -E '^(JWT_SECRET|JWT_REFRESH_SECRET|LIBRECHAT_MONGO_PASSWORD|LIBRECHAT_MEILI_KEY|CREDS_KEY|CREDS_IV)=' /Volumes/X/dream-server-test/.env | cut -d= -f1
JWT_SECRET
JWT_REFRESH_SECRET
LIBRECHAT_MONGO_PASSWORD
LIBRECHAT_MEILI_KEY
CREDS_KEY
CREDS_IV

None are in core schema

$ grep -E '"(JWT_SECRET|JWT_REFRESH_SECRET|LIBRECHAT_MONGO_PASSWORD|LIBRECHAT_MEILI_KEY|CREDS_KEY|CREDS_IV)"' /Volumes/X/dream-server-test/.env.schema.json
(no output)

raw_text PUT fails

$ KEY=$(grep ^DASHBOARD_API_KEY= /Volumes/X/dream-server-test/.env | cut -d= -f2)
$ python3 -c "
import json, urllib.request
raw = open('/Volumes/X/dream-server-test/.env').read()
req = urllib.request.Request('http://127.0.0.1:3002/api/settings/env',
method='PUT', headers={'Authorization': f'Bearer $KEY', 'Content-Type': 'application/json'},
data=json.dumps({'raw_text': raw}).encode())
urllib.request.urlopen(req)"
urllib.error.HTTPError: HTTP Error 503
body: {"detail":{"message":"Unknown key: JWT_SECRET"}}
```

Identical symptom happens regardless of which extension install hook ran — any extension that adds env keys breaks Settings save.

Why the extension install hook succeeds but subsequent saves fail

The install hook writes .env via the host-agent, which may bypass the schema-validated PUT path (it uses a direct file write or a different endpoint). The schema validator only runs on user-initiated PUT /api/settings/env calls from the dashboard. So the install-time write succeeds, the extension starts, the dashboard can display values — but the user can never save anything because the existing file fails validation on read.

Discovered during

Testing my fix for #337 on the drifted integration-test install. My schema fix unblocks HOST_RAM_GB, but then the validator hits the first LibreChat key and 503s on the same code path. Verified the HOST_RAM_GB fix in isolation by temporarily swapping to the 84-line pre-LibreChat baseline.

Platforms affected

• macOS: affected on any install that ran a LibreChat-style extension install hook. Combined with macOS: env-generator.sh writes HOST_RAM_GB to .env but .env.schema.json has no entry — 503 on every PUT /api/settings/env #337's HOST_RAM_GB gap, the Settings panel is doubly broken.
• Linux: affected on any install that ran such an extension install hook.
• Windows/WSL2: same.

Proposed fix directions

Pick one or a combination:

A. Declarative — extension manifest registers its env keys

Each extension's manifest.yaml gains an env_keys: array listing the keys it writes. The core _handle_env_update loads core schema AND all enabled-extension manifests' env_keys lists and treats extension keys as valid (perhaps as opaque strings). Clean separation of concerns, survives enable/disable cycles.

B. Validator relaxation — prefix whitelist

_handle_env_update allows any key matching a prefix pattern like LIBRECHAT_*, LANGFUSE_*, QDRANT_* (one per extension). Requires per-extension whitelist maintenance in core code, which is worse than A.

C. Validator relaxation — warn-on-unknown instead of reject

_handle_env_update logs a warning for unknown keys but accepts the PUT. Passes them through unchanged. Least principled but unblocks users immediately. Conflicts with Option A of fork issue #337 (which deliberately chose strict-reject over silent-accept).

Recommended: A + C — extension manifests register their keys (long-term correct model), and until extensions are migrated the validator degrades to warn-on-unknown so users aren't blocked. Migration path: extensions can register their keys via a simple manifest addition, and the validator gradually tightens as coverage grows.

Priority

High. On any install with any extension whose install hook writes env keys (LibreChat is one, others probably exist), the Settings panel is unusable — identical user-visible symptom to #337.

Related

• macOS: env-generator.sh writes HOST_RAM_GB to .env but .env.schema.json has no entry — 503 on every PUT /api/settings/env #337 — HOST_RAM_GB schema gap (same symptom, different root cause)
• bug: PUT /api/settings/env round-trip rebuilds file from .env.example template, drops keys not in schema #335 — _render_env_from_values rebuild bug (manifests after this fix unblocks PUT)

[yasinBursali]

Test Results — 12APRdevelopments branch (commit 2e238b3), WSL2 Ubuntu 24.04.4

Status: CONFIRMED

Reproduction (via stale GET cache + non-schema key)

1. Add non-schema key: echo 'MY_CUSTOM_KEY=hello_world' >> ~/dream-server/.env
2. GET /api/settings/env — cached response now includes MY_CUSTOM_KEY in values
   (the cache includes it because _read_env_map_from_path reads all keys, and the cache was set before cleanup)
3. PUT /api/settings/env with the cached values (which include MY_CUSTOM_KEY) → 503:

   {"detail": {"message": "Unknown key: MY_CUSTOM_KEY"}}

Root cause chain

The host agent (dream-host-agent.py lines 649–663) validates every key in the submitted .env text against .env.schema.json:

if key not in allowed_keys:
    json_response(self, 400, {"error": f"Unknown key: {key}"})
    return

The dashboard-api converts the host agent's 400 into a 503 (lines 1351–1358 of main.py).

This breaks all dashboard settings saves as long as a non-schema key appears in the values submitted to PUT. Extension install hooks that write custom keys to .env trigger this.

Interaction with #331/#335

These three issues form a triangle:

• bug: extension install hooks bypass core .env schema, then break PUT /api/settings/env with 503 #345 (this one): non-schema key gets into submitted PUT values → 503, nothing written
• bug: read-only extensions mount blocks built-in template activation — every catalog template apply fails 500 #331/bug: PUT /api/settings/env round-trip rebuilds file from .env.example template, drops keys not in schema #335: if the non-schema key is NOT in submitted values, PUT succeeds but the key is silently dropped from the file

The fundamental conflict is between the host agent's strict schema validation and the dashboard-api's inclusive current_values merge.

[yasinBursali]

Fixed in Light-Heart-Labs#908 — relaxed unknown-key validation to warn-and-accept so extension-added keys no longer cause 503 on Settings save.