sprints work

src/__Libraries/StellaOps.Evidence.Pack/IEvidencePackSigner.cs

@@ -0,0 +1,72 @@
+// <copyright file="IEvidencePackSigner.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under the AGPL-3.0-or-later.
+// </copyright>
+
+using StellaOps.Evidence.Pack.Models;
+
+namespace StellaOps.Evidence.Pack;
+
+/// <summary>
+/// Signs and verifies evidence packs using DSSE.
+/// Sprint: SPRINT_20260109_011_005 Task: EVPK-003
+/// </summary>
+public interface IEvidencePackSigner
+{
+    /// <summary>
+    /// Signs an evidence pack and creates a DSSE envelope.
+    /// </summary>
+    /// <param name="pack">The evidence pack to sign.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The DSSE envelope containing the signature.</returns>
+    Task<DsseEnvelope> SignAsync(
+        EvidencePack pack,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Verifies a DSSE envelope signature.
+    /// </summary>
+    /// <param name="envelope">The envelope to verify.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The verification result.</returns>
+    Task<SignatureVerificationResult> VerifyAsync(
+        DsseEnvelope envelope,
+        CancellationToken cancellationToken);
+}
+
+/// <summary>
+/// Result of verifying a signature.
+/// </summary>
+public sealed record SignatureVerificationResult
+{
+    /// <summary>Gets whether the signature is valid.</summary>
+    public required bool Valid { get; init; }
+
+    /// <summary>Gets the signing key identifier.</summary>
+    public string? KeyId { get; init; }
+
+    /// <summary>Gets the verification timestamp.</summary>
+    public required DateTimeOffset VerifiedAt { get; init; }
+
+    /// <summary>Gets the failure reason if invalid.</summary>
+    public string? FailureReason { get; init; }
+
+    /// <summary>
+    /// Creates a successful verification result.
+    /// </summary>
+    public static SignatureVerificationResult Success(string keyId, DateTimeOffset verifiedAt) => new()
+    {
+        Valid = true,
+        KeyId = keyId,
+        VerifiedAt = verifiedAt
+    };
+
+    /// <summary>
+    /// Creates a failed verification result.
+    /// </summary>
+    public static SignatureVerificationResult Failure(string reason, DateTimeOffset verifiedAt) => new()
+    {
+        Valid = false,
+        VerifiedAt = verifiedAt,
+        FailureReason = reason
+    };
+}