npm - @moxxy/plugin-oauth - Versions diffs - 0.0.33 - Mend

@moxxy/plugin-oauth 0.0.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (113) hide show

package/LICENSE +21 -0
package/dist/adapters/openai-device-flow.d.ts +34 -0
package/dist/adapters/openai-device-flow.d.ts.map +1 -0
package/dist/adapters/openai-device-flow.js +136 -0
package/dist/adapters/openai-device-flow.js.map +1 -0
package/dist/adapters/rfc8628-device-flow.d.ts +20 -0
package/dist/adapters/rfc8628-device-flow.d.ts.map +1 -0
package/dist/adapters/rfc8628-device-flow.js +54 -0
package/dist/adapters/rfc8628-device-flow.js.map +1 -0
package/dist/credential-lock.d.ts +60 -0
package/dist/credential-lock.d.ts.map +1 -0
package/dist/credential-lock.js +149 -0
package/dist/credential-lock.js.map +1 -0
package/dist/ensure-fresh.d.ts +63 -0
package/dist/ensure-fresh.d.ts.map +1 -0
package/dist/ensure-fresh.js +122 -0
package/dist/ensure-fresh.js.map +1 -0
package/dist/flow.d.ts +6 -0
package/dist/flow.d.ts.map +1 -0
package/dist/flow.js +5 -0
package/dist/flow.js.map +1 -0
package/dist/index.d.ts +43 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +82 -0
package/dist/index.js.map +1 -0
package/dist/oauth/browser-flow.d.ts +23 -0
package/dist/oauth/browser-flow.d.ts.map +1 -0
package/dist/oauth/browser-flow.js +82 -0
package/dist/oauth/browser-flow.js.map +1 -0
package/dist/oauth/callback-server.d.ts +10 -0
package/dist/oauth/callback-server.d.ts.map +1 -0
package/dist/oauth/callback-server.js +158 -0
package/dist/oauth/callback-server.js.map +1 -0
package/dist/oauth/device-flow-shared.d.ts +39 -0
package/dist/oauth/device-flow-shared.d.ts.map +1 -0
package/dist/oauth/device-flow-shared.js +101 -0
package/dist/oauth/device-flow-shared.js.map +1 -0
package/dist/oauth/device-flow.d.ts +29 -0
package/dist/oauth/device-flow.d.ts.map +1 -0
package/dist/oauth/device-flow.js +74 -0
package/dist/oauth/device-flow.js.map +1 -0
package/dist/oauth/poll-until.d.ts +41 -0
package/dist/oauth/poll-until.d.ts.map +1 -0
package/dist/oauth/poll-until.js +70 -0
package/dist/oauth/poll-until.js.map +1 -0
package/dist/oauth/token-exchange.d.ts +28 -0
package/dist/oauth/token-exchange.d.ts.map +1 -0
package/dist/oauth/token-exchange.js +142 -0
package/dist/oauth/token-exchange.js.map +1 -0
package/dist/oauth/types.d.ts +90 -0
package/dist/oauth/types.d.ts.map +1 -0
package/dist/oauth/types.js +2 -0
package/dist/oauth/types.js.map +1 -0
package/dist/open-browser.d.ts +32 -0
package/dist/open-browser.d.ts.map +1 -0
package/dist/open-browser.js +83 -0
package/dist/open-browser.js.map +1 -0
package/dist/pkce.d.ts +20 -0
package/dist/pkce.d.ts.map +1 -0
package/dist/pkce.js +34 -0
package/dist/pkce.js.map +1 -0
package/dist/profile.d.ts +129 -0
package/dist/profile.d.ts.map +1 -0
package/dist/profile.js +11 -0
package/dist/profile.js.map +1 -0
package/dist/run-login.d.ts +9 -0
package/dist/run-login.d.ts.map +1 -0
package/dist/run-login.js +93 -0
package/dist/run-login.js.map +1 -0
package/dist/storage.d.ts +46 -0
package/dist/storage.d.ts.map +1 -0
package/dist/storage.js +167 -0
package/dist/storage.js.map +1 -0
package/dist/tools.d.ts +8 -0
package/dist/tools.d.ts.map +1 -0
package/dist/tools.js +283 -0
package/dist/tools.js.map +1 -0
package/package.json +73 -0
package/skills/google-oauth.md +313 -0
package/skills/oauth-flow.md +132 -0
package/src/adapters/openai-device-flow.test.ts +191 -0
package/src/adapters/openai-device-flow.ts +179 -0
package/src/adapters/rfc8628-device-flow.ts +75 -0
package/src/credential-lock.ts +183 -0
package/src/discovery.test.ts +35 -0
package/src/ensure-fresh.test.ts +279 -0
package/src/ensure-fresh.ts +178 -0
package/src/flow.ts +9 -0
package/src/index.ts +153 -0
package/src/oauth/browser-flow.ts +96 -0
package/src/oauth/callback-server.test.ts +90 -0
package/src/oauth/callback-server.ts +208 -0
package/src/oauth/device-flow-shared.test.ts +142 -0
package/src/oauth/device-flow-shared.ts +129 -0
package/src/oauth/device-flow.test.ts +102 -0
package/src/oauth/device-flow.ts +82 -0
package/src/oauth/poll-until.test.ts +63 -0
package/src/oauth/poll-until.ts +100 -0
package/src/oauth/token-exchange.test.ts +224 -0
package/src/oauth/token-exchange.ts +169 -0
package/src/oauth/types.ts +92 -0
package/src/oauth.test.ts +185 -0
package/src/open-browser-spawn.test.ts +69 -0
package/src/open-browser.test.ts +30 -0
package/src/open-browser.ts +84 -0
package/src/pkce.ts +37 -0
package/src/profile.test.ts +331 -0
package/src/profile.ts +135 -0
package/src/run-login.ts +123 -0
package/src/storage.test.ts +191 -0
package/src/storage.ts +208 -0
package/src/tools.test.ts +239 -0
package/src/tools.ts +332 -0

package/src/oauth/device-flow.test.ts ADDED Viewed

@@ -0,0 +1,102 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import { runDeviceCodeFlow } from './device-flow.js';
+import type { DeviceFlowOptions } from './types.js';
+function jsonResponse(obj: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => obj,
+    text: async () => JSON.stringify(obj),
+  } as unknown as Response;
+}
+function nonJsonResponse(status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: 'OK',
+    json: async () => {
+      throw new SyntaxError('Unexpected token < in JSON');
+    },
+    text: async () => '<html>captive portal</html>',
+  } as unknown as Response;
+}
+const baseOpts: Omit<DeviceFlowOptions, 'onPrompt'> = {
+  deviceUrl: 'https://idp.example/device',
+  tokenUrl: 'https://idp.example/token',
+  clientId: 'client-1',
+  scopes: ['openid'],
+};
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+describe('runDeviceCodeFlow — happy path applies the poll safety margin', () => {
+  it('polls only AFTER interval + DEVICE_POLL_SAFETY_MARGIN_MS (no edge-poll racing the rate limiter)', async () => {
+    vi.useFakeTimers();
+    const deviceAuth = {
+      device_code: 'dc-1',
+      user_code: 'WXYZ',
+      verification_uri: 'https://idp.example/verify',
+      expires_in: 600,
+      interval: 5,
+    };
+    const calls: string[] = [];
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: unknown) => {
+        const u = String(url);
+        if (u === baseOpts.deviceUrl) {
+          calls.push('device');
+          return jsonResponse(deviceAuth);
+        }
+        calls.push('poll');
+        return jsonResponse({ access_token: 'at-1', token_type: 'Bearer', expires_in: 3600 });
+      }),
+    );
+    let prompted = false;
+    const p = runDeviceCodeFlow({ ...baseOpts, onPrompt: () => (prompted = true) });
+    // Let the device-auth request resolve.
+    await vi.advanceTimersByTimeAsync(0);
+    expect(prompted).toBe(true);
+    expect(calls).toEqual(['device']);
+    // At interval (5s) exactly, the poll must NOT have fired — the +3s margin
+    // delays the first poll to 8s.
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(calls).toEqual(['device']);
+    await vi.advanceTimersByTimeAsync(3_000);
+    // Now the first poll fires.
+    const tokens = await p;
+    expect(calls).toEqual(['device', 'poll']);
+    expect(tokens.accessToken).toBe('at-1');
+  });
+});
+describe('runDeviceCodeFlow — hostile / malformed input degrades, never crashes', () => {
+  it('rejects a non-JSON 200 device-authorization body with a typed MoxxyError', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => nonJsonResponse(200)));
+    await expect(
+      runDeviceCodeFlow({ ...baseOpts, onPrompt: () => {} }),
+    ).rejects.toMatchObject({ code: 'PROVIDER_UNKNOWN_RESPONSE' });
+  });
+  it('rejects a 200 device-authorization body missing required fields', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ user_code: 'X' /* no device_code */ })));
+    const err = await runDeviceCodeFlow({ ...baseOpts, onPrompt: () => {} }).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('PROVIDER_UNKNOWN_RESPONSE');
+  });
+  it('surfaces a non-ok device-authorization HTTP error as a MoxxyError (no raw throw)', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => jsonResponse({ error: 'invalid_client' }, 400)));
+    const err = await runDeviceCodeFlow({ ...baseOpts, onPrompt: () => {} }).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+  });
+});

package/src/oauth/device-flow.ts ADDED Viewed

@@ -0,0 +1,82 @@
+import { pollUntil, type PollOutcome, type PollState } from './poll-until.js';
+import { classifyDeviceTokenResponse, requestDeviceAuthorization } from './device-flow-shared.js';
+import type { DeviceFlowOptions, TokenSet } from './types.js';
+/**
+ * Small margin added to the provider's interval before the first/each poll, so
+ * a server that enforces the interval strictly doesn't answer edge polls with
+ * `slow_down`. Mirrors `run-login.ts`'s margin so both device-flow drivers
+ * behave identically.
+ */
+const DEVICE_POLL_SAFETY_MARGIN_MS = 3000;
+/**
+ * Run the RFC 8628 device-authorization flow. Suitable for headless
+ * environments (SSH session, CI, kiosk, no display): the user opens
+ * the verification URL on any device, types the short user_code,
+ * approves the scopes, and the local process discovers the grant by
+ * polling the token endpoint.
+ *
+ * Phases:
+ *   1. POST `client_id` + `scope` to deviceUrl → returns user_code,
+ *      verification_uri, device_code, expires_in, interval.
+ *   2. `onPrompt` fires once with the user-facing pieces — the caller
+ *      surfaces them in whatever UI it has.
+ *   3. Poll tokenUrl every `interval` seconds with
+ *      grant_type=urn:ietf:params:oauth:grant-type:device_code +
+ *      device_code. The provider replies:
+ *        - authorization_pending → keep polling.
+ *        - slow_down            → bump interval by 5s and keep polling.
+ *        - access_denied        → user clicked deny; throw.
+ *        - expired_token        → device_code expired; throw.
+ *        - access_token, ...    → success; return TokenSet.
+ *
+ * The device-authorization request + the poll-response classification are
+ * shared with the {@link rfc8628DeviceFlow} adapter via `device-flow-shared`.
+ * This flow additionally sends `client_id` (+ optional `client_secret`) on the
+ * poll, which is why it builds its own poll body.
+ */
+export async function runDeviceCodeFlow(opts: DeviceFlowOptions): Promise<TokenSet> {
+  const auth = await requestDeviceAuthorization({
+    deviceUrl: opts.deviceUrl,
+    clientId: opts.clientId,
+    scopes: opts.scopes,
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+  opts.onPrompt({
+    userCode: auth.userCode,
+    verificationUri: auth.verificationUri,
+    ...(auth.verificationUriComplete ? { verificationUriComplete: auth.verificationUriComplete } : {}),
+    expiresIn: auth.expiresInSec,
+    interval: auth.intervalSec,
+  });
+  return pollUntil((state) => pollOnce(opts, auth.deviceCode, state), {
+    intervalMs: auth.intervalSec * 1000 + DEVICE_POLL_SAFETY_MARGIN_MS,
+    timeoutMs: Math.min(opts.timeoutMs ?? auth.expiresInSec * 1000, auth.expiresInSec * 1000),
+    label: 'OAuth device flow',
+    leadingWait: true,
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+}
+async function pollOnce(
+  opts: DeviceFlowOptions,
+  deviceCode: string,
+  state: PollState,
+): Promise<PollOutcome<TokenSet>> {
+  const body = new URLSearchParams();
+  body.set('grant_type', 'urn:ietf:params:oauth:grant-type:device_code');
+  body.set('device_code', deviceCode);
+  body.set('client_id', opts.clientId);
+  if (opts.clientSecret) body.set('client_secret', opts.clientSecret);
+  const pollRes = await fetch(opts.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: body.toString(),
+    ...(state.signal ? { signal: state.signal } : {}),
+  });
+  const pollJson = (await pollRes.json().catch(() => ({}))) as Record<string, unknown>;
+  return classifyDeviceTokenResponse(pollRes, pollJson, state);
+}

package/src/oauth/poll-until.test.ts ADDED Viewed

@@ -0,0 +1,63 @@
+import { getEventListeners } from 'node:events';
+import { describe, expect, it } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import { pollUntil } from './poll-until.js';
+const abortListeners = (signal: AbortSignal): number => getEventListeners(signal, 'abort').length;
+describe('pollUntil — abort-event listener hygiene', () => {
+  it('does not accumulate abort listeners across poll iterations', async () => {
+    // sleep() adds one `abort` listener per inter-poll wait against the SAME
+    // long-lived signal. If the timer-resolved path doesn't remove it, a device
+    // flow polling for minutes would pile up listeners and trip
+    // MaxListenersExceededWarning. Assert the count never grows past 1.
+    const controller = new AbortController();
+    const { signal } = controller;
+    let polls = 0;
+    let maxListeners = 0;
+    const result = await pollUntil(
+      async () => {
+        polls += 1;
+        maxListeners = Math.max(maxListeners, abortListeners(signal));
+        return polls >= 5 ? { done: 'ok' as const } : { pending: true as const };
+      },
+      { intervalMs: 1, timeoutMs: 5_000, signal, leadingWait: false },
+    );
+    expect(result).toBe('ok');
+    expect(polls).toBe(5);
+    // At most one abort listener is ever attached at a time — no leak.
+    expect(maxListeners).toBeLessThanOrEqual(1);
+    // And none is left dangling after the flow resolves.
+    expect(abortListeners(signal)).toBe(0);
+  });
+  it('rejects with NETWORK_ABORTED when the signal aborts mid-wait', async () => {
+    const controller = new AbortController();
+    const pending = pollUntil(async () => ({ pending: true as const }), {
+      intervalMs: 50,
+      timeoutMs: 5_000,
+      signal: controller.signal,
+      leadingWait: true,
+    });
+    const rejected = expect(pending).rejects.toMatchObject({ code: 'NETWORK_ABORTED' });
+    controller.abort();
+    await rejected;
+    // The abort listener is detached on the reject path too.
+    expect(abortListeners(controller.signal)).toBe(0);
+  });
+  it('throws OAUTH_FLOW_TIMEOUT once the deadline passes', async () => {
+    let err: unknown;
+    try {
+      await pollUntil(async () => ({ pending: true as const }), {
+        intervalMs: 1,
+        timeoutMs: 10,
+        leadingWait: false,
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    expect((err as MoxxyError).code).toBe('OAUTH_FLOW_TIMEOUT');
+  });
+});

package/src/oauth/poll-until.ts ADDED Viewed

@@ -0,0 +1,100 @@
+/**
+ * Shared polling primitive for OAuth-style "ask again later" modes. Handles
+ * the gnarly bits — deadline math, abort-responsive sleep, interval bumps
+ * for `slow_down`-style backpressure — so each device-flow dialect only has
+ * to encode its HTTP shape, not the timing harness.
+ *
+ * Consumed by both `runDeviceCodeFlow` (RFC 8628) and the Codex device flow
+ * (non-standard OpenAI endpoints). The polling fn returns `{done}` to finish
+ * or `{pending}` to keep going, and may mutate `state.intervalMs` mid-flight
+ * to apply a `slow_down` bump.
+ */
+import { MoxxyError } from '@moxxy/sdk';
+export interface PollState {
+  /** Mutable so the polling fn can bump on `slow_down`. */
+  intervalMs: number;
+  /**
+   * The flow's abort signal, threaded through so a polling fn can pass it
+   * into its in-flight fetch and cancel a hung request — not just the
+   * inter-poll sleep. Undefined when the caller supplied no signal.
+   */
+  readonly signal?: AbortSignal;
+}
+export type PollOutcome<T> = { done: T } | { pending: true };
+export interface PollUntilOpts {
+  readonly intervalMs: number;
+  readonly timeoutMs: number;
+  readonly signal?: AbortSignal;
+  /**
+   * Wait BEFORE the first call. RFC 8628 says clients SHOULD wait `interval`
+   * before the first poll; some flows (e.g. Codex) poll immediately. Default
+   * true to match the more conservative RFC behavior.
+   */
+  readonly leadingWait?: boolean;
+  /** Used in timeout / abort error messages. */
+  readonly label?: string;
+}
+export async function pollUntil<T>(
+  fn: (state: PollState) => Promise<PollOutcome<T>>,
+  opts: PollUntilOpts,
+): Promise<T> {
+  const state: PollState = {
+    intervalMs: opts.intervalMs,
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  };
+  const leadingWait = opts.leadingWait ?? true;
+  const deadline = Date.now() + opts.timeoutMs;
+  const label = opts.label ?? 'poll';
+  let first = true;
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) throw abortedError(label);
+    if (!first || leadingWait) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleep(Math.min(state.intervalMs, remaining), opts.signal, label);
+    }
+    first = false;
+    const result = await fn(state);
+    if ('done' in result) return result.done;
+  }
+  throw new MoxxyError({
+    code: 'OAUTH_FLOW_TIMEOUT',
+    message: `${label} timed out waiting for completion`,
+    context: { label, timeout_ms: opts.timeoutMs },
+  });
+}
+function abortedError(label: string): MoxxyError {
+  return new MoxxyError({
+    code: 'NETWORK_ABORTED',
+    message: `${label} aborted`,
+    context: { label },
+  });
+}
+function sleep(ms: number, signal: AbortSignal | undefined, label: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortedError(label));
+    // `{ once: true }` only auto-removes a listener that actually FIRES; on the
+    // timer-resolved path it would linger. pollUntil calls sleep() once per
+    // poll cycle against the SAME long-lived signal, so an unremoved listener
+    // accumulates one-per-iteration (~120 over a 10-min device flow), tripping
+    // MaxListenersExceededWarning and retaining each closure. Remove on BOTH
+    // exits so it's exactly one add / one remove per sleep.
+    const onAbort = (): void => {
+      clearTimeout(t);
+      reject(abortedError(label));
+    };
+    const t = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}

package/src/oauth/token-exchange.test.ts ADDED Viewed

@@ -0,0 +1,224 @@
+import { MoxxyError } from '@moxxy/sdk';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  exchangeCodeForToken,
+  parseTokenResponse,
+  refreshAccessToken,
+} from './token-exchange.js';
+describe('parseTokenResponse', () => {
+  it('throws PROVIDER_UNKNOWN_RESPONSE when access_token is missing', () => {
+    let err: unknown;
+    try {
+      parseTokenResponse({ token_type: 'Bearer' });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    expect((err as MoxxyError).code).toBe('PROVIDER_UNKNOWN_RESPONSE');
+  });
+  it('throws when access_token is present but not a string', () => {
+    expect(() => parseTokenResponse({ access_token: 12345 })).toThrow(MoxxyError);
+  });
+  it('maps every field of a full response', () => {
+    const before = Date.now();
+    const set = parseTokenResponse({
+      access_token: 'at',
+      refresh_token: 'rt',
+      expires_in: 3600,
+      scope: 'a b',
+      token_type: 'MAC',
+      id_token: 'idt',
+    });
+    expect(set.accessToken).toBe('at');
+    expect(set.refreshToken).toBe('rt');
+    expect(set.scope).toBe('a b');
+    expect(set.tokenType).toBe('MAC');
+    expect(set.idToken).toBe('idt');
+    // expiresAt = now + expires_in*1000 (allow for the small wall-clock delta).
+    expect(set.expiresAt!).toBeGreaterThanOrEqual(before + 3600 * 1000);
+    expect(set.expiresAt!).toBeLessThanOrEqual(Date.now() + 3600 * 1000);
+  });
+  it('omits expiresAt when expires_in is absent', () => {
+    const set = parseTokenResponse({ access_token: 'at' });
+    expect('expiresAt' in set).toBe(false);
+  });
+  it('omits refreshToken/scope/idToken when absent', () => {
+    const set = parseTokenResponse({ access_token: 'at', expires_in: 10 });
+    expect('refreshToken' in set).toBe(false);
+    expect('scope' in set).toBe(false);
+    expect('idToken' in set).toBe(false);
+  });
+  it("defaults token_type to 'Bearer' when absent or non-string", () => {
+    expect(parseTokenResponse({ access_token: 'at' }).tokenType).toBe('Bearer');
+    expect(parseTokenResponse({ access_token: 'at', token_type: 7 }).tokenType).toBe('Bearer');
+  });
+});
+describe('refreshAccessToken', () => {
+  const baseInput = {
+    tokenUrl: 'https://idp.example/token',
+    clientId: 'cid',
+    refreshToken: 'old-rt',
+  };
+  function fakeFetch(status: number, body: unknown): typeof fetch {
+    return (async () =>
+      ({
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => body,
+        text: async () => JSON.stringify(body),
+      })) as unknown as typeof fetch;
+  }
+  it('preserves no refresh_token in the result when the provider omits one', async () => {
+    // RFC 6749 §6: a refresh response MAY omit refresh_token. The caller is
+    // documented to preserve the prior token, so the returned set must NOT
+    // carry a refreshToken key in that case.
+    const set = await refreshAccessToken(
+      baseInput,
+      fakeFetch(200, { access_token: 'new-at', expires_in: 3600 }),
+    );
+    expect(set.accessToken).toBe('new-at');
+    expect('refreshToken' in set).toBe(false);
+  });
+  it('returns the rotated refresh_token when the provider supplies one', async () => {
+    const set = await refreshAccessToken(
+      baseInput,
+      fakeFetch(200, { access_token: 'new-at', refresh_token: 'rotated' }),
+    );
+    expect(set.refreshToken).toBe('rotated');
+  });
+  it('throws a MoxxyError on a non-ok status', async () => {
+    await expect(
+      refreshAccessToken(baseInput, fakeFetch(400, { error: 'invalid_grant' })),
+    ).rejects.toBeInstanceOf(MoxxyError);
+  });
+  it('sends grant_type=refresh_token with the refresh token in the body', async () => {
+    const spy = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ access_token: 'x' }),
+      text: async () => '',
+    }));
+    await refreshAccessToken(baseInput, spy as unknown as typeof fetch);
+    const body = (spy.mock.calls[0]![1] as RequestInit).body as string;
+    expect(body).toContain('grant_type=refresh_token');
+    expect(body).toContain('refresh_token=old-rt');
+    expect(body).toContain('client_id=cid');
+  });
+  it('maps a non-JSON 200 success body to PROVIDER_UNKNOWN_RESPONSE (not a raw SyntaxError)', async () => {
+    // A captive portal / proxy can answer HTTP 200 with HTML; an unguarded
+    // res.json() would reject with a native SyntaxError that escapes the
+    // MoxxyError boundary (isAuthRejection can't classify it).
+    const nonJson: typeof fetch = (async () =>
+      ({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new SyntaxError('Unexpected token < in JSON at position 0');
+        },
+        text: async () => '<html>captive portal</html>',
+      })) as unknown as typeof fetch;
+    let err: unknown;
+    try {
+      await refreshAccessToken(baseInput, nonJson);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    expect((err as MoxxyError).code).toBe('PROVIDER_UNKNOWN_RESPONSE');
+  });
+});
+describe('exchangeCodeForToken — error-body handling', () => {
+  const baseInput = {
+    tokenUrl: 'https://idp.example/token',
+    code: 'auth-code',
+    redirectUri: 'http://localhost:8765/callback',
+    clientId: 'cid',
+    codeVerifier: 'verifier',
+  };
+  function fakeRes(opts: {
+    ok: boolean;
+    status: number;
+    json?: () => Promise<unknown>;
+    text?: () => Promise<string>;
+  }): typeof fetch {
+    return (async () =>
+      ({
+        ok: opts.ok,
+        status: opts.status,
+        json: opts.json ?? (async () => ({})),
+        text: opts.text ?? (async () => ''),
+      })) as unknown as typeof fetch;
+  }
+  it('maps a non-JSON 200 success body to PROVIDER_UNKNOWN_RESPONSE', async () => {
+    let err: unknown;
+    try {
+      await exchangeCodeForToken(
+        baseInput,
+        fakeRes({
+          ok: true,
+          status: 200,
+          json: async () => {
+            throw new SyntaxError('boom');
+          },
+        }),
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    expect((err as MoxxyError).code).toBe('PROVIDER_UNKNOWN_RESPONSE');
+  });
+  it('does NOT reflect an opaque/HTML error body into the human message (only structured fields)', async () => {
+    // status 402 is not mapped by classifyHttpStatus → hits the fallback.
+    let err: unknown;
+    try {
+      await exchangeCodeForToken(
+        baseInput,
+        fakeRes({ ok: false, status: 402, text: async () => '<html><script>evil()</script></html>' }),
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    const e = err as MoxxyError;
+    // Opaque body never reaches the user-facing message…
+    expect(e.message).not.toContain('<html>');
+    expect(e.message).not.toContain('evil');
+    // …but the bounded raw body is retained in context for diagnostics.
+    expect(String(e.context?.body)).toContain('<html>');
+  });
+  it('surfaces the structured error_description in the message on an unmapped status', async () => {
+    let err: unknown;
+    try {
+      await exchangeCodeForToken(
+        baseInput,
+        fakeRes({
+          ok: false,
+          status: 418,
+          text: async () => JSON.stringify({ error: 'teapot', error_description: 'short and steep' }),
+        }),
+      );
+    } catch (e) {
+      err = e;
+    }
+    expect((err as MoxxyError).message).toContain('short and steep');
+  });
+});