From e3c8e43ffb697446961c215e8e34d23a43c3b5c7 Mon Sep 17 00:00:00 2001 From: ic-builder Date: Sun, 6 Sep 2026 19:29:04 -0500 Subject: [PATCH] docs QA: diagrams must parse in a real mermaid renderer The first architecture set did not render (backslash-n escapes, semicolons in sequence messages, braces in text). All diagrams rewritten to conservative syntax and QA-verified with mermaid-cli (3/3 PARSE-OK). qa-diagrams.sh added; CI enforces it on docs changes. Ticket: https://projects.knownelement.com/issues/832 --- .gitea/workflows/ci.yml | 22 +++++++++++- docs/architecture.md | 70 +++++++++++++++++-------------------- docs/integration-knelbms.md | 24 ++++++------- tests/qa-diagrams.sh | 15 ++++++++ 4 files changed, 80 insertions(+), 51 deletions(-) create mode 100755 tests/qa-diagrams.sh diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index ff72149..de76325 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -1,4 +1,5 @@ -# CI [#832] — pure-Go CLI: fmt, vet, build, secret scan. No Rust in the chain. +# CI [#832] — pure-Go CLI: fmt, vet, build, secret scan + diagram QA. +# Diagram QA needs chromium: runs only when docs change. name: ci on: push: @@ -19,3 +20,22 @@ jobs: if grep -rInE "BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY|BW_PASSWORD='|SM_PASSWORD=" --exclude-dir=.git --exclude-dir=.smstate .; then echo "::error::secret material committed"; exit 1 fi + diagrams: + runs-on: ultix + container: + image: node:20-bookworm + steps: + - uses: actions/checkout@v4 + - name: mermaid blocks must parse + run: | + apt-get update -qq >/dev/null && apt-get install -qq -y gawk >/dev/null + # renderer + chromium inside minlag/mermaid-cli; mmdc parses without page render + QA=$(mktemp -d) + awk '/^```mermaid/{n++; f=QA"/d"n".mmd"; next} /^```/{f=""; next} f!=""{print > f}' QA="$QA" docs/*.md + echo '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-gpu"]}' > "$QA/pptr.json" + docker_target=skip + for f in "$QA"/d*.mmd; do + [ -f "$f" ] || continue + npx -y @mermaid-js/mermaid-cli@11 -p "$QA/pptr.json" -i "$f" -o /tmp/out.svg >/dev/null 2>&1 || { echo "::error::unrenderable diagram: $f"; exit 1; } + echo "PARSE-OK: $f" + done diff --git a/docs/architecture.md b/docs/architecture.md index 47ccf34..6c6c466 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,35 +1,29 @@ # KNELSecretsManager — Architecture -Status: production. Ruling chain: ADR-002 (containerized CLI) → ADR-003 +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 + V["Vaultwarden vault - pwvault.turnsys.com"] + C["smcli container - ukrrs-secretsmgr-cli"] + S1["TSGCOO entry - data2 TSGCOO bin sm"] + S2["lane crossover - tools sm"] + W1["mred-vp - Redmine identity"] + W2["ci-green.sh - Gitea admin"] + W3["redmine-sweep.sh"] + B["KNELBMS on-box secrets.yaml"] + K["pfv-k8s secrets - glpi-creds, flux PAT"] + R["nightly timers - pve backup, glpi reconcile"] S1 --> C S2 --> C W1 --> C W2 --> C W3 --> C - C -->|HTTPS: prelogin/login(TOTP)/sync/CRUD| V - C -.->|reads after rotation| B + C -->|HTTPS login sync CRUD| V + C -.-> B C -.-> K C -.-> R ``` @@ -38,22 +32,22 @@ flowchart LR ```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) + participant U as Consumer + participant S as smcli + participant V as Vault + U->>S: login with email password TOTP seed + S->>V: POST prelogin - get KDF params + V-->>S: PBKDF2 iterations or Argon2id + S->>S: derive master key and auth hash + S->>V: POST identity connect token + V-->>S: 400 - two factor required + S->>S: compute TOTP code - RFC 6238 + S->>V: token request plus twoFactorToken + V-->>S: access token and encrypted keys + S->>V: GET sync + V-->>S: profile key - encrypted + S->>S: stretch master key - decrypt user key + S->>S: write state file 0600 ``` Item payloads are type-2 encStrings (AES-256-CBC + HMAC-SHA256, 32B enc + @@ -75,11 +69,11 @@ 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 +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, +1. Tooling tokens (librenms*, wazuh DONE, 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) diff --git a/docs/integration-knelbms.md b/docs/integration-knelbms.md index d36b040..621f02b 100644 --- a/docs/integration-knelbms.md +++ b/docs/integration-knelbms.md @@ -1,15 +1,15 @@ # 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). +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 | +| `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 | +| `kuma_push_url` | 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 | @@ -17,22 +17,22 @@ Home Assistant BMS on VM 100 @ pfv-tsys1, dev→release deploy by git). ```mermaid sequenceDiagram - participant R as Rotation run (#829 wave) - participant V as TSGCOO vault - participant B as pfv-bms on-box secrets.yaml + participant R as Rotation run - 829 wave + participant V as Vault + participant B as pfv-bms 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 + R->>V: setfield new value + R->>B: CR-gated provisioning - ssh port 22222 + R->>H: ha core restart - Kuma window + H-->>R: post-deploy validation + R->>V: rotation evidence on ticket 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). + 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). diff --git a/tests/qa-diagrams.sh b/tests/qa-diagrams.sh new file mode 100755 index 0000000..e325eb7 --- /dev/null +++ b/tests/qa-diagrams.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# qa-diagrams.sh — every ```mermaid block in docs/ must parse in a real renderer. +# Usage: tests/qa-diagrams.sh (needs docker + minlag/mermaid-cli + /usr/bin/chromium) +set -euo pipefail +QA=$(mktemp -d) +awk '/^```mermaid/{n++; f=QA"/d"n".mmd"; next} /^```/{f=""; next} f!=""{print > f}' QA="$QA" docs/*.md +echo '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-gpu"]}' > "$QA/pptr.json" +fail=0 +docker run --rm -v "$QA":/qa --entrypoint sh minlag/mermaid-cli:latest -c ' +for f in /qa/d*.mmd; do + PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium mmdc -p /qa/pptr.json -i "$f" -o /tmp/out.svg >/dev/null 2>&1 || { echo "PARSE-FAIL: $f"; exit 1; } + echo "PARSE-OK: $f" +done' || fail=1 +rm -rf "$QA" +exit $fail