# Idempotent SBOM/Attestation APIs

## Module
Attestor

## Status
VERIFIED

## Description
Content-addressed identification for artifacts is implemented. Full idempotent REST API endpoints (POST /sbom/ingest, POST /attest/verify) are not clearly visible as standalone web service endpoints.

## What's Implemented
- **Content-Addressed IDs**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/` -- ArtifactId, EvidenceId, ProofBundleId, GenericContentAddressedId, ContentAddressedIdGenerator (with `.Graph`), Sha256IdParser -- SHA-256 based content-addressed identification.
- **Proof Chain REST API**: `StellaOps.Attestor.WebService/Controllers/ProofChainController.cs` -- existing proof chain API endpoints.
- **Bundles Controller**: `WebService/Controllers/BundlesController.cs` -- bundle management endpoints.
- **Verify Controller**: `WebService/Controllers/VerifyController.cs` -- verification endpoints.
- **Chain Controller**: `WebService/Controllers/ChainController.cs` -- chain query endpoints.
- **SBOM OCI Publisher**: `__Libraries/StellaOps.Attestor.Oci/Services/SbomOciPublisher.cs` -- publishes SBOMs to OCI registries.

## What's Missing
- **Idempotent SBOM ingest endpoint**: No `POST /sbom/ingest` endpoint that accepts an SBOM and returns the same content-addressed ID on duplicate submissions without creating duplicate records.
- **Idempotent attestation verify endpoint**: No `POST /attest/verify` endpoint that caches verification results by content hash for repeat submissions.
- **Idempotency key support**: No HTTP idempotency key header (`Idempotency-Key`) support for POST endpoints.
- **Content-addressed deduplication at API level**: Content-addressed IDs exist at the library level but API endpoints do not use them for deduplication (checking if content already exists before processing).
- **Conditional response (ETag/304)**: No ETag-based conditional responses for GET endpoints to avoid re-fetching unchanged content.

## Implementation Plan
- Add `POST /sbom/ingest` endpoint with content-hash-based deduplication
- Add `POST /attest/verify` endpoint with cached verification results
- Implement idempotency key support for all POST endpoints
- Add content-addressed deduplication at the API layer (check-before-store)
- Add ETag support for GET endpoints
- Add tests for idempotency (duplicate submissions return same result)

## Related Documentation
- Source: See feature catalog
- Related: `scanner/idempotent-attestation-submission.md` (scanner-side submission idempotency)

## 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 |