Proposal: Support secret refs to decouple secret/provider definition and use

[brian-dlee]

Proposal

I really like fnox and the combination with mise. Coming from asdf and direnv, I'm finding elegant solutions for many issues I've experienced over the few years of using these tools. As I dug into fnox, I found myself looking for one feature that is yet to exist, a way to defining the parameters of a secret without forcing that secret to be active. I'm calling this refs.

Background / How I use fnox

When I started reading up on fnox, it read like a great tool that allowed me to declare that a certain project requires a key to run effectively. In my world, this is often in Pulumi apps for projects. If my project maintains a Temporal resource then I need to communicate to the team that TEMPORAL_CLOUD_API_KEY must be defined for this project for pulumi up to work. The pattern I wanted was to publish documentation or a simple shell tool to tell my infrastructure team about the relevant administrative tokens/keys they would need to deploy different services. They could use the mechanism that works for them (fnox has great provider support) and when they enter a directory or use fnox exec the environment is properly hydrated automatically due to an fnox.toml file committed to the project. Most of this works excellent and appears to match the vision. And the if_missing behavior matches my need very well to grant surface missing credentials early.

Issues

The issue I've found is that when a developer runs fnox set (the most convenient and intuitive way to define a missing value) it wants to edit the fnox.toml file. I tried stubbing the the fnox.toml files with SECRET = {}. I was hoping this would work fulfill my need but when a user runs fnox set or fnox list it still wants to change the secret config in the file and fnox list doesn't offer great details on where the secret is coming from if it is set because it is influenced by the empty brackets in the local file. I'm afraid of these fnox.toml file modifications will cause churn and confusion as engineers configure their systems.

Secondly, if I define secrets globally I can set them once and kind of reference them in projects using the stub format I mentioned previously but when I do that they are active and I risk them being available in cases where I may not want them which increases the chance of leaking them through arbitrary servers, running agent harnesses or any other execution in the directory space that inherits the secrets.

Proposal

My refs proposal grants me the ability to define/declare the secrets once and then separately define when they should be active. It also allows me to separate the provider configuration and other parameters from the secret usage. Connecting this to fnox set and fnox list would allow fnox to follow the parameters back to how I've defined them and indicate their status without me having put any of that information in the project fnox.toml file.

Global config

# ~/.config/fnox/config.toml
[providers]
op = { type = "1password", account = "onenpasswordaccountid" }

[refs]
GITHUB_TOKEN = { provider = "op", value = "op://Private/github_token/password" }
TEMPORAL_CLOUD_API_KEY = { provider = "op", value = "op://Private/temporal_cloud_api_key/password" }

Workspace config

# ~/Work/orgname/fnox.toml

# I use MCP servers and things that always seem to need access to a GITHUB_TOKEN so I make
# it available across my whole workspace.

[secrets]
GITHUB_TOKEN = { ref = "GITHUB_TOKEN" }

Project config

# ~/Work/orgname/project/pulumi/fnox.toml

# this would be a project that uses temporal. I drop a fnox.toml in the pulumi/ directory
# so the token is ONLY exposed when I need to use it. General tasks in the app itself do
# not need this admin account. The ref system could also potentially allow elegant ways to
# override credentials with different keys using multiple refs but filing into the same secret
# leveraging the built-in layering functionality.

[secrets]
TEMPORAL_CLOUD_API_KEY = { ref = "TEMPORAL_CLOUD_API_KEY" }

This system makes my fnox.toml files stable. I can commit them and each engineer can choose to configure them in a way
that works for them and their machine.

In my vision for this feature, fnox set and fnox list would follow the ref back to the original definition as if it were inline
here. In my example, fnox set TEMPORAL_CLOUD_API_KEY ... from the project would attempt to set the 1Password
field op://Private/temporal_cloud_api_key/password. Similarly, fnox list wouldn't show a generic stored value, but instead
it would actually show where the value is sourced as it it were inlined.

Related discussions

I briefly looked through other discussions. I think this proposal could be an elegant solution to a couple discussions or work well with
them: #163 and #146. It contains some similar ideas to #85 and perhaps could help it along.

Honestly, I think it's a bit strange to propose a feature/change at such a core/fundamental area of the tool. I understand there is a
guiding vision I'm unaware of and I have no way of knowing if it conflicts or fits nicely. To me, it seems like a home run but that's
only from my narrow view. Any feedback would be greatly appreciated! I'm going to test my idea a bit in a private fork of the tool.

[jdx]

I don't think I like this design but I understand the problem

[brian-dlee]

Would you be interested in collaborating or discussing an alternative design? I'm happy to take the change and run with it if I have an understanding of what you are looking for.