Files
configkit/docs/adr/0023-explicit-configured-secrets-bootstrap.md

61 lines
2.7 KiB
Markdown

# ADR 0023: Keep Configured Secrets Bootstrap Explicit
## Status
Accepted. Supersedes [ADR 0004](0004-secret-references-and-explicit-bootstrap.md).
## Date
2026-11-18
## Context
Applications may discover their main configuration file during startup and keep
secret files beside it. Requiring applications to discover and parse that file
separately duplicates ConfigKit's work. Some deployments also need secret files
to replace environment values that are already set.
## Decision
Keep secrets as typed references to environment-variable names. Resolve surviving
references and keep credential values out of configuration trees, history, and
inspection. Applications own credential use.
Directory bootstrap remains a separate startup operation that the application
must call explicitly. Ordinary configuration loading never writes the process
environment. The application may supply the directory directly or authorize
bootstrap from settings in the selected main document. Imports, underlays,
overlays, and later application processing do not choose those settings.
When bootstrap uses the main document, ConfigKit selects and captures that
document and its filesystem context for subsequent loading. This keeps bootstrap
and loading tied to the same main contents and location. It does not snapshot
later imports, resources, or the environment.
Preserve existing environment variables by default, including empty values.
Allow an explicit overwrite choice. An application-supplied choice takes
precedence over the main document's choice, including an explicit choice to
preserve existing values.
Keep bootstrap reports separate from later secret-lookup evidence. Report
writes, skips, and partial failures without credential values. Bootstrap offers
no rollback or transaction across environment variables and no protection
against concurrent environment mutation. General environment-variable
configuration overlays remain outside this model.
## Alternatives Considered
- Leave discovery and parsing to applications. This preserves duplicate startup
infrastructure and can select different main contents for bootstrap and loading.
- Run bootstrap inside ordinary loading. This hides process mutation in an
operation applications may repeat or run concurrently.
- Always preserve existing environment values. This keeps one precedence rule
but prevents deployments from explicitly choosing provisioned files instead.
## Consequences
Applications retain control of startup ordering and environment writes.
ConfigKit owns main-source capture, bounded secret-file loading, and safe
reporting. A later configuration failure leaves completed bootstrap writes in
place. Existing callers retain the preservation default.