lmxopcua/docs/plans/2026-06-18-adminui-cert-actions-design.md

AdminUI Certificate Store Actions — Design

Date: 2026-06-18 Status: Approved Backlog item: AdminUI Certificates page actions (reconciled ranked-OPEN list)

Goal

Turn the read-only /certificates AdminUI page into an operator surface that can trust, untrust, and delete peer certificates in the OPC UA server's PKI directory stores. Changes are honored live by the running server's certificate validator — no restart.

Background — current state

src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Certificates.razor (@page "/certificates", [Authorize], @rendermode InteractiveServer) reads four PKI directory stores directly from the filesystem in OnInitialized() and renders a table per store (subject / issuer / thumbprint / validity). It is display-only — zero action buttons, no backend service.

The four stores live under {OpcUa:PkiStoreRoot} (default pki), each with a certs/ subdir holding .der/.cer/.crt files:

Store label	Subdir	Actionable?
Own	own/certs	no (read-only)
Trusted peers	trusted/certs	yes
Trusted issuers	issuer/certs	no (read-only)
Rejected	rejected/certs	yes

The running server (OpcUaApplicationHost.BuildConfigurationAsync) points its SecurityConfiguration trust lists (TrustedPeerCertificates, RejectedCertificateStore, …) at these same on-disk paths. The SDK's DirectoryStore re-enumerates certs/ on each validation, so a file moved into trusted/certs is trusted live, and one removed is no longer trusted — no process restart required.

Action set (approved)

Symmetric trust/untrust + delete:

• Rejected rows: [Trust] (→ trusted) and [Delete].
• Trusted rows: [Untrust] (→ rejected) and [Delete].
• Own / Issuer rows: unchanged (read-only).

Upload-to-trust is explicitly deferred (would add file-upload plumbing + an upload approval gate; the primary operator workflow — approve a peer that already tried to connect and landed in rejected — does not need it).

Architecture

Why an in-process service called directly (not a minimal-API endpoint)

A Blazor Server component cannot reliably dial its own HTTP endpoint server-side behind Traefik (durable lesson: project_blazor_server_self_hubconnection). The page already reads the stores via direct in-process filesystem access in OnInitialized; the write actions follow the same seam — the component calls an injected CertificateStoreManager directly, server-side, within the authenticated circuit. No HttpClient self-dial, no new endpoint.

Why pure filesystem (not the OPC UA SDK store API)

A directory-store cert is just a .der/.cer/.crt file in {store}/certs/. Trust = move the file rejected/certs → trusted/certs; delete = remove it. The filesystem approach:

• adds no new dependency (the page already uses BCL X509CertificateLoader);
• is identical to the existing read path, so behavior is predictable;
• is trivially unit-testable on a temp directory;
• finds the file by enumerate-and-match-thumbprint — never by building a path from caller input — so there is no path-injection surface;
• is honored live because the SDK DirectoryStore re-enumerates certs/.

The SDK store API would add an async-store dependency for no behavioral gain on Directory stores.

Components

1. CertificateStoreManager (NEW)

src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Certificates/CertificateStoreManager.cs

public sealed record CertActionResult(bool Success, string? Error)
{
    public static CertActionResult Ok() => new(true, null);
    public static CertActionResult Fail(string error) => new(false, error);
}

public sealed class CertificateStoreManager
{
    private readonly string _pkiRoot;
    public CertificateStoreManager(IConfiguration config)
        => _pkiRoot = config.GetValue<string?>("OpcUa:PkiStoreRoot") ?? "pki";

    // test seam — explicit root
    internal CertificateStoreManager(string pkiRoot) => _pkiRoot = pkiRoot;

    public CertActionResult Trust(string thumbprint)   => Move("rejected", "trusted", thumbprint);
    public CertActionResult Untrust(string thumbprint) => Move("trusted", "rejected", thumbprint);
    public CertActionResult Delete(string store, string thumbprint) { … }
    private CertActionResult Move(string fromSub, string toSub, string thumbprint) { … }
}

• Operations are synchronous filesystem moves/deletes (fast, local). Returning CertActionResult keeps the UI exception-free.
• Delete(store, …) accepts only "trusted" or "rejected" (else Fail("unknown store")).
• Thumbprint is validated as hex of length 40 (SHA-1) or 64 (SHA-256) before use — a cheap guard; path safety comes from enumerate-and-match, not from validation.
• Move: validate thumbprint → enumerate {root}/{fromSub}/certs/*.{der,cer,crt}, load each, match .Thumbprint (case-insensitive); not found → Fail("certificate not found in {fromSub}"). Ensure {root}/{toSub}/certs exists; File.Move(src, dest) preserving the SDK filename, with a thumbprint suffix on name collision. If a cert with the same thumbprint already exists in the destination, the source is removed and the op is idempotent success.
• All IOException/UnauthorizedAccessException caught → Fail(ex.Message).

2. Certificates.razor (MODIFY)

• Tag each StoreView with a CertStoreKind (Own/Trusted/Issuer/Rejected) so the table knows which actions to render.
• Refactor OnInitialized → a reusable LoadAll() (re-run after each action).
• Add an Actions column rendered only for Trusted/Rejected, wrapped in <AuthorizeView Policy="FleetAdmin"> (Administrator role — the most-privileged existing policy, matching the ScriptAnalysis endpoints). Buttons set a _pending action record (kind, thumbprint, subject, verb).
• Inline Blazor confirmation — a banner "Confirm {verb} of {subject}? [Confirm] [Cancel]". No window.confirm (a JS modal dialog would block browser-automation live-verify and is disallowed by the harness).
• On Confirm: call the injected CertificateStoreManager, set a status banner (green success / red error), LoadAll(), clear _pending.

3. DI registration (MODIFY)

AddAdminUI(IServiceCollection) in EndpointRouteBuilderExtensions.cs: services.AddSingleton<Certificates.CertificateStoreManager>(); (stateless bar config → singleton).

Authorization

The page stays [Authorize] for viewing. The action buttons and handler are gated by <AuthorizeView Policy="FleetAdmin"> (= RequireRole("Administrator")). On the docker-dev rig (DisableLogin=true) the auto-admin satisfies the policy, so the buttons render and the actions are live-provable.

Data flow

operator clicks [Trust] on a rejected cert
  → component sets _pending=(Rejected, thumbprint, subject, "trust")
  → operator clicks [Confirm]
  → component (server circuit) calls CertificateStoreManager.Trust(thumbprint)
  → File.Move  rejected/certs/<f>.der → trusted/certs/<f>.der
  → live OPC UA CertificateValidator now enumerates the cert under trusted
  → component LoadAll() → cert now shows under "Trusted peers", gone from "Rejected"

Error handling

Condition	Result
invalid/missing thumbprint	Fail → red banner, no change
cert not in source store (concurrent admin already moved it)	Fail("not found")
dest already has the thumbprint	source removed, idempotent success
Delete with store ∉ {trusted, rejected}	Fail("unknown store")
IOException / access denied	caught → Fail(message)

Testing

xUnit + Shouldly in tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Certificates/, driving CertificateStoreManager against a temp PkiStoreRoot seeded with ephemeral self-signed DER certs (generated in-test via CertificateRequest/X509Certificate2, written to rejected/certs):

• Trust moves rejected → trusted (file gone from source, present in dest).
• Untrust moves trusted → rejected.
• Delete("rejected", …) / Delete("trusted", …) removes the file.
• unknown thumbprint → Fail, no change.
• path-traversal thumbprint ("../../x") → rejected by hex validation, nothing touched.
• Delete("own", …) (disallowed store) → Fail("unknown store").
• idempotent re-trust (thumbprint already in trusted) → Success, source removed.

No bUnit — the Razor changes are proven only by live /run.

Live-verify (/run)

docker-dev rig (login disabled → auto-admin). Seed a DER into a central node's rejected/certs/, open http://localhost:9200/certificates, click [Trust] → [Confirm], verify the cert appears under Trusted peers and is gone from Rejected; click [Delete] on a cert, verify removal.

Rig caveat (durable): :9200 is Traefik-round-robined across central-1 and central-2, and each node has its own on-disk PKI dir. Pin the verify to a single node — seed the rejected cert into one container and drive that same container — so the read and the write line up. (docker exec into the chosen central container to seed + confirm the file move on disk.)

Constraints honored

No EF migration, no Commons/proto/wire change, no bUnit. Stage by explicit path (never git add .); never stage the never-stage files. Finish = merge to master

• push.

Touched code

• NEW src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Certificates/CertificateStoreManager.cs
• MODIFY src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Certificates.razor
• MODIFY src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/EndpointRouteBuilderExtensions.cs (DI)
• NEW tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Certificates/CertificateStoreManagerTests.cs
• (optional) one-line note in docs/security.md cert-store section