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/iam/authorizer.go

@@ -118,7 +118,12 @@ func (a *Authorizer) checkOAuth2Scope(
 	}
 
 	if a.scopeRegistry == nil || !a.scopeRegistry.Allows(accessToken.Scopes, action) {
-		return NewInsufficientOAuth2ScopeError(principal, action)
+		var scopes []coredata.OAuth2Scope
+		if a.scopeRegistry != nil {
+			scopes = a.scopeRegistry.ScopesForAction(action)
+		}
+
+		return NewInsufficientOAuth2ScopeError(principal, scopes...)
 	}
 
 	return nil

pkg/iam/authorizer_oauth2_scope_test.go

@@ -60,7 +60,38 @@ func TestAuthorizer_checkOAuth2Scope(t *testing.T) {
 		scopeErr, ok := errors.AsType[*ErrInsufficientOAuth2Scope](err)
 		require.True(t, ok)
 		assert.Equal(t, principal, scopeErr.IdentityID)
-		assert.Equal(t, action, scopeErr.Action)
+		assert.Empty(t, scopeErr.Scopes)
+	})
+
+	t.Run("reports granting scopes when token lacks authorization", func(t *testing.T) {
+		t.Parallel()
+
+		const (
+			scopeV1OrgWrite = coredata.OAuth2Scope("v1:org")
+			updateAction    = Action("core:organization:update")
+		)
+
+		scopeSet := oauth2scope.NewRegistry().Register(
+			map[coredata.OAuth2Scope][]string{
+				scopeV1OrgRead:  {action},
+				scopeV1OrgWrite: {updateAction},
+			},
+		)
+
+		a := NewAuthorizer(nil, nil, scopeSet)
+
+		ctx := oauth2.ContextWithAccessToken(
+			context.Background(),
+			&coredata.OAuth2AccessToken{Scopes: coredata.OAuth2Scopes{scopeV1OrgRead}},
+		)
+
+		err := a.checkOAuth2Scope(ctx, principal, updateAction)
+		require.Error(t, err)
+
+		scopeErr, ok := errors.AsType[*ErrInsufficientOAuth2Scope](err)
+		require.True(t, ok)
+		assert.Equal(t, principal, scopeErr.IdentityID)
+		assert.Equal(t, []coredata.OAuth2Scope{scopeV1OrgWrite}, scopeErr.Scopes)
 	})
 
 	t.Run("allows when registered scopes authorize the action", func(t *testing.T) {

pkg/iam/errors.go

@@ -17,6 +17,7 @@ package iam
 import (
 	"fmt"
 
+	"go.probo.inc/probo/pkg/coredata"
 	"go.probo.inc/probo/pkg/gid"
 	"go.probo.inc/probo/pkg/mail"
 )
@@ -205,18 +206,17 @@ func (e ErrInsufficientPermissions) Error() string {
 
 type ErrInsufficientOAuth2Scope struct {
 	IdentityID gid.GID
-	Action     Action
+	Scopes     []coredata.OAuth2Scope
 }
 
-func NewInsufficientOAuth2ScopeError(identityID gid.GID, action Action) error {
-	return &ErrInsufficientOAuth2Scope{IdentityID: identityID, Action: action}
+func NewInsufficientOAuth2ScopeError(identityID gid.GID, scopes ...coredata.OAuth2Scope) error {
+	return &ErrInsufficientOAuth2Scope{IdentityID: identityID, Scopes: scopes}
 }
 
 func (e ErrInsufficientOAuth2Scope) Error() string {
 	return fmt.Sprintf(
-		"identity %q does not have an OAuth2 scope granting action %s",
+		"identity %q does not have an OAuth2 scope granting the requested action",
 		e.IdentityID,
-		e.Action,
 	)
 }
 

pkg/iam/oauth2scope/registry.go

@@ -72,6 +72,13 @@ func (r *Registry) Allows(tokenScopes coredata.OAuth2Scopes, action string) bool
 	return slices.ContainsFunc(grantingScopes, tokenScopes.Contains)
 }
 
+func (r *Registry) ScopesForAction(action string) []coredata.OAuth2Scope {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	return sortedScopes(r.invertedIndex[action])
+}
+
 func (r *Registry) ValidateScopes(scopes coredata.OAuth2Scopes) error {
 	r.mu.RLock()
 	defer r.mu.RUnlock()

pkg/iam/oauth2scope/registry_test.go

@@ -81,6 +81,30 @@ func TestRegistry_ValidateScopes(t *testing.T) {
 	assert.EqualError(t, err, "invalid scope: v1:unknown:read")
 }
 
+func TestRegistry_ScopesForAction(t *testing.T) {
+	t.Parallel()
+
+	const (
+		scopeV1OrgRead  = coredata.OAuth2Scope("v1:org:read")
+		scopeV1OrgWrite = coredata.OAuth2Scope("v1:org")
+	)
+
+	reg := oauth2scope.NewRegistry().Register(
+		map[coredata.OAuth2Scope][]string{
+			scopeV1OrgRead:  {"core:organization:get"},
+			scopeV1OrgWrite: {"core:organization:get", "core:organization:update"},
+		},
+	)
+
+	assert.Equal(
+		t,
+		[]coredata.OAuth2Scope{scopeV1OrgWrite, scopeV1OrgRead},
+		reg.ScopesForAction("core:organization:get"),
+	)
+	assert.Equal(t, []coredata.OAuth2Scope{scopeV1OrgWrite}, reg.ScopesForAction("core:organization:update"))
+	assert.Nil(t, reg.ScopesForAction("core:organization:delete"))
+}
+
 func TestRegistry_RegisteredScopes(t *testing.T) {
 	t.Parallel()