git.stella-ops.org/docs/modules/provenance/architecture.md

# component_architecture_provenance.md - **Stella Ops Provenance** (2025Q4)

> Provenance attestation library for SLSA/DSSE compliance.

> **Scope.** Library architecture for **Provenance**: shared libraries and tooling for generating, signing, and verifying provenance attestations (DSSE/SLSA). Used by evidence bundles, exports, and timeline verification flows.

---

## 0) Mission & boundaries

**Mission.** Provide **deterministic, verifiable provenance attestations** for all StellaOps artifacts. Enable SLSA compliance through DSSE statement generation, Merkle tree construction, and cryptographic verification.

**Boundaries.**

* Provenance is a **library**, not a standalone service.
* Provenance **does not** store attestations. Storage is handled by Attestor and EvidenceLocker.
* Provenance **does not** hold signing keys. Key management is delegated to Signer/KMS.
* All attestation outputs are **deterministic** with canonical JSON serialization.

---

## 1) Solution & project layout

```
src/Provenance/
 ├─ StellaOps.Provenance.Attestation/    # Core attestation library
 │   ├─ AGENTS.md                        # Guild charter
 │   ├─ PromotionAttestation.cs          # Promotion statement builder
 │   ├─ BuildModels.cs                   # SLSA build predicate models
 │   ├─ Signers.cs                       # Signer abstractions
 │   ├─ Verification.cs                  # Verification harness
 │   └─ Hex.cs                           # Hex encoding utilities
 │
 ├─ StellaOps.Provenance.Attestation.Tool/  # CLI tool for attestation
 │   ├─ Program.cs
 │   └─ README.md
 │
 └─ __Tests/
     └─ StellaOps.Provenance.Attestation.Tests/
         ├─ PromotionAttestationBuilderTests.cs
         ├─ VerificationTests.cs
         ├─ SignersTests.cs
         ├─ MerkleTreeTests.cs
         └─ RotatingSignerTests.cs
```

---

## 2) External dependencies

* **Signer** - Cryptographic signing operations
* **Cryptography** - Hash computation, signature algorithms
* **EvidenceLocker** - Consumes attestations for storage
* **ExportCenter** - Attaches attestations to export bundles
* **.NET 10** - Runtime target

---

## 3) Contracts & data model

### 3.1 DSSE Statement

Dead Simple Signing Envelope (DSSE) format:

```json
{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "<base64-encoded-statement>",
  "signatures": [
    {
      "keyid": "sha256:abc123...",
      "sig": "<base64-signature>"
    }
  ]
}
```

### 3.2 SLSA Provenance Predicate

```json
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "pkg:oci/scanner@sha256:abc123",
      "digest": { "sha256": "abc123..." }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://stellaops.dev/build/v1",
      "externalParameters": {},
      "internalParameters": {},
      "resolvedDependencies": []
    },
    "runDetails": {
      "builder": {
        "id": "https://stellaops.dev/builders/scanner"
      },
      "metadata": {
        "invocationId": "build-2025-01-15-abc123",
        "startedOn": "2025-01-15T10:30:00Z",
        "finishedOn": "2025-01-15T10:35:00Z"
      }
    }
  }
}
```

### 3.3 Promotion Attestation

For artifact promotion across environments:

```csharp
public sealed class PromotionAttestation
{
    public required string ArtifactDigest { get; init; }
    public required string SourceEnvironment { get; init; }
    public required string TargetEnvironment { get; init; }
    public required DateTimeOffset PromotedAt { get; init; }
    public required string ApprovedBy { get; init; }
    public required IReadOnlyList<string> PolicyDigests { get; init; }
    public string? MerkleRoot { get; init; }
}
```

---

## 4) Core Components

### 4.1 Signer Abstractions

```csharp
public interface IAttestationSigner
{
    string KeyId { get; }
    string Algorithm { get; }

    Task<byte[]> SignAsync(
        ReadOnlyMemory<byte> payload,
        CancellationToken ct);
}

public interface IRotatingSigner : IAttestationSigner
{
    DateTimeOffset KeyNotBefore { get; }
    DateTimeOffset KeyNotAfter { get; }
    Task<IAttestationSigner> GetCurrentSignerAsync(CancellationToken ct);
}
```

### 4.2 Verification Harness

```csharp
public interface IAttestationVerifier
{
    Task<VerificationResult> VerifyAsync(
        DsseEnvelope envelope,
        VerificationOptions options,
        CancellationToken ct);
}

public sealed record VerificationResult
{
    public required bool IsValid { get; init; }
    public required string KeyId { get; init; }
    public DateTimeOffset? SignedAt { get; init; }
    public IReadOnlyList<string>? Warnings { get; init; }
    public string? ErrorMessage { get; init; }
}
```

### 4.3 Merkle Tree Utilities

For evidence chain verification:

```csharp
public static class MerkleTree
{
    public static string ComputeRoot(IEnumerable<string> leaves);
    public static IReadOnlyList<string> ComputePath(
        IReadOnlyList<string> leaves,
        int leafIndex);
    public static bool VerifyPath(
        string leaf,
        IReadOnlyList<string> path,
        string root);
}
```

---

## 5) CLI Tool

`StellaOps.Provenance.Attestation.Tool` provides CLI commands:

```bash
# Generate provenance attestation
provenance-tool generate \
  --subject "pkg:oci/scanner@sha256:abc123" \
  --builder "stellaops/ci" \
  --output attestation.json

# Sign attestation
provenance-tool sign \
  --input attestation.json \
  --key-id "kms://keys/signing-key" \
  --output attestation.dsse.json

# Verify attestation
provenance-tool verify \
  --input attestation.dsse.json \
  --trust-root trust-bundle.json

# Generate promotion attestation
provenance-tool promote \
  --artifact "sha256:abc123" \
  --from staging \
  --to production \
  --approver "user@example.com"
```

---

## 6) Security & compliance

* **SLSA L3 compliance**: Build provenance with hermetic builds
* **Key rotation**: RotatingSigner supports key rotation with overlap
* **Determinism**: Canonical JSON ensures reproducible digests
* **Offline verification**: Trust bundles for air-gapped verification
* **Threat model**: Reviewed before each release

---

## 7) Performance targets

* **Statement generation**: < 10ms for typical attestation
* **Signing**: Depends on KMS (target < 100ms for HSM)
* **Verification**: < 50ms for single signature
* **Merkle root**: < 100ms for 10,000 leaves

---

## 8) Testing matrix

* **Serialization tests**: Deterministic JSON output across runs
* **Signing tests**: Round-trip sign/verify
* **Merkle tests**: Path generation and verification
* **Rotation tests**: Key rotation with overlap handling
* **Integration tests**: Full attestation flow with mock KMS

---

## 9) Sample Artifacts

Samples committed under `samples/provenance/`:

```
samples/provenance/
  ├─ slsa-provenance-v1.json       # Sample SLSA statement
  ├─ promotion-attestation.json    # Sample promotion
  ├─ trust-bundle.json             # Sample trust root
  └─ verify-example.sh             # Verification script
```

---

## 10) Integration Points

### 10.1 EvidenceLocker

Evidence bundles include attestations:

```json
{
  "bundleId": "eb-2025-01-15-abc123",
  "attestations": [
    {
      "type": "slsa-provenance",
      "dsse": { /* DSSE envelope */ }
    }
  ]
}
```

### 10.2 ExportCenter

Exports attach attestations to manifests:

```json
{
  "exportId": "export-abc123",
  "manifest": { /* export manifest */ },
  "attestation": { /* DSSE envelope */ }
}
```

### 10.3 CLI

Scanner and other tools generate attestations:

```bash
stella scan image:tag --attest --output sbom.cdx.json
# Produces sbom.cdx.json + sbom.cdx.json.dsse
```

---

## Related Documentation

* Attestor architecture: `../attestor/architecture.md`
* Signer architecture: `../signer/architecture.md`
* EvidenceLocker: `../evidence-locker/architecture.md`
* SLSA specification: https://slsa.dev/provenance/v1
* DSSE specification: https://github.com/secure-systems-lab/dsse