scadaproj/docs/plans/2026-07-19-secrets-interactive-cli-design.md

Design: secret interactive console (ZB.MOM.WW.Secrets CLI, 0.3.0)

Date: 2026-07-19 · Status: Approved · Execution: git worktree worktree-secrets-interactive-cli (another agent is active on main)

1. Purpose & posture

Extend the existing headless secret CLI (src/ZB.MOM.WW.Secrets.Cli) with a menu-driven Spectre.Console TUI for two operator jobs:

1. Deployment setup — seed a deployment's secrets before first startup (apps fail closed when a ${secret:...} reference is missing).
2. Lockout recovery — diagnose and fix wrong/lost-KEK and missing-secret states.

No authentication: the tool only runs locally with direct file/DB access — the same trust model as the existing headless verbs. All existing verbs stay byte-identical for scripts.

2. Entry point

secret with no args in a real terminal (!Console.IsInputRedirected && !Console.IsOutputRedirected) launches the TUI. Redirected I/O keeps today's usage-and-exit-2 behavior, so nothing scriptable changes. All other Program.cs paths are untouched.

3. Target selection & sessions

First screen picks a store target:

• Recent targets — persisted to ~/.zb-secrets/recent-targets.json (names and paths only; NEVER key material).
• Browse to an app's appsettings.json.
• Manual entry — db path + KEK source.

TargetConfigReader loads the app's real config the way the app would (appsettings.json + optional appsettings.<Environment>.json overlay + environment variables; section Secrets by default, overridable) and binds SecretsOptions (+ SqlServerSecretsOptions when present) — operating on exactly what the app will read at startup, so a fix cannot land in the wrong store.

SecretsSessionFactory constructs the stack directly — SecretsSqliteConnectionFactory / SqlServerSecretStore, MasterKeyProviderFactory, AesGcmEnvelopeCipher, the matching migrator — no per-target DI host. If the configured KEK env var isn't set in the CLI's shell (common: it exists only in the service's environment), the session opens degraded: metadata ops work; decrypt/seal ops prompt for the key via masked input or file path, held in memory only.

Dependency changes to ZB.MOM.WW.Secrets.Cli: add Spectre.Console and a project reference to ZB.MOM.WW.Secrets.Replicator.SqlServer (to open SQL-hub stores such as ScadaBridge central).

4. Menu actions

Action	Behavior
List / set-rotate / get / delete	Thin TUI wrappers over the same core seams SecretCommands uses. Masked value entry; tables for listings; get reveals once after confirm, never cached.
Reference audit + seeding	Scan the target app's fully-composed config for ${secret:NAME} tokens (same regex as SecretReferenceExpander); report each OK / missing / tombstoned / undecryptable; walk through seeding every non-OK one with masked prompts. This is the deployment-setup flow.
KEK doctor	Verify the session KEK against the store: per-row KekId match + actual DEK-unwrap probe; report row classes (OK / wrong-KEK / corrupt). Guided remedies: rewrap-all (old key from env/file/masked paste, reusing KekRotationService) or re-set affected secrets when the old KEK is truly lost. This is the lockout flow.
Bundle export / import	Export rows as ciphertext-only JSON (name, metadata, wrapped DEK, kekId, ciphertext — safe at rest, useless without the KEK). Import into another store; conflicts resolved by core SecretLastWriterWins with per-row override prompt. Cross-KEK import offers inline rewrap given the source KEK.
Switch target / quit	Rebuild session for a new target; quit exits 0.

5. Structure

New Interactive/ layer inside ZB.MOM.WW.Secrets.Cli:

• InteractiveShell — menu loop; the ONLY class that touches IAnsiConsole.
• UI-free services: TargetConfigReader, SecretsSessionFactory, ReferenceAuditor, KekDoctor, SecretBundleCodec + import/export service, RecentTargetsStore.

Services never touch the console; the shell never touches the store directly. Secret values are never written to recents, bundles (plaintext), logs, or screen except the explicit reveal action.

6. Error handling

Every action catches SecretDecryptionException / ArgumentException / IO / SQL failures and renders a red panel with a remedy hint (usually "run KEK doctor"), returning to the menu — the shell never crashes out mid-recovery. Ctrl-C at a prompt cancels back to the menu; at the menu it exits 0.

7. Testing

• Unit tests for all services in tests/ZB.MOM.WW.Secrets.Tests/Cli/ (temp SQLite stores, fake KEK providers — same style as existing tests).
• Shell flows scripted via Spectre.Console.Testing's TestConsole: menu navigation, masked entry, degraded-KEK path, audit→seed walk-through, doctor→rewrap.
• Pin test: non-TTY no-args still prints usage / exit 2.
• Suite stays 0-warning (TreatWarningsAsErrors posture of the repo).

8. Versioning & execution

• Directory.Build.props version bumps 0.2.3 → 0.3.0 (new feature; CLI is unpacked but the 5 packages ship together — publish decision deferred to rollout).
• Implemented on worktree branch worktree-secrets-interactive-cli; merge to main when the full suite is green.

Alternatives considered

• Separate ZB.MOM.WW.Secrets.Cli.Interactive library — cleaner layering if another front-end ever hosts the flows; rejected as YAGNI for a one-exe operator tool.
• Prompts inside SecretCommands — least code but couples UI into the tested headless layer and breaks its TextWriter-only contract; rejected.
• REPL shell / wizards-only UX — rejected in favor of discoverable menus (operators under lockout stress shouldn't need to remember verbs).
• Own profiles file as source of truth — rejected: can drift from what the app actually reads; parsing the app's own config is the honest source.