Secrets

Stackpanel stores secrets in SOPS-encrypted YAML files under .stack/secrets/. The active model is SOPS-first:

• recipients are declared in Nix
• recipient groups are reusable named sets of recipients
• creation rules render directly into .stack/secrets/.sops.yaml
• app and variable values can point directly at secrets with ref+sops://...#/KEY

Getting Started

1. Enter the devshell with nix develop --impure.
2. Add your public key in stackpanel.secrets.recipients or stackpanel.users.
3. Configure stackpanel.secrets.sops-age-keys.sources so sops-age-keys can return a private key whose public key matches one configured recipient.
4. Add at least one stackpanel.secrets.creation-rules entry, or configure one in Studio under Variables → SOPS.
5. Store secret values in .stack/secrets/**/*.sops.yaml and reference them directly with ref+sops://...#/KEY.

How It Works

• Stackpanel generates a local AGE key for you on shell entry.
• Recipient public keys live in Nix config.
• sops-age-keys can resolve keys from ordered sources such as user paths, repo paths, macOS Keychain, 1Password refs, vals refs, and scripts.
• .stack/secrets/.sops.yaml is generated from recipients, recipient groups, and creation rules.
• SOPS encrypts matching files directly to the resolved recipients from the first matching rule, with a catch-all fallback when needed.
• When recipient keys change, an existing recipient runs .stack/secrets/bin/rekey.sh and commits the updated SOPS files.

Common Commands

Team Workflow

1. A teammate adds their public key in Nix config.
2. They commit the updated config and generated .stack/secrets/.sops.yaml.
3. Someone who already has access runs .stack/secrets/bin/rekey.sh.
4. The updated .sops.yaml and SOPS files are committed and shared.

Sections