Add resolved source info in ResolutionRequest status

Related to
- #5529
- #5397

Before:
The `ResolutionRequestStatusFields` only has the `Data` that is a string
representation of the resolved content.

Now:
A new field called `Source` is now introduced to the `ResolutionRequestStatusFields`
to record the source information of the remote data in a structured way
using the standard SLSA ConfigSource struct.

Why?
Recently there is a clear requirement that the remote source
information of the remote data should be recorded in the provenance to
link back to its origin including the resolved the commit sha when users
only provide the branch/tag name for the resolver. Without this PR, the
only way to achieve this is to pass the resolved source information through
annotations, which has a couple of the drawbacks i.e. unstructured data,
hard to maintain and to make changes in future etc. That's where this PR
comes in to solve the problem.

Signed-off-by: Chuang Wang <[email protected]>

docs/how-to-write-a-resolver.md

@@ -191,6 +191,7 @@ import (
 
   "github.com/tektoncd/pipeline/pkg/resolution/resolver/framework"
   "knative.dev/pkg/injection/sharedmain"
+  "github.com/tektoncd/pipeline/pkg/apis/resolution/v1alpha1"
 )
 ```
 
@@ -259,6 +260,31 @@ func (*myResolvedResource) Data() []byte {
 func (*myResolvedResource) Annotations() map[string]string {
   return nil
 }
+
+// Source is the source reference of the remote data that records where the remote 
+// file came from including the url, digest and the entrypoint. None atm.
+func (*myResolvedResource) Source() *v1alpha1.ConfigSource {
+	return nil
+}
+```
+
+Best practice: In order to enable Tekton Chains to record the source 
+information of the remote data in the SLSA provenance, the resolver should 
+implement the `Source()` method to return a correct ConfigSource value. See the 
+following example.
+
+```go
+// Source is the source reference of the remote data that records where the remote 
+// file came from including the url, digest and the entrypoint.
+func (*myResolvedResource) Source() *v1alpha1.ConfigSource {
+	return &v1alpha1.ConfigSource{
+		URI: "https://github.com/user/example",
+		Digest: map[string]string{
+			"sha1": "example",
+		},
+		EntryPoint: "foo/bar/task.yaml",
+	}
+}
 ```
 
 ## The deployment configuration

docs/resolver-template/cmd/demoresolver/main.go

@@ -91,3 +91,9 @@ func (*myResolvedResource) Data() []byte {
 func (*myResolvedResource) Annotations() map[string]string {
 	return nil
 }
+
+// Source is the source reference of the remote data that records where the remote
+// file came from including the url, digest and the entrypoint. None atm.
+func (*myResolvedResource) Source() *v1alpha1.ConfigSource {
+	return nil
+}

pkg/apis/pipeline/v1beta1/swagger.json

@@ -140,6 +140,28 @@
         }
       }
     },
+    "v1alpha1.ConfigSource": {
+      "description": "ConfigSource records where the task/pipeline file came from.",
+      "type": "object",
+      "properties": {
+        "digest": {
+          "description": "Digest is a collection of cryptographic digests for the contents of the artifact specified by URI. https://github.com/in-toto/attestation/blob/main/spec/field_types.md#DigestSet Example: {\"sha1\": \"f99d13e554ffcb696dee719fa85b695cb5b0f428\"}",
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "default": ""
+          }
+        },
+        "entryPoint": {
+          "description": "EntryPoint identifying the entry point into the build. This is often a path to a configuration file and/or a target label within that file. Example: \"task/git-clone/0.8/git-clone.yaml\"",
+          "type": "string"
+        },
+        "uri": {
+          "description": "URI indicating the identity of the source of the config. https://github.com/in-toto/attestation/blob/main/spec/field_types.md#ResourceURI Example: https://github.com/tektoncd/catalog",
+          "type": "string"
+        }
+      }
+    },
     "v1alpha1.PipelineResource": {
       "description": "PipelineResource describes a resource that is an input to or output from a Task.",
       "type": "object",
@@ -308,7 +330,8 @@
       "description": "ResolutionRequestStatus are all the fields in a ResolutionRequest's status subresource.",
       "type": "object",
       "required": [
-        "data"
+        "data",
+        "source"
       ],
       "properties": {
         "annotations": {
@@ -338,20 +361,29 @@
           "description": "ObservedGeneration is the 'Generation' of the Service that was last processed by the controller.",
           "type": "integer",
           "format": "int64"
+        },
+        "source": {
+          "description": "Source is the source reference of the remote data that records where the remote file came from including the url, digest and the entrypoint.",
+          "$ref": "#/definitions/v1alpha1.ConfigSource"
         }
       }
     },
     "v1alpha1.ResolutionRequestStatusFields": {
       "description": "ResolutionRequestStatusFields are the ResolutionRequest-specific fields for the status subresource.",
       "type": "object",
       "required": [
-        "data"
+        "data",
+        "source"
       ],
       "properties": {
         "data": {
           "description": "Data is a string representation of the resolved content of the requested resource in-lined into the ResolutionRequest object.",
           "type": "string",
           "default": ""
+        },
+        "source": {
+          "description": "Source is the source reference of the remote data that records where the remote file came from including the url, digest and the entrypoint.",
+          "$ref": "#/definitions/v1alpha1.ConfigSource"
         }
       }
     },

pkg/apis/resolution/v1alpha1/resolution_request_types.go

@@ -78,9 +78,30 @@ type ResolutionRequestStatusFields struct {
 	// of the requested resource in-lined into the ResolutionRequest
 	// object.
 	Data string `json:"data"`
+	// Source is the source reference of the remote data that records where the remote
+	// file came from including the url, digest and the entrypoint.
+	Source *ConfigSource `json:"source"`
 }
 
 // GetStatus implements KRShaped.
 func (rr *ResolutionRequest) GetStatus() *duckv1.Status {
 	return &rr.Status.Status
 }
+
+// ConfigSource records where the task/pipeline file came from.
+type ConfigSource struct {
+	// URI indicating the identity of the source of the config.
+	// https://github.com/in-toto/attestation/blob/main/spec/field_types.md#ResourceURI
+	// Example: https://github.com/tektoncd/catalog
+	URI string `json:"uri,omitempty"`
+
+	// Digest is a collection of cryptographic digests for the contents of the artifact specified by URI.
+	// https://github.com/in-toto/attestation/blob/main/spec/field_types.md#DigestSet
+	// Example: {"sha1": "f99d13e554ffcb696dee719fa85b695cb5b0f428"}
+	Digest map[string]string `json:"digest,omitempty"`
+
+	// EntryPoint identifying the entry point into the build. This is often a path to a
+	// configuration file and/or a target label within that file.
+	// Example: "task/git-clone/0.8/git-clone.yaml"
+	EntryPoint string `json:"entryPoint,omitempty"`
+}

pkg/apis/resolution/v1beta1/resolution_request_types.go

@@ -79,9 +79,30 @@ type ResolutionRequestStatusFields struct {
 	// of the requested resource in-lined into the ResolutionRequest
 	// object.
 	Data string `json:"data"`
+	// Source is the source reference of the remote data that records the url, digest
+	// and the entrypoint.
+	Source *ConfigSource `json:"source"`
 }
 
 // GetStatus implements KRShaped.
 func (rr *ResolutionRequest) GetStatus() *duckv1.Status {
 	return &rr.Status.Status
 }
+
+// ConfigSource records where the task/pipeline file came from.
+type ConfigSource struct {
+	// URI indicating the identity of the source of the config.
+	// https://github.com/in-toto/attestation/blob/main/spec/field_types.md#ResourceURI
+	// Example: https://github.com/tektoncd/catalog
+	URI string `json:"uri,omitempty"`
+
+	// Digest is a collection of cryptographic digests for the contents of the artifact specified by URI.
+	// https://github.com/in-toto/attestation/blob/main/spec/field_types.md#DigestSet
+	// Example: {"sha1": "f99d13e554ffcb696dee719fa85b695cb5b0f428"}
+	Digest map[string]string `json:"digest,omitempty"`
+
+	// EntryPoint identifying the entry point into the build. This is often a path to a
+	// configuration file and/or a target label within that file.
+	// Example: "task/git-clone/0.8/git-clone.yaml"
+	EntryPoint string `json:"entryPoint,omitempty"`
+}