oci

package
v1.234.0 Latest Latest
Warning

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

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

Documentation

Overview

Package oci provides shared helpers for authenticating to OCI registries.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidFilePath = errors.New("invalid file path")
View Source 
var ErrNoLayers = errors.New("the OCI image does not have any layers")

Functions

func ExportIndex 

func ExportIndex(ctx context.Context, source Registry, ref name.Reference, directory string) error

ExportIndex downloads all platforms into an offline OCI layout.

func ExtractTar 

func ExtractTar(raw []byte, directory string) error

ExtractTar validates a bounded, already verified tar payload before using the shared confined extractor. Links, duplicate names, special files, and modes other than ordinary files/directories are rejected before any write.

func GHCRAuth 

func GHCRAuth(atmosConfig *schema.AtmosConfiguration) (authn.Authenticator, string)

GHCRAuth returns authentication credentials for GitHub Container Registry (ghcr.io) derived from Atmos settings, along with a human-readable source description. It returns (nil, "") when no usable credentials are configured so callers can fall back to anonymous access or the default keychain.

func ImportIndex 

func ImportIndex(ctx context.Context, destination Registry, directory string, ref name.Reference) error

ImportIndex uploads a layout with the destination's credentials, independent of any source registry credentials used to create it.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound distinguishes a missing manifest from auth and transport failures.

func LoadIndex 

func LoadIndex(directory, expected string) (v1.ImageIndex, error)

LoadIndex opens the single root index in an OCI layout, optionally enforcing its expected digest. Referenced blobs remain lazy so callers can select one platform; they must validate that platform's bytes before materializing it.

func PinDigest added in v1.230.0 

func PinDigest(imageName, digest string) (string, error)

PinDigest re-expresses imageName with digest bound as an explicit "repo@sha256:..." reference, discarding any tag, so a later fetch of the returned string resolves to the exact manifest identified by digest instead of whatever a mutable tag currently points to. Callers that need to re-fetch reproducibly later should record digest (from ResolveImage) and re-derive the pinned reference via this function rather than storing a tag.

func ProcessImage 

func ProcessImage(ctx context.Context, atmosConfig *schema.AtmosConfiguration, imageName string, destDir string) error

ProcessImage pulls an OCI image and extracts its layers to the specified destination directory. The context bounds the pull (registry auth plus manifest/layer fetch) -- callers should pass one with a deadline, matching the timeout the go-getter download path already enforces.

func ReadVerifiedBlob 

func ReadVerifiedBlob(reader io.Reader, expected *v1.Descriptor, limit int64) ([]byte, error)

ReadVerifiedBlob enforces a byte limit and checks both size and digest before exposing data. It works identically for registry and offline-layout blobs.

func ResolveAuthentication 

func ResolveAuthentication(config *schema.AtmosConfiguration, chain authn.Keychain, resource authn.Resource) (authn.Authenticator, string, error)

ResolveAuthentication keeps Docker/helper credentials ahead of GHCR settings. Resolver errors fail closed; mutation callers must never fall back to anonymous.

func SaveIndex 

func SaveIndex(directory string, index v1.ImageIndex) error

SaveIndex writes a complete index to a standard OCI layout. The outer layout index contains exactly one descriptor for the unchanged release index.

func SaveSelection 

func SaveSelection(directory string, index v1.ImageIndex, selected []v1.Hash) error

SaveSelection retains an unchanged index and all child manifests/configs, downloading layers only for selected image digests. The resulting partial layout supports offline inspection and restoration of those platforms. Nested indexes are rejected explicitly; they must use SaveIndex instead.

func WithRetryObserver added in v1.229.0 

func WithRetryObserver(ctx context.Context, observer func(int)) context.Context

WithRetryObserver routes retry notices to the caller and suppresses terminal diagnostics during this operation. Errors are still returned to the caller. The observer is scoped to this context, including provenance resolution.

Types

type AuthenticationResolver 

type AuthenticationResolver interface {
	Resolve(context.Context, authn.Resource) (authn.Authenticator, bool, error)
}

AuthenticationResolver resolves explicitly bound identities before ambient credentials. The matched result distinguishes an unbound host from a failed configured identity.

type Client 

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

Client performs registry operations without plugin or component semantics.

func NewClient 

func NewClient(config *schema.AtmosConfiguration, options ...ClientOption) *Client

NewClient constructs a client using the existing Docker and GHCR auth policy.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, ref name.Digest) error

Delete deletes only an explicitly selected digest, never a mutable tag.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, ref name.Reference) (*remote.Descriptor, error)

Get resolves an index or image without selecting a platform or extracting it.

func (*Client) Head 

func (c *Client) Head(ctx context.Context, ref name.Reference) (*v1.Descriptor, error)

Head resolves the immutable descriptor without downloading artifact layers.

func (*Client) Referrers 

func (c *Client) Referrers(ctx context.Context, ref name.Digest) (v1.ImageIndex, error)

Referrers uses the shared credentials and transport, including the standard referrers-tag fallback on registries without the OCI 1.1 API.

func (*Client) Tags 

func (c *Client) Tags(ctx context.Context, repo name.Repository) ([]string, error)

Tags lists repository tags without interpreting them as versions.

func (*Client) WriteImage 

func (c *Client) WriteImage(ctx context.Context, ref name.Reference, img v1.Image) error

WriteImage uploads an image and its blobs. Rejected writes never retry anonymously.

func (*Client) WriteIndex 

func (c *Client) WriteIndex(ctx context.Context, ref name.Reference, index v1.ImageIndex) error

WriteIndex uploads the complete index and its children without platform filtering.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures authentication or transport for one client.

func WithAuthenticationResolver 

func WithAuthenticationResolver(resolver AuthenticationResolver) ClientOption

WithAuthenticationResolver binds a context-aware identity resolver to this client. Configured identities never fall through to Docker helpers or environment credentials.

func WithCredentialFallback 

func WithCredentialFallback(chain authn.Keychain) ClientOption

WithCredentialFallback supplies credentials after Docker helpers and GHCR settings. It does not retry failed authenticated registry requests with another identity.

func WithKeychain 

func WithKeychain(keychain authn.Keychain) ClientOption

WithKeychain sets a repository-aware credential resolver. Callers transferring between registries can supply separate source and destination clients.

func WithTransport 

func WithTransport(transport http.RoundTripper) ClientOption

WithTransport supplies TLS, CA, proxy, and instrumentation settings.

type CredentialKeychain 

type CredentialKeychain struct {
	Store    keyring.Keyring
	Open     func() (keyring.Keyring, error)
	Optional bool
}

CredentialKeychain stores registry credentials in the shared Atmos keyring. Registry names, not package aliases, determine credential scope.

func (CredentialKeychain) Login 

func (k CredentialKeychain) Login(registry string, config *authn.AuthConfig) error

Login records explicit credentials for a registry without changing source configuration.

func (CredentialKeychain) Logout 

func (k CredentialKeychain) Logout(registry string) error

Logout removes only Atmos's stored credentials for the selected registry.

func (CredentialKeychain) Resolve 

func (k CredentialKeychain) Resolve(resource authn.Resource) (authn.Authenticator, error)

Resolve implements the standard OCI keychain interface.

type ReferrerRegistry 

type ReferrerRegistry interface {
	Registry
	Referrers(context.Context, name.Digest) (v1.ImageIndex, error)
}

ReferrerRegistry extends OCI transport with OCI 1.1 attachment discovery.

type Registry 

type Registry interface {
	Get(context.Context, name.Reference) (*remote.Descriptor, error)
	Head(context.Context, name.Reference) (*v1.Descriptor, error)
	Tags(context.Context, name.Repository) ([]string, error)
	WriteImage(context.Context, name.Reference, v1.Image) error
	WriteIndex(context.Context, name.Reference, v1.ImageIndex) error
	Delete(context.Context, name.Digest) error
}

Registry is the transport boundary shared by OCI consumers. Images and indexes retain their original bytes; package-specific extraction lives above it. A client resolves credentials independently for every repository operation.

type ResolvedImage added in v1.225.0 

type ResolvedImage struct {
	Reference string
	Digest    string
	MediaType string
}

ResolvedImage is the immutable registry identity selected for an OCI source. Digest is the descriptor digest for the selected manifest; it is suitable for locks and SBOM provenance, unlike the mutable declared tag/reference.

func ResolveImage added in v1.225.0 

func ResolveImage(ctx context.Context, atmosConfig *schema.AtmosConfiguration, imageName string) (*ResolvedImage, error)

ResolveImage authenticates and resolves an OCI reference without extracting layers. It is the public provenance boundary for OCI consumers.

Source Files

View all Source files

Directories

Path Synopsis
Package ocitest provides an in-process OCI registry for tests, so tests never depend on real network access or a real container registry.
 Package ocitest provides an in-process OCI registry for tests, so tests never depend on real network access or a real container registry.
Package signature verifies Sigstore bundles against caller-selected identities.
 Package signature verifies Sigstore bundles against caller-selected identities.
signaturetest
Package signaturetest creates real certificates, signatures and transparency proofs without contacting a public identity provider or transparency log.
 Package signaturetest creates real certificates, signatures and transparency proofs without contacting a public identity provider or transparency log.

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.