refactor! remove pkg directory (#145)

* refactor!: remove pkg directory * chore: include breaking changes in draft
2024-09-02 16:17:50 +01:00
parent 23849c1c2e
commit 8982778507
103 changed files with 152 additions and 142 deletions
--- a/mirror/README.md
+++ b/mirror/README.md
@@ -0,0 +1,2 @@
+## mirror
+This package contains components to mirror TUF metadata and targets to OCI.
--- a/mirror/example_mirror_test.go
+++ b/mirror/example_mirror_test.go
@@ -0,0 +1,152 @@
+package mirror_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/docker/attest/mirror"
+	"github.com/docker/attest/oci"
+	"github.com/docker/attest/tuf"
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+)
+
+type TufMirrorOutput struct {
+	metadata          v1.Image
+	delegatedMetadata []*mirror.Image
+	targets           []*mirror.Image
+	delegatedTargets  []*mirror.Index
+}
+
+func ExampleNewTUFMirror() {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		panic(err)
+	}
+	tufOutputPath := filepath.Join(home, ".docker", "tuf")
+
+	// configure TUF mirror
+	metadataURI := "https://docker.github.io/tuf-staging/metadata"
+	targetsURI := "https://docker.github.io/tuf-staging/targets"
+	m, err := mirror.NewTUFMirror(tuf.DockerTUFRootStaging.Data, tufOutputPath, metadataURI, targetsURI, tuf.NewMockVersionChecker())
+	if err != nil {
+		panic(err)
+	}
+
+	// create metadata manifest
+	metadataManifest, err := m.GetMetadataManifest(metadataURI)
+	if err != nil {
+		panic(err)
+	}
+	// create delegated targets metadata manifests
+	delegatedMetadata, err := m.GetDelegatedMetadataMirrors()
+	if err != nil {
+		panic(err)
+	}
+
+	// create targets manifest
+	targets, err := m.GetTUFTargetMirrors()
+	if err != nil {
+		panic(err)
+	}
+	// create delegated targets manifests
+	delegatedTargets, err := m.GetDelegatedTargetMirrors()
+	if err != nil {
+		panic(err)
+	}
+
+	mirrorOutput := &TufMirrorOutput{
+		metadata:          metadataManifest,
+		delegatedMetadata: delegatedMetadata,
+		targets:           targets,
+		delegatedTargets:  delegatedTargets,
+	}
+
+	// push metadata and targets to registry (optional)
+	err = mirrorToRegistry(mirrorOutput)
+	if err != nil {
+		panic(err)
+	}
+
+	// save metadata and targets to local directory (optional)
+	mirrorOutputPath := filepath.Join(home, ".docker", "tuf", "mirror")
+	err = mirrorToLocal(mirrorOutput, mirrorOutputPath)
+	if err != nil {
+		panic(err)
+	}
+}
+
+func mirrorToRegistry(o *TufMirrorOutput) error {
+	// push metadata to registry
+	metadataRepo := "registry-1.docker.io/docker/tuf-metadata:latest"
+	err := oci.PushImageToRegistry(o.metadata, metadataRepo)
+	if err != nil {
+		return err
+	}
+	// push delegated metadata to registry
+	for _, metadata := range o.delegatedMetadata {
+		repo, _, ok := strings.Cut(metadataRepo, ":")
+		if !ok {
+			return fmt.Errorf("failed to get repo without tag: %s", metadataRepo)
+		}
+		imageName := fmt.Sprintf("%s:%s", repo, metadata.Tag)
+		err = oci.PushImageToRegistry(metadata.Image, imageName)
+		if err != nil {
+			return err
+		}
+	}
+
+	// push top-level targets to registry
+	targetsRepo := "registry-1.docker.io/docker/tuf-targets"
+	for _, target := range o.targets {
+		imageName := fmt.Sprintf("%s:%s", targetsRepo, target.Tag)
+		err = oci.PushImageToRegistry(target.Image, imageName)
+		if err != nil {
+			return err
+		}
+	}
+	// push delegated targets to registry
+	for _, target := range o.delegatedTargets {
+		imageName := fmt.Sprintf("%s:%s", targetsRepo, target.Tag)
+		err = oci.PushIndexToRegistry(target.Index, imageName)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func mirrorToLocal(o *TufMirrorOutput, outputPath string) error {
+	// output metadata to local directory
+	err := oci.SaveImageAsOCILayout(o.metadata, outputPath)
+	if err != nil {
+		return err
+	}
+	// output delegated metadata to local directory
+	for _, metadata := range o.delegatedMetadata {
+		path := filepath.Join(outputPath, metadata.Tag)
+		err = oci.SaveImageAsOCILayout(metadata.Image, path)
+		if err != nil {
+			return err
+		}
+	}
+
+	// output top-level targets to local directory
+	for _, target := range o.targets {
+		path := filepath.Join(outputPath, target.Tag)
+		err = oci.SaveImageAsOCILayout(target.Image, path)
+		if err != nil {
+			return err
+		}
+	}
+	// output delegated targets to local directory
+	for _, target := range o.delegatedTargets {
+		path := filepath.Join(outputPath, target.Tag)
+		err = oci.SaveIndexAsOCILayout(target.Index, path)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
--- a/mirror/metadata.go
+++ b/mirror/metadata.go
@@ -0,0 +1,197 @@
+package mirror
+
+import (
+	"fmt"
+	"strconv"
+
+	"github.com/docker/attest/oci"
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+	"github.com/google/go-containerregistry/pkg/v1/empty"
+	"github.com/google/go-containerregistry/pkg/v1/mutate"
+	"github.com/google/go-containerregistry/pkg/v1/static"
+	"github.com/google/go-containerregistry/pkg/v1/types"
+	"github.com/theupdateframework/go-tuf/v2/metadata"
+)
+
+// -----------------
+// TUF root metadata
+// -----------------
+
+// GetMetadataManifest returns an image with TUF root metadata as layers.
+func (m *TUFMirror) GetMetadataManifest(metadataURL string) (*oci.EmptyConfigImage, error) {
+	metadata, err := m.getMetadataMirror(metadataURL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get metadata: %w", err)
+	}
+	manifest, err := m.buildMetadataManifest(metadata)
+	if err != nil {
+		return nil, fmt.Errorf("failed to build metadata manifest: %w", err)
+	}
+	return &oci.EmptyConfigImage{Image: manifest}, nil
+}
+
+// getMetadataMirror returns a TufMetadata struct with TUF metadata as map of file names to bytes.
+func (m *TUFMirror) getMetadataMirror(metadataURL string) (*TUFMetadata, error) {
+	trustedMetadata := m.TUFClient.GetMetadata()
+
+	rootMetadata := map[string][]byte{}
+	rootVersion := trustedMetadata.Root.Signed.Version
+	// get the previous versions of root metadata if any
+	if rootVersion != 1 {
+		var err error
+		rootMetadata, err = m.TUFClient.GetPriorRoots(metadataURL)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get prior root metadata: %w", err)
+		}
+	}
+	// get current root metadata
+	rootBytes, err := trustedMetadata.Root.ToBytes(false)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get root metadata: %w", err)
+	}
+	rootMetadata[nameFromRole(metadata.ROOT, strconv.FormatInt(rootVersion, 10))] = rootBytes
+
+	snapshotBytes, err := trustedMetadata.Snapshot.ToBytes(false)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get snapshot metadata: %w", err)
+	}
+	targetsBytes, err := trustedMetadata.Targets[metadata.TARGETS].ToBytes(false)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get targets metadata: %w", err)
+	}
+	timestampBytes, err := trustedMetadata.Timestamp.ToBytes(false)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get timestamp metadata: %w", err)
+	}
+
+	snapshotVersion := ""
+	targetsVersion := ""
+	if trustedMetadata.Root.Signed.ConsistentSnapshot {
+		snapshotVersion = strconv.FormatInt(trustedMetadata.Snapshot.Signed.Version, 10)
+		targetsVersion = strconv.FormatInt(trustedMetadata.Targets[metadata.TARGETS].Signed.Version, 10)
+	}
+	return &TUFMetadata{
+		Root:      rootMetadata,
+		Snapshot:  map[string][]byte{nameFromRole(metadata.SNAPSHOT, snapshotVersion): snapshotBytes},
+		Targets:   map[string][]byte{nameFromRole(metadata.TARGETS, targetsVersion): targetsBytes},
+		Timestamp: timestampBytes,
+	}, nil
+}
+
+// buildMetadataManifest returns an OCI image with TUF metadata as layers with annotations.
+func (m *TUFMirror) buildMetadataManifest(metadata *TUFMetadata) (v1.Image, error) {
+	img := empty.Image
+	img = mutate.MediaType(img, types.OCIManifestSchema1)
+	img = mutate.ConfigMediaType(img, types.OCIConfigJSON)
+	for _, role := range TUFRoles {
+		layers, err := m.makeRoleLayers(role, metadata)
+		if err != nil {
+			return nil, fmt.Errorf("failed to make role layer: %w", err)
+		}
+		img, err = mutate.Append(img, layers...)
+		if err != nil {
+			return nil, fmt.Errorf("failed to append role layer to image: %w", err)
+		}
+	}
+	return img, nil
+}
+
+// makeRoleLayers returns a list of layers for a given TUF role.
+func (m *TUFMirror) makeRoleLayers(role TUFRole, tufMetadata *TUFMetadata) ([]mutate.Addendum, error) {
+	var layers []mutate.Addendum
+	ann := map[string]string{tufFileAnnotation: ""}
+	switch role {
+	case metadata.ROOT:
+		layers = m.annotatedMetaLayers(tufMetadata.Root)
+	case metadata.SNAPSHOT:
+		layers = m.annotatedMetaLayers(tufMetadata.Snapshot)
+	case metadata.TARGETS:
+		layers = m.annotatedMetaLayers(tufMetadata.Targets)
+	case metadata.TIMESTAMP:
+		ann[tufFileAnnotation] = fmt.Sprintf("%s.json", role)
+		layers = append(layers, mutate.Addendum{Layer: static.NewLayer(tufMetadata.Timestamp, tufMetadataMediaType), Annotations: ann})
+	default:
+		return nil, fmt.Errorf("unsupported TUF role: %s", role)
+	}
+	return layers, nil
+}
+
+// annotatedMetaLayers returns a list of layers with annotations for each TUF metadata file.
+func (m *TUFMirror) annotatedMetaLayers(meta map[string][]byte) []mutate.Addendum {
+	var layers []mutate.Addendum
+	for name, data := range meta {
+		ann := map[string]string{tufFileAnnotation: name}
+		layers = append(layers, mutate.Addendum{Layer: static.NewLayer(data, tufMetadataMediaType), Annotations: ann})
+	}
+	return layers
+}
+
+// ------------------------------
+// TUF delegated targets metadata
+// ------------------------------
+
+// GetDelegatedMetadataMirrors returns a list of mirrors (image/tag pairs) for each delegated targets role metadata.
+func (m *TUFMirror) GetDelegatedMetadataMirrors() ([]*Image, error) {
+	// get current delegated targets metadata
+	delegatedTargets, err := m.getDelegatedTargetsMetadata()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get delegated targets metadata: %w", err)
+	}
+	mirror, err := m.buildDelegatedMetadataManifests(delegatedTargets)
+	if err != nil {
+		return nil, fmt.Errorf("failed to build delegated targets manifests: %w", err)
+	}
+	return mirror, nil
+}
+
+// getDelegatedTargetsMetadata returns delegated targets metadata as a list of DelegatedTargetMetadata (role name and data).
+func (m *TUFMirror) getDelegatedTargetsMetadata() ([]DelegatedTargetMetadata, error) {
+	var delegatedTargets []DelegatedTargetMetadata
+	md := m.TUFClient.GetMetadata()
+	for _, role := range md.Targets[metadata.TARGETS].Signed.Delegations.Roles {
+		roleMetadata, err := m.TUFClient.LoadDelegatedTargets(role.Name, metadata.TARGETS)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get delegated role metadata: %w", err)
+		}
+		roleBytes, err := roleMetadata.ToBytes(false)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get role %s metadata: %w", role.Name, err)
+		}
+		meta, ok := md.Snapshot.Signed.Meta[nameFromRole(role.Name, "")]
+		if !ok {
+			return nil, fmt.Errorf("failed to get role %s metadata: %w", role.Name, err)
+		}
+		// extract target metadata version in case of consistent snapshot naming
+		version := ""
+		if md.Root.Signed.ConsistentSnapshot {
+			version = strconv.FormatInt(meta.Version, 10)
+		}
+		delegatedTargets = append(delegatedTargets, DelegatedTargetMetadata{Name: role.Name, Version: version, Data: roleBytes})
+	}
+	return delegatedTargets, nil
+}
+
+// buildDelegatedMetadataManifests returns a list of mirrors (image/tag pairs) for each delegated target role metadata.
+func (m *TUFMirror) buildDelegatedMetadataManifests(delegated []DelegatedTargetMetadata) ([]*Image, error) {
+	manifests := []*Image{}
+	for _, role := range delegated {
+		img := empty.Image
+		img = mutate.MediaType(img, types.OCIManifestSchema1)
+		img = mutate.ConfigMediaType(img, types.OCIConfigJSON)
+		ann := map[string]string{tufFileAnnotation: nameFromRole(role.Name, role.Version)}
+		layer := mutate.Addendum{Layer: static.NewLayer(role.Data, tufMetadataMediaType), Annotations: ann}
+		img, err := mutate.Append(img, layer)
+		if err != nil {
+			return nil, fmt.Errorf("failed to append delegated targets layer to image: %w", err)
+		}
+		manifests = append(manifests, &Image{Image: &oci.EmptyConfigImage{Image: img}, Tag: role.Name})
+	}
+	return manifests, nil
+}
+
+func nameFromRole(role, version string) string {
+	if version != "" {
+		return fmt.Sprintf("%s.%s.json", version, role)
+	}
+	return fmt.Sprintf("%s.json", role)
+}
--- a/mirror/metadata_test.go
+++ b/mirror/metadata_test.go
@@ -0,0 +1,93 @@
+package mirror
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/docker/attest/internal/test"
+	"github.com/docker/attest/tuf"
+	"github.com/stretchr/testify/assert"
+	"github.com/theupdateframework/go-tuf/v2/metadata"
+)
+
+const (
+	metadataPath = "/metadata"
+	targetsPath  = "/targets"
+)
+
+func TestGetTufMetadataMirror(t *testing.T) {
+	server := httptest.NewServer(http.FileServer(http.Dir(filepath.Join("..", "test", "testdata", "tuf", "test-repo"))))
+	defer server.Close()
+
+	path := test.CreateTempDir(t, "", "tuf_temp")
+	m, err := NewTUFMirror(tuf.DockerTUFRootDev.Data, path, server.URL+metadataPath, server.URL+targetsPath, tuf.NewMockVersionChecker())
+	assert.NoError(t, err)
+
+	tufMetadata, err := m.getMetadataMirror(server.URL + metadataPath)
+	assert.NoError(t, err)
+
+	// check that all roles are not empty
+	assert.Greater(t, len(tufMetadata.Root), 0)
+	assert.Greater(t, len(tufMetadata.Snapshot), 0)
+	assert.Greater(t, len(tufMetadata.Targets), 0)
+	assert.Greater(t, len(tufMetadata.Timestamp), 0)
+}
+
+func TestGetMetadataManifest(t *testing.T) {
+	server := httptest.NewServer(http.FileServer(http.Dir(filepath.Join("..", "test", "testdata", "tuf", "test-repo"))))
+	defer server.Close()
+
+	path := test.CreateTempDir(t, "", "tuf_temp")
+	m, err := NewTUFMirror(tuf.DockerTUFRootDev.Data, path, server.URL+metadataPath, server.URL+targetsPath, tuf.NewMockVersionChecker())
+	assert.NoError(t, err)
+
+	img, err := m.GetMetadataManifest(server.URL + metadataPath)
+	assert.NoError(t, err)
+	assert.NotNil(t, img)
+
+	mf, err := img.RawManifest()
+	assert.NoError(t, err)
+
+	type Annotations struct {
+		Annotations map[string]string `json:"annotations"`
+	}
+	type Layers struct {
+		Layers []Annotations `json:"layers"`
+	}
+	l := &Layers{}
+	err = json.Unmarshal(mf, l)
+	assert.NoError(t, err)
+
+	// check that layers are annotated and use consistent snapshot naming
+	for _, layer := range l.Layers {
+		ann, ok := layer.Annotations[tufFileAnnotation]
+		assert.True(t, ok)
+		// check for consistent snapshot version
+		parts := strings.Split(ann, ".")
+		if parts[0] == metadata.TIMESTAMP {
+			continue
+		}
+		_, err := strconv.Atoi(parts[0])
+		assert.NoError(t, err)
+	}
+}
+
+func TestGetDelegatedMetadataMirrors(t *testing.T) {
+	server := httptest.NewServer(http.FileServer(http.Dir(filepath.Join("..", "test", "testdata", "tuf", "test-repo"))))
+	defer server.Close()
+
+	path := test.CreateTempDir(t, "", "tuf_temp")
+	m, err := NewTUFMirror(tuf.DockerTUFRootDev.Data, path, server.URL+metadataPath, server.URL+targetsPath, tuf.NewMockVersionChecker())
+	assert.NoError(t, err)
+
+	delegations, err := m.GetDelegatedMetadataMirrors()
+	assert.NoError(t, err)
+
+	assert.NotNil(t, delegations)
+	assert.Greater(t, len(delegations), 0)
+}
--- a/mirror/mirror.go
+++ b/mirror/mirror.go
@@ -0,0 +1,18 @@
+package mirror
+
+import (
+	"fmt"
+
+	"github.com/docker/attest/tuf"
+)
+
+func NewTUFMirror(root []byte, tufPath, metadataURL, targetsURL string, versionChecker tuf.VersionChecker) (*TUFMirror, error) {
+	if root == nil {
+		root = tuf.DockerTUFRootDefault.Data
+	}
+	tufClient, err := tuf.NewClient(&tuf.ClientOptions{InitialRoot: root, Path: tufPath, MetadataSource: metadataURL, TargetsSource: targetsURL, VersionChecker: versionChecker})
+	if err != nil {
+		return nil, fmt.Errorf("failed to create TUF client: %w", err)
+	}
+	return &TUFMirror{TUFClient: tufClient, tufPath: tufPath, metadataURL: metadataURL, targetsURL: targetsURL}, nil
+}
--- a/mirror/targets.go
+++ b/mirror/targets.go
@@ -0,0 +1,111 @@
+package mirror
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+
+	"github.com/docker/attest/oci"
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+	"github.com/google/go-containerregistry/pkg/v1/empty"
+	"github.com/google/go-containerregistry/pkg/v1/mutate"
+	"github.com/google/go-containerregistry/pkg/v1/static"
+	"github.com/google/go-containerregistry/pkg/v1/types"
+	"github.com/theupdateframework/go-tuf/v2/metadata"
+)
+
+// GetTUFTargetMirrors returns a list of top-level target files as MirrorImages (image with tag).
+func (m *TUFMirror) GetTUFTargetMirrors() ([]*Image, error) {
+	targetMirrors := []*Image{}
+	md := m.TUFClient.GetMetadata()
+
+	// for each top-level target file, create an image with the target file as a layer
+	targets := md.Targets[metadata.TARGETS].Signed.Targets
+	for _, t := range targets {
+		// download target file
+		file, err := m.TUFClient.DownloadTarget(t.Path, filepath.Join(m.tufPath, "download"))
+		if err != nil {
+			return nil, fmt.Errorf("failed to download target %s: %w", t.Path, err)
+		}
+		// create image with target file as layer
+		img := empty.Image
+		img = mutate.MediaType(img, types.OCIManifestSchema1)
+		img = mutate.ConfigMediaType(img, types.OCIConfigJSON)
+		// annotate layer
+		hash, ok := t.Hashes["sha256"]
+		if !ok {
+			return nil, fmt.Errorf("missing sha256 hash for target %s", t.Path)
+		}
+		name := hash.String() + "." + t.Path
+		ann := map[string]string{tufFileAnnotation: name}
+		layer := mutate.Addendum{Layer: static.NewLayer(file.Data, tufTargetMediaType), Annotations: ann}
+		img, err = mutate.Append(img, layer)
+		if err != nil {
+			return nil, fmt.Errorf("failed to append role layer to image: %w", err)
+		}
+		targetMirrors = append(targetMirrors, &Image{Image: &oci.EmptyConfigImage{Image: img}, Tag: name})
+	}
+	return targetMirrors, nil
+}
+
+// GetDelegatedTargetMirrors returns a list of delegated target files as MirrorIndexes (image index with tag)
+// each image in the index contains a delegated target file.
+func (m *TUFMirror) GetDelegatedTargetMirrors() ([]*Index, error) {
+	mirror := []*Index{}
+	md := m.TUFClient.GetMetadata()
+
+	// for each delegated role, create an image index with target files as images
+	roles := md.Targets[metadata.TARGETS].Signed.Delegations.Roles
+	for _, role := range roles {
+		// create an image index
+		index := v1.ImageIndex(empty.Index)
+
+		// get delegated targets metadata for role
+		roleMeta, err := m.TUFClient.LoadDelegatedTargets(role.Name, metadata.TARGETS)
+		if err != nil {
+			return nil, fmt.Errorf("failed to load delegated targets metadata: %w", err)
+		}
+
+		// for each target file, create an image with the target file as a layer
+		for _, target := range roleMeta.Signed.Targets {
+			// download target file
+			file, err := m.TUFClient.DownloadTarget(target.Path, filepath.Join(m.tufPath, "download"))
+			if err != nil {
+				return nil, fmt.Errorf("failed to download target %s: %w", target.Path, err)
+			}
+			// create image with target file as layer
+			img := empty.Image
+			img = mutate.MediaType(img, types.OCIManifestSchema1)
+			img = mutate.ConfigMediaType(img, types.OCIConfigJSON)
+			// annotate layer
+			hash, ok := target.Hashes["sha256"]
+			if !ok {
+				return nil, fmt.Errorf("missing sha256 hash for target %s", target.Path)
+			}
+			filename := filepath.Base(target.Path)
+			subdir, ok := strings.CutSuffix(target.Path, "/"+filename)
+			if !ok {
+				return nil, fmt.Errorf("failed to find target subdirectory [%s] in path: %s", subdir, target.Path)
+			}
+			name := hash.String() + "." + filename
+			ann := map[string]string{tufFileAnnotation: name}
+			layer := mutate.Addendum{Layer: static.NewLayer(file.Data, tufTargetMediaType), Annotations: ann}
+			img, err = mutate.Append(img, layer)
+			if err != nil {
+				return nil, fmt.Errorf("failed to append role layer to image: %w", err)
+			}
+			emptyConfigImage := &oci.EmptyConfigImage{Image: img}
+			// append image to index with annotation
+			index = mutate.AppendManifests(index, mutate.IndexAddendum{
+				Add: emptyConfigImage,
+				Descriptor: v1.Descriptor{
+					Annotations: map[string]string{
+						tufFileAnnotation: fmt.Sprintf("%s/%s", subdir, name),
+					},
+				},
+			})
+		}
+		mirror = append(mirror, &Index{Index: index, Tag: role.Name})
+	}
+	return mirror, nil
+}
--- a/mirror/targets_test.go
+++ b/mirror/targets_test.go
@@ -0,0 +1,103 @@
+package mirror
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/docker/attest/internal/test"
+	"github.com/docker/attest/tuf"
+	"github.com/stretchr/testify/assert"
+)
+
+type Layer struct {
+	Annotations map[string]string `json:"annotations"`
+	Digest      string            `json:"digest"`
+}
+type Layers struct {
+	Layers []Layer `json:"layers"`
+}
+
+func TestGetTufTargetsMirror(t *testing.T) {
+	server := httptest.NewServer(http.FileServer(http.Dir(filepath.Join("..", "test", "testdata", "tuf", "test-repo"))))
+	defer server.Close()
+
+	path := test.CreateTempDir(t, "", "tuf_temp")
+	m, err := NewTUFMirror(tuf.DockerTUFRootDev.Data, path, server.URL+metadataPath, server.URL+targetsPath, tuf.NewMockVersionChecker())
+	assert.NoError(t, err)
+
+	targets, err := m.GetTUFTargetMirrors()
+	assert.NoError(t, err)
+	assert.Greater(t, len(targets), 0)
+
+	// check for image layer annotations
+	for _, target := range targets {
+		img := target.Image
+		mf, err := img.RawManifest()
+		assert.NoError(t, err)
+
+		// unmarshal manifest with annotations
+		l := &Layers{}
+		err = json.Unmarshal(mf, l)
+		assert.NoError(t, err)
+
+		// check that layers are annotated
+		for _, layer := range l.Layers {
+			ann, ok := layer.Annotations[tufFileAnnotation]
+			assert.True(t, ok)
+			parts := strings.Split(ann, ".")
+			// <digest>.filename.<ext|optional>
+			assert.GreaterOrEqual(t, len(parts), 2)
+		}
+	}
+}
+
+func TestTargetDelegationMetadata(t *testing.T) {
+	server := httptest.NewServer(http.FileServer(http.Dir(filepath.Join("..", "test", "testdata", "tuf", "test-repo"))))
+	defer server.Close()
+
+	path := test.CreateTempDir(t, "", "tuf_temp")
+	tm, err := NewTUFMirror(tuf.DockerTUFRootDev.Data, path, server.URL+metadataPath, server.URL+targetsPath, tuf.NewMockVersionChecker())
+	assert.NoError(t, err)
+
+	targets, err := tm.TUFClient.LoadDelegatedTargets("test-role", "targets")
+	assert.NoError(t, err)
+	assert.Greater(t, len(targets.Signed.Targets), 0)
+}
+
+func TestGetDelegatedTargetMirrors(t *testing.T) {
+	server := httptest.NewServer(http.FileServer(http.Dir(filepath.Join("..", "test", "testdata", "tuf", "test-repo"))))
+	defer server.Close()
+
+	path := test.CreateTempDir(t, "", "tuf_temp")
+	m, err := NewTUFMirror(tuf.DockerTUFRootDev.Data, path, server.URL+metadataPath, server.URL+targetsPath, tuf.NewMockVersionChecker())
+	assert.NoError(t, err)
+
+	mirrors, err := m.GetDelegatedTargetMirrors()
+	assert.NoError(t, err)
+	assert.Greater(t, len(mirrors), 0)
+
+	// check for index image annotations
+	for _, mirror := range mirrors {
+		idx := mirror.Index
+		mf, err := idx.RawManifest()
+		assert.NoError(t, err)
+
+		// unmarshal manifest with annotations
+		l := &Layers{}
+		err = json.Unmarshal(mf, l)
+		assert.NoError(t, err)
+
+		// check that layers are annotated
+		for _, layer := range l.Layers {
+			ann, ok := layer.Annotations[tufFileAnnotation]
+			assert.True(t, ok)
+			parts := strings.Split(ann, ".")
+			// <subdir>/<digest>.filename.<ext|optional>
+			assert.GreaterOrEqual(t, len(parts), 2)
+		}
+	}
+}
--- a/mirror/types.go
+++ b/mirror/types.go
@@ -0,0 +1,50 @@
+package mirror
+
+import (
+	"github.com/docker/attest/oci"
+	"github.com/docker/attest/tuf"
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+	"github.com/theupdateframework/go-tuf/v2/metadata"
+)
+
+const (
+	DefaultMetadataURL   = "https://docker.github.io/tuf/metadata"
+	DefaultTargetsURL    = "https://docker.github.io/tuf/targets"
+	tufMetadataMediaType = "application/vnd.tuf.metadata+json"
+	tufTargetMediaType   = "application/vnd.tuf.target"
+	tufFileAnnotation    = "tuf.io/filename"
+)
+
+type TUFRole string
+
+var TUFRoles = []TUFRole{metadata.ROOT, metadata.SNAPSHOT, metadata.TARGETS, metadata.TIMESTAMP}
+
+type TUFMetadata struct {
+	Root      map[string][]byte
+	Snapshot  map[string][]byte
+	Targets   map[string][]byte
+	Timestamp []byte
+}
+
+type DelegatedTargetMetadata struct {
+	Name    string
+	Version string
+	Data    []byte
+}
+
+type Image struct {
+	Image *oci.EmptyConfigImage
+	Tag   string
+}
+
+type Index struct {
+	Index v1.ImageIndex
+	Tag   string
+}
+
+type TUFMirror struct {
+	TUFClient   *tuf.Client
+	tufPath     string
+	metadataURL string
+	targetsURL  string
+}