64 lines
2.0 KiB
Markdown
64 lines
2.0 KiB
Markdown
# secrets/
|
|
|
|
SOPS-encrypted YAML files. The plaintext lives only in transit and in the
|
|
operator's head — committed files are always ciphertext.
|
|
|
|
## Conventions
|
|
|
|
- One file per logical grouping (e.g. `gitea-tokens.yaml`, `webhook-hmacs.yaml`,
|
|
`api-keys.yaml`).
|
|
- Recipients are declared in `../.sops.yaml` by path-regex, not per-file.
|
|
- The plaintext schema inside each file is free-form YAML; the consumer code
|
|
decides what it expects (e.g. `gitea-tokens.yaml` contains
|
|
`{"<host>": "ghp_xxx"}`).
|
|
|
|
## How to add a secret
|
|
|
|
```bash
|
|
# 1. Decide which clients should be able to decrypt it; edit ../.sops.yaml to
|
|
# list their age public keys for the new path_regex.
|
|
# 2. Create the plaintext, encrypt in place:
|
|
sops -e --in-place secrets/my-thing.yaml
|
|
# 3. Commit + push. The 5-min sync propagates to every recipient.
|
|
```
|
|
|
|
## How to consume a secret
|
|
|
|
```bash
|
|
# On any client that's a recipient:
|
|
homelab secret my-thing # prints plaintext
|
|
# Or programmatically:
|
|
sops -d /opt/homelab-context/secrets/my-thing.yaml
|
|
```
|
|
|
|
The `mcp` tool `list_my_secrets(caller_pubkey)` returns the names of secrets
|
|
the caller can decrypt. The MCP server never reads plaintext — decryption
|
|
stays client-side.
|
|
|
|
## Granting / revoking access
|
|
|
|
To grant a new recipient: edit `../.sops.yaml` to add their age pubkey, then
|
|
re-key every affected file:
|
|
|
|
```bash
|
|
sops updatekeys -y secrets/my-thing.yaml
|
|
```
|
|
|
|
To revoke: remove the recipient from `../.sops.yaml` and `sops updatekeys` —
|
|
but remember this only protects future ciphertext. Past plaintext the client
|
|
already decrypted is gone from your control. Rotate the underlying credential
|
|
if compromise is suspected.
|
|
|
|
`homelab client remove <name>` does the recipient removal + `updatekeys` for
|
|
you, and prints the rotation checklist as a follow-up.
|
|
|
|
## hello.yaml — bootstrap decrypt test
|
|
|
|
`secrets/hello.yaml` is encrypted to every enrolled client. Used by Phase 3a
|
|
verification to confirm the end-to-end decrypt path works on a freshly-
|
|
bootstrapped machine. Content is intentionally trivial:
|
|
|
|
```yaml
|
|
greeting: hello from the homelab
|
|
```
|