135 lines
5.0 KiB
C#
135 lines
5.0 KiB
C#
// <copyright file="IEvidencePackService.cs" company="StellaOps">
|
|
// Copyright (c) StellaOps. Licensed under the BUSL-1.1.
|
|
// </copyright>
|
|
|
|
using StellaOps.Evidence.Pack.Models;
|
|
|
|
namespace StellaOps.Evidence.Pack;
|
|
|
|
/// <summary>
|
|
/// Service for creating, signing, and managing evidence packs.
|
|
/// Sprint: SPRINT_20260109_011_005 Task: EVPK-002
|
|
/// </summary>
|
|
public interface IEvidencePackService
|
|
{
|
|
/// <summary>
|
|
/// Creates an Evidence Pack from grounding validation results.
|
|
/// </summary>
|
|
/// <param name="claims">The claims to include in the pack.</param>
|
|
/// <param name="evidence">The evidence items supporting the claims.</param>
|
|
/// <param name="subject">The subject of the evidence pack.</param>
|
|
/// <param name="context">Optional context information.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The created evidence pack.</returns>
|
|
Task<EvidencePack> CreateAsync(
|
|
IEnumerable<EvidenceClaim> claims,
|
|
IEnumerable<EvidenceItem> evidence,
|
|
EvidenceSubject subject,
|
|
EvidencePackContext? context,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Creates an Evidence Pack from a Run's artifacts.
|
|
/// </summary>
|
|
/// <param name="runId">The run identifier.</param>
|
|
/// <param name="subject">The subject of the evidence pack.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The created evidence pack.</returns>
|
|
Task<EvidencePack> CreateFromRunAsync(
|
|
string runId,
|
|
EvidenceSubject subject,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Adds evidence items to an existing pack (creates new version).
|
|
/// </summary>
|
|
/// <param name="packId">The pack identifier.</param>
|
|
/// <param name="items">The evidence items to add.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The updated evidence pack (new version).</returns>
|
|
Task<EvidencePack> AddEvidenceAsync(
|
|
string packId,
|
|
IEnumerable<EvidenceItem> items,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Signs an Evidence Pack with DSSE.
|
|
/// </summary>
|
|
/// <param name="pack">The evidence pack to sign.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The signed evidence pack.</returns>
|
|
Task<SignedEvidencePack> SignAsync(
|
|
EvidencePack pack,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Verifies a signed Evidence Pack.
|
|
/// </summary>
|
|
/// <param name="signedPack">The signed pack to verify.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The verification result.</returns>
|
|
Task<EvidencePackVerificationResult> VerifyAsync(
|
|
SignedEvidencePack signedPack,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Exports a pack to various formats.
|
|
/// </summary>
|
|
/// <param name="packId">The pack identifier.</param>
|
|
/// <param name="format">The export format.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The exported pack.</returns>
|
|
Task<EvidencePackExport> ExportAsync(
|
|
string packId,
|
|
EvidencePackExportFormat format,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Gets a pack by ID.
|
|
/// </summary>
|
|
/// <param name="tenantId">The tenant identifier.</param>
|
|
/// <param name="packId">The pack identifier.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The evidence pack, or null if not found.</returns>
|
|
Task<EvidencePack?> GetAsync(
|
|
string tenantId,
|
|
string packId,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Lists evidence packs for a tenant.
|
|
/// </summary>
|
|
/// <param name="tenantId">The tenant identifier.</param>
|
|
/// <param name="query">Optional query parameters.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The list of evidence packs.</returns>
|
|
Task<IReadOnlyList<EvidencePack>> ListAsync(
|
|
string tenantId,
|
|
EvidencePackQuery? query,
|
|
CancellationToken cancellationToken);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Query parameters for listing evidence packs.
|
|
/// </summary>
|
|
public sealed record EvidencePackQuery
|
|
{
|
|
/// <summary>Gets or sets the subject CVE ID filter.</summary>
|
|
public string? CveId { get; init; }
|
|
|
|
/// <summary>Gets or sets the subject component filter.</summary>
|
|
public string? Component { get; init; }
|
|
|
|
/// <summary>Gets or sets the associated run ID filter.</summary>
|
|
public string? RunId { get; init; }
|
|
|
|
/// <summary>Gets or sets the creation time filter (packs after this time).</summary>
|
|
public DateTimeOffset? Since { get; init; }
|
|
|
|
/// <summary>Gets or sets the maximum number of results.</summary>
|
|
public int Limit { get; init; } = 50;
|
|
|
|
/// <summary>Gets or sets the pagination cursor.</summary>
|
|
public string? Cursor { get; init; }
|
|
}
|