@moxxy/plugin-oauth 0.0.33

package/src/oauth/token-exchange.ts

@@ -0,0 +1,169 @@
+import { classifyHttpStatus, MoxxyError } from '@moxxy/sdk';
+import type { TokenSet } from './types.js';
+
+interface ExchangeCodeInput {
+  readonly tokenUrl: string;
+  readonly code: string;
+  readonly redirectUri: string;
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly codeVerifier: string;
+  /** Abort the exchange fetch when the caller's flow is cancelled. */
+  readonly signal?: AbortSignal;
+}
+
+export async function exchangeCodeForToken(
+  input: ExchangeCodeInput,
+  fetchImpl: typeof fetch = fetch,
+): Promise<TokenSet> {
+  const body = new URLSearchParams();
+  body.set('grant_type', 'authorization_code');
+  body.set('code', input.code);
+  body.set('redirect_uri', input.redirectUri);
+  body.set('client_id', input.clientId);
+  body.set('code_verifier', input.codeVerifier);
+  if (input.clientSecret) body.set('client_secret', input.clientSecret);
+  const res = await fetchImpl(input.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+    ...(input.signal ? { signal: input.signal } : {}),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw (
+      classifyHttpStatus(res.status, { url: input.tokenUrl, body: text }) ??
+      new MoxxyError({
+        code: 'AUTH_INVALID',
+        message: `Token exchange failed (HTTP ${res.status})${errorSummary(text)}`,
+        context: { status: res.status, url: input.tokenUrl, ...bodyContext(text) },
+      })
+    );
+  }
+  const json = await parseJsonBody(res, input.tokenUrl);
+  return parseTokenResponse(json);
+}
+
+/**
+ * Build a human-message suffix from a token-endpoint error body. Token
+ * endpoints return `{error, error_description}` (RFC 6749 §5.2); prefer those
+ * structured fields verbatim. For an opaque/HTML body (proxy/captive-portal
+ * error page) — provider/attacker-influenced text that flows to logs and can
+ * reach the model — emit nothing in the human message; the bounded raw body
+ * still lands in `context` via {@link bodyContext}.
+ */
+function errorSummary(body: string): string {
+  const fields = parseOauthError(body);
+  if (!fields) return '';
+  const { error, error_description } = fields;
+  const detail = error_description ?? error;
+  return detail ? `: ${detail.slice(0, 300)}` : '';
+}
+
+/** Truncated raw body for the error context only (never the human message). */
+function bodyContext(body: string): Record<string, string> {
+  return body ? { body: body.slice(0, 200) } : {};
+}
+
+function parseOauthError(body: string): { error?: string; error_description?: string } | null {
+  if (!body) return null;
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (!parsed || typeof parsed !== 'object') return null;
+    const obj = parsed as Record<string, unknown>;
+    const error = typeof obj.error === 'string' ? obj.error : undefined;
+    const error_description =
+      typeof obj.error_description === 'string' ? obj.error_description : undefined;
+    if (!error && !error_description) return null;
+    return {
+      ...(error !== undefined ? { error } : {}),
+      ...(error_description !== undefined ? { error_description } : {}),
+    };
+  } catch {
+    return null; // opaque / HTML body — don't reflect it into the message
+  }
+}
+
+/**
+ * Parse a 2xx token-endpoint body as JSON. A provider (or an intercepting
+ * proxy / captive portal / load-balancer error page) can return HTTP 200 with
+ * a non-JSON or truncated body; an unguarded `res.json()` would reject with a
+ * native SyntaxError that escapes the MoxxyError boundary (no code/hint, and
+ * `isAuthRejection` can't classify it). Convert it to a typed error instead.
+ */
+async function parseJsonBody(res: { json(): Promise<unknown> }, url: string): Promise<Record<string, unknown>> {
+  return (await res.json().catch(() => {
+    throw new MoxxyError({
+      code: 'PROVIDER_UNKNOWN_RESPONSE',
+      message: 'token endpoint returned a non-JSON success body',
+      context: { url },
+    });
+  })) as Record<string, unknown>;
+}
+
+/**
+ * Refresh an access token using a stored refresh_token. Same token
+ * endpoint, different grant_type. Returns a new TokenSet — note that
+ * providers MAY or MAY NOT rotate the refresh_token (Google does
+ * not; Auth0 with rotation does). Caller should preserve the prior
+ * refresh_token if the response omits one.
+ */
+export async function refreshAccessToken(
+  input: {
+    readonly tokenUrl: string;
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly refreshToken: string;
+  },
+  fetchImpl: typeof fetch = fetch,
+): Promise<TokenSet> {
+  const body = new URLSearchParams();
+  body.set('grant_type', 'refresh_token');
+  body.set('refresh_token', input.refreshToken);
+  body.set('client_id', input.clientId);
+  if (input.clientSecret) body.set('client_secret', input.clientSecret);
+  const res = await fetchImpl(input.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    // 401/403 here typically means the refresh_token was revoked/expired —
+    // classifyHttpStatus maps those to AUTH_INVALID/AUTH_DENIED. Surface a
+    // refresh-specific fallback for the unmapped statuses.
+    throw (
+      classifyHttpStatus(res.status, { url: input.tokenUrl, body: text }) ??
+      new MoxxyError({
+        code: 'AUTH_EXPIRED',
+        message: `Token refresh failed (HTTP ${res.status})${errorSummary(text)}`,
+        context: { status: res.status, url: input.tokenUrl, ...bodyContext(text) },
+      })
+    );
+  }
+  const json = await parseJsonBody(res, input.tokenUrl);
+  return parseTokenResponse(json);
+}
+
+export function parseTokenResponse(json: Record<string, unknown>): TokenSet {
+  const access = typeof json.access_token === 'string' ? json.access_token : null;
+  if (!access) {
+    throw new MoxxyError({
+      code: 'PROVIDER_UNKNOWN_RESPONSE',
+      message: `token response missing access_token: ${JSON.stringify(json).slice(0, 200)}`,
+    });
+  }
+  const refresh = typeof json.refresh_token === 'string' ? json.refresh_token : undefined;
+  const expiresIn = typeof json.expires_in === 'number' ? json.expires_in : null;
+  const scope = typeof json.scope === 'string' ? json.scope : undefined;
+  const tokenType = typeof json.token_type === 'string' ? json.token_type : 'Bearer';
+  const idToken = typeof json.id_token === 'string' ? json.id_token : undefined;
+  return {
+    accessToken: access,
+    ...(refresh !== undefined ? { refreshToken: refresh } : {}),
+    ...(expiresIn != null ? { expiresAt: Date.now() + expiresIn * 1000 } : {}),
+    ...(scope !== undefined ? { scope } : {}),
+    tokenType,
+    ...(idToken !== undefined ? { idToken } : {}),
+  };
+}

package/src/oauth/types.ts

@@ -0,0 +1,92 @@
+export interface OAuthFlowOptions {
+  /** Provider's authorization endpoint, e.g. https://accounts.google.com/o/oauth2/v2/auth */
+  readonly authUrl: string;
+  /** Provider's token endpoint, e.g. https://oauth2.googleapis.com/token */
+  readonly tokenUrl: string;
+  readonly clientId: string;
+  /** Confidential clients only; loopback flows usually omit. */
+  readonly clientSecret?: string;
+  readonly scopes: ReadonlyArray<string>;
+  /**
+   * Loopback redirect port. The redirect URI MUST be registered with
+   * the provider exactly (most providers require an exact match) — pick
+   * a value and tell the user to register it. Default 8765 to keep the
+   * Google Cloud Console setup deterministic across sessions.
+   */
+  readonly redirectPort?: number;
+  /**
+   * Loopback redirect path. Default `/callback`. Some providers reject
+   * paths other than `/`; tweak per provider. The full registered
+   * redirect URI must be `http://localhost:<port><path>` exactly.
+   */
+  readonly redirectPath?: string;
+  /**
+   * Provider-specific extra query parameters on the auth URL. Common
+   * cases: `access_type=offline` + `prompt=consent` for Google (forces
+   * the issuance of a refresh_token); `audience=...` for Auth0.
+   */
+  readonly extraAuthParams?: Readonly<Record<string, string>>;
+  /** How long to wait for the callback before giving up. Default 5min. */
+  readonly timeoutMs?: number;
+  /**
+   * Abort signal — when fired, shuts the local server and rejects the
+   * flow. Wire from `ctx.signal` so a turn cancel kills a pending auth.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * When true, do NOT auto-open the browser. The auth URL still
+   * gets handed to `onAuthUrl`; the caller is expected to print it
+   * for the user to visit on a host where the loopback callback is
+   * reachable (same machine, SSH tunnel, port-forward).
+   */
+  readonly noOpen?: boolean;
+  /**
+   * Fires with the built auth URL just before the browser-open step.
+   * Use to log / display the URL so the user sees it even when
+   * auto-open fails or `noOpen` is set.
+   */
+  readonly onAuthUrl?: (url: string) => void;
+}
+
+export interface DeviceFlowOptions {
+  /** Provider's device-authorization endpoint (RFC 8628 §3.1). */
+  readonly deviceUrl: string;
+  readonly tokenUrl: string;
+  readonly clientId: string;
+  readonly clientSecret?: string;
+  readonly scopes: ReadonlyArray<string>;
+  /** Hard cap; the device-code's own expires_in usually drives the timer. */
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  /**
+   * Fired ONCE with the user-facing prompt info as soon as the
+   * device endpoint returns. Channels should surface this prominently
+   * — the whole flow stalls until the user finishes on the URL.
+   */
+  readonly onPrompt: (info: DevicePrompt) => void;
+}
+
+export interface DevicePrompt {
+  /** Short code the user types into the verification page. */
+  readonly userCode: string;
+  /** URL the user opens on any device. */
+  readonly verificationUri: string;
+  /** Some providers return a URL that already includes the user_code. */
+  readonly verificationUriComplete?: string;
+  /** Seconds until the device_code expires (from the provider). */
+  readonly expiresIn: number;
+  /** Poll interval the provider wants us to use, in seconds. */
+  readonly interval: number;
+}
+
+export interface TokenSet {
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  /** Epoch ms when the access_token expires. */
+  readonly expiresAt?: number;
+  /** Granted scopes — provider may grant less than requested. */
+  readonly scope?: string;
+  readonly tokenType: string;
+  /** OIDC id_token if the provider returned one (Google does for `openid` scope). */
+  readonly idToken?: string;
+}

package/src/oauth.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import {
+  buildAuthUrl,
+  buildOauthAuthorizeTool,
+  buildOauthClearTool,
+  buildOauthGetTokenTool,
+  computeCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+  validateProvider,
+} from './index.js';
+
+const noopLogger = { debug() {}, info() {}, warn() {}, error() {} };
+const fakeCtx = {
+  signal: new AbortController().signal,
+  logger: noopLogger,
+} as never;
+
+describe('@moxxy/plugin-oauth', () => {
+  describe('PKCE primitives', () => {
+    it('verifier is 43-128 chars and url-safe (RFC 7636 §4.1)', () => {
+      for (let i = 0; i < 20; i += 1) {
+        const v = generateCodeVerifier();
+        expect(v.length).toBeGreaterThanOrEqual(43);
+        expect(v.length).toBeLessThanOrEqual(128);
+        expect(v).toMatch(/^[A-Za-z0-9_-]+$/);
+      }
+    });
+
+    it('challenge is S256(verifier) base64url-encoded', () => {
+      // RFC 7636 §B.1 worked example
+      const verifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
+      const challenge = computeCodeChallenge(verifier);
+      expect(challenge).toBe('E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM');
+    });
+
+    it('state is high-entropy and url-safe', () => {
+      const a = generateState();
+      const b = generateState();
+      expect(a).not.toBe(b);
+      expect(a).toMatch(/^[A-Za-z0-9_-]+$/);
+      expect(a.length).toBeGreaterThanOrEqual(20);
+    });
+  });
+
+  describe('buildAuthUrl', () => {
+    it('includes all required OAuth + PKCE params', () => {
+      const url = buildAuthUrl({
+        authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+        clientId: 'ABC.apps.googleusercontent.com',
+        redirectUri: 'http://localhost:8765/callback',
+        scopes: ['openid', 'email', 'profile'],
+        codeChallenge: 'XYZ',
+        state: 'STATE',
+      });
+      const parsed = new URL(url);
+      expect(parsed.searchParams.get('client_id')).toBe('ABC.apps.googleusercontent.com');
+      expect(parsed.searchParams.get('redirect_uri')).toBe('http://localhost:8765/callback');
+      expect(parsed.searchParams.get('response_type')).toBe('code');
+      expect(parsed.searchParams.get('scope')).toBe('openid email profile');
+      expect(parsed.searchParams.get('code_challenge')).toBe('XYZ');
+      expect(parsed.searchParams.get('code_challenge_method')).toBe('S256');
+      expect(parsed.searchParams.get('state')).toBe('STATE');
+    });
+
+    it('merges extraAuthParams (Google offline access)', () => {
+      const url = buildAuthUrl({
+        authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+        clientId: 'X',
+        redirectUri: 'http://localhost:8765/callback',
+        scopes: ['email'],
+        codeChallenge: 'C',
+        state: 'S',
+        extraAuthParams: { access_type: 'offline', prompt: 'consent' },
+      });
+      const parsed = new URL(url);
+      expect(parsed.searchParams.get('access_type')).toBe('offline');
+      expect(parsed.searchParams.get('prompt')).toBe('consent');
+    });
+  });
+
+  describe('provider validation', () => {
+    it('accepts lowercase ids with . _ -', () => {
+      expect(() => validateProvider('google')).not.toThrow();
+      expect(() => validateProvider('google.workspace')).not.toThrow();
+      expect(() => validateProvider('github-enterprise')).not.toThrow();
+      expect(() => validateProvider('my_provider_42')).not.toThrow();
+    });
+
+    it('rejects uppercase / spaces / slashes', () => {
+      expect(() => validateProvider('Google')).toThrow();
+      expect(() => validateProvider('google workspace')).toThrow();
+      expect(() => validateProvider('google/workspace')).toThrow();
+    });
+  });
+
+  describe('tool schemas', () => {
+    const noopDeps = { vault: {} as never };
+
+    it('authorize requires tokenUrl, scopes, clientId, provider', () => {
+      const tool = buildOauthAuthorizeTool(noopDeps);
+      expect(
+        tool.inputSchema.safeParse({
+          provider: 'google',
+          authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+          tokenUrl: 'https://oauth2.googleapis.com/token',
+          clientId: 'X',
+          scopes: ['email'],
+        }).success,
+      ).toBe(true);
+      expect(tool.inputSchema.safeParse({ provider: 'google' }).success).toBe(false);
+    });
+
+    it('authorize accepts mode=device', () => {
+      const tool = buildOauthAuthorizeTool(noopDeps);
+      expect(
+        tool.inputSchema.safeParse({
+          provider: 'google',
+          deviceUrl: 'https://oauth2.googleapis.com/device/code',
+          tokenUrl: 'https://oauth2.googleapis.com/token',
+          clientId: 'X',
+          scopes: ['email'],
+          mode: 'device',
+        }).success,
+      ).toBe(true);
+    });
+
+    it('get_token has includeRefresh opt-in', () => {
+      const tool = buildOauthGetTokenTool(noopDeps);
+      expect(
+        tool.inputSchema.safeParse({ provider: 'google', includeRefresh: true }).success,
+      ).toBe(true);
+    });
+
+    it('clear requires provider', () => {
+      const tool = buildOauthClearTool(noopDeps);
+      expect(tool.inputSchema.safeParse({ provider: 'google' }).success).toBe(true);
+      expect(tool.inputSchema.safeParse({}).success).toBe(false);
+    });
+  });
+
+  describe('authorize input validation', () => {
+    const deps = { vault: {} as never };
+
+    it('throws a TOOL_ERROR MoxxyError when mode=device is missing deviceUrl', async () => {
+      const tool = buildOauthAuthorizeTool(deps);
+      const err = await Promise.resolve()
+        .then(() => tool.handler({ provider: 'google', clientId: 'X', scopes: ['email'], tokenUrl: 'https://t', mode: 'device' }, fakeCtx))
+        .catch((e) => e);
+      expect(MoxxyError.isMoxxyError(err)).toBe(true);
+      expect((err as MoxxyError).code).toBe('TOOL_ERROR');
+      expect((err as MoxxyError).message).toMatch(/deviceUrl/);
+    });
+
+    it('throws a TOOL_ERROR MoxxyError when mode=loopback is missing authUrl', async () => {
+      const tool = buildOauthAuthorizeTool(deps);
+      const err = await Promise.resolve()
+        .then(() => tool.handler({ provider: 'google', clientId: 'X', scopes: ['email'], tokenUrl: 'https://t' }, fakeCtx))
+        .catch((e) => e);
+      expect(MoxxyError.isMoxxyError(err)).toBe(true);
+      expect((err as MoxxyError).code).toBe('TOOL_ERROR');
+      expect((err as MoxxyError).message).toMatch(/authUrl/);
+    });
+  });
+
+  describe('end-to-end chain', () => {
+    it('exposes the three tools needed for OAuth → MCP wiring', () => {
+      const deps = { vault: {} as never };
+      const tools = [
+        buildOauthAuthorizeTool(deps),
+        buildOauthGetTokenTool(deps),
+        buildOauthClearTool(deps),
+      ];
+      expect(tools.map((t) => t.name).sort()).toEqual([
+        'oauth_authorize',
+        'oauth_clear_token',
+        'oauth_get_token',
+      ]);
+      for (const tool of tools) {
+        expect(tool.permission?.action).toBe('prompt');
+      }
+    });
+  });
+});

package/src/open-browser-spawn.test.ts

@@ -0,0 +1,69 @@
+import { EventEmitter } from 'node:events';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// Mock node:child_process so we can drive spawn's error/success timing
+// deterministically without launching a real browser opener.
+const spawnMock = vi.fn();
+vi.mock('node:child_process', () => ({
+  spawn: (...args: unknown[]) => spawnMock(...args),
+}));
+
+// Imported AFTER the mock is registered.
+const { openInBrowser } = await import('./open-browser.js');
+
+interface FakeChild extends EventEmitter {
+  unref: () => void;
+}
+
+function fakeChild(): FakeChild {
+  const ee = new EventEmitter() as FakeChild;
+  ee.unref = vi.fn();
+  return ee;
+}
+
+afterEach(() => {
+  spawnMock.mockReset();
+});
+
+describe('openInBrowser — failure path degrades, never hangs or leaks', () => {
+  it('rejects when the opener process emits a spawn error (does NOT swallow it into a resolve)', async () => {
+    const child = fakeChild();
+    spawnMock.mockReturnValue(child);
+    const p = openInBrowser('https://example.test/auth?a=1&b=2');
+    // Fire the spawn error synchronously after the call returns.
+    queueMicrotask(() => child.emit('error', new Error('ENOENT')));
+    await expect(p).rejects.toThrow(/ENOENT/);
+  });
+
+  it('a LATE error after settle is swallowed, never an unhandled (fatal) error event', async () => {
+    vi.useFakeTimers();
+    try {
+      const child = fakeChild();
+      spawnMock.mockReturnValue(child);
+      const p = openInBrowser('https://example.test/auth');
+      // Advance past the 50ms settle so the success path resolves first.
+      await vi.advanceTimersByTimeAsync(60);
+      await expect(p).resolves.toBeUndefined();
+      // A late async spawn failure must not throw. The error listener stays
+      // attached (a listenerless 'error' event crashes the process in Node), so
+      // the late error is handled and harmlessly ignored.
+      expect(() => child.emit('error', new Error('late'))).not.toThrow();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('resolves after the spawn tick on the happy path and unrefs the child', async () => {
+    vi.useFakeTimers();
+    try {
+      const child = fakeChild();
+      spawnMock.mockReturnValue(child);
+      const p = openInBrowser('https://example.test/auth');
+      await vi.advanceTimersByTimeAsync(60);
+      await expect(p).resolves.toBeUndefined();
+      expect(child.unref).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/open-browser.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { browserOpenCommand } from './open-browser';
+
+// A realistic OAuth authorize URL: many `&`-separated params, which cmd.exe
+// treats as command separators unless the whole URL is quoted.
+const AUTH_URL =
+  'https://auth.openai.com/oauth/authorize?client_id=app_x&redirect_uri=http%3A%2F%2Flocalhost%3A1455%2Fauth%2Fcallback&response_type=code&scope=openid+profile&code_challenge=abc123&state=deadbeef';
+
+describe('browserOpenCommand', () => {
+  it('macOS uses `open` with the URL as a single arg', () => {
+    expect(browserOpenCommand(AUTH_URL, 'darwin')).toEqual({ cmd: 'open', args: [AUTH_URL] });
+  });
+
+  it('Linux uses `xdg-open` with the URL as a single arg', () => {
+    expect(browserOpenCommand(AUTH_URL, 'linux')).toEqual({ cmd: 'xdg-open', args: [AUTH_URL] });
+  });
+
+  it('Windows DOUBLE-QUOTES the URL so cmd.exe does not split it on `&`', () => {
+    const { cmd, args, verbatim } = browserOpenCommand(AUTH_URL, 'win32');
+    expect(cmd).toMatch(/cmd(\.exe)?$/i);
+    expect(verbatim).toBe(true);
+    expect(args.slice(0, 3)).toEqual(['/c', 'start', '""']);
+    // The whole URL — every `&` included — is inside one double-quoted token.
+    expect(args[3]).toBe(`"${AUTH_URL}"`);
+    // Sanity: the quoted arg still contains all the params after the first `&`.
+    expect(args[3]).toContain('redirect_uri');
+    expect(args[3]).toContain('code_challenge');
+    expect(args[3]).toContain('state=deadbeef');
+  });
+});

package/src/open-browser.ts

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Open a URL in the user's default browser. Platform-specific:
+ *   macOS  → `open <url>`
+ *   Linux  → `xdg-open <url>`
+ *   Win32  → `cmd /c start "" "<url>"` (the URL DOUBLE-QUOTED + args passed
+ *           verbatim — see {@link browserOpenCommand})
+ *
+ * Returns once the helper process is spawned — it does NOT wait for the
+ * browser itself, since the user's flow continues asynchronously via
+ * the OAuth callback. Failures fall back to returning the URL string
+ * so the caller can print it for the user to paste manually.
+ */
+export async function openInBrowser(url: string): Promise<void> {
+  const { cmd, args, verbatim } = browserOpenCommand(url);
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: 'ignore',
+      detached: true,
+      // Windows only: keep cmd.exe from re-quoting our already-quoted URL,
+      // which would otherwise break the `&` escaping (see below).
+      ...(verbatim ? { windowsVerbatimArguments: true } : {}),
+    });
+    // Settle exactly once. An early spawn `error` rejects AND clears the pending
+    // 50ms timer (else it would fire a stray resolve later and hold a live timer
+    // handle on the event loop). After we've resolved, a LATE async spawn error
+    // must NOT be left unhandled: an 'error' event with no listener is fatal in
+    // Node (it re-throws as an uncaught exception). So we keep an error listener
+    // attached for the child's whole lifetime — it rejects before settle, and
+    // harmlessly swallows after.
+    let settled = false;
+    const onError = (err: Error): void => {
+      if (settled) return; // post-resolve late error: swallow, never crash
+      settled = true;
+      clearTimeout(timer);
+      reject(err);
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    }, 50);
+    // Don't let the 50ms settle-timer keep the process alive on its own.
+    timer.unref?.();
+    // `on` (not `once`): the listener stays for the child's lifetime so any late
+    // 'error' is always handled (a listenerless 'error' would crash the process).
+    child.on('error', onError);
+    // `unref` so a misbehaving opener process can't keep the moxxy
+    // process alive past its own lifetime.
+    child.unref();
+    // Resolve after spawn — we never want to wait for the browser to
+    // close. A 50ms tick is enough to surface spawn-time errors.
+  });
+}
+
+/**
+ * Resolve the platform's "open this URL in the default browser" command.
+ * Exported + `platform`-parameterized so the Windows quoting can be unit-tested
+ * without actually spawning a browser.
+ *
+ * Windows is the tricky one: `&` (and `|`, `<`, `>`, `^`) in a URL are cmd.exe
+ * command separators. `cmd /c start "" http://a?x=1&y=2` truncates the URL at
+ * the first `&`, so an OAuth authorize URL loses redirect_uri / code_challenge /
+ * state and the provider rejects the request ("authorization error"). Wrapping
+ * the URL in double quotes makes cmd treat it as one literal token; passing the
+ * args verbatim (`windowsVerbatimArguments`) stops Node from re-quoting and
+ * undoing that. The empty `""` is the required `start` window-title placeholder.
+ */
+export function browserOpenCommand(
+  url: string,
+  platform: NodeJS.Platform = process.platform,
+): { cmd: string; args: string[]; verbatim?: boolean } {
+  if (platform === 'darwin') return { cmd: 'open', args: [url] };
+  if (platform === 'win32') {
+    return {
+      cmd: process.env.ComSpec || 'cmd.exe',
+      args: ['/c', 'start', '""', `"${url}"`],
+      verbatim: true,
+    };
+  }
+  // Linux + everything else assumes a Freedesktop-compliant `xdg-open`.
+  return { cmd: 'xdg-open', args: [url] };
+}

package/src/pkce.ts

@@ -0,0 +1,37 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+/**
+ * Generate a PKCE code verifier per RFC 7636 §4.1.
+ * Spec range: 43–128 chars from the unreserved set [A-Z a-z 0-9 - . _ ~].
+ * We use 96 bytes of entropy → 128 base64url chars (full length).
+ */
+export function generateCodeVerifier(): string {
+  return base64urlEncode(randomBytes(96));
+}
+
+/**
+ * RFC 7636 §4.2 — SHA-256(verifier) then base64url-encode. The
+ * challenge_method is implied: callers MUST send `code_challenge_method=S256`
+ * to the authorization endpoint when using this helper.
+ */
+export function computeCodeChallenge(codeVerifier: string): string {
+  return base64urlEncode(createHash('sha256').update(codeVerifier).digest());
+}
+
+/**
+ * Opaque CSRF token included in the `state` query param. The callback
+ * server verifies that the returned state matches what we sent, so a
+ * cross-site forgery can't redirect the user back into our local
+ * server with attacker-controlled code.
+ */
+export function generateState(): string {
+  return base64urlEncode(randomBytes(24));
+}
+
+function base64urlEncode(buf: Buffer): string {
+  return buf
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}