configuration-runtime-resolution

Configuration Runtime Resolution

Purpose

Use this skill when generated Caddyfiles rely on values resolved during provisioning. Runtime replacement is implemented in caddyfile_resolve.go and tested by caddyfile_resolve_test.go.

Keep this skill aligned with github.com/greenpau/go-authcrunch config shapes: some sections preserve raw encoded directive arguments and are revalidated after replacement, while others are typed structs where only selected fields are resolved.

Replacement Forms

Use Caddy replacer placeholders for environment-backed values:

password {env.SMTP_PASSWORD}
client_secret {env.OIDC_CLIENT_SECRET}
crypto key sign-verify {env.JWT_SHARED_KEY}

Use secrets manager lookups for values provided by security.secrets modules:

password "secrets:users/jsmith:password" overwrite
crypto key sign-verify "secrets:access_token:shared_secret"

Secret lookup syntax is:

secrets:<secret_id>:<key>

The secret_id must match the second argument of a secrets <plugin> <secret_id> block, and <key> must be returned by that secrets manager.

Secret lookups run after Caddy replacer expansion and must be the entire value. The parser accepts exactly three colon-separated parts, so the secret key cannot contain another colon.

What Gets Resolved

ResolveRuntimeAppConfig mutates the authcrunch app config, then calls the affected authcrunch Validate methods so derived configs are rebuilt. The app supplies a fresh config copy for each runtime; never run resolution on a serving graph. JSON inputs can omit optional portal UI and cookie settings. Resolve those fields only when present and leave their defaults to AuthCrunch. Reject null entries in typed component collections, including nested ACL, redirect, credential, and registration objects, before calling validators or constructors. app_config.go uses explicit typed validators and generic slice and map helpers for those checks, following the coding skill's prohibition on reflect. When upstream adds a component collection, extend its typed validator and unit/E2E coverage. The checks permit omitted optional objects and leave flexible parameter maps to the resolver. After substitution, decode local/LDAP/OAuth/SAML parameter maps into AuthCrunch's exported config types and check decoding errors and null objects. Some dispatch validators ignore JSON decoding errors; do not let a partially decoded user or provider config reach construction. Reuse upstream types and semantic validation instead of maintaining field allowlists here. Object lists in those maps must contain objects throughout; do not silently skip a null or scalar entry after the first object. Return field paths so malformed replacements fail without disrupting the active deployment. The unit tests in app_lifecycle_test.go and actual Caddy reload tests in app_lifecycle_e2e_test.go cover these JSON provisioning cases.