Secrets (sops-nix)

All network secrets (passwords, keys, tokens) live encrypted in a single file, managed by sops-nix 🡕. It is versioned in git in encrypted form; only key holders can decrypt it.

# usr/secrets/secrets.yaml (encrypted at rest)
default-password: ...
default-password-hash: ...
user:
  alice:
    password-hash: ...

The two keys

Decryption relies on two age 🡕 keys:

Key	Where	Role
Admin key	~/.config/sops/age/keys.txt	Edit secrets from the admin workstation
Infra key	/etc/sops/age/infra.key	Decrypt on each host at deploy time

• The admin key derives from your SSH key (~/.ssh/id_ed25519, via ssh-to-age).
• The infra key is generated once, then pushed to each host.
• Recipients are listed in usr/secrets/.sops.yaml (admin + infra).

Never commit a private key

The infra key lives outside the repo (/etc/sops/age/). The usr/secrets/ .gitignore already excludes *.key. Never copy it into the repo.

Initialize (admin workstation)

A single command prepares all the secrets infrastructure:

just configure-admin-host

It is idempotent and creates, if needed:

• the deployer SSH key (nix);
• the admin key (from the SSH key) and the infra key (age-keygen);
• the .sops.yaml file (recipients);
• a default password (just passwd-default);
• the Harmonia binary cache signing key.

Setup walkthrough

This step is part of the initial installation.

Manage passwords

Command	Effect
just passwd-default	(Re)sets the default password for accounts
just passwd <user>	Sets a user’s password
just passwd-restic	Generates backup secrets (per host / zone)
just sops	Edits the secrets file manually ($EDITOR)

After a change, deploy to propagate it:

just passwd alice
just apply @user-alice     # deploys the new hash

Hashes, never plaintext

Account passwords are stored hashed (password-hash). The plaintext is never deployed to hosts.

Push the key to a host

A host can only decrypt secrets with the infra key. It is placed automatically by just configure <host>, or manually:

just push-key <host>      # copies /etc/sops/age/infra.key to the host

Rarely needed

push-key is already built into just install (and just configure): in practice, you should not need to call it yourself.

Rotating the infra key

Rotation replaces the infra key across the entire fleet, in three verified steps:

Finalize only when the entire fleet is updated

finalize removes the old key. If a host hasn’t yet received the new one (rotate push-keys + just apply), it becomes impossible to decrypt, and thus inaccessible to deployment. Only run finalize after confirming that all hosts are using the new key.

1. Introduce the new key

   just rotate init        # new key + re-encryption (old + new)

2. Distribute to all hosts

   just rotate push-keys   # each host receives both keys
   just apply '*'

3. Finalize

   just rotate finalize    # discards the old key (after verification)
   just apply '*'

Mandatory order

The presence of /etc/sops/age/infra.key.old indicates a rotation in progress. Always finish with finalize: until then, hosts carry both keys.