Support environment variable placeholders in config validation

[npeham]

Summary

Adds support for environment variable placeholders (e.g., ${ENV_VAR}) in LibreChat configuration files when imported via the admin panel. The admin panel doesn't have access to deployment-specific environment variables, so placeholders would previously fail schema validation. This change sanitizes placeholders before validation and restores them afterwards, allowing full structural validation while preserving placeholder syntax.

Change Type

• New feature (non-breaking change which adds functionality)

Implementation Details

New Utilities (src/server/utils/envPlaceholder.ts)

Two complementary functions handle placeholder management:

• sanitizeEnvPlaceholders(value) — Recursively walks a config object and replaces any string containing ${...} with a unique, schema-safe sentinel URL (https://env-placeholder.invalid/0, etc.), returning both the sanitized config and a Map<sentinel, original> for restoration.
• restoreEnvPlaceholders(value, placeholders) — Reverses the process by swapping sentinels back to their original placeholder strings using exact equality matching.

The sentinel format is deliberately chosen to satisfy URL validators (used in schema constraints like z.string().url()) while remaining obviously invalid for actual use.

Integration (src/server/config.ts)

The parseImportedYaml server function now:

1. Sanitizes the raw imported config before schema validation
2. Validates the sanitized config against configSchema
3. Restores placeholders in the validated config before returning
4. Also restores placeholders in the fallback config if AppService fails

This ensures that configs with environment variable placeholders pass validation and are returned with their original placeholder syntax intact.

Testing

Added comprehensive unit tests in src/server/utils/envPlaceholder.test.ts:

• Placeholder detection and sentinel replacement
• Handling of placeholder-free configs
• Embedded placeholders within larger strings
• Round-trip validation (sanitize → validate → restore)
• Integration with the real configSchema from librechat-data-provider

All tests pass and cover the core functionality and edge cases.

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in complex areas of my code (JSDoc on public functions)
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective
• Local unit tests pass with my changes

https://claude.ai/code/session_015i1Rwi3ms2TbF1upWF7LbX