git.stella-ops.org/src/Scanner/StellaOps.Scanner.WebService/Contracts/RichGraphStatement.cs

// -----------------------------------------------------------------------------
// RichGraphStatement.cs
// Sprint: SPRINT_3801_0001_0002_richgraph_attestation
// Description: In-toto statement for RichGraph attestations.
// -----------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using System.Text.Json.Serialization;

namespace StellaOps.Scanner.WebService.Contracts;

/// <summary>
/// In-toto statement for RichGraph computation attestations.
/// Predicate type: stella.ops/richgraph@v1
/// </summary>
/// <remarks>
/// This statement attests that a RichGraph was computed from a specific
/// SBOM and call graph, producing a content-addressed graph digest.
/// </remarks>
public sealed record RichGraphStatement
{
    /// <summary>
    /// The statement type, always "https://in-toto.io/Statement/v1".
    /// </summary>
    [JsonPropertyName("_type")]
    public string Type => "https://in-toto.io/Statement/v1";

    /// <summary>
    /// The subjects this statement is about (scan + graph artifacts).
    /// </summary>
    [JsonPropertyName("subject")]
    public required IReadOnlyList<RichGraphSubject> Subject { get; init; }

    /// <summary>
    /// The predicate type URI.
    /// </summary>
    [JsonPropertyName("predicateType")]
    public string PredicateType => "stella.ops/richgraph@v1";

    /// <summary>
    /// The RichGraph predicate payload.
    /// </summary>
    [JsonPropertyName("predicate")]
    public required RichGraphPredicate Predicate { get; init; }
}

/// <summary>
/// Subject in a RichGraph statement.
/// </summary>
public sealed record RichGraphSubject
{
    /// <summary>
    /// The name or identifier of the subject (e.g., scan ID, graph ID).
    /// </summary>
    [JsonPropertyName("name")]
    public required string Name { get; init; }

    /// <summary>
    /// Digests of the subject in algorithm:hex format.
    /// </summary>
    [JsonPropertyName("digest")]
    public required IReadOnlyDictionary<string, string> Digest { get; init; }
}

/// <summary>
/// Predicate payload for RichGraph attestations.
/// </summary>
public sealed record RichGraphPredicate
{
    /// <summary>
    /// The RichGraph identifier.
    /// </summary>
    [JsonPropertyName("graph_id")]
    public required string GraphId { get; init; }

    /// <summary>
    /// Content-addressed digest of the RichGraph.
    /// </summary>
    [JsonPropertyName("graph_digest")]
    public required string GraphDigest { get; init; }

    /// <summary>
    /// Number of nodes in the graph.
    /// </summary>
    [JsonPropertyName("node_count")]
    public required int NodeCount { get; init; }

    /// <summary>
    /// Number of edges in the graph.
    /// </summary>
    [JsonPropertyName("edge_count")]
    public required int EdgeCount { get; init; }

    /// <summary>
    /// Number of root nodes (entrypoints) in the graph.
    /// </summary>
    [JsonPropertyName("root_count")]
    public required int RootCount { get; init; }

    /// <summary>
    /// Information about the analyzer that computed the graph.
    /// </summary>
    [JsonPropertyName("analyzer")]
    public required RichGraphAnalyzerInfo Analyzer { get; init; }

    /// <summary>
    /// When the graph was computed (UTC ISO 8601).
    /// </summary>
    [JsonPropertyName("computed_at")]
    public required DateTimeOffset ComputedAt { get; init; }

    /// <summary>
    /// When the graph attestation expires (UTC ISO 8601).
    /// </summary>
    [JsonPropertyName("expires_at")]
    public DateTimeOffset? ExpiresAt { get; init; }

    /// <summary>
    /// Reference to the source SBOM (digest).
    /// </summary>
    [JsonPropertyName("sbom_ref")]
    public string? SbomRef { get; init; }

    /// <summary>
    /// Reference to the source call graph (digest).
    /// </summary>
    [JsonPropertyName("callgraph_ref")]
    public string? CallgraphRef { get; init; }

    /// <summary>
    /// Language of the analyzed code.
    /// </summary>
    [JsonPropertyName("language")]
    public string? Language { get; init; }

    /// <summary>
    /// Schema version of the RichGraph.
    /// </summary>
    [JsonPropertyName("schema")]
    public string Schema { get; init; } = "richgraph-v1";
}

/// <summary>
/// Information about the analyzer that computed the RichGraph.
/// </summary>
public sealed record RichGraphAnalyzerInfo
{
    /// <summary>
    /// Name of the analyzer.
    /// </summary>
    [JsonPropertyName("name")]
    public required string Name { get; init; }

    /// <summary>
    /// Version of the analyzer.
    /// </summary>
    [JsonPropertyName("version")]
    public required string Version { get; init; }

    /// <summary>
    /// Configuration hash used for the analysis.
    /// </summary>
    [JsonPropertyName("config_hash")]
    public string? ConfigHash { get; init; }
}