diff --git a/docs/roadmap/secrets-directory.md b/docs/roadmap/secrets-directory.md new file mode 100644 index 0000000..b72c864 --- /dev/null +++ b/docs/roadmap/secrets-directory.md @@ -0,0 +1,146 @@ +# 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.