skills: agent-provisioning - codified identity stand-up workflow

Policy rulings (#942): unique passwords, Cloudron-only SSO accounts, no reachableceo credentials, TOTP seeds MUST be captured to the vault. Cloudron admin API wrapper, cookie-jar OIDC login, RFC-6238-tested TOTP helper, per-system SSO/API references, incident log.
2026-09-08 04:07:14 -05:00
parent a4a54f553e
commit bde7845490
8 changed files with 503 additions and 0 deletions
@@ -0,0 +1,48 @@
+# TSGCOO vault (`sm` CLI) — entry points and gotchas
+
+The KNELSecretsManager vault (Vaultwarden at pwvault.turnsys.com, account
+coo@turnsys.com) is the ONLY credential store. Full doctrine:
+OAM workspace memory `tsgcoo-account-ops` + `creds-migration`; tool
+reference: KNEL workspace memory `knelsecretsmanager-reference`.
+
+## Invocation
+
+```bash
+# from the reachableceo account (this workstation):
+sudo -u TSGCOO /data2/TSGCOO/.local/bin/sm <cmd>   # TSGCOO crossover
+# from inside the TSGCOO account:
+/data2/TSGCOO/.local/bin/sm <cmd>
+# raw container form:
+docker exec -i ukrrs-secretsmgr-cli smcli <cmd>
+```
+
+Commands: `status`, `list [pattern]`, `get <name> [--field KEY]`,
+`env <name>`, `set`, `setfield <name> <key> <value>`, `rm`, `folders`.
+Item naming: `creds/<name>` for services; `<login> <System>` for identity
+login items; `creds/<login>` for the new per-identity schema.
+
+## Gotchas that have actually bitten
+
+1. `sm env` / `sm get` in scripts: append `</dev/null` — docker exec -i eats
+   stdin and hangs the call inside loops/pipelines.
+2. `--field URI` NEVER matches — URIs are login URIs, not custom fields. Use
+   `sm env` (synthetic URI/USERNAME/PASSWORD) or `--field password`.
+3. `sm env` PASSWORD is the login password, which for token-style items IS
+   the token (e.g. `creds/cloudron`). Always confirm what a field holds
+   before assuming password-vs-token semantics.
+4. zsh does not word-split `$VAR` — `SM="sudo -u ... sm"; $SM get` fails with
+   "no such file". Use a function: `smget() { sudo -u TSGCOO /data2/TSGCOO/.local/bin/sm "$@" </dev/null; }`.
+5. Mask secrets in ALL visible output: pipe through
+   `sed -E 's/((password|token|secret|key|seed|totp)[^:=]*[=:]).*/\1 [MASKED]/Ig'`
+   and jq projections of field NAMES/lengths, never values.
+6. `smcli` self-heals expired sessions (v13: refresh-token rotation +
+   fallback relogin using injected env). If `smcli status` is fine but
+   fetches hang (`/api/sync` context deadline), the vault server is sick —
+   stop retrying, check the shared box (incident-log.md), escalate.
+7. Never print a filled password form's DOM snapshot (browser work) — the
+   ARIA tree includes field values; one coo password hit a transcript this
+   way (2026-09-07).
+
+---
+
+**Records:** Redmine #942 — https://projects.knownelement.com/issues/942 · Discourse docs home: https://community.turnsys.com (skill topic pending admin-key provisioning, tracked on #942)