git.stella-ops.org/src/Policy/StellaOps.Policy.Registry/Services/IPublishPipelineService.cs

using StellaOps.Policy.Registry.Contracts;

namespace StellaOps.Policy.Registry.Services;

/// <summary>
/// Service for publishing policy packs with signing and attestations.
/// Implements REGISTRY-API-27-007: Publish pipeline with signing/attestations.
/// </summary>
public interface IPublishPipelineService
{
    /// <summary>
    /// Publishes an approved policy pack.
    /// </summary>
    Task<PublishResult> PublishAsync(
        Guid tenantId,
        Guid packId,
        PublishPackRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the publication status of a policy pack.
    /// </summary>
    Task<PublicationStatus?> GetPublicationStatusAsync(
        Guid tenantId,
        Guid packId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the attestation for a published policy pack.
    /// </summary>
    Task<PolicyPackAttestation?> GetAttestationAsync(
        Guid tenantId,
        Guid packId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Verifies the signature and attestation of a published policy pack.
    /// </summary>
    Task<AttestationVerificationResult> VerifyAttestationAsync(
        Guid tenantId,
        Guid packId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Lists published policy packs for a tenant.
    /// </summary>
    Task<PublishedPackList> ListPublishedAsync(
        Guid tenantId,
        int pageSize = 20,
        string? pageToken = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Revokes a published policy pack.
    /// </summary>
    Task<RevokeResult> RevokeAsync(
        Guid tenantId,
        Guid packId,
        RevokePackRequest request,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Request to publish a policy pack.
/// </summary>
public sealed record PublishPackRequest
{
    public string? ApprovalId { get; init; }
    public string? PublishedBy { get; init; }
    public SigningOptions? SigningOptions { get; init; }
    public AttestationOptions? AttestationOptions { get; init; }
    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
}

/// <summary>
/// Signing options for policy pack publication.
/// </summary>
public sealed record SigningOptions
{
    public required string KeyId { get; init; }
    public SigningAlgorithm Algorithm { get; init; } = SigningAlgorithm.ECDSA_P256_SHA256;
    public bool IncludeTimestamp { get; init; } = true;
    public bool IncludeRekorEntry { get; init; }
}

/// <summary>
/// Attestation options for policy pack publication.
/// </summary>
public sealed record AttestationOptions
{
    public required string PredicateType { get; init; }
    public bool IncludeCompilationResult { get; init; } = true;
    public bool IncludeReviewHistory { get; init; } = true;
    public bool IncludeSimulationResults { get; init; }
    public IReadOnlyDictionary<string, object>? CustomClaims { get; init; }
}

/// <summary>
/// Supported signing algorithms.
/// </summary>
public enum SigningAlgorithm
{
    ECDSA_P256_SHA256,
    ECDSA_P384_SHA384,
    RSA_PKCS1_SHA256,
    RSA_PSS_SHA256,
    Ed25519
}

/// <summary>
/// Result of policy pack publication.
/// </summary>
public sealed record PublishResult
{
    public required bool Success { get; init; }
    public Guid? PackId { get; init; }
    public string? Digest { get; init; }
    public PublicationStatus? Status { get; init; }
    public PolicyPackAttestation? Attestation { get; init; }
    public string? Error { get; init; }
}

/// <summary>
/// Publication status of a policy pack.
/// </summary>
public sealed record PublicationStatus
{
    public required Guid PackId { get; init; }
    public required string PackVersion { get; init; }
    public required string Digest { get; init; }
    public required PublishState State { get; init; }
    public required DateTimeOffset PublishedAt { get; init; }
    public string? PublishedBy { get; init; }
    public DateTimeOffset? RevokedAt { get; init; }
    public string? RevokedBy { get; init; }
    public string? RevokeReason { get; init; }
    public string? SignatureKeyId { get; init; }
    public SigningAlgorithm? SignatureAlgorithm { get; init; }
    public string? RekorLogId { get; init; }
}

/// <summary>
/// Publication state.
/// </summary>
public enum PublishState
{
    Published,
    Revoked,
    Superseded
}

/// <summary>
/// Policy pack attestation following in-toto/DSSE format.
/// </summary>
public sealed record PolicyPackAttestation
{
    public required string PayloadType { get; init; }
    public required string Payload { get; init; }
    public required IReadOnlyList<AttestationSignature> Signatures { get; init; }
}

/// <summary>
/// Attestation signature.
/// </summary>
public sealed record AttestationSignature
{
    public required string KeyId { get; init; }
    public required string Signature { get; init; }
    public DateTimeOffset? Timestamp { get; init; }
    public string? RekorLogIndex { get; init; }
}

/// <summary>
/// Attestation payload in SLSA provenance format.
/// </summary>
public sealed record AttestationPayload
{
    public required string Type { get; init; }
    public required string PredicateType { get; init; }
    public required AttestationSubject Subject { get; init; }
    public required AttestationPredicate Predicate { get; init; }
}

/// <summary>
/// Attestation subject (the policy pack).
/// </summary>
public sealed record AttestationSubject
{
    public required string Name { get; init; }
    public required IReadOnlyDictionary<string, string> Digest { get; init; }
}

/// <summary>
/// Attestation predicate containing provenance metadata.
/// </summary>
public sealed record AttestationPredicate
{
    public required string BuildType { get; init; }
    public required AttestationBuilder Builder { get; init; }
    public DateTimeOffset? BuildStartedOn { get; init; }
    public DateTimeOffset? BuildFinishedOn { get; init; }
    public PolicyPackCompilationMetadata? Compilation { get; init; }
    public PolicyPackReviewMetadata? Review { get; init; }
    public IReadOnlyDictionary<string, object>? Metadata { get; init; }
}

/// <summary>
/// Attestation builder information.
/// </summary>
public sealed record AttestationBuilder
{
    public required string Id { get; init; }
    public string? Version { get; init; }
}

/// <summary>
/// Compilation metadata in attestation.
/// </summary>
public sealed record PolicyPackCompilationMetadata
{
    public required string Digest { get; init; }
    public required int RuleCount { get; init; }
    public DateTimeOffset? CompiledAt { get; init; }
    public IReadOnlyDictionary<string, int>? Statistics { get; init; }
}

/// <summary>
/// Review metadata in attestation.
/// </summary>
public sealed record PolicyPackReviewMetadata
{
    public required string ReviewId { get; init; }
    public required DateTimeOffset ApprovedAt { get; init; }
    public string? ApprovedBy { get; init; }
    public IReadOnlyList<string>? Reviewers { get; init; }
}

/// <summary>
/// Result of attestation verification.
/// </summary>
public sealed record AttestationVerificationResult
{
    public required bool Valid { get; init; }
    public IReadOnlyList<VerificationCheck>? Checks { get; init; }
    public IReadOnlyList<string>? Errors { get; init; }
    public IReadOnlyList<string>? Warnings { get; init; }
}

/// <summary>
/// Individual verification check result.
/// </summary>
public sealed record VerificationCheck
{
    public required string Name { get; init; }
    public required bool Passed { get; init; }
    public string? Details { get; init; }
}

/// <summary>
/// List of published policy packs.
/// </summary>
public sealed record PublishedPackList
{
    public required IReadOnlyList<PublicationStatus> Items { get; init; }
    public string? NextPageToken { get; init; }
    public int TotalCount { get; init; }
}

/// <summary>
/// Request to revoke a published policy pack.
/// </summary>
public sealed record RevokePackRequest
{
    public required string Reason { get; init; }
    public string? RevokedBy { get; init; }
}

/// <summary>
/// Result of policy pack revocation.
/// </summary>
public sealed record RevokeResult
{
    public required bool Success { get; init; }
    public PublicationStatus? Status { get; init; }
    public string? Error { get; init; }
}