Files
scadaproj/docs/plans/2026-11-12-scada-ui-consistency/Secrets.md
T

23 KiB
Raw Blame History

Shared Secrets UI Consistency Implementation Plan

For Codex: REQUIRED SUB-SKILL: Use executeplan to implement this plan task-by-task.

Goal: Isolate secret-editor targets, make privileged administration accessible and recoverable, and ship one consistent UI to every sister host.

Architecture: Fix target/draft identity before visual changes, then adopt the reviewed Theme API and shared interaction recipes in the existing Razor library. Preserve metadata-only lists, separate manage/reveal authorization, fail-closed reveal auditing, committed mutation semantics, tombstones and cache invalidation. Domain services remain unchanged; generic modal behavior is only considered for extraction after two real consumer pilots.

Tech Stack: .NET 10 Razor Class Library, ZB.MOM.WW.Theme, existing ISecretStore/ISecretCipher/IAuditWriter, xUnit 2.9.3, bUnit 2.7.2 after GB (BunitContext / Render), native DOM dialog/focus APIs when required.


Required testing prerequisite

Complete bUnit standardization and close GB before any task in this chapter, including local fixes and candidate UI pilots. All bUnit snippets below use the post-GB BunitContext / Render / AddAuthorization API; their inherited helpers must be migrated in GB. Preserve framework HtmlRenderer methods and xUnit runner APIs where used. Non-bUnit runtimes retain their existing harnesses, but their UI work also waits for the family gate. Old package pins are discovery baselines, not targets for this chapter.

Scope, baseline and dependencies

  • Cwd for all commands: /Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets; all task files below are relative to that cwd.
  • Inputs: /Users/dohertj2/Desktop/scadaproj/impeccable/Secrets.md, shared recommendations, master plan and Theme G1 gate. Review source unchanged between review baseline and current umbrella HEAD d93ca7b; record actual execution HEAD.
  • Current library source version: Directory.Build.props → 0.6.6; Theme central pin Directory.Packages.props → 0.2.0. Consumers may resolve higher Theme versions; use restored graphs as truth.
  • THEME_VERSION: actual compatible release after G1. SECRETS_UI_VERSION: actual package release selected for these changes after its own compatibility review. Neither string is a version to commit literally. Do not assume 0.6.0 or republish an existing immutable package.
  • SEC-01 target isolation may proceed after GB closes while Theme G1 is pending. All visual/API adoption tasks depend on G1. Host adoption depends on both chosen packages.
  • G1 API: additive TechField.For, HintId, ErrorId; callers provide matching control id, aria-describedby, aria-invalid. BusyText/aria-busy are shared; caller live outcome regions must never contain plaintext. Theme status text uses dedicated ink tokens; information-state blue is independent of product accent.
  • Complete the required bUnit 2.7.2 migration in GB first. Subsequent tasks preserve that validated test stack; backend/storage redesign, real-secret fixtures and real reveals are outside these UI tasks.

Run baseline from the stated cwd:

dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj

Expected PASS; record restore warnings/count. Feed/SDK or existing parser/test-stack failures are baseline blockers, to record in GB; the prescribed 2.7.2 migration and compatibility verification must close before these tasks. New tests below extend the named existing classes and retain their existing usings/helpers. Test data is synthetic.

SEC-01 · Isolate Add/Rotate targets and pending editor lifetimes

Covers: review SEC-06; highest priority before aesthetic work. Depends: baseline only.

Modify: src/ZB.MOM.WW.Secrets.Ui/Components/SecretEditor.razor; src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor; tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretEditorTests.cs; tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs; tests/ZB.MOM.WW.Secrets.Ui.Tests/Fakes/RecordingSecretStore.cs for optional delayed-call hooks.

  1. Add this test inside SecretEditorTests, reusing RegisterServices():
[Fact]
public void ChangingRotateTarget_DoesNotReuseAnotherSecretsDraft()
{
    var (store, _, cipher) = RegisterServices();
    var a = new SecretName("app/a");
    var b = new SecretName("app/b");
    store.Seed(cipher.Encrypt(a, "old-a", SecretContentType.Text) with { Description = "A" });
    store.Seed(cipher.Encrypt(b, "old-b", SecretContentType.Json) with { Description = "B" });
    var auth = this.AddAuthorization();
    auth.SetAuthorized("reviewer");
    auth.SetPolicies(SecretsAuthorization.ManagePolicy);
    var cut = Render<SecretEditor>(p => p.Add(x => x.ExistingName, a));
    cut.Find("[data-testid=secret-value]").Change("draft-for-a");
    cut.Render(p => p.Add(x => x.ExistingName, b));
    cut.WaitForAssertion(() =>
    {
        Assert.Equal("B", cut.Find("[data-testid=secret-description]").GetAttribute("value"));
        Assert.Equal("", cut.Find("[data-testid=secret-value]").GetAttribute("value") ?? "");
    });
}
  1. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~ChangingRotateTarget_DoesNotReuseAnotherSecretsDraft; expected FAIL because _metadataLoaded and _value survive target changes.
  2. Track editor identity explicitly (Add vs Rotate + exact secret name). On identity change, increment a generation, cancel the previous metadata read and reset name/description/type/value/error/restore-confirmation/loading flags before loading the new metadata. Apply read results only if generation and identity still match. Capture immutable target identity when submitting. Preserve failed-save drafts only for that identity. The list also keys editor instances by mode/name and tracks its editor generation so a superseded completion cannot close a newer editor. Disable Add/Rotate/Cancel target switching while a committed mutation outcome is pending; explain pending state instead of claiming cancellation rolled back a write.
  3. Add tests for Rotate→Add; same-target rerender preserving unsaved text; delayed A metadata completing after B; parent row A→B switching; cancellation during pending write; and stale OnSaved not closing a new editor. Add optional GetOverride/UpsertOverride delegates to the recording fake for TaskCompletionSource-controlled delay rather than sleeping. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter "FullyQualifiedName~SecretEditor|FullyQualifiedName~SecretsList|FullyQualifiedName~AuditFailureAfterCommit"; expected PASS and existing audit/cache semantics unchanged.
  4. Stage only the five named files; commit fix(secrets-ui): isolate drafts and pending operations by editor target.

SEC-02 · Adopt the shared Theme field and state API

Covers: SEC-01; DS-01/02/04/06. Depends: SEC-01 + G1.

Modify: Directory.Packages.props; src/ZB.MOM.WW.Secrets.Ui/Components/SecretEditor.razor; tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretEditorTests.cs.

  1. Add a rendered association regression in SecretEditorTests:
[Fact]
public void EveryEditorControl_HasAnAssociatedLabel()
{
    RegisterServices();
    var cut = Render<SecretEditor>();
    foreach (var control in cut.FindAll("input:not([type=hidden]),select"))
    {
        var id = control.Id;
        Assert.False(string.IsNullOrWhiteSpace(id));
        Assert.NotNull(cut.Find($"label[for='{id}']"));
    }
}
  1. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~EveryEditorControl_HasAnAssociatedLabel; expected FAIL on absent IDs/associations.
  2. Set the actual Theme pin to THEME_VERSION. Give each editor instance stable unique control/hint/error IDs, pass For, HintId, ErrorId, and wire child attributes. Include required/name-format hints and field-local errors. New secret value stays a password input with autocomplete="new-password"; never prefill stored plaintext. Use BusyText and aria-busy; error/status text uses new semantic ink classes, not signal colors.
  3. Add two-instance unique-ID and invalid-name aria-invalid/description tests; run the SecretEditorTests filter then the whole UI suite. Expected PASS. Browser-verify label activation, correct names and field errors with keyboard/screen reader; never announce new values. Use computed contrast and visual inspection for palette changes, not CSS-string tests.
  4. Stage the three named files; commit fix(secrets-ui): adopt shared field associations and readable states.

SEC-03 · Make deletion keyboard accessible inside real hosts

Covers: SEC-02; DS-04/05. Depends: G1 dialog recipe + SEC-01.

Modify: src/ZB.MOM.WW.Secrets.Ui/Components/ConfirmDeleteModal.razor; src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor; tests/ZB.MOM.WW.Secrets.Ui.Tests/ConfirmDeleteModalTests.cs. Create if recipe requires DOM enhancement: src/ZB.MOM.WW.Secrets.Ui/wwwroot/js/secrets-dialog.js.

  1. Add a regression inside ConfirmDeleteModalTests (same registration/auth setup as existing first test):
[Fact]
public void DeleteDialog_HasANameLinkedToTheExactTarget()
{
    Services.AddSingleton<ISecretStore>(new RecordingSecretStore());
    Services.AddSingleton<IAuditWriter>(new CapturingAuditWriter());
    var cut = Render<ConfirmDeleteModal>(p => p
        .Add(x => x.Visible, true).Add(x => x.Name, new SecretName("app/a")));
    var dialog = cut.Find("[role=dialog]");
    var titleId = dialog.GetAttribute("aria-labelledby");
    Assert.False(string.IsNullOrWhiteSpace(titleId));
    Assert.Contains("app/a", cut.Find($"[id='{titleId}']").TextContent);
    Assert.Equal("true", dialog.GetAttribute("aria-modal"));
}
  1. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~DeleteDialog_HasANameLinkedToTheExactTarget; expected FAIL on missing association. If DOM module initialization is introduced, add an exact bUnit module stub in test setup before rerunning; do not weaken the existing strict assertion to allow arbitrary browser confirm/alert.
  2. Apply the shared confirmation recipe: unique heading/description association, initial Cancel focus, contained tab order, inert background, safe Escape, focus return to originating row. Retain .zb-secrets-* namespace to avoid the documented Bootstrap .modal{display:none} collision. Retain awaited busy operation and exact target; after deletion choose next logical row/heading if trigger vanished. DOM handler receives its actual event argument; never use window.event. Dispose event listeners and restore any prior inert state.
  3. Add cancel-does-not-delete, busy double activation, failed delete retains target and error, and next-focus-target selection tests in the named files. Run the ConfirmDeleteModalTests filter and whole UI suite; expected PASS. Browser-test actual focus/Escape/background isolation in two hosts including one Bootstrap host: bUnit markup cannot establish focus containment.
  4. Stage only named modified files plus the module if created; commit fix(secrets-ui): apply accessible confirmation lifecycle.

SEC-04 · Separate list loading, commit and refresh outcomes

Covers: SEC-03; DS-04/05. Depends: SEC-01.

Modify: src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor; tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs; tests/ZB.MOM.WW.Secrets.Ui.Tests/Fakes/RecordingSecretStore.cs.

  1. Extend the recording fake with optional ListFault and ListCalls; preserve normal behavior when unset. Add a list regression inside SecretsListTests:
[Fact]
public void InitialListFailure_IsRetryableAndIsNotAnEmptyInventory()
{
    var store = new RecordingSecretStore { ListFault = new IOException("synthetic outage") };
    Services.AddSingleton<ISecretStore>(store);
    Services.AddSingleton<ISecretCipher>(new FakeCipher());
    Services.AddSingleton<IAuditWriter>(new CapturingAuditWriter());
    var cut = Render<SecretsList>();
    cut.WaitForAssertion(() => Assert.NotNull(cut.Find("[data-testid=list-error]")));
    Assert.DoesNotContain("No secrets.", cut.Markup);
    store.ListFault = null;
    cut.Find("[data-testid=list-retry]").Click();
    cut.WaitForAssertion(() => Assert.Contains("No secrets.", cut.Markup));
}
  1. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~InitialListFailure_IsRetryableAndIsNotAnEmptyInventory; expected FAIL from unhandled initial list exception (after fake compiles).
  2. Catch list failures locally, preserve previous metadata if present, and show Retry with a polite status region. Keep initial loading distinct from empty. Track mutation committed separately from list refresh; show “Change saved; list refresh failed” if necessary. Retry refresh only; never replay upsert/delete to fix a read. Preserve generation ownership and CTS disposal from SEC-01.
  3. Add delayed initial load, metadata-only Retry, mutation-committed/reload-failed and disposed-load tests. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj; expected PASS, especially AuditFailureAfterCommitTests and reveal fail-closed tests.
  4. Stage the three named files; commit fix(secrets-ui): distinguish list recovery from committed mutations.

SEC-05 · Improve metadata scanning and row-action context

Covers: SEC-04; DS-01/05. Depends: G1 + SEC-01–04.

Modify: src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor; src/ZB.MOM.WW.Secrets.Ui/Components/RevealButton.razor; tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs.

  1. Add a behavior regression inside SecretsListTests, reusing RegisterStore/SecretOne/SecretTwo:
[Fact]
public void NameFilter_CanBeClearedWithoutHidingMetadataPermanently()
{
    RegisterStore(SecretOne, SecretTwo);
    var cut = Render<SecretsList>();
    cut.Find("input[data-testid=secret-filter]").Input("db/primary");
    Assert.Single(cut.FindAll("tbody tr[data-secret-row]"));
    cut.Find("[data-testid=clear-secret-filter]").Click();
    Assert.Equal(2, cut.FindAll("tbody tr[data-secret-row]").Count);
}
  1. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~NameFilter_CanBeClearedWithoutHidingMetadataPermanently; expected FAIL: no filter.
  2. Add a visibly labelled local name filter (metadata already loaded, no value access), clear action and zero-match state. Keep name/description/update time prominent. Move KEK/revision/type/by into native details or responsive secondary cells without deleting metadata. Name each action with its row target (“Rotate app/a”); use a real Actions header and proper row/header semantics. Preserve manage/reveal policies both in markup and handlers.
  3. Add no-match/clear, long-name and accessible action-context tests; run --filter FullyQualifiedName~SecretsListTests, expected PASS. Inspect 390px, 1440px, 200% zoom, keyboard, long unbroken names and multiple simultaneous rows. The document may not overflow; scoped table/payload scrolling is acceptable. Layout-only changes need visual checks, not tests counting CSS classes.
  4. Stage the three named files; commit feat(secrets-ui): add metadata filtering and clear row actions.

SEC-06 · Keep reveal outcomes discoverable without announcing plaintext

Covers: SEC-05; DS-04. Depends: SEC-05 + G1 busy/focus recipe.

Modify: src/ZB.MOM.WW.Secrets.Ui/Components/RevealButton.razor; tests/ZB.MOM.WW.Secrets.Ui.Tests/RevealButtonTests.cs; tests/ZB.MOM.WW.Secrets.Ui.Tests/RevealAuditFailureTests.cs.

  1. Extend RevealButtonTests with a regression using the same fake registrations as its existing reveal test: seed cipher.Encrypt(new SecretName("app/a"), "synthetic-value", SecretContentType.Text), authorize RevealPolicy, render Name app/a, click [data-testid=reveal-button]. Add these assertions:
cut.WaitForAssertion(() =>
{
    var status = cut.Find("[data-testid=reveal-status][role=status]");
    Assert.Contains("Value revealed", status.TextContent);
    Assert.DoesNotContain("synthetic-value", status.TextContent);
});
cut.Find("[data-testid=hide-button]").Click();
Assert.Empty(cut.FindAll("[data-testid=revealed-value]"));
  1. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~RevealButtonTests; expected FAIL in the new regression on absent outcome status.
  2. Keep a stable non-sensitive outcome region and a logically stable trigger/Hide focus path. Announce reveal success/failure only, never plaintext. Clear rendered value on Hide; preserve audit-before-disclosure and handler authorization. Do not add auto-hide without an explicit product policy: current review proposes evaluation, not a mandate. Document the chosen “visible until Hide/navigation” behavior in local help for this release.
  3. Run the named RevealButtonTests/RevealAuditFailureTests filters and entire UI suite; expected PASS. Browser-test keyboard reveal/error/hide with synthetic data. Inspect accessibility tree and audit payload to ensure plaintext occurs only in the intentional rendered value, never live status, labels, URL or event details. Use no real-secret screenshot.
  4. Stage the three named files; commit fix(secrets-ui): announce reveal outcomes without disclosing values.

SEC-07 · Package and host integration evidence

Covers: SEC-01–06, DS-06. Depends: all tasks + G1.

Modify at version-selection time: src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj, README.md; modify Directory.Build.props only if deliberately coordinating a complete dependency release. Create: docs/ui-consistency-validation.md.

  1. Run dotnet build src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj -c Release; expected zero new warnings.
  2. Run dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj -c Release; expected all tests pass, including authorization, audit-failure-after-commit and reveal-audit-failure suites. Record restored Theme/transitive dependencies.
  3. Exercise packaged UI in OtOpcUa's per-page-interactive wrapper and another Bootstrap/global-interactive host using synthetic values. Verify no duplicate /admin/secrets route, dead @onclick, missing scoped assets or Bootstrap modal collision. Verify manages-only/reveals-authorized/denied, empty/load/reload failure, target switches, long names, 390/1440px, zoom, reduced motion and actual modal focus. Cross-check shared recipes against the OtOpcUa dialog pilot before extracting generic code.
  4. Choose the smallest valid package release set. Prefer a UI-only project-level <Version> override in src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj, leaving the shared Directory.Build.props version and Abstractions unchanged. A global version bump would also change the UI's ProjectReference-derived Abstractions dependency; UI-only packing would then reference a possibly unpublished package. Verify the exact Abstractions version exists in the feed. If it does not, coordinate the minimal dependency package set explicitly; do not assume a global version number implies every package is available. Document the actual Theme lower bound and host adoption order.
  5. Commit the source/version changes before packing, recording a clean committed source identity. Run dotnet pack src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj -c Release -o artifacts/ui-consistency; expected a local new immutable SECRETS_UI_VERSION artifact. If a coordinated Abstractions package is required, also run dotnet pack src/ZB.MOM.WW.Secrets.Abstractions/ZB.MOM.WW.Secrets.Abstractions.csproj -c Release -o artifacts/ui-consistency. Inspect each .nuspec inside its .nupkg for actual ID/version/Theme/Abstractions dependencies; record SHA-256 and repository commit. Do not infer dependency versions from folder names.
  6. Verify an isolated restore before feed publication. Create a disposable /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj with Microsoft.NET.Sdk.Web, net10.0, and PackageReferences to the exact selected UI and Theme versions, plus a minimal Program.cs containing WebApplication.CreateBuilder(args).Build().Run(); with the ASP.NET builder using. Run dotnet restore /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj --packages /tmp/scada-ui-consistency-secrets-restore/packages --source /Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets/artifacts/ui-consistency --source ACTUAL_APPROVED_FEED_URL with the existing authenticated feed configuration; substitute the actual URL rather than commit that placeholder. Include every other approved configured package source needed by the dependency graph, including the approved public source when required: explicit --source flags override source selection. Keep the isolated package directory empty initially so success is not masked by a developer global package cache. Run dotnet build /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj --no-restore; expected restore/build success using the exact minimal package set, with no fallback to an unintended source build. Inspect obj/project.assets.json and record the resolved graph.
  7. After the master release gate and later explicit authorization, publish only the exact validated package set through the established package release process. Download those feed artifacts into a separate empty verification directory, compare SHA-256 to the validated local artifacts, and repeat isolated restore against the feed without the local package source. Consumer package-pin adoption remains blocked until this succeeds. No publication or deployment occurs while writing or reviewing this plan.
  8. Record validation, checksums, dependency graph, actual versions and screenshot links in the validation doc; finish Impeccable audit/polish. Stage only readme/validation updates and commit docs(secrets-ui): record package and host UI acceptance gates.

Complete finding coverage

Review finding Plan task Shared contract
SEC-06 target/draft leakage SEC-01, SEC-07 local state identity; independent of G1
SEC-01 unnamed fields SEC-02, SEC-07 DS-01/02/04/06
SEC-02 dialog name/focus SEC-03, SEC-07 DS-04/05
SEC-03 loading/refresh recovery SEC-04, SEC-07 DS-04/05
SEC-04 metadata/action context SEC-05, SEC-07 DS-01/05
SEC-05 reveal feedback SEC-06, SEC-07 DS-04

Rollout and rollback

This chapter prepares source, tests, package and host acceptance only. Consumers adopt SECRETS_UI_VERSION and THEME_VERSION through their own reviewed package pins after gates. Keep the previous immutable library/host artifacts and restored graphs. Roll back package/host assets together; do not undo tombstones, rotate credentials, replay mutations or change encryption/storage formats as a visual rollback. If target isolation is fixed independently, preserve that correction rather than reverting it with later aesthetic work. No data migration is planned.