tegwick
84952c5212
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
72 lines
2.9 KiB
Markdown
72 lines
2.9 KiB
Markdown
# SBOM Nexus client contract v1
|
|
|
|
Repo Manager consumes SBOM Nexus; it does not implement a second scanner,
|
|
snapshot store, freshness model, licence classifier, or catch-up scheduler.
|
|
This contract pins the boundary used by `RMGR-WP-0011`.
|
|
|
|
## Authority modes
|
|
|
|
| Mode | Surface | Authoritative | Persisted | Advances Nexus state |
|
|
| --- | --- | --- | --- | --- |
|
|
| Local preview | `rmgr sbom scan|licence-report` → `sbom-nexus scan` | no | no | no |
|
|
| Service operation | configured SBOM Nexus HTTP client | yes | Nexus decides | yes, according to the route outcome |
|
|
|
|
Every compatibility-command result carries:
|
|
|
|
```json
|
|
{
|
|
"repo_manager_context": {
|
|
"mode": "local-preview",
|
|
"authoritative": false,
|
|
"persisted": false,
|
|
"advances_last_attempt_at": false,
|
|
"advances_last_success_at": false,
|
|
"creates_snapshot_history": false
|
|
}
|
|
}
|
|
```
|
|
|
|
Writing preview JSON to a file creates optional local evidence only. It does
|
|
not turn the result into an authoritative snapshot or ingest receipt.
|
|
|
|
## Pinned snapshot envelope
|
|
|
|
Repo Manager accepts `schema: sbom-nexus.snapshot.v1`. Additive fields are
|
|
compatible. An unknown schema or omission of any of these fields is a contract
|
|
error: `schema`, `ok`, `repo_slug`, `source_revision`, `generated_at`,
|
|
`entry_count`, `entries`, `sources`, `licence_report`, and `errors`.
|
|
|
|
Repo Manager may project the existing licence-report compatibility shape from
|
|
that envelope. It must not recalculate licence groups or copyleft signals.
|
|
|
|
## Authoritative service routes
|
|
|
|
The production client may consume these Nexus-owned routes without depending
|
|
on Nexus tables or migrations:
|
|
|
|
| Purpose | Route |
|
|
| --- | --- |
|
|
| Upsert repository projection | `PUT /repositories/{repo_slug}` |
|
|
| Read repository projections | `GET /repositories/` |
|
|
| Persist scan outcome | `POST /sbom/{repo_slug}/ingest` |
|
|
| Persist terminal skip outcome | `POST /sbom/{repo_slug}/skip` |
|
|
| Read latest repository SBOM | `GET /sbom/{repo_slug}` |
|
|
| Read immutable snapshot detail | `GET /sbom/snapshots/{snapshot_id}` |
|
|
| Read licence report | `GET /sbom/report/licences/` |
|
|
|
|
Calls use a bounded timeout and surface deterministic transport, HTTP, and
|
|
contract errors. Credentials enter only through the platform runtime path and
|
|
must never appear in files, command output, or logs.
|
|
|
|
## Repository source identity and provenance
|
|
|
|
Repo Manager remains authoritative for repository slug, active state,
|
|
checkout/source identity, and Git revision. An authoritative scan request must
|
|
refer to a controlled source artifact or checkout pinned to that revision. It
|
|
must not infer identity from a path string or repository name, and it must not
|
|
mount a workstation filesystem into the cluster.
|
|
|
|
`CUST-WP-0064` owns the coordinated source-input topology. Until that topology
|
|
is live, local checkout scans remain previews even when their Git revision is
|
|
known. SBOM Nexus alone records the resulting authoritative snapshot and
|
|
attempt/success history.
|