pad/internal/server/middleware_auth.go

package server

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"log/slog"
	"net"
	"net/http"
	"strings"
	"time"

	"github.com/go-chi/chi/v5"
	"github.com/xarmian/pad/internal/models"
	"github.com/xarmian/pad/internal/store"
)

type contextKey string

const (
	// ctxTokenWorkspaceID is set when a valid API token is present.
	ctxTokenWorkspaceID contextKey = "token_workspace_id"
	// ctxCurrentUser is set when an authenticated user is resolved.
	ctxCurrentUser contextKey = "current_user"
	// ctxWorkspaceRole is set by RequireWorkspaceAccess with the user's role.
	ctxWorkspaceRole contextKey = "workspace_role"
	// ctxIsAPIToken is set to true when the request is authenticated via an API token
	// (as opposed to a session cookie or CLI session token).
	ctxIsAPIToken contextKey = "is_api_token"
	// ctxResolvedWorkspaceID is set by RequireWorkspaceAccess after resolving
	// the workspace slug/ID. Avoids redundant lookups in handlers.
	ctxResolvedWorkspaceID contextKey = "resolved_workspace_id"
)

// TokenAuth middleware checks for an Authorization: Bearer pad_xxx header.
// If a valid token is found, the associated workspace ID is stored in the
// request context. If no token header is present the request passes through
// unchanged (existing localhost behaviour). Invalid or expired tokens
// receive a 401 response.
func (s *Server) TokenAuth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		auth := r.Header.Get("Authorization")
		if auth == "" {
			// No token provided — allow through (localhost access).
			next.ServeHTTP(w, r)
			return
		}

		// Expect "Bearer pad_<64 hex chars>" or "Bearer padsess_<64 hex chars>"
		if !strings.HasPrefix(auth, "Bearer ") {
			writeError(w, http.StatusUnauthorized, "unauthorized", "Invalid authorization header format")
			return
		}

		token := strings.TrimPrefix(auth, "Bearer ")
		token = strings.TrimSpace(token)

		// Session token (from CLI login)
		if strings.HasPrefix(token, "padsess_") {
			session, err := s.store.ValidateSession(token)
			if err != nil {
				writeError(w, http.StatusInternalServerError, "internal_error", "Session validation failed")
				return
			}
			if session == nil {
				writeError(w, http.StatusUnauthorized, "unauthorized", "Invalid or expired session")
				return
			}
			// Session binding: validate User-Agent hasn't changed
			if session.UAHash != "" && sha256hex(r.UserAgent()) != session.UAHash {
				slog.Warn("session binding mismatch: User-Agent changed",
					"session_ip", session.IPAddress,
					"client_ip", clientIP(r))
				writeError(w, http.StatusUnauthorized, "unauthorized", "Session expired")
				return
			}
			// Session binding: detect IP changes. Log to audit log in all modes;
			// reject only when PAD_IP_CHANGE_ENFORCE=strict.
			switch s.handleSessionIPChange(w, r, session, token) {
			case sessionIPChangeTerminated:
				return
			case sessionIPChangeRevoked:
				// Session was destroyed. For public API paths (login,
				// password reset, health, share links) pass through
				// unauthenticated so the caller can recover. For
				// authenticated-only paths, the Bearer flow has no SPA
				// fallback — treat revocation as a hard 401.
				if isPublicAPIPath(r.URL.Path) {
					next.ServeHTTP(w, r)
					return
				}
				writeError(w, http.StatusUnauthorized, "session_ip_changed",
					"Session client IP changed — please log in again.")
				return
			}
			ctx := context.WithValue(r.Context(), ctxCurrentUser, session.User)
			next.ServeHTTP(w, r.WithContext(ctx))
			return
		}

		// API token
		if !strings.HasPrefix(token, "pad_") || len(token) != 68 {
			writeError(w, http.StatusUnauthorized, "unauthorized", "Invalid token format")
			return
		}

		apiToken, err := s.store.ValidateToken(token)
		if err != nil {
			writeError(w, http.StatusInternalServerError, "internal_error", "Token validation failed")
			return
		}
		if apiToken == nil {
			writeError(w, http.StatusUnauthorized, "unauthorized", "Invalid or expired token")
			return
		}

		// Enforce token scopes
		if !tokenScopeAllows(apiToken.Scopes, r.Method, r.URL.Path) {
			writeError(w, http.StatusForbidden, "forbidden", "Token scope does not permit this action")
			return
		}

		// Add near-expiry warning headers
		setTokenExpiryWarning(w, apiToken)

		ctx := context.WithValue(r.Context(), ctxIsAPIToken, true)

		// Resolve user from token's user_id (new user-owned tokens)
		if apiToken.UserID != "" {
			user, err := s.store.GetUser(apiToken.UserID)
			if err == nil && user != nil {
				ctx = context.WithValue(ctx, ctxCurrentUser, user)
			}
		}

		// Store workspace ID from the token if workspace-scoped
		if apiToken.WorkspaceID != "" {
			ctx = context.WithValue(ctx, ctxTokenWorkspaceID, apiToken.WorkspaceID)
		}

		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// SessionAuth middleware resolves session cookies into authenticated users.
// If a user was already resolved by TokenAuth, this is a no-op.
func (s *Server) SessionAuth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Already authenticated by TokenAuth — user-bound API tokens set
		// currentUser, legacy workspace-scoped tokens set tokenWorkspaceID
		// with no user. In either case we must short-circuit: otherwise a
		// stale session cookie on the same request could trigger the
		// IP-change strict-mode path and 401 the request even though the
		// API token itself is valid.
		if currentUser(r) != nil || tokenWorkspaceID(r) != "" {
			next.ServeHTTP(w, r)
			return
		}

		// Try session cookie (with fallback to unprefixed name for upgrade path)
		cookie, err := r.Cookie(sessionCookieName(s.secureCookies))
		if err != nil {
			cookie, err = r.Cookie("pad_session")
			if err != nil {
				next.ServeHTTP(w, r)
				return
			}
		}

		session, err := s.store.ValidateSession(cookie.Value)
		if err != nil || session == nil {
			next.ServeHTTP(w, r)
			return
		}

		// Session binding: validate User-Agent hasn't changed
		if session.UAHash != "" && sha256hex(r.UserAgent()) != session.UAHash {
			slog.Warn("session binding mismatch: User-Agent changed",
				"session_ip", session.IPAddress,
				"client_ip", clientIP(r))
			next.ServeHTTP(w, r)
			return
		}

		// Session binding: detect IP changes. Log to audit log in all modes;
		// reject only when PAD_IP_CHANGE_ENFORCE=strict.
		switch s.handleSessionIPChange(w, r, session, cookie.Value) {
		case sessionIPChangeTerminated:
			return
		case sessionIPChangeRevoked:
			// Browser path: let the request through unauthenticated so
			// the SPA renders its login flow instead of a JSON error.
			next.ServeHTTP(w, r)
			return
		}

		// Re-issue CSRF cookie if the session is valid but the cookie is missing.
		// This can happen when cookies expire at different times or are selectively cleared.
		// Skip for auth endpoints — they manage their own CSRF cookies (login sets, logout clears).
		if !strings.HasPrefix(r.URL.Path, "/api/v1/auth/") {
			if _, csrfErr := r.Cookie(csrfCookieName(s.secureCookies)); csrfErr != nil {
				setCSRFCookie(w, 7*24*60*60, s.secureCookies)
			}
		}

		ctx := context.WithValue(r.Context(), ctxCurrentUser, session.User)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// isPublicAPIPath reports whether the given request path is an API
// endpoint that bypasses authentication entirely. These handlers must
// work even when the caller has no valid session (login, registration,
// password reset, health probes, public plan limits, share-link tokens).
// Shared between RequireAuth and the session-IP-change path so both stay
// in sync — in particular, strict IP-change enforcement must NOT 401
// these endpoints, otherwise a user with a stale cookie can't even
// recover by logging in again.
func isPublicAPIPath(path string) bool {
	return strings.HasPrefix(path, "/api/v1/auth/") ||
		path == "/api/v1/health" ||
		strings.HasPrefix(path, "/api/v1/health/") ||
		strings.HasPrefix(path, "/api/v1/s/") ||
		path == "/api/v1/plan-limits"
}

// RequireAuth middleware blocks unauthenticated requests when users exist
// in the system. When no users exist (fresh install), all requests pass
// through to allow the setup flow.
func (s *Server) RequireAuth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		path := r.URL.Path

		// Auth endpoints, share link resolution, health, and the public
		// plan-limits endpoint are always exempt from auth.
		if isPublicAPIPath(path) {
			next.ServeHTTP(w, r)
			return
		}

		// Cloud sidecar endpoints authenticate via cloud_secret (X-Cloud-Secret
		// header, or legacy ?cloud_secret query-param). Only bypass the auth
		// gate when BOTH conditions hold:
		//   1. The request path is one of the three cloud admin endpoints.
		//   2. The request carries a cloud-secret marker.
		// The path gate is critical — without it, setting X-Cloud-Secret on
		// any route (e.g. GET /api/v1/workspaces) would globally bypass auth.
		// After the bypass, requireCloudMode (route-level) + validateCloudSecret
		// (handler-level) still confirm cloud mode is actually on and that the
		// secret matches.
		if isCloudAdminPath(path) && hasCloudSecretMarker(r) {
			next.ServeHTTP(w, r)
			return
		}

		// Static assets are exempt
		if strings.HasPrefix(path, "/_app/") ||
			path == "/favicon.ico" ||
			strings.HasSuffix(path, ".png") ||
			strings.HasSuffix(path, ".svg") ||
			strings.HasSuffix(path, ".ico") ||
			strings.HasSuffix(path, ".webmanifest") ||
			strings.HasSuffix(path, ".json") && !strings.HasPrefix(path, "/api/") {
			next.ServeHTTP(w, r)
			return
		}

		// If no users exist, allow everything (fresh install / setup mode)
		count, err := s.store.UserCount()
		if err != nil || count == 0 {
			next.ServeHTTP(w, r)
			return
		}

		// Already authenticated via token or session
		if user := currentUser(r); user != nil {
			if user.IsDisabled() {
				writeError(w, http.StatusForbidden, "account_disabled", "Your account has been disabled. Contact an administrator.")
				return
			}
			// Use a short-lived context so the write is cancelled if the DB is slow,
			// preventing goroutine/connection buildup under load.
			go func() {
				ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
				defer cancel()
				s.store.TouchUserActivity(ctx, user.ID)
			}()
			next.ServeHTTP(w, r)
			return
		}
		if tokenWorkspaceID(r) != "" {
			next.ServeHTTP(w, r)
			return
		}

		// Unauthenticated — return 401 for API, let SPA handle for browser
		if strings.HasPrefix(path, "/api/") {
			writeError(w, http.StatusUnauthorized, "unauthorized", "Authentication required")
			return
		}

		// For browser page requests, serve the SPA (frontend will check auth and show login)
		next.ServeHTTP(w, r)
	})
}

// tokenWorkspaceID returns the workspace ID set by the TokenAuth middleware,
// or an empty string if no token was used.
func tokenWorkspaceID(r *http.Request) string {
	v, _ := r.Context().Value(ctxTokenWorkspaceID).(string)
	return v
}

// currentUser returns the authenticated user from the request context,
// or nil if no user is authenticated.
func currentUser(r *http.Request) *models.User {
	u, _ := r.Context().Value(ctxCurrentUser).(*models.User)
	return u
}

// isAPITokenAuth returns true if the request was authenticated via an API token
// (not a session cookie or CLI session). Use this to gate sensitive operations
// like 2FA enrollment that should require an interactive session.
func isAPITokenAuth(r *http.Request) bool {
	v, _ := r.Context().Value(ctxIsAPIToken).(bool)
	return v
}

// currentUserID returns the authenticated user's ID, or empty string.
func currentUserID(r *http.Request) string {
	if u := currentUser(r); u != nil {
		return u.ID
	}
	return ""
}

// RequireWorkspaceAccess checks that the current user is a member of the
// workspace identified by the {slug} URL parameter. The user's workspace
// role is stored in the request context for downstream permission checks.
//
// When no users exist (fresh install), access is granted with an implicit
// "owner" role. Legacy API tokens (workspace-scoped, no user) are allowed
// if the token's workspace matches the requested workspace.
func (s *Server) RequireWorkspaceAccess(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		slugOrID := chi.URLParam(r, "slug")
		if slugOrID == "" {
			next.ServeHTTP(w, r)
			return
		}

		// Resolve workspace: supports both UUID and slug.
		ws, err := s.resolveWorkspace(slugOrID, currentUser(r))
		if err != nil {
			writeError(w, http.StatusInternalServerError, "internal_error", "Failed to resolve workspace")
			return
		}
		if ws == nil {
			writeError(w, http.StatusNotFound, "not_found", "Workspace not found")
			return
		}

		// Store resolved workspace ID in context for downstream handlers
		ctx := context.WithValue(r.Context(), ctxResolvedWorkspaceID, ws.ID)

		// Fresh install: no users → everyone gets owner access
		count, _ := s.store.UserCount()
		if count == 0 {
			ctx = context.WithValue(ctx, ctxWorkspaceRole, "owner")
			next.ServeHTTP(w, r.WithContext(ctx))
			return
		}

		// Legacy API token: workspace-scoped token without user context
		if tokenWsID := tokenWorkspaceID(r); tokenWsID != "" && currentUser(r) == nil {
			if tokenWsID == ws.ID {
				ctx = context.WithValue(ctx, ctxWorkspaceRole, "editor")
				next.ServeHTTP(w, r.WithContext(ctx))
				return
			}
			writeError(w, http.StatusForbidden, "forbidden", "Token not authorized for this workspace")
			return
		}

		// Authenticated user: check workspace membership
		user := currentUser(r)
		if user == nil {
			writeError(w, http.StatusUnauthorized, "unauthorized", "Authentication required")
			return
		}

		// Admin users get owner access to all workspaces
		if user.Role == "admin" {
			ctx = context.WithValue(ctx, ctxWorkspaceRole, "owner")
			next.ServeHTTP(w, r.WithContext(ctx))
			return
		}

		member, err := s.store.GetWorkspaceMember(ws.ID, user.ID)
		if err != nil {
			writeError(w, http.StatusInternalServerError, "internal_error", "Failed to check workspace access")
			return
		}
		if member == nil {
			// Not a member — check for guest access via grants
			hasGrants, grantErr := s.store.UserHasGrantsInWorkspace(ws.ID, user.ID)
			if grantErr != nil {
				slog.Error("failed to check guest grants", "workspace_id", ws.ID, "user_id", user.ID, "error", grantErr)
				writeError(w, http.StatusInternalServerError, "internal_error", "Failed to check workspace access")
				return
			}
			if !hasGrants {
				writeError(w, http.StatusForbidden, "forbidden", "You are not a member of this workspace")
				return
			}
			ctx = context.WithValue(ctx, ctxWorkspaceRole, "guest")
			next.ServeHTTP(w, r.WithContext(ctx))
			return
		}

		ctx = context.WithValue(ctx, ctxWorkspaceRole, member.Role)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

// workspaceRole returns the user's role in the current workspace,
// as set by RequireWorkspaceAccess. Returns empty string if not set.
func workspaceRole(r *http.Request) string {
	v, _ := r.Context().Value(ctxWorkspaceRole).(string)
	return v
}

// requireRole checks if the user's workspace role meets the minimum
// required level. Role hierarchy: owner > editor > viewer.
func requireRole(r *http.Request, minRole string) bool {
	role := workspaceRole(r)
	if role == "" {
		return false
	}
	return roleLevel(role) >= roleLevel(minRole)
}

// requireMinRole checks role and writes a 403 if insufficient.
// Returns true if the request should continue, false if it was rejected.
func requireMinRole(w http.ResponseWriter, r *http.Request, minRole string) bool {
	if requireRole(r, minRole) {
		return true
	}
	writeError(w, http.StatusForbidden, "forbidden", "Insufficient permissions")
	return false
}

// roleLevel returns a numeric level for role comparison.
// Higher values indicate more permissions.
func roleLevel(role string) int {
	switch role {
	case "owner":
		return 3
	case "editor":
		return 2
	case "viewer":
		return 1
	case "guest":
		return 0 // Guests have grant-based access only, no role-based permissions
	default:
		return 0
	}
}

// permissionLevel returns a numeric level for grant permission comparison.
func permissionLevel(perm string) int {
	switch perm {
	case "owner":
		return 4
	case "admin":
		return 3
	case "editor":
		return 2
	case "edit":
		return 2
	case "viewer":
		return 1
	case "view":
		return 1
	default:
		return 0
	}
}

// sha256hex returns the SHA-256 hex digest of a string.
func sha256hex(s string) string {
	h := sha256.Sum256([]byte(s))
	return hex.EncodeToString(h[:])
}

// canonicalIP returns the semantic (canonical text) form of an IP
// address string. For IPv6 this collapses different valid spellings
// (compressed vs expanded, uppercase vs lowercase, leading zeroes) to
// a single representation so comparing two strings by == reflects
// actual IP equality. For IPv4 it accepts both 4-byte and IPv4-in-IPv6
// forms. For inputs that don't parse as an IP the original string is
// returned so behavior stays predictable on malformed/debug values.
func canonicalIP(s string) string {
	if s == "" {
		return s
	}
	if ip := net.ParseIP(s); ip != nil {
		return ip.String()
	}
	return s
}

// sessionIPChangeOutcome captures what the caller (TokenAuth / SessionAuth)
// should do after handleSessionIPChange inspected the session.
type sessionIPChangeOutcome int

const (
	// sessionIPChangeContinue — happy path. IP matches (or no recorded IP).
	// Caller proceeds to install the session user in context and call next.
	sessionIPChangeContinue sessionIPChangeOutcome = iota
	// sessionIPChangeAllowedLogged — IP differs, log-only mode. Session
	// remains valid, caller proceeds as usual.
	sessionIPChangeAllowedLogged
	// sessionIPChangeRevoked — strict mode. The session was destroyed and
	// the caller must NOT install the user in context. For browser (non-API)
	// paths the request should continue unauthenticated so the SPA can
	// render its login screen instead of a raw JSON error.
	sessionIPChangeRevoked
	// sessionIPChangeTerminated — strict mode + API path. A 401 has already
	// been written; caller must return immediately.
	sessionIPChangeTerminated
)

// handleSessionIPChange compares the client IP on this request to the IP
// recorded when the session was created.
//
// Behavior:
//   - Session has no recorded IP (legacy pre-migration row): continue.
//   - IP matches: continue.
//   - Log-only mode (default): atomically rotate the stored IP via
//     compare-and-set. The race winner emits exactly one
//     ActionSessionIPChanged audit row per transition — concurrent
//     requests that lose the CAS skip logging to avoid duplicate rows.
//   - Strict mode (PAD_IP_CHANGE_ENFORCE=strict): do NOT rotate the
//     stored IP. Instead use DeleteSessionIfExists as the CAS primitive
//     — the request that actually deletes the row (a) logs the audit
//     entry once, (b) returns 401 for API / revoked for browser paths.
//     Rotating the IP first would be unsafe: if the subsequent
//     DeleteSession failed (transient DB error) the session would remain
//     valid rebound to the new IP, defeating strict enforcement. By
//     deleting atomically, any failure leaves the session bound to the
//     original IP so a follow-up request from the new IP still mismatches
//     and is still rejected. If the delete errors outright, the request
//     is rejected with 500 so the client can't proceed.
//
// Log-only mode breaks fewer legitimate clients (mobile roaming, VPN
// toggles, carrier NAT) while still giving operators a visible signal.
func (s *Server) handleSessionIPChange(w http.ResponseWriter, r *http.Request, session *store.SessionInfo, plainToken string) sessionIPChangeOutcome {
	// Canonicalize both sides so equivalent IPv6 representations
	// (compressed vs expanded, case, leading zeros) don't register as a
	// spurious change. Raw trusted-proxy X-Forwarded-For values can
	// arrive in any valid form.
	storedIP := canonicalIP(session.IPAddress)
	newIP := canonicalIP(clientIP(r))
	if storedIP == "" || newIP == "" || storedIP == newIP {
		return sessionIPChangeContinue
	}

	userID := ""
	if session.User != nil {
		userID = session.User.ID
	}

	if s.ipChangeEnforceStrict {
		// Destroy the session atomically. Only the caller whose DELETE
		// affected a row logs and issues the "session_ip_changed" response
		// body. A failed delete means the session is still valid AND still
		// bound to the old IP (we skipped the rotation), so a follow-up
		// request from the new IP will hit this path again — safe.
		deleted, err := s.store.DeleteSessionIfExists(plainToken)
		if err != nil {
			// Fail closed: we can't prove the session is gone, so refuse
			// to let the request through. A retry will converge once the
			// DB recovers.
			slog.Error("failed to destroy session on IP-change in strict mode; failing closed",
				"session_ip", storedIP,
				"client_ip", newIP,
				"user_id", userID,
				"error", err)
			writeError(w, http.StatusInternalServerError, "internal_error",
				"Unable to validate session. Please try again.")
			return sessionIPChangeTerminated
		}
		if deleted {
			s.logAuditEventForUser(models.ActionSessionIPChanged, r, userID, auditMeta(map[string]string{
				"old_ip": storedIP,
				"new_ip": newIP,
			}))
			slog.Warn("session destroyed: IP changed (strict enforcement)",
				"session_ip", storedIP,
				"client_ip", newIP,
				"user_id", userID)
		}
		// Clear client-side cookies regardless — even if another request
		// already deleted the row, this client is still holding the now-
		// invalid token.
		clearSessionCookie(w, s.secureCookies)
		clearCSRFCookie(w)
		// Public API paths (login/register/password-reset, health, share
		// links, plan-limits) must STILL work after the session was
		// destroyed — a user with a stale cookie needs a way back in, and
		// Prometheus health probes shouldn't 401 because some other tab
		// left a stale session. Pass the request through unauthenticated.
		if isPublicAPIPath(r.URL.Path) {
			return sessionIPChangeRevoked
		}
		if strings.HasPrefix(r.URL.Path, "/api/") {
			writeError(w, http.StatusUnauthorized, "session_ip_changed",
				"Session client IP changed — please log in again.")
			return sessionIPChangeTerminated
		}
		// Non-API (browser) path: caller must NOT install the destroyed
		// session's user into the request context. The SPA will render its
		// unauth state and the user will redirect to login.
		return sessionIPChangeRevoked
	}

	// Log-only mode: CAS-rotate the stored IP so only the winner logs.
	// The CAS compares against session.IPAddress (the raw value we read
	// from the DB) and writes the canonical newIP so future comparisons
	// are consistent. Err on the side of "winner" when the CAS errors
	// — we'd rather log an extra row than miss the signal entirely.
	// A failed rotate here is non-fatal: worst case the next request
	// also gets an audit row.
	won, err := s.store.UpdateSessionIPIfEquals(plainToken, session.IPAddress, newIP)
	if err != nil {
		slog.Warn("failed to rotate session ip after change", "error", err)
		won = true
	}
	if won {
		s.logAuditEventForUser(models.ActionSessionIPChanged, r, userID, auditMeta(map[string]string{
			"old_ip": storedIP,
			"new_ip": newIP,
		}))
		slog.Info("session client IP changed (logged, request allowed)",
			"session_ip", storedIP,
			"client_ip", newIP,
			"user_id", userID)
	}
	return sessionIPChangeAllowedLogged
}

// clearSessionCookie expires the session cookie on the client so a
// subsequent request doesn't keep presenting a now-revoked token.
func clearSessionCookie(w http.ResponseWriter, secure bool) {
	http.SetCookie(w, &http.Cookie{
		Name:     sessionCookieName(secure),
		Value:    "",
		Path:     "/",
		MaxAge:   -1,
		HttpOnly: true,
		Secure:   secure,
		SameSite: http.SameSiteLaxMode,
	})
}

// tokenScopeAllows checks if the token's scopes permit the given HTTP method
// and path. Scopes are stored as a JSON array of strings.
//
// Supported scopes:
//   - "*"       — full access
//   - "read"    — GET/HEAD/OPTIONS only
//   - "write"   — all methods
//
// Policy (deny-by-default whitelist):
//   - Empty scope string → allow (legacy DB rows where the column was never
//     populated). These tokens pre-date scope enforcement.
//   - Empty JSON array `[]` → allow (explicit "unrestricted" legacy form,
//     equivalent to no scopes recorded).
//   - Parseable array with at least one scope: allow iff a RECOGNIZED scope
//     grants this method. Unrecognized scopes never contribute to allow
//     and are logged once per request so operators can spot typos like
//     "read-only" that would previously have fallen open.
//   - Unparseable JSON → deny (data corruption or tampering). Previously
//     fell open; that was the security concern behind TASK-667.
//
// Switching to deny-by-default closes the hole where a future scope name
// like "read-only" would silently grant full access.
func tokenScopeAllows(scopesJSON, method, path string) bool {
	_ = path // reserved for future per-resource scopes

	// Empty string (legacy DB rows where the column was never populated)
	// → full access. Same fast path for the explicit wildcard.
	if scopesJSON == "" || strings.TrimSpace(scopesJSON) == `["*"]` {
		return true
	}

	var scopes []string
	if err := json.Unmarshal([]byte(scopesJSON), &scopes); err != nil {
		slog.Warn("token has unparseable scopes; denying request",
			"method", method, "path", path, "error", err)
		return false
	}

	// Distinguish JSON null (scopes == nil after unmarshal) from an
	// explicit empty array (non-nil, len 0). null falls into the deny
	// path because it signals a client-side serializer bug, not a
	// documented legacy form. An explicit [] (including whitespace-
	// padded "[ ]" or "[\n]") is the documented legacy-unrestricted
	// form and keeps working.
	if scopes == nil {
		slog.Warn("token has null scopes; denying request",
			"method", method, "path", path, "scopes_json", scopesJSON)
		return false
	}
	if len(scopes) == 0 {
		// Explicit empty array → unrestricted (legacy pre-enforcement).
		return true
	}

	allowed := false
	var unknown []string
	for _, scope := range scopes {
		switch scope {
		case "*", "write":
			allowed = true
		case "read":
			if method == http.MethodGet || method == http.MethodHead || method == http.MethodOptions {
				allowed = true
			}
		default:
			unknown = append(unknown, scope)
		}
	}

	if len(unknown) > 0 {
		slog.Warn("token has unrecognized scopes; treated as no-grant",
			"method", method, "path", path, "unknown_scopes", unknown)
	}
	return allowed
}