refactor(server): extract the device authorization endpoints into a package

Move the browser-facing side of the OAuth2 device flow (RFC 8628) out of the
god Server into a server/device package: the /device user-code page,
/device/code authorization request, /device/auth/verify_code verification, and
the /device/callback that completes the flow. The handler mounts its own routes
and holds only its dependencies (storage, templates, issuer URL, timing, logger)
plus the shared ExchangeAuthCode and a RenderError callback.

The device_code token grant stays with the token endpoint: it is a /token grant
like the others, dispatched from handleToken, so the token endpoint keeps
owning it rather than the server reaching into the device handler. The
deprecated /device/token endpoint stays alongside it.

The PKCE code-challenge method names move to the oauth2 package as
PKCEMethodPlain/PKCEMethodS256. No behaviour change.

Signed-off-by: maksim.nabokikh <max.nabokih@gmail.com>

Author: nabokihms

server/device/device.go

@@ -0,0 +1,394 @@
+// Package device implements the browser-facing side of the OAuth2 device
+// authorization grant (RFC 8628): the /device user-code entry page, the
+// /device/code authorization request, user-code verification, and the callback
+// that completes the flow. The device_code token grant that the device polls for
+// lives with the token endpoint.
+package device
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"path"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/dexidp/dex/server/oauth2"
+	"github.com/dexidp/dex/server/router"
+	"github.com/dexidp/dex/server/templates"
+	"github.com/dexidp/dex/server/tokens"
+	"github.com/dexidp/dex/storage"
+)
+
+// DeviceCodeResponse is the device authorization response (RFC 8628 §3.2).
+type DeviceCodeResponse struct {
+	// The unique device code for device authentication
+	DeviceCode string `json:"device_code"`
+	// The code the user will exchange via a browser and log in
+	UserCode string `json:"user_code"`
+	// The url to verify the user code.
+	VerificationURI string `json:"verification_uri"`
+	// The verification uri with the user code appended for pre-filling form
+	VerificationURIComplete string `json:"verification_uri_complete"`
+	// The lifetime of the device code
+	ExpireTime int `json:"expires_in"`
+	// How often the device is allowed to poll to verify that the user login occurred
+	PollInterval int `json:"interval"`
+}
+
+// Handler serves the browser side of the device authorization grant.
+type Handler struct {
+	IssuerURL        url.URL
+	Storage          storage.Storage
+	Templates        *templates.Templates
+	Now              func() time.Time
+	RequestsValidFor time.Duration
+	Logger           *slog.Logger
+
+	// ExchangeAuthCode exchanges the authorization code for tokens after the
+	// user authenticates. It is the authorization-code grant's logic, injected
+	// so the device handler does not reimplement token issuance.
+	//
+	// TODO: this injected Server method is a temporary seam; the auth-code
+	// exchange should become a shared component both grants depend on directly.
+	ExchangeAuthCode func(ctx context.Context, w http.ResponseWriter, authCode storage.AuthCode, client storage.Client) (tokens.Response, error)
+}
+
+// renderError renders an HTML error page.
+func (h *Handler) renderError(r *http.Request, w http.ResponseWriter, status int, description string) {
+	if err := h.Templates.Err(r, w, status, description); err != nil {
+		h.Logger.ErrorContext(r.Context(), "server template error", "err", err)
+	}
+}
+
+// Mount registers the device authorization routes.
+func (h *Handler) Mount(m router.Mux) {
+	m.HandleFunc("/device", h.handleDeviceExchange)
+	m.HandleFunc("/device/auth/verify_code", h.verifyUserCode)
+	m.HandleFunc("/device/code", h.handleDeviceCode)
+	m.HandleFunc(oauth2.DeviceCallbackURI, h.handleDeviceCallback)
+}
+
+func (h *Handler) writeError(w http.ResponseWriter, typ, description string, statusCode int) {
+	if err := oauth2.WriteError(w, typ, description, statusCode); err != nil {
+		h.Logger.Error("device error response", "err", err)
+	}
+}
+
+func (h *Handler) getDeviceVerificationURI() string {
+	return path.Join(h.IssuerURL.Path, "/device/auth/verify_code")
+}
+
+func (h *Handler) handleDeviceExchange(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		// Grab the parameter(s) from the query.
+		// If "user_code" is set, pre-populate the user code text field.
+		// If "invalid" is set, set the invalidAttempt boolean, which will display a message to the user that they
+		// attempted to redeem an invalid or expired user code.
+		userCode := r.URL.Query().Get("user_code")
+		invalidAttempt, err := strconv.ParseBool(r.URL.Query().Get("invalid"))
+		if err != nil {
+			invalidAttempt = false
+		}
+		if err := h.Templates.Device(r, w, h.getDeviceVerificationURI(), userCode, invalidAttempt); err != nil {
+			h.Logger.ErrorContext(r.Context(), "server template error", "err", err)
+			h.renderError(r, w, http.StatusNotFound, "Page not found")
+		}
+	default:
+		h.renderError(r, w, http.StatusBadRequest, "Requested resource does not exist.")
+	}
+}
+
+func (h *Handler) handleDeviceCode(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	pollIntervalSeconds := 5
+
+	switch r.Method {
+	case http.MethodPost:
+		err := r.ParseForm()
+		if err != nil {
+			h.Logger.ErrorContext(r.Context(), "could not parse Device Request body", "err", err)
+			h.writeError(w, oauth2.InvalidRequest, "", http.StatusNotFound)
+			return
+		}
+
+		// Get the client id and scopes from the post
+		clientID := r.Form.Get("client_id")
+		clientSecret := r.Form.Get("client_secret")
+		scopes := strings.Fields(r.Form.Get("scope"))
+		codeChallenge := r.Form.Get("code_challenge")
+		codeChallengeMethod := r.Form.Get("code_challenge_method")
+
+		if codeChallengeMethod == "" {
+			codeChallengeMethod = oauth2.PKCEMethodPlain
+		}
+		if codeChallengeMethod != oauth2.PKCEMethodS256 && codeChallengeMethod != oauth2.PKCEMethodPlain {
+			description := fmt.Sprintf("Unsupported PKCE challenge method (%q).", codeChallengeMethod)
+			h.writeError(w, oauth2.InvalidRequest, description, http.StatusBadRequest)
+			return
+		}
+
+		if len(scopes) == 0 {
+			// per RFC8628 section 3.1, https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
+			// scope is optional but dex requires that it is always at least 'openid' so default it
+			scopes = []string{"openid"}
+		}
+
+		h.Logger.InfoContext(r.Context(), "received device request", "client_id", clientID, "scoped", scopes)
+
+		// Make device code
+		deviceCode := storage.NewDeviceCode()
+
+		// make user code
+		userCode := storage.NewUserCode()
+
+		// Generate the expire time
+		expireTime := time.Now().Add(h.RequestsValidFor)
+
+		// Store the Device Request
+		deviceReq := storage.DeviceRequest{
+			UserCode:     userCode,
+			DeviceCode:   deviceCode,
+			ClientID:     clientID,
+			ClientSecret: clientSecret,
+			Scopes:       scopes,
+			Expiry:       expireTime,
+		}
+
+		if err := h.Storage.CreateDeviceRequest(ctx, deviceReq); err != nil {
+			h.Logger.ErrorContext(r.Context(), "failed to store device request", "err", err)
+			h.writeError(w, oauth2.InvalidRequest, "", http.StatusInternalServerError)
+			return
+		}
+
+		// Store the device token
+		deviceToken := storage.DeviceToken{
+			DeviceCode:          deviceCode,
+			Status:              oauth2.DeviceTokenPending,
+			Expiry:              expireTime,
+			LastRequestTime:     h.Now(),
+			PollIntervalSeconds: 0,
+			PKCE: storage.PKCE{
+				CodeChallenge:       codeChallenge,
+				CodeChallengeMethod: codeChallengeMethod,
+			},
+		}
+
+		if err := h.Storage.CreateDeviceToken(ctx, deviceToken); err != nil {
+			h.Logger.ErrorContext(r.Context(), "failed to store device token", "err", err)
+			h.writeError(w, oauth2.InvalidRequest, "", http.StatusInternalServerError)
+			return
+		}
+
+		u, err := url.Parse(h.IssuerURL.String())
+		if err != nil {
+			h.Logger.ErrorContext(r.Context(), "could not parse issuer URL", "err", err)
+			h.writeError(w, oauth2.InvalidRequest, "", http.StatusInternalServerError)
+			return
+		}
+		u.Path = path.Join(u.Path, "device")
+		vURI := u.String()
+
+		q := u.Query()
+		q.Set("user_code", userCode)
+		u.RawQuery = q.Encode()
+		vURIComplete := u.String()
+
+		code := DeviceCodeResponse{
+			DeviceCode:              deviceCode,
+			UserCode:                userCode,
+			VerificationURI:         vURI,
+			VerificationURIComplete: vURIComplete,
+			ExpireTime:              int(h.RequestsValidFor.Seconds()),
+			PollInterval:            pollIntervalSeconds,
+		}
+
+		// Device Authorization Response can contain cache control header according to
+		// https://tools.ietf.org/html/rfc8628#section-3.2
+		w.Header().Set("Cache-Control", "no-store")
+
+		// Response type should be application/json according to
+		// https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
+		w.Header().Set("Content-Type", "application/json")
+
+		enc := json.NewEncoder(w)
+		enc.SetEscapeHTML(false)
+		enc.SetIndent("", "   ")
+		enc.Encode(code)
+
+	default:
+		h.renderError(r, w, http.StatusBadRequest, "Invalid device code request type")
+		h.writeError(w, oauth2.InvalidRequest, "", http.StatusBadRequest)
+	}
+}
+
+func (h *Handler) verifyUserCode(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	switch r.Method {
+	case http.MethodPost:
+		err := r.ParseForm()
+		if err != nil {
+			h.Logger.Warn("could not parse user code verification request body", "err", err)
+			h.renderError(r, w, http.StatusBadRequest, "")
+			return
+		}
+
+		userCode := r.Form.Get("user_code")
+		if userCode == "" {
+			h.renderError(r, w, http.StatusBadRequest, "No user code received")
+			return
+		}
+
+		userCode = strings.ToUpper(userCode)
+
+		// Find the user code in the available requests
+		deviceRequest, err := h.Storage.GetDeviceRequest(ctx, userCode)
+		if err != nil || h.Now().After(deviceRequest.Expiry) {
+			if err != nil && err != storage.ErrNotFound {
+				h.Logger.ErrorContext(r.Context(), "failed to get device request", "err", err)
+			}
+			if err := h.Templates.Device(r, w, h.getDeviceVerificationURI(), userCode, true); err != nil {
+				h.Logger.ErrorContext(r.Context(), "Server template error", "err", err)
+				h.renderError(r, w, http.StatusNotFound, "Page not found")
+			}
+			return
+		}
+
+		// Redirect to Dex Auth Endpoint
+		u := h.IssuerURL
+		u.Path = path.Join(u.Path, "/auth")
+		q := u.Query()
+		q.Set("client_id", deviceRequest.ClientID)
+		q.Set("client_secret", deviceRequest.ClientSecret)
+		q.Set("state", deviceRequest.UserCode)
+		q.Set("response_type", "code")
+		q.Set("redirect_uri", path.Join(h.IssuerURL.Path, oauth2.DeviceCallbackURI))
+		q.Set("scope", strings.Join(deviceRequest.Scopes, " "))
+		u.RawQuery = q.Encode()
+
+		http.Redirect(w, r, u.String(), http.StatusFound)
+
+	default:
+		h.renderError(r, w, http.StatusBadRequest, "Requested resource does not exist.")
+	}
+}
+
+func (h *Handler) handleDeviceCallback(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	switch r.Method {
+	case http.MethodGet:
+		userCode := r.FormValue("state")
+		code := r.FormValue("code")
+
+		if userCode == "" || code == "" {
+			h.renderError(r, w, http.StatusBadRequest, "Request was missing parameters")
+			return
+		}
+
+		// Authorization redirect callback from OAuth2 auth flow.
+		if errMsg := r.FormValue("error"); errMsg != "" {
+			// Log the error details but don't expose them to the user
+			h.Logger.ErrorContext(r.Context(), "OAuth2 authorization error",
+				"error", errMsg,
+				"error_description", r.FormValue("error_description"))
+			h.renderError(r, w, http.StatusBadRequest, "Authorization failed. Please try again.")
+			return
+		}
+
+		authCode, err := h.Storage.GetAuthCode(ctx, code)
+		if err != nil || h.Now().After(authCode.Expiry) {
+			errCode := http.StatusBadRequest
+			if err != nil && err != storage.ErrNotFound {
+				h.Logger.ErrorContext(r.Context(), "failed to get auth code", "err", err)
+				errCode = http.StatusInternalServerError
+			}
+			h.renderError(r, w, errCode, "Invalid or expired auth code.")
+			return
+		}
+
+		// Grab the device request from storage
+		deviceReq, err := h.Storage.GetDeviceRequest(ctx, userCode)
+		if err != nil || h.Now().After(deviceReq.Expiry) {
+			errCode := http.StatusBadRequest
+			if err != nil && err != storage.ErrNotFound {
+				h.Logger.ErrorContext(r.Context(), "failed to get device code", "err", err)
+				errCode = http.StatusInternalServerError
+			}
+			h.renderError(r, w, errCode, "Invalid or expired user code.")
+			return
+		}
+
+		client, err := h.Storage.GetClient(ctx, deviceReq.ClientID)
+		if err != nil {
+			if err != storage.ErrNotFound {
+				h.Logger.ErrorContext(r.Context(), "failed to get client", "err", err)
+				h.writeError(w, oauth2.ServerError, "", http.StatusInternalServerError)
+			} else {
+				h.writeError(w, oauth2.InvalidClient, "Invalid client credentials.", http.StatusUnauthorized)
+			}
+			return
+		}
+		if client.Secret != deviceReq.ClientSecret {
+			h.writeError(w, oauth2.InvalidClient, "Invalid client credentials.", http.StatusUnauthorized)
+			return
+		}
+
+		resp, err := h.ExchangeAuthCode(ctx, w, authCode, client)
+		if err != nil {
+			h.Logger.ErrorContext(r.Context(), "could not exchange auth code for clien", "client_id", deviceReq.ClientID, "err", err)
+			h.renderError(r, w, http.StatusInternalServerError, "Failed to exchange auth code.")
+			return
+		}
+
+		// Grab the device token from storage
+		old, err := h.Storage.GetDeviceToken(ctx, deviceReq.DeviceCode)
+		if err != nil || h.Now().After(old.Expiry) {
+			errCode := http.StatusBadRequest
+			if err != nil && err != storage.ErrNotFound {
+				h.Logger.ErrorContext(r.Context(), "failed to get device token", "err", err)
+				errCode = http.StatusInternalServerError
+			}
+			h.renderError(r, w, errCode, "Invalid or expired device code.")
+			return
+		}
+
+		updater := func(old storage.DeviceToken) (storage.DeviceToken, error) {
+			if old.Status == oauth2.DeviceTokenComplete {
+				return old, errors.New("device token already complete")
+			}
+			respStr, err := json.MarshalIndent(resp, "", "  ")
+			if err != nil {
+				h.Logger.ErrorContext(r.Context(), "failed to marshal device token response", "err", err)
+				h.renderError(r, w, http.StatusInternalServerError, "")
+				return old, err
+			}
+
+			old.Token = string(respStr)
+			old.Status = oauth2.DeviceTokenComplete
+			return old, nil
+		}
+
+		// Update refresh token in the storage, store the token and mark as complete
+		if err := h.Storage.UpdateDeviceToken(ctx, deviceReq.DeviceCode, updater); err != nil {
+			h.Logger.ErrorContext(r.Context(), "failed to update device token", "err", err)
+			h.renderError(r, w, http.StatusBadRequest, "")
+			return
+		}
+
+		if err := h.Templates.DeviceSuccess(r, w, client.Name); err != nil {
+			h.Logger.ErrorContext(r.Context(), "Server template error", "err", err)
+			h.renderError(r, w, http.StatusNotFound, "Page not found")
+		}
+
+	default:
+		h.Logger.ErrorContext(r.Context(), "unsupported method in device callback", "method", r.Method)
+		h.renderError(r, w, http.StatusBadRequest, "Method not allowed.")
+		return
+	}
+}