# 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}`).

## 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
```

## 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/

## 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.