git.stella-ops.org/docs/cli/distribution-matrix.md

stella CLI - Build and Distribution Matrix

Sprint: SPRINT_4100_0006_0006 - CLI Documentation Overhaul

Overview

StellaOps CLI is distributed in four regional variants to comply with export control regulations and cryptographic standards. Each distribution includes different cryptographic plugins based on regional requirements.

Key Principles:

1. Build-time Selection: Crypto plugins are conditionally compiled based on build flags
2. Export Compliance: Each distribution complies with export control laws
3. Deterministic Builds: Same source + flags = same binary (reproducible builds)
4. Validation: Automated validation ensures correct plugin inclusion

---

Distribution Matrix

Distribution	Crypto Plugins	Build Flag	Target Audience	Export Restrictions
stella-international	Default (.NET, BouncyCastle)	None	Global (unrestricted)	✅ No restrictions
stella-russia	Default + GOST	StellaOpsEnableGOST=true	Russia, CIS states	⚠️ Russia/CIS only
stella-eu	Default + eIDAS	StellaOpsEnableEIDAS=true	European Union	⚠️ EU/EEA only
stella-china	Default + SM	StellaOpsEnableSM=true	China	⚠️ China only

---

Crypto Provider Matrix

Provider	International	Russia	EU	China
.NET Crypto (RSA, ECDSA, EdDSA)	✅	✅	✅	✅
BouncyCastle (Extended algorithms)	✅	✅	✅	✅
GOST (R 34.10-2012, R 34.11-2012)	❌	✅	❌	❌
eIDAS (QES, AES, AdES)	❌	❌	✅	❌
SM (SM2, SM3, SM4)	❌	❌	❌	✅

---

Build Instructions

Prerequisites

• .NET 10 SDK
• Git
• Docker (for Linux builds on Windows/macOS)

Build Environment Setup

# Clone repository
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org
cd git.stella-ops.org

# Verify .NET SDK
dotnet --version
# Expected: 10.0.0 or later

---

Building Regional Distributions

1. International Distribution (Default)

Includes: Default crypto providers only (no regional algorithms)

Build Command:

dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output dist/stella-international-linux-x64

Supported Platforms:

• linux-x64 - Linux x86_64
• linux-arm64 - Linux ARM64
• osx-x64 - macOS Intel
• osx-arm64 - macOS Apple Silicon
• win-x64 - Windows x64

Example (all platforms):

# Linux x64
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output dist/stella-international-linux-x64

# Linux ARM64
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-arm64 \
  --self-contained true \
  --output dist/stella-international-linux-arm64

# macOS Intel
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime osx-x64 \
  --self-contained true \
  --output dist/stella-international-osx-x64

# macOS Apple Silicon
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime osx-arm64 \
  --self-contained true \
  --output dist/stella-international-osx-arm64

# Windows x64
dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime win-x64 \
  --self-contained true \
  --output dist/stella-international-win-x64

---

2. Russia Distribution (GOST)

Includes: Default + GOST crypto providers

Build Command:

dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableGOST=true \
  -p:DefineConstants="STELLAOPS_ENABLE_GOST" \
  --output dist/stella-russia-linux-x64

Important: The build flag StellaOpsEnableGOST=true conditionally includes GOST plugin projects, and DefineConstants enables #if STELLAOPS_ENABLE_GOST preprocessor directives.

Multi-platform Example:

#!/bin/bash
# build-russia.sh - Build all Russia distributions

set -e

RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

for runtime in "${RUNTIMES[@]}"; do
  echo "Building stella-russia for $runtime..."
  dotnet publish src/Cli/StellaOps.Cli \
    --configuration Release \
    --runtime "$runtime" \
    --self-contained true \
    -p:StellaOpsEnableGOST=true \
    -p:DefineConstants="STELLAOPS_ENABLE_GOST" \
    --output "dist/stella-russia-$runtime"
done

echo "All Russia distributions built successfully"

---

3. EU Distribution (eIDAS)

Includes: Default + eIDAS crypto providers

Build Command:

dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableEIDAS=true \
  -p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
  --output dist/stella-eu-linux-x64

Multi-platform Example:

#!/bin/bash
# build-eu.sh - Build all EU distributions

set -e

RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

for runtime in "${RUNTIMES[@]}"; do
  echo "Building stella-eu for $runtime..."
  dotnet publish src/Cli/StellaOps.Cli \
    --configuration Release \
    --runtime "$runtime" \
    --self-contained true \
    -p:StellaOpsEnableEIDAS=true \
    -p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
    --output "dist/stella-eu-$runtime"
done

echo "All EU distributions built successfully"

---

4. China Distribution (SM)

Includes: Default + SM crypto providers

Build Command:

dotnet publish src/Cli/StellaOps.Cli \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  -p:StellaOpsEnableSM=true \
  -p:DefineConstants="STELLAOPS_ENABLE_SM" \
  --output dist/stella-china-linux-x64

Multi-platform Example:

#!/bin/bash
# build-china.sh - Build all China distributions

set -e

RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

for runtime in "${RUNTIMES[@]}"; do
  echo "Building stella-china for $runtime..."
  dotnet publish src/Cli/StellaOps.Cli \
    --configuration Release \
    --runtime "$runtime" \
    --self-contained true \
    -p:StellaOpsEnableSM=true \
    -p:DefineConstants="STELLAOPS_ENABLE_SM" \
    --output "dist/stella-china-$runtime"
done

echo "All China distributions built successfully"

---

Build All Distributions

Automated build script:

#!/bin/bash
# build-all.sh - Build all distributions for all platforms

set -e

DISTRIBUTIONS=("international" "russia" "eu" "china")
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")

build_distribution() {
    local dist=$1
    local runtime=$2
    local flags=""

    case $dist in
        "russia")
            flags="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
            ;;
        "eu")
            flags="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
            ;;
        "china")
            flags="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
            ;;
    esac

    echo "Building stella-$dist for $runtime..."

    dotnet publish src/Cli/StellaOps.Cli \
        --configuration Release \
        --runtime "$runtime" \
        --self-contained true \
        $flags \
        --output "dist/stella-$dist-$runtime"

    # Create tarball (except Windows)
    if [[ ! $runtime =~ ^win ]]; then
        tar -czf "dist/stella-$dist-$runtime.tar.gz" -C "dist/stella-$dist-$runtime" .
        echo "✅ Created dist/stella-$dist-$runtime.tar.gz"
    else
        # Create zip for Windows
        (cd "dist/stella-$dist-$runtime" && zip -r "../stella-$dist-$runtime.zip" .)
        echo "✅ Created dist/stella-$dist-$runtime.zip"
    fi
}

for dist in "${DISTRIBUTIONS[@]}"; do
    for runtime in "${RUNTIMES[@]}"; do
        build_distribution "$dist" "$runtime"
    done
done

echo ""
echo "🎉 All distributions built successfully!"
echo "See dist/ directory for artifacts"

---

Distribution Validation

Automated Validation Script

#!/bin/bash
# validate-distribution.sh - Validate distribution has correct plugins

set -e

DISTRIBUTION=$1  # international, russia, eu, china
BINARY_PATH=$2

if [ -z "$DISTRIBUTION" ] || [ -z "$BINARY_PATH" ]; then
    echo "Usage: $0 <distribution> <binary-path>"
    echo "Example: $0 russia dist/stella-russia-linux-x64/stella"
    exit 1
fi

echo "Validating $DISTRIBUTION distribution: $BINARY_PATH"
echo ""

# Function to check for symbol in binary
has_symbol() {
    local symbol=$1
    if command -v objdump &> /dev/null; then
        objdump -p "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
    elif command -v nm &> /dev/null; then
        nm "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
    else
        # Fallback: check if binary contains string
        strings "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
    fi
}

# Validation rules
validate_international() {
    echo "Checking International distribution..."

    # Should NOT contain regional plugins
    if has_symbol "GostCryptoProvider" || \
       has_symbol "EidasCryptoProvider" || \
       has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: International distribution contains restricted plugins"
        return 1
    fi

    echo "✅ PASS: International distribution valid (no restricted plugins)"
    return 0
}

validate_russia() {
    echo "Checking Russia distribution..."

    # Should contain GOST
    if ! has_symbol "GostCryptoProvider"; then
        echo "❌ FAIL: Russia distribution missing GOST plugin"
        return 1
    fi

    # Should NOT contain eIDAS or SM
    if has_symbol "EidasCryptoProvider" || has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: Russia distribution contains non-GOST regional plugins"
        return 1
    fi

    echo "✅ PASS: Russia distribution valid (GOST included, no other regional plugins)"
    return 0
}

validate_eu() {
    echo "Checking EU distribution..."

    # Should contain eIDAS
    if ! has_symbol "EidasCryptoProvider"; then
        echo "❌ FAIL: EU distribution missing eIDAS plugin"
        return 1
    fi

    # Should NOT contain GOST or SM
    if has_symbol "GostCryptoProvider" || has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: EU distribution contains non-eIDAS regional plugins"
        return 1
    fi

    echo "✅ PASS: EU distribution valid (eIDAS included, no other regional plugins)"
    return 0
}

validate_china() {
    echo "Checking China distribution..."

    # Should contain SM
    if ! has_symbol "SmCryptoProvider"; then
        echo "❌ FAIL: China distribution missing SM plugin"
        return 1
    fi

    # Should NOT contain GOST or eIDAS
    if has_symbol "GostCryptoProvider" || has_symbol "EidasCryptoProvider"; then
        echo "❌ FAIL: China distribution contains non-SM regional plugins"
        return 1
    fi

    echo "✅ PASS: China distribution valid (SM included, no other regional plugins)"
    return 0
}

# Run validation
case $DISTRIBUTION in
    "international")
        validate_international
        ;;
    "russia")
        validate_russia
        ;;
    "eu")
        validate_eu
        ;;
    "china")
        validate_china
        ;;
    *)
        echo "❌ ERROR: Unknown distribution '$DISTRIBUTION'"
        echo "Valid distributions: international, russia, eu, china"
        exit 1
        ;;
esac

exit $?

Usage:

# Validate Russia distribution
./validate-distribution.sh russia dist/stella-russia-linux-x64/stella

# Output:
# Validating russia distribution: dist/stella-russia-linux-x64/stella
#
# Checking Russia distribution...
# ✅ PASS: Russia distribution valid (GOST included, no other regional plugins)

---

Runtime Validation

Verify correct plugins are available at runtime:

# International distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)

# Russia distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - gost (GOST R 34.10-2012, GOST R 34.11-2012)

# EU distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - eidas (QES, AES, AdES)

# China distribution
./stella crypto providers
# Expected output:
# Available Crypto Providers:
# - default (.NET Crypto, BouncyCastle)
# - sm (SM2, SM3, SM4)

---

Packaging

Tarball Creation

#!/bin/bash
# package.sh - Create distribution tarballs

DIST=$1  # stella-russia-linux-x64
OUTPUT_DIR="dist"

cd "$OUTPUT_DIR/$DIST"

# Create tarball
tar -czf "../$DIST.tar.gz" .

echo "✅ Created $OUTPUT_DIR/$DIST.tar.gz"

Checksums

#!/bin/bash
# checksums.sh - Generate checksums for all distributions

cd dist

for tarball in *.tar.gz *.zip; do
    if [ -f "$tarball" ]; then
        sha256sum "$tarball" >> checksums.txt
    fi
done

echo "✅ Checksums written to dist/checksums.txt"
cat dist/checksums.txt

---

CI/CD Integration

GitHub Actions / Gitea Actions

name: Build and Release CLI

on:
  push:
    tags:
      - 'v*'

jobs:
  build-matrix:
    strategy:
      matrix:
        distribution: [international, russia, eu, china]
        runtime: [linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64]

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Build Distribution
        run: |
          FLAGS=""
          case "${{ matrix.distribution }}" in
            "russia")
              FLAGS="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
              ;;
            "eu")
              FLAGS="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
              ;;
            "china")
              FLAGS="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
              ;;
          esac

          dotnet publish src/Cli/StellaOps.Cli \
            --configuration Release \
            --runtime ${{ matrix.runtime }} \
            --self-contained true \
            $FLAGS \
            --output dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}

      - name: Validate Distribution
        run: |
          chmod +x scripts/validate-distribution.sh
          ./scripts/validate-distribution.sh \
            ${{ matrix.distribution }} \
            dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}/stella

      - name: Create Tarball
        if: ${{ !contains(matrix.runtime, 'win') }}
        run: |
          cd dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}
          tar -czf ../stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz .

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: stella-${{ matrix.distribution }}-${{ matrix.runtime }}
          path: dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz

---

Distribution Deployment

Release Structure

releases/
├── v2.1.0/
│   ├── stella-international-linux-x64.tar.gz
│   ├── stella-international-linux-arm64.tar.gz
│   ├── stella-international-osx-x64.tar.gz
│   ├── stella-international-osx-arm64.tar.gz
│   ├── stella-international-win-x64.zip
│   ├── stella-russia-linux-x64.tar.gz
│   ├── stella-russia-linux-arm64.tar.gz
│   ├── stella-russia-osx-x64.tar.gz
│   ├── stella-russia-osx-arm64.tar.gz
│   ├── stella-russia-win-x64.zip
│   ├── stella-eu-linux-x64.tar.gz
│   ├── stella-eu-linux-arm64.tar.gz
│   ├── stella-eu-osx-x64.tar.gz
│   ├── stella-eu-osx-arm64.tar.gz
│   ├── stella-eu-win-x64.zip
│   ├── stella-china-linux-x64.tar.gz
│   ├── stella-china-linux-arm64.tar.gz
│   ├── stella-china-osx-x64.tar.gz
│   ├── stella-china-osx-arm64.tar.gz
│   ├── stella-china-win-x64.zip
│   ├── checksums.txt
│   └── RELEASE_NOTES.md
└── latest -> v2.1.0

---

Download Links

Public Release Server:

https://releases.stella-ops.org/cli/
├── latest/
│   ├── stella-international-linux-x64.tar.gz
│   ├── stella-russia-linux-x64.tar.gz
│   ├── stella-eu-linux-x64.tar.gz
│   └── stella-china-linux-x64.tar.gz
├── v2.1.0/
├── v2.0.0/
└── checksums.txt

User Installation:

# International (unrestricted)
wget https://releases.stella-ops.org/cli/latest/stella-international-linux-x64.tar.gz

# Russia (GOST)
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz

# EU (eIDAS)
wget https://releases.stella-ops.org/cli/eu/latest/stella-eu-linux-x64.tar.gz

# China (SM)
wget https://releases.stella-ops.org/cli/china/latest/stella-china-linux-x64.tar.gz

---

Legal & Export Control

Export Control Statement

StellaOps CLI regional distributions contain cryptographic software subject to export control laws.

• stella-international: No export restrictions (standard commercial crypto)
• stella-russia: Authorized for Russia and CIS states only
• stella-eu: Authorized for EU/EEA member states only
• stella-china: Authorized for China only

Unauthorized export, re-export, or transfer may violate applicable laws. Users are responsible for compliance with export control regulations in their jurisdiction.

License Compliance

All distributions are licensed under AGPL-3.0-or-later, with regional plugins subject to additional vendor licenses (e.g., CryptoPro CSP requires commercial license).

---

See Also

• CLI Overview - Installation and quick start
• CLI Architecture - Plugin architecture
• Command Reference - Command usage
• Compliance Guide - Regional compliance requirements
• Crypto Plugins - Plugin development
• Troubleshooting - Build and validation issues