archive: prune stale dirs, move actual content to docs/

Deleted stale (Python-era artifacts, superseded by DB):
- archive/oikos-cards/ (46 files, predecessor to DB entity graph)
- archive/ledger/ (5-line JSONL fragment, superseded by DB audit log)

Moved to docs/ (actual, current architecture docs):
- docs/infrastructure/ — 12 infrastructure docs (network, DNS, mesh,
  SSH, ingress, media-permissions, backups, homelab-context, auto-deploy,
  VPS-hardening, monitoring, check-lifecycle)
- docs/secrets/ — secrets README and rotation runbook
- docs/GLOSSARY.md — 28-term homelab glossary

Added STALE.md markers to hermes-plans/ and secrets-issuance/.
Added MOVED.md pointers in archive sources.
Updated docs/index.md to include new paths.
This commit is contained in:
2026-08-16 11:26:27 +02:00
parent 104593de0c
commit f127925d5a
67 changed files with 1774 additions and 875 deletions

63
docs/secrets/README.md Normal file
View File

@@ -0,0 +1,63 @@
# 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
```