Codebase quality pass: fix bugs, unify patterns, reduce complexity

Fix duplicate isStdioServer with diverging implementations by adding
IsStdio() method on MCPClientConfig. Unify CSRF strategy across admin
and token handlers using stateless HMAC-based tokens (removes sync.Map
approach). Make StoreAuthorizeRequest return an error so Firestore
failures surface clearly. Use cookie.SetSession consistently (fixes
SameSite mismatch from Strict to Lax for OAuth callbacks).

Split http.go into focused files (user_token_service.go,
session_handler.go). Extract handleBrowserCallback and
handleOAuthClientCallback from 190-line IDPCallbackHandler. Add
GetUser to Storage interface for O(1) admin checks. Consolidate
browserauth + oauthsession into internal/session, move envutil.IsDev
into config package. Replace hardcoded Firestore collection names
with constants. Delete unused GetErrorName. Update CLAUDE.md to
reference ./scripts/ instead of make.

Author: dgellow

CLAUDE.md

@@ -245,23 +245,24 @@ When refactoring for better design:
 
 ```bash
 # Build everything
-make build
+./scripts/build
 
 # Format everything
-make format
+./scripts/format
 
 # Lint everything
-make lint
+./scripts/lint
 
 # Test mcp-front
+./scripts/test
 go test ./internal/... -v
 go test ./integration -v
 
 # Run mcp-front locally
 ./mcp-front -config config.json
 
 # Start docs dev server
-make doc
+./scripts/docs
 ```
 
 ## Documentation Site Guidelines

internal/adminauth/admin.go

@@ -22,8 +22,16 @@ func IsAdmin(ctx context.Context, email string, adminConfig *config.AdminConfig,
 		return true
 	}
 
-	// Check if user is a promoted admin in storage
+	// Check if user is a promoted admin in storage.
+	// Try exact match first (O(1)), fall back to case-insensitive scan
+	// since emails may be stored with different casing.
 	if store != nil {
+		user, err := store.GetUser(ctx, normalizedEmail)
+		if err == nil {
+			return user.IsAdmin
+		}
+
+		// Fallback: case-insensitive scan for emails stored with different casing
 		users, err := store.GetAllUsers(ctx)
 		if err == nil {
 			for _, user := range users {

internal/browserauth/session.go

@@ -1,4 +1,4 @@
-package envutil
+package config
 
 import (
 	"os"

internal/envutil/envutil.go internal/config/env.gointernal/envutil/envutil.go renamed to internal/config/env.go

@@ -187,6 +187,11 @@ type MCPClientConfig struct {
 	InlineConfig json.RawMessage `json:"inline,omitempty"`
 }
 
+// IsStdio returns true if this is a stdio-based MCP server
+func (c *MCPClientConfig) IsStdio() bool {
+	return c.TransportType == MCPClientTypeStdio
+}
+
 // SessionConfig represents session management configuration
 type SessionConfig struct {
 	Timeout         time.Duration

internal/config/types.go

@@ -4,7 +4,7 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/dgellow/mcp-front/internal/envutil"
+	"github.com/dgellow/mcp-front/internal/config"
 	"github.com/dgellow/mcp-front/internal/log"
 )
 
@@ -16,7 +16,7 @@ const (
 
 // SetSession sets a session cookie with appropriate security settings
 func SetSession(w http.ResponseWriter, value string, maxAge time.Duration) {
-	secure := !envutil.IsDev()
+	secure := !config.IsDev()
 	http.SetCookie(w, &http.Cookie{
 		Name:     SessionCookie,
 		Value:    value,
@@ -41,7 +41,7 @@ func SetCSRF(w http.ResponseWriter, value string) {
 		Value:    value,
 		Path:     "/",
 		HttpOnly: false, // CSRF tokens need to be readable by JavaScript
-		Secure:   !envutil.IsDev(),
+		Secure:   !config.IsDev(),
 		SameSite: http.SameSiteStrictMode,
 		MaxAge:   int((24 * time.Hour).Seconds()), // 24 hours
 	})

internal/cookie/cookie.go

@@ -0,0 +1,61 @@
+package crypto
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// CSRFProtection provides stateless HMAC-based CSRF token generation and validation.
+// Tokens are self-contained: nonce:timestamp:signature, with configurable expiry.
+type CSRFProtection struct {
+	signingKey []byte
+	ttl        time.Duration
+}
+
+// NewCSRFProtection creates a new CSRF protection instance
+func NewCSRFProtection(signingKey []byte, ttl time.Duration) CSRFProtection {
+	return CSRFProtection{
+		signingKey: signingKey,
+		ttl:        ttl,
+	}
+}
+
+// Generate creates a new CSRF token
+func (c *CSRFProtection) Generate() (string, error) {
+	nonce := GenerateSecureToken()
+	if nonce == "" {
+		return "", fmt.Errorf("failed to generate nonce")
+	}
+
+	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
+	data := nonce + ":" + timestamp
+	signature := SignData(data, c.signingKey)
+
+	return fmt.Sprintf("%s:%s:%s", nonce, timestamp, signature), nil
+}
+
+// Validate checks if a CSRF token is valid and not expired
+func (c *CSRFProtection) Validate(token string) bool {
+	parts := strings.SplitN(token, ":", 3)
+	if len(parts) != 3 {
+		return false
+	}
+
+	nonce := parts[0]
+	timestampStr := parts[1]
+	signature := parts[2]
+
+	timestamp, err := strconv.ParseInt(timestampStr, 10, 64)
+	if err != nil {
+		return false
+	}
+
+	if time.Since(time.Unix(timestamp, 0)) > c.ttl {
+		return false
+	}
+
+	data := nonce + ":" + timestampStr
+	return ValidateSignedData(data, signature, c.signingKey)
+}

internal/crypto/csrf.go

@@ -47,24 +47,3 @@ func NewStandardError(code int) *Error {
 	}
 }
 
-// GetErrorName returns a human-readable name for standard error codes
-func GetErrorName(code int) string {
-	switch code {
-	case ParseError:
-		return "PARSE_ERROR"
-	case InvalidRequest:
-		return "INVALID_REQUEST"
-	case MethodNotFound:
-		return "METHOD_NOT_FOUND"
-	case InvalidParams:
-		return "INVALID_PARAMS"
-	case InternalError:
-		return "INTERNAL_ERROR"
-	default:
-		// Check if it's an MCP-specific error code
-		if code >= -32099 && code <= -32000 {
-			return "SERVER_ERROR"
-		}
-		return "UNKNOWN_ERROR"
-	}
-}

internal/jsonrpc/errors.go

@@ -380,7 +380,7 @@ func buildHTTPHandler(
 		}
 
 		// Create token handlers
-		tokenHandlers := server.NewTokenHandlers(storage, cfg.MCPServers, true, serviceOAuthClient)
+		tokenHandlers := server.NewTokenHandlers(storage, cfg.MCPServers, true, serviceOAuthClient, []byte(authConfig.EncryptionKey))
 
 		// Token management UI endpoints
 		mux.Handle(route("/my/tokens"), server.ChainMiddleware(http.HandlerFunc(tokenHandlers.ListTokensHandler), tokenMiddleware...))
@@ -421,7 +421,7 @@ func buildHTTPHandler(
 			}
 		} else {
 			// For stdio/SSE servers
-			if isStdioServer(serverConfig) {
+			if serverConfig.IsStdio() {
 				sseServer, mcpServer, err = buildStdioSSEServer(serverName, baseURL, sessionManager)
 				if err != nil {
 					return nil, fmt.Errorf("failed to create SSE server for %s: %w", serverName, err)
@@ -606,7 +606,3 @@ func buildStdioSSEServer(serverName, baseURL string, sessionManager *client.Stdi
 	return sseServer, mcpServer, nil
 }
 
-// isStdioServer checks if this is a stdio-based server
-func isStdioServer(cfg *config.MCPClientConfig) bool {
-	return cfg.TransportType == config.MCPClientTypeStdio
-}

internal/mcpfront.go

@@ -12,10 +12,9 @@ import (
 
 	"github.com/dgellow/mcp-front/internal/config"
 	"github.com/dgellow/mcp-front/internal/crypto"
-	"github.com/dgellow/mcp-front/internal/envutil"
 	jsonwriter "github.com/dgellow/mcp-front/internal/json"
 	"github.com/dgellow/mcp-front/internal/log"
-	"github.com/dgellow/mcp-front/internal/oauthsession"
+	"github.com/dgellow/mcp-front/internal/session"
 	"github.com/dgellow/mcp-front/internal/storage"
 	"github.com/dgellow/mcp-front/internal/urlutil"
 	"github.com/ory/fosite"
@@ -48,8 +47,8 @@ func NewOAuthProvider(oauthConfig config.OAuthAuthConfig, store storage.Storage,
 
 	// Determine min parameter entropy based on environment
 	minEntropy := 8 // Production default - enforce secure state parameters (8+ chars)
-	log.Logf("OAuth provider initialization - MCP_FRONT_ENV=%s, isDevelopmentMode=%v", os.Getenv("MCP_FRONT_ENV"), envutil.IsDev())
-	if envutil.IsDev() {
+	log.Logf("OAuth provider initialization - MCP_FRONT_ENV=%s, isDevelopmentMode=%v", os.Getenv("MCP_FRONT_ENV"), config.IsDev())
+	if config.IsDev() {
 		minEntropy = 0 // Development mode - allow empty state parameters
 		log.LogWarn("Development mode enabled - OAuth security checks relaxed (state parameter entropy: %d)", minEntropy)
 	}
@@ -158,8 +157,8 @@ func NewValidateTokenMiddleware(provider fosite.OAuth2Provider, issuer string, a
 			// - This is documented fosite behavior, not a bug
 			// - The actual session data must be retrieved from the returned AccessRequester
 			// See: https://github.com/ory/fosite/issues/256
-			session := &oauthsession.Session{DefaultSession: &fosite.DefaultSession{}}
-			_, accessRequest, err := provider.IntrospectToken(ctx, token, fosite.AccessToken, session)
+			oauthSession := &session.OAuthSession{DefaultSession: &fosite.DefaultSession{}}
+			_, accessRequest, err := provider.IntrospectToken(ctx, token, fosite.AccessToken, oauthSession)
 			if err != nil {
 				jsonwriter.WriteUnauthorizedRFC9728(w, "Invalid or expired token", metadataURI)
 				return
@@ -180,7 +179,7 @@ func NewValidateTokenMiddleware(provider fosite.OAuth2Provider, issuer string, a
 			// This is the correct way to retrieve session data after token introspection
 			var userEmail string
 			if accessRequest != nil {
-				if reqSession, ok := accessRequest.GetSession().(*oauthsession.Session); ok {
+				if reqSession, ok := accessRequest.GetSession().(*session.OAuthSession); ok {
 					if reqSession.Identity.Email != "" {
 						userEmail = reqSession.Identity.Email
 					}