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

8.0 KiB

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 · Secrets 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 · 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.

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 · 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 · Secret references and explicit bootstrap

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.
  • 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.