container: add support for uploading to registries

Add a new generic container registry client via a new `container`
package. Use this to create a command line utility as well as a
new upload target for container registries.

The code uses the github.com/containers/* project and packages to
interact with container registires that is also used by skopeo,
podman et al. One if the dependencies is `proglottis/gpgme` that
is using cgo to bind libgpgme, so we have to add the corresponding
devel package to the BuildRequires as well as installing it on CI.

Checks will follow later via an integration test.

vendor/github.com/containers/image/v5/oci/layout/oci_dest.go

@@ -0,0 +1,346 @@
+package layout
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/containers/image/v5/internal/putblobdigest"
+	"github.com/containers/image/v5/manifest"
+	"github.com/containers/image/v5/types"
+	digest "github.com/opencontainers/go-digest"
+	imgspec "github.com/opencontainers/image-spec/specs-go"
+	imgspecv1 "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/pkg/errors"
+)
+
+type ociImageDestination struct {
+	ref                      ociReference
+	index                    imgspecv1.Index
+	sharedBlobDir            string
+	acceptUncompressedLayers bool
+}
+
+// newImageDestination returns an ImageDestination for writing to an existing directory.
+func newImageDestination(sys *types.SystemContext, ref ociReference) (types.ImageDestination, error) {
+	var index *imgspecv1.Index
+	if indexExists(ref) {
+		var err error
+		index, err = ref.getIndex()
+		if err != nil {
+			return nil, err
+		}
+	} else {
+		index = &imgspecv1.Index{
+			Versioned: imgspec.Versioned{
+				SchemaVersion: 2,
+			},
+			Annotations: make(map[string]string),
+		}
+	}
+
+	d := &ociImageDestination{ref: ref, index: *index}
+	if sys != nil {
+		d.sharedBlobDir = sys.OCISharedBlobDirPath
+		d.acceptUncompressedLayers = sys.OCIAcceptUncompressedLayers
+	}
+
+	if err := ensureDirectoryExists(d.ref.dir); err != nil {
+		return nil, err
+	}
+	// Per the OCI image specification, layouts MUST have a "blobs" subdirectory,
+	// but it MAY be empty (e.g. if we never end up calling PutBlob)
+	// https://github.com/opencontainers/image-spec/blame/7c889fafd04a893f5c5f50b7ab9963d5d64e5242/image-layout.md#L19
+	if err := ensureDirectoryExists(filepath.Join(d.ref.dir, "blobs")); err != nil {
+		return nil, err
+	}
+	return d, nil
+}
+
+// Reference returns the reference used to set up this destination.  Note that this should directly correspond to user's intent,
+// e.g. it should use the public hostname instead of the result of resolving CNAMEs or following redirects.
+func (d *ociImageDestination) Reference() types.ImageReference {
+	return d.ref
+}
+
+// Close removes resources associated with an initialized ImageDestination, if any.
+func (d *ociImageDestination) Close() error {
+	return nil
+}
+
+func (d *ociImageDestination) SupportedManifestMIMETypes() []string {
+	return []string{
+		imgspecv1.MediaTypeImageManifest,
+		imgspecv1.MediaTypeImageIndex,
+	}
+}
+
+// SupportsSignatures returns an error (to be displayed to the user) if the destination certainly can't store signatures.
+// Note: It is still possible for PutSignatures to fail if SupportsSignatures returns nil.
+func (d *ociImageDestination) SupportsSignatures(ctx context.Context) error {
+	return errors.Errorf("Pushing signatures for OCI images is not supported")
+}
+
+func (d *ociImageDestination) DesiredLayerCompression() types.LayerCompression {
+	if d.acceptUncompressedLayers {
+		return types.PreserveOriginal
+	}
+	return types.Compress
+}
+
+// AcceptsForeignLayerURLs returns false iff foreign layers in manifest should be actually
+// uploaded to the image destination, true otherwise.
+func (d *ociImageDestination) AcceptsForeignLayerURLs() bool {
+	return true
+}
+
+// MustMatchRuntimeOS returns true iff the destination can store only images targeted for the current runtime architecture and OS. False otherwise.
+func (d *ociImageDestination) MustMatchRuntimeOS() bool {
+	return false
+}
+
+// IgnoresEmbeddedDockerReference returns true iff the destination does not care about Image.EmbeddedDockerReferenceConflicts(),
+// and would prefer to receive an unmodified manifest instead of one modified for the destination.
+// Does not make a difference if Reference().DockerReference() is nil.
+func (d *ociImageDestination) IgnoresEmbeddedDockerReference() bool {
+	return false // N/A, DockerReference() returns nil.
+}
+
+// HasThreadSafePutBlob indicates whether PutBlob can be executed concurrently.
+func (d *ociImageDestination) HasThreadSafePutBlob() bool {
+	return true
+}
+
+// PutBlob writes contents of stream and returns data representing the result.
+// inputInfo.Digest can be optionally provided if known; if provided, and stream is read to the end without error, the digest MUST match the stream contents.
+// inputInfo.Size is the expected length of stream, if known.
+// inputInfo.MediaType describes the blob format, if known.
+// May update cache.
+// WARNING: The contents of stream are being verified on the fly.  Until stream.Read() returns io.EOF, the contents of the data SHOULD NOT be available
+// to any other readers for download using the supplied digest.
+// If stream.Read() at any time, ESPECIALLY at end of input, returns an error, PutBlob MUST 1) fail, and 2) delete any data stored so far.
+func (d *ociImageDestination) PutBlob(ctx context.Context, stream io.Reader, inputInfo types.BlobInfo, cache types.BlobInfoCache, isConfig bool) (types.BlobInfo, error) {
+	blobFile, err := os.CreateTemp(d.ref.dir, "oci-put-blob")
+	if err != nil {
+		return types.BlobInfo{}, err
+	}
+	succeeded := false
+	explicitClosed := false
+	defer func() {
+		if !explicitClosed {
+			blobFile.Close()
+		}
+		if !succeeded {
+			os.Remove(blobFile.Name())
+		}
+	}()
+
+	digester, stream := putblobdigest.DigestIfCanonicalUnknown(stream, inputInfo)
+	// TODO: This can take quite some time, and should ideally be cancellable using ctx.Done().
+	size, err := io.Copy(blobFile, stream)
+	if err != nil {
+		return types.BlobInfo{}, err
+	}
+	blobDigest := digester.Digest()
+	if inputInfo.Size != -1 && size != inputInfo.Size {
+		return types.BlobInfo{}, errors.Errorf("Size mismatch when copying %s, expected %d, got %d", blobDigest, inputInfo.Size, size)
+	}
+	if err := blobFile.Sync(); err != nil {
+		return types.BlobInfo{}, err
+	}
+
+	// On POSIX systems, blobFile was created with mode 0600, so we need to make it readable.
+	// On Windows, the “permissions of newly created files” argument to syscall.Open is
+	// ignored and the file is already readable; besides, blobFile.Chmod, i.e. syscall.Fchmod,
+	// always fails on Windows.
+	if runtime.GOOS != "windows" {
+		if err := blobFile.Chmod(0644); err != nil {
+			return types.BlobInfo{}, err
+		}
+	}
+
+	blobPath, err := d.ref.blobPath(blobDigest, d.sharedBlobDir)
+	if err != nil {
+		return types.BlobInfo{}, err
+	}
+	if err := ensureParentDirectoryExists(blobPath); err != nil {
+		return types.BlobInfo{}, err
+	}
+
+	// need to explicitly close the file, since a rename won't otherwise not work on Windows
+	blobFile.Close()
+	explicitClosed = true
+	if err := os.Rename(blobFile.Name(), blobPath); err != nil {
+		return types.BlobInfo{}, err
+	}
+	succeeded = true
+	return types.BlobInfo{Digest: blobDigest, Size: size}, nil
+}
+
+// TryReusingBlob checks whether the transport already contains, or can efficiently reuse, a blob, and if so, applies it to the current destination
+// (e.g. if the blob is a filesystem layer, this signifies that the changes it describes need to be applied again when composing a filesystem tree).
+// info.Digest must not be empty.
+// If canSubstitute, TryReusingBlob can use an equivalent equivalent of the desired blob; in that case the returned info may not match the input.
+// If the blob has been successfully reused, returns (true, info, nil); info must contain at least a digest and size, and may
+// include CompressionOperation and CompressionAlgorithm fields to indicate that a change to the compression type should be
+// reflected in the manifest that will be written.
+// If the transport can not reuse the requested blob, TryReusingBlob returns (false, {}, nil); it returns a non-nil error only on an unexpected failure.
+// May use and/or update cache.
+func (d *ociImageDestination) TryReusingBlob(ctx context.Context, info types.BlobInfo, cache types.BlobInfoCache, canSubstitute bool) (bool, types.BlobInfo, error) {
+	if info.Digest == "" {
+		return false, types.BlobInfo{}, errors.Errorf(`"Can not check for a blob with unknown digest`)
+	}
+	blobPath, err := d.ref.blobPath(info.Digest, d.sharedBlobDir)
+	if err != nil {
+		return false, types.BlobInfo{}, err
+	}
+	finfo, err := os.Stat(blobPath)
+	if err != nil && os.IsNotExist(err) {
+		return false, types.BlobInfo{}, nil
+	}
+	if err != nil {
+		return false, types.BlobInfo{}, err
+	}
+
+	return true, types.BlobInfo{Digest: info.Digest, Size: finfo.Size()}, nil
+}
+
+// PutManifest writes a manifest to the destination.  Per our list of supported manifest MIME types,
+// this should be either an OCI manifest (possibly converted to this format by the caller) or index,
+// neither of which we'll need to modify further.
+// If instanceDigest is not nil, it contains a digest of the specific manifest instance to overwrite the manifest for (when
+// the primary manifest is a manifest list); this should always be nil if the primary manifest is not a manifest list.
+// It is expected but not enforced that the instanceDigest, when specified, matches the digest of `manifest` as generated
+// by `manifest.Digest()`.
+// FIXME? This should also receive a MIME type if known, to differentiate between schema versions.
+// If the destination is in principle available, refuses this manifest type (e.g. it does not recognize the schema),
+// but may accept a different manifest type, the returned error must be an ManifestTypeRejectedError.
+func (d *ociImageDestination) PutManifest(ctx context.Context, m []byte, instanceDigest *digest.Digest) error {
+	var digest digest.Digest
+	var err error
+	if instanceDigest != nil {
+		digest = *instanceDigest
+	} else {
+		digest, err = manifest.Digest(m)
+		if err != nil {
+			return err
+		}
+	}
+
+	blobPath, err := d.ref.blobPath(digest, d.sharedBlobDir)
+	if err != nil {
+		return err
+	}
+	if err := ensureParentDirectoryExists(blobPath); err != nil {
+		return err
+	}
+	if err := os.WriteFile(blobPath, m, 0644); err != nil {
+		return err
+	}
+
+	if instanceDigest != nil {
+		return nil
+	}
+
+	// If we had platform information, we'd build an imgspecv1.Platform structure here.
+
+	// Start filling out the descriptor for this entry
+	desc := imgspecv1.Descriptor{}
+	desc.Digest = digest
+	desc.Size = int64(len(m))
+	if d.ref.image != "" {
+		desc.Annotations = make(map[string]string)
+		desc.Annotations[imgspecv1.AnnotationRefName] = d.ref.image
+	}
+
+	// If we knew the MIME type, we wouldn't have to guess here.
+	desc.MediaType = manifest.GuessMIMEType(m)
+
+	d.addManifest(&desc)
+
+	return nil
+}
+
+func (d *ociImageDestination) addManifest(desc *imgspecv1.Descriptor) {
+	// If the new entry has a name, remove any conflicting names which we already have.
+	if desc.Annotations != nil && desc.Annotations[imgspecv1.AnnotationRefName] != "" {
+		// The name is being set on a new entry, so remove any older ones that had the same name.
+		// We might be storing an index and all of its component images, and we'll want to attach
+		// the name to the last one, which is the index.
+		for i, manifest := range d.index.Manifests {
+			if manifest.Annotations[imgspecv1.AnnotationRefName] == desc.Annotations[imgspecv1.AnnotationRefName] {
+				delete(d.index.Manifests[i].Annotations, imgspecv1.AnnotationRefName)
+				break
+			}
+		}
+	}
+	// If it has the same digest as another entry in the index, we already overwrote the file,
+	// so just pick up the other information.
+	for i, manifest := range d.index.Manifests {
+		if manifest.Digest == desc.Digest && manifest.Annotations[imgspecv1.AnnotationRefName] == "" {
+			// Replace it completely.
+			d.index.Manifests[i] = *desc
+			return
+		}
+	}
+	// It's a new entry to be added to the index.
+	d.index.Manifests = append(d.index.Manifests, *desc)
+}
+
+// PutSignatures would add the given signatures to the oci layout (currently not supported).
+// If instanceDigest is not nil, it contains a digest of the specific manifest instance to write or overwrite the signatures for
+// (when the primary manifest is a manifest list); this should always be nil if the primary manifest is not a manifest list.
+func (d *ociImageDestination) PutSignatures(ctx context.Context, signatures [][]byte, instanceDigest *digest.Digest) error {
+	if len(signatures) != 0 {
+		return errors.Errorf("Pushing signatures for OCI images is not supported")
+	}
+	return nil
+}
+
+// Commit marks the process of storing the image as successful and asks for the image to be persisted.
+// unparsedToplevel contains data about the top-level manifest of the source (which may be a single-arch image or a manifest list
+// if PutManifest was only called for the single-arch image with instanceDigest == nil), primarily to allow lookups by the
+// original manifest list digest, if desired.
+// WARNING: This does not have any transactional semantics:
+// - Uploaded data MAY be visible to others before Commit() is called
+// - Uploaded data MAY be removed or MAY remain around if Close() is called without Commit() (i.e. rollback is allowed but not guaranteed)
+func (d *ociImageDestination) Commit(context.Context, types.UnparsedImage) error {
+	if err := os.WriteFile(d.ref.ociLayoutPath(), []byte(`{"imageLayoutVersion": "1.0.0"}`), 0644); err != nil {
+		return err
+	}
+	indexJSON, err := json.Marshal(d.index)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(d.ref.indexPath(), indexJSON, 0644)
+}
+
+func ensureDirectoryExists(path string) error {
+	if _, err := os.Stat(path); err != nil && os.IsNotExist(err) {
+		if err := os.MkdirAll(path, 0755); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ensureParentDirectoryExists ensures the parent of the supplied path exists.
+func ensureParentDirectoryExists(path string) error {
+	return ensureDirectoryExists(filepath.Dir(path))
+}
+
+// indexExists checks whether the index location specified in the OCI reference exists.
+// The implementation is opinionated, since in case of unexpected errors false is returned
+func indexExists(ref ociReference) bool {
+	_, err := os.Stat(ref.indexPath())
+	if err == nil {
+		return true
+	}
+	if os.IsNotExist(err) {
+		return false
+	}
+	return true
+}

vendor/github.com/containers/image/v5/oci/layout/oci_src.go

@@ -0,0 +1,208 @@
+package layout
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strconv"
+
+	"github.com/containers/image/v5/manifest"
+	"github.com/containers/image/v5/pkg/tlsclientconfig"
+	"github.com/containers/image/v5/types"
+	"github.com/docker/go-connections/tlsconfig"
+	"github.com/opencontainers/go-digest"
+	imgspecv1 "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/pkg/errors"
+)
+
+type ociImageSource struct {
+	ref           ociReference
+	index         *imgspecv1.Index
+	descriptor    imgspecv1.Descriptor
+	client        *http.Client
+	sharedBlobDir string
+}
+
+// newImageSource returns an ImageSource for reading from an existing directory.
+func newImageSource(sys *types.SystemContext, ref ociReference) (types.ImageSource, error) {
+	tr := tlsclientconfig.NewTransport()
+	tr.TLSClientConfig = tlsconfig.ServerDefault()
+
+	if sys != nil && sys.OCICertPath != "" {
+		if err := tlsclientconfig.SetupCertificates(sys.OCICertPath, tr.TLSClientConfig); err != nil {
+			return nil, err
+		}
+		tr.TLSClientConfig.InsecureSkipVerify = sys.OCIInsecureSkipTLSVerify
+	}
+
+	client := &http.Client{}
+	client.Transport = tr
+	descriptor, err := ref.getManifestDescriptor()
+	if err != nil {
+		return nil, err
+	}
+	index, err := ref.getIndex()
+	if err != nil {
+		return nil, err
+	}
+	d := &ociImageSource{ref: ref, index: index, descriptor: descriptor, client: client}
+	if sys != nil {
+		// TODO(jonboulle): check dir existence?
+		d.sharedBlobDir = sys.OCISharedBlobDirPath
+	}
+	return d, nil
+}
+
+// Reference returns the reference used to set up this source.
+func (s *ociImageSource) Reference() types.ImageReference {
+	return s.ref
+}
+
+// Close removes resources associated with an initialized ImageSource, if any.
+func (s *ociImageSource) Close() error {
+	return nil
+}
+
+// GetManifest returns the image's manifest along with its MIME type (which may be empty when it can't be determined but the manifest is available).
+// It may use a remote (= slow) service.
+// If instanceDigest is not nil, it contains a digest of the specific manifest instance to retrieve (when the primary manifest is a manifest list);
+// this never happens if the primary manifest is not a manifest list (e.g. if the source never returns manifest lists).
+func (s *ociImageSource) GetManifest(ctx context.Context, instanceDigest *digest.Digest) ([]byte, string, error) {
+	var dig digest.Digest
+	var mimeType string
+	var err error
+
+	if instanceDigest == nil {
+		dig = digest.Digest(s.descriptor.Digest)
+		mimeType = s.descriptor.MediaType
+	} else {
+		dig = *instanceDigest
+		for _, md := range s.index.Manifests {
+			if md.Digest == dig {
+				mimeType = md.MediaType
+				break
+			}
+		}
+	}
+
+	manifestPath, err := s.ref.blobPath(dig, s.sharedBlobDir)
+	if err != nil {
+		return nil, "", err
+	}
+
+	m, err := os.ReadFile(manifestPath)
+	if err != nil {
+		return nil, "", err
+	}
+	if mimeType == "" {
+		mimeType = manifest.GuessMIMEType(m)
+	}
+
+	return m, mimeType, nil
+}
+
+// HasThreadSafeGetBlob indicates whether GetBlob can be executed concurrently.
+func (s *ociImageSource) HasThreadSafeGetBlob() bool {
+	return false
+}
+
+// GetBlob returns a stream for the specified blob, and the blob’s size (or -1 if unknown).
+// The Digest field in BlobInfo is guaranteed to be provided, Size may be -1 and MediaType may be optionally provided.
+// May update BlobInfoCache, preferably after it knows for certain that a blob truly exists at a specific location.
+func (s *ociImageSource) GetBlob(ctx context.Context, info types.BlobInfo, cache types.BlobInfoCache) (io.ReadCloser, int64, error) {
+	if len(info.URLs) != 0 {
+		r, s, err := s.getExternalBlob(ctx, info.URLs)
+		if err != nil {
+			return nil, 0, err
+		} else if r != nil {
+			return r, s, nil
+		}
+	}
+
+	path, err := s.ref.blobPath(info.Digest, s.sharedBlobDir)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	r, err := os.Open(path)
+	if err != nil {
+		return nil, 0, err
+	}
+	fi, err := r.Stat()
+	if err != nil {
+		return nil, 0, err
+	}
+	return r, fi.Size(), nil
+}
+
+// GetSignatures returns the image's signatures.  It may use a remote (= slow) service.
+// If instanceDigest is not nil, it contains a digest of the specific manifest instance to retrieve signatures for
+// (when the primary manifest is a manifest list); this never happens if the primary manifest is not a manifest list
+// (e.g. if the source never returns manifest lists).
+func (s *ociImageSource) GetSignatures(ctx context.Context, instanceDigest *digest.Digest) ([][]byte, error) {
+	return [][]byte{}, nil
+}
+
+// getExternalBlob returns the reader of the first available blob URL from urls, which must not be empty.
+// This function can return nil reader when no url is supported by this function. In this case, the caller
+// should fallback to fetch the non-external blob (i.e. pull from the registry).
+func (s *ociImageSource) getExternalBlob(ctx context.Context, urls []string) (io.ReadCloser, int64, error) {
+	if len(urls) == 0 {
+		return nil, 0, errors.New("internal error: getExternalBlob called with no URLs")
+	}
+
+	errWrap := errors.New("failed fetching external blob from all urls")
+	hasSupportedURL := false
+	for _, u := range urls {
+		if u, err := url.Parse(u); err != nil || (u.Scheme != "http" && u.Scheme != "https") {
+			continue // unsupported url. skip this url.
+		}
+		hasSupportedURL = true
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+		if err != nil {
+			errWrap = errors.Wrapf(errWrap, "fetching %s failed %s", u, err.Error())
+			continue
+		}
+
+		resp, err := s.client.Do(req)
+		if err != nil {
+			errWrap = errors.Wrapf(errWrap, "fetching %s failed %s", u, err.Error())
+			continue
+		}
+
+		if resp.StatusCode != http.StatusOK {
+			resp.Body.Close()
+			errWrap = errors.Wrapf(errWrap, "fetching %s failed, response code not 200", u)
+			continue
+		}
+
+		return resp.Body, getBlobSize(resp), nil
+	}
+	if !hasSupportedURL {
+		return nil, 0, nil // fallback to non-external blob
+	}
+
+	return nil, 0, errWrap
+}
+
+// LayerInfosForCopy returns either nil (meaning the values in the manifest are fine), or updated values for the layer
+// blobsums that are listed in the image's manifest.  If values are returned, they should be used when using GetBlob()
+// to read the image's layers.
+// If instanceDigest is not nil, it contains a digest of the specific manifest instance to retrieve BlobInfos for
+// (when the primary manifest is a manifest list); this never happens if the primary manifest is not a manifest list
+// (e.g. if the source never returns manifest lists).
+// The Digest field is guaranteed to be provided; Size may be -1.
+// WARNING: The list may contain duplicates, and they are semantically relevant.
+func (s *ociImageSource) LayerInfosForCopy(context.Context, *digest.Digest) ([]types.BlobInfo, error) {
+	return nil, nil
+}
+
+func getBlobSize(resp *http.Response) int64 {
+	size, err := strconv.ParseInt(resp.Header.Get("Content-Length"), 10, 64)
+	if err != nil {
+		size = -1
+	}
+	return size
+}

vendor/github.com/containers/image/v5/oci/layout/oci_transport.go

@@ -0,0 +1,264 @@
+package layout
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/containers/image/v5/directory/explicitfilepath"
+	"github.com/containers/image/v5/docker/reference"
+	"github.com/containers/image/v5/image"
+	"github.com/containers/image/v5/oci/internal"
+	"github.com/containers/image/v5/transports"
+	"github.com/containers/image/v5/types"
+	"github.com/opencontainers/go-digest"
+	imgspecv1 "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/pkg/errors"
+)
+
+func init() {
+	transports.Register(Transport)
+}
+
+var (
+	// Transport is an ImageTransport for OCI directories.
+	Transport = ociTransport{}
+
+	// ErrMoreThanOneImage is an error returned when the manifest includes
+	// more than one image and the user should choose which one to use.
+	ErrMoreThanOneImage = errors.New("more than one image in oci, choose an image")
+)
+
+type ociTransport struct{}
+
+func (t ociTransport) Name() string {
+	return "oci"
+}
+
+// ParseReference converts a string, which should not start with the ImageTransport.Name prefix, into an ImageReference.
+func (t ociTransport) ParseReference(reference string) (types.ImageReference, error) {
+	return ParseReference(reference)
+}
+
+// ValidatePolicyConfigurationScope checks that scope is a valid name for a signature.PolicyTransportScopes keys
+// (i.e. a valid PolicyConfigurationIdentity() or PolicyConfigurationNamespaces() return value).
+// It is acceptable to allow an invalid value which will never be matched, it can "only" cause user confusion.
+// scope passed to this function will not be "", that value is always allowed.
+func (t ociTransport) ValidatePolicyConfigurationScope(scope string) error {
+	return internal.ValidateScope(scope)
+}
+
+// ociReference is an ImageReference for OCI directory paths.
+type ociReference struct {
+	// Note that the interpretation of paths below depends on the underlying filesystem state, which may change under us at any time!
+	// Either of the paths may point to a different, or no, inode over time.  resolvedDir may contain symbolic links, and so on.
+
+	// Generally we follow the intent of the user, and use the "dir" member for filesystem operations (e.g. the user can use a relative path to avoid
+	// being exposed to symlinks and renames in the parent directories to the working directory).
+	// (But in general, we make no attempt to be completely safe against concurrent hostile filesystem modifications.)
+	dir         string // As specified by the user. May be relative, contain symlinks, etc.
+	resolvedDir string // Absolute path with no symlinks, at least at the time of its creation. Primarily used for policy namespaces.
+	// If image=="", it means the "only image" in the index.json is used in the case it is a source
+	// for destinations, the image name annotation "image.ref.name" is not added to the index.json
+	image string
+}
+
+// ParseReference converts a string, which should not start with the ImageTransport.Name prefix, into an OCI ImageReference.
+func ParseReference(reference string) (types.ImageReference, error) {
+	dir, image := internal.SplitPathAndImage(reference)
+	return NewReference(dir, image)
+}
+
+// NewReference returns an OCI reference for a directory and a image.
+//
+// We do not expose an API supplying the resolvedDir; we could, but recomputing it
+// is generally cheap enough that we prefer being confident about the properties of resolvedDir.
+func NewReference(dir, image string) (types.ImageReference, error) {
+	resolved, err := explicitfilepath.ResolvePathToFullyExplicit(dir)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := internal.ValidateOCIPath(dir); err != nil {
+		return nil, err
+	}
+
+	if err = internal.ValidateImageName(image); err != nil {
+		return nil, err
+	}
+
+	return ociReference{dir: dir, resolvedDir: resolved, image: image}, nil
+}
+
+func (ref ociReference) Transport() types.ImageTransport {
+	return Transport
+}
+
+// StringWithinTransport returns a string representation of the reference, which MUST be such that
+// reference.Transport().ParseReference(reference.StringWithinTransport()) returns an equivalent reference.
+// NOTE: The returned string is not promised to be equal to the original input to ParseReference;
+// e.g. default attribute values omitted by the user may be filled in in the return value, or vice versa.
+// WARNING: Do not use the return value in the UI to describe an image, it does not contain the Transport().Name() prefix.
+func (ref ociReference) StringWithinTransport() string {
+	return fmt.Sprintf("%s:%s", ref.dir, ref.image)
+}
+
+// DockerReference returns a Docker reference associated with this reference
+// (fully explicit, i.e. !reference.IsNameOnly, but reflecting user intent,
+// not e.g. after redirect or alias processing), or nil if unknown/not applicable.
+func (ref ociReference) DockerReference() reference.Named {
+	return nil
+}
+
+// PolicyConfigurationIdentity returns a string representation of the reference, suitable for policy lookup.
+// This MUST reflect user intent, not e.g. after processing of third-party redirects or aliases;
+// The value SHOULD be fully explicit about its semantics, with no hidden defaults, AND canonical
+// (i.e. various references with exactly the same semantics should return the same configuration identity)
+// It is fine for the return value to be equal to StringWithinTransport(), and it is desirable but
+// not required/guaranteed that it will be a valid input to Transport().ParseReference().
+// Returns "" if configuration identities for these references are not supported.
+func (ref ociReference) PolicyConfigurationIdentity() string {
+	// NOTE: ref.image is not a part of the image identity, because "$dir:$someimage" and "$dir:" may mean the
+	// same image and the two can’t be statically disambiguated.  Using at least the repository directory is
+	// less granular but hopefully still useful.
+	return ref.resolvedDir
+}
+
+// PolicyConfigurationNamespaces returns a list of other policy configuration namespaces to search
+// for if explicit configuration for PolicyConfigurationIdentity() is not set.  The list will be processed
+// in order, terminating on first match, and an implicit "" is always checked at the end.
+// It is STRONGLY recommended for the first element, if any, to be a prefix of PolicyConfigurationIdentity(),
+// and each following element to be a prefix of the element preceding it.
+func (ref ociReference) PolicyConfigurationNamespaces() []string {
+	res := []string{}
+	path := ref.resolvedDir
+	for {
+		lastSlash := strings.LastIndex(path, "/")
+		// Note that we do not include "/"; it is redundant with the default "" global default,
+		// and rejected by ociTransport.ValidatePolicyConfigurationScope above.
+		if lastSlash == -1 || path == "/" {
+			break
+		}
+		res = append(res, path)
+		path = path[:lastSlash]
+	}
+	return res
+}
+
+// NewImage returns a types.ImageCloser for this reference, possibly specialized for this ImageTransport.
+// The caller must call .Close() on the returned ImageCloser.
+// NOTE: If any kind of signature verification should happen, build an UnparsedImage from the value returned by NewImageSource,
+// verify that UnparsedImage, and convert it into a real Image via image.FromUnparsedImage.
+// WARNING: This may not do the right thing for a manifest list, see image.FromSource for details.
+func (ref ociReference) NewImage(ctx context.Context, sys *types.SystemContext) (types.ImageCloser, error) {
+	src, err := newImageSource(sys, ref)
+	if err != nil {
+		return nil, err
+	}
+	return image.FromSource(ctx, sys, src)
+}
+
+// getIndex returns a pointer to the index references by this ociReference. If an error occurs opening an index nil is returned together
+// with an error.
+func (ref ociReference) getIndex() (*imgspecv1.Index, error) {
+	indexJSON, err := os.Open(ref.indexPath())
+	if err != nil {
+		return nil, err
+	}
+	defer indexJSON.Close()
+
+	index := &imgspecv1.Index{}
+	if err := json.NewDecoder(indexJSON).Decode(index); err != nil {
+		return nil, err
+	}
+	return index, nil
+}
+
+func (ref ociReference) getManifestDescriptor() (imgspecv1.Descriptor, error) {
+	index, err := ref.getIndex()
+	if err != nil {
+		return imgspecv1.Descriptor{}, err
+	}
+
+	var d *imgspecv1.Descriptor
+	if ref.image == "" {
+		// return manifest if only one image is in the oci directory
+		if len(index.Manifests) == 1 {
+			d = &index.Manifests[0]
+		} else {
+			// ask user to choose image when more than one image in the oci directory
+			return imgspecv1.Descriptor{}, ErrMoreThanOneImage
+		}
+	} else {
+		// if image specified, look through all manifests for a match
+		for _, md := range index.Manifests {
+			if md.MediaType != imgspecv1.MediaTypeImageManifest && md.MediaType != imgspecv1.MediaTypeImageIndex {
+				continue
+			}
+			refName, ok := md.Annotations[imgspecv1.AnnotationRefName]
+			if !ok {
+				continue
+			}
+			if refName == ref.image {
+				d = &md
+				break
+			}
+		}
+	}
+	if d == nil {
+		return imgspecv1.Descriptor{}, fmt.Errorf("no descriptor found for reference %q", ref.image)
+	}
+	return *d, nil
+}
+
+// LoadManifestDescriptor loads the manifest descriptor to be used to retrieve the image name
+// when pulling an image
+func LoadManifestDescriptor(imgRef types.ImageReference) (imgspecv1.Descriptor, error) {
+	ociRef, ok := imgRef.(ociReference)
+	if !ok {
+		return imgspecv1.Descriptor{}, errors.Errorf("error typecasting, need type ociRef")
+	}
+	return ociRef.getManifestDescriptor()
+}
+
+// NewImageSource returns a types.ImageSource for this reference.
+// The caller must call .Close() on the returned ImageSource.
+func (ref ociReference) NewImageSource(ctx context.Context, sys *types.SystemContext) (types.ImageSource, error) {
+	return newImageSource(sys, ref)
+}
+
+// NewImageDestination returns a types.ImageDestination for this reference.
+// The caller must call .Close() on the returned ImageDestination.
+func (ref ociReference) NewImageDestination(ctx context.Context, sys *types.SystemContext) (types.ImageDestination, error) {
+	return newImageDestination(sys, ref)
+}
+
+// DeleteImage deletes the named image from the registry, if supported.
+func (ref ociReference) DeleteImage(ctx context.Context, sys *types.SystemContext) error {
+	return errors.Errorf("Deleting images not implemented for oci: images")
+}
+
+// ociLayoutPath returns a path for the oci-layout within a directory using OCI conventions.
+func (ref ociReference) ociLayoutPath() string {
+	return filepath.Join(ref.dir, "oci-layout")
+}
+
+// indexPath returns a path for the index.json within a directory using OCI conventions.
+func (ref ociReference) indexPath() string {
+	return filepath.Join(ref.dir, "index.json")
+}
+
+// blobPath returns a path for a blob within a directory using OCI image-layout conventions.
+func (ref ociReference) blobPath(digest digest.Digest, sharedBlobDir string) (string, error) {
+	if err := digest.Validate(); err != nil {
+		return "", errors.Wrapf(err, "unexpected digest reference %s", digest)
+	}
+	blobDir := filepath.Join(ref.dir, "blobs")
+	if sharedBlobDir != "" {
+		blobDir = sharedBlobDir
+	}
+	return filepath.Join(blobDir, digest.Algorithm().String(), digest.Hex()), nil
+}