# VexHub

**Status:** Implemented
**Source:** `src/VexHub/`
**Owner:** VEX Guild

## Purpose

VexHub aggregates, validates, and distributes VEX statements from multiple upstream sources. Provides the canonical VEX distribution layer with deterministic outputs, conflict detection, and offline-friendly operation for internal services and external tools (Trivy/Grype).

## Components

**Services:**
- `StellaOps.VexHub.WebService` - Minimal API host for distribution endpoints and admin controls
- `StellaOps.VexHub.Worker` - Background workers for scheduled ingestion and validation (planned)

**Libraries:**
- Normalization Pipeline - Canonicalizes statements to OpenVEX-compatible structures
- Validation Pipeline - Schema validation (OpenVEX/CycloneDX/CSAF) and signature checks

## Configuration

Configuration is typically embedded in module settings.

Key settings:
- PostgreSQL connection (schema: `vexhub`)
- Ingestion source connectors
- Validation policies (schema, signature)
- Export snapshot settings
- Conflict detection rules

## API Surface

- `GET /api/v1/vex/cve/{cve-id}` - Query VEX statements by CVE
- `GET /api/v1/vex/package/{purl}` - Query VEX statements by PURL
- `GET /api/v1/vex/source/{source-id}` - Query statements from specific source
- `GET /api/v1/vex/export` - Bulk OpenVEX feed (deterministic)
- `GET /api/v1/vex/index` - VEX index metadata (vex-index.json)

All responses use deterministic ordering: `timestamp DESC`, then `source_id ASC`, then `statement_hash ASC`.

## Dependencies

- PostgreSQL (schema: `vexhub` with tables: `statement`, `provenance`, `conflict`, `export_cursor`)
- Authority (authentication)
- IssuerDirectory (issuer trust registry)
- VexLens (consumes VexHub data for consensus)
- Excititor (VEX ingestion source)

## Related Documentation

- Architecture: `./architecture.md`
- VexLens: `../vex-lens/`
- IssuerDirectory: `../issuer-directory/`
- Excititor: `../excititor/`

## Current Status

WebService implemented with distribution API. Normalization and validation pipelines in place. Supports conflict detection and deterministic exports. Worker component planned for scheduled ingestion.