Add RFC 6750 WWW-Authenticate on OAuth bearer APIs

Introduce BearerChallengeMiddleware on MCP, Console and Connect GraphQL, Files, and OAuth2 userinfo. Call sites record challenge intent in context via NoteUnauthenticated, NoteInvalidToken, and NoteInsufficientScope; the middleware applies resource_metadata, invalid_token, and insufficient_scope on WriteHeader.

OAuth2 access token middleware flags rejected Bearer tokens for invalid_token challenges. Add Authorizer.ScopesForAction for the scope auth-param.

Signed-off-by: Ludovic Vielle <ludovic@probo.com>

pkg/bearertoken/bearer_challenge.go

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package bearertoken
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+
+	"go.probo.inc/probo/pkg/baseurl"
+	"go.probo.inc/probo/pkg/coredata"
+)
+
+const (
+	BearerErrInvalidToken      = "invalid_token"
+	BearerErrInsufficientScope = "insufficient_scope"
+)
+
+func protectedResourceMetadataURL(baseURL *baseurl.BaseURL) string {
+	return baseURL.WithPath("/.well-known/oauth-protected-resource").MustString()
+}
+
+// BearerChallenge builds the WWW-Authenticate header value per RFC 6750 and RFC 9728.
+// Pass errorCode == "" for discovery-only (401, no Bearer attempt).
+// Pass scopes only when errorCode == BearerErrInsufficientScope.
+func BearerChallenge(
+	baseURL *baseurl.BaseURL,
+	errorCode string,
+	scopes ...coredata.OAuth2Scope,
+) string {
+	metadataURL := protectedResourceMetadataURL(baseURL)
+
+	var parts []string
+
+	if errorCode != "" {
+		parts = append(parts, fmt.Sprintf(`error="%s"`, errorCode))
+	}
+
+	if errorCode == BearerErrInsufficientScope && len(scopes) > 0 {
+		scopeValues := make([]string, len(scopes))
+		for i, scope := range scopes {
+			scopeValues[i] = string(scope)
+		}
+
+		parts = append(parts, fmt.Sprintf(`scope="%s"`, strings.Join(scopeValues, " ")))
+	}
+
+	parts = append(parts, fmt.Sprintf(`resource_metadata="%s"`, metadataURL))
+
+	return "Bearer " + strings.Join(parts, ", ")
+}
+
+func SetBearerChallenge(
+	w http.ResponseWriter,
+	baseURL *baseurl.BaseURL,
+	errorCode string,
+	scopes ...coredata.OAuth2Scope,
+) {
+	w.Header().Set("WWW-Authenticate", BearerChallenge(baseURL, errorCode, scopes...))
+}
+
+// SetBearerUnauthenticated sets a discovery-only challenge (RFC 9728 resource_metadata).
+func SetBearerUnauthenticated(w http.ResponseWriter, baseURL *baseurl.BaseURL) {
+	SetBearerChallenge(w, baseURL, "")
+}
+
+func SetBearerInvalidToken(w http.ResponseWriter, baseURL *baseurl.BaseURL) {
+	SetBearerChallenge(w, baseURL, BearerErrInvalidToken)
+}
+
+func SetBearerInsufficientScope(
+	w http.ResponseWriter,
+	baseURL *baseurl.BaseURL,
+	scopes ...coredata.OAuth2Scope,
+) {
+	SetBearerChallenge(w, baseURL, BearerErrInsufficientScope, scopes...)
+}

pkg/bearertoken/bearer_challenge_test.go

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package bearertoken
+
+import (
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"go.probo.inc/probo/pkg/baseurl"
+	"go.probo.inc/probo/pkg/coredata"
+)
+
+func TestBearerChallenge(t *testing.T) {
+	t.Parallel()
+
+	baseURL := baseurl.MustParse("https://example.com")
+
+	tests := []struct {
+		name      string
+		errorCode string
+		scopes    []coredata.OAuth2Scope
+		want      string
+	}{
+		{
+			name:      "discovery",
+			errorCode: "",
+			want:      `Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"`,
+		},
+		{
+			name:      "invalid token",
+			errorCode: BearerErrInvalidToken,
+			want:      `Bearer error="invalid_token", resource_metadata="https://example.com/.well-known/oauth-protected-resource"`,
+		},
+		{
+			name:      "insufficient scope",
+			errorCode: BearerErrInsufficientScope,
+			scopes:    []coredata.OAuth2Scope{"v1:org:read", "v1:privacy"},
+			want:      `Bearer error="insufficient_scope", scope="v1:org:read v1:privacy", resource_metadata="https://example.com/.well-known/oauth-protected-resource"`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := BearerChallenge(baseURL, tt.errorCode, tt.scopes...)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestSetBearerChallenge(t *testing.T) {
+	t.Parallel()
+
+	baseURL := baseurl.MustParse("https://example.com")
+	rec := httptest.NewRecorder()
+
+	SetBearerInvalidToken(rec, baseURL)
+
+	assert.Equal(
+		t,
+		`Bearer error="invalid_token", resource_metadata="https://example.com/.well-known/oauth-protected-resource"`,
+		rec.Header().Get("WWW-Authenticate"),
+	)
+}
+
+func TestIsAttempt(t *testing.T) {
+	t.Parallel()
+
+	assert.True(t, IsAttempt("Bearer token"))
+	assert.True(t, IsAttempt("bearer token"))
+	assert.True(t, IsAttempt("BEARER"))
+	assert.False(t, IsAttempt(""))
+	assert.False(t, IsAttempt("Basic dXNlcjpwYXNz"))
+	assert.False(t, IsAttempt("Bear token"))
+}

pkg/bearertoken/bearertoken.go

@@ -12,7 +12,8 @@
 // OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 // PERFORMANCE OF THIS SOFTWARE.
 
-// Package bearertoken parses Bearer tokens according to RFC 6750.
+// Package bearertoken parses Bearer tokens and builds Bearer WWW-Authenticate
+// challenges according to RFC 6750.
 //
 // The grammar is defined as:
 //
@@ -69,6 +70,15 @@ func Parse(credentials string) (string, error) {
 	return token, nil
 }
 
+// IsAttempt reports whether credentials use the Bearer scheme.
+func IsAttempt(credentials string) bool {
+	if len(credentials) < len(scheme) {
+		return false
+	}
+
+	return strings.EqualFold(credentials[:len(scheme)], scheme)
+}
+
 // isValidToken checks if the given string is a valid b64token.
 // A valid b64token consists of 1 or more characters from the set
 // [A-Za-z0-9-._~+/] followed by zero or more '=' characters.