artifact

package
v0.9.2 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Overview

Package artifact defines Brewlet application and layer-set artifacts.

Producers supply explicit launch bytes, platforms and source/destination mappings. Build preserves launch bytes and source modes/mtimes, rejects all source xattrs, and uses sorted root-owned tar entries and fixed compression. ParseLaunch, ParseImage, ValidateMirror and RunFixtures are the shared wire validators. Resolve accepts a local BlobOpener and never contacts registries.

MaterializeLayers provides portable flattened composition in a new destination. LayerCache provides digest-and-policy-keyed persistent overlay lower directories; Linux whiteout conversion requires the corresponding host privileges. Callers run materializers as root to obtain ownership 0:0, validate cache-parent ownership, and own durable cache leases and mount-aware collection. The package does not implement node cache GC, CRI accounting, or runtime authorization.

Each layer is extracted independently. Its implicit upper directories shadow inherited directory symlinks, matching the reverse-ordered overlay lowers. Visible link targets are checked against the composed namespace without lexically collapsing ".." before preceding symlinks are resolved.

Every layer set has exactly one CycloneDX 1.5 SBOM referrer. With an explicit lock, components mirror its ecosystem/name/version/path/hash and optional author-supplied group/purl. Without a lock, components are file inventories, not inferred dependency identities. Maven owns its BOM/GAV graph and supplies its group and Maven package URL explicitly; generic code never detects Java.

Optional layer-set provenance uses ECDSA-P256 DSSE and an in-toto Statement v1. Its predicate type is LayerSetPredicateType and LayerSetPredicate binds the manifest, config, ordered layer/diff-ID pairs, optional lock, SBOM blob and builder identity. Presence of any provenance requires explicit public keys and expected signer identity; at least one complete candidate must validate. Referrers are discovered through OCI layout indexes, the paginated registry Referrers API, or paginated deterministic per-referrer digest tags.

VerifyGraph and the push CLI command are byte-preserving OCI transport, not Brewlet semantic validators. They can publish ordinary approved-runtime inputs and negative conformance fixtures. Normal push still validates the launch and layers, and runtime consumers independently enforce the contract.

Package artifact implements the language-neutral Brewlet wire contract.

Index

Constants

View Source
const (
	MediaTypeLayerSet       = "application/vnd.brewlet.layerset.v1+json"
	MediaTypeLayerSetConfig = "application/vnd.brewlet.layerset.config.v1+json"
	MediaTypeLayerSetLock   = "application/vnd.brewlet.layerset.lock.v1+json"
)
View Source
const (
	MediaTypeCycloneDX        = "application/vnd.cyclonedx+json"
	MediaTypeAttestation      = "application/vnd.brewlet.attestation.v1+json"
	MediaTypeDSSE             = "application/vnd.dsse.envelope.v1+json"
	LayerSetPredicateType     = "https://brewlet.sh/attestations/layerset/v1"
	InTotoPayloadType         = "application/vnd.in-toto+json"
	AnnotationReferrerSubject = "brewlet.sh/referrer-subject"
)
View Source
const (
	MediaTypeComposition     = "application/vnd.brewlet.composition.v1+json"
	CompositionPredicateType = "https://brewlet.sh/attestations/composition/v1"
)
View Source
const PolicyVersion = "v1-3"

Variables

This section is empty.

Functions

func Build

func Build(ctx context.Context, store Store, o BuildOptions) (v1.Descriptor, error)

func BuildIndex

func BuildIndex(ctx context.Context, store Store, descriptorFiles []string) (v1.Descriptor, error)

BuildIndex accepts only explicitly supplied descriptors. Their blobs must already be present in the store, and each selected artifact is verified.

func BuildLayerSet

func BuildLayerSet(ctx context.Context, store Store, config LayerSetConfig, layers []LayerSpec, lock *LayerSetLock, options ...LayerSetPublishOptions) (v1.Descriptor, error)

func CompositionMaterials

func CompositionMaterials(store Store, subject v1.Descriptor) ([]v1.Descriptor, error)

CompositionMaterials returns the immutable supporting graphs to transport with a composed image. It parses bindings only; it does not authorize them.

func ConsumeLayerSet

func ConsumeLayerSet(ctx context.Context, store Store, target v1.Descriptor, trusts ...LayerSetTrust) ([]BuiltLayer, LayerSetEvidence, error)

func CopyGraph

func CopyGraph(ctx context.Context, source, destination Store, target v1.Descriptor) error

func MaterializeLayers

func MaterializeLayers(ctx context.Context, sources []LayerSource, destination string) error

MaterializeLayers creates a flattened, verified /app tree in a newly published destination. The caller must own the parent directory. No existing destination is ever replaced. Runtime roots and live stages must never be supplied here.

func ParseImage

func ParseImage(data []byte) (v1.Image, error)

ParseImage validates image execution fields which OCI's Image type intentionally does not model (for example Docker Healthcheck) before typed decoding drops them.

func ParsePlatform

func ParsePlatform(s string) (v1.Platform, error)

func ParseSigningKey

func ParseSigningKey(data []byte) (*ecdsa.PrivateKey, error)

func ParseTrustKey

func ParseTrustKey(data []byte) (*ecdsa.PublicKey, error)

func Reason

func Reason(err error) string

func ReferrerTag

func ReferrerTag(subject v1.Descriptor, referrer v1.Descriptor) string

func StrictJSON

func StrictJSON(data []byte, dst any) error

StrictJSON rejects unknown fields, duplicate object members, and trailing data.

func ValidateComposition

func ValidateComposition(ctx context.Context, sources []LayerSource) error

ValidateComposition models reverse-ordered overlay lowers, including implicit upper directories which shadow inherited symlinks, then resolves every visible symlink against the composed namespace before a mount can expose it.

func ValidateEvidence

func ValidateEvidence(m v1.Manifest) error

ValidateEvidence checks that evidence references only dependency descriptors actually present in the application manifest.

func ValidateMirror

func ValidateMirror(l *Launch, image v1.Image) error

func ValidateRuntimeImageID

func ValidateRuntimeImageID(id string) error

func VerifyGraph

func VerifyGraph(ctx context.Context, store Store, target v1.Descriptor) error

VerifyGraph checks the identity of every referenced OCI blob, including local referrers, without applying Brewlet launch, rootfs, or layer-set policy. Layers are hashed as streams and are never decompressed or rewritten.

Types

type BlobOpener

type BlobOpener func(v1.Descriptor) (io.ReadCloser, error)

type BuildOptions

type BuildOptions struct {
	Launch        []byte
	Platforms     []v1.Platform
	Layers        []LayerSpec
	LayerSets     []v1.Descriptor
	LayerSetTrust LayerSetTrust
}

type BuiltLayer

type BuiltLayer struct {
	Descriptor v1.Descriptor `json:"descriptor"`
	DiffID     digest.Digest `json:"diffId"`
}

func BuildLayer

func BuildLayer(ctx context.Context, store Store, spec LayerSpec) (BuiltLayer, error)

type CacheReceipt

type CacheReceipt struct {
	Policy      string    `json:"policy"`
	Digest      string    `json:"digest"`
	DiffID      string    `json:"diffId"`
	PublishedAt time.Time `json:"publishedAt"`
}

func VerifyCachedEntry

func VerifyCachedEntry(directory string) (string, CacheReceipt, error)

VerifyCachedEntry checks a canonical published entry without following a symlink for its directory, receipt, or rootfs. The caller supplies a trusted root-owned parent and holds its GC/start barrier for the entire decision. Missing or malformed receipts are uncertainty, never permission to collect.

type ComposeOptions

type ComposeOptions struct {
	Application   v1.Descriptor
	DependencySet v1.Descriptor
	Platform      v1.Platform
	Policy        ReleasePolicy
	Signer        *LayerSetSigner
	Launch        []byte
}

type CompositionInspection

type CompositionInspection struct {
	SchemaVersion        int                  `json:"schemaVersion"`
	Structural           bool                 `json:"structural"`
	PublisherProvenance  bool                 `json:"publisherProvenance"`
	CompositionSignature bool                 `json:"compositionSignature"`
	TestReleaseApproval  string               `json:"testReleaseApproval"`
	PolicyMode           string               `json:"policyMode"`
	Attestation          v1.Descriptor        `json:"attestation"`
	Predicate            CompositionPredicate `json:"predicate"`
}

func Compose

func VerifyComposition

func VerifyComposition(ctx context.Context, store Store, target v1.Descriptor, platform v1.Platform, policy ReleasePolicy) (CompositionInspection, error)

type CompositionPredicate

type CompositionPredicate struct {
	SchemaVersion       int              `json:"schemaVersion"`
	Output              digest.Digest    `json:"output"`
	Platform            v1.Platform      `json:"platform"`
	SourceRoot          v1.Descriptor    `json:"sourceRoot"`
	SourceManifest      v1.Descriptor    `json:"sourceManifest"`
	ApplicationRoot     v1.Descriptor    `json:"applicationRoot"`
	ApplicationManifest v1.Descriptor    `json:"applicationManifest"`
	ApplicationLayers   []BuiltLayer     `json:"applicationLayers"`
	DependencySet       v1.Descriptor    `json:"dependencySet"`
	DependencyEvidence  LayerSetEvidence `json:"dependencyEvidence"`
	OriginalLaunch      BuiltLayer       `json:"originalLaunch"`
	InputLaunch         BuiltLayer       `json:"inputLaunch"`
	EffectiveLaunch     BuiltLayer       `json:"effectiveLaunch"`
	OutputConfig        v1.Descriptor    `json:"outputConfig"`
	ParentComposition   digest.Digest    `json:"parentComposition,omitempty"`
	BuilderIdentity     string           `json:"builderIdentity,omitempty"`
}

type ContentCache

type ContentCache struct {
	Dir       string
	IsMissing func(error) bool
	// contains filtered or unexported fields
}

func (*ContentCache) Open

Open always checks the source first. Only a genuinely absent source permits retained bytes; corrupt/present, inaccessible and rejected content fails. Compressed payloads are copied/hashed as streams, never loaded into memory.

func (*ContentCache) References

func (c *ContentCache) References() []string

func (*ContentCache) Target

func (c *ContentCache) Target(ctx context.Context, target digest.Digest) (ocispec.Descriptor, error)

Target supplies the ORIGINAL target descriptor only when the caller has independently established genuine absence of the protected CRI target.

type ContentReceipt

type ContentReceipt struct {
	Policy      string             `json:"policy"`
	Descriptor  ocispec.Descriptor `json:"descriptor"`
	PublishedAt time.Time          `json:"publishedAt"`
}

ContentReceipt binds retained ORIGINAL bytes to their declaring descriptor. It is never a reconstructed manifest, config, launch document or layer.

func VerifyContentEntry

func VerifyContentEntry(ctx context.Context, entry string) (ContentReceipt, error)

type DependencyReport

type DependencyReport struct {
	Verification CompositionInspection `json:"verification"`
	Packages     []LockEntry           `json:"packages"`
	SBOM         json.RawMessage       `json:"sbom"`
}

func InspectDependencies

func InspectDependencies(ctx context.Context, store Store, target v1.Descriptor, platform v1.Platform, policy ReleasePolicy) (DependencyReport, error)

InspectDependencies exports facts for external scanners, not vulnerability verdicts. The SBOM is the exact document covered by the publisher's evidence.

type Entry

type Entry struct {
	Path, Link string
	Type       byte
	Mode       int64
	ModTime    time.Time
}

type Env

type Env struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type Error

type Error struct{ Reason, Detail string }

func (*Error) Error

func (e *Error) Error() string

type Fixture

type Fixture struct {
	Name    string           `json:"name"`
	Kind    string           `json:"kind"`
	Launch  json.RawMessage  `json:"launch,omitempty"`
	Image   json.RawMessage  `json:"image,omitempty"`
	Value   string           `json:"value,omitempty"`
	Entries []FixtureEntry   `json:"entries,omitempty"`
	Layers  [][]FixtureEntry `json:"layers,omitempty"`
	Process *Process         `json:"process,omitempty"`
	Reason  string           `json:"reason,omitempty"`
}

type FixtureEntry

type FixtureEntry struct {
	Path   string            `json:"path"`
	Type   string            `json:"type"`
	Mode   int64             `json:"mode"`
	Data   string            `json:"data,omitempty"`
	Link   string            `json:"link,omitempty"`
	Xattrs map[string]string `json:"xattrs,omitempty"`
}

type FixtureResult

type FixtureResult struct {
	Name    string   `json:"name"`
	Process *Process `json:"process,omitempty"`
	Reason  string   `json:"reason,omitempty"`
	Passed  bool     `json:"passed"`
}

func EvaluateFixture

func EvaluateFixture(ctx context.Context, f Fixture) (FixtureResult, error)

EvaluateFixture is shared by producer, shim, and cross-language conformance tests.

func RunFixtures

func RunFixtures(ctx context.Context, data []byte) ([]FixtureResult, error)

type Launch

type Launch struct {
	SchemaVersion int      `json:"schemaVersion"`
	Process       Process  `json:"process"`
	RuntimeImages []string `json:"runtimeImages,omitempty"`
}

func ParseLaunch

func ParseLaunch(data []byte) (*Launch, error)

func (*Launch) Allows

func (l *Launch) Allows(id string) bool

func (*Launch) ImageConfig

func (l *Launch) ImageConfig() v1.ImageConfig

func (Launch) MarshalJSON

func (l Launch) MarshalJSON() ([]byte, error)

Preserve an explicit deny-all [] rather than dropping it through omitempty.

type LayerBinding

type LayerBinding struct {
	Digest digest.Digest `json:"digest"`
	DiffID digest.Digest `json:"diffId"`
}

type LayerCache

type LayerCache struct{ Dir string }

LayerCache stores immutable per-compressed-digest overlay lowers. Its trusted, root-owned parent must live on persistent storage. The node owns cache leases and must not collect entries with live mounts or durable task references.

func (LayerCache) Materialize

func (c LayerCache) Materialize(ctx context.Context, source LayerSource) (string, error)

type LayerInfo

type LayerInfo struct {
	DiffID  digest.Digest
	Entries []Entry
	Launch  []byte
}

func WalkLayer

func WalkLayer(ctx context.Context, src LayerSource, visit func(*tar.Header, io.Reader) error) (*LayerInfo, error)

WalkLayer verifies compressed identity and diff ID while streaming. The visitor must consume each regular file before returning; unread bytes are drained.

type LayerSetConfig

type LayerSetConfig struct {
	SchemaVersion           int            `json:"schemaVersion"`
	Name                    string         `json:"name"`
	Version                 string         `json:"version"`
	Ecosystem               string         `json:"ecosystem"`
	Layers                  []LayerBinding `json:"layers"`
	CompatibleRuntimeImages []string       `json:"compatibleRuntimeImages,omitempty"`
}

type LayerSetEvidence

type LayerSetEvidence struct {
	ManifestDigest    digest.Digest  `json:"manifestDigest"`
	ConfigDigest      digest.Digest  `json:"configDigest"`
	LockDigest        digest.Digest  `json:"lockDigest,omitempty"`
	SBOMDigest        digest.Digest  `json:"sbomDigest"`
	AttestationDigest digest.Digest  `json:"attestationDigest,omitempty"`
	Layers            []LayerBinding `json:"layers"`
}

type LayerSetLock

type LayerSetLock struct {
	SchemaVersion int         `json:"schemaVersion"`
	Entries       []LockEntry `json:"entries"`
}

type LayerSetPredicate

type LayerSetPredicate struct {
	SchemaVersion   int            `json:"schemaVersion"`
	LayerSetDigest  digest.Digest  `json:"layerSetDigest"`
	ConfigDigest    digest.Digest  `json:"layerSetConfigDigest"`
	Layers          []LayerBinding `json:"layers"`
	LockDigest      digest.Digest  `json:"layerSetLockDigest,omitempty"`
	SBOMDigest      digest.Digest  `json:"sbomDigest"`
	BuilderIdentity string         `json:"builderIdentity"`
}

type LayerSetPublishOptions

type LayerSetPublishOptions struct {
	SBOM   []byte
	Signer *LayerSetSigner
	Trust  LayerSetTrust
}

type LayerSetSigner

type LayerSetSigner struct {
	Key      *ecdsa.PrivateKey
	Identity string
}

type LayerSetTrust

type LayerSetTrust struct {
	PublicKeys        []*ecdsa.PublicKey
	ExpectedIdentity  string
	RequireProvenance bool
}

type LayerSource

type LayerSource struct {
	Descriptor v1.Descriptor
	DiffID     digest.Digest
	Open       func() (io.ReadCloser, error)
}

type LayerSpec

type LayerSpec struct {
	Role, Source, Destination string
	Platform                  *v1.Platform
}

LayerSpec describes one producer layer. A nil Platform applies the layer to every declared platform; otherwise it belongs only to that platform manifest.

func ParseLayerSpec

func ParseLayerSpec(s string) (LayerSpec, error)

ParseLayerSpec parses [OS/ARCH[/VARIANT]:]ROLE=SOURCE:/app/PATH.

type LockEntry

type LockEntry struct {
	Ecosystem string `json:"ecosystem"`
	Name      string `json:"name"`
	Version   string `json:"version"`
	Path      string `json:"path"`
	SHA256    string `json:"sha256"`
	Group     string `json:"group,omitempty"`
	PURL      string `json:"purl,omitempty"`
}

type Process

type Process struct {
	Entrypoint []string `json:"entrypoint"`
	Args       []string `json:"args,omitempty"`
	WorkingDir string   `json:"workingDir,omitempty"`
	Env        []Env    `json:"env,omitempty"`
}

type Registry

type Registry struct {
	Origin                *url.URL
	Repository, Reference string
	Username, Password    string
	Client                *http.Client
	// contains filtered or unexported fields
}

func NewRegistry

func NewRegistry(ref string, insecure bool) (*Registry, error)

func (*Registry) FetchBlob

func (r *Registry) FetchBlob(ctx context.Context, d digest.Digest, max int64) ([]byte, error)

FetchBlob fetches a small blob such as an image config, bounded by max bytes, and verifies its digest.

func (*Registry) FetchManifest

func (r *Registry) FetchManifest(ctx context.Context, key string) (v1.Descriptor, []byte, error)

FetchManifest fetches the manifest or index named by key (a tag or a digest) without importing its graph. The returned descriptor carries the digest of the exact bytes served, so a tag resolves to a canonical digest; digest keys are verified.

func (*Registry) Pull

func (r *Registry) Pull(ctx context.Context, store Store) (v1.Descriptor, error)

Pull imports a manifest/index and its full graph into a local layout CAS.

func (*Registry) Push

func (r *Registry) Push(ctx context.Context, store Store, target v1.Descriptor) error

func (*Registry) Referrers

func (r *Registry) Referrers(ctx context.Context, subject v1.Descriptor) ([]v1.Descriptor, error)

type ReleaseAuthority

type ReleaseAuthority struct {
	Identity        string          `json:"identity"`
	Keys            []ReleaseKey    `json:"keys"`
	Subjects        []digest.Digest `json:"subjects,omitempty"`
	RevokedSubjects []digest.Digest `json:"revokedSubjects,omitempty"`
}

type ReleaseKey

type ReleaseKey struct {
	PublicKey string    `json:"publicKey"`
	NotBefore time.Time `json:"notBefore"`
	NotAfter  time.Time `json:"notAfter"`
	Revoked   bool      `json:"revoked,omitempty"`
}

type ReleasePolicy

type ReleasePolicy struct {
	SchemaVersion int              `json:"schemaVersion"`
	Mode          string           `json:"mode"`
	NotAfter      time.Time        `json:"notAfter"`
	Publisher     ReleaseAuthority `json:"publisher"`
	Composer      ReleaseAuthority `json:"composer"`
}

ReleasePolicy separates publisher authorization from release authorization. Public PEMs are embedded; private keys are never part of this document.

func ParseReleasePolicy

func ParseReleasePolicy(data []byte) (ReleasePolicy, error)

func (ReleasePolicy) Validate

func (p ReleasePolicy) Validate(now time.Time) error

type Resolved

type Resolved struct {
	Reference                  string
	Target, ManifestDescriptor v1.Descriptor
	Manifest                   v1.Manifest
	Image                      v1.Image
	Launch                     *Launch
	LaunchJSON                 []byte
	Layers                     []LayerSource
	ContentRoots               []string
}

func Resolve

func Resolve(ctx context.Context, open BlobOpener, target v1.Descriptor, platform v1.Platform) (*Resolved, error)

Resolve verifies a strict platform selection, config mirror and every streamed layer. open must read local content only; Resolve never accesses a registry.

type Store

type Store struct{ Dir string }

func (Store) Open

func (s Store) Open(d v1.Descriptor) (io.ReadCloser, error)

func (Store) Put

func (s Store) Put(media string, r io.Reader) (v1.Descriptor, error)

func (Store) PutJSON

func (s Store) PutJSON(media string, v any) (v1.Descriptor, error)

func (Store) Read

func (s Store) Read(d v1.Descriptor) ([]byte, error)

func (Store) RecordReferrer

func (s Store) RecordReferrer(subject, descriptor v1.Descriptor) error

func (Store) Referrers

func (s Store) Referrers(subject v1.Descriptor) ([]v1.Descriptor, error)

func (Store) Target

func (s Store) Target(ref string) (v1.Descriptor, error)

func (Store) WriteIndex

func (s Store) WriteIndex(target v1.Descriptor, ref string) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL