revert: "feat: upgrade to OCI 1.1 (#916)" (#958)

.github/workflows/codeql.yml

@@ -15,11 +15,11 @@ name: "CodeQL"
 
 on:
   push:
-    branches: 
+    branches:
       - main
       - release-*
   pull_request:
-    branches: 
+    branches:
       - main
       - release-*
   schedule:

cmd/notation/inspect.go

@@ -83,6 +83,10 @@ Example - Inspect signatures on an OCI artifact identified by a tag  (Notation w
 
 Example - Inspect signatures on an OCI artifact identified by a digest and output as json:
   notation inspect --output json <registry>/<repository>@<digest>
+`
+	experimentalExamples := `
+Example - [Experimental] Inspect signatures on an OCI artifact identified by a digest using the Referrers API, if not supported (returns 404), fallback to the Referrers tag schema
+  notation inspect --allow-referrers-api <registry>/<repository>@<digest>
 `
 	command := &cobra.Command{
 		Use:   "inspect [reference]",
@@ -102,9 +106,6 @@ Example - Inspect signatures on an OCI artifact identified by a digest and outpu
 			if opts.maxSignatures <= 0 {
 				return fmt.Errorf("max-signatures value %d must be a positive number", opts.maxSignatures)
 			}
-			if cmd.Flags().Changed("allow-referrers-api") {
-				fmt.Fprintln(os.Stderr, "Warning: flag '--allow-referrers-api' is deprecated and will be removed in future versions.")
-			}
 			return runInspect(cmd, opts)
 		},
 	}
@@ -114,6 +115,7 @@ Example - Inspect signatures on an OCI artifact identified by a digest and outpu
 	cmd.SetPflagOutput(command.Flags(), &opts.outputFormat, cmd.PflagOutputUsage)
 	command.Flags().IntVar(&opts.maxSignatures, "max-signatures", 100, "maximum number of signatures to evaluate or examine")
 	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, fmt.Sprintf(cmd.PflagReferrersUsageFormat, "inspect"))
+	experimental.HideFlags(command, experimentalExamples, []string{"allow-referrers-api"})
 	return command
 }
 
@@ -127,9 +129,7 @@ func runInspect(command *cobra.Command, opts *inspectOpts) error {
 
 	// initialize
 	reference := opts.reference
-	// always use the Referrers API, if not supported, automatically fallback to
-	// the referrers tag schema
-	sigRepo, err := getRemoteRepository(ctx, &opts.SecureFlagOpts, reference, false)
+	sigRepo, err := getRemoteRepository(ctx, &opts.SecureFlagOpts, reference, opts.allowReferrersAPI)
 	if err != nil {
 		return err
 	}

cmd/notation/list.go

@@ -17,7 +17,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"os"
 
 	notationregistry "github.com/notaryproject/notation-go/registry"
 	cmderr "github.com/notaryproject/notation/cmd/notation/internal/errors"
@@ -53,6 +52,9 @@ Example - List signatures of an OCI artifact identified by a tag (Notation will
   notation list <registry>/<repository>:<tag>
 `
 	experimentalExamples := `
+Example - [Experimental] List signatures of an OCI artifact using the Referrers API. If it's not supported (returns 404), fallback to the Referrers tag schema
+  notation list --allow-referrers-api <registry>/<repository>@<digest>
+
 Example - [Experimental] List signatures of an OCI artifact referenced in an OCI layout
   notation list --oci-layout "<oci_layout_path>@<digest>"
 
@@ -81,18 +83,16 @@ Example - [Experimental] List signatures of an OCI artifact identified by a tag
 			if opts.maxSignatures <= 0 {
 				return fmt.Errorf("max-signatures value %d must be a positive number", opts.maxSignatures)
 			}
-			if cmd.Flags().Changed("allow-referrers-api") {
-				fmt.Fprintln(os.Stderr, "Warning: flag '--allow-referrers-api' is deprecated and will be removed in future versions.")
-			}
 			return runList(cmd.Context(), opts)
 		},
 	}
 	opts.LoggingFlagOpts.ApplyFlags(command.Flags())
 	opts.SecureFlagOpts.ApplyFlags(command.Flags())
 	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, fmt.Sprintf(cmd.PflagReferrersUsageFormat, "list"))
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] list signatures stored in OCI image layout")
+	experimental.HideFlags(command, "", []string{"allow-referrers-api", "oci-layout"})
 	command.Flags().IntVar(&opts.maxSignatures, "max-signatures", 100, "maximum number of signatures to evaluate or examine")
-	experimental.HideFlags(command, experimentalExamples, []string{"oci-layout"})
+	experimental.HideFlags(command, experimentalExamples, []string{"allow-referrers-api", "oci-layout"})
 	return command
 }
 
@@ -102,9 +102,7 @@ func runList(ctx context.Context, opts *listOpts) error {
 
 	// initialize
 	reference := opts.reference
-	// always use the Referrers API, if not supported, automatically fallback to
-	// the referrers tag schema
-	sigRepo, err := getRepository(ctx, opts.inputType, reference, &opts.SecureFlagOpts, false)
+	sigRepo, err := getRepository(ctx, opts.inputType, reference, &opts.SecureFlagOpts, opts.allowReferrersAPI)
 	if err != nil {
 		return err
 	}

cmd/notation/registry.go

@@ -21,6 +21,7 @@ import (
 
 	"github.com/notaryproject/notation-go/log"
 	notationregistry "github.com/notaryproject/notation-go/registry"
+	"github.com/notaryproject/notation/cmd/notation/internal/experimental"
 	notationauth "github.com/notaryproject/notation/internal/auth"
 	"github.com/notaryproject/notation/internal/httputil"
 	"github.com/notaryproject/notation/pkg/configutil"
@@ -40,10 +41,10 @@ const (
 
 // getRepository returns a notationregistry.Repository given user input
 // type and user input reference
-func getRepository(ctx context.Context, inputType inputType, reference string, opts *SecureFlagOpts, forceReferrersTag bool) (notationregistry.Repository, error) {
+func getRepository(ctx context.Context, inputType inputType, reference string, opts *SecureFlagOpts, allowReferrersAPI bool) (notationregistry.Repository, error) {
 	switch inputType {
 	case inputTypeRegistry:
-		return getRemoteRepository(ctx, opts, reference, forceReferrersTag)
+		return getRemoteRepository(ctx, opts, reference, allowReferrersAPI)
 	case inputTypeOCILayout:
 		layoutPath, _, err := parseOCILayoutReference(reference)
 		if err != nil {
@@ -56,18 +57,17 @@ func getRepository(ctx context.Context, inputType inputType, reference string, o
 }
 
 // getRemoteRepository returns a registry.Repository.
-// When forceReferrersTag is true, Notation will always generate an image index
-// according to the Referrers tag schema to store signature.
-//
-// When forceReferrersTag is false, Notation will first try to store the
-// signature as a referrer according to the Referrers API. If the Referrers API
-// is not supported, fallback to use the referrers tag schema.
-// This flag is always FALSE when verify/list/inspect signatures.
+// When experimental feature is disabled OR allowReferrersAPI is not set,
+// Notation always uses referrers tag schema to store and consume signatures
+// by default.
+// When experimental feature is enabled AND allowReferrersAPI is set, Notation
+// tries the Referrers API, if not supported, fallback to use the Referrers
+// tag schema.
 //
 // References:
-// https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers
-// https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#referrers-tag-schema
-func getRemoteRepository(ctx context.Context, opts *SecureFlagOpts, reference string, forceReferrersTag bool) (notationregistry.Repository, error) {
+// https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers
+// https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema
+func getRemoteRepository(ctx context.Context, opts *SecureFlagOpts, reference string, allowReferrersAPI bool) (notationregistry.Repository, error) {
 	logger := log.GetLogger(ctx)
 	ref, err := registry.ParseReference(reference)
 	if err != nil {
@@ -82,13 +82,13 @@ func getRemoteRepository(ctx context.Context, opts *SecureFlagOpts, reference st
 		return nil, err
 	}
 
-	if forceReferrersTag {
-		logger.Info("The referrers tag schema is always attempted")
+	if !experimental.IsDisabled() && allowReferrersAPI {
+		logger.Info("Trying to use the referrers API")
+	} else {
+		logger.Info("Using the referrers tag schema")
 		if err := remoteRepo.SetReferrersCapability(false); err != nil {
 			return nil, err
 		}
-	} else {
-		logger.Info("Allowed to access the referrers API, fallback if not supported")
 	}
 	return notationregistry.NewRepository(remoteRepo), nil
 }

cmd/notation/registry_test.go

@@ -19,13 +19,19 @@ import (
 	"net/http/httptest"
 	"net/url"
 	"testing"
+
+	"github.com/notaryproject/notation/cmd/notation/internal/experimental"
 )
 
 const (
 	zeroDigest = "sha256:0000000000000000000000000000000000000000000000000000000000000000"
 )
 
 func TestRegistry_getRemoteRepositoryWithReferrersAPISupported(t *testing.T) {
+	t.Setenv("NOTATION_EXPERIMENTAL", "1")
+	if experimental.IsDisabled() {
+		t.Fatal("failed to enable experimental")
+	}
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method == http.MethodGet && r.URL.Path == "/v2/test/v1/referrers/"+zeroDigest {
 			w.WriteHeader(http.StatusOK)
@@ -50,6 +56,10 @@ func TestRegistry_getRemoteRepositoryWithReferrersAPISupported(t *testing.T) {
 }
 
 func TestRegistry_getRemoteRepositoryWithReferrersAPINotSupported(t *testing.T) {
+	t.Setenv("NOTATION_EXPERIMENTAL", "1")
+	if experimental.IsDisabled() {
+		t.Fatal("failed to enable experimental")
+	}
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method == http.MethodGet && r.URL.Path == "/v2/test/v1/referrers/"+zeroDigest {
 			w.WriteHeader(http.StatusNotFound)

cmd/notation/sign.go

@@ -14,13 +14,15 @@
 package main
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"os"
 	"strings"
 	"time"
 
 	"github.com/notaryproject/notation-go"
+	notationregistry "github.com/notaryproject/notation-go/registry"
 	"github.com/notaryproject/notation/cmd/notation/internal/experimental"
 	"github.com/notaryproject/notation/internal/cmd"
 	"github.com/notaryproject/notation/internal/envelope"
@@ -39,7 +41,6 @@ type signOpts struct {
 	userMetadata      []string
 	reference         string
 	allowReferrersAPI bool
-	forceReferrersTag bool
 	ociLayout         bool
 	inputType         inputType
 }
@@ -71,11 +72,11 @@ Example - Sign an OCI artifact identified by a tag (Notation will resolve tag to
 
 Example - Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours
   notation sign --expiry 24h <registry>/<repository>@<digest>
-
-Example - Sign an OCI artifact and store signature using the Referrers API. If it's not supported, fallback to the Referrers tag schema
-  notation sign --force-referrers-tag=false <registry>/<repository>@<digest>
 `
 	experimentalExamples := `
+Example - [Experimental] Sign an OCI artifact and store signature using the Referrers API. If it's not supported (returns 404), fallback to the Referrers tag schema
+  notation sign --allow-referrers-api <registry>/<repository>@<digest>
+
 Example - [Experimental] Sign an OCI artifact referenced in an OCI layout
   notation sign --oci-layout "<oci_layout_path>@<digest>"
 
@@ -101,15 +102,6 @@ Example - [Experimental] Sign an OCI artifact identified by a tag and referenced
 			return experimental.CheckFlagsAndWarn(cmd, "allow-referrers-api", "oci-layout")
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			// allow-referrers-api flag is set
-			if cmd.Flags().Changed("allow-referrers-api") {
-				if opts.allowReferrersAPI {
-					fmt.Fprintln(os.Stderr, "Warning: flag '--allow-referrers-api' is deprecated and will be removed in future versions, use '--force-referrers-tag=false' instead.")
-					opts.forceReferrersTag = false
-				} else {
-					fmt.Fprintln(os.Stderr, "Warning: flag '--allow-referrers-api' is deprecated and will be removed in future versions.")
-				}
-			}
 			return runSign(cmd, opts)
 		},
 	}
@@ -120,10 +112,9 @@ Example - [Experimental] Sign an OCI artifact identified by a tag and referenced
 	cmd.SetPflagPluginConfig(command.Flags(), &opts.pluginConfig)
 	cmd.SetPflagUserMetadata(command.Flags(), &opts.userMetadata, cmd.PflagUserMetadataSignUsage)
 	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, fmt.Sprintf(cmd.PflagReferrersUsageFormat, "sign"))
-	cmd.SetPflagReferrersTag(command.Flags(), &opts.forceReferrersTag, "force to store signatures using the referrers tag schema")
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] sign the artifact stored as OCI image layout")
-	command.MarkFlagsMutuallyExclusive("oci-layout", "force-referrers-tag", "allow-referrers-api")
-	experimental.HideFlags(command, experimentalExamples, []string{"oci-layout"})
+	command.MarkFlagsMutuallyExclusive("oci-layout", "allow-referrers-api")
+	experimental.HideFlags(command, experimentalExamples, []string{"allow-referrers-api", "oci-layout"})
 	return command
 }
 
@@ -136,11 +127,14 @@ func runSign(command *cobra.Command, cmdOpts *signOpts) error {
 	if err != nil {
 		return err
 	}
-	sigRepo, err := getRepository(ctx, cmdOpts.inputType, cmdOpts.reference, &cmdOpts.SecureFlagOpts, cmdOpts.forceReferrersTag)
+	if cmdOpts.allowReferrersAPI {
+		fmt.Fprintln(os.Stderr, "Warning: using the Referrers API to store signature. On success, must set the `--allow-referrers-api` flag to list, inspect, and verify the signature.")
+	}
+	sigRepo, err := getRepository(ctx, cmdOpts.inputType, cmdOpts.reference, &cmdOpts.SecureFlagOpts, cmdOpts.allowReferrersAPI)
 	if err != nil {
 		return err
 	}
-	signOpts, err := prepareSigningOpts(cmdOpts)
+	signOpts, err := prepareSigningOpts(ctx, cmdOpts, sigRepo)
 	if err != nil {
 		return err
 	}
@@ -168,7 +162,7 @@ func runSign(command *cobra.Command, cmdOpts *signOpts) error {
 	return nil
 }
 
-func prepareSigningOpts(opts *signOpts) (notation.SignOptions, error) {
+func prepareSigningOpts(ctx context.Context, opts *signOpts, sigRepo notationregistry.Repository) (notation.SignOptions, error) {
 	mediaType, err := envelope.GetEnvelopeMediaType(opts.SignerFlagOpts.SignatureFormat)
 	if err != nil {
 		return notation.SignOptions{}, err