Building GitHub OAuth device flow in a Node.js CLI

#node #github #typescript #cli

When building a CLI tool that needs GitHub access, you have three options:

Ask users to create a personal access token manually (bad UX)
Redirect to a web page (requires a server)
Use the OAuth device flow

The device flow is what the GitHub CLI itself uses. Users run one command, a URL and code appear, they open it in any browser. No server, no copy-pasting tokens. Here's how to implement it cleanly.

The flow in three steps

1. POST /login/device/code
   → returns: device_code, user_code, verification_uri, expires_in, interval

2. Show the user:
   "Open https://github.com/login/device/activate and enter: XXXX-YYYY"

3. Poll POST /login/oauth/access_token every {interval} seconds
   → returns: access_token (when user completes) or error codes (keep polling)

The implementation is ~100 lines. Most of the complexity is in handling the polling responses correctly.

Polling response codes

This is the part most tutorials skip. The responses aren't HTTP errors — they come back as 200 OK with an error field:

type PollResponse =
  | { access_token: string; token_type: string }
  | { error: 'authorization_pending' }   // user hasn't authorized yet — keep polling
  | { error: 'slow_down'; interval: number }  // increase interval by 5s
  | { error: 'expired_token' }           // time's up — restart the flow
  | { error: 'access_denied' }           // user denied — stop

Treating all of these as errors breaks the UX. authorization_pending just means "not yet" — keep the spinner going.

The polling loop

async function pollForToken(deviceCode: string, intervalSecs: number): Promise<string> {
  let interval = intervalSecs;

  while (true) {
    await sleep(interval * 1000);

    const response = await fetch('https://github.com/login/oauth/access_token', {
      method: 'POST',
      headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: CLIENT_ID,
        device_code: deviceCode,
        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
      }),
    });

    const data = await response.json();

    if ('access_token' in data) return data.access_token;
    if (data.error === 'slow_down') interval += 5;
    if (data.error === 'expired_token') throw new Error('Authorization timed out. Run auth login again.');
    if (data.error === 'access_denied') throw new Error('Authorization denied.');
    // authorization_pending: continue loop
  }
}

Token storage

Write to ~/.toolname/config.json and immediately chmod:

import { writeFileSync, chmodSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';

const configPath = join(homedir(), '.releasehub', 'config.json');
writeFileSync(configPath, JSON.stringify({ githubToken: token }), 'utf-8');
chmodSync(configPath, 0o600);  // owner read/write only