bool Succeeded { get; }
Source
Gets a value indicating whether normalization succeeded.
LocalSecrets
IAppSurfaceLocalSecretMetadataStore
SourceProbes LocalSecrets metadata without returning raw secret values.
Remarks
Transfer workflows use this seam for dry-run planning and overwrite checks so they can answer whether a local identity is known without calling IAppSurfaceLocalSecretStore.Get(AppSurfaceLocalSecretIdentity). Implementations must return display-safe diagnostics and must not put secret payloads in successful probe results. Platform stores may use their LocalSecrets index as metadata; stale indexed entries are verified later when an apply operation performs the value read that is required for transfer.
Probe
AppSurfaceLocalSecretResult Probe(AppSurfaceLocalSecretIdentity identity)
Source
Probes whether a local secret identity is present in store metadata.
Parameters
identityThe normalized local secret identity.
Returns
A display-safe result. LocalSecretResultStatus.Found means the identity is present in metadata; LocalSecretResultStatus.Missing means the store can confirm no metadata entry exists.
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.
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.
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
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.
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
string Code { get; }
Source
Gets the stable machine-readable diagnostic 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.
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.
PlatformAppSurfaceLocalSecretStore
SourceLocalSecrets store that delegates to the current operating system's user secret facility when available.
Remarks
macOS uses an entitlement-free Security.framework SecItem v2 Keychain namespace with retained legacy-record migration diagnostics, Windows uses current-user Credential Manager generic credentials, Linux uses Secret Service through secret-tool, and unsupported sessions return display-safe diagnostics.
CreateInnerStoreForTests
IAppSurfaceLocalSecretStore CreateInnerStoreForTests(AppSurfaceLocalSecretsOptions options, LinuxSecretToolResolver linuxSecretToolResolver, LocalSecretsPlatform? platformOverride = null)
Source
Creates the platform-specific inner store with deterministic platform selection for tests.
Parameters
optionsLocalSecrets options used by platform resolution.linuxSecretToolResolverLinux resolver seam used when the selected platform is Linux.platformOverrideOptional platform override; when unset, the current runtime platform is used.
Returns
The store selected for the requested platform and options.
LinuxSecretToolResolver
SourceResolves the Linux secret-tool executable from AppSurface-trusted defaults or an explicit absolute override.
Remarks
The resolver is the trust boundary for Linux Secret Service command execution. It intentionally ignores arbitrary PATH matches for command selection and reports them only as diagnostic context so package consumers do not accidentally execute a spoofed secret-tool binary.
Resolve
LinuxSecretToolResolution Resolve(string? overridePath)
Source
Resolves the executable path that the Linux platform store may launch.
Parameters
overridePathOptional explicit override path fromAppSurfaceLocalSecretsOptions.LinuxSecretToolPathor the CLI--secret-tool-pathoption. Overrides must be absolute executable files.
Returns
A successful resolution with a trusted executable path, or a failed resolution containing a display-safe diagnostic that explains why command execution is blocked.
Remarks
Passing null uses the trusted default candidates only. Passing an empty, relative, missing, directory, or non-executable override fails before any process is launched.
UnsupportedPlatformOverride
LinuxSecretToolResolution UnsupportedPlatformOverride(string overridePath)
Source
Creates the diagnostic result used when a Linux-only override is configured on a non-Linux platform.
Parameters
overridePathThe configured override path that cannot be used on the current platform.
Returns
A failed resolution instructing callers to remove the Linux-only override.
Default
LinuxSecretToolResolver Default { get; }
Source
Gets the production resolver that trusts /usr/bin/secret-tool, then /bin/secret-tool.
LinuxSecretToolResolution
SourceImmutable outcome from resolving the Linux secret-tool command path.
Parameters
SucceededtruewhenPathcontains a command path that may be launched.PathThe trusted executable path for successful resolutions, ornullfor failed resolutions.StatusThe LocalSecrets result status callers should surface when resolution fails.DiagnosticDisplay-safe diagnostic details for failed resolutions, ornullwhen resolution succeeds.
Remarks
Callers should use Found(string) and Failed(LocalSecretResultStatus, AppSurfaceLocalSecretDiagnostic) so success results never carry diagnostics and failed results always carry the user-facing cause/fix guidance.
Found
LinuxSecretToolResolution Found(string path)
Source
Creates a successful resolution for a trusted executable path.
Parameters
pathThe absolute command path that the Linux platform store may launch.
Returns
A resolution with Succeeded set and no diagnostic.
Failed
LinuxSecretToolResolution Failed(LocalSecretResultStatus status, AppSurfaceLocalSecretDiagnostic diagnostic)
Source
Creates a failed resolution with the status and diagnostic callers should surface.
Parameters
statusThe LocalSecrets status that best describes the failure category.diagnosticDisplay-safe details explaining why command resolution failed and how to fix it.
Returns
A resolution with no executable path and Succeeded unset.
IndexedLocalSecretStore
SourceReadStoredValue
AppSurfaceLocalSecretResult ReadStoredValue(AppSurfaceLocalSecretIdentity identity)
Source
Reads one raw platform-stored value without applying indexed-store policy.
Parameters
identityThe normalized storage identity to read.
Returns
LocalSecretResultStatus.Found with the stored secret value when the value exists, LocalSecretResultStatus.Missing when the platform confirms absence, or a terminal failure such as LocalSecretResultStatus.Locked, LocalSecretResultStatus.Unavailable, LocalSecretResultStatus.UnsupportedPlatform, or LocalSecretResultStatus.ProviderFailed when the platform cannot safely answer. List depends on these statuses to distinguish stale indexed names from stores it could not verify.
WriteStoredValue
AppSurfaceLocalSecretResult WriteStoredValue(AppSurfaceLocalSecretIdentity identity, string value)
Source
Writes one raw platform-stored value without applying indexed-store policy.
Parameters
identityThe normalized storage identity to write.valueThe secret value or index JSON to store.
Returns
LocalSecretResultStatus.Found with no display value when the platform write succeeds, or a terminal failure when the platform is locked, unavailable, unsupported, or rejects the write. Set and index repair only report success after this method succeeds for both the value and any required index write.
DeleteStoredValue
AppSurfaceLocalSecretResult DeleteStoredValue(AppSurfaceLocalSecretIdentity identity)
Source
Deletes one raw platform-stored value without applying indexed-store policy.
Parameters
identityThe normalized storage identity to delete.
Returns
LocalSecretResultStatus.Found when the platform deleted an existing value, LocalSecretResultStatus.Missing when the platform confirms absence, or a terminal failure when the platform cannot safely delete or confirm absence. Delete uses the result together with an index read to decide whether to remove a stale indexed name, preserve a confirmed missing result, or fail closed.
DoctorStore
AppSurfaceLocalSecretResult DoctorStore(string applicationName, string environment, string? keyPrefix)
Source
Verifies raw platform store availability for a namespace.
Parameters
applicationNameThe normalized application namespace.environmentThe normalized environment namespace.keyPrefixThe optional normalized key prefix.
Returns
A display-safe readiness result. Implementations should exercise raw platform read/write/delete behavior without adding probe names to the user-visible index and should propagate locked, unavailable, unsupported, or provider failures so CLI diagnostics remain fail-closed.
CommandBackedLocalSecretStore
SourceMapCommandFailure
AppSurfaceLocalSecretResult MapCommandFailure(PlatformSecretCommandResult result, string operation)
Source
Maps a failed platform command result into the LocalSecrets diagnostic contract.
Parameters
resultThe platform command result with explicit real-process or synthetic provenance.operationThe display-safe LocalSecrets operation name, such asgetordelete.
Returns
A retryable not-found result classified as LocalSecretResultStatus.Locked for real locked-store process output, or LocalSecretResultStatus.Unavailable for timeouts, startup failures, and other process failures.
Remarks
Only PlatformSecretCommandResultKind.ProcessExited carries real platform process output that can prove a locked or denied user secret store. Synthetic PlatformSecretCommandResultKind.TimedOut and PlatformSecretCommandResultKind.StartFailed results must remain LocalSecretResultStatus.Unavailable and use redacted cause text, even when the underlying exception message contains words such as locked or denied. Custom internal runners should use PlatformSecretCommandResult.FromProcess(int, string, string) only after a platform command exits, and should keep command paths, arguments, logical values, absolute paths, and secret values out of AppSurfaceLocalSecretDiagnostic provenance fields.
BuildCommandFailureCause
string BuildCommandFailureCause(PlatformSecretCommandResult result, string operation)
Source
Builds the display-safe diagnostic cause for a failed platform command.
Remarks
Real process exits report only the exit code because platform stderr can contain provider-specific text. Synthetic startup failures report sanitized exception provenance prepared by PlatformSecretCommandResult.StartFailed(Exception); if an internal runner constructs a startup failure without detail, the cause uses a stable fallback instead of rendering empty punctuation.
PlatformSecretCommandResult
SourceCaptures display-safe output and provenance for one platform secret command attempt.
FromProcess
PlatformSecretCommandResult FromProcess(int exitCode, string output, string error)
Source
Creates a result from a platform process that started and exited.
Parameters
exitCodeThe process exit code.outputThe trimmed standard output.errorThe standard error output.
Returns
A process-exited command result.
StartFailed
PlatformSecretCommandResult StartFailed(Exception exception)
Source
Creates the synthetic result used when the platform command cannot be started.
Parameters
exceptionThe runner exception caught while starting the process.
Returns
A display-safe startup failure result.
ExitCode
int ExitCode { get; }
Source
Gets the process exit code or the synthetic failure code for runner-level failures.
Output
string Output { get; }
Source
Gets the trimmed standard output for process results.
Error
string Error { get; }
Source
Gets standard error or display-safe synthetic failure details.
Kind
PlatformSecretCommandResultKind Kind { get; }
Source
Gets the result provenance used by platform status mapping.
TimedOut
PlatformSecretCommandResult TimedOut { get; }
Source
Gets the synthetic result used when the platform command exceeds the timeout.
LocalSecretsPlatform
SourceRepresents platform selections used by deterministic platform-store tests.
LinuxSecretToolPathState
SourceDescribes the file-system state of a candidate Linux secret-tool path.
Remarks
The states deliberately separate existence from executability so diagnostics can distinguish missing binaries, directory mistakes, and files that exist but cannot be launched.
PlatformSecretCommandResultKind
SourceIdentifies whether a platform secret command result came from an exited process or a runner-level synthetic failure.
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.
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.
AppSurfaceLocalSecretListResult
SourceDescribes a local secret list operation.
Parameters
StatusThe list status.KeysThe display-safe logical config keys that the store could verify as currently retrievable.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 that the store could verify as currently retrievable.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.
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.
LinuxSecretToolPath
string? LinuxSecretToolPath { get; set; }
Source
Gets or sets an explicit Linux secret-tool executable path for nonstandard trusted installs.
Remarks
Leave unset to use AppSurface's trusted Linux system candidates only: /usr/bin/secret-tool, then /bin/secret-tool. Set this only when the binary is trusted and verified with a command such as test -x /absolute/path/to/secret-tool. Relative, empty, missing, directory, and non-executable paths are rejected. This option is Linux-only; macOS and Windows use their native credential stores.
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.
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.
AppSurfaceLocalSecretMigrationRow
SourceDescribes one value-safe local-secret migration outcome.
Parameters
KeyThe logical LocalSecrets key. Secret values are never included.ActionThe completed or failed migration action.StatusThe store status for this key.DiagnosticThe display-safe diagnostic when the action failed.
AppSurfaceLocalSecretMigrationActionExtensions
SourceProvides display-safe text for AppSurfaceLocalSecretMigrationAction values.
ToDisplayString
string ToDisplayString(this AppSurfaceLocalSecretMigrationAction action)
Source
Returns the stable text rendered by the LocalSecrets migration command.
Parameters
actionThe migration action to render.
Returns
The stable action text, or the enum fallback text for an action introduced by a newer implementation.
AppSurfaceLocalSecretMigrationResult
SourceDescribes migration of one LocalSecrets namespace without exposing secret values.
Parameters
StatusThe overall migration status.RowsValue-safe per-key outcomes.DiagnosticA display-safe namespace-level failure diagnostic when migration could not start.SourceThe display-safe store name.
Completed
AppSurfaceLocalSecretMigrationResult Completed(IEnumerable<AppSurfaceLocalSecretMigrationRow> rows, string source)
Source
Creates a completed migration result.
Parameters
rowsValue-safe per-key outcomes.sourceThe display-safe store name.
Returns
The migration result.
FailedToStart
AppSurfaceLocalSecretMigrationResult FailedToStart(LocalSecretResultStatus status, AppSurfaceLocalSecretDiagnostic diagnostic, string source)
Source
Creates a migration result that could not start safely.
Parameters
statusThe terminal status.diagnosticThe display-safe diagnostic.sourceThe display-safe store name.
Returns
The failed migration result.
Migrated
int Migrated { get; }
Source
Gets the number of records copied into current storage.
AlreadyV2
int AlreadyV2 { get; }
Source
Gets the number of records already present in current storage.
Failed
int Failed { get; }
Source
Gets the number of records that could not be migrated.
AppSurfaceLocalSecretMigrationAction
SourceIdentifies the action taken for one LocalSecrets migration row.
Remarks
Use AppSurfaceLocalSecretMigrationActionExtensions.ToDisplayString(AppSurfaceLocalSecretMigrationAction) when rendering an action for an operator. The text remains stable so command output is compatible with the initial macOS v2 migration workflow.
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.
IFileAppSurfaceLocalSecretStoreFileSystem
SourceProvides filesystem operations for the explicit file-backed LocalSecrets store.
Remarks
The seam keeps posture checks ordered around raw secret IO: read inspection must finish before file contents are opened, write preparation may create only missing directories, and doctor may repair only the fallback file itself.
FileExists
bool FileExists(string path)
Source
Returns whether the configured fallback file exists.
Parameters
pathThe normalized fallback file path.
Returns
true when the fallback file exists.
ReadAllText
string ReadAllText(string path)
Source
Reads the fallback JSON file after posture inspection has already succeeded.
Parameters
pathThe normalized fallback file path.
Returns
The raw JSON contents.
OpenRead
Stream OpenRead(string path)
Source
Opens the fallback JSON file for metadata-only streaming scans after posture inspection has already succeeded.
Parameters
pathThe normalized fallback file path.
Returns
A readable stream for the raw JSON contents.
InspectReadPath
FileSecretPostureResult InspectReadPath(string path)
Source
Inspects only the path shape needed before read attempts that do not need file mode posture.
Parameters
pathThe normalized fallback file path.
Returns
The path-shape posture result.
InspectExistingFilePosture
FileSecretPostureResult InspectExistingFilePosture(string path)
Source
Inspects the existing fallback file and immediate containing directory before returning or reading secret values.
Parameters
pathThe normalized fallback file path.
Returns
The existing-file posture result.
PrepareWrite
FileSecretPostureResult PrepareWrite(string path)
Source
Prepares the fallback path for a write without reading or mutating existing parent directory permissions.
Parameters
pathThe normalized fallback file path.
Returns
The write-preparation posture result.
WriteAllTextWithPosture
FileSecretPostureResult WriteAllTextWithPosture(string path, string contents)
Source
Atomically writes the fallback JSON file and repairs the final file mode when the platform supports it.
Parameters
pathThe normalized fallback file path.contentsThe serialized JSON contents.
Returns
The write posture result.
Doctor
FileSecretPostureResult Doctor(string path)
Source
Opens or creates the fallback file and reports ready, repaired, degraded, or unsupported posture.
Parameters
pathThe normalized fallback file path.
Returns
The doctor posture result.
DefaultFileAppSurfaceLocalSecretStoreFileSystem
SourceDefault filesystem adapter for the explicit file-backed LocalSecrets store.
Remarks
The adapter validates path shape, Unix mode posture, and write ordering without broad filesystem mutation. Missing fallback directories may be created, but existing loose directories are reported for the caller to fix deliberately.
Instance
DefaultFileAppSurfaceLocalSecretStoreFileSystem Instance { get; }
Source
Gets the singleton production adapter.
FileSecretPostureResult
SourceCarries a posture outcome and the value-safe diagnostic text shown by LocalSecrets commands.
Parameters
KindThe posture outcome kind.CodeThe stable diagnostic code.ProblemThe value-safe problem summary.CauseThe value-safe cause.FixThe recommended fix.RetryableWhether retrying without changes may succeed.
Ready
FileSecretPostureResult Ready()
Source
Creates a ready posture result.
Returns
A ready posture result.
Repaired
FileSecretPostureResult Repaired()
Source
Creates a repaired posture result for fallback files tightened by write or doctor.
Returns
A repaired posture result.
Degraded
FileSecretPostureResult Degraded()
Source
Creates a degraded posture result for platforms where owner-only posture cannot be proven in v1.
Returns
A degraded posture result.
Unsupported
FileSecretPostureResult Unsupported(string code, string problem, string cause, string fix)
Source
Creates an unsupported posture result for unsafe path shapes or permanent posture violations.
Parameters
codeThe stable diagnostic code.problemThe value-safe problem summary.causeThe value-safe cause.fixThe recommended fix.
Returns
An unsupported posture result.
ToDiagnostic
AppSurfaceLocalSecretDiagnostic ToDiagnostic()
Source
Converts the posture result to a LocalSecrets diagnostic.
Returns
The value-safe LocalSecrets diagnostic.
FileSecretPostureKind
SourceDescribes the posture outcome for the explicit file fallback.
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.
MacOsV2CompatibilityLocalSecretStore
SourceImplements the macOS v2 write-forward bridge while preserving v1 as a read-only recovery source.
Remarks
V2 uses SecItem without a data-protection attribute, access group, or custom ACL. This intentionally targets the entitlement-free file-based Keychain configuration proven by the macOS feasibility spike. The v1 store remains available only to identify records that require explicit operator migration.
MacOsSecItemQuery
SourceDescribes an immutable file-based macOS SecItem generic-password identity.
MacOsSecItemReadResult
SourceDescribes the status and optional raw value returned by a macOS SecItem read.
IMacOsSecItemInterop
SourceIsolates native macOS Keychain request construction for deterministic compatibility tests.
Read
MacOsSecItemReadResult Read(MacOsSecItemQuery query)
Source
Reads the raw value for a generic-password query.
Parameters
queryThe immutable SecItem identity to read.
Returns
The raw OSStatus and optional copied value. MacOsV2CompatibilityLocalSecretStore maps OSStatus through its local-secret status mapping; a success status with null data is treated as a fail-closed provider error.
Exists
int Exists(MacOsSecItemQuery query)
Source
Checks whether a generic-password query exists without requesting its value data.
Parameters
queryThe immutable SecItem identity to check.
Returns
The raw OSStatus, which the v2 store maps through its local-secret status mapping.
Add
int Add(MacOsSecItemQuery query, byte[] value)
Source
Adds a generic-password value under query without overwriting a record.
Parameters
queryThe immutable SecItem identity to add.valueThe value bytes to store.
Returns
The raw OSStatus, which the v2 store maps through its local-secret status mapping. Existing records must return errSecDuplicateItem so MacOsV2CompatibilityLocalSecretStore can route the write to Update.
Update
int Update(MacOsSecItemQuery query, byte[] value)
Source
Replaces the value for an existing generic-password query.
Parameters
queryThe immutable SecItem identity to update.valueThe replacement value bytes.
Returns
The raw OSStatus, which the v2 store maps through its local-secret status mapping.
Delete
int Delete(MacOsSecItemQuery query)
Source
Deletes the generic-password record identified by query.
Parameters
queryThe immutable SecItem identity to delete.
Returns
The raw OSStatus, which the v2 store maps through its local-secret status mapping.
IAppSurfaceLocalSecretMigrationStore
SourceSupports an explicit, value-safe migration from a legacy LocalSecrets namespace to its current storage format.
Remarks
This optional capability is implemented only by stores that have retained readable legacy records. It never performs migration during configuration resolution: callers must invoke it deliberately and handle the returned per-key status without rendering secret values.
Migrate
AppSurfaceLocalSecretMigrationResult Migrate(string applicationName, string environment, string? keyPrefix)
Source
Copies currently readable legacy records into the current storage format for one normalized namespace.
Parameters
applicationNameThe normalized application identity.environmentThe normalized environment identity.keyPrefixThe optional normalized key prefix.
Returns
A value-safe migration summary.
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. Platform-indexed stores may return LocalSecretResultStatus.Found when the value was already missing but a stale indexed name was removed; keys that were never stored still return LocalSecretResultStatus.Missing when the store can confirm no stale index entry remains. If the platform index cannot be read, platform-indexed stores fail closed instead of assuming the key was never indexed.
List
AppSurfaceLocalSecretListResult List(string applicationName, string environment, string? keyPrefix)
Source
Lists currently retrievable 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. Platform-indexed stores validate indexed names against live stored values and may prune missing entries after a successful validation pass. Corrupt indexes and terminal platform failures return display-safe diagnostics instead of hiding unverified names.
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.
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.
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.