Help us shape the future of Go! Take the 2026 Go Developer Survey

releaseindex

package
v0.55.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 2, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PreviewCandidateProvenanceSchema       = "stackkits.preview-candidate-provenance/v1"
	PreviewCandidateIndexSchema            = "stackkits.preview-candidate-index/v1"
	PreviewCandidateIndexName              = "stackkits-preview-candidate-index-v1.json"
	PreviewCandidatePayloadAttestationName = "payload.intoto.jsonl"
)
View Source 
const (
	SchemaVersion                          = "stackkits-release-index/v1"
	ReceiptSchemaVersion                   = "stackkit.release-receipt/v1"
	ReleaseIndexAssetName                  = "stackkits-release-index-v1.json"
	ReleaseIndexAttestationAssetName       = "stackkits-release-index-v1.json.intoto.jsonl"
	TrustedRootAssetName                   = "sigstore-trusted-root.jsonl"
	ReleaseReceiptName                     = "release-receipt.json"
	SPDXJSONMediaType                      = "application/spdx+json"
	InTotoJSONLMediaType                   = "application/vnd.in-toto+jsonl"
	GitHubOIDCIssuer                       = "https://token.actions.githubusercontent.com"
	GitHubAttestationPredicate             = "https://slsa.dev/provenance/v1"
	SigstoreTrustedRootMediaType           = "application/vnd.dev.sigstore.trustedroot+json;version=0.1"
	DefaultMaxBlobBytes              int64 = 4 << 30
)

Variables

View Source 
var (
	ErrDigestMismatch = errors.New("release blob digest mismatch")
	ErrNoRelease      = errors.New("no matching StackKits release")
)

Functions

func CacheInstallationDirectory added in v0.52.6 

func CacheInstallationDirectory(cacheDirectory, kit, tag string, platform Platform) (string, error)

CacheInstallationDirectory confines both existing and missing cache paths; a missing leaf under a linked ancestor is never treated as an absent cache.

func ExactTagForBuildVersion 

func ExactTagForBuildVersion(buildVersion string) (string, error)

ExactTagForBuildVersion converts the release build value embedded by GoReleaser into the one exact GitHub tag that publishes it.

func PreviewSourceCacheDirectory added in v0.54.10 

func PreviewSourceCacheDirectory(cache string, selector PreviewSourceSelector) (string, error)

Types

type Asset 

type Asset struct {
	Kit         string      `json:"kit"`
	Version     string      `json:"version"`
	Channel     Channel     `json:"channel"`
	Platform    Platform    `json:"platform"`
	Archive     Blob        `json:"archive"`
	SBOM        Blob        `json:"sbom"`
	Attestation Attestation `json:"attestation"`
}

type Attestation 

type Attestation struct {
	Blob
	Issuer              string `json:"issuer"`
	CertificateIdentity string `json:"certificateIdentity"`
	Subject             string `json:"subject"`
	PredicateType       string `json:"predicateType"`
}

type AttestationInput 

type AttestationInput struct {
	Index           Index
	Asset           Asset
	ArchivePath     string
	SBOMPath        string
	BundlePath      string
	TrustedRootPath string
}

type AttestationVerifier 

type AttestationVerifier interface {
	Verify(context.Context, AttestationInput) error
	VerifyIndex(context.Context, IndexAttestationInput) error
}

type AttestedPreviewCandidateIdentity added in v0.54.10 

type AttestedPreviewCandidateIdentity struct {
	Source                   PreviewCandidateSource   `json:"source"`
	Producer                 PreviewCandidateProducer `json:"producer"`
	IndexSHA256              string                   `json:"indexSha256"`
	ArchiveSHA256            string                   `json:"archiveSha256"`
	IndexAttestationSHA256   string                   `json:"indexAttestationSha256,omitempty"`
	PayloadAttestationSHA256 string                   `json:"payloadAttestationSha256,omitempty"`
	TrustedRootSHA256        string                   `json:"trustedRootSha256,omitempty"`
	SBOMSHA256               string                   `json:"sbomSha256,omitempty"`
	BuildProfile             CandidateBuildProfile    `json:"buildProfile,omitempty"`
	BuildTags                []string                 `json:"buildTags,omitempty"`
}

AttestedPreviewCandidateIdentity deliberately excludes the caller-admitted artifact metadata, which the offline signature cannot authenticate.

type Blob 

type Blob struct {
	Name      string `json:"name"`
	URL       string `json:"url"`
	SHA256    string `json:"sha256"`
	MediaType string `json:"mediaType"`
}

type CandidateBuildProfile added in v0.54.10 

type CandidateBuildProfile string

CandidateBuildProfile discloses the compiler variant, independently of the runtime data profile. Historical candidates without this disclosure are Standard. 

const (
	CandidateStandard  CandidateBuildProfile = "standard"
	CandidateFullLocal CandidateBuildProfile = "full-local"
	FullLocalBuildTag                        = "kombify_full_local"
)

type Channel 

type Channel string
const (
	ChannelStable Channel = "stable"
	ChannelBeta   Channel = "beta"
	ChannelEdge   Channel = "edge"
)

type FixtureSource 

type FixtureSource struct {
	// contains filtered or unexported fields
}

FixtureSource is a hermetic in-memory release source for contract and OSS E2E tests. Product code depends only on Source; it never branches on fixture mode.

func NewFixtureSource 

func NewFixtureSource() *FixtureSource

func (*FixtureSource) AddRelease 

func (source *FixtureSource) AddRelease(index Index, prerelease bool, publishedAt time.Time) error

func (*FixtureSource) Fetch 

func (source *FixtureSource) Fetch(_ context.Context, url string, limit int64) ([]byte, error)

func (*FixtureSource) ListReleases 

func (source *FixtureSource) ListReleases(context.Context) ([]Release, error)

func (*FixtureSource) SetBlob 

func (source *FixtureSource) SetBlob(url string, data []byte)

type GitHubSource 

type GitHubSource struct {
	Client     *http.Client
	APIBaseURL string
	Repository string
}

func NewGitHubFixtureSource 

func NewGitHubFixtureSource(client *http.Client, apiBaseURL string) (*GitHubSource, error)

NewGitHubFixtureSource creates the hermetic HTTP adapter used by the standalone OSS E2E. It deliberately accepts only loopback and the reserved .localhost namespace; public release URLs retain the GitHub-only policy.

func NewGitHubSource 

func NewGitHubSource(client *http.Client) *GitHubSource

func (*GitHubSource) Fetch 

func (source *GitHubSource) Fetch(ctx context.Context, location string, limit int64) ([]byte, error)

func (*GitHubSource) GetRelease added in v0.52.6 

func (source *GitHubSource) GetRelease(ctx context.Context, tag string) (Release, error)

GetRelease resolves one exact tag independently of the newest release page. It provides metadata only: Resolver and Installer still authenticate every index, archive and cached receipt before an executable can be used.

func (*GitHubSource) ListReleases 

func (source *GitHubSource) ListReleases(ctx context.Context) ([]Release, error)

type Index 

type Index struct {
	SchemaVersion string            `json:"schemaVersion"`
	Release       ReleaseDescriptor `json:"release"`
	Assets        []Asset           `json:"assets"`
}

func Decode 

func Decode(raw []byte) (Index, error)

func (Index) Validate 

func (index Index) Validate() error

type IndexAttestationInput 

type IndexAttestationInput struct {
	Version     string
	Index       []byte
	Bundle      []byte
	TrustedRoot []byte
}

type Installer 

type Installer struct {
	Source       Source
	Attestations AttestationVerifier
	MaxBlobBytes int64
	Now          func() time.Time
}

func (Installer) InspectInstalled 

func (installer Installer) InspectInstalled(
	ctx context.Context,
	installDir string,
	inspect func(VerifiedInstallation) error,
) error

InspectInstalled re-verifies an installed release and returns an immutable proof containing the exact bounded archive bytes verified in this operation.

func (Installer) InspectVerifiedArchive 

func (installer Installer) InspectVerifiedArchive(ctx context.Context, resolution Resolution, inspect func(VerifiedArchive) error) error

InspectVerifiedArchive downloads and verifies one resolved release in a process-owned temporary directory without installing or caching anything in the Stack workspace. The callback cannot retain the paths after it returns.

func (Installer) Install 

func (installer Installer) Install(ctx context.Context, resolution Resolution, workspaceRoot string) (Receipt, error)

func (Installer) InstallToCache added in v0.52.6 

func (installer Installer) InstallToCache(ctx context.Context, resolution Resolution, cacheDirectory string, inspect func(VerifiedInstallation) error) (Receipt, error)

InstallToCache uses the same public trust chain and canonical receipt, with an explicitly selected cache directory independent of a runtime workspace.

func (Installer) VerifyInstalled 

func (installer Installer) VerifyInstalled(ctx context.Context, installDir string) (Receipt, error)

func (Installer) VerifyWorkspace 

func (installer Installer) VerifyWorkspace(ctx context.Context, workspaceRoot, kit string, platform Platform) ([]Receipt, error)

VerifyWorkspace re-verifies every cached release receipt for one kit and platform without consulting the release source or making network requests.

type Platform 

type Platform struct {
	OS   string `json:"os"`
	Arch string `json:"arch"`
}

type PreviewCandidateArtifact added in v0.54.10 

type PreviewCandidateArtifact struct {
	ID     string `json:"id"`
	SHA256 string `json:"sha256"`
}

type PreviewCandidateBlob added in v0.54.10 

type PreviewCandidateBlob struct {
	Name   string `json:"name"`
	SHA256 string `json:"sha256"`
}

type PreviewCandidateInput added in v0.54.10 

type PreviewCandidateInput struct {
	Expected                                                 PreviewCandidateProvenance
	Kit                                                      string
	Platform                                                 Platform
	ArchiveSHA256                                            string
	Index, IndexAttestation, PayloadAttestation, TrustedRoot []byte
	Archive, SBOM                                            []byte
}

PreviewCandidateInput requires the exact index and selected payload bytes. Expected is selected only from the authenticated installed Stage admission, never from the downloaded index or an arbitrary caller-supplied receipt.

type PreviewCandidateProducer added in v0.54.10 

type PreviewCandidateProducer struct {
	Workflow    string `json:"workflow"`
	WorkflowRef string `json:"workflowRef"`
	WorkflowSHA string `json:"workflowSha"`
	RunID       string `json:"runId"`
	RunAttempt  string `json:"runAttempt"`
	Event       string `json:"event"`
}

type PreviewCandidateProvenance added in v0.54.10 

type PreviewCandidateProvenance struct {
	SchemaVersion            string                   `json:"schemaVersion"`
	IndexSHA256              string                   `json:"indexSha256"`
	IndexAttestationSHA256   string                   `json:"indexAttestationSha256"`
	PayloadAttestationSHA256 string                   `json:"payloadAttestationSha256"`
	TrustedRootSHA256        string                   `json:"trustedRootSha256"`
	Artifact                 PreviewCandidateArtifact `json:"artifact"`
	Source                   PreviewCandidateSource   `json:"source"`
	Producer                 PreviewCandidateProducer `json:"producer"`
}

PreviewCandidateProvenance is the frozen cross-product identity. It carries no installation permission. Its artifact identity must come from separately authenticated GitHub metadata retained by the signed Stage admission.

func DecodePreviewCandidateProvenance added in v0.54.10 

func DecodePreviewCandidateProvenance(raw []byte) (PreviewCandidateProvenance, error)

DecodePreviewCandidateProvenance is the strict JSON boundary for installed signed admissions. It authenticates no metadata by itself.

func (PreviewCandidateProvenance) Validate added in v0.54.10 

func (provenance PreviewCandidateProvenance) Validate() error

type PreviewCandidateSource added in v0.54.10 

type PreviewCandidateSource struct {
	Repository string `json:"repository"`
	Commit     string `json:"commit"`
	Tree       string `json:"tree"`
	ExportTree string `json:"exportTree"`
}

type PreviewSourceCacheProof added in v0.54.10 

type PreviewSourceCacheProof struct {
	SchemaVersion            string                   `json:"schemaVersion"`
	Kit                      string                   `json:"kit"`
	Version                  string                   `json:"version"`
	Platform                 Platform                 `json:"platform"`
	IndexSHA256              string                   `json:"indexSha256"`
	ArchiveSHA256            string                   `json:"archiveSha256"`
	CLISHA256                string                   `json:"cliSha256"`
	IndexAttestationSHA256   string                   `json:"indexAttestationSha256"`
	PayloadAttestationSHA256 string                   `json:"payloadAttestationSha256"`
	TrustedRootSHA256        string                   `json:"trustedRootSha256"`
	SBOMSHA256               string                   `json:"sbomSha256"`
	Source                   PreviewCandidateSource   `json:"source"`
	Producer                 PreviewCandidateProducer `json:"producer"`
	BuildProfile             CandidateBuildProfile    `json:"buildProfile,omitempty"`
	BuildTags                []string                 `json:"buildTags,omitempty"`
}

type PreviewSourceSelector added in v0.54.10 

type PreviewSourceSelector struct {
	Kit, Version                          string
	Platform                              Platform
	IndexSHA256, ArchiveSHA256, CLISHA256 string
}

PreviewSourceSelector selects bytes, never installation authority. Every readback re-verifies the canonical offline signature policy. Artifact IDs retained beside those bytes remain untrusted and are not exported as proof.

func PreviewSourceSelectorFromIndex added in v0.54.10 

func PreviewSourceSelectorFromIndex(raw []byte, version string, platform Platform, indexSHA256, archiveSHA256, cliSHA256 string) (PreviewSourceSelector, error)

PreviewSourceSelectorFromIndex resolves metadata only. A deployment's kit label is not necessarily the packaged bootstrap archive's kit. The exact independently selected index/archive digests choose one asset; the opaque Sigstore verifier and executable equality still decide whether it is proof.

type Receipt 

type Receipt struct {
	SchemaVersion          string    `json:"schemaVersion"`
	Kit                    string    `json:"kit"`
	Version                string    `json:"version"`
	Channel                Channel   `json:"channel"`
	Platform               Platform  `json:"platform"`
	ArchiveSHA256          string    `json:"archiveSha256"`
	SBOMSHA256             string    `json:"sbomSha256"`
	AttestationSHA256      string    `json:"attestationSha256"`
	AttestationIssuer      string    `json:"attestationIssuer"`
	AttestationSubject     string    `json:"attestationSubject"`
	TrustedRootSHA256      string    `json:"trustedRootSha256"`
	IndexSHA256            string    `json:"indexSha256"`
	IndexAttestationSHA256 string    `json:"indexAttestationSha256"`
	VerifiedAt             time.Time `json:"verifiedAt"`
	InstallDir             string    `json:"installDir"`
}

type Release 

type Release struct {
	TagName             string
	Prerelease          bool
	PublishedAt         time.Time
	IndexURL            string
	IndexAttestationURL string
	TrustedRootURL      string
}

type ReleaseDescriptor 

type ReleaseDescriptor struct {
	Repository  string    `json:"repository"`
	Version     string    `json:"version"`
	PublishedAt time.Time `json:"publishedAt"`
	TrustedRoot Blob      `json:"trustedRoot"`
}

type Resolution 

type Resolution struct {
	Release             Release
	Index               Index
	Asset               Asset
	RawIndex            []byte
	RawIndexAttestation []byte
	RawTrustedRoot      []byte
}

type ResolveRequest 

type ResolveRequest struct {
	Kit    string
	Target string
	OS     string
	Arch   string
}

type Resolver 

type Resolver struct {
	Source       Source
	Attestations AttestationVerifier
}

func (Resolver) Resolve 

func (resolver Resolver) Resolve(ctx context.Context, request ResolveRequest) (Resolution, error)

type SigstoreVerifier 

type SigstoreVerifier struct {
	// contains filtered or unexported fields
}

SigstoreVerifier verifies a cached GitHub artifact-attestation bundle against the exact cached trusted root, archive digest, GitHub OIDC issuer, workflow identity, predicate type, and subject name declared by the release index. It performs no network requests.

trustedRootDocumentSHA256 exists for same-package hermetic tests. Production callers cannot set it and are bound to the versioned policy embedded in the binary.

func (SigstoreVerifier) InspectPreviewSourceCache added in v0.54.10 

func (verifier SigstoreVerifier) InspectPreviewSourceCache(ctx context.Context, cache string, selector PreviewSourceSelector, inspect func(VerifiedPreviewCandidate) error) error

func (SigstoreVerifier) InspectPreviewSourceDirectory added in v0.54.10 

func (verifier SigstoreVerifier) InspectPreviewSourceDirectory(ctx context.Context, directory string, selector PreviewSourceSelector, inspect func(VerifiedPreviewCandidate) error) error

func (SigstoreVerifier) RetainPreviewSourceCache added in v0.54.10 

func (verifier SigstoreVerifier) RetainPreviewSourceCache(ctx context.Context, cache, source string, selector PreviewSourceSelector, inspect func(VerifiedPreviewCandidate) error) error

RetainPreviewSourceCache acquires only verified immutable bytes. The caller's callback must match the archive executable against its exact source selector. Existing entries are verified and refused on corruption, never overwritten.

func (SigstoreVerifier) Verify 

func (verifier SigstoreVerifier) Verify(ctx context.Context, input AttestationInput) error

func (SigstoreVerifier) VerifyIndex 

func (verifier SigstoreVerifier) VerifyIndex(ctx context.Context, input IndexAttestationInput) error

func (SigstoreVerifier) VerifyPreviewCandidate added in v0.54.10 

func (verifier SigstoreVerifier) VerifyPreviewCandidate(ctx context.Context, input PreviewCandidateInput) (VerifiedPreviewCandidate, error)

VerifyPreviewCandidate preserves the public tag trust policy. Candidate identity is explicit and adds certificate-bound source, signer, hosted runner and exact run invocation requirements to the same pinned-root verifier.

type Source 

type Source interface {
	ListReleases(context.Context) ([]Release, error)
	Fetch(context.Context, string, int64) ([]byte, error)
}

type VerifiedArchive 

type VerifiedArchive struct {
	ArchivePath     string
	SBOMPath        string
	AttestationPath string
	TrustedRootPath string
}

VerifiedArchive is a short-lived, fully verified release payload. Paths are valid only for the duration of InspectVerifiedArchive's callback.

type VerifiedInstallation 

type VerifiedInstallation struct {
	// contains filtered or unexported fields
}

VerifiedInstallation is an immutable proof of one offline-verified cached release. Its private token and fields make the zero value invalid and prevent another package from fabricating or mutating release authority.

func (VerifiedInstallation) Inspect 

func (installation VerifiedInstallation) Inspect(
	inspect func(Receipt, Asset, io.Reader) error,
) error

Inspect exposes defensive copies only after validating the package-private proof token and the retained archive digest.

type VerifiedPreviewCandidate added in v0.54.10 

type VerifiedPreviewCandidate struct {
	// contains filtered or unexported fields
}

VerifiedPreviewCandidate proves only the offline private build provenance. It is deliberately unrelated to VerifiedInstallation and the public Receipt. Stage installation still needs authenticated assignment/Guard custody. The imagepreparation owner may separately admit a fresh neutral bundle only after full profile, process, five-tool, provider, image and model verification.

func (VerifiedPreviewCandidate) Inspect added in v0.54.10 

func (candidate VerifiedPreviewCandidate) Inspect(inspect func(AttestedPreviewCandidateIdentity, string, string, Platform, io.Reader) error) error

func (VerifiedPreviewCandidate) SourceCacheProof added in v0.54.10 

func (candidate VerifiedPreviewCandidate) SourceCacheProof(cliSHA256 string) (PreviewSourceCacheProof, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.