# sbom-nexus

SBOM Nexus is the dedicated software-bill-of-materials service for the Coulomb
fleet. It captures dependency evidence from repositories, keeps immutable
snapshots, evaluates licence risk and freshness, and provides a bounded catch-up
queue for automation.

The product direction is defined in [INTENT.md](INTENT.md). The first delivery
contract is in [ProductRequirementsDocument.md](ProductRequirementsDocument.md).

## Development

```bash
uv sync --dev
uv run pytest
uv run ruff check src tests
uv run sbom-nexus serve --reload
```

The default API listens on `http://127.0.0.1:8010`. Local development uses
SQLite through `SBOM_NEXUS_DATABASE_PATH`; production uses
`SBOM_NEXUS_DATABASE_URL_FILE=/var/run/secrets/.../url` and `make migrate`.
The direct `SBOM_NEXUS_DATABASE_URL` variable remains available for disposable
development environments; mounted secret files are preferred for production.

## Initial API surface

- `GET /state/health`
- `PUT /repositories/{repo_slug}`
- `GET /sbom/catch-up?limit=3`
- `POST /sbom/{repo_slug}/ingest`
- State Hub-compatible `/sbom/` snapshot, entry, repository, and licence routes

Authoritative automation may ingest a controlled `forgejo-archive-v1`
`source_ref` pinned to a full commit SHA. Nexus constructs the Forgejo URL,
streams and safely extracts the archive within configured limits, records the
archive and manifest provenance, and removes the transient directory. It does
not accept arbitrary source URLs. `Idempotency-Key` is durably enforced on
repository ingest and skip operations; a matching retry replays the original
snapshot outcome and conflicting key reuse returns HTTP 409.

See [docs/state-hub-sbom-extraction-review.md](docs/state-hub-sbom-extraction-review.md)
for the extraction inventory and cutover dispositions.