Files
configkit/docs/roadmap/secrets-directory.md

147 lines
8.0 KiB
Markdown
Raw Normal View History

# Main-relative secrets directories
## Motivation and baseline
Applications can use `SearchConfig` to select their main configuration file
during a load. They can also call `LoadSecretsIntoEnvironment` during startup,
but that helper takes a native directory path before the load begins. A relative
argument uses the process working directory. Using a directory beside the
discovered file therefore requires the application to take over main-file
selection or perform a preliminary load. [Configuration discovery](../config.md#configuration-discovery) · [Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap)
ConfigKit already carries the selected main's filesystem context into layered
loading. It resolves effective typed `Secret` references after application
resolution and before final validation. Those two points provide the base for
the directory and the set of credential names to read. [Main-relative contexts](../adr/0022-main-relative-context.md) · [Typed secret references](../config.md#typed-secret-references)
## Target behavior
### Declaration and path resolution
An application opts in through Go when calling `Load` or `LoadLayered`. The
selected main document supplies one relative directory through its root control
mapping. For example, the following declaration in `/etc/demo/config.yml`
selects `/etc/demo/secrets` when discovery selects that main file.
```yaml
config:
secrets_dir: secrets
api_key: DEMO_API_KEY
```
Interpret the declaration at the main document's root before placement and
composition. Diagnose a declaration used without opt-in or in an unsupported
source-control context. Nested application data follows the existing
`config` rules. The location comes from the main document even when an import,
overlay, CLI override, default, or application resolution supplies the final
credential name. Environment lookup alone applies when there is no declaration,
including when an optional search finds no main file.
Resolve the directory from the selected main file's canonical base within its
existing filesystem root. For a discovered symlink, the base is the selected
file's canonical target directory. Parent-relative paths follow the same
containment rule as other main-relative inputs. The declaration must be a
nonempty relative path and requires a usable main-file context. Keep the
declaration and any diagnostics in source-local coordinates. [Document-root controls](../adr/0020-document-root-controls.md) · [Layered loading](../config.md#layered-loading)
### Lookup within a load
The usual opt-in mode checks the environment first. A present variable wins,
including an empty one, which produces the existing empty-secret failure. For
an unset variable, read the file whose name matches the effective typed
`Secret` reference. The directory is accessed only if a reference needs a file.
An application can also select file-first lookup for a load. An absent file
allows environment lookup. A file that is present but unreadable or invalid
produces a safe diagnostic, and an empty file follows the existing rule that a
resolved credential must be nonempty. If neither source supplies a credential,
report the failure at the affected configuration field.
Resolve surviving references at the existing secret-resolution step and share
the lookup result for repeated names within that load. Use the existing
secret-file checks, content rules, and per-file and cumulative byte limits for
the files read. Exact-name lookup leaves unrelated directory entries alone.
Close library-owned handles during the load. Final validation sees the
resolved credentials, with byte access through `Secret.Value()`. Inspection
can distinguish the environment and a file as the credential provider while
keeping credential bytes outside diagnostics, history, and effective YAML.
### Explicit startup export
Applications that start SDKs or subprocesses which read the environment can
explicitly request file-first loading and environment export. This is a
startup operation distinct from the ordinary load entry points. Go code
authorizes writes and overwrites. The main-file declaration selects the
directory.
Complete configuration loading and validation before writing to the process
environment. Export the values of the file-backed effective references used
by that successful load, once per name. Each successful write sets the
variable to the same value used by the returned configuration. If a file is
absent and lookup uses an existing environment value, leave that variable alone.
Invoke this operation during startup before starting concurrent work. It runs
synchronously and reports successful writes and partial failures without
credential bytes, following the existing bootstrap reporting model. ConfigKit
does not roll back earlier writes when a later write fails.
Ordinary `Load` and `LoadLayered` resolve credentials for their own results
without writing to the environment. The existing
`LoadSecretsIntoEnvironment(directory)` remains the explicit startup helper
for callers supplying a directory independently. [Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Secret references and explicit bootstrap](../adr/0004-secret-references-and-explicit-bootstrap.md)
## Work needed
- Extend main-document control parsing and the public load options to capture
the opted-in declaration and bind it to the main context already obtained
during acquisition. Carry the binding into secret resolution without another
search or parse.
- Reuse the secret-file reading and validation rules for exact-name lookup.
Extend the operation-local lookup to report value-free filesystem failures
and retain the provider for inspection separately from configuration value
provenance.
- Add the explicit startup operation around the shared load lifecycle. Use the
resolved file values for export and reuse the bootstrap reporting semantics
where they fit.
- Verify discovery from a different working directory, canonical main paths,
declaration scope, both lookup orders, and effective references after
composition and application resolution. Cover unused and missing files,
empty values, read errors, safe inspection, and startup export after
validation, including partial writes and absence of writes on a failed load.
Use disposable credential values and deterministic failure seams in line
with the [testing policy](../policy/testing.md).
- Document the resulting contract and a consumer startup example. Record the
architectural decision to add file-backed resolution and explicit startup
export alongside ADR 0004, and align the current architecture and component
documentation when the feature lands.
## Open Decisions
### Startup API and export failure reporting
**Recommendation.** Provide explicit startup entry points corresponding to
ordinary and layered loading, backed by the same load implementation. Return
the configuration outcome and the export report so callers can distinguish a
failed load from a successful load followed by an environment write failure.
The successful load's private file values can be handed directly to export
within the call, which keeps the application flow short and the lifetime of
those values local to the startup operation.
**Alternative.** Export from a successfully returned result through a separate
explicit call. This gives applications control over when to perform the writes
and avoids a parallel pair of load entry points. It requires a result contract
for retaining the original file-backed assignments or defining how later
application edits to the result affect export.
### Filesystem scope
**Recommendation.** Support discovered and explicitly selected host files
first, including their existing main-root options. These cover the requested
deployment pattern and allow reuse of the existing native secret-file checks.
**Alternative.** Support caller-supplied filesystems with a usable main-file
context in the same change. This aligns with companion inputs and supports
virtual filesystems. It requires an explicit decision about file-type and
symlink handling where a caller filesystem exposes different metadata or
access capabilities.