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:JMARyA/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.

---

Nix

The flake exposes separate CLI and server packages, so each command runs the
intended binary:

nix run github:JMARyA/keybox                 # kbx CLI
nix run github:JMARyA/keybox#kbx-server      # ciphertext-sync server
nix develop github:JMARyA/keybox             # Rust, age, sops, and bwrap on Linux

kbx is wrapped with age, sops, and (on Linux) bwrap, so encryption and
generator sandboxing work without separately installing those tools. See the
Server guide for the NixOS module and server setup.

---

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