VerseVDI-Data-Plane/openspec/changes/archive/2026-08-10-deterministic-gateway-sbom/design.md

Context

The repository already produces reproducible pure-Go Linux binaries and can read exact Go module/build metadata. A standard deterministic document is missing; adding an external SBOM tool is unnecessary for this bounded artifact.

Goals / Non-Goals

Goals:

• Generate byte-stable SPDX 2.3 JSON with Go standard library encoding.
• Describe the repository, Protocol dependency, all resolved modules, both Linux binaries, relationships, hashes, architectures, notices, and truthful licenses.

Non-Goals:

• Vulnerability scanning, signing, image remediation, public release, or inferred license conclusions.

Decisions

• Use a small repository command that reads each binary with debug/buildinfo, verifies Linux architecture and cgo settings, and compares embedded module inventories before sorting every package and relationship.
• Use fixed SPDX identifiers and a source-date timestamp supplied by the caller; reject dirty/ambiguous inputs rather than embedding current time.
• Use NOASSERTION for unavailable concluded/declared license evidence and record no vulnerability result.

Risks / Trade-offs

• [Go module metadata lacks complete license conclusions] → retain notices and use NOASSERTION.
• [Artifact paths make output host-dependent] → encode architecture, filename, size, and digest only.
• [A hand-built serializer could drift] → validate required SPDX fields and require byte-identical double generation.