# stella CLI - Plugin Architecture

**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul

## Overview

The `stella` CLI is built with a plugin architecture that enables conditional compilation of regional cryptographic providers (GOST, eIDAS, SM) while maintaining a unified command interface. This design supports compliance with export control regulations and cryptographic standards across different jurisdictions.

**Key Design Goals:**
1. **Conditional Compilation**: Include only authorized crypto providers per distribution
2. **Plugin Isolation**: Crypto providers as self-contained, testable modules
3. **Dependency Injection**: Runtime service resolution for providers
4. **Configuration-driven**: Profile-based provider selection
5. **Extensibility**: Easy addition of new providers without core CLI changes

---

## Architecture Layers

```
┌─────────────────────────────────────────────────────────────┐
│                       stella CLI                             │
├─────────────────────────────────────────────────────────────┤
│  Command Groups                                              │
│  ├─ scan, aoc, symbols, crypto, admin, ...                  │
│  └─ System.CommandLine 2.0 routing                          │
├─────────────────────────────────────────────────────────────┤
│  Plugin System                                               │
│  ├─ ICryptoProvider interface                               │
│  ├─ Plugin discovery (build-time + runtime)                 │
│  └─ DependencyInjection (Microsoft.Extensions.DI)           │
├─────────────────────────────────────────────────────────────┤
│  Crypto Plugins (Conditional)                                │
│  ├─ Default (.NET Crypto, BouncyCastle)        [ALL]        │
│  ├─ GOST (CryptoPro, OpenSSL-GOST, PKCS#11)    [RUSSIA]     │
│  ├─ eIDAS (TSP Client, Local Signer)           [EU]         │
│  └─ SM (GmSSL, SM Remote CSP)                  [CHINA]      │
├─────────────────────────────────────────────────────────────┤
│  Backend Integration                                         │
│  ├─ Authority (OAuth2 + DPoP)                               │
│  ├─ Scanner, Concelier, Policy, ...                         │
│  └─ HTTP clients with retry policies                        │
└─────────────────────────────────────────────────────────────┘
```

---

## Build-time Plugin Selection

### Conditional Compilation Workflow

```mermaid
graph TD
    A[MSBuild Start] --> B{Check Build Flags}
    B -->|StellaOpsEnableGOST=true| C[Include GOST Plugin]
    B -->|StellaOpsEnableEIDAS=true| D[Include eIDAS Plugin]
    B -->|StellaOpsEnableSM=true| E[Include SM Plugin]
    B -->|No flags| F[Include Default Only]

    C --> G[Set STELLAOPS_ENABLE_GOST]
    D --> H[Set STELLAOPS_ENABLE_EIDAS]
    E --> I[Set STELLAOPS_ENABLE_SM]

    G --> J[Compile with Plugin]
    H --> J
    I --> J
    F --> J

    J --> K[Link Plugin Assembly]
    K --> L[Final Binary]
```

### Project Structure

```
src/Cli/
├── StellaOps.Cli/
│   ├── Program.cs                          # Entry point, DI setup
│   ├── Commands/
│   │   ├── CommandFactory.cs               # Command routing
│   │   ├── Crypto/CryptoCommandGroup.cs    # Crypto commands
│   │   ├── Admin/AdminCommandGroup.cs      # Admin commands
│   │   └── ...
│   └── StellaOps.Cli.csproj                # Conditional <ProjectReference>
│
├── StellaOps.Cli.Crypto/
│   ├── ICryptoProvider.cs                  # Plugin interface
│   ├── ICryptoProviderDiagnostics.cs       # Diagnostics interface
│   └── Models/                             # Shared models
│
├── StellaOps.Cli.Crypto.Default/           # Always included
│   ├── DotNetCryptoProvider.cs             # .NET crypto
│   ├── BouncyCastleCryptoProvider.cs       # BouncyCastle
│   └── ServiceCollectionExtensions.cs      # DI registration
│
├── StellaOps.Cli.Crypto.Gost/              # Conditional (Russia)
│   ├── GostCryptoProvider.cs               # GOST implementation
│   ├── CryptoProAdapter.cs                 # CryptoPro CSP adapter
│   ├── OpenSslGostAdapter.cs               # OpenSSL-GOST adapter
│   └── ServiceCollectionExtensions.cs
│
├── StellaOps.Cli.Crypto.Eidas/             # Conditional (EU)
│   ├── EidasCryptoProvider.cs              # eIDAS implementation
│   ├── TspClientAdapter.cs                 # TSP remote signing
│   └── ServiceCollectionExtensions.cs
│
└── StellaOps.Cli.Crypto.Sm/                # Conditional (China)
    ├── SmCryptoProvider.cs                 # SM implementation
    ├── GmSslAdapter.cs                     # GmSSL adapter
    └── ServiceCollectionExtensions.cs
```

### StellaOps.Cli.csproj (Conditional References)

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>

  <!-- Always include default crypto -->
  <ItemGroup>
    <ProjectReference Include="..\StellaOps.Cli.Crypto\StellaOps.Cli.Crypto.csproj" />
    <ProjectReference Include="..\StellaOps.Cli.Crypto.Default\StellaOps.Cli.Crypto.Default.csproj" />
  </ItemGroup>

  <!-- GOST plugin (Russia distribution) -->
  <ItemGroup Condition="'$(StellaOpsEnableGOST)' == 'true'">
    <ProjectReference Include="..\StellaOps.Cli.Crypto.Gost\StellaOps.Cli.Crypto.Gost.csproj" />
    <DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_GOST</DefineConstants>
  </ItemGroup>

  <!-- eIDAS plugin (EU distribution) -->
  <ItemGroup Condition="'$(StellaOpsEnableEIDAS)' == 'true'">
    <ProjectReference Include="..\StellaOps.Cli.Crypto.Eidas\StellaOps.Cli.Crypto.Eidas.csproj" />
    <DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_EIDAS</DefineConstants>
  </ItemGroup>

  <!-- SM plugin (China distribution) -->
  <ItemGroup Condition="'$(StellaOpsEnableSM)' == 'true'">
    <ProjectReference Include="..\StellaOps.Cli.Crypto.Sm\StellaOps.Cli.Crypto.Sm.csproj" />
    <DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_SM</DefineConstants>
  </ItemGroup>
</Project>
```

### Build Commands

```bash
# International distribution (default, no flags)
dotnet publish src/Cli/StellaOps.Cli --configuration Release --runtime linux-x64

# Russia distribution (GOST enabled)
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  -p:StellaOpsEnableGOST=true

# EU distribution (eIDAS enabled)
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  -p:StellaOpsEnableEIDAS=true

# China distribution (SM enabled)
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  -p:StellaOpsEnableSM=true
```

---

## Runtime Plugin Discovery

### Program.cs - DI Registration

```csharp
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using StellaOps.Cli.Crypto;
using StellaOps.Cli.Crypto.Default;

#if STELLAOPS_ENABLE_GOST
using StellaOps.Cli.Crypto.Gost;
#endif

#if STELLAOPS_ENABLE_EIDAS
using StellaOps.Cli.Crypto.Eidas;
#endif

#if STELLAOPS_ENABLE_SM
using StellaOps.Cli.Crypto.Sm;
#endif

namespace StellaOps.Cli;

public class Program
{
    public static async Task<int> Main(string[] args)
    {
        // Build configuration
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json", optional: true)
            .AddYamlFile("appsettings.yaml", optional: true)
            .AddYamlFile(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".stellaops", "config.yaml"), optional: true)
            .AddEnvironmentVariables("STELLAOPS_")
            .Build();

        // Setup DI container
        var services = new ServiceCollection();

        // Register configuration
        services.AddSingleton<IConfiguration>(configuration);

        // Register HTTP clients
        services.AddHttpClient("StellaOpsBackend", client =>
        {
            var baseUrl = configuration["StellaOps:Backend:BaseUrl"];
            if (!string.IsNullOrEmpty(baseUrl))
                client.BaseAddress = new Uri(baseUrl);
        });

        // Register default crypto providers (always available)
        services.AddDefaultCryptoProviders(configuration);

        // Register regional crypto providers (conditional compilation)
#if STELLAOPS_ENABLE_GOST
        services.AddGostCryptoProviders(configuration);
#endif

#if STELLAOPS_ENABLE_EIDAS
        services.AddEidasCryptoProviders(configuration);
#endif

#if STELLAOPS_ENABLE_SM
        services.AddSmCryptoProviders(configuration);
#endif

        // Build service provider
        var serviceProvider = services.BuildServiceProvider();

        // Create root command and run
        var rootCommand = CommandFactory.CreateRootCommand(serviceProvider);
        return await rootCommand.InvokeAsync(args);
    }
}
```

### Plugin Discovery Flow

```mermaid
sequenceDiagram
    participant Build as MSBuild
    participant CLI as stella CLI
    participant DI as DI Container
    participant Plugin as Crypto Plugin
    participant User as User Command

    Build->>Build: Check StellaOpsEnableGOST=true
    Build->>Build: Include GOST plugin <ProjectReference>
    Build->>Build: Set DefineConstants=STELLAOPS_ENABLE_GOST
    Build->>CLI: Compile with GOST plugin

    User->>CLI: stella crypto sign --provider gost
    CLI->>CLI: Program.cs startup
    CLI->>CLI: Check #if STELLAOPS_ENABLE_GOST
    CLI->>DI: services.AddGostCryptoProviders()
    DI->>Plugin: Register GostCryptoProvider as ICryptoProvider
    Plugin->>DI: Provider registered

    CLI->>DI: Resolve ICryptoProvider (name="gost")
    DI->>Plugin: Return GostCryptoProvider instance
    Plugin->>CLI: Execute sign operation
    CLI->>User: Signature created
```

---

## Plugin Interfaces

### ICryptoProvider

The core interface all crypto providers must implement:

```csharp
namespace StellaOps.Cli.Crypto;

public interface ICryptoProvider
{
    /// <summary>
    /// Unique provider name (e.g., "gost", "eidas", "sm")
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Supported algorithms (e.g., "GOST12-256", "ECDSA-P256")
    /// </summary>
    string[] SupportedAlgorithms { get; }

    /// <summary>
    /// Sign data with specified algorithm and key
    /// </summary>
    Task<byte[]> SignAsync(
        byte[] data,
        string algorithm,
        CryptoKeyReference keyRef,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Verify signature
    /// </summary>
    Task<bool> VerifyAsync(
        byte[] data,
        byte[] signature,
        string algorithm,
        CryptoKeyReference keyRef,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// List available keys
    /// </summary>
    Task<IReadOnlyList<CryptoKeyInfo>> ListKeysAsync(
        CancellationToken cancellationToken = default);
}
```

### ICryptoProviderDiagnostics

Optional interface for provider diagnostics:

```csharp
namespace StellaOps.Cli.Crypto;

public interface ICryptoProviderDiagnostics
{
    /// <summary>
    /// Run provider self-test
    /// </summary>
    Task<ProviderHealthCheck> HealthCheckAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Get provider version and capabilities
    /// </summary>
    ProviderInfo GetInfo();
}

public sealed record ProviderHealthCheck
{
    public required string ProviderName { get; init; }
    public required bool IsHealthy { get; init; }
    public required string[] Checks { get; init; }
    public string? ErrorMessage { get; init; }
}

public sealed record ProviderInfo
{
    public required string Name { get; init; }
    public required string Version { get; init; }
    public required string[] Capabilities { get; init; }
    public required string[] SupportedAlgorithms { get; init; }
}
```

### CryptoKeyReference

Represents a reference to a cryptographic key:

```csharp
namespace StellaOps.Cli.Crypto;

public sealed record CryptoKeyReference
{
    /// <summary>
    /// Key identifier (e.g., "prod-key-2024", file path, HSM slot)
    /// </summary>
    public required string KeyId { get; init; }

    /// <summary>
    /// Key source: "file", "hsm", "kms", "csp"
    /// </summary>
    public required string Source { get; init; }

    /// <summary>
    /// Additional parameters (e.g., HSM PIN, KMS region)
    /// </summary>
    public IReadOnlyDictionary<string, string>? Parameters { get; init; }
}
```

---

## Configuration

### Profile-based Provider Selection

```yaml
StellaOps:
  Crypto:
    # Default provider (when --provider not specified)
    DefaultProvider: "default"

    # Crypto profiles for easy switching
    Profiles:
      - name: "default-signing"
        provider: "default"
        algorithm: "ECDSA-P256"
        keyId: "default-key"

      - name: "gost-signing"
        provider: "gost"
        algorithm: "GOST12-256"
        keyId: "gost-key-2024"

      - name: "eidas-qes"
        provider: "eidas"
        algorithm: "ECDSA-P256-QES"
        keyId: "eidas-qes-key"

    # Provider-specific configuration
    Providers:
      Gost:
        CryptoProCsp:
          Enabled: true
          ContainerName: "StellaOps-GOST-2024"

        OpenSslGost:
          Enabled: false
          EnginePath: "/usr/lib/engines/gost.so"

      Eidas:
        TspClient:
          Enabled: true
          TspUrl: "https://tsp.example.eu/api/v1/sign"
          ApiKey: "${EIDAS_TSP_API_KEY}"

      Sm:
        GmSsl:
          Enabled: true
          LibraryPath: "/usr/lib/libgmssl.so"
```

### Usage with Profiles

```bash
# Use default profile
stella crypto sign --file document.pdf

# Use specific profile
stella crypto sign --profile gost-signing --file document.pdf

# Override provider explicitly
stella crypto sign --provider gost --algorithm GOST12-256 --key-id key1 --file document.pdf
```

---

## Distribution Matrix

| Distribution | Default | GOST | eIDAS | SM |
|--------------|---------|------|-------|-----|
| **stella-international** | ✅ | ❌ | ❌ | ❌ |
| **stella-russia** | ✅ | ✅ | ❌ | ❌ |
| **stella-eu** | ✅ | ❌ | ✅ | ❌ |
| **stella-china** | ✅ | ❌ | ❌ | ✅ |

**Verification:**
```bash
# Check available providers
stella crypto providers

# Output (International):
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)

# Output (Russia):
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - gost (GOST R 34.10-2012, GOST R 34.11-2012)
```

---

## Creating Custom Plugins

### 1. Create Plugin Project

```bash
dotnet new classlib -n StellaOps.Cli.Crypto.MyCustom
cd StellaOps.Cli.Crypto.MyCustom

# Add reference to interface project
dotnet add reference ../StellaOps.Cli.Crypto/StellaOps.Cli.Crypto.csproj
```

### 2. Implement ICryptoProvider

```csharp
using StellaOps.Cli.Crypto;

namespace StellaOps.Cli.Crypto.MyCustom;

public class MyCustomCryptoProvider : ICryptoProvider, ICryptoProviderDiagnostics
{
    private readonly MyCustomCryptoOptions _options;

    public MyCustomCryptoProvider(IOptions<MyCustomCryptoOptions> options)
    {
        _options = options.Value;
    }

    public string Name => "mycustom";

    public string[] SupportedAlgorithms => new[] { "MYCUSTOM-ALG1", "MYCUSTOM-ALG2" };

    public async Task<byte[]> SignAsync(
        byte[] data,
        string algorithm,
        CryptoKeyReference keyRef,
        CancellationToken cancellationToken = default)
    {
        // Implementation
        throw new NotImplementedException();
    }

    public async Task<bool> VerifyAsync(
        byte[] data,
        byte[] signature,
        string algorithm,
        CryptoKeyReference keyRef,
        CancellationToken cancellationToken = default)
    {
        // Implementation
        throw new NotImplementedException();
    }

    public async Task<IReadOnlyList<CryptoKeyInfo>> ListKeysAsync(
        CancellationToken cancellationToken = default)
    {
        // Implementation
        throw new NotImplementedException();
    }

    public async Task<ProviderHealthCheck> HealthCheckAsync(
        CancellationToken cancellationToken = default)
    {
        return new ProviderHealthCheck
        {
            ProviderName = Name,
            IsHealthy = true,
            Checks = new[] { "Library loaded", "Keys accessible" }
        };
    }

    public ProviderInfo GetInfo()
    {
        return new ProviderInfo
        {
            Name = Name,
            Version = "1.0.0",
            Capabilities = new[] { "sign", "verify" },
            SupportedAlgorithms = SupportedAlgorithms
        };
    }
}
```

### 3. Create DI Extension

```csharp
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace StellaOps.Cli.Crypto.MyCustom;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyCustomCryptoProviders(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // Register provider
        services.AddSingleton<ICryptoProvider, MyCustomCryptoProvider>();

        // Bind configuration
        services.Configure<MyCustomCryptoOptions>(
            configuration.GetSection("StellaOps:Crypto:Providers:MyCustom"));

        return services;
    }
}
```

### 4. Update StellaOps.Cli.csproj

```xml
<!-- MyCustom plugin (custom distribution) -->
<ItemGroup Condition="'$(StellaOpsEnableMyCustom)' == 'true'">
  <ProjectReference Include="..\StellaOps.Cli.Crypto.MyCustom\StellaOps.Cli.Crypto.MyCustom.csproj" />
  <DefineConstants>$(DefineConstants);STELLAOPS_ENABLE_MYCUSTOM</DefineConstants>
</ItemGroup>
```

### 5. Update Program.cs

```csharp
#if STELLAOPS_ENABLE_MYCUSTOM
using StellaOps.Cli.Crypto.MyCustom;
#endif

// In Main():
#if STELLAOPS_ENABLE_MYCUSTOM
services.AddMyCustomCryptoProviders(configuration);
#endif
```

### 6. Build Custom Distribution

```bash
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  -p:StellaOpsEnableMyCustom=true
```

---

## Command Routing

### System.CommandLine 2.0 Integration

```csharp
// CommandFactory.cs
using System.CommandLine;

public static class CommandFactory
{
    public static Command CreateRootCommand(IServiceProvider services)
    {
        var root = new Command("stella", "StellaOps unified CLI");

        // Add command groups
        root.Add(BuildScanCommand(services));
        root.Add(BuildCryptoCommand(services));
        root.Add(BuildAdminCommand(services));
        root.Add(BuildAuthCommand(services));
        // ... more commands

        return root;
    }

    private static Command BuildCryptoCommand(IServiceProvider services)
    {
        var crypto = new Command("crypto", "Cryptographic operations");

        // crypto providers
        var providers = new Command("providers", "List available crypto providers");
        providers.SetAction(async (parseResult, ct) =>
        {
            var cryptoProviders = services.GetServices<ICryptoProvider>();
            foreach (var provider in cryptoProviders)
            {
                Console.WriteLine($"- {provider.Name}: {string.Join(", ", provider.SupportedAlgorithms)}");
            }
            return 0;
        });
        crypto.Add(providers);

        // crypto sign
        var sign = new Command("sign", "Sign file");
        // ... add options and handler
        crypto.Add(sign);

        return crypto;
    }
}
```

---

## Testing

### Unit Tests

```csharp
using StellaOps.Cli.Crypto;
using StellaOps.Cli.Crypto.Gost;
using Xunit;

public class GostCryptoProviderTests
{
    [Fact]
    public void Name_ReturnsGost()
    {
        var provider = new GostCryptoProvider(Options.Create(new GostCryptoOptions()));
        Assert.Equal("gost", provider.Name);
    }

    [Fact]
    public void SupportedAlgorithms_IncludesGost12_256()
    {
        var provider = new GostCryptoProvider(Options.Create(new GostCryptoOptions()));
        Assert.Contains("GOST12-256", provider.SupportedAlgorithms);
    }

    [Fact]
    public async Task SignAsync_ProducesSignature()
    {
        var provider = new GostCryptoProvider(Options.Create(new GostCryptoOptions()));
        var data = "test"u8.ToArray();
        var keyRef = new CryptoKeyReference { KeyId = "test-key", Source = "file" };

        var signature = await provider.SignAsync(data, "GOST12-256", keyRef);

        Assert.NotNull(signature);
        Assert.NotEmpty(signature);
    }
}
```

### Integration Tests

```csharp
using Microsoft.Extensions.DependencyInjection;
using Xunit;

public class CryptoPluginIntegrationTests
{
    [Fact]
    public void ServiceProvider_ResolvesAllProviders()
    {
        var services = new ServiceCollection();
        var configuration = new ConfigurationBuilder().Build();

        services.AddDefaultCryptoProviders(configuration);
#if STELLAOPS_ENABLE_GOST
        services.AddGostCryptoProviders(configuration);
#endif

        var serviceProvider = services.BuildServiceProvider();
        var providers = serviceProvider.GetServices<ICryptoProvider>().ToList();

        Assert.NotEmpty(providers);
        Assert.Contains(providers, p => p.Name == "default");
#if STELLAOPS_ENABLE_GOST
        Assert.Contains(providers, p => p.Name == "gost");
#endif
    }
}
```

---

## Packaging

### NuGet Package Structure

```
StellaOps.Cli (metapackage)
├── StellaOps.Cli.Crypto (interfaces)
├── StellaOps.Cli.Crypto.Default (always included)
├── StellaOps.Cli.Crypto.Gost (optional)
├── StellaOps.Cli.Crypto.Eidas (optional)
└── StellaOps.Cli.Crypto.Sm (optional)
```

### Distribution Artifacts

```
releases/
├── stella-international-linux-x64.tar.gz
├── stella-russia-linux-x64.tar.gz
├── stella-eu-linux-x64.tar.gz
└── stella-china-linux-x64.tar.gz
```

Each artifact contains only the authorized crypto providers for that region.

---

## See Also

- [Command Reference](command-reference.md) - Complete command documentation
- [Crypto Plugin Development](crypto-plugins.md) - Detailed plugin development guide
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
- [Distribution Matrix](distribution-matrix.md) - Build and distribution guide
- [Troubleshooting](troubleshooting.md) - Common plugin issues