summaryrefslogtreecommitdiff
path: root/secrets/README.md
diff options
context:
space:
mode:
authorIgor Soarez <igor@soarez.org>2026-11-18 14:02:09 +0000
committerIgor Soarez <igor@soarez.org>2026-11-18 14:02:09 +0000
commit8f818a64f2f0f3a833fc842d52a675358ec64c9c (patch)
treeeac13a48cada4595c9073d62060c1145189c6344 /secrets/README.md
parent6444d6a508cdfdcf52cc6c83bab1e29a7e2a2e10 (diff)
szecret: buckets beside the old store -- get/has/put/mv/rekey/list/check/enrol, admins from SZECRET_ADMINS_COMMAND; rotate retired (fleet hardening 12)
A bucket is a directory of secrets with one set of readers: its recipients file plus the admins, the full set recorded in .szecret by rekey. put refuses when the readers or admins drift from that set, or with no admins; a plain put of a new name goes to admin-only, one still in the old store is rewritten there. The old store keeps working throughout. link/claude.sh leaves out an MCP server whose secret is in a bucket this host doesn't read. Design: cloud-setup docs/proposal-secret-roles.md.
Diffstat (limited to 'secrets/README.md')
-rw-r--r--secrets/README.md78
1 files changed, 53 insertions, 25 deletions
diff --git a/secrets/README.md b/secrets/README.md
index 293b747..d4860eb 100644
--- a/secrets/README.md
+++ b/secrets/README.md
@@ -19,15 +19,49 @@ szecret list
| Command | Description |
|---------|-------------|
-| `get <name>` | Retrieve and decrypt a secret |
-| `put <name>` | Store a secret (reads from stdin) |
-| `list` | List all secrets in the store |
-| `ready` | Check if private key is configured |
-| `ensure` | Ensure private key is configured (interactive) |
-| `rotate` | Generate a new key and re-encrypt the global store |
-| `create-local <name> <dir>` | Create a localized secret store |
-| `put-local <file>` | Encrypt to a local store |
-| `get-local <file>` | Decrypt from a local store |
+| `get <name>`, `get <bucket>/<name>` | Decrypt a secret. A plain name searches every bucket and the old store |
+| `has <name>` | Succeed quietly if this machine can read it; decrypts nothing |
+| `put <bucket>/<name>` | Encrypt stdin to the bucket's readers and the admins |
+| `put <name>` | The same, in `admin-only` (a name still in the old store is rewritten there) |
+| `mv <name> <bucket>` | Move a secret to another bucket; never copies |
+| `rekey <bucket>` | Re-encrypt a bucket to its readers now; adding a reader needs a yes or `--add-ok` |
+| `list` | The secrets this machine reads (`--names`, `--all`) |
+| `check [--all]` | Check that the buckets this machine reads (or every bucket) are whole |
+| `enrol [--tpm\|--se]` | Make this machine's identity and print its public key |
+| `ready` | Check there is a store and an identity |
+| `ensure` | Ensure the old private key is configured (interactive) |
+| `create-local <name> <dir>` | Create a localized secret store (the old kind) |
+| `put-local <file>` | Encrypt to a local store or a repository bucket |
+| `get-local <file>` | Decrypt from a local store or a repository bucket |
+
+## Buckets
+
+A bucket is a directory of secrets that all have one set of readers, defined
+by its readers, not by a workload: a secret is in exactly one bucket, and when
+another host needs it, it moves to a bucket that has every reader who needs it.
+The design, and who reads which bucket, are cloud-setup's
+(`docs/proposal-secret-roles.md`, `szecret/hosts`); szecret knows no host.
+
+```
+buckets/<bucket>/
+ recipients # age public keys, one a line, a comment above each naming its reader
+ .szecret # kind=bucket, and the full set its files were last encrypted to
+ <name>.age
+```
+
+- **The admins**, printed by the command in `SZECRET_ADMINS_COMMAND`, are added
+ to every encryption. With none, nothing is encrypted.
+- **`put` refuses** when the recipients or the admins differ from the set in
+ `.szecret`, so a forgotten rekey can't leave a removed reader reading new
+ values. Only `rekey` writes that set.
+- **This machine's identity** is `SZECRET_IDENTITY`, or
+ `~/.local/share/szecret/identity`, made by `enrol` and never copied off; its
+ public key is in `identity.pub` beside it. Decrypting passes it and the old
+ key together while both are here.
+- **Names** are `[A-Za-z0-9][A-Za-z0-9._-]*`, buckets lowercase, and a name is
+ unique across every bucket and the old store.
+- age 1.3 or later is needed to encrypt (it encrypts to `age1tag1` hardware
+ keys itself).
## Local Stores
@@ -64,16 +98,18 @@ The commands automatically read the store name from the `.szecret` metadata file
### Where the store lives
-These scripts carry no secrets. The global store is a directory of `.age`
-files plus `id.pub`, the public key they are encrypted to, kept in a checkout
-of its own. szecret looks for it in this order:
+These scripts carry no secrets. The buckets are found at `$SZECRET_BUCKETS`,
+else `~/.local/share/szecret/buckets`. The old global store, which empties as
+its secrets move into buckets, is a directory of `.age` files plus `id.pub`,
+the public key they are encrypted to, kept in a checkout of its own. szecret
+looks for it in this order:
1. `$SZECRET_STORE` and `$SZECRET_PUBLIC_KEY`, if set.
2. `~/.local/share/szecret/store` and `~/.local/share/szecret/id.pub`, beside
the private keys. Normally symlinks into the checkout that holds the store.
-With neither, every command stops with setup instructions, and `ready`
-fails silently.
+With no buckets and no old store, every command but `enrol` stops with setup
+instructions, and `ready` fails silently.
### Initial Setup
@@ -93,17 +129,6 @@ mv private "${HOME}/.local/share/szecret/${pubkey}"
szecret ensure
```
-### Rotating the Global Key
-
-```bash
-# Re-encrypt all secrets with a new age key
-szecret rotate
-```
-
-This updates `id.pub` and every file in the store. When complete, commit
-those changes in the checkout that holds the store, and update the private key
-backup in 1Password.
-
## Migration Guide
### Migrating Local Stores (pre-2026)
@@ -146,6 +171,9 @@ For testing or custom setups, these environment variables override default paths
| `SZECRET_PUBLIC_KEY` | Public key path | `~/.local/share/szecret/id.pub` |
| `SZECRET_PRIVATE_KEY` | Single private key file (full override) | (none) |
| `SZECRET_PRIVATE_KEY_DIR` | Directory containing private keys (named by their public key) | `~/.local/share/szecret` |
+| `SZECRET_BUCKETS` | Buckets directory | `~/.local/share/szecret/buckets` |
+| `SZECRET_IDENTITY` | This machine's identity (its public key in `<path>.pub`) | `~/.local/share/szecret/identity` |
+| `SZECRET_ADMINS_COMMAND` | Prints the admins' public keys, one a line | (none: nothing is encrypted to a bucket) |
* Private keys are stored in `~/.local/share/szecret/` (or `$SZECRET_PRIVATE_KEY_DIR`), with each file named after its public key (e.g. `age1...`).
* `id.pub` indicates which public key is current.