# VEX Findings API with Proof Artifacts

## Module
Attestor

## Status
VERIFIED

## Description
VEX verdict models, VEX delta predicates, and a VexProofSpineService exist in the backend, but the full API contract (GET /vex/findings/:id with proof artifacts) is not visible as a standalone endpoint.

## What's Implemented
- **VEX Attestation Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/VexAttestationPredicate.cs` -- VEX verdict predicate with proof references.
- **VEX Verdict Summary**: `Predicates/VexVerdictSummary.cs` -- VEX verdict summary model.
- **VEX Proof Integrator**: `Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) -- proof integration for VEX verdicts.
- **VEX Verdict Proof Payload**: `Generators/VexVerdictProofPayload.cs` -- proof-carrying VEX verdict payload.
- **VEX Verdict Statement**: `Statements/VexVerdictStatement.cs` -- in-toto statement for VEX verdicts.
- **VEX Verdict ID**: `Identifiers/VexVerdictId.cs` -- content-addressed VEX verdict identifier.
- **Proof Spine System**: `Assembly/ProofSpineRequest.cs`, `ProofSpineResult.cs`, `ProofSpineSubject.cs` -- proof spine for evidence assembly.
- **Verdict Controller**: `StellaOps.Attestor.WebService/Controllers/VerdictController.cs` -- existing verdict API.
- **Proofs Controller**: `WebService/Controllers/ProofsController.cs` -- existing proofs API.

## What's Missing
- **`GET /vex/findings/:id` endpoint**: No REST endpoint returning VEX findings with attached proof artifacts for a specific finding ID.
- **Proof artifact packaging**: No service that packages proof artifacts (DSSE signatures, Rekor receipts, Merkle proofs) alongside VEX findings in API responses.
- **Finding-level proof resolution**: No resolver that collects all proof artifacts for a specific finding (CVE + component combination).
- **Proof artifact download**: No endpoint for downloading individual proof artifacts as files.
- **Finding search with proof status filter**: No search endpoint filtering findings by proof availability (e.g., "show only findings with proof").

## Implementation Plan
- Add `GET /vex/findings/:id` endpoint returning finding details with proof artifacts
- Create a proof artifact resolver collecting all proofs for a finding
- Add proof artifact packaging in API responses (inline or as download links)
- Add `GET /vex/findings/:id/proofs` endpoint for downloading proof artifacts
- Implement finding search with proof status filtering
- Add tests for finding retrieval, proof packaging, and search filtering

## Related Documentation
- Source: See feature catalog

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source Verification | PASS |
| Tier 1 - Build + Code Review | PASS |
| Tier 2 - Behavioral Verification | PASS |
| Verified Date | 2026-02-13 |
| Run ID | run-001 |