[INVESTIGATION] Evaluate numtide/nix-auth for potential NixOS configuration integration #148

New issue

Closed

opened 2026-08-06 23:23:48 +01:00 by nimmo · 1 comment

nimmo commented

2026-08-06 23:23:48 +01:00

Owner

Investigation: numtide/nix-auth

Overview

Investigate the numtide/nix-auth repository to determine if it provides valuable enhancements, simplifications, or performance improvements for the NixOS configuration at https://git.nimmog.uk/nimmo/nixos-config.

Repository Information

URL: https://github.com/numtide/nix-auth
Description: Authentication helpers and patterns for NixOS systems

Investigation Goals

Understand the core functionality and purpose of nix-auth
Evaluate relevance to current NixOS authentication infrastructure
Identify potential integration points for simplifying or enhancing authentication handling
Assess maintenance burden and compatibility with existing SOPS-based secret management
Determine if proof-of-concept implementation is warranted

SOPS-based secret management in secrets/ directory
age encryption for secrets
Various service-specific tokens:
- Paseo tokens in secrets/git.yaml
- Trilium ETAPI token in secrets/trilium.yaml
- Hermes Matrix access token in secrets/hermes.yaml (though Hermes was removed)
- OpenCode/OpenRouter API keys in secrets/ai-runtime.yaml
- Beszel MCP credentials in secrets/ai-agents.yaml
- Engram cloud token in secrets/ai-agents.yaml
- Bookstack and Karakeep MCP credentials
NixOS services that consume these secrets via sops.nix
Default-config.nix authentication-related options

Specific Areas to Examine

Unified authentication configuration patterns that could replace scattered secret definitions
Integration approaches with existing SOPS infrastructure
Helper functions for generating/managing service tokens
Patterns for handling authentication across multiple services (Paseo, Trilium, Beszel, etc.)
Potential to simplify the complex secret management in secrets/

Suggested Evaluation Approach

Review documentation and README
Examine example usage patterns in NixOS context
Check compatibility with NixOS unstable channel
Test how it would integrate with current secrets.yaml structure
Evaluate if it could reduce complexity in secrets/ directory
Review maintenance history and community adoption
Examine if it works well with sops.nix and age encryption

Decision Criteria

Significant simplification of secret management complexity
Better organization and standardization of authentication patterns
Compatibility with existing SOPS+age encryption approach
Active maintenance and community support
Clear benefits over current ad-hoc secret handling

Notes for Investigating Agent

Feel free to adjust investigation focus based on initial findings
If a repository shows little promise, document reasons for closing investigation
If additional related repositories are discovered during investigation, feel free to create issues for those as well
Initial investigation should be time-boxed (e.g., 2-4 hours per repository max) unless significant promise is found

# Investigation: numtide/nix-auth ## Overview Investigate the numtide/nix-auth repository to determine if it provides valuable enhancements, simplifications, or performance improvements for the NixOS configuration at https://git.nimmog.uk/nimmo/nixos-config. ## Repository Information - **URL**: https://github.com/numtide/nix-auth - **Description**: Authentication helpers and patterns for NixOS systems ## Investigation Goals 1. Understand the core functionality and purpose of nix-auth 2. Evaluate relevance to current NixOS authentication infrastructure 3. Identify potential integration points for simplifying or enhancing authentication handling 4. Assess maintenance burden and compatibility with existing SOPS-based secret management 5. Determine if proof-of-concept implementation is warranted ## Current Related Infrastructure - SOPS-based secret management in secrets/ directory - age encryption for secrets - Various service-specific tokens: - Paseo tokens in secrets/git.yaml - Trilium ETAPI token in secrets/trilium.yaml - Hermes Matrix access token in secrets/hermes.yaml (though Hermes was removed) - OpenCode/OpenRouter API keys in secrets/ai-runtime.yaml - Beszel MCP credentials in secrets/ai-agents.yaml - Engram cloud token in secrets/ai-agents.yaml - Bookstack and Karakeep MCP credentials - NixOS services that consume these secrets via sops.nix - Default-config.nix authentication-related options ## Specific Areas to Examine 1. Unified authentication configuration patterns that could replace scattered secret definitions 2. Integration approaches with existing SOPS infrastructure 3. Helper functions for generating/managing service tokens 4. Patterns for handling authentication across multiple services (Paseo, Trilium, Beszel, etc.) 5. Potential to simplify the complex secret management in secrets/ ## Suggested Evaluation Approach - Review documentation and README - Examine example usage patterns in NixOS context - Check compatibility with NixOS unstable channel - Test how it would integrate with current secrets.yaml structure - Evaluate if it could reduce complexity in secrets/ directory - Review maintenance history and community adoption - Examine if it works well with sops.nix and age encryption ## Decision Criteria - Significant simplification of secret management complexity - Better organization and standardization of authentication patterns - Compatibility with existing SOPS+age encryption approach - Active maintenance and community support - Clear benefits over current ad-hoc secret handling ## Notes for Investigating Agent - Feel free to adjust investigation focus based on initial findings - If a repository shows little promise, document reasons for closing investigation - If additional related repositories are discovered during investigation, feel free to create issues for those as well - Initial investigation should be time-boxed (e.g., 2-4 hours per repository max) unless significant promise is found

nimmo added this to the NumTide Repository Evaluation milestone

2026-08-06 23:23:48 +01:00

nimmo added the

investigation

priority:medium

repo:numtide/nix-auth

area:authentication

labels

2026-08-06 23:23:48 +01:00

nimmo commented

2026-08-09 23:03:43 +01:00

Author

Owner

Evaluation conclusion: useful on demand, but do not integrate declaratively

Reviewed upstream numtide/nix-auth at commit d43fad3.

What it actually provides

nix-auth manages the Nix client's access-tokens setting for authenticated flake and fetcher access. It writes a mode-0600 ~/.config/nix/access-tokens.conf and adds an include to the user's nix.conf. It is not a general service-authentication framework and does not replace application secrets, environment files, OIDC client credentials, or SOPS.

For Forgejo, it uses an interactive personal-access-token flow rather than device OAuth. The token is stored imperatively in the invoking user's home directory.

Fit with this repository

Service credentials are already encrypted with SOPS and rendered to narrowly scoped runtime files. Moving those credentials into Nix's user-level access-tokens setting would be incorrect and would weaken the current separation of concerns.
The repository's private nixos-auto-update flake input uses git+ssh, so a Forgejo HTTPS access token does not simplify that fetch path.
Public GitHub inputs may eventually encounter anonymous API rate limits, but no current repository evidence establishes that as an operational problem. Installing another root input fleet-wide before that problem exists would add update and maintenance surface without improving current builds.
If a particular interactive user or CI runner does encounter GitHub rate limiting or needs a private HTTPS flake, upstream already supports an on-demand nix run github:numtide/nix-auth -- login ... workflow. That does not require repository integration.

Validation performed

nix flake check --no-build passed against the reviewed upstream commit.
The package built successfully.
A non-mutating dry run against git.nimmog.uk successfully selected the Forgejo provider and requested only read:repository and read:user; no authentication was performed and no token or configuration file was written.

Decision

Do not add nix-auth to the flake or system packages, and do not attempt to combine it with SOPS. Keep it as an on-demand troubleshooting/tooling option.

Revisit if a specific host repeatedly hits GitHub API limits or a private flake is deliberately moved from SSH to HTTPS. Any future adoption should be scoped to the affected user or runner and should document token rotation separately from SOPS-managed service credentials.

## Evaluation conclusion: useful on demand, but do not integrate declaratively Reviewed upstream `numtide/nix-auth` at commit [`d43fad3`](https://github.com/numtide/nix-auth/tree/d43fad3e926493db26d915aba7c0284606e07782). ### What it actually provides `nix-auth` manages the Nix client's `access-tokens` setting for authenticated flake and fetcher access. It writes a mode-0600 [`~/.config/nix/access-tokens.conf`](https://github.com/numtide/nix-auth/blob/d43fad3e926493db26d915aba7c0284606e07782/README.md#how-it-works) and adds an include to the user's `nix.conf`. It is not a general service-authentication framework and does not replace application secrets, environment files, OIDC client credentials, or SOPS. For Forgejo, it uses an interactive personal-access-token flow rather than device OAuth. The token is stored imperatively in the invoking user's home directory. ### Fit with this repository - Service credentials are already encrypted with SOPS and rendered to narrowly scoped runtime files. Moving those credentials into Nix's user-level `access-tokens` setting would be incorrect and would weaken the current separation of concerns. - The repository's private `nixos-auto-update` flake input uses `git+ssh`, so a Forgejo HTTPS access token does not simplify that fetch path. - Public GitHub inputs may eventually encounter anonymous API rate limits, but no current repository evidence establishes that as an operational problem. Installing another root input fleet-wide before that problem exists would add update and maintenance surface without improving current builds. - If a particular interactive user or CI runner does encounter GitHub rate limiting or needs a private HTTPS flake, upstream already supports an on-demand `nix run github:numtide/nix-auth -- login ...` workflow. That does not require repository integration. ### Validation performed - `nix flake check --no-build` passed against the reviewed upstream commit. - The package built successfully. - A non-mutating dry run against `git.nimmog.uk` successfully selected the Forgejo provider and requested only `read:repository` and `read:user`; no authentication was performed and no token or configuration file was written. ### Decision Do not add `nix-auth` to the flake or system packages, and do not attempt to combine it with SOPS. Keep it as an on-demand troubleshooting/tooling option. Revisit if a specific host repeatedly hits GitHub API limits or a private flake is deliberately moved from SSH to HTTPS. Any future adoption should be scoped to the affected user or runner and should document token rotation separately from SOPS-managed service credentials.

nimmo closed this issue

2026-08-09 23:03:53 +01:00