App secrets: environment variable & Kubernetes secret provisioning with 5-tier precedence

Problem

dotCMS app secrets (e.g. analytics, AI, payment integrations) can currently only be configured by storing an encrypted secrets blob per host through the UI/API. In containerized/Kubernetes deployments, operators want to provision these secrets via environment variables and K8s Secrets injected as env vars, without clicking through the UI or pre-seeding a stored blob. There is partial/legacy APP_ env var support but no host-aware, specificity-first precedence model and no way to fully provision an app from env alone.

Goal

Provide environment variable and Kubernetes secret provisioning for dotCMS app secrets using a 5-tier specificity-first precedence model:

1. host-env — DOT_{APP_KEY}_{HOSTNAME}_{APP_VALUE_KEY} (read-only lock, tier 1)
2. host-stored — encrypted stored blob for that host
3. system-host-env — DOT_{APP_KEY}_SYSTEM_HOST_{APP_VALUE_KEY} (global default)
4. legacy-APP_-env — APP_{APP_KEY}_PARAM_{APP_VALUE_KEY} (deprecated, throttled warning)
5. system-host-stored — encrypted stored blob on System Host

DevOps teams will be able to fully provision an app from env vars (no stored blob required), with per-param independent tier walking, Config.envKey() normalization for the new DOT_ tiers, env-backed config counting as configured in all listing/presence methods, and a fromEnv boolean exposed on both Java Secret objects and REST responses.

Target Personas

• DevOps teams
• System administrators (dotCMS)
• Developer teams

Demo Expectations

In the demo we will: set DOT_{APP_KEY}_{HOSTNAME}_{APP_VALUE_KEY} env vars for a registered app with no stored secrets blob, restart dotCMS, and show the app appears configured in the apps listing and presence checks, the values resolve at read time, the host-specific env param is read-only (isEditable=false), and the REST response shows fromEnv=true. We will also show System Host (SYSTEM_HOST) global defaults cascading to child hosts, legacy APP_ vars still resolving with a one-time deprecation warning, and fallbackOnSystemHost=false suppressing both System Host tiers.

Acceptance Criteria

• Setting DOT_{APP_KEY}_{HOSTNAME}_{APP_VALUE_KEY} resolves as the highest-precedence (tier 1) host-specific value, read-only
• Stored host blob (tier 2) resolves when no host env var is present
• DOT_{APP_KEY}_SYSTEM_HOST_{APP_VALUE_KEY} (tier 3) resolves as global default for child hosts
• Legacy APP_{APP_KEY}_PARAM_{APP_VALUE_KEY} (tier 4) continues to resolve with throttled deprecation warning
• System Host stored blob (tier 5) resolves as final fallback
• Per-param independent tier walking fully provisions an app with no stored blob
• Config.envKey() normalization reused for DOT_ tiers 1 and 3
• Env-backed config counts as configured in all listing/presence methods
• fromEnv boolean present on Java Secret objects and REST responses
• isEditable=false applies only to tier-1 host-specific env vars
• fallbackOnSystemHost=false suppresses tiers 3 and 5
• Backward compatibility: existing APP_ env vars work without rename

Out of Scope

• Live hot-reload / secret rotation (restart-to-apply accepted)
• File-mount secret watching
• Type coercion/validation of env-sourced values at read time
• Startup secret index
• Tier enum in public REST API (only fromEnv boolean exposed)

Links

• Implementation in com.dotcms.security.apps (AppsAPIImpl, AppsUtil, AbstractProperty)
• Reuses com.dotmarketing.util.Config.envKey() normalization

Start by reading AppsAPIImpl, AppsUtil, AbstractProperty, and the existing Config.envKey() normalization. Trace current APP_ environment-variable resolution, listing and presence checks, Secret objects, and REST responses. Done means the five precedence tiers, independent parameter fallback, configured-state reporting, fromEnv, editability, warnings, and fallbackOnSystemHost behavior meet the acceptance criteria.