Skip to content

Component: Smrt.Security

Canonical source: SmrtApps/src/Smrt.Security/README.md (mirrored below)

Smrt.Security

Overview & Responsibilities

  • Provides shared security helpers consumed by multiple SmrtHub components with no cross-assembly dependencies.
  • Current surface area is WindowsCredentialHelper, a thin wrapper over the Windows Credential Manager (Cred* APIs) for storing opaque secrets.
  • Follows guidance from README.Files/System/Policies/SmrtHub-Documentation-Policy-v1.0.README.md to keep XML documentation authoritative for IDE help and future doc generation.

Public surface

The primary public surface is the set of APIs listed under Key APIs below.

Key APIs

  • WindowsCredentialHelper.SaveCredential / UpdateCredential persist UTF-16 secrets against a target identifier.
  • WindowsCredentialHelper.GetCredential retrieves the previously stored secret for the same target, surfacing unexpected Win32 failures as InvalidOperationException while returning null when the credential is missing.
  • WindowsCredentialHelper.DeleteCredential removes credentials that are no longer required (silently ignores already-removed targets).
  • WindowsCredentialHelper.ListCredentials enumerates available credential targets for diagnostics and throws when the enumerator returns an unexpected Win32 error so the caller can capture it in logs/support bundles.

Cloud provider credential targets (vNext)

Cloud provider secrets are stored in Windows Credential Manager and must not be persisted to config/state/logs. Credential target naming is owned by Smrt.CloudProviders and follows the vNext spine spec in README.Files/SmrtHub-vNext-Architecture/Milestone-A-Spine-Spec.md.

Dependencies & Integrations

  • No third-party packages; uses Windows advapi32.dll P/Invoke bindings.
  • Consumers should continue to resolve configuration via Smrt.Config and log with SmrtHub.Logging as documented in README.Files/Reference-Guides/SmrtHub.Logging.README.md.
  • Secrets retrieved from this helper must never be written to logs; redaction policies in README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md apply.

Configuration & Log Paths

  • The helper itself is configuration-free. Calling applications manage settings under %AppData%/SmrtHub/Config/<slug> and logs under %AppData%/SmrtHub/Logs/<slug> per the Operational Data Policy.
  • Exceptions expose Win32 error codes to the caller; callers must capture these through SmrtHub.Logging (without secret values) for traceability.

Runtime Workflow

  1. Normalize the credential target name (for example smrt-hub/api-gateway).
  2. Call SaveCredential with a UTF-16 secret up to 512 bytes. Optional user name and comment metadata are supported.
  3. Fetch the secret when required via GetCredential; the helper returns null if the credential is missing.
  4. Remove credentials that are no longer valid using DeleteCredential so that stale data is not left in the credential vault.

Testing & Validation

  • Unit tests should focus on validating argument guards and error propagation (mock the Win32 calls or abstract via the partial class pattern).
  • Integration tests must run on Windows, create disposable targets, and delete credentials they create to avoid polluting developer machines.
  • Manual smoke testing is available via WindowsCredentialHelper.TestUtility (DEBUG-only) to verify local Credential Manager access after clearing %AppData%/SmrtHub secrets.

Support Bundle & Diagnostics Touchpoints

  • Failures surface as InvalidOperationException with the Win32 error; calling components should log the error and include results in support bundles generated via Smrt.SupportBundle.
  • When investigating issues, capture the component log plus the Support Bundle manifest hashes to confirm which credentials were queried.

Directory Map

  • SmrtHub.Security.WindowsCredentialHelper.cs — public API and P/Invoke bindings.
  • SmrtHub.Security.csproj — library configuration (compiled with XML documentation output).
  • bin/, obj/ — generated build output; cleansed by standard dotnet clean or repository build scripts.
  • README.Files/System/Policies/SmrtHub-Privacy-and-Security-Policy.README.md
  • README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md