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
- func Build(ctx context.Context, store Store, o BuildOptions) (v1.Descriptor, error)
- func BuildIndex(ctx context.Context, store Store, descriptorFiles []string) (v1.Descriptor, error)
- func BuildLayerSet(ctx context.Context, store Store, config LayerSetConfig, layers []LayerSpec, ...) (v1.Descriptor, error)
- func CompositionMaterials(store Store, subject v1.Descriptor) ([]v1.Descriptor, error)
- func ConsumeLayerSet(ctx context.Context, store Store, target v1.Descriptor, ...) ([]BuiltLayer, LayerSetEvidence, error)
- func CopyGraph(ctx context.Context, source, destination Store, target v1.Descriptor) error
- func MaterializeLayers(ctx context.Context, sources []LayerSource, destination string) error
- func ParseImage(data []byte) (v1.Image, error)
- func ParsePlatform(s string) (v1.Platform, error)
- func ParseSigningKey(data []byte) (*ecdsa.PrivateKey, error)
- func ParseTrustKey(data []byte) (*ecdsa.PublicKey, error)
- func Reason(err error) string
- func ReferrerTag(subject v1.Descriptor, referrer v1.Descriptor) string
- func StrictJSON(data []byte, dst any) error
- func ValidateComposition(ctx context.Context, sources []LayerSource) error
- func ValidateEvidence(m v1.Manifest) error
- func ValidateMirror(l *Launch, image v1.Image) error
- func ValidateRuntimeImageID(id string) error
- func VerifyGraph(ctx context.Context, store Store, target v1.Descriptor) error
- type BlobOpener
- type BuildOptions
- type BuiltLayer
- type CacheReceipt
- type ComposeOptions
- type CompositionInspection
- type CompositionPredicate
- type ContentCache
- type ContentReceipt
- type DependencyReport
- type Entry
- type Env
- type Error
- type Fixture
- type FixtureEntry
- type FixtureResult
- type Launch
- type LayerBinding
- type LayerCache
- type LayerInfo
- type LayerSetConfig
- type LayerSetEvidence
- type LayerSetLock
- type LayerSetPredicate
- type LayerSetPublishOptions
- type LayerSetSigner
- type LayerSetTrust
- type LayerSource
- type LayerSpec
- type LockEntry
- type Process
- type Registry
- func (r *Registry) FetchBlob(ctx context.Context, d digest.Digest, max int64) ([]byte, error)
- func (r *Registry) FetchManifest(ctx context.Context, key string) (v1.Descriptor, []byte, error)
- func (r *Registry) Pull(ctx context.Context, store Store) (v1.Descriptor, error)
- func (r *Registry) Push(ctx context.Context, store Store, target v1.Descriptor) error
- func (r *Registry) Referrers(ctx context.Context, subject v1.Descriptor) ([]v1.Descriptor, error)
- type ReleaseAuthority
- type ReleaseKey
- type ReleasePolicy
- type Resolved
- type Store
- func (s Store) Open(d v1.Descriptor) (io.ReadCloser, error)
- func (s Store) Put(media string, r io.Reader) (v1.Descriptor, error)
- func (s Store) PutJSON(media string, v any) (v1.Descriptor, error)
- func (s Store) Read(d v1.Descriptor) ([]byte, error)
- func (s Store) RecordReferrer(subject, descriptor v1.Descriptor) error
- func (s Store) Referrers(subject v1.Descriptor) ([]v1.Descriptor, error)
- func (s Store) Target(ref string) (v1.Descriptor, error)
- func (s Store) WriteIndex(target v1.Descriptor, ref string) error
Constants ¶
const ( MediaTypeLayerSet = "application/vnd.brewlet.layerset.v1+json" MediaTypeLayerSetConfig = "application/vnd.brewlet.layerset.config.v1+json" MediaTypeLayerSetLock = "application/vnd.brewlet.layerset.lock.v1+json" )
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" )
const ( MediaTypeComposition = "application/vnd.brewlet.composition.v1+json" CompositionPredicateType = "https://brewlet.sh/attestations/composition/v1" )
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 ¶
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 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 ¶
ParseImage validates image execution fields which OCI's Image type intentionally does not model (for example Docker Healthcheck) before typed decoding drops them.
func ParseSigningKey ¶
func ParseSigningKey(data []byte) (*ecdsa.PrivateKey, error)
func ReferrerTag ¶
func ReferrerTag(subject v1.Descriptor, referrer v1.Descriptor) string
func StrictJSON ¶
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 ¶
ValidateEvidence checks that evidence references only dependency descriptors actually present in the application manifest.
func ValidateRuntimeImageID ¶
func VerifyGraph ¶
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 ¶
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 Compose(ctx context.Context, store Store, options ComposeOptions) (v1.Descriptor, CompositionInspection, error)
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 ¶
func (c *ContentCache) Open(ctx context.Context, source BlobOpener, d ocispec.Descriptor) (io.ReadCloser, error)
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 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 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 (*Launch) ImageConfig ¶
func (l *Launch) ImageConfig() v1.ImageConfig
func (Launch) MarshalJSON ¶
Preserve an explicit deny-all [] rather than dropping it through omitempty.
type LayerBinding ¶
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 LayerSetConfig ¶
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 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 LayerSource ¶
type LayerSource struct {
Descriptor v1.Descriptor
DiffID digest.Digest
Open func() (io.ReadCloser, error)
}
type LayerSpec ¶
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 ¶
ParseLayerSpec parses [OS/ARCH[/VARIANT]:]ROLE=SOURCE:/app/PATH.
type Registry ¶
type Registry struct {
Origin *url.URL
Repository, Reference string
Username, Password string
Client *http.Client
// contains filtered or unexported fields
}
func (*Registry) FetchBlob ¶
FetchBlob fetches a small blob such as an image config, bounded by max bytes, and verifies its digest.
func (*Registry) FetchManifest ¶
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) Referrers ¶
func (r *Registry) Referrers(ctx context.Context, subject v1.Descriptor) ([]v1.Descriptor, error)
type ReleaseAuthority ¶
type ReleaseKey ¶
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)
type Resolved ¶
type Store ¶
type Store struct{ Dir string }
func (Store) Open ¶
func (s Store) Open(d v1.Descriptor) (io.ReadCloser, 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) WriteIndex ¶
func (s Store) WriteIndex(target v1.Descriptor, ref string) error
Source Files
¶
- cache.go
- composition.go
- conformance.go
- content_cache.go
- dependency_report.go
- doc.go
- graph.go
- jsonkeys.go
- launch.go
- layer.go
- layerset.go
- overlay_linux.go
- pinned.go
- producer.go
- referrer_store.go
- referrers.go
- registry.go
- registry_referrers.go
- registry_tls.go
- release.go
- release_policy.go
- resolve_helpers.go
- source_unix.go
- store.go
- verify_graph.go
- xattrs.go
- xattrs_linux.go