# nix-cache-login

CLI tool for authenticating with a Nix binary cache via Keycloak OIDC. Obtains
access tokens and writes them to a netrc file so Nix can use them
transparently.

Canonical Repository: https://guardianproject.dev/ops/nix-cache-login

## Overview

Nix binary caches can be protected with OIDC-based authentication backed by
Keycloak. This tool handles the token lifecycle:

- Workstation users: authenticate via browser (Authorization Code + PKCE), get a 1-hour access token and a 24-hour refresh token
- Servers: authenticate headlessly via client credentials, get a short-lived access token refreshed on a timer

The access token is written to a netrc file, which Nix reads automatically when
fetching from the cache.

## Installation

```bash
# run directly
nix run guardianproject.dev/ops/nix-cache-login  
```

Or add as a flake input:

```nix
{
  inputs.nix-cache-login.url = "git+https://guardianproject.dev/ops/nix-cache-login";

  # use the package
  # nix-cache-login.packages.${system}.default
}
```

## Configuration

Create `$XDG_CONFIG_HOME/nix-cache-login/config.toml` (default `~/.config/nix-cache-login/config.toml`):

**Workstation:**
```toml
issuer = "https://id.guardianproject.info/realms/gp"
client_id = "nix-cache"
cache_host = "cache.guardianproject.dev"
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
```

**Server (service account):**
```toml
issuer = "https://id.guardianproject.info/realms/gp"
client_id = "nix-cache-server"
client_secret_file = "/run/secrets/nix-cache-client-secret"
cache_host = "cache.guardianproject.dev"
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
```

Path values support environment variable expansion (`$VAR` and `${VAR}`).

`netrc_path` is the path this tool writes tokens to.

Configure Nix to read that same path.

This supports both cppnix and detsysnix. The latter has [special
requirements][additionalnetrcsources] around `netrc` files, so set
`additionalNetrcSources` to include the configured `netrc_path`.

## Usage

```bash
nix-cache-login login            # authenticate via browser (default command)
nix-cache-login refresh          # refresh token without browser
nix-cache-login service-account  # headless client credentials flow
nix-cache-login status           # show token expiry info
nix-cache-login logout           # revoke tokens and clean up
```

Config path resolution order:

1. `--config`
2. `$NIX_CACHE_LOGIN_CONFIG`
3. `$XDG_CONFIG_HOME/nix-cache-login/config.toml`
4. `/etc/nix-cache-login/config.toml` (server fallback)

The NixOS server module exports `NIX_CACHE_LOGIN_CONFIG` and installs
`/etc/nix-cache-login/config.toml` from `services.nix-cache-login-server.configFile`.

## Module Integration

The Home Manager and NixOS modules in this repo install the package and refresh
services.

Nix and detsysnix daemon configuration stays outside these modules.

Set your daemon to read the `netrc_path` configured in `config.toml`.

## Maintenance

This tool is actively maintained by [Guardian Project](https://guardianproject.info).

### Issues

For bug reports and feature requests, please use the [Issues][issues] page.

### Security

For security-related issues, please contact us through our [security policy][sec].

[issues]: https://guardianproject.dev/ops/nix-cache-login/issues
[sec]: https://guardianproject.info/contact/
[additionalnetrcsources]: https://docs.determinate.systems/determinate-nix/#additionalnetrcsources

## License

Copyright (c) 2026 Abel Luck <abel@guardianproject.info>

This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.