FractalDataWorks.Services.SecretManagers.Abstractions 0.4.0-preview.6

FractalDataWorks.Services.SecretManagers.Abstractions

Abstractions and interfaces for secret management operations in the FractalDataWorks platform, providing provider-agnostic secret storage and retrieval capabilities.

Overview

This package defines the core abstractions for the FractalDataWorks secret management system, enabling secure storage and retrieval of sensitive data across multiple secret providers (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, etc.). It uses a command-based pattern with the framework's ServiceType infrastructure for provider discovery.

Target Framework

• netstandard2.0

Key Components

Core Interfaces

ISecretManager

Main interface for secret management operations using command-based pattern.

From ISecretManager.cs:21-78:

public interface ISecretManager : IDisposable, IGenericService
{
    Task<IGenericResult<object?>> Execute(ISecretManagerCommand managementCommand, CancellationToken cancellationToken = default);
    Task<IGenericResult<TResult>> Execute<TResult>(ISecretManagerCommand<TResult> managementCommand, CancellationToken cancellationToken = default);
    Task<IGenericResult> ExecuteBatch(IReadOnlyList<ISecretManagerCommand> commands, CancellationToken cancellationToken = default);
    IGenericResult ValidateCommand(ISecretManagerCommand managementCommand);
}

ISecretManagerCommand

Command interface for secret operations with validation and metadata support.

From ISecretManagerCommand.cs:18-130:

public interface ISecretManagerCommand : IGenericCommand
{
    new string CommandId { get; }
    string? Container { get; }
    string? SecretKey { get; }
    Type ExpectedResultType { get; }
    TimeSpan? Timeout { get; }
    IReadOnlyDictionary<string, object?> Parameters { get; }
    IReadOnlyDictionary<string, object> Metadata { get; }
    bool IsSecretModifying { get; }
    ISecretManagerCommand WithParameters(IReadOnlyDictionary<string, object?> newParameters);
    ISecretManagerCommand WithMetadata(IReadOnlyDictionary<string, object> newMetadata);
}

ISecretManagerCommand<TResult>

Generic interface for typed command results.

From ISecretManagerCommand.cs:141-164:

public interface ISecretManagerCommand<TResult> : ISecretManagerCommand
{
    new ISecretManagerCommand<TResult> WithParameters(IReadOnlyDictionary<string, object?> newParameters);
    new ISecretManagerCommand<TResult> WithMetadata(IReadOnlyDictionary<string, object> newMetadata);
}

Configuration

ISecretManagerConfiguration

Configuration interface for secret management services.

From ISecretManagerConfiguration.cs:12-28:

public interface ISecretManagerConfiguration : IGenericConfiguration
{
    string SecretManagerType { get; }
    IServiceLifetime Lifetime { get; }
}

Provider Infrastructure

ISecretManagerProvider

Provider interface for creating and resolving secret manager services. Inherits from IFdwServiceProvider.

From ISecretManagerProvider.cs:1-11:

/// <summary>
/// Interface for providers that create and manage secret managers.
/// Inherits Create methods from IFdwServiceProvider.
/// </summary>
public interface ISecretManagerProvider : IFdwServiceProvider<ISecretManager, ISecretManagerConfiguration>
{
    // Inherits from IFdwServiceProvider:
    // IGenericResult<ISecretManager> Create(ISecretManagerConfiguration configuration);
    // IGenericResult<ISecretManager> Create(string name);
    // IGenericResult<ISecretManager> Create(Guid id);
    // IGenericResult<T> Create<T>(ISecretManagerConfiguration configuration) where T : ISecretManager;
    // IGenericResult<T> Create<T>(string name) where T : ISecretManager;
    // IGenericResult<T> Create<T>(Guid id) where T : ISecretManager;
}

ISecretManagerServiceFactory

Factory interfaces for creating secret manager instances.

From ISecretManagerServiceFactory.cs:13-53:

public interface ISecretManagerServiceFactory : IServiceFactory
{
    Task<IGenericResult<ISecretManager>> CreateSecretManager(IGenericConfiguration configuration);
}

public interface ISecretManagerServiceFactory<TSecretService> : ISecretManagerServiceFactory, IServiceFactory<TSecretService>
    where TSecretService : ISecretManager
{
}

public interface ISecretManagerServiceFactory<TSecretService, TConfiguration> : ISecretManagerServiceFactory<TSecretService>, IServiceFactory<TSecretService, TConfiguration>
    where TSecretService : ISecretManager
    where TConfiguration : ISecretManagerConfiguration
{
    Task<IGenericResult<TSecretService>> CreateSecretManager(TConfiguration configuration);
}

ServiceType Infrastructure

ISecretManagerType

Interface for secret management service types with provider capabilities.

From ISecretManagerType.cs:27-73:

public interface ISecretManagerType : IServiceType
{
    string[] SupportedSecretStores { get; }
    IReadOnlyList<string> SupportedSecretTypes { get; }
    bool SupportsRotation { get; }
    bool SupportsVersioning { get; }
    bool SupportsBulkOperations { get; }
    bool SupportsEncryptionAtRest { get; }
    bool SupportsAuditing { get; }
    int MaxSecretSize { get; }
    string CloudProvider { get; }
}

Container and Metadata

ISecretContainer

Interface representing a secret container (vault, store, namespace).

From ISecretContainer.cs:15-181:

public interface ISecretContainer
{
    string ContainerId { get; }
    string Name { get; }
    string ContainerType { get; }
    string? Description { get; }
    string ProviderId { get; }
    DateTimeOffset CreatedAt { get; }
    DateTimeOffset ModifiedAt { get; }
    bool IsEnabled { get; }
    bool SupportsVersioning { get; }
    bool SupportsExpiration { get; }
    bool SupportsBinarySecrets { get; }
    IReadOnlyCollection<string> Tags { get; }
    IReadOnlyDictionary<string, object> Metadata { get; }
    IReadOnlyCollection<string> SupportedOperations { get; }
    ISecretContainerUsage? Usage { get; }
}

ISecretContainerUsage

Interface for container usage statistics.

From ISecretContainerUsage.cs:13-60:

public interface ISecretContainerUsage
{
    long UsedStorageBytes { get; }
    long ReadOperations { get; }
    long WriteOperations { get; }
    long DeleteOperations { get; }
    TimeSpan AverageResponseTime { get; }
    DateTimeOffset LastUpdated { get; }
    TimeSpan StatisticsPeriod { get; }
}

ISecretMetadata

Interface for secret metadata without exposing values.

From ISecretMetadata.cs:15-146:

public interface ISecretMetadata
{
    string Key { get; }
    string? Container { get; }
    string? Version { get; }
    DateTimeOffset CreatedAt { get; }
    DateTimeOffset ModifiedAt { get; }
    DateTimeOffset? ExpiresAt { get; }
    bool IsExpired { get; }
    bool IsEnabled { get; }
    bool IsBinary { get; }
    long SizeInBytes { get; }
    IReadOnlyCollection<string> Tags { get; }
    IReadOnlyDictionary<string, object> Properties { get; }
    IReadOnlyCollection<string> AvailableVersions { get; }
}

Secret Types (TypeCollection)

SecretTypes

TypeCollection for identifying what kind of credential a service requires.

From Secrets/SecretTypes.cs:11-21:

[TypeCollection(typeof(SecretTypeBase), typeof(ISecretType), typeof(SecretTypes), RestrictToCurrentCompilation = false)]
public sealed partial class SecretTypes : TypeCollectionBase<SecretTypeBase, ISecretType>
{
}

SecretTypeBase

Base class for secret type markers.

From Secrets/SecretTypeBase.cs:14-39:

public abstract class SecretTypeBase : TypeOptionBase<int, ISecretType>, ISecretType
{
    public bool RequiresSecureStorage { get; }

    protected SecretTypeBase(
        int id,
        string name,
        string description,
        bool requiresSecureStorage = true,
        string? category = null)
        : base(id, name, name, name, description ?? string.Empty, category ?? "Secret")
    {
        RequiresSecureStorage = requiresSecureStorage;
    }
}

NoneSecretType

Built-in type for services that do not require secrets.

From Secrets/NoneSecretType.cs:8-22:

[TypeOption(typeof(SecretTypes), "None")]
public sealed class NoneSecretType : SecretTypeBase, ISecretType
{
    public NoneSecretType()
        : base(
            id: 0,
            name: "None",
            description: "No secret required",
            requiresSecureStorage: false)
    {
    }
}

Command TypeCollection

SecretManagerCommands

Collection of secret manager command types with source-generated lookups.

From Commands/SecretManagerCommands.cs:12-16:

[TypeCollection(typeof(ISecretManagerCommand), typeof(ISecretManagerCommand), typeof(SecretManagerCommands))]
public abstract partial class SecretManagerCommands : TypeCollectionBase<ISecretManagerCommand>
{
}

Messages

SecretManagerMessage

Base class for secret manager messages using the MessageCollection pattern.

From Messages/SecretManagerMessage.cs:10-24:

[MessageCollection("SecretManagerMessages")]
public abstract class SecretManagerMessage : MessageTemplate<MessageSeverity>, IServiceMessage
{
    protected SecretManagerMessage(int id, string name, MessageSeverity severity,
        string message, string? code = null)
        : base(id, name, severity, message, code, "SecretManager", null, null) { }
}

Predefined messages include:

• CommandNullMessage - Command cannot be null (SM_CMD_NULL)
• SecretKeyRequiredMessage - SecretKey is required for operation (SM_KEY_REQUIRED)
• SecretValueRequiredMessage - SecretValue parameter is required (SM_VALUE_REQUIRED)
• ValidationFailedMessage - Validation failed (SM_VALIDATION_FAILED)

Logging

SecretManagerLogger

Static logger class using MessageLogging source generator.

From Logging/SecretManagerLogger.cs:10-23:

public static partial class SecretManagerLogger
{
    [MessageLogging(
        EventId = 4001,
        Level = LogLevel.Error,
        Message = "Secret manager validation failed: {errorMessage}")]
    public static partial IGenericMessage ValidationFailed(ILogger logger, string errorMessage);
}

Registration

SecretManagerRegistrationOptions

Registration options with default Singleton lifetime.

From SecretManagerRegistrationOptions.cs:10-16:

public sealed class SecretManagerRegistrationOptions : RegistrationOptions
{
    public SecretManagerRegistrationOptions() : base(ServiceLifetime.Singleton) { }
}

Dependencies

Project References

• FractalDataWorks.Collections - TypeCollection infrastructure
• FractalDataWorks.Collections.SourceGenerators - TypeCollection source generation
• FractalDataWorks.Configuration - Configuration base types
• FractalDataWorks.Configuration.Abstractions - Configuration interfaces
• FractalDataWorks.MessageLogging.SourceGenerators - Logger source generation
• FractalDataWorks.Services.Abstractions - Service abstractions
• FractalDataWorks.Services.Abstractions - ServiceType patterns

Package References

• Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions
• Microsoft.Extensions.Logging.Abstractions

Architecture Notes

Command Pattern

The package uses a command-based pattern for secret operations:

• Commands encapsulate operation details (container, key, parameters, metadata)
• Commands are validated before execution via ValidateCommand()
• Commands support fluent copying via WithParameters() and WithMetadata()
• The IsSecretModifying flag distinguishes reads from writes for access control

ServiceType Integration

Secret managers integrate with the ServiceType framework:

• ISecretManagerType defines provider capabilities (versioning, rotation, auditing)
• ISecretManagerServiceFactory creates instances from configuration
• ISecretManagerProvider resolves managers by type or configuration name
• TypeCollections enable discovery across assemblies

Message Infrastructure

Messages follow the framework's MessageCollection pattern:

• SecretManagerMessage base class with severity and code
• Predefined messages for common validation errors
• Source-generated logger methods via SecretManagerLogger

Design Philosophy

These abstractions follow the framework's minimal interface pattern:

• Define domain boundaries through interfaces
• Provide type safety through base classes
• Enable service discovery via TypeCollections
• Support provider-specific extensions through metadata
• No implementation logic in abstractions
• No secret values exposed in interface contracts

Related Packages

• FractalDataWorks.Services.SecretManagers - Concrete implementations
• FractalDataWorks.Services.Connections.Abstractions - Connection abstractions (uses secrets)
• FractalDataWorks.Services.Authentication.Abstractions - Authentication abstractions