Add some validity testing for AccessBoundaryRules and add documentation.

google/downscope/downscoping.go

@@ -1,4 +1,9 @@
-package downscoped
+/*
+Package downscope implements the ability to downwcope, or restrict, the
+Identity and AccessManagement permissions that a short-lived Token
+can use.  Please note that only Google Cloud Storage supports this feature.
+ */
+package downscope
 
 import (
 	"context"
@@ -16,19 +21,40 @@ const (
 
 // Defines an upper bound of permissions available for a GCP credential for one or more resources
 type AccessBoundary struct {
-	// One or more AccessBoundaryRules are required to define permissions for the new downscoped token
+	// One or more AccessBoundaryRules are required to define permissions
+	// for the new downscoped token.  Each one defines an access (or set of accesses)
+	// that the new token has to a given resource.
 	AccessBoundaryRules []AccessBoundaryRule `json:"accessBoundaryRules"`
 }
 
+// An AvailabilityCondition restricts access to a given Resource.
 type AvailabilityCondition struct {
-	Title       string `json:"title,omitempty"`
+	// A condition expression that specifies the Cloud Storage objects where
+	// permissions are available. For further documentation, see
+	// https://cloud.google.com/iam/docs/conditions-overview
 	Expression  string `json:"expression"`
+	// Optional. A short string that identifies the purpose of the condition.
+	Title       string `json:"title,omitempty"`
+	// Optional. Details about the purpose of the condition.
 	Description string `json:"description,omitempty"`
 }
 
+// Sets the permissions (and optionally conditions) that the new
+// token has on given resource.
 type AccessBoundaryRule struct {
+	// AvailableResource is the full resource name of the Cloud Storage bucket that the rule applies to.
+	// Use the format //storage.googleapis.com/projects/_/buckets/bucket-name.
 	AvailableResource    string                 `json:"availableResource"`
+	// AvailablePermissions is a list that defines the upper bound on the available permissions
+	// for the resource.  Each value is the identifier for an IAM predefined role or custom role,
+	// with the prefix inRole:. For example: inRole:roles/storage.objectViewer.
+	// Only the permissions in these roles will be available.
 	AvailablePermissions []string               `json:"availablePermissions"`
+	// An optional Condition that restricts the availability of permissions
+	// to specific Cloud Storage objects.
+	//
+	// Use this field if you want to make permissions available for specific objects,
+	// rather than all objects in a Cloud Storage bucket.
 	Condition            *AvailabilityCondition `json:"availabilityCondition,omitempty"`
 }
 
@@ -39,17 +65,33 @@ type downscopedTokenResponse struct {
 	ExpiresIn       int    `json:"expires_in"`
 }
 
+// Specifies the information necessary to request a downscoped token.
 type DownscopingConfig struct {
+	// RootSource is the TokenSource used to create the downscoped token.
+	// The downscoped token therefore has some subset of the accesses of
+	// the original RootSource.
 	RootSource               oauth2.TokenSource
+	// CredentialAccessBoundary defines the accesses held by the new
+	// downscoped Token.
 	CredentialAccessBoundary AccessBoundary
 }
 
+// downscopedTokenWithEndpoint is a helper function used for unit testing
+// purposes, as it allows us to pass in a locally mocked endpoint.
 func downscopedTokenWithEndpoint(ctx context.Context, config DownscopingConfig, endpoint string) (oauth2.TokenSource, error) {
 	if config.RootSource == nil {
-		return nil, fmt.Errorf("oauth2/google/downscoped: rootTokenSource cannot be nil")
+		return nil, fmt.Errorf("downscope: rootTokenSource cannot be nil")
 	}
 	if len(config.CredentialAccessBoundary.AccessBoundaryRules) == 0 {
-		return nil, fmt.Errorf("oauth2/google/downscoped: length of AccessBoundaryRules must be at least 1")
+		return nil, fmt.Errorf("downscope: length of AccessBoundaryRules must be at least 1")
+	}
+	for _, val := range config.CredentialAccessBoundary.AccessBoundaryRules {
+		if val.AvailableResource == "" {
+			return nil, fmt.Errorf("downscope: all rules must have a nonempty AvailableResource: %+v", val)
+		}
+		if len(val.AvailablePermissions) == 0 {
+			return nil, fmt.Errorf("downscope: all rules must provide at least one permission: %+v", val)
+		}
 	}
 
 	downscopedOptions := struct {
@@ -60,12 +102,12 @@ func downscopedTokenWithEndpoint(ctx context.Context, config DownscopingConfig,
 
 	tok, err := config.RootSource.Token()
 	if err != nil {
-		return nil, fmt.Errorf("oauth2/google/downscoped: unable to refresh root token %v", err)
+		return nil, fmt.Errorf("downscope: unable to obtain root token: %v", err)
 	}
 
 	b, err := json.Marshal(downscopedOptions)
 	if err != nil {
-		return nil, fmt.Errorf("oauth2/google/downscoped: Unable to marshall AccessBoundary payload %v", err)
+		return nil, fmt.Errorf("downscope: Unable to marshall AccessBoundary payload %v", err)
 	}
 
 	form := url.Values{}
@@ -88,7 +130,7 @@ func downscopedTokenWithEndpoint(ctx context.Context, config DownscopingConfig,
 		return nil, fmt.Errorf("unable to unmarshal response body: %v", err)
 	}
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("unable to exchange token %v", tresp)
+		return nil, fmt.Errorf("unable to exchange token; %v", resp.StatusCode)
 	}
 
 	// an exchanged token that is derived from a service account (2LO) has an expired_in value
@@ -110,6 +152,10 @@ func downscopedTokenWithEndpoint(ctx context.Context, config DownscopingConfig,
 	return oauth2.StaticTokenSource(newToken), nil
 }
 
-func NewDownscopedTokenSource(ctx context.Context, config DownscopingConfig) (oauth2.TokenSource, error) {
+// NewTokenSource takes a root TokenSource and returns a downscoped TokenSource
+// with a subset of the permissions held by the root source.  The
+// CredentialAccessBoundary in the config defines the permissions held
+// by the new TokenSource.
+func NewTokenSource(ctx context.Context, config DownscopingConfig) (oauth2.TokenSource, error) {
 	return downscopedTokenWithEndpoint(ctx, config, identityBindingEndpoint)
 }

google/downscope/downscoping_test.go

@@ -1,4 +1,4 @@
-package downscoped
+package downscope
 
 import (
 	"context"