A way to tell fnox how to get a secret for a provider

[KyleChamberlin]

today, I need to externally provider some configuration to fnox (e.g. VAULT_TOKEN) but if I have multiple providers defined with different vaults, I need to know ahead of time which vault fnox needs, and replace the VAULT_TOKEN variable with one for the correct vault. Ideally, a provider should have some configuration that allows us to define how to get the credentials. I would love it if this was consistent across providers, but that isn't a deal breaker.

We could create a raw "command" concept that allows us to pass in an arbitrary command that returns the token, something like:

[providers.vault-one]
type = "vault"
address = "https://my-vault-one.com/"
path = "secret/over/here"
credential-command = "VAULT_ADDR={{address}} vault login -method=oidc -field=token" 

or we could create a more purpose driven config per provider, that allows us to configure args and such for the login command, something like:

[providers.vault-one]
type = "vault"
address = "https://my-vault-one.com/"
path = "secret/over/here"
credential = { method = "oidc" }

[KyleChamberlin]

I just want to get some idea of if this makes sense for fnox, and if it is then we can play around with what design or principles make the most sense.

[jdx]

Thanks for bringing this up Kyle - this is a real pain point, especially when working with multiple instances of the same provider type.

I've been thinking through a few approaches (AI-assisted analysis):

Current State

fnox already supports StringOrSecretRef for provider config fields, allowing things like:

[providers.vault-one]
type = "vault"
address = "https://my-vault-one.com/"
token = { secret = "VAULT_ONE_TOKEN" }  # references another secret

But this doesn't solve the bootstrap problem - how do you obtain the token in the first place?

Proposed Path Forward

I'm leaning toward a hybrid approach:

Phase 1: Generic credential-command

[providers.vault-one]
type = "vault"
address = "https://my-vault-one.com/"
path = "secret/over/here"
credential-command = ["vault", "login", "-method=oidc", "-field=token"]

• Array format avoids shell parsing/injection issues
• Command stdout becomes the credential
• fnox sets provider-specific env vars before running (e.g., VAULT_ADDR)
• Similar pattern to SSH ProxyCommand or Git credential helpers
• Works for any provider immediately

Phase 2: Provider-specific credential configs

[providers.vault-one]
type = "vault"
address = "https://my-vault-one.com/"
credential = { method = "oidc", role = "my-role" }

• Type-safe, better error messages
• Provider implements auth natively (no shelling out)
• Add common auth methods over time (OIDC, AppRole, etc.)

Open Questions

1. Should credentials be cached for the session duration?
2. For credential-command, do we need template variables like {address}, or is setting env vars sufficient?
3. Should this be consistent across all providers, or is it okay for some providers to have richer credential options than others?

Thoughts?

---

This response was drafted with AI assistance

[KyleChamberlin]

Thanks for the detailed breakdown. A few thoughts on the approach and open questions:

On the phased approach:

• Phase 1 (credential-command) is pragmatic, it unblocks users immediately without coupling fnox to specific auth implementations.
• Phase 2 is more ergonomic but does tie the codebase to provider-specific auth flows that may evolve independently.

I think this approach makes a ton of sense. I can put together a draft PR if you'd like for phase 1 so we can have a more technical discussion of the implementation.

On the open questions:

1. Credential caching: Yes, some form of TTL-based caching makes sense. Vault tokens include a TTL in the login response, so ideally fnox could parse and respect that. For Phase 1 (command-based), a user-configurable credential-ttl would be a reasonable fallback since the command output is opaque. Additionally, it is worth noting that there is a vault command (vault token) that will return the current token and can provide information about expiry. I think in a Phase 2 approach we can be more pragmatic about only calling a login command when the token is expired and using the vault login command just when the token needs a refresh. This also offloads fnox from being the responsible party for caching this token. (as an aside, the vault cli just stores the token in the clear in a file in $HOME so I don't think we would be lowering the bar if we cached the token ourselves.)
2. Template variables vs env vars: templating is likely a nice-to-have and can save a lot of duplicated information, but I don't know if the juice is worth the squeeze, I guess it just depends on what exactly we plan on supporting. do we want to support the full tera feature set? Also, in a phase 2 approach, we can likely just infer some of what is likely to be templated (host/address, namespace) outright, and wouldn't need to support templating.
3. Consistency across providers: I think consistency is a nice-to-have, not a hard requirement. Different providers have fundamentally different auth models. Phase 1's credential-command naturally provides a consistent escape hatch across providers, while Phase 2 can offer richer, provider-specific options where it makes sense.
   One additional consideration: For the array format in credential-command, is there a plan to handle commands that need shell features (pipes, redirects)? Requiring users to wrap those in sh -c "..." is fine, but worth documenting.

[jdx]

even if we don't have any specific templating stuff today it'd be a good idea to have tera template it anyways, that way users will need to escape tera syntax anyways and we can later adopt tera without it being a breaking change

I think maybe just automatically doing "sh -c" would be a good idea actually and just making this a string would be the way to go. I definitely do that in mise and hk—I'm not actually sure if we have this pattern anywhere in fnox yet but it probably makes sense to be consistent across hk/mise. There can be some quirks with that especially around windows where you can't just /bin/sh though.

[nipuna-perera]

I agree with the proposal here - #171 (comment) and would like to add

We have a need to use the -mount flag to retrieve the secret. Otherwise the cli uses the sys/internal path which returns a 403.

We also require oidc login, so, for individual secrets (or at the provider level) we'd like to pass through flags to the CLI for secret retrieval on top of being able to use a specific login method.

As you suggested, allowing the consumer to configure that makes sense and is easier to maintain rather than baking all the provider options into fnox.