README
¶
sigstore
A thin sigstore-go wrapper that validates a sigstore bundle against the live (or cached) Sigstore TUF trust root. Cross-ecosystem by design: handles any (digestAlg, digest) pair, so npm tarball (sha512), GitHub artifact (sha256), PyPI distribution, Maven Central, and Cargo package attestations all use the same code path.
Install
go get github.com/git-pkgs/sigstore
Usage
import (
"crypto/sha512"
"github.com/sigstore/sigstore-go/pkg/root"
"github.com/git-pkgs/sigstore"
)
tr, err := root.FetchTrustedRoot() // or FetchTrustedRootWithOptions for a local cache
if err != nil { return err }
v := sigstore.New(tr)
digest := sha512.Sum512(artifactBytes)
err = v.VerifyBundle(ctx, bundleBytes, "sha512", digest[:])
VerifyBundle returns nil when:
- the bundle's Fulcio cert chains to the trust root,
- the Rekor inclusion proof is valid,
- the DSSE envelope signature matches the cert,
- the in-toto subject digest matches the supplied
(digestAlg, digest).
Use VerifyBundleDetailed when the caller also needs the certificate identity
and OIDC issuer, verified hex-encoded Rekor log key ID, URI, and integrated
time, in-toto subjects, or predicate data:
result, err := v.VerifyBundleDetailed(ctx, bundleBytes, "sha512", digest[:])
result.Statement contains the exact decoded DSSE payload and
result.Predicate contains its raw JSON predicate. These fields are returned
only after verification succeeds. The caller is responsible for deciding
whether result.CertificateIdentity and result.CertificateIssuer are
authorized for its use case.
Pluggable verifier pattern
Consumers typically declare a one-method interface so other verifiers (witness, SBOMit, plain in-toto) can swap in:
type ProvenanceVerifier interface {
VerifyBundle(ctx context.Context, body []byte, alg string, digest []byte) error
}
*Verifier satisfies this structurally — no shared interface package needed.
Why standalone
sigstore-go is a heavy dependency (TUF, Fulcio, Rekor, x509, protobuf). Carrying it in larger surfaces (CLIs, libraries) is wasteful when consumers only want bundle verification. Importing this package opts in explicitly.
For identity-field extraction without verification, see github.com/git-pkgs/attestation (stdlib-only).
License
MIT
Documentation
¶
Overview ¶
Package sigstore validates a sigstore bundle against the live (or cached) Sigstore TUF trust root via sigstore-go. Cross-ecosystem: handles any (digestAlg, digest) pair, so npm tarball (sha512) and GitHub artifact (sha256) attestations share the same path. PyPI, Maven, Cargo, and any other registry whose trusted-publishing flow emits a sigstore bundle work the same way.
Stdlib + sigstore-go only — no project-specific deps, so it suits consumers that need bundle verification without baking sigstore-go into a larger surface.
Consumers typically declare a one-method interface so verifiers (witness, SBOMit, plain in-toto) can swap. Verifier satisfies it structurally:
type ProvenanceVerifier interface {
VerifyBundle(ctx context.Context, body []byte, alg string, digest []byte) error
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type TransparencyLog ¶ added in v0.2.0
TransparencyLog identifies a log and the verified time at which it integrated the bundle entry. ID is the log's hex-encoded key ID when it can be uniquely matched; otherwise ID is empty.
type VerificationResult ¶ added in v0.2.0
type VerificationResult struct {
CertificateIdentity string
CertificateIssuer string
TransparencyLogs []TransparencyLog
Subjects []Subject
PredicateType string
Statement json.RawMessage
Predicate json.RawMessage
}
VerificationResult contains metadata whose integrity was established by bundle verification. CertificateIdentity and CertificateIssuer describe the signer but do not authorize it.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier wraps a Sigstore trust root. Construct via New.
func New ¶
func New(trustedRoot *root.TrustedRoot) *Verifier
New binds the Verifier to a trust root. Fetch the root via sigstore-go's root.FetchTrustedRoot or FetchTrustedRootWithOptions (the latter supports a local cache directory).
func (*Verifier) VerifyBundle ¶
func (v *Verifier) VerifyBundle(ctx context.Context, bundleBody []byte, digestAlg string, digest []byte) error
VerifyBundle returns nil when the Fulcio cert chains to the trust root, the Rekor inclusion proof is valid, the DSSE signature matches the cert, and the in-toto subject digest matches (digestAlg, digest). digestAlg is "sha256" or "sha512".
func (*Verifier) VerifyBundleDetailed ¶ added in v0.2.0
func (v *Verifier) VerifyBundleDetailed(_ context.Context, bundleBody []byte, digestAlg string, digest []byte) (*VerificationResult, error)
VerifyBundleDetailed verifies a bundle like VerifyBundle and returns metadata covered by that verification. The result describes the signer and signed statement. Deciding whether the signer is authorized remains the caller's responsibility.
Source Files