@moxxy/plugin-oauth 0.0.33

package/src/oauth/browser-flow.ts

@@ -0,0 +1,96 @@
+import { computeCodeChallenge, generateCodeVerifier, generateState } from '../pkce.js';
+import { openInBrowser } from '../open-browser.js';
+import { waitForCallback } from './callback-server.js';
+import { exchangeCodeForToken } from './token-exchange.js';
+import type { OAuthFlowOptions, TokenSet } from './types.js';
+
+export interface BuildAuthUrlInput {
+  readonly authUrl: string;
+  readonly clientId: string;
+  readonly redirectUri: string;
+  readonly scopes: ReadonlyArray<string>;
+  readonly codeChallenge: string;
+  readonly state: string;
+  readonly extraAuthParams?: Readonly<Record<string, string>>;
+}
+
+/** Pure URL builder, exported separately so tests can assert on it. */
+export function buildAuthUrl(input: BuildAuthUrlInput): string {
+  const url = new URL(input.authUrl);
+  url.searchParams.set('client_id', input.clientId);
+  url.searchParams.set('redirect_uri', input.redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('scope', input.scopes.join(' '));
+  url.searchParams.set('state', input.state);
+  url.searchParams.set('code_challenge', input.codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  for (const [k, v] of Object.entries(input.extraAuthParams ?? {})) {
+    url.searchParams.set(k, v);
+  }
+  return url.toString();
+}
+
+/**
+ * Run the full authorization-code-with-PKCE dance:
+ *   1. Bind a loopback HTTP server on `redirectPort`.
+ *   2. Build the auth URL (PKCE challenge, CSRF state, scopes, etc.).
+ *   3. Open the URL in the user's default browser.
+ *   4. Wait for the provider to redirect back with `code` + `state`.
+ *   5. Verify state, POST the code to the token endpoint with the
+ *      verifier, return the parsed token set.
+ */
+export async function runAuthorizationCodeFlow(opts: OAuthFlowOptions): Promise<TokenSet> {
+  const port = opts.redirectPort ?? 8765;
+  const path = opts.redirectPath ?? '/callback';
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = computeCodeChallenge(codeVerifier);
+  const state = generateState();
+  const redirectUri = `http://localhost:${port}${path}`;
+
+  const authUrl = buildAuthUrl({
+    authUrl: opts.authUrl,
+    clientId: opts.clientId,
+    redirectUri,
+    scopes: opts.scopes,
+    codeChallenge,
+    state,
+    ...(opts.extraAuthParams ? { extraAuthParams: opts.extraAuthParams } : {}),
+  });
+
+  // Start the server BEFORE opening the browser — otherwise the user
+  // could complete the consent screen before we're listening and the
+  // redirect would 404.
+  const codePromise = waitForCallback({
+    port,
+    path,
+    expectedState: state,
+    timeoutMs: opts.timeoutMs ?? 300_000,
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+
+  if (opts.onAuthUrl) opts.onAuthUrl(authUrl);
+  if (!opts.noOpen) {
+    try {
+      await openInBrowser(authUrl);
+    } catch {
+      // Failed to open the browser — not fatal; the user can visit
+      // the URL surfaced via onAuthUrl. The loopback server is still
+      // listening.
+    }
+  }
+
+  const code = await codePromise;
+  // Thread the abort signal into the exchange too: a turn cancelled AFTER the
+  // browser redirect arrives but DURING the token POST must cancel the in-flight
+  // fetch, not leak a hung request past the cancel. (waitForCallback already
+  // honours the same signal for the listening phase.)
+  return exchangeCodeForToken({
+    tokenUrl: opts.tokenUrl,
+    code,
+    redirectUri,
+    clientId: opts.clientId,
+    ...(opts.clientSecret ? { clientSecret: opts.clientSecret } : {}),
+    codeVerifier,
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+}

package/src/oauth/callback-server.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import net from 'node:net';
+import { request } from 'node:http';
+import { waitForCallback } from './callback-server';
+
+/** Grab a port that's free right now (best-effort; good enough for a test). */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.once('error', reject);
+    s.listen(0, '127.0.0.1', () => {
+      const port = (s.address() as net.AddressInfo).port;
+      s.close(() => resolve(port));
+    });
+  });
+}
+
+/** GET host:port/path, resolving once the response completes (or rejecting on
+ *  a connection error — e.g. the stack isn't listening). */
+function hit(host: string, port: number, path: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const req = request({ host, port, path, method: 'GET' }, (res) => {
+      res.resume();
+      res.on('end', () => resolve());
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+const tick = (): Promise<void> => new Promise((r) => setTimeout(r, 50));
+
+describe('waitForCallback — dual-stack loopback', () => {
+  it('receives the callback over IPv4 (127.0.0.1)', async () => {
+    const port = await freePort();
+    const pending = waitForCallback({ port, path: '/auth/callback', expectedState: 'S', timeoutMs: 4_000 });
+    await tick(); // let both listeners bind
+    await hit('127.0.0.1', port, '/auth/callback?code=CODE4&state=S');
+    expect(await pending).toBe('CODE4');
+  });
+
+  it('receives the callback over IPv6 (::1) — the Windows `localhost` path', async () => {
+    const port = await freePort();
+    const pending = waitForCallback({ port, path: '/auth/callback', expectedState: 'S', timeoutMs: 4_000 });
+    await tick();
+    // Prefer IPv6 (what Windows hits); fall back to IPv4 only if this host has
+    // no IPv6 loopback, so the test stays green on IPv6-less CI runners.
+    try {
+      await hit('::1', port, '/auth/callback?code=CODE6&state=S');
+    } catch {
+      await hit('127.0.0.1', port, '/auth/callback?code=CODE6&state=S');
+    }
+    expect(await pending).toBe('CODE6');
+  });
+
+  it('rejects a state mismatch (CSRF guard) regardless of stack', async () => {
+    const port = await freePort();
+    const pending = waitForCallback({ port, path: '/auth/callback', expectedState: 'GOOD', timeoutMs: 4_000 });
+    // Attach the rejection assertion BEFORE triggering the callback so the
+    // rejection is never momentarily unhandled.
+    const rejected = expect(pending).rejects.toThrow(/state mismatch/i);
+    await tick();
+    await hit('127.0.0.1', port, '/auth/callback?code=X&state=EVIL');
+    await rejected;
+  });
+
+  it('rejects immediately on an ALREADY-aborted signal — never binds, never blocks', async () => {
+    const port = await freePort();
+    const ac = new AbortController();
+    ac.abort(); // aborted BEFORE the flow starts → the abort event never fires
+    const started = Date.now();
+    // A huge timeout: if the guard were missing it would block for the full
+    // timeout (the abort listener never runs for a pre-aborted signal).
+    await expect(
+      waitForCallback({
+        port,
+        path: '/auth/callback',
+        expectedState: 'S',
+        timeoutMs: 60_000,
+        signal: ac.signal,
+      }),
+    ).rejects.toMatchObject({ code: 'NETWORK_ABORTED' });
+    expect(Date.now() - started).toBeLessThan(1_000);
+    // The port was never bound — a fresh listener can claim it without EADDRINUSE.
+    const second = waitForCallback({ port, path: '/auth/callback', expectedState: 'S', timeoutMs: 2_000 });
+    await tick();
+    await hit('127.0.0.1', port, '/auth/callback?code=AFTER&state=S');
+    expect(await second).toBe('AFTER');
+  });
+});

package/src/oauth/callback-server.ts

@@ -0,0 +1,208 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { MoxxyError } from '@moxxy/sdk';
+
+interface WaitForCallbackOpts {
+  readonly port: number;
+  readonly path: string;
+  readonly expectedState: string;
+  readonly timeoutMs: number;
+  readonly signal?: AbortSignal;
+}
+
+export function waitForCallback(opts: WaitForCallbackOpts): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    // Bind BOTH loopback stacks. The redirect_uri uses `localhost`, which
+    // Windows resolves to `::1` (IPv6) first while macOS/Linux use `127.0.0.1`
+    // (IPv4). A v4-only listener therefore never receives the redirect on
+    // Windows → the login hangs on "waiting for the browser". IPv4 is required;
+    // IPv6 is best-effort (a host without it still works, since there
+    // `localhost` is IPv4 anyway).
+    const servers: Server[] = [];
+    let settled = false;
+    const settle = (fn: () => void): void => {
+      if (settled) return;
+      settled = true;
+      // Single cleanup chokepoint: clear the timeout AND detach the abort
+      // listener on every exit (success/timeout/abort/error), so neither a
+      // dangling timer nor a lingering signal listener is left behind. Guard
+      // each close()/fn() so a Server.close() that throws ERR_SERVER_NOT_RUNNING
+      // (server pushed before its listen completed) can never strand the
+      // remaining servers or skip the resolve/reject.
+      clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onAbort);
+      try {
+        for (const s of servers) {
+          try {
+            s.close();
+          } catch {
+            /* not yet listening — nothing to close */
+          }
+        }
+      } finally {
+        fn();
+      }
+    };
+
+    const timer = setTimeout(() => {
+      settle(() =>
+        reject(
+          new MoxxyError({
+            code: 'OAUTH_FLOW_TIMEOUT',
+            message: `OAuth callback timed out after ${Math.round(opts.timeoutMs / 1000)}s.`,
+            hint: 'Re-run the login command and complete the consent screen before the timeout.',
+            context: { port: opts.port, path: opts.path, timeout_ms: opts.timeoutMs },
+          }),
+        ),
+      );
+    }, opts.timeoutMs);
+    timer.unref?.();
+
+    const onAbort = (): void => {
+      settle(() =>
+        reject(
+          new MoxxyError({
+            code: 'NETWORK_ABORTED',
+            message: 'OAuth flow was aborted.',
+          }),
+        ),
+      );
+    };
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
+
+    // A signal that was ALREADY aborted before entry never fires `abort`, so
+    // the listener above won't run — without this guard we'd bind two HTTP
+    // servers and block for the full timeout, ignoring the cancel. (pollUntil
+    // guards the same case.) settle() detaches the listener and skips binding.
+    if (opts.signal?.aborted) {
+      settle(() =>
+        reject(
+          new MoxxyError({
+            code: 'NETWORK_ABORTED',
+            message: 'OAuth flow was aborted.',
+          }),
+        ),
+      );
+      return;
+    }
+
+    const handleRequest = (req: IncomingMessage, res: ServerResponse): void => {
+      const url = new URL(req.url ?? '/', `http://localhost:${opts.port}`);
+      if (url.pathname !== opts.path) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('not found');
+        return;
+      }
+      const err = url.searchParams.get('error');
+      const errDesc = url.searchParams.get('error_description');
+      if (err) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(htmlPage('OAuth error', `${err}${errDesc ? `: ${errDesc}` : ''}`));
+        const denied = err === 'access_denied';
+        settle(() =>
+          reject(
+            new MoxxyError({
+              code: denied ? 'OAUTH_FLOW_DENIED' : 'AUTH_INVALID',
+              message: denied
+                ? 'You declined the authorization request.'
+                : `Authorization server returned an error: ${err}${errDesc ? ` — ${errDesc}` : ''}.`,
+              ...(denied
+                ? { hint: 'Re-run the login command and approve the consent screen to continue.' }
+                : {}),
+              context: { provider_error: err, ...(errDesc ? { description: errDesc } : {}) },
+            }),
+          ),
+        );
+        return;
+      }
+      const code = url.searchParams.get('code');
+      const returnedState = url.searchParams.get('state');
+      if (!code || !returnedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(htmlPage('OAuth error', 'callback was missing code or state'));
+        settle(() =>
+          reject(
+            new MoxxyError({
+              code: 'AUTH_INVALID',
+              message: 'OAuth callback was missing code or state — the upstream redirect is malformed.',
+              hint: 'Re-run the login command. If this persists, the provider may have rejected the request.',
+            }),
+          ),
+        );
+        return;
+      }
+      if (returnedState !== opts.expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(htmlPage('OAuth error', 'state mismatch — possible CSRF, refusing'));
+        settle(() =>
+          reject(
+            new MoxxyError({
+              code: 'OAUTH_FLOW_STATE_MISMATCH',
+              message: 'OAuth state mismatch — possible CSRF attempt, refusing to continue.',
+              hint:
+                'Make sure no other moxxy login is running at the same time, and re-run the command. ' +
+                'If this keeps happening, your browser or a proxy may be tampering with redirects.',
+            }),
+          ),
+        );
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(htmlPage('Authorized', 'You can close this window — moxxy received the token.'));
+      settle(() => resolve(code));
+    };
+
+    const onFatalError = (e: NodeJS.ErrnoException): void => {
+      if (e.code === 'EADDRINUSE') {
+        settle(() =>
+          reject(
+            new MoxxyError({
+              code: 'OAUTH_FLOW_PORT_BUSY',
+              message: `OAuth callback port ${opts.port} is already in use.`,
+              hint:
+                'Another moxxy login may already be running, or the port is occupied by something else. ' +
+                `Stop the other process, or set a different port for this provider's redirect.`,
+              context: { port: opts.port },
+              cause: e,
+            }),
+          ),
+        );
+        return;
+      }
+      settle(() =>
+        reject(
+          MoxxyError.wrap(e, {
+            code: 'INTERNAL',
+            message: `OAuth callback server failed: ${e.message}`,
+          }),
+        ),
+      );
+    };
+
+    // IPv4 loopback — the required listener; its bind/port errors are fatal.
+    const v4 = createServer(handleRequest);
+    v4.on('error', onFatalError);
+    v4.listen(opts.port, '127.0.0.1');
+    servers.push(v4);
+
+    // IPv6 loopback — Windows resolves `localhost` to ::1 first, so the
+    // redirect lands here. Best-effort: swallow bind errors (host without IPv6,
+    // or ::1 already bound), since the IPv4 listener above is the guaranteed
+    // path and on such hosts `localhost` is IPv4 anyway.
+    const v6 = createServer(handleRequest);
+    v6.on('error', () => undefined);
+    v6.listen(opts.port, '::1');
+    servers.push(v6);
+  });
+}
+
+function htmlPage(title: string, body: string): string {
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>
+<style>body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#111;color:#eee;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100vh;margin:0}h1{font-weight:300}</style>
+</head><body><h1>${escapeHtml(title)}</h1><p>${escapeHtml(body)}</p></body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;',
+  );
+}

package/src/oauth/device-flow-shared.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import {
+  classifyDeviceTokenResponse,
+  requestDeviceAuthorization,
+} from './device-flow-shared.js';
+
+/** RFC 8628 §3.5 state machine — the throwing branches were previously
+ *  untested, so a regression in the error-code mapping would ship silently. */
+describe('classifyDeviceTokenResponse', () => {
+  const ok = { ok: true, status: 200 };
+  const bad = { ok: false, status: 400 };
+
+  it('returns {done} with a parsed TokenSet on success', () => {
+    const state = { intervalMs: 5000 };
+    const outcome = classifyDeviceTokenResponse(
+      ok,
+      { access_token: 'at-1', refresh_token: 'rt-1', token_type: 'Bearer', expires_in: 3600 },
+      state,
+    );
+    expect('done' in outcome).toBe(true);
+    if ('done' in outcome) {
+      expect(outcome.done.accessToken).toBe('at-1');
+    }
+  });
+
+  it('authorization_pending → keep polling, interval unchanged', () => {
+    const state = { intervalMs: 5000 };
+    const outcome = classifyDeviceTokenResponse(bad, { error: 'authorization_pending' }, state);
+    expect(outcome).toEqual({ pending: true });
+    expect(state.intervalMs).toBe(5000);
+  });
+
+  it('slow_down → pending and bumps the interval by exactly 5000ms', () => {
+    const state = { intervalMs: 5000 };
+    const outcome = classifyDeviceTokenResponse(bad, { error: 'slow_down' }, state);
+    expect(outcome).toEqual({ pending: true });
+    expect(state.intervalMs).toBe(10000);
+  });
+
+  it('access_denied → throws OAUTH_FLOW_DENIED', () => {
+    const state = { intervalMs: 5000 };
+    try {
+      classifyDeviceTokenResponse(bad, { error: 'access_denied' }, state);
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(MoxxyError);
+      expect((err as MoxxyError).code).toBe('OAUTH_FLOW_DENIED');
+    }
+  });
+
+  it('expired_token → throws OAUTH_FLOW_TIMEOUT', () => {
+    const state = { intervalMs: 5000 };
+    try {
+      classifyDeviceTokenResponse(bad, { error: 'expired_token' }, state);
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(MoxxyError);
+      expect((err as MoxxyError).code).toBe('OAUTH_FLOW_TIMEOUT');
+    }
+  });
+
+  it('generic error → throws AUTH_INVALID with the provider_error in context', () => {
+    const state = { intervalMs: 5000 };
+    try {
+      classifyDeviceTokenResponse(
+        bad,
+        { error: 'invalid_grant', error_description: 'bad code' },
+        state,
+      );
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(MoxxyError);
+      const e = err as MoxxyError;
+      expect(e.code).toBe('AUTH_INVALID');
+      expect(e.context?.provider_error).toBe('invalid_grant');
+      expect(e.context?.description).toBe('bad code');
+    }
+  });
+
+  it('non-ok with no error field → AUTH_INVALID keyed by the HTTP status', () => {
+    const state = { intervalMs: 5000 };
+    try {
+      classifyDeviceTokenResponse({ ok: false, status: 503 }, {}, state);
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(MoxxyError);
+      const e = err as MoxxyError;
+      expect(e.code).toBe('AUTH_INVALID');
+      expect(e.context?.provider_error).toBe('HTTP 503');
+    }
+  });
+});
+
+describe('requestDeviceAuthorization — malformed 2xx body', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  const args = {
+    deviceUrl: 'https://idp.example/device',
+    clientId: 'cid',
+    scopes: ['openid'],
+  };
+
+  it('maps a non-JSON 200 body to PROVIDER_UNKNOWN_RESPONSE (not a raw SyntaxError)', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new SyntaxError('Unexpected token < in JSON at position 0');
+        },
+        text: async () => '<html>proxy error</html>',
+      })),
+    );
+    let err: unknown;
+    try {
+      await requestDeviceAuthorization(args);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    expect((err as MoxxyError).code).toBe('PROVIDER_UNKNOWN_RESPONSE');
+  });
+
+  it('still rejects with PROVIDER_UNKNOWN_RESPONSE when required fields are absent', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({
+        ok: true,
+        status: 200,
+        json: async () => ({ user_code: 'ABC' }), // missing device_code + verification_uri
+        text: async () => '',
+      })),
+    );
+    await expect(requestDeviceAuthorization(args)).rejects.toMatchObject({
+      code: 'PROVIDER_UNKNOWN_RESPONSE',
+    });
+  });
+});

package/src/oauth/device-flow-shared.ts

@@ -0,0 +1,129 @@
+import { classifyHttpStatus, MoxxyError } from '@moxxy/sdk';
+import { parseTokenResponse } from './token-exchange.js';
+import type { PollOutcome } from './poll-until.js';
+import type { TokenSet } from './types.js';
+
+/**
+ * Parsed RFC 8628 device-authorization response. Times are kept in seconds (as
+ * the wire reports them); callers convert to ms where their API needs it.
+ */
+export interface DeviceAuthorization {
+  readonly deviceCode: string;
+  readonly userCode: string;
+  readonly verificationUri: string;
+  readonly verificationUriComplete?: string;
+  readonly expiresInSec: number;
+  readonly intervalSec: number;
+}
+
+/**
+ * POST the RFC 8628 device-authorization request and parse the response. The
+ * single home for the request + field parsing + error handling shared by the
+ * legacy `runDeviceCodeFlow` and the `rfc8628DeviceFlow` adapter.
+ */
+export async function requestDeviceAuthorization(args: {
+  readonly deviceUrl: string;
+  readonly clientId: string;
+  readonly scopes: ReadonlyArray<string>;
+  readonly signal?: AbortSignal;
+}): Promise<DeviceAuthorization> {
+  const body = new URLSearchParams();
+  body.set('client_id', args.clientId);
+  body.set('scope', args.scopes.join(' '));
+  const res = await fetch(args.deviceUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+    ...(args.signal ? { signal: args.signal } : {}),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw (
+      classifyHttpStatus(res.status, { url: args.deviceUrl, body: text }) ??
+      new MoxxyError({
+        code: 'AUTH_INVALID',
+        message: `device-code request failed (HTTP ${res.status}): ${text.slice(0, 300)}`,
+        context: { status: res.status, url: args.deviceUrl },
+      })
+    );
+  }
+  // A 200 with a non-JSON/truncated body (proxy/captive-portal error page)
+  // would make res.json() reject with a raw SyntaxError that escapes the
+  // MoxxyError boundary; convert it to a typed PROVIDER_UNKNOWN_RESPONSE.
+  const json = (await res.json().catch(() => {
+    throw new MoxxyError({
+      code: 'PROVIDER_UNKNOWN_RESPONSE',
+      message: 'device-authorization endpoint returned a non-JSON success body',
+      context: { url: args.deviceUrl },
+    });
+  })) as Record<string, unknown>;
+  const deviceCode = typeof json.device_code === 'string' ? json.device_code : null;
+  const userCode = typeof json.user_code === 'string' ? json.user_code : null;
+  const verificationUri =
+    typeof json.verification_uri === 'string'
+      ? json.verification_uri
+      : typeof json.verification_url === 'string'
+        ? json.verification_url
+        : null;
+  const verificationUriComplete =
+    typeof json.verification_uri_complete === 'string' ? json.verification_uri_complete : undefined;
+  const expiresInSec = typeof json.expires_in === 'number' ? json.expires_in : 600;
+  const intervalSec = typeof json.interval === 'number' ? json.interval : 5;
+  if (!deviceCode || !userCode || !verificationUri) {
+    throw new MoxxyError({
+      code: 'PROVIDER_UNKNOWN_RESPONSE',
+      message: `device-code response missing required fields: ${JSON.stringify(json).slice(0, 200)}`,
+    });
+  }
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    ...(verificationUriComplete ? { verificationUriComplete } : {}),
+    expiresInSec,
+    intervalSec,
+  };
+}
+
+/**
+ * Classify a device-flow token-poll response per RFC 8628 §3.5: success →
+ * `done`; `authorization_pending` → keep waiting; `slow_down` → +5s and wait;
+ * `access_denied` / `expired_token` / other → throw a MoxxyError. Shared by both
+ * poll loops; each caller builds its own request body (the legacy flow appends
+ * client_id/client_secret) and hands the response + parsed JSON here.
+ */
+export function classifyDeviceTokenResponse(
+  res: { readonly ok: boolean; readonly status: number },
+  json: Record<string, unknown>,
+  state: { intervalMs: number },
+): PollOutcome<TokenSet> {
+  if (res.ok && typeof json.access_token === 'string') {
+    return { done: parseTokenResponse(json) };
+  }
+  const err = typeof json.error === 'string' ? json.error : `HTTP ${res.status}`;
+  if (err === 'authorization_pending') return { pending: true };
+  if (err === 'slow_down') {
+    state.intervalMs += 5000;
+    return { pending: true };
+  }
+  if (err === 'access_denied') {
+    throw new MoxxyError({
+      code: 'OAUTH_FLOW_DENIED',
+      message: 'You declined the device authorization.',
+      hint: 'Re-run the login command and approve the consent screen on your browser device.',
+    });
+  }
+  if (err === 'expired_token') {
+    throw new MoxxyError({
+      code: 'OAUTH_FLOW_TIMEOUT',
+      message: 'The device code expired before you finished signing in.',
+      hint: 'Re-run the login command — a new code will be generated.',
+    });
+  }
+  const desc = typeof json.error_description === 'string' ? json.error_description : '';
+  throw new MoxxyError({
+    code: 'AUTH_INVALID',
+    message: `OAuth device flow failed: ${err}${desc ? ` — ${desc}` : ''}.`,
+    context: { provider_error: String(err), ...(desc ? { description: desc } : {}) },
+  });
+}