Documentation
¶
Overview ¶
Package application holds the standard-library chain-of-custody use-case: it acquires the canonical source tarball, verifies its integrity against Go's published checksum, records the VCS anchor, computes the artefact digests, extracts the licence, and caches the derived facts by Go version.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUndeterminableVersion = errors.New("stdlib: undeterminable go version")
ErrUndeterminableVersion means the supplied toolchain string yielded no usable Go version, so no release tarball can be requested.
Functions ¶
This section is empty.
Types ¶
type Acquirer ¶
type Acquirer struct {
// contains filtered or unexported fields
}
Acquirer establishes the standard library's chain of custody. It is safe for concurrent use once constructed.
func NewAcquirer ¶
func NewAcquirer( manifest ports.ManifestClient, tarballs ports.TarballClient, commits ports.CommitResolver, licenses ports.LicenseIdentifier, store ports.Store, blobs fetchports.BlobStore, clock fetchports.Clock, logger *slog.Logger, ) *Acquirer
NewAcquirer constructs an Acquirer. blobs may be nil, in which case the source tarball is verified and hashed but not cached in the blob store (the derived facts are still cached by the Store).
func (*Acquirer) Acquire ¶
func (a *Acquirer) Acquire(ctx context.Context, goVersionRaw string, opts Options) (domain.Facts, error)
Acquire establishes (or serves from cache) the chain-of-custody facts for the standard library at goVersionRaw (any toolchain form: "go1.26.4", "1.26.4", "v1.26.4"). On a cache hit and without opts.Force it returns the stored facts unchanged. Otherwise it downloads the canonical source tarball, verifies its SHA-256 against the published release manifest, resolves the googlesource commit (unless opts.SkipVCS), computes the artefact digests, extracts the BSD-3-Clause licence, caches the tarball and facts, and returns them.
A checksum mismatch is recorded as GoDevChecksumMismatch, not an error — the evidence is preserved for the SBOM rather than hidden. A manifest that could not be read is recorded as UnverifiedGoDevUnavailable, and a manifest that was read and publishes no checksum for this version as UnverifiedGoDevNotPublished. Only an undeterminable version or a failed tarball download is a hard error, since without the bytes there are no digests to record.
func (*Acquirer) WithAudit ¶
WithAudit wires an audit sink so acquisition appends one stdlib_custody_recorded event per persisted measurement. It is optional — a nil sink (the default) disables emission — and returns the receiver for chaining, mirroring the extraction stages' optional-dependency builders.
type Acquisition ¶
type Acquisition interface {
// Acquire establishes (or serves from cache) the chain-of-custody facts for
// the standard library at goVersionRaw.
Acquire(ctx context.Context, goVersionRaw string, opts Options) (domain.Facts, error)
}
Acquisition is the chain-of-custody entry point shared by the online (go.dev/dl) Acquirer and the offline LocalAcquirer, so the walk bridge can wrap either without knowing which anchor established the facts.
type LocalAcquirer ¶
type LocalAcquirer struct {
// contains filtered or unexported fields
}
LocalAcquirer establishes the standard library's chain of custody from the local Go toolchain, without any network access. It is the offline (--from-modcache) counterpart to Acquirer: instead of downloading go.dev/dl's source tarball and matching its published checksum, it anchors to the toolchain the audit itself compiles with — $GOROOT/src for the artefact digests and $GOROOT/LICENSE for the licence — and records the result as VerifiedLocalToolchain, which never claims the go.dev/dl checksum was consulted.
func NewLocalAcquirer ¶
func NewLocalAcquirer( toolchain ports.ToolchainInspector, source ports.LocalSourceReader, licenses ports.LicenseIdentifier, store ports.Store, clock fetchports.Clock, logger *slog.Logger, ) *LocalAcquirer
NewLocalAcquirer constructs a LocalAcquirer over the toolchain inspector, the local source reader, the same licence detector the online path uses, and the version-keyed fact cache.
func (*LocalAcquirer) Acquire ¶
func (a *LocalAcquirer) Acquire(ctx context.Context, goVersionRaw string, opts Options) (domain.Facts, error)
Acquire establishes (or serves from cache) the offline chain-of-custody facts for the standard library at goVersionRaw. On a cache hit without opts.Force it returns the stored facts unchanged — including facts a prior online run established, so a mixed pipeline never downgrades a stronger anchor. Otherwise it locates the local toolchain, computes the artefact digests over $GOROOT/src, extracts and classifies $GOROOT/LICENSE, and records the result as VerifiedLocalToolchain with the VCS anchor marked skipped (offline).
opts.SkipVCS is accepted for interface parity but is always effectively true: the offline path never performs a VCS lookup. Only an undeterminable version, a failed toolchain probe, or an unreadable source tree is a hard error, since without those there are no digests to record.
func (*LocalAcquirer) WithAudit ¶
func (a *LocalAcquirer) WithAudit(sink ports.AuditSink) *LocalAcquirer
WithAudit wires an audit sink so offline acquisition appends one stdlib_custody_recorded event per persisted measurement, on the same terms as the online route: the two paths write the same record, so they must leave the same trace. A nil sink (the default) disables emission.
Source Files