# Secrets workflow (sops + age)

## Files
- `creds/age-key.txt`: age private key (keep out of git; store in a password manager). Public key is in the header.
- `creds/secrets.enc.env`: encrypted dotenv managed by sops/age (committable).
- `creds/secrets.env`: decrypted dotenv (git-ignored) produced when loading secrets; not committed.
- Legacy plaintext secrets moved to `creds/deprecated/` for reference.
- `creds/n8n-billing.key`: API key for the billing verification endpoint (git-ignored). Can also be provided via `N8N_BILLING_API_KEY`.

## Editing secrets
```bash
# Ensure sops+age binaries are available
sops creds/secrets.enc.env
```
Sops will decrypt, open in $EDITOR, and re-encrypt on save. The age recipient is configured in `.sops.yaml`.

## Loading secrets locally
```bash
source scripts/load-secrets.sh
```
This decrypts `creds/secrets.enc.env` to `creds/secrets.env` if needed (requires sops) and exports all variables.

## Adding developers
- Share `creds/age-key.txt` securely (password manager). They need the age secret key to decrypt.
- No change to `.sops.yaml` is needed unless you rotate keys.

## Deploys/CI
- `deploy/deploy.sh` sources `scripts/load-secrets.sh`, so providing `creds/secrets.enc.env` + age key is enough for secret env injection.

## Rotating keys
- Generate a new age key: `age-keygen -o creds/age-key.txt` (keep old backup if you need to reencrypt).
- Update `.sops.yaml` recipient to the new public key.
- Re-encrypt: `SOPS_AGE_KEY_FILE=creds/age-key.txt sops --encrypt --in-place creds/secrets.enc.env`.

## n8n billing API key
- The billing assistant verification endpoint (`/api/integrations/billing/verify`) requires an API key.
- Store it in `creds/n8n-billing.key` (git-ignored) or export `N8N_BILLING_API_KEY` via `creds/secrets.env`.
- Rotate by replacing the file/env value and restarting the app/n8n caller with the new key.

## Per-user age keys
- Keys live under `creds/age/<user>.key` (git-ignored) and carry a public key in the header.
- Helper: `./scripts/manage-age-key.sh add alice` generates a key and appends the recipient to `.sops.yaml`.
- Remove: `./scripts/manage-age-key.sh remove alice` deletes the key file and strips the recipient (re-encrypt afterwards).
- List: `./scripts/manage-age-key.sh list`.
- After adding/removing recipients, re-encrypt secrets: `sops --encrypt --in-place creds/secrets.enc.env`.

Share each user’s private key securely (password manager). Multiple recipients in `.sops.yaml` allow any listed user to decrypt.