sprints enhancements

2025-12-25 19:52:30 +02:00
parent ef6ac36323
commit b8b2d83f4a
138 changed files with 25133 additions and 594 deletions
--- a/src/__Libraries/StellaOps.Provcache.Api/ApiModels.cs
+++ b/src/__Libraries/StellaOps.Provcache.Api/ApiModels.cs
@@ -189,3 +189,189 @@ internal static class InvalidationTypeExtensions
    /// </summary>
    public const string VeriKey = "VeriKey";
 }
+
+/// <summary>
+/// Response model for GET /v1/proofs/{proofRoot}.
+/// </summary>
+public sealed class ProofEvidenceResponse
+{
+    /// <summary>
+    /// The proof root (Merkle root).
+    /// </summary>
+    public required string ProofRoot { get; init; }
+
+    /// <summary>
+    /// Total number of chunks available.
+    /// </summary>
+    public required int TotalChunks { get; init; }
+
+    /// <summary>
+    /// Total size of all evidence in bytes.
+    /// </summary>
+    public required long TotalSize { get; init; }
+
+    /// <summary>
+    /// The chunks in this page.
+    /// </summary>
+    public required IReadOnlyList<ProofChunkResponse> Chunks { get; init; }
+
+    /// <summary>
+    /// Pagination cursor for next page (null if last page).
+    /// </summary>
+    public string? NextCursor { get; init; }
+
+    /// <summary>
+    /// Whether there are more chunks available.
+    /// </summary>
+    public bool HasMore { get; init; }
+}
+
+/// <summary>
+/// Response model for a single proof chunk.
+/// </summary>
+public sealed class ProofChunkResponse
+{
+    /// <summary>
+    /// Unique chunk identifier.
+    /// </summary>
+    public required Guid ChunkId { get; init; }
+
+    /// <summary>
+    /// Zero-based chunk index.
+    /// </summary>
+    public required int Index { get; init; }
+
+    /// <summary>
+    /// SHA256 hash for verification.
+    /// </summary>
+    public required string Hash { get; init; }
+
+    /// <summary>
+    /// Size in bytes.
+    /// </summary>
+    public required int Size { get; init; }
+
+    /// <summary>
+    /// Content type.
+    /// </summary>
+    public required string ContentType { get; init; }
+
+    /// <summary>
+    /// Base64-encoded chunk data (included only when includeData=true).
+    /// </summary>
+    public string? Data { get; init; }
+}
+
+/// <summary>
+/// Response model for GET /v1/proofs/{proofRoot}/manifest.
+/// </summary>
+public sealed class ProofManifestResponse
+{
+    /// <summary>
+    /// The proof root (Merkle root).
+    /// </summary>
+    public required string ProofRoot { get; init; }
+
+    /// <summary>
+    /// Total number of chunks.
+    /// </summary>
+    public required int TotalChunks { get; init; }
+
+    /// <summary>
+    /// Total size of all evidence in bytes.
+    /// </summary>
+    public required long TotalSize { get; init; }
+
+    /// <summary>
+    /// Ordered list of chunk metadata (without data).
+    /// </summary>
+    public required IReadOnlyList<ChunkMetadataResponse> Chunks { get; init; }
+
+    /// <summary>
+    /// When the manifest was generated.
+    /// </summary>
+    public required DateTimeOffset GeneratedAt { get; init; }
+}
+
+/// <summary>
+/// Response model for chunk metadata (without data).
+/// </summary>
+public sealed class ChunkMetadataResponse
+{
+    /// <summary>
+    /// Chunk identifier.
+    /// </summary>
+    public required Guid ChunkId { get; init; }
+
+    /// <summary>
+    /// Zero-based index.
+    /// </summary>
+    public required int Index { get; init; }
+
+    /// <summary>
+    /// SHA256 hash for verification.
+    /// </summary>
+    public required string Hash { get; init; }
+
+    /// <summary>
+    /// Size in bytes.
+    /// </summary>
+    public required int Size { get; init; }
+
+    /// <summary>
+    /// Content type.
+    /// </summary>
+    public required string ContentType { get; init; }
+}
+
+/// <summary>
+/// Response model for POST /v1/proofs/{proofRoot}/verify.
+/// </summary>
+public sealed class ProofVerificationResponse
+{
+    /// <summary>
+    /// The proof root that was verified.
+    /// </summary>
+    public required string ProofRoot { get; init; }
+
+    /// <summary>
+    /// Whether the Merkle tree is valid.
+    /// </summary>
+    public required bool IsValid { get; init; }
+
+    /// <summary>
+    /// Details about each chunk's verification.
+    /// </summary>
+    public IReadOnlyList<ChunkVerificationResult>? ChunkResults { get; init; }
+
+    /// <summary>
+    /// Error message if verification failed.
+    /// </summary>
+    public string? Error { get; init; }
+}
+
+/// <summary>
+/// Result of verifying a single chunk.
+/// </summary>
+public sealed class ChunkVerificationResult
+{
+    /// <summary>
+    /// Chunk index.
+    /// </summary>
+    public required int Index { get; init; }
+
+    /// <summary>
+    /// Whether the chunk hash is valid.
+    /// </summary>
+    public required bool IsValid { get; init; }
+
+    /// <summary>
+    /// Expected hash from manifest.
+    /// </summary>
+    public required string ExpectedHash { get; init; }
+
+    /// <summary>
+    /// Computed hash from chunk data.
+    /// </summary>
+    public string? ComputedHash { get; init; }
+}
--- a/src/__Libraries/StellaOps.Provcache.Api/ProvcacheEndpointExtensions.cs
+++ b/src/__Libraries/StellaOps.Provcache.Api/ProvcacheEndpointExtensions.cs
@@ -1,5 +1,6 @@
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
@@ -14,7 +15,7 @@ public sealed class ProvcacheApiEndpoints;
 /// <summary>
 /// Extension methods for mapping Provcache API endpoints.
 /// </summary>
-public static class ProvcacheEndpointExtensions
+public static partial class ProvcacheEndpointExtensions
 {
    /// <summary>
    /// Maps Provcache API endpoints to the specified route builder.
@@ -69,6 +70,47 @@ public static class ProvcacheEndpointExtensions
            .Produces<ProvcacheMetricsResponse>(StatusCodes.Status200OK)
            .Produces<ProblemDetails>(StatusCodes.Status500InternalServerError);

+        // Map evidence paging endpoints under /proofs
+        var proofsGroup = endpoints.MapGroup($"{prefix}/proofs")
+            .WithTags("Provcache Evidence")
+            .WithOpenApi();
+
+        // GET /v1/provcache/proofs/{proofRoot}
+        proofsGroup.MapGet("/{proofRoot}", GetEvidenceChunks)
+            .WithName("GetProofEvidence")
+            .WithSummary("Get evidence chunks by proof root")
+            .WithDescription("Retrieves evidence chunks for a proof root with pagination support. Use cursor parameter for subsequent pages.")
+            .Produces<ProofEvidenceResponse>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status404NotFound)
+            .Produces<ProblemDetails>(StatusCodes.Status500InternalServerError);
+
+        // GET /v1/provcache/proofs/{proofRoot}/manifest
+        proofsGroup.MapGet("/{proofRoot}/manifest", GetProofManifest)
+            .WithName("GetProofManifest")
+            .WithSummary("Get chunk manifest (metadata without data)")
+            .WithDescription("Retrieves the chunk manifest for lazy evidence fetching. Contains hashes and sizes but no blob data.")
+            .Produces<ProofManifestResponse>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status404NotFound)
+            .Produces<ProblemDetails>(StatusCodes.Status500InternalServerError);
+
+        // GET /v1/provcache/proofs/{proofRoot}/chunks/{chunkIndex}
+        proofsGroup.MapGet("/{proofRoot}/chunks/{chunkIndex:int}", GetSingleChunk)
+            .WithName("GetProofChunk")
+            .WithSummary("Get a single chunk by index")
+            .WithDescription("Retrieves a specific chunk by its index within the proof.")
+            .Produces<ProofChunkResponse>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status404NotFound)
+            .Produces<ProblemDetails>(StatusCodes.Status500InternalServerError);
+
+        // POST /v1/provcache/proofs/{proofRoot}/verify
+        proofsGroup.MapPost("/{proofRoot}/verify", VerifyProof)
+            .WithName("VerifyProof")
+            .WithSummary("Verify Merkle tree integrity")
+            .WithDescription("Verifies all chunk hashes and the Merkle tree for the proof root.")
+            .Produces<ProofVerificationResponse>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status404NotFound)
+            .Produces<ProblemDetails>(StatusCodes.Status500InternalServerError);
+
        return group;
    }

@@ -278,3 +320,234 @@ internal sealed class ProblemDetails
    public string? Detail { get; set; }
    public string? Instance { get; set; }
 }
+
+/// <summary>
+/// Marker class for logging in Proofs API endpoints.
+/// </summary>
+public sealed class ProofsApiEndpoints;
+
+partial class ProvcacheEndpointExtensions
+{
+    private const int DefaultPageSize = 10;
+    private const int MaxPageSize = 100;
+
+    /// <summary>
+    /// GET /v1/provcache/proofs/{proofRoot}
+    /// </summary>
+    private static async Task<IResult> GetEvidenceChunks(
+        string proofRoot,
+        int? offset,
+        int? limit,
+        bool? includeData,
+        [FromServices] IEvidenceChunkRepository chunkRepository,
+        ILogger<ProofsApiEndpoints> logger,
+        CancellationToken cancellationToken)
+    {
+        logger.LogDebug("GET /v1/provcache/proofs/{ProofRoot} offset={Offset} limit={Limit}", proofRoot, offset, limit);
+
+        try
+        {
+            var startIndex = offset ?? 0;
+            var pageSize = Math.Min(limit ?? DefaultPageSize, MaxPageSize);
+
+            // Get manifest for total count
+            var manifest = await chunkRepository.GetManifestAsync(proofRoot, cancellationToken);
+            if (manifest is null)
+            {
+                return Results.NotFound();
+            }
+
+            // Get chunk range
+            var chunks = await chunkRepository.GetChunkRangeAsync(proofRoot, startIndex, pageSize, cancellationToken);
+
+            var chunkResponses = chunks.Select(c => new ProofChunkResponse
+            {
+                ChunkId = c.ChunkId,
+                Index = c.ChunkIndex,
+                Hash = c.ChunkHash,
+                Size = c.BlobSize,
+                ContentType = c.ContentType,
+                Data = includeData == true ? Convert.ToBase64String(c.Blob) : null
+            }).ToList();
+
+            var hasMore = startIndex + chunks.Count < manifest.TotalChunks;
+            var nextCursor = hasMore ? (startIndex + pageSize).ToString() : null;
+
+            return Results.Ok(new ProofEvidenceResponse
+            {
+                ProofRoot = proofRoot,
+                TotalChunks = manifest.TotalChunks,
+                TotalSize = manifest.TotalSize,
+                Chunks = chunkResponses,
+                NextCursor = nextCursor,
+                HasMore = hasMore
+            });
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Error getting evidence chunks for proof root {ProofRoot}", proofRoot);
+            return Results.Problem(
+                detail: ex.Message,
+                statusCode: StatusCodes.Status500InternalServerError,
+                title: "Evidence retrieval failed");
+        }
+    }
+
+    /// <summary>
+    /// GET /v1/provcache/proofs/{proofRoot}/manifest
+    /// </summary>
+    private static async Task<IResult> GetProofManifest(
+        string proofRoot,
+        [FromServices] IEvidenceChunkRepository chunkRepository,
+        ILogger<ProofsApiEndpoints> logger,
+        CancellationToken cancellationToken)
+    {
+        logger.LogDebug("GET /v1/provcache/proofs/{ProofRoot}/manifest", proofRoot);
+
+        try
+        {
+            var manifest = await chunkRepository.GetManifestAsync(proofRoot, cancellationToken);
+            if (manifest is null)
+            {
+                return Results.NotFound();
+            }
+
+            var chunkMetadata = manifest.Chunks.Select(c => new ChunkMetadataResponse
+            {
+                ChunkId = c.ChunkId,
+                Index = c.Index,
+                Hash = c.Hash,
+                Size = c.Size,
+                ContentType = c.ContentType
+            }).ToList();
+
+            return Results.Ok(new ProofManifestResponse
+            {
+                ProofRoot = proofRoot,
+                TotalChunks = manifest.TotalChunks,
+                TotalSize = manifest.TotalSize,
+                Chunks = chunkMetadata,
+                GeneratedAt = manifest.GeneratedAt
+            });
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Error getting manifest for proof root {ProofRoot}", proofRoot);
+            return Results.Problem(
+                detail: ex.Message,
+                statusCode: StatusCodes.Status500InternalServerError,
+                title: "Manifest retrieval failed");
+        }
+    }
+
+    /// <summary>
+    /// GET /v1/provcache/proofs/{proofRoot}/chunks/{chunkIndex}
+    /// </summary>
+    private static async Task<IResult> GetSingleChunk(
+        string proofRoot,
+        int chunkIndex,
+        [FromServices] IEvidenceChunkRepository chunkRepository,
+        ILogger<ProofsApiEndpoints> logger,
+        CancellationToken cancellationToken)
+    {
+        logger.LogDebug("GET /v1/provcache/proofs/{ProofRoot}/chunks/{ChunkIndex}", proofRoot, chunkIndex);
+
+        try
+        {
+            var chunk = await chunkRepository.GetChunkAsync(proofRoot, chunkIndex, cancellationToken);
+            if (chunk is null)
+            {
+                return Results.NotFound();
+            }
+
+            return Results.Ok(new ProofChunkResponse
+            {
+                ChunkId = chunk.ChunkId,
+                Index = chunk.ChunkIndex,
+                Hash = chunk.ChunkHash,
+                Size = chunk.BlobSize,
+                ContentType = chunk.ContentType,
+                Data = Convert.ToBase64String(chunk.Blob)
+            });
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Error getting chunk {ChunkIndex} for proof root {ProofRoot}", chunkIndex, proofRoot);
+            return Results.Problem(
+                detail: ex.Message,
+                statusCode: StatusCodes.Status500InternalServerError,
+                title: "Chunk retrieval failed");
+        }
+    }
+
+    /// <summary>
+    /// POST /v1/provcache/proofs/{proofRoot}/verify
+    /// </summary>
+    private static async Task<IResult> VerifyProof(
+        string proofRoot,
+        [FromServices] IEvidenceChunkRepository chunkRepository,
+        [FromServices] IEvidenceChunker chunker,
+        ILogger<ProofsApiEndpoints> logger,
+        CancellationToken cancellationToken)
+    {
+        logger.LogDebug("POST /v1/provcache/proofs/{ProofRoot}/verify", proofRoot);
+
+        try
+        {
+            var chunks = await chunkRepository.GetChunksAsync(proofRoot, cancellationToken);
+            if (chunks.Count == 0)
+            {
+                return Results.NotFound();
+            }
+
+            var chunkResults = new List<ChunkVerificationResult>();
+            var allValid = true;
+
+            foreach (var chunk in chunks)
+            {
+                var isValid = chunker.VerifyChunk(chunk);
+                var computedHash = isValid ? chunk.ChunkHash : ComputeChunkHash(chunk.Blob);
+
+                chunkResults.Add(new ChunkVerificationResult
+                {
+                    Index = chunk.ChunkIndex,
+                    IsValid = isValid,
+                    ExpectedHash = chunk.ChunkHash,
+                    ComputedHash = isValid ? null : computedHash
+                });
+
+                if (!isValid)
+                {
+                    allValid = false;
+                }
+            }
+
+            // Verify Merkle root
+            var chunkHashes = chunks.Select(c => c.ChunkHash).ToList();
+            var computedRoot = chunker.ComputeMerkleRoot(chunkHashes);
+            var rootMatches = string.Equals(computedRoot, proofRoot, StringComparison.OrdinalIgnoreCase);
+
+            return Results.Ok(new ProofVerificationResponse
+            {
+                ProofRoot = proofRoot,
+                IsValid = allValid && rootMatches,
+                ChunkResults = chunkResults,
+                Error = !rootMatches ? $"Merkle root mismatch. Expected: {proofRoot}, Computed: {computedRoot}" : null
+            });
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Error verifying proof root {ProofRoot}", proofRoot);
+            return Results.Problem(
+                detail: ex.Message,
+                statusCode: StatusCodes.Status500InternalServerError,
+                title: "Proof verification failed");
+        }
+    }
+
+    private static string ComputeChunkHash(byte[] data)
+    {
+        var hash = System.Security.Cryptography.SHA256.HashData(data);
+        return $"sha256:{Convert.ToHexStringLower(hash)}";
+    }
+}