Support OAuth device authorization for headless CLI sign-in
- Dominant language
- Go
- Stars
- 368
- Forks
- 44
- Avg merge
- 15h 15m
- Merged PRs (30d)
- 189
Description
## Problem
`hey auth login` currently uses an OAuth authorization-code flow with PKCE and a loopback callback. That works on a desktop, but is awkward or impossible when the CLI runs on a headless server, over SSH, in a container, or inside an agent runtime where no browser can reach the CLI's `127.0.0.1` callback.
`--no-browser` prints the authorization URL, but it still depends on the loopback callback being reachable from the browser environment.
## Request
Please support an OAuth 2.0 Device Authorization Grant (RFC 8628) for the official HEY CLI, exposed as:
```sh
hey auth login --device
```
Suggested user experience:
1. CLI requests a device/user code.
2. CLI displays the verification URL and short user code (and optionally opens the complete verification URL when possible).
3. User approves the request on any browser-capable device.
4. CLI polls the token endpoint, respecting `interval`, `authorization_pending`, `slow_down`, expiry, cancellation, and timeout.
5. CLI stores the resulting access/refresh tokens through the existing credential store.
## Required HEY server/web support
The CLI repository can implement the client and polling behavior, but it cannot implement the HEY website portion. This needs server-side support equivalent to:
- a device authorization endpoint that returns `device_code`, `user_code`, `verification_uri`, optional `verification_uri_complete`, `expires_in`, and `interval`;
- a HEY-hosted verification page where the user signs in, enters/confirms the code, and approves or denies the device request;
- support at `/oauth/tokens` for `grant_type=urn:ietf:params:oauth:grant-type:device_code`;
- RFC 8628 responses including `authorization_pending`, `slow_down`, `access_denied`, and `expired_token`.
The server should bind codes to the existing public CLI client and `install_id`, make user codes short-lived and single-use, rate-limit issuance and verification, and avoid placing access tokens in browser URLs or terminal-visible commands.
## CLI contribution
I can contribute the CLI-side implementation and unit tests with mocked device endpoints. The HEY team would need to confirm endpoint paths and response details, and implement/enable the server and verification-page components.
Contributor guide
Research direction
Start at the existing `hey auth login` flow and credential store, then review how mocked device endpoints can cover device-code responses and polling behavior. Confirm the HEY team’s endpoint paths and response details before implementing; done means `--device` handles pending, slowdown, denial, expiry, cancellation, and timeout cases while storing tokens through the existing credential store.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api, authentication, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100