Modify openapi & middleware to allow for optional auth

Typically, you would set the security section to the following
to signal that endpoint can optionally take bearerAuth:

```
      security:
        - bearerAuth: []
        - {}
```

But the current Go openapi library does not let us know that {} has been set.

As a result, this change sets a new security called `noAuth`. Now with
this new security parameter, it lets the server know that:
1. If the authorization header is provided, try to authenticate like normal, or
2. If the authorization header is not set and this new noAuth option is a possibility
   for the route, treat it like an unauthenticated request that should proceed.

The GCIP middleware has been modified to fit that logic.

This is needed for the get_saved_search endpoint.

Other changes:
- Have the getSavedSearch endpoint use the new noAuth config
- Fix other openapi lint errors.

Author: jcscottiii

backend/cmd/server/main.go

@@ -136,7 +136,11 @@ func main() {
 	}
 
 	authMiddleware := httpmiddlewares.NewBearerTokenAuthenticationMiddleware(
-		auth.NewGCIPAuthenticator(firebaseAuthClient), backend.BearerAuthScopes, httpserver.GenericErrorFn)
+		auth.NewGCIPAuthenticator(firebaseAuthClient),
+		backend.BearerAuthScopes,
+		backend.NoAuthScopes,
+		httpserver.GenericErrorFn,
+	)
 
 	preRequestMiddlewares := []func(http.Handler) http.Handler{
 		cors.Handler(

lib/httpmiddlewares/bearertokenauth.go

@@ -35,31 +35,42 @@ type BearerTokenAuthenticator interface {
 }
 
 // NewBearerTokenAuthenticationMiddleware returns a middleware that can be used to authenticate requests.
-// It detects if a route requires authentication by checking if a field is set in the request context.
-// If the field is set, the middleware verifies the Authorization header and sets the authenticated user in the context.
+// It detects if a route requires authentication by checking if a field (authCtxKey) is set in the request context.
+// If the authCtxKey field is set and the Authorization header is present, the middleware authenticates the user and
+// sets the authenticated user in the context. If both authCtxKey and optionalAuthCtxKey fields are set and the
+// Authorization header is not present, it allows the request to proceed without authentication.
 //
 // The errorFn parameter allows the caller to customize the error response returned when authentication fails.
 // This makes the middleware more generic and adaptable to different error handling requirements.
 //
-// It is the responsibility of the caller of this middleware to ensure that the `ctxKey` is set in the request context
-// whenever authentication is needed. This can be done using a wrapper middleware that knows about the OpenAPI
+// It is the responsibility of the caller of this middleware to ensure that the `authCtxKey` is set in the request
+// context whenever authentication is needed. This can be done using a wrapper middleware that knows about the OpenAPI
 // generator's security semantics.
 //
 // See https://github.com/oapi-codegen/oapi-codegen/issues/518 for details on the lack of per-endpoint middleware
 // support.
-func NewBearerTokenAuthenticationMiddleware(authenticator BearerTokenAuthenticator, ctxKey any,
+func NewBearerTokenAuthenticationMiddleware(authenticator BearerTokenAuthenticator,
+	authCtxKey any, optionalAuthCtxKey any,
 	errorFn func(context.Context, int, http.ResponseWriter, error)) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			value := r.Context().Value(ctxKey)
+			value := r.Context().Value(authCtxKey)
 			if value == nil {
 				// The route does not have any security requirements set for it.
 				next.ServeHTTP(w, r)
 
 				return
 			}
+			optionalAuthValue := r.Context().Value(optionalAuthCtxKey)
 			authHdr := r.Header.Get("Authorization")
 			// Check for the Authorization header.
+			if authHdr == "" && optionalAuthValue != nil {
+				// optionalAuthCtxKey is set and no Authorization header, proceed without authentication.
+				next.ServeHTTP(w, r)
+
+				return
+			}
+
 			if authHdr == "" {
 				errorFn(r.Context(), http.StatusUnauthorized, w, ErrMissingAuthHeader)
 

lib/httpmiddlewares/bearertokenauth_test.go

@@ -27,11 +27,14 @@ import (
 
 type authCtxKey struct{}
 
+type optionalAuthCtxKey struct{}
+
 func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 	const testID = "id"
 	tests := []struct {
 		name               string
-		ctxKey             any
+		authCtxKey         any
+		optionalAuthCtxKey any
 		authHeader         string
 		mockAuthenticator  func(ctx context.Context, token string) (*auth.User, error)
 		mockErrorFn        func(context.Context, int, http.ResponseWriter, error)
@@ -40,9 +43,10 @@ func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 		expectedUser       *auth.User
 	}{
 		{
-			name:       "No security requirements",
-			ctxKey:     nil,
-			authHeader: "",
+			name:               "No security requirements",
+			authCtxKey:         nil,
+			optionalAuthCtxKey: nil,
+			authHeader:         "",
 			mockAuthenticator: func(_ context.Context, _ string) (*auth.User, error) {
 				t.Fatal("authenticate should not have been called")
 
@@ -57,9 +61,10 @@ func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 			expectedUser:       nil,
 		},
 		{
-			name:       "Missing Authorization header",
-			ctxKey:     authCtxKey{},
-			authHeader: "",
+			name:               "Missing Authorization header",
+			authCtxKey:         authCtxKey{},
+			authHeader:         "",
+			optionalAuthCtxKey: nil,
 			mockAuthenticator: func(_ context.Context, _ string) (*auth.User, error) {
 				t.Fatal("authenticate should not have been called")
 
@@ -80,9 +85,10 @@ func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 			expectedBody:       "",
 		},
 		{
-			name:       "Invalid Authorization header",
-			ctxKey:     authCtxKey{},
-			authHeader: "Invalid Auth",
+			name:               "Invalid Authorization header",
+			authCtxKey:         authCtxKey{},
+			optionalAuthCtxKey: nil,
+			authHeader:         "Invalid Auth",
 			mockAuthenticator: func(_ context.Context, _ string) (*auth.User, error) {
 				t.Fatal("authenticate should not have been called")
 
@@ -103,9 +109,10 @@ func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 			expectedBody:       "",
 		},
 		{
-			name:       "Authentication failure",
-			ctxKey:     authCtxKey{},
-			authHeader: "Bearer my-token",
+			name:               "Authentication failure without optional auth context",
+			authCtxKey:         authCtxKey{},
+			optionalAuthCtxKey: nil,
+			authHeader:         "Bearer my-token",
 			mockAuthenticator: func(_ context.Context, _ string) (*auth.User, error) {
 				return nil, errors.New("authentication failed")
 			},
@@ -123,9 +130,49 @@ func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 			expectedBody:       "",
 		},
 		{
-			name:       "Successful authentication",
-			ctxKey:     authCtxKey{},
-			authHeader: "Bearer my-token",
+			name:               "Authentication failure with optional auth context",
+			authCtxKey:         authCtxKey{},
+			optionalAuthCtxKey: optionalAuthCtxKey{},
+			authHeader:         "Bearer my-token",
+			mockAuthenticator: func(_ context.Context, _ string) (*auth.User, error) {
+				return nil, errors.New("authentication failed")
+			},
+			mockErrorFn: func(_ context.Context, code int, w http.ResponseWriter, err error) {
+				if code != http.StatusUnauthorized {
+					t.Errorf("expected status code %d, got %d", http.StatusUnauthorized, code)
+				}
+				if err == nil || err.Error() != "authentication failed" {
+					t.Errorf("expected error 'authentication failed', got %v", err)
+				}
+				w.WriteHeader(code)
+			},
+			expectedStatusCode: http.StatusUnauthorized,
+			expectedUser:       nil,
+			expectedBody:       "",
+		},
+		{
+			name:               "Successful request with optional auth context set",
+			authCtxKey:         authCtxKey{},
+			optionalAuthCtxKey: optionalAuthCtxKey{},
+			authHeader:         "",
+			mockAuthenticator: func(_ context.Context, _ string) (*auth.User, error) {
+				t.Fatal("authenticate should not have been called")
+
+				// nolint:nilnil // WONTFIX - should not reach this.
+				return nil, nil
+			},
+			mockErrorFn: func(_ context.Context, _ int, _ http.ResponseWriter, _ error) {
+				t.Fatal("errorFn should not have been called")
+			},
+			expectedStatusCode: http.StatusOK,
+			expectedBody:       "next handler was called",
+			expectedUser:       nil,
+		},
+		{
+			name:               "Successful authentication",
+			authCtxKey:         authCtxKey{},
+			optionalAuthCtxKey: nil,
+			authHeader:         "Bearer my-token",
 			mockAuthenticator: func(_ context.Context, token string) (*auth.User, error) {
 				if token != "my-token" {
 					t.Errorf("expected token 'my-token', got %s", token)
@@ -161,19 +208,14 @@ func TestBearerTokenAuthenticationMiddleware(t *testing.T) {
 
 			middleware := NewBearerTokenAuthenticationMiddleware(
 				&mockBearerTokenAuthenticator{tc.mockAuthenticator},
-				tc.ctxKey,
+				tc.authCtxKey,
+				tc.optionalAuthCtxKey,
 				tc.mockErrorFn,
 			)
 
 			handler := middleware(nextHandler)
 
-			req := httptest.NewRequest(http.MethodGet, "/", nil)
-			if tc.authHeader != "" {
-				req.Header.Set("Authorization", tc.authHeader)
-			}
-			if tc.ctxKey != nil {
-				req = req.WithContext(context.WithValue(req.Context(), tc.ctxKey, "authCtxValue"))
-			}
+			req := createTestRequest(tc.authHeader, tc.authCtxKey, tc.optionalAuthCtxKey)
 
 			rr := httptest.NewRecorder()
 			handler.ServeHTTP(rr, req)
@@ -196,6 +238,21 @@ func (m *mockBearerTokenAuthenticator) Authenticate(ctx context.Context, token s
 	return m.authenticateFn(ctx, token)
 }
 
+func createTestRequest(authHeader string, authCtxKey any, optionalAuthCtxKey any) *http.Request {
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	if authHeader != "" {
+		req.Header.Set("Authorization", authHeader)
+	}
+	if authCtxKey != nil {
+		req = req.WithContext(context.WithValue(req.Context(), authCtxKey, "authCtxValue"))
+	}
+	if optionalAuthCtxKey != nil {
+		req = req.WithContext(context.WithValue(req.Context(), optionalAuthCtxKey, "optionalAuthCtxValue"))
+	}
+
+	return req
+}
+
 func assertStatusCode(t *testing.T, rr *httptest.ResponseRecorder, expectedCode int) {
 	t.Helper()
 	if rr.Code != expectedCode {

openapi/backend/openapi.yaml

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-openapi: '3.0.2'
+openapi: '3.0.4'
 info:
   title: webstatus.dev API
   version: 0.1.0
@@ -569,7 +569,7 @@ paths:
         - $ref: '#/components/parameters/paginationTokenParam'
         - $ref: '#/components/parameters/paginationSizeParam'
       security:
-        - bearerAuth:
+        - bearerAuth: []
       responses:
         '200':
           description: OK
@@ -613,7 +613,7 @@ paths:
       summary: Get a user's bookmark status
       operationId: getUserSavedSearchBookmark
       security:
-        - bearerAuth:
+        - bearerAuth: []
       responses:
         '200':
           description: OK
@@ -732,7 +732,7 @@ paths:
       summary: Create a saved search
       operationId: createSavedSearch
       security:
-        - bearerAuth:
+        - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -781,6 +781,11 @@ paths:
     get:
       summary: Get saved search
       operationId: getSavedSearch
+      security:
+        - bearerAuth: []
+        # User can opt out of providing a bearer token.
+        # They just won't get bookmark and role information.
+        - noAuth: []
       responses:
         '200':
           description: OK
@@ -803,7 +808,7 @@ paths:
     patch:
       operationId: updateSavedSearch
       security:
-        - bearerAuth:
+        - bearerAuth: []
       requestBody:
         required: true
         content:
@@ -844,7 +849,7 @@ paths:
     delete:
       operationId: removeSavedSearch
       security:
-        - bearerAuth:
+        - bearerAuth: []
       responses:
         '204':
           description: No Content (successful deletion)