Unify authentication with Identity struct across ToolHive (#2437)

* Unify authentication with Identity struct across ToolHive

Consolidate the vMCP Identity infrastructure into pkg/auth to eliminate
code duplication and simplify authentication flow throughout ToolHive.

Changes:
- Move Identity struct from pkg/vmcp/auth to pkg/auth as the canonical
  type for representing authenticated principals
- Update all authentication middleware (OIDC, local, anonymous) to
  directly create and inject Identity into context
- Remove duplicate IdentityMiddleware from vMCP (now redundant)
- Update authz and audit packages to use IdentityFromContext
- Add backward-compatible GetClaimsFromContext helper
- Delete duplicate implementations: identity.go, context.go, and
  associated test files from pkg/vmcp/auth

This reduces code by ~655 lines while maintaining full functionality
and test coverage. All middleware now outputs Identity directly,
eliminating the need for a separate Claims → Identity conversion layer.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Address PR feedback: Fix token exchange integration and add test coverage

This commit addresses all feedback from PR #2437 review:

Critical fixes:
- Fix token exchange middleware to use Identity from context instead of
  directly accessing ClaimsContextKey, preventing silent token exchange
  failures in production (pkg/auth/tokenexchange/middleware.go)
- Update all token exchange tests to use WithIdentity pattern to match
  production auth flow (pkg/auth/tokenexchange/middleware_test.go)

Code quality improvements:
- Add nil safety check in GetClaimsFromContext to guard against edge
  case where nil Identity pointer is explicitly stored in context
  (pkg/auth/context.go)
- Add WWW-Authenticate header for claims-to-identity conversion errors
  for RFC 6750 compliance (pkg/auth/token.go)

Test coverage:
- Restore test coverage from deleted pkg/vmcp/auth files:
  - pkg/auth/identity_test.go: Tests for Identity struct, MarshalJSON,
    String, and claimsToIdentity conversion
  - pkg/auth/context_test.go: Tests for context operations including
    edge cases for nil handling and backward compatibility

All tests pass. Linting clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove dead ClaimsContextKey code

ClaimsContextKey was a legacy context key that is no longer used after
the Identity unification. All authentication middleware now uses
IdentityContextKey via WithIdentity(), and GetClaimsFromContext() reads
from Identity, never from ClaimsContextKey.

Changes:
- Remove ClaimsContextKey type definition from pkg/auth/context.go
- Remove obsolete comment reference from pkg/auth/token.go
- Update test to use realistic edge case (Identity with nil Claims)
  instead of testing impossible scenario with ClaimsContextKey

All tests pass. No functional change to production code.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: JAORMX

pkg/audit/auditor.go

@@ -315,26 +315,26 @@ func (*Auditor) getClientIP(r *http.Request) string {
 func (*Auditor) extractSubjects(r *http.Request) map[string]string {
 	subjects := make(map[string]string)
 
-	// Extract user information from JWT claims
-	if claims, ok := auth.GetClaimsFromContext(r.Context()); ok {
-		if sub, ok := claims["sub"].(string); ok && sub != "" {
-			subjects[SubjectKeyUserID] = sub
+	// Extract user information from Identity
+	if identity, ok := auth.IdentityFromContext(r.Context()); ok {
+		if identity.Subject != "" {
+			subjects[SubjectKeyUserID] = identity.Subject
 		}
 
-		if name, ok := claims["name"].(string); ok && name != "" {
-			subjects[SubjectKeyUser] = name
-		} else if preferredUsername, ok := claims["preferred_username"].(string); ok && preferredUsername != "" {
+		if identity.Name != "" {
+			subjects[SubjectKeyUser] = identity.Name
+		} else if preferredUsername, ok := identity.Claims["preferred_username"].(string); ok && preferredUsername != "" {
 			subjects[SubjectKeyUser] = preferredUsername
-		} else if email, ok := claims["email"].(string); ok && email != "" {
-			subjects[SubjectKeyUser] = email
+		} else if identity.Email != "" {
+			subjects[SubjectKeyUser] = identity.Email
 		}
 
 		// Add client information if available
-		if clientName, ok := claims["client_name"].(string); ok && clientName != "" {
+		if clientName, ok := identity.Claims["client_name"].(string); ok && clientName != "" {
 			subjects[SubjectKeyClientName] = clientName
 		}
 
-		if clientVersion, ok := claims["client_version"].(string); ok && clientVersion != "" {
+		if clientVersion, ok := identity.Claims["client_version"].(string); ok && clientVersion != "" {
 			subjects[SubjectKeyClientVersion] = clientVersion
 		}
 	}

pkg/audit/auditor_test.go

@@ -2,7 +2,6 @@ package audit
 
 import (
 	"bytes"
-	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -353,7 +352,13 @@ func TestExtractSubjects(t *testing.T) {
 		}
 
 		req := httptest.NewRequest("GET", "/test", nil)
-		ctx := context.WithValue(req.Context(), auth.ClaimsContextKey{}, claims)
+		identity := &auth.Identity{
+			Subject: claims["sub"].(string),
+			Name:    claims["name"].(string),
+			Email:   claims["email"].(string),
+			Claims:  claims,
+		}
+		ctx := auth.WithIdentity(req.Context(), identity)
 		req = req.WithContext(ctx)
 
 		subjects := auditor.extractSubjects(req)
@@ -372,7 +377,11 @@ func TestExtractSubjects(t *testing.T) {
 		}
 
 		req := httptest.NewRequest("GET", "/test", nil)
-		ctx := context.WithValue(req.Context(), auth.ClaimsContextKey{}, claims)
+		identity := &auth.Identity{
+			Subject: claims["sub"].(string),
+			Claims:  claims,
+		}
+		ctx := auth.WithIdentity(req.Context(), identity)
 		req = req.WithContext(ctx)
 
 		subjects := auditor.extractSubjects(req)
@@ -389,7 +398,12 @@ func TestExtractSubjects(t *testing.T) {
 		}
 
 		req := httptest.NewRequest("GET", "/test", nil)
-		ctx := context.WithValue(req.Context(), auth.ClaimsContextKey{}, claims)
+		identity := &auth.Identity{
+			Subject: claims["sub"].(string),
+			Email:   claims["email"].(string),
+			Claims:  claims,
+		}
+		ctx := auth.WithIdentity(req.Context(), identity)
 		req = req.WithContext(ctx)
 
 		subjects := auditor.extractSubjects(req)

pkg/auth/anonymous.go

@@ -2,18 +2,17 @@
 package auth
 
 import (
-	"context"
 	"net/http"
 	"time"
 
 	"github.com/golang-jwt/jwt/v5"
 )
 
-// AnonymousMiddleware creates an HTTP middleware that sets up anonymous claims.
+// AnonymousMiddleware creates an HTTP middleware that sets up anonymous identity.
 // This is useful for testing and local environments where authorization policies
 // need to work without requiring actual authentication.
 //
-// The middleware sets up basic anonymous claims that can be used by authorization
+// The middleware sets up basic anonymous identity that can be used by authorization
 // policies, allowing them to function even when authentication is disabled.
 // This is heavily discouraged in production settings but is handy for testing
 // and local development environments.
@@ -31,9 +30,18 @@ func AnonymousMiddleware(next http.Handler) http.Handler {
 			"name":  "Anonymous User",
 		}
 
-		// Add the anonymous claims to the request context using the same key
-		// as the JWT middleware for consistency
-		ctx := context.WithValue(r.Context(), ClaimsContextKey{}, claims)
+		// Create Identity from claims
+		identity := &Identity{
+			Subject:   "anonymous",
+			Name:      "Anonymous User",
+			Email:     "anonymous@localhost",
+			Claims:    claims,
+			Token:     "", // No token for anonymous auth
+			TokenType: "Bearer",
+		}
+
+		// Add the Identity to the request context
+		ctx := WithIdentity(r.Context(), identity)
 		next.ServeHTTP(w, r.WithContext(ctx))
 	})
 }

pkg/auth/context.go

@@ -0,0 +1,101 @@
+// Package auth provides authentication and authorization utilities.
+package auth
+
+import (
+	"context"
+	"errors"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+// IdentityContextKey is the key used to store Identity in the request context.
+// This provides type-safe context storage and retrieval for authenticated identities.
+//
+// Using an empty struct as the key prevents collisions with other context keys,
+// as each empty struct type is distinct even if they have the same name in different packages.
+type IdentityContextKey struct{}
+
+// WithIdentity stores an Identity in the context.
+// If identity is nil, the original context is returned unchanged.
+//
+// This function is typically called by authentication middleware after successful
+// authentication to make the identity available to downstream handlers.
+//
+// Example:
+//
+//	identity := &Identity{Subject: "user123", Name: "Alice"}
+//	ctx = WithIdentity(ctx, identity)
+func WithIdentity(ctx context.Context, identity *Identity) context.Context {
+	if identity == nil {
+		return ctx
+	}
+	return context.WithValue(ctx, IdentityContextKey{}, identity)
+}
+
+// IdentityFromContext retrieves an Identity from the context.
+// Returns the identity and true if present, nil and false otherwise.
+//
+// This function is typically called by authorization middleware or handlers that need
+// to check who the authenticated user is.
+//
+// Example:
+//
+//	identity, ok := IdentityFromContext(ctx)
+//	if !ok {
+//	    return errors.New("no authenticated identity")
+//	}
+//	log.Printf("Request from user: %s", identity.Subject)
+func IdentityFromContext(ctx context.Context) (*Identity, bool) {
+	identity, ok := ctx.Value(IdentityContextKey{}).(*Identity)
+	return identity, ok
+}
+
+// GetClaimsFromContext retrieves the claims from Identity in the request context.
+// This is a helper function for backward compatibility with code that expects MapClaims.
+// New code should use IdentityFromContext and access the Claims field directly.
+func GetClaimsFromContext(ctx context.Context) (jwt.MapClaims, bool) {
+	if ctx == nil {
+		return nil, false
+	}
+
+	// Get Identity and return its Claims
+	if identity, ok := IdentityFromContext(ctx); ok && identity != nil {
+		if identity.Claims != nil {
+			return jwt.MapClaims(identity.Claims), true
+		}
+	}
+
+	return nil, false
+}
+
+// claimsToIdentity converts JWT claims to Identity struct.
+// It requires the 'sub' claim per OIDC Core 1.0 spec § 5.1.
+// The original token can be provided for passthrough scenarios.
+//
+// Note: The Groups field is intentionally NOT populated here.
+// Authorization logic MUST extract groups from the Claims map, as group claim
+// names vary by provider (e.g., "groups", "roles", "cognito:groups").
+func claimsToIdentity(claims jwt.MapClaims, token string) (*Identity, error) {
+	// Validate required 'sub' claim per OIDC Core 1.0 spec
+	sub, ok := claims["sub"].(string)
+	if !ok || sub == "" {
+		return nil, errors.New("missing or invalid 'sub' claim (required by OIDC Core 1.0 § 5.1)")
+	}
+
+	identity := &Identity{
+		Subject:   sub,
+		Claims:    claims,
+		Token:     token,
+		TokenType: "Bearer",
+	}
+
+	// Extract optional standard claims
+	if name, ok := claims["name"].(string); ok {
+		identity.Name = name
+	}
+	if email, ok := claims["email"].(string); ok {
+		identity.Email = email
+	}
+
+	return identity, nil
+}