feat: Add CVSS receipt management endpoints and related functionality

- Introduced new API endpoints for creating, retrieving, amending, and listing CVSS receipts.
- Updated IPolicyEngineClient interface to include methods for CVSS receipt operations.
- Implemented PolicyEngineClient to handle CVSS receipt requests.
- Enhanced Program.cs to map new CVSS receipt routes with appropriate authorization.
- Added necessary models and contracts for CVSS receipt requests and responses.
- Integrated Postgres document store for managing CVSS receipts and related data.
- Updated database schema with new migrations for source documents and payload storage.
- Refactored existing components to support new CVSS functionality.

src/Policy/StellaOps.Policy.Gateway/Program.cs

@@ -279,11 +279,11 @@ policyPacks.MapPost("/{packId}/revisions", async Task<IResult> (
     })
     .RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.PolicyAuthor));
 
-policyPacks.MapPost("/{packId}/revisions/{version:int}:activate", async Task<IResult> (
-        HttpContext context,
-        string packId,
-        int version,
-        ActivatePolicyRevisionRequest request,
+policyPacks.MapPost("/{packId}/revisions/{version:int}:activate", async Task<IResult> (
+        HttpContext context,
+        string packId,
+        int version,
+        ActivatePolicyRevisionRequest request,
         IPolicyEngineClient client,
         PolicyEngineTokenProvider tokenProvider,
         PolicyGatewayMetrics metrics,
@@ -330,13 +330,144 @@ policyPacks.MapPost("/{packId}/revisions/{version:int}:activate", async Task<IRe
         var logger = loggerFactory.CreateLogger("StellaOps.Policy.Gateway.Activation");
         LogActivation(logger, packId, version, outcome, source, response.StatusCode);
 
-        return response.ToMinimalResult();
-    })
-    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(
-        StellaOpsScopes.PolicyOperate,
-        StellaOpsScopes.PolicyActivate));
-
-app.Run();
+        return response.ToMinimalResult();
+    })
+    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(
+        StellaOpsScopes.PolicyOperate,
+        StellaOpsScopes.PolicyActivate));
+
+var cvss = app.MapGroup("/api/cvss")
+    .WithTags("CVSS Receipts");
+
+cvss.MapPost("/receipts", async Task<IResult>(
+        HttpContext context,
+        CreateCvssReceiptRequest request,
+        IPolicyEngineClient client,
+        PolicyEngineTokenProvider tokenProvider,
+        CancellationToken cancellationToken) =>
+    {
+        if (request is null)
+        {
+            return Results.BadRequest(new ProblemDetails
+            {
+                Title = "Request body required.",
+                Status = StatusCodes.Status400BadRequest
+            });
+        }
+
+        GatewayForwardingContext? forwardingContext = null;
+        if (GatewayForwardingContext.TryCreate(context, out var callerContext))
+        {
+            forwardingContext = callerContext;
+        }
+        else if (!tokenProvider.IsEnabled)
+        {
+            return Results.Unauthorized();
+        }
+
+        var response = await client.CreateCvssReceiptAsync(forwardingContext, request, cancellationToken).ConfigureAwait(false);
+        return response.ToMinimalResult();
+    })
+    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.PolicyRun));
+
+cvss.MapGet("/receipts/{receiptId}", async Task<IResult>(
+        HttpContext context,
+        string receiptId,
+        IPolicyEngineClient client,
+        PolicyEngineTokenProvider tokenProvider,
+        CancellationToken cancellationToken) =>
+    {
+        GatewayForwardingContext? forwardingContext = null;
+        if (GatewayForwardingContext.TryCreate(context, out var callerContext))
+        {
+            forwardingContext = callerContext;
+        }
+        else if (!tokenProvider.IsEnabled)
+        {
+            return Results.Unauthorized();
+        }
+
+        var response = await client.GetCvssReceiptAsync(forwardingContext, receiptId, cancellationToken).ConfigureAwait(false);
+        return response.ToMinimalResult();
+    })
+    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.FindingsRead));
+
+cvss.MapPut("/receipts/{receiptId}/amend", async Task<IResult>(
+        HttpContext context,
+        string receiptId,
+        AmendCvssReceiptRequest request,
+        IPolicyEngineClient client,
+        PolicyEngineTokenProvider tokenProvider,
+        CancellationToken cancellationToken) =>
+    {
+        if (request is null)
+        {
+            return Results.BadRequest(new ProblemDetails
+            {
+                Title = "Request body required.",
+                Status = StatusCodes.Status400BadRequest
+            });
+        }
+
+        GatewayForwardingContext? forwardingContext = null;
+        if (GatewayForwardingContext.TryCreate(context, out var callerContext))
+        {
+            forwardingContext = callerContext;
+        }
+        else if (!tokenProvider.IsEnabled)
+        {
+            return Results.Unauthorized();
+        }
+
+        var response = await client.AmendCvssReceiptAsync(forwardingContext, receiptId, request, cancellationToken).ConfigureAwait(false);
+        return response.ToMinimalResult();
+    })
+    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.PolicyRun));
+
+cvss.MapGet("/receipts/{receiptId}/history", async Task<IResult>(
+        HttpContext context,
+        string receiptId,
+        IPolicyEngineClient client,
+        PolicyEngineTokenProvider tokenProvider,
+        CancellationToken cancellationToken) =>
+    {
+        GatewayForwardingContext? forwardingContext = null;
+        if (GatewayForwardingContext.TryCreate(context, out var callerContext))
+        {
+            forwardingContext = callerContext;
+        }
+        else if (!tokenProvider.IsEnabled)
+        {
+            return Results.Unauthorized();
+        }
+
+        var response = await client.GetCvssReceiptHistoryAsync(forwardingContext, receiptId, cancellationToken).ConfigureAwait(false);
+        return response.ToMinimalResult();
+    })
+    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.FindingsRead));
+
+cvss.MapGet("/policies", async Task<IResult>(
+        HttpContext context,
+        IPolicyEngineClient client,
+        PolicyEngineTokenProvider tokenProvider,
+        CancellationToken cancellationToken) =>
+    {
+        GatewayForwardingContext? forwardingContext = null;
+        if (GatewayForwardingContext.TryCreate(context, out var callerContext))
+        {
+            forwardingContext = callerContext;
+        }
+        else if (!tokenProvider.IsEnabled)
+        {
+            return Results.Unauthorized();
+        }
+
+        var response = await client.ListCvssPoliciesAsync(forwardingContext, cancellationToken).ConfigureAwait(false);
+        return response.ToMinimalResult();
+    })
+    .RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.FindingsRead));
+
+app.Run();
 
 static IAsyncPolicy<HttpResponseMessage> CreateAuthorityRetryPolicy(IServiceProvider provider)
 {