From 54fe2a388b3a9fa0e7b7b6b4bb51ac458742ed39 Mon Sep 17 00:00:00 2001
From: jordan-extend <jordan@extend.app>
Date: Sun, 23 Aug 2026 08:06:09 -0400
Subject: [PATCH] Fall back to the OAuth device flow when no local browser can
 sign in
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The loopback flow cannot work over SSH or on displayless hosts: the
browser opens elsewhere (or not at all) and the 127.0.0.1 redirect
never comes back. Detect that and switch to the RFC 8628 device flow —
print a one-time code and URL, approve from a browser on any device,
poll the token endpoint for the result. --device forces the flow
explicitly. The endpoint comes only from discovery metadata (RFC 8628
has no conventional path); servers that do not advertise it keep the
loopback behavior.
---
 internal/cli/login.go            | 208 +++++++++++++++++++++-------
 internal/cli/login_test.go       | 209 +++++++++++++++++++++++++++-
 internal/oauth/device.go         | 128 +++++++++++++++++
 internal/oauth/device_test.go    | 227 +++++++++++++++++++++++++++++++
 internal/oauth/discovery.go      |  20 ++-
 internal/oauth/discovery_test.go |  12 +-
 6 files changed, 743 insertions(+), 61 deletions(-)
 create mode 100644 internal/oauth/device.go
 create mode 100644 internal/oauth/device_test.go

diff --git a/internal/cli/login.go b/internal/cli/login.go
index f6935ef..0b6983a 100644
--- a/internal/cli/login.go
+++ b/internal/cli/login.go
@@ -3,6 +3,7 @@ package cli
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -26,6 +27,7 @@ const loginWaitTimeout = 10 * time.Minute
 
 func newLoginDoc(app *App) *CommandDoc {
 	var noBrowser bool
+	var device bool
 	return &CommandDoc{
 		Use:     "login",
 		Summary: "Sign in to Extend through your browser (no API key needed)",
@@ -34,17 +36,25 @@ func newLoginDoc(app *App) *CommandDoc {
 			"log in to the extend cli with my browser",
 			"authenticate the cli without creating an api key",
 			"oauth login for the extend cli",
+			"sign in to extend over ssh or on a headless machine",
 		},
 		WhenToUse: `Use to authenticate interactively without creating an API key: it opens
 your browser, you pick one workspace and one environment on the consent
 screen, and the CLI stores the resulting tokens securely. Prefer an API
 key (EXTEND_API_KEY or 'extend setup') for CI and unattended use; login
-needs a browser once, though the stored session then works headlessly
-until it expires or is revoked.`,
+needs a browser once — on this machine or, with the device flow, on any
+other device — and the stored session then works headlessly until it
+expires or is revoked.`,
 		Details: `The flow is a standard native-app OAuth authorization code grant with
 PKCE: the CLI listens on an ephemeral 127.0.0.1 port, sends you to the
 Extend consent screen, and exchanges the returned code for tokens.
 
+When no usable local browser is detected (an SSH session, or a Linux
+host with no display), login automatically switches to the OAuth device
+flow: it prints a short one-time code and a URL, you approve the
+sign-in from a browser on any device, and the CLI picks the tokens up.
+Pass --device to use that flow explicitly.
+
 Tokens are stored in the OS keychain when one is available, otherwise in
 a 0600 file next to the config file (~/.config/extend/oauth_tokens.json).
 Logins are stored per API base URL, so sessions against different
@@ -59,6 +69,7 @@ config file always wins over a stored login. Run 'extend config' to see
 which source is in effect.`,
 		Examples: []Example{
 			{Label: "Sign in", Cmd: "extend login"},
+			{Label: "Sign in from an SSH session or headless machine", Cmd: "extend login --device"},
 			{Label: "Print the URL instead of opening a browser", Cmd: "extend login --no-browser"},
 			{Label: "Sign in to the EU region", Cmd: "extend login --region eu"},
 		},
@@ -67,18 +78,24 @@ which source is in effect.`,
 			"Each login targets exactly one workspace and one environment, chosen on the consent screen; log in again to switch.",
 			"Logins are keyed by API base URL: switching --region or EXTEND_BASE_URL selects a different stored session (or none).",
 			"With --env <label> set, commands read EXTEND_<LABEL>_API_KEY only and never fall back to the stored login.",
+			"--no-browser prints a URL that only works in a browser on this machine; to approve from another device, use --device.",
 		},
 		SeeAlso: []string{"logout", "whoami", "setup", "auth"},
 		Output:  OutputSpec{TTY: OutputNone, Pipe: OutputNone},
 		Args:    cobra.NoArgs,
 		Configure: func(cmd *cobra.Command) {
 			cmd.Flags().BoolVar(&noBrowser, "no-browser", false, "Print the sign-in URL instead of opening a browser")
+			cmd.Flags().BoolVar(&device, "device", false, "Sign in by approving a one-time code from a browser on any device")
 		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runLogin(cmd.Context(), app, loginOptions{
 				noBrowser:   noBrowser,
+				device:      device,
 				openBrowser: openBrowser,
-				store:       oauth.DefaultStore(),
+				browserUnavailable: func() bool {
+					return browserUnavailable(os.Getenv, runtime.GOOS)
+				},
+				store: oauth.DefaultStore(),
 			})
 		},
 	}
@@ -176,9 +193,16 @@ func runWhoami(ctx context.Context, app *App) error {
 // loginOptions carries the injectable pieces of runLogin so tests can
 // substitute a fake browser and an isolated store.
 type loginOptions struct {
-	noBrowser   bool
+	noBrowser bool
+	// device forces the RFC 8628 device flow instead of the loopback
+	// redirect.
+	device      bool
 	openBrowser func(url string) error
-	store       oauth.Store
+	// browserUnavailable reports that the loopback flow cannot work
+	// here (no local browser), triggering the device-flow fallback.
+	// Nil means a browser is assumed available.
+	browserUnavailable func() bool
+	store              oauth.Store
 }
 
 func runLogin(ctx context.Context, app *App, opts loginOptions) error {
@@ -209,62 +233,34 @@ func runLogin(ctx context.Context, app *App, opts loginOptions) error {
 		return err
 	}
 
-	verifier, err := oauth.NewVerifier()
-	if err != nil {
-		return err
-	}
-	state, err := oauth.NewState()
-	if err != nil {
-		return err
+	tokenClient := &oauth.Client{
+		HTTPClient: authHTTP,
+		Endpoints:  eps,
+		ClientID:   clientID,
+		Resource:   base,
 	}
 
-	lb, err := oauth.NewLoopback(state)
-	if err != nil {
-		return err
+	useDevice := opts.device
+	if opts.device && eps.DeviceAuthorization == "" {
+		return fmt.Errorf("this authorization server does not support device sign-in; run 'extend login' without --device")
+	}
+	if !useDevice && !opts.noBrowser && eps.DeviceAuthorization != "" &&
+		opts.browserUnavailable != nil && opts.browserUnavailable() {
+		fmt.Fprintf(app.IO.ErrOut, "No usable local browser detected; switching to device sign-in.\n\n")
+		useDevice = true
 	}
-	defer lb.Close()
-
-	authURL := oauth.AuthorizeURL(eps.Authorization, oauth.AuthorizeParams{
-		ClientID:    clientID,
-		RedirectURI: lb.RedirectURI(),
-		State:       state,
-		Challenge:   oauth.ChallengeS256(verifier),
-		Resource:    base,
-	})
 
-	if opts.noBrowser {
-		fmt.Fprintf(app.IO.ErrOut, "Open this URL in your browser to sign in:\n\n    %s\n\n", authURL)
-	} else if openErr := opts.openBrowser(authURL); openErr != nil {
-		fmt.Fprintf(app.IO.ErrOut, "%s Could not open a browser (%v).\n", pal.Yellow("!"), openErr)
-		fmt.Fprintf(app.IO.ErrOut, "Open this URL to sign in:\n\n    %s\n\n", authURL)
+	var tr *oauth.TokenResponse
+	if useDevice {
+		tr, err = deviceLogin(ctx, app, tokenClient)
 	} else {
-		fmt.Fprintf(app.IO.ErrOut, "Opening your browser to sign in. If nothing opens, use this URL:\n\n    %s\n\n", authURL)
+		tr, err = loopbackLogin(ctx, app, opts, tokenClient)
 	}
-
-	waitCtx, cancel := context.WithTimeout(ctx, loginWaitTimeout)
-	defer cancel()
-	sp := app.IO.StartSpinner("Waiting for you to approve access in the browser...")
-	code, err := lb.Wait(waitCtx)
 	if err != nil {
-		sp.Stop("")
-		if waitCtx.Err() != nil && ctx.Err() == nil {
-			return fmt.Errorf("timed out waiting for the browser sign-in; run 'extend login' to try again")
-		}
 		return err
 	}
 
-	sp.Update("Completing sign-in...")
-	tokenClient := &oauth.Client{
-		HTTPClient: authHTTP,
-		Endpoints:  eps,
-		ClientID:   clientID,
-		Resource:   base,
-	}
-	tr, err := tokenClient.Exchange(ctx, code, verifier, lb.RedirectURI())
-	if err != nil {
-		sp.Stop("")
-		return fmt.Errorf("exchange authorization code: %w", err)
-	}
+	sp := app.IO.StartSpinner("Completing sign-in...")
 
 	// Captured before the new record lands so the replaced grant can be
 	// revoked server-side; without this every re-login leaves a live
@@ -311,6 +307,116 @@ func runLogin(ctx context.Context, app *App, opts loginOptions) error {
 	return nil
 }
 
+// loopbackLogin runs the RFC 8252 native-app flow: authorization code
+// with PKCE, redirected back to an ephemeral 127.0.0.1 listener. It
+// requires a browser on this machine.
+func loopbackLogin(ctx context.Context, app *App, opts loginOptions, tc *oauth.Client) (*oauth.TokenResponse, error) {
+	pal := paletteFor(app.IO)
+	verifier, err := oauth.NewVerifier()
+	if err != nil {
+		return nil, err
+	}
+	state, err := oauth.NewState()
+	if err != nil {
+		return nil, err
+	}
+
+	lb, err := oauth.NewLoopback(state)
+	if err != nil {
+		return nil, err
+	}
+	defer lb.Close()
+
+	authURL := oauth.AuthorizeURL(tc.Endpoints.Authorization, oauth.AuthorizeParams{
+		ClientID:    tc.ClientID,
+		RedirectURI: lb.RedirectURI(),
+		State:       state,
+		Challenge:   oauth.ChallengeS256(verifier),
+		Resource:    tc.Resource,
+	})
+
+	if opts.noBrowser {
+		fmt.Fprintf(app.IO.ErrOut, "Open this URL in your browser to sign in:\n\n    %s\n\n", authURL)
+	} else if openErr := opts.openBrowser(authURL); openErr != nil {
+		fmt.Fprintf(app.IO.ErrOut, "%s Could not open a browser (%v).\n", pal.Yellow("!"), openErr)
+		fmt.Fprintf(app.IO.ErrOut, "Open this URL to sign in:\n\n    %s\n\n", authURL)
+	} else {
+		fmt.Fprintf(app.IO.ErrOut, "Opening your browser to sign in. If nothing opens, use this URL:\n\n    %s\n\n", authURL)
+	}
+
+	waitCtx, cancel := context.WithTimeout(ctx, loginWaitTimeout)
+	defer cancel()
+	sp := app.IO.StartSpinner("Waiting for you to approve access in the browser...")
+	code, err := lb.Wait(waitCtx)
+	sp.Stop("")
+	if err != nil {
+		if waitCtx.Err() != nil && ctx.Err() == nil {
+			return nil, fmt.Errorf("timed out waiting for the browser sign-in; run 'extend login' to try again")
+		}
+		return nil, err
+	}
+
+	tr, err := tc.Exchange(ctx, code, verifier, lb.RedirectURI())
+	if err != nil {
+		return nil, fmt.Errorf("exchange authorization code: %w", err)
+	}
+	return tr, nil
+}
+
+// deviceLogin runs the RFC 8628 device flow: the CLI shows a one-time
+// code and URL, the user approves the sign-in from a browser on any
+// device, and the CLI polls the token endpoint for the result. No
+// local browser or loopback listener is involved, so it works over
+// SSH and on headless machines.
+func deviceLogin(ctx context.Context, app *App, tc *oauth.Client) (*oauth.TokenResponse, error) {
+	pal := paletteFor(app.IO)
+	da, err := tc.DeviceAuthorize(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("start device sign-in: %w", err)
+	}
+
+	// verification_uri_complete carries the code prefilled; the bare
+	// code is still shown so the user can confirm what the approval
+	// page displays.
+	verifyURL := da.VerificationURIComplete
+	if verifyURL == "" {
+		verifyURL = da.VerificationURI
+	}
+	fmt.Fprintf(app.IO.ErrOut, "Your one-time code is: %s\n\n", pal.Cyan(da.UserCode))
+	fmt.Fprintf(app.IO.ErrOut, "To sign in, open this URL in a browser on any device and confirm the code:\n\n    %s\n\n", verifyURL)
+
+	waitCtx, cancel := context.WithTimeout(ctx, loginWaitTimeout)
+	defer cancel()
+	sp := app.IO.StartSpinner("Waiting for you to approve the sign-in...")
+	tr, err := tc.PollDeviceToken(waitCtx, da)
+	sp.Stop("")
+	if err != nil {
+		var te *oauth.TokenError
+		switch {
+		case errors.As(err, &te) && te.Code == "access_denied":
+			return nil, fmt.Errorf("the sign-in was declined in the browser")
+		case errors.As(err, &te) && te.Code == "expired_token":
+			return nil, fmt.Errorf("the one-time code expired before the sign-in was approved; run 'extend login' to get a new one")
+		case errors.Is(err, context.DeadlineExceeded) && ctx.Err() == nil:
+			return nil, fmt.Errorf("timed out waiting for the sign-in approval; run 'extend login' to try again")
+		}
+		return nil, fmt.Errorf("device sign-in: %w", err)
+	}
+	return tr, nil
+}
+
+// browserUnavailable reports whether the loopback flow is doomed on
+// this machine: in an SSH session or on a displayless Linux host the
+// browser would open elsewhere (or not at all) and the 127.0.0.1
+// redirect could never come back, so login falls back to the device
+// flow instead.
+func browserUnavailable(getenv func(string) string, goos string) bool {
+	if getenv("SSH_CONNECTION") != "" || getenv("SSH_TTY") != "" {
+		return true
+	}
+	return goos == "linux" && getenv("DISPLAY") == "" && getenv("WAYLAND_DISPLAY") == ""
+}
+
 func runLogout(ctx context.Context, app *App, store oauth.Store) error {
 	s := resolveSettings(app.Env, app.Region, app.Workspace, os.Getenv, config.Load)
 	base, err := effectiveBaseURL(s)
diff --git a/internal/cli/login_test.go b/internal/cli/login_test.go
index 117b580..c5fc855 100644
--- a/internal/cli/login_test.go
+++ b/internal/cli/login_test.go
@@ -48,6 +48,18 @@ type fakeAuthServer struct {
 	exchanged string
 	// accessToken overrides the token endpoint's access_token when set.
 	accessToken string
+	// deviceEnabled makes discovery advertise the device authorization
+	// endpoint, like WorkOS does when the grant is enabled for the app.
+	deviceEnabled bool
+	// devicePendingPolls device-grant token calls answer
+	// authorization_pending before tokens are issued.
+	devicePendingPolls int
+	// deviceErr, when set, is the terminal error code for device-grant
+	// token calls.
+	deviceErr string
+	// deviceExchanged records the device_code redeemed at the token
+	// endpoint.
+	deviceExchanged string
 	// revoked records the bearer tokens presented to /oauth/revoke-current.
 	revoked []string
 	// meHandler, when set, serves GET /me; unset answers 404 so tests
@@ -61,14 +73,56 @@ func newFakeAuthServer(t *testing.T) *fakeAuthServer {
 	t.Helper()
 	f := &fakeAuthServer{}
 	mux := http.NewServeMux()
-	mux.HandleFunc("/oauth2/token", func(w http.ResponseWriter, r *http.Request) {
+	mux.HandleFunc("/.well-known/oauth-authorization-server", func(w http.ResponseWriter, r *http.Request) {
+		if !f.deviceEnabled {
+			// Discovery 404s fall back to the default endpoints, the
+			// pre-device-flow behavior most tests run under.
+			http.NotFound(w, r)
+			return
+		}
+		fmt.Fprintf(w, `{"device_authorization_endpoint":"%s/oauth2/device_authorization"}`, f.srv.URL)
+	})
+	mux.HandleFunc("/oauth2/device_authorization", func(w http.ResponseWriter, r *http.Request) {
 		r.ParseForm()
-		if got := r.PostForm.Get("grant_type"); got != "authorization_code" {
-			t.Errorf("grant_type = %q", got)
+		if got := r.PostForm.Get("client_id"); got != oauth.DefaultClientID {
+			t.Errorf("device authorization client_id = %q", got)
+		}
+		if got := r.PostForm.Get("resource"); got != f.srv.URL {
+			t.Errorf("device authorization resource = %q, want %q", got, f.srv.URL)
 		}
+		fmt.Fprintf(w, `{
+			"device_code": "device-code-1",
+			"user_code": "WXYZ-1234",
+			"verification_uri": "%[1]s/device",
+			"verification_uri_complete": "%[1]s/device?user_code=WXYZ-1234",
+			"expires_in": 300,
+			"interval": 1
+		}`, f.srv.URL)
+	})
+	mux.HandleFunc("/oauth2/token", func(w http.ResponseWriter, r *http.Request) {
+		r.ParseForm()
 		if got := r.PostForm.Get("resource"); got != f.srv.URL {
 			t.Errorf("resource = %q, want %q", got, f.srv.URL)
 		}
+		if r.PostForm.Get("grant_type") == oauth.DeviceCodeGrant {
+			if f.devicePendingPolls > 0 {
+				f.devicePendingPolls--
+				w.WriteHeader(http.StatusBadRequest)
+				fmt.Fprint(w, `{"error":"authorization_pending"}`)
+				return
+			}
+			if f.deviceErr != "" {
+				w.WriteHeader(http.StatusBadRequest)
+				fmt.Fprintf(w, `{"error":%q}`, f.deviceErr)
+				return
+			}
+			f.deviceExchanged = r.PostForm.Get("device_code")
+			fmt.Fprint(w, `{"access_token":"eoat_test","refresh_token":"eort_test","token_type":"Bearer","expires_in":3600}`)
+			return
+		}
+		if got := r.PostForm.Get("grant_type"); got != "authorization_code" {
+			t.Errorf("grant_type = %q", got)
+		}
 		if got := r.PostForm.Get("redirect_uri"); got != f.redirectURI {
 			t.Errorf("redirect_uri = %q, want %q", got, f.redirectURI)
 		}
@@ -522,6 +576,155 @@ func TestRunLoginRevokesDifferentConsentGrant(t *testing.T) {
 	}
 }
 
+func TestRunLoginDeviceFlag(t *testing.T) {
+	f := newFakeAuthServer(t)
+	f.deviceEnabled = true
+	f.devicePendingPolls = 1
+	loginTestEnv(t, f.srv.URL)
+	app, stderr := testAppForLogin()
+
+	store := oauth.DefaultStore()
+	err := runLogin(context.Background(), app, loginOptions{
+		device: true,
+		openBrowser: func(string) error {
+			t.Error("openBrowser must not be called for a device sign-in")
+			return nil
+		},
+		store: store,
+	})
+	if err != nil {
+		t.Fatalf("runLogin: %v", err)
+	}
+	if f.deviceExchanged != "device-code-1" {
+		t.Errorf("deviceExchanged = %q, want device-code-1", f.deviceExchanged)
+	}
+	if rec, _ := store.Get(f.srv.URL); rec == nil || rec.AccessToken != "eoat_test" || rec.RefreshToken != "eort_test" {
+		t.Errorf("stored record = %+v, want the device-flow tokens", rec)
+	}
+
+	out := stderr()
+	if !strings.Contains(out, "WXYZ-1234") {
+		t.Errorf("stderr missing the one-time code: %q", out)
+	}
+	if !strings.Contains(out, f.srv.URL+"/device?user_code=WXYZ-1234") {
+		t.Errorf("stderr missing the verification URL: %q", out)
+	}
+	if !strings.Contains(out, "Signed in to "+f.srv.URL) {
+		t.Errorf("stderr missing success line: %q", out)
+	}
+}
+
+func TestRunLoginDeviceFallbackWhenBrowserUnavailable(t *testing.T) {
+	f := newFakeAuthServer(t)
+	f.deviceEnabled = true
+	loginTestEnv(t, f.srv.URL)
+	app, stderr := testAppForLogin()
+
+	store := oauth.DefaultStore()
+	err := runLogin(context.Background(), app, loginOptions{
+		openBrowser: func(string) error {
+			t.Error("openBrowser must not be called when no browser is available")
+			return nil
+		},
+		browserUnavailable: func() bool { return true },
+		store:              store,
+	})
+	if err != nil {
+		t.Fatalf("runLogin: %v", err)
+	}
+	if f.deviceExchanged != "device-code-1" {
+		t.Errorf("deviceExchanged = %q, want the device flow to have run", f.deviceExchanged)
+	}
+	if out := stderr(); !strings.Contains(out, "switching to device sign-in") {
+		t.Errorf("stderr missing the fallback notice: %q", out)
+	}
+}
+
+// Without a device endpoint in discovery, a browserless machine keeps
+// the loopback flow (and its printed URL) rather than failing outright.
+func TestRunLoginBrowserUnavailableWithoutDeviceSupportStaysLoopback(t *testing.T) {
+	f := newFakeAuthServer(t)
+	loginTestEnv(t, f.srv.URL)
+	app, _ := testAppForLogin()
+
+	store := oauth.DefaultStore()
+	err := runLogin(context.Background(), app, loginOptions{
+		openBrowser:        f.browserFor(t, "code-xyz", ""),
+		browserUnavailable: func() bool { return true },
+		store:              store,
+	})
+	if err != nil {
+		t.Fatalf("runLogin: %v", err)
+	}
+	if f.exchanged != "code-xyz" {
+		t.Errorf("exchanged code = %q, want the loopback flow to have run", f.exchanged)
+	}
+}
+
+func TestRunLoginDeviceFlagUnsupportedServer(t *testing.T) {
+	f := newFakeAuthServer(t)
+	loginTestEnv(t, f.srv.URL)
+	app, _ := testAppForLogin()
+
+	err := runLogin(context.Background(), app, loginOptions{
+		device: true,
+		openBrowser: func(string) error {
+			t.Error("openBrowser must not be called")
+			return nil
+		},
+		store: oauth.DefaultStore(),
+	})
+	if err == nil || !strings.Contains(err.Error(), "does not support device sign-in") {
+		t.Fatalf("err = %v, want the unsupported-server error", err)
+	}
+}
+
+func TestRunLoginDeviceDenied(t *testing.T) {
+	f := newFakeAuthServer(t)
+	f.deviceEnabled = true
+	f.deviceErr = "access_denied"
+	loginTestEnv(t, f.srv.URL)
+	app, _ := testAppForLogin()
+
+	store := oauth.DefaultStore()
+	err := runLogin(context.Background(), app, loginOptions{
+		device:      true,
+		openBrowser: func(string) error { return nil },
+		store:       store,
+	})
+	if err == nil || !strings.Contains(err.Error(), "declined") {
+		t.Fatalf("err = %v, want the declined-sign-in error", err)
+	}
+	if rec, _ := store.Get(f.srv.URL); rec != nil {
+		t.Errorf("no tokens must be stored after a declined sign-in, got %+v", rec)
+	}
+}
+
+func TestBrowserUnavailable(t *testing.T) {
+	env := func(vars map[string]string) func(string) string {
+		return func(k string) string { return vars[k] }
+	}
+	cases := []struct {
+		name string
+		vars map[string]string
+		goos string
+		want bool
+	}{
+		{"ssh connection", map[string]string{"SSH_CONNECTION": "1.2.3.4 5 6.7.8.9 22"}, "darwin", true},
+		{"ssh tty", map[string]string{"SSH_TTY": "/dev/pts/0"}, "linux", true},
+		{"linux without display", map[string]string{}, "linux", true},
+		{"linux with X display", map[string]string{"DISPLAY": ":0"}, "linux", false},
+		{"linux with wayland", map[string]string{"WAYLAND_DISPLAY": "wayland-0"}, "linux", false},
+		{"macos desktop", map[string]string{}, "darwin", false},
+		{"windows desktop", map[string]string{}, "windows", false},
+	}
+	for _, tc := range cases {
+		if got := browserUnavailable(env(tc.vars), tc.goos); got != tc.want {
+			t.Errorf("%s: browserUnavailable = %v, want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
 func TestRunWhoami(t *testing.T) {
 	f := newFakeAuthServer(t)
 	f.meHandler = func(w http.ResponseWriter, r *http.Request) {
diff --git a/internal/oauth/device.go b/internal/oauth/device.go
new file mode 100644
index 0000000..3d48bab
--- /dev/null
+++ b/internal/oauth/device.go
@@ -0,0 +1,128 @@
+package oauth
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/extend-hq/extend-cli/internal/iostreams"
+)
+
+// DeviceCodeGrant is the RFC 8628 device_code grant type URN sent to
+// the token endpoint while polling for the user's approval.
+const DeviceCodeGrant = "urn:ietf:params:oauth:grant-type:device_code"
+
+// defaultDevicePollInterval applies when the device authorization
+// response omits interval, per RFC 8628 §3.2.
+const defaultDevicePollInterval = 5 * time.Second
+
+// DeviceAuthorization is the RFC 8628 device authorization response:
+// the code pair and where the user goes to approve the sign-in.
+type DeviceAuthorization struct {
+	DeviceCode              string `json:"device_code"`
+	UserCode                string `json:"user_code"`
+	VerificationURI         string `json:"verification_uri"`
+	VerificationURIComplete string `json:"verification_uri_complete"`
+	ExpiresIn               int64  `json:"expires_in"`
+	Interval                int64  `json:"interval"`
+}
+
+// DeviceAuthorize starts an RFC 8628 device authorization grant. The
+// returned user code and verification URI are shown to the user, who
+// approves the sign-in from a browser on any device; PollDeviceToken
+// then waits for that approval.
+func (c *Client) DeviceAuthorize(ctx context.Context) (*DeviceAuthorization, error) {
+	if c.Endpoints.DeviceAuthorization == "" {
+		return nil, fmt.Errorf("the authorization server does not advertise a device authorization endpoint")
+	}
+	form := url.Values{
+		"client_id": {c.ClientID},
+		"resource":  {c.Resource},
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.Endpoints.DeviceAuthorization, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	resp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return nil, parseTokenError(resp)
+	}
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("read device authorization response: %w", err)
+	}
+	var da DeviceAuthorization
+	if err := json.Unmarshal(body, &da); err != nil {
+		return nil, fmt.Errorf("parse device authorization response: %w", err)
+	}
+	if da.DeviceCode == "" || da.UserCode == "" || da.VerificationURI == "" {
+		return nil, fmt.Errorf("device authorization response missing device_code, user_code, or verification_uri")
+	}
+	// These strings land verbatim on the user's terminal; neutralize
+	// escape sequences at the source like parseTokenError does.
+	da.UserCode = iostreams.SanitizeForTerminal(da.UserCode)
+	da.VerificationURI = iostreams.SanitizeForTerminal(da.VerificationURI)
+	da.VerificationURIComplete = iostreams.SanitizeForTerminal(da.VerificationURIComplete)
+	return &da, nil
+}
+
+// PollDeviceToken polls the token endpoint with the device_code grant
+// until the user approves the sign-in, the code expires, or ctx ends.
+// authorization_pending keeps polling; slow_down backs the interval
+// off by 5s per RFC 8628 §3.5. Any other token error (access_denied,
+// expired_token, ...) is returned as a *TokenError for the caller to
+// present.
+func (c *Client) PollDeviceToken(ctx context.Context, da *DeviceAuthorization) (*TokenResponse, error) {
+	if da.ExpiresIn > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, time.Duration(da.ExpiresIn)*time.Second)
+		defer cancel()
+	}
+	interval := time.Duration(da.Interval) * time.Second
+	if interval <= 0 {
+		interval = defaultDevicePollInterval
+	}
+	form := url.Values{
+		"grant_type":  {DeviceCodeGrant},
+		"device_code": {da.DeviceCode},
+		"client_id":   {c.ClientID},
+		"resource":    {c.Resource},
+	}
+	// First poll fires immediately; approval cannot have happened yet,
+	// but a wasted request is cheaper than always sleeping a full
+	// interval on servers that answer pending instantly.
+	for {
+		tr, err := c.postToken(ctx, form)
+		if err == nil {
+			return tr, nil
+		}
+		var te *TokenError
+		if errors.As(err, &te) {
+			switch te.Code {
+			case "authorization_pending":
+			case "slow_down":
+				interval += 5 * time.Second
+			default:
+				return nil, err
+			}
+		} else {
+			return nil, err
+		}
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(interval):
+		}
+	}
+}
diff --git a/internal/oauth/device_test.go b/internal/oauth/device_test.go
new file mode 100644
index 0000000..0029e9a
--- /dev/null
+++ b/internal/oauth/device_test.go
@@ -0,0 +1,227 @@
+package oauth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// fakeDeviceServer serves the device authorization and token endpoints
+// of the RFC 8628 flow. pendingPolls token calls answer
+// authorization_pending (after an optional slow_down) before the
+// terminal response.
+type fakeDeviceServer struct {
+	srv          *httptest.Server
+	pendingPolls int32
+	slowDowns    int32
+	// tokenErr, when set, is the terminal token-endpoint error code
+	// once the pending polls run out; empty issues tokens.
+	tokenErr string
+	// polls counts token-endpoint calls.
+	polls atomic.Int32
+	// lastForm captures the last token request's form values.
+	lastGrantType  string
+	lastDeviceCode string
+	lastResource   string
+}
+
+func newFakeDeviceServer(t *testing.T) *fakeDeviceServer {
+	t.Helper()
+	f := &fakeDeviceServer{}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/oauth2/device_authorization", func(w http.ResponseWriter, r *http.Request) {
+		r.ParseForm()
+		if got := r.PostForm.Get("client_id"); got != "extend-cli" {
+			t.Errorf("device authorization client_id = %q", got)
+		}
+		fmt.Fprint(w, `{
+			"device_code": "dev-code-1",
+			"user_code": "ABCD-EFGH",
+			"verification_uri": "https://id.example/device",
+			"verification_uri_complete": "https://id.example/device?user_code=ABCD-EFGH",
+			"expires_in": 300,
+			"interval": 0
+		}`)
+	})
+	mux.HandleFunc("/oauth2/token", func(w http.ResponseWriter, r *http.Request) {
+		r.ParseForm()
+		f.polls.Add(1)
+		f.lastGrantType = r.PostForm.Get("grant_type")
+		f.lastDeviceCode = r.PostForm.Get("device_code")
+		f.lastResource = r.PostForm.Get("resource")
+		if atomic.AddInt32(&f.slowDowns, -1) >= 0 {
+			w.WriteHeader(http.StatusBadRequest)
+			fmt.Fprint(w, `{"error":"slow_down"}`)
+			return
+		}
+		if atomic.AddInt32(&f.pendingPolls, -1) >= 0 {
+			w.WriteHeader(http.StatusBadRequest)
+			fmt.Fprint(w, `{"error":"authorization_pending"}`)
+			return
+		}
+		if f.tokenErr != "" {
+			w.WriteHeader(http.StatusBadRequest)
+			fmt.Fprintf(w, `{"error":%q}`, f.tokenErr)
+			return
+		}
+		fmt.Fprint(w, `{"access_token":"eoat_dev","refresh_token":"eort_dev","token_type":"Bearer","expires_in":3600}`)
+	})
+	f.srv = httptest.NewServer(mux)
+	t.Cleanup(f.srv.Close)
+	return f
+}
+
+func (f *fakeDeviceServer) client() *Client {
+	eps := DefaultEndpoints(f.srv.URL)
+	// Not part of the defaults: the device endpoint only ever comes
+	// from discovery metadata.
+	eps.DeviceAuthorization = f.srv.URL + "/oauth2/device_authorization"
+	return &Client{
+		HTTPClient: f.srv.Client(),
+		Endpoints:  eps,
+		ClientID:   "extend-cli",
+		Resource:   "https://api.example",
+	}
+}
+
+// deviceAuth runs DeviceAuthorize and pins the interval to keep the
+// poll loop fast in tests (a zero-interval response defaults to the
+// RFC's 5s otherwise).
+func (f *fakeDeviceServer) deviceAuth(t *testing.T, c *Client) *DeviceAuthorization {
+	t.Helper()
+	da, err := c.DeviceAuthorize(context.Background())
+	if err != nil {
+		t.Fatalf("DeviceAuthorize: %v", err)
+	}
+	da.Interval = 1
+	return da
+}
+
+func TestDeviceAuthorize(t *testing.T) {
+	f := newFakeDeviceServer(t)
+	da, err := f.client().DeviceAuthorize(context.Background())
+	if err != nil {
+		t.Fatalf("DeviceAuthorize: %v", err)
+	}
+	if da.UserCode != "ABCD-EFGH" || da.DeviceCode != "dev-code-1" {
+		t.Errorf("codes = %+v", da)
+	}
+	if da.VerificationURI != "https://id.example/device" {
+		t.Errorf("VerificationURI = %q", da.VerificationURI)
+	}
+	if !strings.Contains(da.VerificationURIComplete, "user_code=ABCD-EFGH") {
+		t.Errorf("VerificationURIComplete = %q", da.VerificationURIComplete)
+	}
+}
+
+func TestDeviceAuthorizeRequiresEndpoint(t *testing.T) {
+	c := &Client{HTTPClient: http.DefaultClient, ClientID: "extend-cli"}
+	if _, err := c.DeviceAuthorize(context.Background()); err == nil {
+		t.Fatal("DeviceAuthorize without an endpoint must fail")
+	}
+}
+
+func TestDeviceAuthorizeSanitizesTerminalOutput(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{
+			"device_code": "dev-code-1",
+			"user_code": "AB\u001b[31mCD",
+			"verification_uri": "https://id.example/device\u001b]0;pwned\u0007"
+		}`)
+	}))
+	t.Cleanup(srv.Close)
+	c := &Client{
+		HTTPClient: srv.Client(),
+		Endpoints:  Endpoints{DeviceAuthorization: srv.URL + "/device"},
+		ClientID:   "extend-cli",
+	}
+	da, err := c.DeviceAuthorize(context.Background())
+	if err != nil {
+		t.Fatalf("DeviceAuthorize: %v", err)
+	}
+	for name, val := range map[string]string{"user_code": da.UserCode, "verification_uri": da.VerificationURI} {
+		if strings.ContainsRune(val, '\x1b') || strings.ContainsRune(val, '\a') {
+			t.Errorf("%s leaked an escape sequence: %q", name, val)
+		}
+	}
+}
+
+func TestPollDeviceTokenSucceedsAfterPending(t *testing.T) {
+	f := newFakeDeviceServer(t)
+	f.pendingPolls = 2
+	c := f.client()
+
+	tr, err := c.PollDeviceToken(context.Background(), f.deviceAuth(t, c))
+	if err != nil {
+		t.Fatalf("PollDeviceToken: %v", err)
+	}
+	if tr.AccessToken != "eoat_dev" || tr.RefreshToken != "eort_dev" {
+		t.Errorf("tokens = %+v", tr)
+	}
+	if got := f.polls.Load(); got != 3 {
+		t.Errorf("token polls = %d, want 3 (2 pending + success)", got)
+	}
+	if f.lastGrantType != DeviceCodeGrant {
+		t.Errorf("grant_type = %q", f.lastGrantType)
+	}
+	if f.lastDeviceCode != "dev-code-1" {
+		t.Errorf("device_code = %q", f.lastDeviceCode)
+	}
+	if f.lastResource != "https://api.example" {
+		t.Errorf("resource = %q", f.lastResource)
+	}
+}
+
+func TestPollDeviceTokenHonorsSlowDown(t *testing.T) {
+	f := newFakeDeviceServer(t)
+	f.slowDowns = 1
+	c := f.client()
+
+	start := time.Now()
+	if _, err := c.PollDeviceToken(context.Background(), f.deviceAuth(t, c)); err != nil {
+		t.Fatalf("PollDeviceToken: %v", err)
+	}
+	// slow_down adds 5s to the 1s test interval, so the success poll
+	// cannot land before ~6s.
+	if elapsed := time.Since(start); elapsed < 5*time.Second {
+		t.Errorf("second poll after %v, want the slow_down-backed interval (>=6s)", elapsed)
+	}
+}
+
+func TestPollDeviceTokenTerminalErrors(t *testing.T) {
+	for _, code := range []string{"access_denied", "expired_token"} {
+		t.Run(code, func(t *testing.T) {
+			f := newFakeDeviceServer(t)
+			f.tokenErr = code
+			c := f.client()
+
+			_, err := c.PollDeviceToken(context.Background(), f.deviceAuth(t, c))
+			var te *TokenError
+			if !errors.As(err, &te) || te.Code != code {
+				t.Fatalf("err = %v, want TokenError %s", err, code)
+			}
+			if got := f.polls.Load(); got != 1 {
+				t.Errorf("token polls = %d, want 1 (terminal errors must stop the loop)", got)
+			}
+		})
+	}
+}
+
+func TestPollDeviceTokenStopsWhenCodeExpires(t *testing.T) {
+	f := newFakeDeviceServer(t)
+	f.pendingPolls = 1000
+	c := f.client()
+
+	da := f.deviceAuth(t, c)
+	da.ExpiresIn = 1
+	_, err := c.PollDeviceToken(context.Background(), da)
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("err = %v, want deadline exceeded once expires_in elapses", err)
+	}
+}
diff --git a/internal/oauth/discovery.go b/internal/oauth/discovery.go
index d5a71f7..27912fd 100644
--- a/internal/oauth/discovery.go
+++ b/internal/oauth/discovery.go
@@ -11,16 +11,22 @@ import (
 	"strings"
 )
 
-// Endpoints holds the three authorization-server endpoints the CLI
-// talks to. All are absolute URLs.
+// Endpoints holds the authorization-server endpoints the CLI talks
+// to. All are absolute URLs.
 type Endpoints struct {
 	Authorization string
 	Token         string
 	Revocation    string
+	// DeviceAuthorization is the RFC 8628 device authorization
+	// endpoint, used when no local browser can run the loopback flow.
+	DeviceAuthorization string
 }
 
 // DefaultEndpoints returns the hardcoded /oauth2/* endpoints for an API
-// base URL. Used directly when RFC 8414 discovery is unavailable.
+// base URL. Used directly when RFC 8414 discovery is unavailable. The
+// device authorization endpoint has no default: RFC 8628 defines no
+// conventional path, so it is only ever taken from discovery metadata
+// and stays empty (device flow unsupported) on fallback.
 func DefaultEndpoints(apiBase string) Endpoints {
 	base := NormalizeBase(apiBase)
 	return Endpoints{
@@ -33,9 +39,10 @@ func DefaultEndpoints(apiBase string) Endpoints {
 // metadata is the subset of the RFC 8414 authorization-server metadata
 // document the CLI consumes.
 type metadata struct {
-	AuthorizationEndpoint string `json:"authorization_endpoint"`
-	TokenEndpoint         string `json:"token_endpoint"`
-	RevocationEndpoint    string `json:"revocation_endpoint"`
+	AuthorizationEndpoint       string `json:"authorization_endpoint"`
+	TokenEndpoint               string `json:"token_endpoint"`
+	RevocationEndpoint          string `json:"revocation_endpoint"`
+	DeviceAuthorizationEndpoint string `json:"device_authorization_endpoint"`
 }
 
 // Discover fetches {apiBase}/.well-known/oauth-authorization-server and
@@ -82,6 +89,7 @@ func Discover(ctx context.Context, client *http.Client, apiBase string) (Endpoin
 		{"authorization_endpoint", m.AuthorizationEndpoint, &out.Authorization},
 		{"token_endpoint", m.TokenEndpoint, &out.Token},
 		{"revocation_endpoint", m.RevocationEndpoint, &out.Revocation},
+		{"device_authorization_endpoint", m.DeviceAuthorizationEndpoint, &out.DeviceAuthorization},
 	} {
 		if ep.val == "" {
 			continue
diff --git a/internal/oauth/discovery_test.go b/internal/oauth/discovery_test.go
index ee544c3..8eb2662 100644
--- a/internal/oauth/discovery_test.go
+++ b/internal/oauth/discovery_test.go
@@ -20,7 +20,8 @@ func TestDiscoverUsesMetadata(t *testing.T) {
 			"issuer": %[1]q,
 			"authorization_endpoint": "%[1]s/custom/authorize",
 			"token_endpoint": "%[1]s/custom/token",
-			"revocation_endpoint": "%[1]s/custom/revoke"
+			"revocation_endpoint": "%[1]s/custom/revoke",
+			"device_authorization_endpoint": "%[1]s/custom/device"
 		}`, srv.URL)
 	}))
 	defer srv.Close()
@@ -38,6 +39,9 @@ func TestDiscoverUsesMetadata(t *testing.T) {
 	if want := srv.URL + "/custom/revoke"; eps.Revocation != want {
 		t.Errorf("Revocation = %q, want %q", eps.Revocation, want)
 	}
+	if want := srv.URL + "/custom/device"; eps.DeviceAuthorization != want {
+		t.Errorf("DeviceAuthorization = %q, want %q", eps.DeviceAuthorization, want)
+	}
 }
 
 func TestDiscoverFallsBackOn404(t *testing.T) {
@@ -55,6 +59,11 @@ func TestDiscoverFallsBackOn404(t *testing.T) {
 	if eps.Authorization != srv.URL+"/oauth2/authorize" {
 		t.Errorf("fallback authorize = %q", eps.Authorization)
 	}
+	// RFC 8628 defines no conventional path, so the fallback must
+	// leave the device endpoint empty (device flow unsupported).
+	if eps.DeviceAuthorization != "" {
+		t.Errorf("fallback device endpoint = %q, want empty", eps.DeviceAuthorization)
+	}
 }
 
 func TestDiscoverFallsBackOnUnreachableServer(t *testing.T) {
@@ -96,6 +105,7 @@ func TestDiscoverRejectsForeignHostEndpoints(t *testing.T) {
 		"foreign token endpoint":     `{"token_endpoint": "https://evil.example/token"}`,
 		"foreign authorize endpoint": `{"authorization_endpoint": "https://evil.example/authorize"}`,
 		"foreign revocation":         `{"revocation_endpoint": "https://evil.example/revoke"}`,
+		"foreign device endpoint":    `{"device_authorization_endpoint": "https://evil.example/device"}`,
 		"same host different port":   `{"token_endpoint": "https://127.0.0.1:1/token"}`,
 	}
 	for name, doc := range cases {