Add secretspec support by domenkozar · Pull Request #16300 · NixOS/nix

domenkozar · 2026-08-13T23:16:53Z

Nix credentials currently have to be stored as literal configuration values. This makes long-lived forge tokens, netrc contents, and build secrets visible to configuration introspection and harder to manage through external secret providers.

I've written about this in secrets don't belong in config.

This PR introduces first-class support for https://secretspec.dev (akin to terraform) that comes currently with support for 30 secrets providers via pkgs.secretspec-ffi.

secretspec-access-tokens = github.com=GITHUB_TOKEN
secretspec-netrc-file = NIX_NETRC
secretspec-impure-env = PRIVATE_TOKEN=BUILD_TOKEN
secretspec-file = /etc/nix/secretspec.toml
secretspec-profile = production
secretspec-scope = nix

Nix ships with its own secretspec.toml that can be overiden for customization via secretspec-file.

It also comes with an extensive test suite.

How it works

SecretSpec separates secret declarations from secret values:

secretspec.toml declares the available secret names and whether each
secret is an inline value or a materialized file.
secretspec-provider, secretspec-profile, and secretspec-scope
select the resolution context.
Nix settings map existing credential consumers to SecretSpec names.
The value is resolved lazily, only when that consumer needs it.

Closes: #6536
Related: #8635
Related: #6942

Nix credentials currently have to be stored as literal configuration values. This makes long-lived forge tokens, netrc contents, and build secrets visible to configuration introspection and harder to manage through external secret providers. Allow these credentials to be referenced by SecretSpec name and resolved only when used. Support GitHub, GitLab, and SourceHut access tokens with the existing host and path-prefix matching, complete netrc files, and impure environment variables requested by fixed-output derivations. Preserve compatibility by preferring literal values for equally specific access-token mappings and equally named impure environment variables. SecretSpec netrc files take precedence over netrc-file. Prevent flakes from configuring credential-bearing settings, even when flake configuration is accepted. Propagate the requesting client trust level through local and remote builds so untrusted daemon clients cannot consume daemon-configured SecretSpec impure environment mappings. Make SecretSpec support optional at build time so libstore remains available where secretspec-ffi cannot be built. Closes: NixOS#6536 Related: NixOS#8635 Related: NixOS#6942 Assisted-by: Claude Code (claude-opus-5) Assisted-by: Codex (GPT-5)

domenkozar · 2026-08-14T00:15:59Z

We could even go further to provide helpers for migration from existing files, but that would need a bit more work.

[project]
name = "nix"
revision = "1.0"

# `system` is intentionally supplied by the machine's global SecretSpec config.
# This alias exposes the existing /etc/nix/netrc as a migration source.
[providers]
legacy_netrc = "file:///etc/nix"

[profiles.default]
NIX_NETRC = {
  description = "Complete netrc file used by Nix",
  required = false,
  as_path = true,
  providers = ["system", "legacy_netrc"],
  refs = {
    legacy_netrc = { item = "netrc" },
  },
}

and then migrate:

$ secretspec \
    --file /etc/nix/secretspec.toml \
    --profile default \
    import legacy_netrc \
    --delete-source

I'll add ini support to file provider then we can also extract access-tokens as part of migration.

xokdvium

Lots of very questionable things here.

xokdvium · 2026-08-14T06:20:14Z

+    /* Keep every resolved context alive so an in-flight user never observes an
+       `as_path` file being deleted after a configuration change. */
+    mutable Sync<std::map<SecretSpecRequest, std::shared_ptr<SecretSpecCache>>> _caches;
+
+    /* Serializes resolution so that a request is resolved only once, without
+       blocking cache lookups for the duration of the resolution. */
+    mutable std::mutex _resolveMutex;


Eh, I'm feeling like a parrot at this point. No, please. No more global mutable state until we figure out how to not rely on globals for things.

Having global credentials (especially stuffed into the settings systems) seems like a disaster waiting to happen.

xokdvium · 2026-08-14T06:22:32Z

+        if (globalConfig.getFlakeConfigSetting(baseName) == FlakeConfigSetting::Forbidden) {
+            warn("ignoring flake configuration setting '%s' because it is not allowed to be set by flakes", name);
+            continue;
+        }


Alternatively, can we remove nixConfig ? :)

I don't think this makes much sense considering how nixConfig now can RCE you pretty trivially.

xokdvium · 2026-08-14T06:23:39Z

    {
        std::string value;
        std::string description;
+        FlakeConfigSetting flakeConfigSetting;


Seems like a huge layer violation to pollute libutil with flakes.

xokdvium · 2026-08-14T06:25:47Z

+static const ResolvedSecret & getSecret(const SecretSpecCache & cache, const std::string & name)
+{
+    if (auto error = cache.errors.find(name); error != cache.errors.end())
+        std::rethrow_exception(error->second);


This will lead to data races and mutation of the refcounted exception. This is not how to rethrow shared errors. The trace system mutates them.

xokdvium · 2026-08-14T06:29:13Z

-    Worker(Store & store, Store & evalStore);
+    Worker(Store & store, Store & evalStore, TrustedFlag requestTrusted = Trusted);


Seeing how we'd love to make the worker less ephemeral and properly reusable this seems like the wrong abstraction layer.

Also the default argument seems very footgunny if the idea is that it's security relevant?

xokdvium · 2026-08-14T06:30:05Z

 {
    copyDrvsFromEvalStore(drvPaths);
    auto conn(store->getConnection());
+    setOptions(*conn);


xokdvium · 2026-08-14T06:32:48Z

+std::string SecretSpecSettings::defaultFile()
+{
+    return NIX_SECRETSPEC_FILE;
+}
+


Hm, usually nix (in static builds) does not rely on non-embedded data.
Or at least we try to. Seems like that would break that?

xokdvium · 2026-08-14T06:54:48Z

Tbh I think we should have a better way to abstract around credential providers, so that it's much more hidden away and sits behind a consistent interface. That should hopefully allow us to pay off the existing tech debt around credentials too.

arianvp · 2026-08-14T08:42:39Z

Linking nix against 27 cloud SDKs transitively sounds like a terrible idea. We just made a lot of effort getting rid of the aws SDK dependency.

Keeping nix’s dependency footprint small is useful for static linking, and trust bootstrapping.

Why not have an interface like varlink over Unix domain sockets for credential brokerage? So that nix can talk to some secretspec credential daemon?

that way we don’t explode the build time dependency footprint of nix. Credentials are a runtime concern; move it to a runtime daemon.

This is also what https://spiffe.io does (albeit gRPC; not varlink)

I started a similar discussion here systemd/systemd#40469

but iirc there are also similar discussions happening in gnome

another option would be exploring introducing this as a nix plugin? though personally I’m very much in IPC > shared library camp for plugin-shaped things.

KiaraGrouwstra · 2026-08-14T10:55:22Z

iiuc, the fix to store leakage here could be a simple as having the interface be a file (or what @arianvp said) rather than the secret itself?
now, in nixpkgs.lib i think NixOS/nixpkgs#503858 could bridge that already, without changes on the nix side.
even if we wanted a native solution from the nix end itself tho, why tightly couple things rather than say having such a more generic interface make for the boundary?

grahamc · 2026-08-14T15:38:29Z

Related: #9857 and rebased in #16087

xokdvium · 2026-08-15T05:52:13Z

In line with @arianvp's comment. Could we maybe indeed come up with a simple varlink interface / internal cred API (maybe consolidate with from #16087), so that it doesn't require too many changes to the internals?

jaen · 2026-08-16T12:50:17Z

simple varlink interface / internal cred API

Ditto to this, I have a weird personal secrets thing (nothing pre-existing worked well for my LUKS setup after scripted stage1 got deprecated) and I'd rather just plug it in to some extension point rather than be forced to migrate to something else that may or may not support my use-case.

It's also probably good to keep options open until the ecosystem at large converges on one option, instead of blessing an arbitrary one.

domenkozar · 2026-08-17T17:16:50Z

Thanks everyone for feedback, I'll try to incorporate it in next iteration.

Draft for Resolver and Provider IPC for secretspec is ready. Feedback welcome!

Provider allows talking to secretspec cli without bringing in huge dependency chain, like for Nix.

Provider IPC allows you to build your own provider!

domenkozar · 2026-08-19T17:10:00Z

simple varlink interface / internal cred API

Ditto to this, I have a weird personal secrets thing (nothing pre-existing worked well for my LUKS setup after scripted stage1 got deprecated) and I'd rather just plug it in to some extension point rather than be forced to migrate to something else that may or may not support my use-case.

Could you share what's missing bit? I'm happy to integrate that into our proposal for IPC.

It's also probably good to keep options open until the ecosystem at large converges on one option, instead of blessing an arbitrary one.

I'm going to rework the PR so it integrates secretstpec via IPC but leaves options open for other protocols to co-exist.

That way we can improve our protocol given the feedback while allowing anyone else to add their own.

domenkozar · 2026-08-20T23:39:14Z

I've split out secrets abstraction inside Nix into #16339 where I explain why it's better to have a generic interface inside instead of #9857 / #16087

Once I'm happy with IPC (reviews welcome) inside secretspec, I'll redo this PR as requested by many. That should also get rid of the other review raised, all globals being removed (which #957 btw has two).

nixos-discourse · 2026-08-26T13:08:25Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/secrets-don-t-belong-in-config/79078/40

nixos-discourse · 2026-08-31T19:28:40Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/secretspec-0-20/79863/1

domenkozar requested review from Ericson2314 and edolstra as code owners August 13, 2026 23:16

github-actions Bot added documentation with-tests Issues related to testing. PRs with tests have some priority store Issues and pull requests concerning the Nix store fetching Networking with the outside (non-Nix) world, input locking labels Aug 13, 2026

github-project-automation Bot added this to Nix documentation Aug 13, 2026

domenkozar force-pushed the secretspec branch from eb9ea2a to 6b5e7dc Compare August 13, 2026 23:26

xokdvium requested changes Aug 14, 2026

View reviewed changes

hsjobeki mentioned this pull request Aug 14, 2026

(Draft) NixOS vars NixOS/nixpkgs#547171

Draft

domenkozar mentioned this pull request Aug 20, 2026

Add secret resolver plumbing #16339

Open

		Worker(Store & store, Store & evalStore);
		Worker(Store & store, Store & evalStore, TrustedFlag requestTrusted = Trusted);

Uh oh!

Uh oh!

Conversation

domenkozar commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How it works

Uh oh!

domenkozar commented Aug 14, 2026

Uh oh!

xokdvium left a comment

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

xokdvium commented Aug 14, 2026

Uh oh!

arianvp commented Aug 14, 2026

Uh oh!

KiaraGrouwstra commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grahamc commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xokdvium commented Aug 15, 2026

Uh oh!

jaen commented Aug 16, 2026

Uh oh!

domenkozar commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

domenkozar commented Aug 19, 2026

Uh oh!

domenkozar commented Aug 20, 2026

Uh oh!

nixos-discourse commented Aug 26, 2026

Uh oh!

nixos-discourse commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

domenkozar commented Aug 13, 2026 •

edited

Loading

KiaraGrouwstra commented Aug 14, 2026 •

edited

Loading

grahamc commented Aug 14, 2026 •

edited

Loading

domenkozar commented Aug 17, 2026 •

edited

Loading