# Secret Management

This repo uses SOPS with age for secrets that must be stored in Git. The
encrypted files can be committed, while the age private key stays on the Debian
homelab server or in a deliberately scoped CI secret.

## First-Time Setup

Restore/install the tools through the Debian host bootstrap:

```bash
ansible-playbook -K -i bootstrap/host/inventory.ini bootstrap/host/playbook.yml
```

Then initialize the age identity and local SOPS config on the Debian host:

```bash
./jeannie secrets-init
```

`secrets-init` installs missing `age`/`sops` packages when needed, generates
`~/.config/sops/age/keys.txt` if it does not already exist, and writes
`.sops.yaml` from `.sops.yaml.example` with the public recipient from that key.
The public recipient in `.sops.yaml` is not sensitive and should be committed.
The private identity in `~/.config/sops/age/keys.txt` must stay outside Git.

Validate the current repo secret state:

```bash
./jeannie secrets-check
```

## File Naming

Use one of these suffixes for encrypted YAML:

```text
*.secret.yaml
*.enc.yaml
```

For Kubernetes `Secret` manifests, keep sensitive values under `stringData` or
`data` so the example `encrypted_regex` encrypts the right fields without
obscuring resource metadata needed by Argo CD and review diffs.

## Editing

Create or edit an encrypted file:

```bash
SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt sops apps/example/app.secret.yaml
```

Check the decrypted render locally without writing it to the repo:

```bash
SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt sops -d apps/example/app.secret.yaml
```

Decrypted scratch files are intentionally ignored by `.gitignore`; encrypted
files are not.

## Git Rules

- Commit `.sops.yaml` after `./jeannie secrets-init` creates it.
- Commit only encrypted files matching `*.secret.yaml`, `*.enc.yaml`,
  `*.secret.json`, or `*.enc.json`.
- Do not commit `~/.config/sops/age/keys.txt`, `.age-key.txt`, `sops-age.key`,
  or decrypted scratch files such as `*.dec.yaml`, `*.decrypted.yaml`, and
  `*.plain.yaml`.
- Run `./jeannie secrets-check` before pushing a change that adds or edits
  encrypted secrets.