wip: doctor/cli/docs/api to vector db consolidation; api hardening for descriptions, tenant, and scopes; migrations and conversions of all DALs to EF v10

src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/AttestorWebServiceEndpoints.cs

@@ -37,6 +37,8 @@ internal static class AttestorWebServiceEndpoints
 
             return Results.Ok(response);
         })
+        .WithName("ListAttestations")
+        .WithDescription("Lists attestation entries from the repository with optional filters. Returns a paginated result with continuation token for incremental sync. Requires attestor:read scope.")
         .RequireAuthorization("attestor:read")
         .RequireRateLimiting("attestor-reads");
 
@@ -60,6 +62,8 @@ internal static class AttestorWebServiceEndpoints
             var package = await bundleService.ExportAsync(request, cancellationToken).ConfigureAwait(false);
             return Results.Ok(package);
         })
+        .WithName("ExportAttestationBundle")
+        .WithDescription("Exports attestations as a portable bundle package with optional filters by artifact digest, date range, and predicate type. Used for offline transfer and air-gap synchronization. Requires attestor:read scope.")
         .RequireAuthorization("attestor:read")
         .RequireRateLimiting("attestor-reads")
         .Produces<AttestorBundlePackage>(StatusCodes.Status200OK);
@@ -74,6 +78,8 @@ internal static class AttestorWebServiceEndpoints
             var result = await bundleService.ImportAsync(package, cancellationToken).ConfigureAwait(false);
             return Results.Ok(result);
         })
+        .WithName("ImportAttestationBundle")
+        .WithDescription("Imports a portable attestation bundle package into the attestor store. All entries within the bundle are validated before persistence. Returns a summary of imported and skipped entries. Requires attestor:write scope.")
         .RequireAuthorization("attestor:write")
         .RequireRateLimiting("attestor-submissions")
         .Produces<AttestorBundleImportResult>(StatusCodes.Status200OK);
@@ -146,8 +152,11 @@ internal static class AttestorWebServiceEndpoints
                     ["code"] = signingEx.Code
                 });
             }
-        }).RequireAuthorization("attestor:write")
-          .RequireRateLimiting("attestor-submissions");
+        })
+        .WithName("SignAttestation")
+        .WithDescription("Signs an attestation payload using the configured key and DSSE envelope format. Requires a valid client certificate and authenticated principal. Returns the signed bundle with key metadata and optional Rekor submission details. Requires attestor:write scope.")
+        .RequireAuthorization("attestor:write")
+        .RequireRateLimiting("attestor-submissions");
 
         // In-toto link creation endpoint
         app.MapPost("/api/v1/attestor/links", async (
@@ -278,9 +287,12 @@ internal static class AttestorWebServiceEndpoints
                     ["code"] = signingEx.Code
                 });
             }
-        }).RequireAuthorization("attestor:write")
-          .RequireRateLimiting("attestor-submissions")
-          .Produces<InTotoLinkCreateResponseDto>(StatusCodes.Status200OK);
+        })
+        .WithName("CreateInTotoLink")
+        .WithDescription("Creates and signs an in-toto link metadata object for a named step, including materials, products, command, environment, and return value. Returns the signed DSSE envelope with optional Rekor entry. Requires attestor:write scope.")
+        .RequireAuthorization("attestor:write")
+        .RequireRateLimiting("attestor-submissions")
+        .Produces<InTotoLinkCreateResponseDto>(StatusCodes.Status200OK);
 
         app.MapPost("/api/v1/rekor/entries", async (AttestorSubmissionRequest request, HttpContext httpContext, IAttestorSubmissionService submissionService, CancellationToken cancellationToken) =>
         {
@@ -316,16 +328,22 @@ internal static class AttestorWebServiceEndpoints
                 });
             }
         })
+        .WithName("SubmitRekorEntry")
+        .WithDescription("Submits an attestation entry to the configured Rekor transparency log. Requires a valid client certificate and authenticated principal. Returns the Rekor entry details including UUID, log index, and inclusion proof. Requires attestor:write scope.")
         .RequireAuthorization("attestor:write")
         .RequireRateLimiting("attestor-submissions");
 
         app.MapGet("/api/v1/rekor/entries/{uuid}", async (string uuid, bool? refresh, IAttestorVerificationService verificationService, CancellationToken cancellationToken) =>
                 await GetAttestationDetailResultAsync(uuid, refresh is true, verificationService, cancellationToken))
+            .WithName("GetRekorEntry")
+            .WithDescription("Retrieves a Rekor transparency log entry by UUID, including inclusion proof, checkpoint, and artifact metadata. Set refresh=true to bypass cache and fetch the latest state from Rekor. Requires attestor:read scope.")
             .RequireAuthorization("attestor:read")
             .RequireRateLimiting("attestor-reads");
 
         app.MapGet("/api/v1/attestations/{uuid}", async (string uuid, bool? refresh, IAttestorVerificationService verificationService, CancellationToken cancellationToken) =>
                 await GetAttestationDetailResultAsync(uuid, refresh is true, verificationService, cancellationToken))
+            .WithName("GetAttestationByUuid")
+            .WithDescription("Retrieves an attestation entry by UUID, including inclusion proof, checkpoint, artifact metadata, and optional mirror status. Equivalent to the Rekor entry endpoint but accessed by attestor UUID alias. Requires attestor:read scope.")
             .RequireAuthorization("attestor:read")
             .RequireRateLimiting("attestor-reads");
 
@@ -349,6 +367,8 @@ internal static class AttestorWebServiceEndpoints
                 });
             }
         })
+        .WithName("VerifyRekorEntry")
+        .WithDescription("Verifies an attestation against the Rekor transparency log, checking inclusion proof, checkpoint consistency, and signature validity. Returns a structured verification result with per-check diagnostics. Requires attestor:verify scope.")
         .RequireAuthorization("attestor:verify")
         .RequireRateLimiting("attestor-verifications");
 
@@ -374,8 +394,11 @@ internal static class AttestorWebServiceEndpoints
             job = await jobStore.CreateAsync(job!, cancellationToken).ConfigureAwait(false);
             var response = BulkVerificationContracts.MapJob(job);
             return Results.Accepted($"/api/v1/rekor/verify:bulk/{job.Id}", response);
-        }).RequireAuthorization("attestor:write")
-          .RequireRateLimiting("attestor-bulk");
+        })
+        .WithName("CreateBulkVerificationJob")
+        .WithDescription("Enqueues a bulk attestation verification job for processing multiple entries asynchronously. Returns 202 Accepted with the job ID and a polling URL. Queue depth is enforced by quota configuration. Requires attestor:write scope.")
+        .RequireAuthorization("attestor:write")
+        .RequireRateLimiting("attestor-bulk");
 
         app.MapGet("/api/v1/rekor/verify:bulk/{jobId}", async (
             string jobId,
@@ -395,7 +418,10 @@ internal static class AttestorWebServiceEndpoints
             }
 
             return Results.Ok(BulkVerificationContracts.MapJob(job));
-        }).RequireAuthorization("attestor:write");
+        })
+        .WithName("GetBulkVerificationJob")
+        .WithDescription("Returns the current status and results of a bulk attestation verification job by job ID. The job is only visible to the principal that submitted it. Returns 404 for unknown or unauthorized job IDs. Requires attestor:write scope.")
+        .RequireAuthorization("attestor:write");
 
         // SPDX 3.0.1 Build Profile export endpoint (BP-007)
         app.MapPost("/api/v1/attestations:export-build", (
@@ -512,6 +538,8 @@ internal static class AttestorWebServiceEndpoints
 
             return Results.Ok(response);
         })
+        .WithName("ExportSpdx3BuildAttestation")
+        .WithDescription("Exports a build attestation payload as an SPDX 3.0.1 Build Profile element, including builder identity, invocation details, configuration source, materials, and build timestamps. Returns structured SPDX document and optional DSSE envelope. Requires attestor:write scope.")
         .RequireAuthorization("attestor:write")
         .RequireRateLimiting("attestor-submissions")
         .Produces<Spdx3BuildExportResponseDto>(StatusCodes.Status200OK);

src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/Endpoints/PredicateRegistryEndpoints.cs

@@ -29,11 +29,15 @@ public static class PredicateRegistryEndpoints
         group.MapGet("/", ListPredicateTypes)
             .WithName("ListPredicateTypes")
             .WithSummary("List all registered predicate types")
+            .WithDescription("Returns a paginated list of registered in-toto predicate type schemas from the registry, with optional filters by category and active status. Used to discover supported predicate URIs for attestation creation.")
+            .RequireAuthorization("attestor:read")
             .Produces<PredicateTypeListResponse>(StatusCodes.Status200OK);
 
         group.MapGet("/{uri}", GetPredicateType)
             .WithName("GetPredicateType")
             .WithSummary("Get predicate type schema by URI")
+            .WithDescription("Retrieves the full schema definition for a predicate type identified by its URI. The URI must be URL-encoded when passed as a path segment. Returns 404 if the predicate type is not registered.")
+            .RequireAuthorization("attestor:read")
             .Produces<PredicateTypeRegistryEntry>(StatusCodes.Status200OK)
             .Produces(StatusCodes.Status404NotFound);
     }

src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/WatchlistEndpoints.cs

@@ -22,7 +22,7 @@ internal static class WatchlistEndpoints
     {
         var group = app.MapGroup("/api/v1/watchlist")
             .WithTags("Watchlist")
-            .RequireAuthorization();
+            .RequireAuthorization("watchlist:read");
 
         // List watchlist entries
         group.MapGet("", ListWatchlistEntries)