# Composition Recipe API for SBOM Determinism Verification

## Module
Scanner

## Status
VERIFIED

## Description
API endpoint (GET /scans/{id}/composition-recipe) that exposes the SBOM composition recipe with Merkle root and layer digest verification, enabling downstream verification that SBOMs are deterministically composed from layer fragments.

## Implementation Details
- **Composition Recipe Service**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CompositionRecipeService.cs` - Core service computing composition recipes with Merkle root
  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/SbomCompositionResult.cs` - Composition result model with Merkle root and layer digests
- **Layer SBOM Composition**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomComposer.cs` - Composes full SBOM from per-layer SBOM fragments
  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/LayerSbomRef.cs` - Layer SBOM reference with digest
  - `src/Scanner/__Libraries/StellaOps.Scanner.Emit/Composition/CycloneDxComposer.cs` - CycloneDX-specific composition
- **API Endpoints**:
  - `src/Scanner/StellaOps.Scanner.WebService/Endpoints/LayerSbomEndpoints.cs` - `LayerSbomEndpoints` exposing composition recipe and layer SBOM data
  - `src/Scanner/StellaOps.Scanner.WebService/Contracts/LayerSbomContracts.cs` - API contracts
- **Layer SBOM Service**:
  - `src/Scanner/StellaOps.Scanner.WebService/Services/ILayerSbomService.cs` - `ILayerSbomService` with `LayerSummary`, `SbomLayerFragment`
  - `src/Scanner/StellaOps.Scanner.WebService/Services/LayerSbomService.cs` - Implementation
- **Surface Manifest**:
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS/SurfaceManifestDeterminismVerifier.cs` - Verifies determinism of surface manifests
  - `src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS/FacetSealExtractor.cs` - Extracts facet seals for composition verification

## E2E Test Plan
- [ ] Scan an image and call `GET /api/v1/scans/{scanId}/composition-recipe` to retrieve the composition recipe
- [ ] Verify the response includes Merkle root and per-layer digest values
- [ ] Verify each layer fragment digest matches the actual layer SBOM content hash
- [ ] Re-compose the SBOM from layer fragments and verify the Merkle root matches the recipe
- [ ] Scan the same image twice and verify composition recipe values are deterministically identical
- [ ] Verify the composition recipe can be used to verify SBOM integrity in an offline/air-gap environment

---

## Verification

| Check | Result |
|-------|--------|
| Tier 0 - Source files exist | PASS |
| Tier 1 - Build + code review | PASS |
| Tier 2 - Integration tests | PASS |
| Verified | 2026-02-13T18:10:00Z |