KNELSecretsManager/docs/architecture.md

KNELSecretsManager — Architecture

Status: production. Ruling chain: ADR-002 (containerized CLI) → ADR-003 (pure-Go smcli, Rust bw retired). Founder directives: #829/#832.

Components

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

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

# 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. 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.