Provide app secrets via environment variables / Kubernetes secrets (DOT_{APP_KEY}_{HOSTNAME}_{APP_VALUE_KEY})

Parent

User Story / Enhancement

Problem

dotCMS app secrets (the Apps framework, com.dotcms.security.apps) can today only be fully configured through the UI / stored secrets store. There is an existing env-var hook (AppsUtil.guessEnvVar → APP_{APP_KEY}_PARAM_{APP_VALUE_KEY}), but it:

• is not host-aware (one var overrides a param for every site),
• only enriches an existing stored blob — it cannot provision an app on a host that has no stored config,
• has override semantics that aren't expressed as a clear precedence model.

This blocks headless / IaC / Kubernetes deployments where secrets should be injected at the platform level.

Proposal

Add per-host environment-variable / Kubernetes-secret provisioning for all apps using the pattern:

DOT_{APP_KEY}_{HOSTNAME}_{APP_VALUE_KEY}

plus a global System Host form DOT_{APP_KEY}_SYSTEM_HOST_{APP_VALUE_KEY}.

Resolution is per-param, specificity-first (highest → lowest):

1. host-specific env — DOT_{APP_KEY}_{HOSTNAME}_{APP_VALUE_KEY} (locks the UI field)
2. host-specific stored / UI value
3. System Host env — DOT_{APP_KEY}_SYSTEM_HOST_{APP_VALUE_KEY}
4. legacy global env — APP_{APP_KEY}_PARAM_{APP_VALUE_KEY} (deprecated, throttled warning)
5. System Host stored value

Behavior

• Full provisioning: an app with no stored blob is usable purely from env vars (partial provisioning returns only env-backed params).
• Normalization: env var names use Config.envKey() only (uppercase, dots/dashes → underscores, DOT_ prefix) — no parallel normalization; construct-and-lookup from AppDescriptor.getParams() (never parses arbitrary env vars). A registered descriptor is required.
• Editability: only tier-1 (host-specific env) locks the field read-only; global tiers stay editable so a deliberate per-host stored value still wins.
• fromEnv: exposed on the Java Secret object and the REST SecretView (boolean; no tier enum).
• Listing/presence: listAppKeys, appKeysByHost, filterSitesForAppKey report env-only apps as configured (lazy detection; System Host/legacy tiers mirror the stored System Host cascade).
• fallbackOnSystemHost=false suppresses both System Host tiers (3 and 5).
• Masking follows the descriptor param type regardless of source; env values are returned raw (no coercion).

Out of scope

Live/hot secret rotation without restart (env vars are process-static), file-mounted-secret watching, type coercion, startup index, tier-enum REST field.

Backward-compatibility note

The legacy APP_..._PARAM_... pattern keeps working as tier-4 (with a deprecation warning), but precedence becomes specificity-first: a host-specific stored value now wins over the legacy global env var (previously legacy env overrode stored). Existing integration tests asserting the old override semantics will need to be updated.

Start with AppsUtil.guessEnvVar and the app resolution paths, then inspect AppDescriptor.getParams() and Config.envKey() for environment-name construction. Review the Java Secret and REST SecretView representations, app-key listing methods, and integration tests covering legacy override semantics. Done means the specified precedence, provisioning, masking, presence, and fallback behavior are covered by tests.