string Code { get; }
Source
Gets the stable machine-readable diagnostic code.
LocalSecrets
PlatformAppSurfaceLocalSecretStore
SourceLocalSecrets store that delegates to the current operating system's user secret facility when available.
Remarks
macOS uses Security.framework Keychain generic passwords, Windows uses current-user Credential Manager generic credentials, Linux uses Secret Service through secret-tool, and unsupported sessions return display-safe diagnostics.
InMemoryAppSurfaceLocalSecretStore
SourceIn-memory LocalSecrets store intended for tests and controlled local examples.
Remarks
This store is not durable and is not a production or development secret store. It exists as a package-local test seam so apps can verify LocalSecrets provider behavior without touching the platform credential store.
AppSurfaceLocalSecretDiagnostic
SourceDescribes a display-safe local secret diagnostic.
Remarks
Diagnostics are safe to render in command output, audit reports, and exception messages. They must never carry raw secret values. Use ToTerminalDiagnostic when the diagnostic should stop lower-priority configuration provider resolution.
ToTerminalDiagnostic
ConfigProviderTerminalDiagnostic ToTerminalDiagnostic()
Source
Converts this local secret diagnostic into a Config terminal diagnostic.
Returns
A terminal diagnostic safe for runtime configuration resolution errors.
ToDisplayString
string ToDisplayString()
Source
Formats this diagnostic for display without exposing secret values.
Returns
A multiline display-safe diagnostic string.
Code
Problem
string Problem { get; }
Source
Gets the display-safe problem summary.
Cause
string Cause { get; }
Source
Gets the display-safe cause summary.
Fix
string Fix { get; }
Source
Gets the suggested recovery action.
Docs
string? Docs { get; }
Source
Gets an optional documentation hint or URL.
Retryable
bool Retryable { get; }
Source
Gets a value indicating whether retrying later may resolve the condition.
AppSurfaceLocalSecretsModule
SourceRegisters the AppSurface LocalSecrets provider and supporting services.
Remarks
Add this module only when the application wants fail-closed local secret posture. Environment variables keep the highest precedence, LocalSecrets sits above file configuration, and only true missing local secrets fall through.
ConfigureServices
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Registers LocalSecrets services.
Parameters
contextStartup context for the current app.servicesService collection that receives LocalSecrets registrations.
FileAppSurfaceLocalSecretStore
SourceFile-backed LocalSecrets store for deterministic local workflows and tests.
Remarks
This store is useful when OS credential tooling is unavailable in CI or examples. It is not the default platform store and should not be used as a production vault. The file contains secret values and must stay outside source control.
GetDefaultPath
string GetDefaultPath()
Source
Gets the default per-user AppSurface local secret file path.
Returns
A path under the user's local application data directory.
AppSurfaceLocalSecretIdentityNormalizer
SourceNormalizes LocalSecrets app, environment, prefix, and key values into a stable storage identity.
Remarks
The normalizer is the boundary between logical AppSurface config keys and platform-specific local secret names. Application, environment, and prefix segments are trimmed, capped at 128 characters, and limited to ASCII letters, digits, dash, underscore, and dot where documented. Whitespace in segments becomes -. Config keys are trimmed, capped at 256 characters, reject nulls and line breaks, normalize __ to :, and normalize \ to /. When the application name is omitted, the normalizer infers one from the entry assembly, then the current directory, then AppSurfaceApp; pin AppSurfaceLocalSecretsOptions.ApplicationName for published apps so deployment shape or working-directory changes do not move the local secret namespace.
Normalize
AppSurfaceLocalSecretIdentityResult Normalize(string? applicationName, string environment, string? keyPrefix, string key)
Source
Normalizes a local secret identity.
Parameters
applicationNameThe optional configured application name.environmentThe AppSurface environment name.keyPrefixThe optional key prefix.keyThe AppSurface config key.
Returns
A normalized identity result.
Remarks
A successful result contains normalized display segments and a storage name in the form appsurface:{application}:{environment}:{key}, or appsurface:{application}:{environment}:{prefix}:{key} when a prefix is configured. Invalid input returns a display-safe diagnostic rather than throwing so command and provider paths can render paste-safe guidance.
LocalSecretsPostureMode
SourceDefines where LocalSecrets is allowed to participate in configuration resolution.
Remarks
Numeric values are part of the public AppSurface LocalSecrets contract and must remain stable. The zero value is DevelopmentOnly so CLR default enum initialization matches the documented provider default.
AppSurfaceLocalSecretIdentityResult
SourceDescribes local secret identity normalization.
Parameters
IdentityThe normalized identity when valid.DiagnosticThe display-safe diagnostic when invalid.
Valid
AppSurfaceLocalSecretIdentityResult Valid(AppSurfaceLocalSecretIdentity identity)
Source
Creates a successful identity result.
Parameters
identityThe normalized identity.
Returns
A successful result.
Invalid
AppSurfaceLocalSecretIdentityResult Invalid(AppSurfaceLocalSecretDiagnostic diagnostic)
Source
Creates a failed identity result.
Parameters
diagnosticThe display-safe diagnostic.
Returns
A failed result.
Succeeded
bool Succeeded { get; }
Source
Gets a value indicating whether normalization succeeded.
AppSurfaceLocalSecretProvider
SourceAppSurface configuration provider that resolves values from the local secret store.
Remarks
The provider sits above file configuration and below environment variables. Only true missing secrets fall through; store, posture, identity, and conversion failures are terminal when fail-closed behavior is enabled.
ResolveValue
AppSurfaceLocalSecretResolution<T> ResolveValue<T>(string environment, string key)
Source
Resolves a local secret and returns the structured LocalSecrets status before config-provider adaptation.
Type Parameters
TThe requested configuration value type.
Parameters
environmentThe AppSurface environment being resolved.keyThe logical AppSurface configuration key.
Returns
The typed LocalSecrets resolution.
ServiceCollectionLocalSecretsExtensions
SourceProvides service collection helpers for AppSurface LocalSecrets.
ConfigureAppSurfaceLocalSecrets
IServiceCollection ConfigureAppSurfaceLocalSecrets(this IServiceCollection services, Action<AppSurfaceLocalSecretsOptions> configure)
Source
Configures LocalSecrets options.
Parameters
servicesThe service collection to configure.configureThe options callback.
Returns
The original service collection.
UseAppSurfaceLocalSecretStore
2 overloads
IServiceCollection UseAppSurfaceLocalSecretStore<TStore>(this IServiceCollection services)
Source
Replaces the local secret store implementation.
Type Parameters
TStoreThe store implementation type.
Parameters
servicesThe service collection to configure.
Returns
The original service collection.
IServiceCollection UseAppSurfaceLocalSecretStore(this IServiceCollection services, IAppSurfaceLocalSecretStore store)
Source
Replaces the local secret store with a specific instance.
Parameters
servicesThe service collection to configure.storeThe store instance.
Returns
The original service collection.
LocalSecretResultStatus
SourceIdentifies the outcome of a local secret lookup or mutation.
Remarks
Only Missing represents true absence and may fall through to lower-priority configuration providers. All other non-found states are terminal for a LocalSecrets-claimed key. Numeric values are part of the public AppSurface LocalSecrets contract and must remain stable because status values may appear in diagnostics, tests, serialized examples, or package-consumer switch expressions.
AppSurfaceLocalSecretListResult
SourceDescribes a local secret list operation.
Parameters
StatusThe list status.KeysThe display-safe logical config keys.DiagnosticThe display-safe diagnostic for non-success states.SourceThe display-safe source name.
Found
AppSurfaceLocalSecretListResult Found(IEnumerable<string> keys, string source)
Source
Creates a successful list result.
Parameters
keysThe display-safe logical config keys.sourceThe display-safe source name.
Returns
A list result.
Failed
AppSurfaceLocalSecretListResult Failed(LocalSecretResultStatus status, AppSurfaceLocalSecretDiagnostic diagnostic, string source)
Source
Creates a non-success list result.
Parameters
statusThe non-success status.diagnosticThe display-safe diagnostic.sourceThe display-safe source name.
Returns
A list result.
AppSurfaceLocalSecretResult
SourceDescribes the result of a local secret store operation.
Parameters
StatusThe operation status.ValueThe raw secret value only whenStatusisLocalSecretResultStatus.Found.DiagnosticThe display-safe diagnostic for non-success states.SourceThe display-safe source name that handled the operation.
Found
AppSurfaceLocalSecretResult Found(string value, string source)
Source
Creates a found result.
Parameters
valueThe raw secret value.sourceThe display-safe source name.
Returns
A found result.
Missing
AppSurfaceLocalSecretResult Missing(string source)
Source
Creates a missing result that may fall through to lower-priority providers.
Parameters
sourceThe display-safe source name.
Returns
A missing result.
NotFound
AppSurfaceLocalSecretResult NotFound(LocalSecretResultStatus status, AppSurfaceLocalSecretDiagnostic diagnostic, string source)
Source
Creates a non-found result with a display-safe diagnostic.
Parameters
statusThe non-found status.diagnosticThe display-safe diagnostic.sourceThe display-safe source name.
Returns
A non-found result.
AppSurfaceLocalSecretResolution<T>
SourceDescribes typed LocalSecrets provider resolution before it is adapted to ForgeTrust.AppSurface.Config.IConfigProvider.
Type Parameters
TThe requested configuration value type.
Parameters
StatusThe structured LocalSecrets resolution status.ValueThe converted secret value only whenStatusisLocalSecretResultStatus.Found.DiagnosticThe display-safe diagnostic for non-success states.SourceThe display-safe source name that handled the lookup.
Found
AppSurfaceLocalSecretResolution<T> Found(T? value, string source)
Source
Creates a found resolution.
Parameters
valueThe converted value.sourceThe display-safe source name.
Returns
A found resolution.
NotFound
AppSurfaceLocalSecretResolution<T> NotFound(LocalSecretResultStatus status, AppSurfaceLocalSecretDiagnostic diagnostic, string source)
Source
Creates a non-found resolution with a display-safe diagnostic.
Parameters
statusThe non-found status.diagnosticThe display-safe diagnostic.sourceThe display-safe source name.
Returns
A non-found resolution.
AppSurfaceLocalSecretsOptions
SourceConfigures the AppSurface LocalSecrets provider.
Remarks
Defaults are intentionally fail-closed: LocalSecrets is development-only, claims keys once registered, and reports local store failures as terminal diagnostics instead of falling through to lower-priority file configuration.
Posture
LocalSecretsPostureMode Posture { get; set; }
Source
Gets or sets the posture mode for local secret resolution.
ApplicationName
string? ApplicationName { get; set; }
Source
Gets or sets the application identity used in the platform store namespace.
Remarks
Leave unset to infer an identity from the entry assembly or current directory. Override this when multiple apps share a binary name or when command-line workflows need a stable package-independent identity.
KeyPrefix
string? KeyPrefix { get; set; }
Source
Gets or sets an optional namespace prefix applied before the AppSurface config key.
DocsHint
string DocsHint { get; set; }
Source
Gets or sets the documentation hint emitted in local secret diagnostics.
FailClosedOnStoreFailure
bool FailClosedOnStoreFailure { get; set; }
Source
Gets or sets a value indicating whether local store failures stop lower-priority provider resolution.
Remarks
Keep the default enabled for secret posture. Disabling this escape hatch makes unavailable stores behave like missing values and can mask secrets from files.
DevelopmentEnvironmentNames
ISet<string> DevelopmentEnvironmentNames { get; }
Source
Gets or sets development-like environment names accepted by LocalSecretsPostureMode.DevelopmentOnly.
AppSurfaceLocalSecretIdentity
SourceIdentifies one local secret across application, environment, prefix, and AppSurface config key.
Parameters
ApplicationNameThe normalized application name.EnvironmentThe normalized environment name.KeyPrefixThe optional normalized key prefix.KeyThe normalized AppSurface config key.StorageNameThe stable cross-platform storage name.
IAppSurfaceLocalSecretStore
SourceStores AppSurface LocalSecrets values for one machine and user context.
Remarks
Implementations should use display-safe diagnostics for expected platform failures. Raw secret values may be returned only through Get(AppSurfaceLocalSecretIdentity) when the status is LocalSecretResultStatus.Found.
Get
AppSurfaceLocalSecretResult Get(AppSurfaceLocalSecretIdentity identity)
Source
Reads a local secret.
Parameters
identityThe normalized local secret identity.
Returns
The store result.
Set
AppSurfaceLocalSecretResult Set(AppSurfaceLocalSecretIdentity identity, string value)
Source
Writes a local secret.
Parameters
identityThe normalized local secret identity.valueThe raw secret value.
Returns
The store result. Successful writes return LocalSecretResultStatus.Found with no value.
Delete
AppSurfaceLocalSecretResult Delete(AppSurfaceLocalSecretIdentity identity)
Source
Deletes a local secret.
Parameters
identityThe normalized local secret identity.
Returns
The store result.
List
AppSurfaceLocalSecretListResult List(string applicationName, string environment, string? keyPrefix)
Source
Lists known local secret config keys for an application/environment namespace.
Parameters
applicationNameThe normalized application name.environmentThe normalized environment name.keyPrefixThe optional normalized key prefix.
Returns
The list result.
Doctor
AppSurfaceLocalSecretResult Doctor(string applicationName, string environment, string? keyPrefix)
Source
Diagnoses whether the store is usable for the supplied namespace.
Parameters
applicationNameThe normalized application name.environmentThe normalized environment name.keyPrefixThe optional normalized key prefix.
Returns
A display-safe store diagnostic result.
Name
string Name { get; }
Source
Gets the display-safe store name.