sprints work

src/__Libraries/StellaOps.AdvisoryAI.Attestation/IAiAttestationService.cs

@@ -0,0 +1,173 @@
+// <copyright file="IAiAttestationService.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under the AGPL-3.0-or-later.
+// </copyright>
+
+using StellaOps.AdvisoryAI.Attestation.Models;
+
+namespace StellaOps.AdvisoryAI.Attestation;
+
+/// <summary>
+/// Service for creating and verifying AI attestations.
+/// Sprint: SPRINT_20260109_011_001 Task: AIAT-002
+/// </summary>
+public interface IAiAttestationService
+{
+    /// <summary>
+    /// Creates an attestation for an AI run.
+    /// </summary>
+    /// <param name="attestation">The attestation to create.</param>
+    /// <param name="sign">Whether to sign the attestation.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The created attestation with optional signature.</returns>
+    Task<AiAttestationResult> CreateRunAttestationAsync(
+        AiRunAttestation attestation,
+        bool sign = true,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Creates an attestation for a specific claim.
+    /// </summary>
+    /// <param name="attestation">The claim attestation to create.</param>
+    /// <param name="sign">Whether to sign the attestation.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The created attestation with optional signature.</returns>
+    Task<AiAttestationResult> CreateClaimAttestationAsync(
+        AiClaimAttestation attestation,
+        bool sign = true,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Verifies an AI run attestation.
+    /// </summary>
+    /// <param name="runId">The run ID to verify.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Verification result.</returns>
+    Task<AiAttestationVerificationResult> VerifyRunAttestationAsync(
+        string runId,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Verifies a claim attestation.
+    /// </summary>
+    /// <param name="claimId">The claim ID to verify.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Verification result.</returns>
+    Task<AiAttestationVerificationResult> VerifyClaimAttestationAsync(
+        string claimId,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Gets a run attestation by ID.
+    /// </summary>
+    /// <param name="runId">The run ID.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The attestation if found.</returns>
+    Task<AiRunAttestation?> GetRunAttestationAsync(
+        string runId,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Gets claim attestations for a run.
+    /// </summary>
+    /// <param name="runId">The run ID.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>All claim attestations for the run.</returns>
+    Task<IReadOnlyList<AiClaimAttestation>> GetClaimAttestationsAsync(
+        string runId,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Lists recent run attestations.
+    /// </summary>
+    /// <param name="tenantId">Tenant filter.</param>
+    /// <param name="limit">Maximum results.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Recent attestations.</returns>
+    Task<IReadOnlyList<AiRunAttestation>> ListRecentAttestationsAsync(
+        string tenantId,
+        int limit = 100,
+        CancellationToken ct = default);
+}
+
+/// <summary>
+/// Result of creating an attestation.
+/// </summary>
+public sealed record AiAttestationResult
+{
+    /// <summary>Attestation ID.</summary>
+    public required string AttestationId { get; init; }
+
+    /// <summary>Content digest.</summary>
+    public required string Digest { get; init; }
+
+    /// <summary>Whether the attestation was signed.</summary>
+    public bool Signed { get; init; }
+
+    /// <summary>DSSE envelope if signed.</summary>
+    public string? DsseEnvelope { get; init; }
+
+    /// <summary>Storage URI.</summary>
+    public string? StorageUri { get; init; }
+
+    /// <summary>Creation timestamp.</summary>
+    public required DateTimeOffset CreatedAt { get; init; }
+}
+
+/// <summary>
+/// Result of verifying an attestation.
+/// </summary>
+public sealed record AiAttestationVerificationResult
+{
+    /// <summary>Whether verification succeeded.</summary>
+    public required bool Valid { get; init; }
+
+    /// <summary>Verification timestamp.</summary>
+    public required DateTimeOffset VerifiedAt { get; init; }
+
+    /// <summary>Signing key ID if signed.</summary>
+    public string? SigningKeyId { get; init; }
+
+    /// <summary>Key expiration if applicable.</summary>
+    public DateTimeOffset? KeyExpiresAt { get; init; }
+
+    /// <summary>Digest verification result.</summary>
+    public bool DigestValid { get; init; }
+
+    /// <summary>Signature verification result.</summary>
+    public bool? SignatureValid { get; init; }
+
+    /// <summary>Verification failure reason if invalid.</summary>
+    public string? FailureReason { get; init; }
+
+    /// <summary>
+    /// Creates a successful verification result.
+    /// </summary>
+    public static AiAttestationVerificationResult Success(
+        DateTimeOffset verifiedAt,
+        string? signingKeyId = null,
+        DateTimeOffset? keyExpiresAt = null) => new()
+    {
+        Valid = true,
+        VerifiedAt = verifiedAt,
+        SigningKeyId = signingKeyId,
+        KeyExpiresAt = keyExpiresAt,
+        DigestValid = true,
+        SignatureValid = signingKeyId != null ? true : null
+    };
+
+    /// <summary>
+    /// Creates a failed verification result.
+    /// </summary>
+    public static AiAttestationVerificationResult Failure(
+        DateTimeOffset verifiedAt,
+        string reason,
+        bool digestValid = false,
+        bool? signatureValid = null) => new()
+    {
+        Valid = false,
+        VerifiedAt = verifiedAt,
+        DigestValid = digestValid,
+        SignatureValid = signatureValid,
+        FailureReason = reason
+    };
+}