update: align Notation with OCI specs

cmd/notation/inspect.go

@@ -61,17 +61,17 @@ func inspectCommand(opts *inspectOpts) *cobra.Command {
 	longMessage := `Inspect all signatures associated with the signed artifact.
 
 Example - Inspect signatures on an OCI artifact identified by a digest:
-	notation inspect <registry>/<repository>@<digest>
+  notation inspect <registry>/<repository>@<digest>
 
 Example - Inspect signatures on an OCI artifact identified by a tag  (Notation will resolve tag to digest):
-	notation inspect <registry>/<repository>:<tag>
+  notation inspect <registry>/<repository>:<tag>
 
 Example - Inspect signatures on an OCI artifact identified by a digest and output as json:
-	notation inspect --output json <registry>/<repository>@<digest>
+  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, fallback to the Referrers tag schema
-	notation inspect --allow-referrers-api <registry>/<repository>@<digest>
+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]",
@@ -95,7 +95,7 @@ Example - [Experimental] Inspect signatures on an OCI artifact identified by a d
 	opts.LoggingFlagOpts.ApplyFlags(command.Flags())
 	opts.SecureFlagOpts.ApplyFlags(command.Flags())
 	cmd.SetPflagOutput(command.Flags(), &opts.outputFormat, cmd.PflagOutputUsage)
-	command.Flags().BoolVar(&opts.allowReferrersAPI, "allow-referrers-api", false, "[Experimental] use the Referrers API to inspect signatures, if not supported, fallback to the Referrers tag schema")
+	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, cmd.PflagReferrersAPIInspectUsage)
 	experimental.HideFlags(command, experimentalExamples, []string{"allow-referrers-api"})
 	return command
 }

cmd/notation/list.go

@@ -28,7 +28,7 @@ func listCommand(opts *listOpts) *cobra.Command {
 			inputType: inputTypeRegistry, // remote registry by default
 		}
 	}
-	cmd := &cobra.Command{
+	command := &cobra.Command{
 		Use:     "list [flags] <reference>",
 		Aliases: []string{"ls"},
 		Short:   "List signatures of the signed artifact",
@@ -50,12 +50,12 @@ func listCommand(opts *listOpts) *cobra.Command {
 			return runList(cmd.Context(), opts)
 		},
 	}
-	opts.LoggingFlagOpts.ApplyFlags(cmd.Flags())
-	opts.SecureFlagOpts.ApplyFlags(cmd.Flags())
-	cmd.Flags().BoolVar(&opts.allowReferrersAPI, "allow-referrers-api", false, "[Experimental] use the Referrers API to list signatures, if not supported, fallback to the Referrers tag schema")
-	cmd.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] list signatures stored in OCI image layout")
-	experimental.HideFlags(cmd, "", []string{"allow-referrers-api", "oci-layout"})
-	return cmd
+	opts.LoggingFlagOpts.ApplyFlags(command.Flags())
+	opts.SecureFlagOpts.ApplyFlags(command.Flags())
+	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, cmd.PflagReferrersAPIListUsage)
+	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"})
+	return command
 }
 
 func runList(ctx context.Context, opts *listOpts) error {

cmd/notation/registry.go

@@ -68,13 +68,13 @@ func getRemoteRepository(ctx context.Context, opts *SecureFlagOpts, reference st
 		return nil, err
 	}
 
-	if experimental.IsDisabled() || !allowReferrersAPI {
-		logger.Info("By default, using the Referrers tag schema")
+	if !experimental.IsDisabled() && allowReferrersAPI {
+		logger.Info("Trying to use referrers API")
+	} else {
+		logger.Info("Using the Referrers tag schema")
 		if err := remoteRepo.SetReferrersCapability(false); err != nil {
 			return nil, err
 		}
-	} else {
-		logger.Info("Using the Referrers API, if not supported, automatically fallback to the Referrers tag schema")
 	}
 	return notationregistry.NewRepository(remoteRepo), nil
 }

cmd/notation/sign.go

@@ -61,8 +61,8 @@ Example - Sign an OCI artifact stored in a registry and specify the signature ex
   notation sign --expiry 24h <registry>/<repository>@<digest>
 `
 	experimentalExamples := `
-Example - [Experimental] Sign an OCI artifact and store signature using the Referrers API, if not supported, fallback to the Referrers tag schema
-	notation sign --allow-referrers-api <registry>/<repository>@<digest>
+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>"
@@ -98,7 +98,7 @@ Example - [Experimental] Sign an OCI artifact identified by a tag and referenced
 	cmd.SetPflagExpiry(command.Flags(), &opts.expiry)
 	cmd.SetPflagPluginConfig(command.Flags(), &opts.pluginConfig)
 	cmd.SetPflagUserMetadata(command.Flags(), &opts.userMetadata, cmd.PflagUserMetadataSignUsage)
-	command.Flags().BoolVar(&opts.allowReferrersAPI, "allow-referrers-api", false, "[Experimental] use the Referrers API to store signatures in the registry, if not supported, fallback to the Referrers tag schema")
+	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, cmd.PflagReferrersAPISignUsage)
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] sign the artifact stored as OCI image layout")
 	experimental.HideFlags(command, experimentalExamples, []string{"allow-referrers-api", "oci-layout"})
 	return command

cmd/notation/verify.go

@@ -49,8 +49,8 @@ Example - Verify a signature on an OCI artifact identified by a tag  (Notation w
   notation verify <registry>/<repository>:<tag>
 `
 	experimentalExamples := `
-Example - [Experimental] Verify an OCI artifact using the Referrers API, if not supported, fallback to the Referrers tag schema
-	notation verify --allow-referrers-api <registry>/<repository>@<digest>
+Example - [Experimental] Verify an OCI artifact using the Referrers API, if not supported (returns 404), fallback to the Referrers tag schema
+  notation verify --allow-referrers-api <registry>/<repository>@<digest>
 
 Example - [Experimental] Verify a signature on an OCI artifact referenced in an OCI layout using trust policy statement specified by scope.
   notation verify --oci-layout <registry>/<repository>@<digest> --scope <trust_policy_scope>
@@ -83,7 +83,7 @@ Example - [Experimental] Verify a signature on an OCI artifact identified by a t
 	opts.SecureFlagOpts.ApplyFlags(command.Flags())
 	command.Flags().StringArrayVar(&opts.pluginConfig, "plugin-config", nil, "{key}={value} pairs that are passed as it is to a plugin, if the verification is associated with a verification plugin, refer plugin documentation to set appropriate values")
 	cmd.SetPflagUserMetadata(command.Flags(), &opts.userMetadata, cmd.PflagUserMetadataVerifyUsage)
-	command.Flags().BoolVar(&opts.allowReferrersAPI, "allow-referrers-api", false, "[Experimental] use the Referrers API to verify signatures, if not supported, fallback to the Referrers tag schema")
+	cmd.SetPflagReferrersAPI(command.Flags(), &opts.allowReferrersAPI, cmd.PflagReferrersAPIVerifyUsage)
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] verify the artifact stored as OCI image layout")
 	command.Flags().StringVar(&opts.trustPolicyScope, "scope", "", "[Experimental] set trust policy scope for artifact verification, required and can only be used when flag \"--oci-layout\" is set")
 	command.MarkFlagsRequiredTogether("oci-layout", "scope")

internal/cmd/flags.go

@@ -93,6 +93,17 @@ var (
 		fs.StringArrayVarP(p, PflagUserMetadata.Name, PflagUserMetadata.Shorthand, nil, usage)
 	}
 
+	PflagReferrersAPI = &pflag.Flag{
+		Name: "allow-referrers-api",
+	}
+	PflagReferrersAPISignUsage    = "[Experimental] use the Referrers API to store signatures in the registry, if not supported (returns 404), fallback to the Referrers tag schema"
+	PflagReferrersAPIVerifyUsage  = "[Experimental] use the Referrers API to verify signatures, if not supported (returns 404), fallback to the Referrers tag schema"
+	PflagReferrersAPIListUsage    = "[Experimental] use the Referrers API to list signatures, if not supported (returns 404), fallback to the Referrers tag schema"
+	PflagReferrersAPIInspectUsage = "[Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema"
+	SetPflagReferrersAPI          = func(fs *pflag.FlagSet, p *bool, usage string) {
+		fs.BoolVar(p, PflagReferrersAPI.Name, false, usage)
+	}
+
 	PflagOutput = &pflag.Flag{
 		Name:      "output",
 		Shorthand: "o",

specs/commandline/inspect.md

@@ -33,7 +33,7 @@ Usage:
     notation inspect [flags] <reference>
 
 Flags:
-      --allow-referrers-api   [Experimental] use the Referrers API to inspect signatures, if not supported, fallback to the Referrers tag schema
+      --allow-referrers-api   [Experimental] use the Referrers API to inspect signatures, if not supported (returns 404), fallback to the Referrers tag schema
   -d, --debug                 debug mode
   -h, --help                  help for inspect
   -o, --output string         output format, options: 'json', 'text' (default "text")

specs/commandline/list.md

@@ -27,7 +27,7 @@ Aliases:
   list, ls
 
 Flags:
-      --allow-referrers-api   [Experimental] use the Referrers API to list signatures, if not supported, fallback to the Referrers tag schema
+      --allow-referrers-api   [Experimental] use the Referrers API to list signatures, if not supported (returns 404), fallback to the Referrers tag schema
   -d, --debug                 debug mode
   -h, --help                  help for list
       --oci-layout            [Experimental] list signatures stored in OCI image layout

specs/commandline/sign.md

@@ -28,7 +28,7 @@ Usage:
   notation sign [flags] <reference>
 
 Flags:
-       --allow-referrers-api        [Experimental] use the Referrers API to store signatures in the registry, if not supported, fallback to the Referrers tag schema
+       --allow-referrers-api        [Experimental] use the Referrers API to store signatures in the registry, if not supported (returns 404), fallback to the Referrers tag schema
   -d,  --debug                      debug mode
   -e,  --expiry duration            optional expiry that provides a "best by use" time for the artifact. The duration is specified in minutes(m) and/or hours(h). For example: 12h, 30m, 3h20m
   -h,  --help                       help for sign

specs/commandline/verify.md

@@ -35,7 +35,7 @@ Usage:
   notation verify [flags] <reference>
 
 Flags:
-       --allow-referrers-api         [Experimental] use the Referrers API to verify signatures, if not supported, fallback to the Referrers tag schema
+       --allow-referrers-api         [Experimental] use the Referrers API to verify signatures, if not supported (returns 404), fallback to the Referrers tag schema
   -d,  --debug                       debug mode
   -h,  --help                        help for verify
        --oci-layout                  [Experimental] verify the artifact stored as OCI image layout

test/e2e/suite/trustpolicy/registry_scope.go

@@ -16,7 +16,7 @@ var _ = Describe("notation trust policy registryScope test", func() {
 			vhost.SetOption(AddTrustPolicyOption("empty_registry_scope_trustpolicy.json"))
 
 			// test localhost:5000/test-repo
-			notation.Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
+			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
 			notation.ExpectFailure().Exec("verify", artifact.ReferenceWithDigest()).
 				MatchErrKeyWords("trust policy statement \"e2e\" has zero registry scopes")
 		})
@@ -27,7 +27,7 @@ var _ = Describe("notation trust policy registryScope test", func() {
 			// update trustpolicy.json
 			vhost.SetOption(AddTrustPolicyOption("malformed_registry_scope_trustpolicy.json"))
 
-			notation.Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
+			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
 			notation.ExpectFailure().Exec("verify", artifact.ReferenceWithDigest()).
 				MatchErrKeyWords(`registry scope "localhost:5000\\test-repo" is not valid, make sure it is a fully qualified registry URL without the scheme/protocol, e.g domain.com/my/repository OR a local trust policy scope, e.g local/myOCILayout`)
 		})
@@ -93,7 +93,7 @@ var _ = Describe("notation trust policy registryScope test", func() {
 			artifact := GenerateArtifact("", "test-repo6")
 
 			// test localhost:5000/test-repo
-			notation.Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
+			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
 			notation.ExpectFailure().Exec("verify", artifact.ReferenceWithDigest()).
 				MatchErrKeyWords("registry scope \"localhost:5000/test-repo6\" is present in multiple trust policy statements")
 		})
@@ -107,7 +107,7 @@ var _ = Describe("notation trust policy registryScope test", func() {
 			artifact := GenerateArtifact("", "test-repo7")
 
 			// test localhost:5000/test-repo
-			notation.Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
+			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
 			notation.ExpectFailure().Exec("verify", artifact.ReferenceWithDigest()).
 				MatchErrKeyWords("trust policy statement \"e2e\" uses wildcard registry scope '*', a wildcard scope cannot be used in conjunction with other scope values")
 		})
@@ -119,7 +119,7 @@ var _ = Describe("notation trust policy registryScope test", func() {
 			vhost.SetOption(AddTrustPolicyOption("invalid_registry_scope_trustpolicy.json"))
 
 			// test localhost:5000/test-repo
-			notation.Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
+			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).MatchKeyWords(SignSuccessfully)
 			notation.ExpectFailure().Exec("verify", artifact.ReferenceWithDigest()).
 				MatchErrContent(fmt.Sprintf("Error: signature verification failed: artifact %q has no applicable trust policy\n", artifact.ReferenceWithDigest()))
 		})