61 lines
2.7 KiB
Markdown
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.
|