diff --git a/README.md b/README.md index 7fd69ff..9dfaf95 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,43 @@ -# KNELSecretsManager (ARCHIVED — moved to KNEL/secrets) +# KNELSecretsManager -This body of work moved to **[KNEL/secrets](https://git.knownelement.com/KNEL/secrets)** per the 2026-09-03 repo split ([#769](https://projects.knownelement.com/issues/769)); content was ported as `legacy-knelsecretsmanager/` (secret-scanned clean — placeholders only). +Fleet secrets management: a **pure-Go Bitwarden/Vaultwarden CLI** (`smcli`) +in a house container, backed by the self-hosted TSGCOO vault. No upstream +Rust `bw` binary, no Node runtime, no `.creds` text files — those patterns +are retired (ADR-003; founder rulings #829/#832). -This repo is historical. New secrets-management work happens in KNEL/secrets (#770). +- Docs: [docs/architecture.md](docs/architecture.md) (diagrams, crypto, rotation program) +- KNELBMS integration: [docs/integration-knelbms.md](docs/integration-knelbms.md) +- Redmine: https://projects.knownelement.com/issues/832 (build) / #829 (migration+rotation) + +## Quick start (lane) + +```bash +# TSGCOO account (COO-area chats; docker group, no sudo) +/data2/TSGCOO/.local/bin/sm status + +# reachableceo crossover +~/projects/KNEL/OAM/.tools/sm env creds/cloudron # export URI/USERNAME/PASSWORD + keys +~/projects/KNEL/OAM/.tools/sm get creds/librenms --field password +~/projects/KNEL/OAM/.tools/sm setfield creds/ # rotation updates +``` + +## Layout + +| Path | What | +|---|---| +| `cli/cmd/smcli/` | the Go CLI (crypto, API, commands) | +| `docker/Dockerfile.cli` | golang build → alpine runtime (CA certs, non-root) | +| `docker/compose.yaml` | always-hot service `ukrrs-secretsmgr-cli` (digest-pinned) | +| `archive/rust-bw-era/` | retired upstream-binary wrapper scripts | +| `docs/ADR-003-GoCLI.md` | decision record | + +## Rules (binding) + +- Secrets live ONLY in the TSGCOO Bitwarden vault, accessed ONLY via this + CLI (container `ukrrs-secretsmgr-cli`, shims above). No textfile creds, + no upstream bw CLI — anywhere. +- All work product is authored by Cloudron account identities + (ic-builder / ic-reviewer / manager-tsg / vptechops); the founder + account (ReachableCEO) reviews and approves. +- Production-affecting rotations follow the CR gating + cross-linking + house rules (GLPI CR deep link in the PR/ticket; evidence on solve). diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..47ccf34 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,99 @@ +# KNELSecretsManager — Architecture + +Status: production. Ruling chain: ADR-002 (containerized CLI) → ADR-003 +(pure-Go `smcli`, Rust `bw` retired). Founder directives: #829/#832. + +## Components + +```mermaid +flowchart LR + subgraph vault["TSGCOO Bitwarden vault (self-hosted)"] + V["pwvault.turnsys.com\n(Vaultwarden API)"] + end + subgraph workstation["Workstation (dev-only host)"] + C["ukrrs-secretsmgr-cli\n(compose, always-hot)\npure-Go smcli v9+"] + S1["/data2/TSGCOO/.local/bin/sm\n(TSGCOO account entry)"] + S2[".tools/sm\n(reachableceo crossover)"] + W1["mred-vp → Redmine identity"] + W2["ci-green.sh → Gitea admin"] + W3["redmine-sweep.sh"] + end + subgraph fleet["Fleet consumers (rotation waves)"] + B["KNELBMS: on-box secrets.yaml\n(deploy webhook, gitea_auth_header,\nkuma_push_url, pve_*_api_token)"] + K["pfv-k8s secrets\n(glpi-creds for kuma-glpi-bridge,\nflux PAT — wave 4)"] + R["Nightly timers\n(pve-config-backup, glpi-reconcile)"] + end + S1 --> C + S2 --> C + W1 --> C + W2 --> C + W3 --> C + C -->|HTTPS: prelogin/login(TOTP)/sync/CRUD| V + C -.->|reads after rotation| B + C -.-> K + C -.-> R +``` + +## Auth + unlock sequence + +```mermaid +sequenceDiagram + participant U as Operator/Consumer + participant S as smcli (container) + participant V as pwvault.turnsys.com + U->>S: smcli login (SM_EMAIL, SM_PASSWORD, SM_TOTP_SECRET) + S->>V: POST /api/accounts/prelogin {email} + V-->>S: kdf type + iterations (PBKDF2 600k / Argon2id) + S->>S: masterKey = KDF(password, email); authHash = PBKDF2(masterKey, password, 1) + S->>V: POST /identity/connect/token (password grant, device fields) + V-->>S: 400 Two factor required (provider 0) + S->>S: TOTP code from SM_TOTP_SECRET (RFC 6238) + S->>V: token request + twoFactorToken + V-->>S: access_token (+Key, PrivateKey) + S->>V: GET /api/sync + V-->>S: profile.key (enc, type 2) + S->>S: stretchedKey = HKDF(masterKey,"enc"/"mac"); userSymKey = decrypt(profile.key) + S->>S: state.json 0600 (master/stretched/user keys + token) +``` + +Item payloads are type-2 encStrings (AES-256-CBC + HMAC-SHA256, 32B enc + +32B mac keys) encrypted/decrypted locally; the vault never sees plaintext. + +## Consumer pattern + +```bash +# env-style consumers (export lines; URI/USERNAME/PASSWORD + original keys) +eval "$(docker exec -i ukrrs-secretsmgr-cli smcli env creds/)" +# surgical single-field rotation update +docker exec -i ukrrs-secretsmgr-cli smcli setfield creds/ +``` + +Items are LOGIN type: username + password/API-key as first-class fields, +service URLs as URIs, remaining keys as named custom fields (hidden where +secret). Original env key names are preserved as the custom-field names. + +## Rotation program (#829) + +All pre-migration material is presumed BURNED (plaintext on disk + LLM +exposure). Waves, each item = rotate at source → `setfield` in vault → +rewire consumers to `sm env` → validate (guard rule: never write the vault +from a failed rotation): + +1. Tooling tokens (librenms*, wazuh ✓, grafana*, gvm, technitium, phpipam, + rancher-sectest, beszel, pihole, PMG pair, PBS tokens) +2. Agent identities (gitea agent-stack, vptechops gitea/redmine) +3. Platform (cloudron API token, kuma, discourse) +4. Deep-wired (flux PAT + gitea runner + HA on-box secrets.yaml + k8s + secrets + PVE upsagent tokens) + +\* item-specific notes: librenms — token-mint API route absent on this +install (UI/DB path); grafana — SSO-managed, local admin parked (instance +password policy blocks CLI reset). + +## KNELBMS integration + +See [integration-knelbms.md](integration-knelbms.md). Short form: the BMS +deploy pipeline (KNELBMS repo, packages/deploy_pipeline.yaml) consumes +`gitea_auth_header` + `kuma_push_url` + `pve_*_api_token` from on-box +`/config/secrets.yaml`; the vault is the source of record and rotations +push to the box through the CR-gated provisioning path. diff --git a/docs/integration-knelbms.md b/docs/integration-knelbms.md new file mode 100644 index 0000000..d36b040 --- /dev/null +++ b/docs/integration-knelbms.md @@ -0,0 +1,50 @@ +# KNELBMS integration — secrets flow + +Repo: https://git.knownelement.com/KNEL/KNELBMS (PhysicalPlant lane; +Home Assistant BMS on VM 100 @ pfv-tsys1, dev→release deploy by git). + +## What the BMS consumes + +| On-box secret (HA `secrets.yaml`) | Vault item + field | Provenance | +|---|---|---| +| `gitea_auth_header` | `creds/pfv-bms-deploy` → GITEA_DEPLOY_WATCH_TOKEN | release-branch sha-watch REST sensor | +| `deploy_webhook_id` / `pfv_relay_webhook_id` | `creds/pfv-bms-deploy` | fast-path deploy webhook | +| `kuma_push_url` | `creds/pfv-bms-beta` sibling — dead-man monitor `pfv-bms-ha-heartbeat-2026-09` (push token) | rotated 2026-09-06 under CR 21 | +| `pve_tsys{1,3,4,5,6,7}_api_token` | `creds/pve-upsagent` (per-node fields) | `upsagent@pam!ups`, PVEAdmin-on-/vms, privsep=0 | +| `doorman_*`, `pfvbms_smb_*`, beta HA creds | respective `creds/*` items | as rotated | + +## Provisioning + rotation flow + +```mermaid +sequenceDiagram + participant R as Rotation run (#829 wave) + participant V as TSGCOO vault + participant B as pfv-bms on-box secrets.yaml + participant H as Home Assistant + R->>V: new value (sm setfield creds/ ) + R->>B: CR-gated provisioning (ssh -p 22222, CR + ha core check) + R->>H: ha core restart (Kuma window; dead-man covers the gap) + H-->>R: post-deploy validation (entity/heartbeat checks) + R->>V: rotation evidence on #829 +``` + +Rules that bind this flow (house rules + #811): + +- pfv-bms prod changes need a GLPI CR **and** a Kuma maintenance window + when a restart is involved; the deploy path itself stays + dev → CI → release PR (founder merges). +- HA runtime template contexts cannot read secrets — the on-box + `shell_command` entries reference `!secret` names only (see KNELBMS + PR #6 / CR 21 for the dead-man fix that taught us this). +- The dead-man heartbeat (`pfv-bms-ha-heartbeat-2026-09`, Kuma id 291) + is the canary for provisioning mistakes: if the on-box secret and the + vault disagree, the push fails and the monitor pages. + +## Current integration state (2026-09-06) + +- On-box `secrets.yaml` provisioned manually under CR 21 (PVE tokens + + rotated Kuma push URL); git-side KNELBMS matches for the `!secret` + keys it owns (PR #6 on dev, awaiting founder release merge). +- Automated push-from-vault (rotation waves writing the box directly via + the AWX ssh path) is **planned, not built** — wave 4. Until then the + table above is the manual runbook, executed under CR.