keybox (kbx)

A secrets, keys, and vars management CLI. Wraps age and sops with a clean
workflow for local encryption, declarative generators, and a central key registry.

Inspired by clan.lol vars — the var directory layout is
intentionally compatible with clan's vars/ structure.

---

Concepts

Concept	Description
Key	A named age public key (age1...). Logical names (e.g. alice, server-prod) map to pubkeys in config.toml.
Rule	Maps a file-path regex to a set of named keys. Determines which keys can decrypt which files.
Var	A generated value — either plaintext (public) or encrypted (secret; sops or age per its rule's store). Stored in .keybox/vars/.
Generator	A shell script that produces vars from interactive prompts. Defined in .keybox/generators/*.toml.
Store	Encryption backend: sops (default) or age. sops is required for NixOS/sops-nix integration.

---

Data Model

your-project/
├── .keybox/
│   ├── config.toml          ← keys and rules
│   ├── vars/                ← generated values (clan vars layout)
│   │   ├── per-machine/
│   │   │   └── <machine>/
│   │   │       └── <generator>/
│   │   │           └── <file>/
│   │   │               ├── value        ← plaintext (public var)
│   │   │               └── secret       ← encrypted (secret var)
│   │   ├── per-user/
│   │   │   └── <user>/
│   │   │       └── <generator>/
│   │   │           └── <file>/{value,secret}
│   │   └── shared/
│   │       └── <generator>/
│   │           └── <file>/{value,secret}
│   └── generators/
│       └── <name>.toml      ← generator definitions
└── secrets/                 ← sops-encrypted files (managed by rules)

---

Setup

# Install (from source)
cargo install --path .

# Or via nix (flake)
nix run github:youruser/keybox

# Initialize in your project
cd your-project
kbx init

This creates:

.keybox/
  config.toml      (version = 1, empty keys/rules)
  vars/
  generators/

Add .keybox/vars/**/secret to .gitignore if you don't want to commit
encrypted secrets. Public vars (the value files) are safe to commit.

---

Docs

Topic
CLI Reference	All commands — init, migrate, status/check, key, rule, var, gen, edit/encrypt/decrypt, ref, login/push/secret, otp, seal/unseal
Generators	Generator format, sandbox, runtime_inputs, dependencies, examples
Generator Examples	PKI chain, SSH CA, WireGuard, database credentials, backup keys (with NixOS snippets)
Security & Secret Management	Threat model, what's safe to commit, key custody, rotation/revocation runbook, recovery
Use Cases	Managing sops secrets, password hashes, LUKS keys, sops-nix, OTP sharing
Server	kbx-server setup, NixOS module, API endpoints, auth
Clan Vars Compatibility	Layout compatibility, differences, .sops.yaml generation, migration