capability support

basculehttp/capabilities.go

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: 2024 Comcast Cable Communications Management, LLC
+// SPDX-License-Identifier: Apache-2.0
+
+package basculehttp
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"regexp"
+	"strings"
+
+	"github.com/xmidt-org/bascule"
+	"go.uber.org/multierr"
+)
+
+const (
+	// DefaultAllMethod is one of the default method strings that will match any HTTP method.
+	DefaultAllMethod = "all"
+
+	// DefaultWildcardMethod is one of the default method strings that will match any HTTP method.
+	DefaultWildcardMethod = "*"
+)
+
+var (
+	// ErrMissingCapabilities indicates that a token had no capabilities
+	// and thus is unauthorized.
+	ErrMissingCapabilities = errors.New("no capabilities in token")
+)
+
+// urlPathNormalization ensures that the given URL has a leading slash.
+func urlPathNormalization(url string) string {
+	if url[0] == '/' {
+		return url
+	}
+
+	return "/" + url
+}
+
+// CapabilityUnauthorizedError indicates that a given capability was
+// rejected and the token is unauthorized.
+type CapabilityUnauthorizedError struct {
+	// Match is the match string in <prefix><url pattern>:<method> format
+	// that matched the capability but did not match the resource request.
+	Match string
+
+	// Capability is the capability string from the token that was rejected.
+	Capability string
+
+	// Err is any error that occurred.  This will be returned from Unwrap.
+	Err error
+}
+
+func (cue *CapabilityUnauthorizedError) Unwrap() error {
+	return cue.Err
+}
+
+func (cue *CapabilityUnauthorizedError) StatusCode() int {
+	return http.StatusForbidden
+}
+
+func (cue *CapabilityUnauthorizedError) Error() string {
+	var o strings.Builder
+	o.WriteString(`Capability [`)
+	o.WriteString(cue.Capability)
+	o.WriteString(`] was rejected due to [`)
+	o.WriteString(cue.Match)
+	o.WriteRune(']')
+
+	if cue.Err != nil {
+		o.WriteString(`: `)
+		o.WriteString(cue.Err.Error())
+	}
+
+	return o.String()
+}
+
+// CapabilityApproverOption is a configurable option used to create a CapabilityApprover.
+type CapabilityApproverOption interface {
+	apply(*CapabilityApprover) error
+}
+
+type capabilityApproverOptionFunc func(*CapabilityApprover) error
+
+func (caof capabilityApproverOptionFunc) apply(ca *CapabilityApprover) error { return caof(ca) }
+
+// WithCapabilityPrefixes adds several prefixes used to match capabilities, e.g. x1:webpa:foo:.  Only
+// the first prefix found during matching is considered for authorization.  If no prefixes
+// are set via this option, the resulting approver will not authorize any requests.
+//
+// Note that a prefix can itself be a regular expression, but may not have any subexpressions.
+func WithCapabilityPrefixes(prefixes ...string) CapabilityApproverOption {
+	return capabilityApproverOptionFunc(func(ca *CapabilityApprover) error {
+		for _, p := range prefixes {
+			re, err := regexp.Compile("^" + p + "(.+):(.+?)$")
+			switch {
+			case err != nil:
+				return fmt.Errorf("Unable to compile capability prefix [%s]: %s", p, err)
+
+			case re.NumSubexp() != 2:
+				return fmt.Errorf("The prefix [%s] cannot have subexpressions", p)
+
+			default:
+				ca.matchers = append(ca.matchers, re)
+			}
+		}
+
+		return nil
+	})
+}
+
+// WithCapabilityAllMethods changes the values used to signal a match of all HTTP methods.
+// By default, both DefaultAllMethod and DefaultWildcardMethod, if present in a capability,
+// will match any HTTP method.  This option overwrites the default, and is cumulative.
+// However, a caller can add values to the default by using
+// WithCapabilityAllMethods(DefaultAllMethod, DefaultWildcardMethod, "myvalue", ...).
+func WithCapabilityAllMethods(v ...string) CapabilityApproverOption {
+	return capabilityApproverOptionFunc(func(ca *CapabilityApprover) error {
+		if ca.allMethods == nil {
+			ca.allMethods = make(map[string]bool, len(v))
+		}
+
+		for _, matchAll := range v {
+			ca.allMethods[matchAll] = true
+		}
+
+		return nil
+	})
+}
+
+// CapabilityApprover is a bascule HTTP approver that authorizes tokens
+// with capabilities against requests.
+//
+// This approver expects capabilities in tokens to be of the form <prefix><endpoing regex>:<method>.
+//
+// The allowed prefixes must be set via one or more WithCapabilityPrefixes options.  Prefixes
+// may themselves contain colon delimiters and can be regular expressions without subexpressions.
+type CapabilityApprover struct {
+	matchers   []*regexp.Regexp
+	allMethods map[string]bool
+}
+
+// NewCapabilityApprover creates a CapabilityApprover using the supplied options.
+// At least (1) of the configured prefixes must match an HTTP request's URL in
+// ordered for a token to be authorized.
+//
+// If no prefixes are added via WithCapabilityPrefix, then the returned approver
+// will not authorize any requests.
+func NewCapabilityApprover(opts ...CapabilityApproverOption) (ca *CapabilityApprover, err error) {
+	ca = new(CapabilityApprover)
+	for _, o := range opts {
+		err = multierr.Append(err, o.apply(ca))
+	}
+
+	switch {
+	case err != nil:
+		ca = nil
+
+	default:
+		if len(ca.allMethods) == 0 {
+			// enforce the defaults
+			ca.allMethods = map[string]bool{
+				DefaultAllMethod:      true,
+				DefaultWildcardMethod: true,
+			}
+		}
+	}
+
+	return
+}
+
+// Approve attempts to match each capability to a configured prefix. Then, for any matched prefix,
+// the URL regexp and method in the capability must match the resource.  URLs are normalized
+// with a leading '/'.
+//
+// This method returns success (i.e. a nil error) when the first matching capability is found.
+func (ca *CapabilityApprover) Approve(_ context.Context, resource *http.Request, token bascule.Token) error {
+	capabilities, ok := bascule.GetCapabilities(token)
+	if len(capabilities) == 0 || !ok {
+		return ErrMissingCapabilities
+	}
+
+	for _, matcher := range ca.matchers {
+		for _, capability := range capabilities {
+			substrings := matcher.FindStringSubmatch(capability)
+			if len(substrings) < 2 {
+				// no match
+				continue
+			}
+
+			// the format of capabilities is <prefix><url pattern>:<method>
+			// <url pattern> and <method> will be substrings
+			err := ca.approveURL(resource, substrings[1])
+			if err == nil {
+				err = ca.approveMethod(resource, substrings[2])
+			}
+
+			if err != nil {
+				err = &CapabilityUnauthorizedError{
+					Match:      matcher.String(),
+					Capability: capability,
+					Err:        err,
+				}
+			}
+
+			// stop at the first match, regardless of result
+			return err
+		}
+	}
+
+	// none of the matchers matched any capability, OR there were no matchers configured
+	return bascule.ErrUnauthorized
+}
+
+func (ca *CapabilityApprover) approveMethod(resource *http.Request, capabilityMethod string) error {
+	switch {
+	case ca.allMethods[capabilityMethod]:
+		return nil
+
+	case capabilityMethod == strings.ToLower(resource.Method):
+		return nil
+
+	default:
+		return fmt.Errorf("method does not match request method [%s]", resource.Method)
+	}
+}
+
+func (ca *CapabilityApprover) approveURL(resource *http.Request, capabilityURL string) error {
+	resourcePath := resource.URL.EscapedPath()
+
+	re, err := regexp.Compile(urlPathNormalization(capabilityURL))
+	if err != nil {
+		return err
+	}
+
+	indices := re.FindStringIndex(urlPathNormalization(resourcePath))
+	if len(indices) < 1 || indices[0] != 0 {
+		return fmt.Errorf("url does not match request URL [%s]", resourcePath)
+	}
+
+	return nil
+}

basculehttp/error.go

@@ -17,17 +17,23 @@ import (
 type ErrorStatusCoder func(request *http.Request, err error) int
 
 // DefaultErrorStatusCoder is the strategy used when no ErrorStatusCoder is supplied.
+// The following tests are done in order:
 //
-// If err has bascule.ErrMissingCredentials in its chain, this function returns
+// (1) First, if err is nil, this method returns 0.
+//
+// (2) If any error in the chain provides a 'StatusCode() int' method, the result
+// from that method is returned.
+//
+// (3) If err has bascule.ErrMissingCredentials in its chain, this function returns
 // http.StatusUnauthorized.
 //
-// If err has bascule.ErrInvalidCredentials in its chain, this function returns
-// http.StatusBadRequest.
+// (4) If err has bascule.ErrUnauthorized in its chain, this function returns
+// http.StatusForbidden.
 //
-// Failing the previous two checks, if the error provides a StatusCode() method,
-// the return value from that method is used.
+// (5) If err has bascule.ErrInvalidCredentials in its chain, this function returns
+// http.StatusBadRequest.
 //
-// Otherwise, this method returns 0 to indicate that it doesn't know how to
+// (6) Otherwise, this method returns 0 to indicate that it doesn't know how to
 // produce a status code from the error.
 func DefaultErrorStatusCoder(_ *http.Request, err error) int {
 	type statusCoder interface {
@@ -37,19 +43,24 @@ func DefaultErrorStatusCoder(_ *http.Request, err error) int {
 	var sc statusCoder
 
 	switch {
-	// check if it's a status coder first, so that we can
-	// override status codes for built-in errors.
+	case err == nil:
+		return 0
+
 	case errors.As(err, &sc):
 		return sc.StatusCode()
 
 	case errors.Is(err, bascule.ErrMissingCredentials):
 		return http.StatusUnauthorized
 
+	case errors.Is(err, bascule.ErrUnauthorized):
+		return http.StatusForbidden
+
 	case errors.Is(err, bascule.ErrInvalidCredentials):
 		return http.StatusBadRequest
-	}
 
-	return 0
+	default:
+		return 0
+	}
 }
 
 // ErrorMarshaler is a strategy for marshaling an error's contents, particularly to

basculehttp/error_test.go

@@ -18,13 +18,26 @@ type ErrorTestSuite struct {
 }
 
 func (suite *ErrorTestSuite) TestDefaultErrorStatusCoder() {
+	suite.Run("Nil", func() {
+		suite.Zero(
+			DefaultErrorStatusCoder(nil, nil),
+		)
+	})
+
 	suite.Run("ErrMissingCredentials", func() {
 		suite.Equal(
 			http.StatusUnauthorized,
 			DefaultErrorStatusCoder(nil, bascule.ErrMissingCredentials),
 		)
 	})
 
+	suite.Run("ErrUnauthorized", func() {
+		suite.Equal(
+			http.StatusForbidden,
+			DefaultErrorStatusCoder(nil, bascule.ErrUnauthorized),
+		)
+	})
+
 	suite.Run("ErrInvalidCredentials", func() {
 		suite.Equal(
 			http.StatusBadRequest,
@@ -53,8 +66,7 @@ func (suite *ErrorTestSuite) TestDefaultErrorStatusCoder() {
 	})
 
 	suite.Run("Unrecognized", func() {
-		suite.Equal(
-			0,
+		suite.Zero(
 			DefaultErrorStatusCoder(nil, errors.New("unrecognized error")),
 		)
 	})