docs: production architecture (mermaid), KNELBMS integration, README
Component + sequence + rotation-flow diagrams; consumer pattern; KNELBMS secrets-flow table + provisioning sequence; README to prod standard. Ticket: https://projects.knownelement.com/issues/832
This commit is contained in:
@@ -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/<name>)"
|
||||
# surgical single-field rotation update
|
||||
docker exec -i ukrrs-secretsmgr-cli smcli setfield creds/<name> <KEY> <newvalue>
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -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/<item> <KEY>)
|
||||
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.
|
||||
Reference in New Issue
Block a user