build(gateway): generate deterministic SPDX SBOM

2026-07-30 22:47:55 +07:00
parent 786c96b110
commit 08eb6dc36c
10 changed files with 570 additions and 3 deletions
@@ -0,0 +1,28 @@
+## 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.