basecamp / basecamp/hey-cli

Support OAuth device authorization for headless CLI sign-in

Open
#381 0 comments 3 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.