@moxxy/plugin-provider-openai-codex 0.21.1

package/src/codex/stream-consumer.ts

@@ -0,0 +1,181 @@
+import { toFriendlyError, type ProviderEvent, type StopReason } from '@moxxy/sdk';
+import { handleSseEvent } from './sse-event-handler.js';
+import { CODEX_RESPONSES_URL } from '../oauth.js';
+import { parseToolArgs, type PendingFunctionCall, type ResponsesSseEvent } from './stream-types.js';
+
+export function toErrorEvent(err: unknown): ProviderEvent {
+  return {
+    type: 'error',
+    ...toFriendlyError(err, { provider: 'openai-codex', url: CODEX_RESPONSES_URL }),
+  };
+}
+
+// Hard cap on the unparsed reassembly buffer. A misbehaving/MITM'd endpoint (or
+// a wedged proxy emitting a continuous body with no blank-line frame separator)
+// would otherwise grow `buffer` without bound until OOM, since it's only ever
+// truncated when a separator is found. 8 MiB is far larger than any legitimate
+// single SSE frame; exceeding it with no separator is treated as a hostile stream.
+const MAX_SSE_BUFFER_BYTES = 8 * 1024 * 1024;
+
+export async function* consumeResponsesSse(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal | undefined,
+  emitReasoning = false,
+  // Called on every successful body read so the caller can reset an idle
+  // watchdog (a stalled stream that stops sending bytes must not hang forever).
+  onActivity?: () => void,
+): AsyncIterable<ProviderEvent> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  const pending = new Map<string, PendingFunctionCall>();
+  let stopReason: StopReason = 'end_turn';
+  let usageIn = 0;
+  let usageOut = 0;
+  let usageCacheRead = 0;
+  // Tracks whether ANY tool_use_end was yielded during the stream.
+  // The Responses API's `response.completed` event doesn't differentiate
+  // text-only vs tool-use turns, so without this we'd report end_turn
+  // even when tools were requested — the upstream tool-use loop would
+  // then drop the calls without executing them.
+  let sawToolCall = false;
+  // Set when an error frame (response.failed/error) surfaced the failure, so
+  // we don't also flush tool calls / emit a normal message_end on top of it.
+  let errored = false;
+
+  try {
+    try {
+      outer: while (true) {
+        if (signal?.aborted) {
+          yield { type: 'error', message: 'aborted', retryable: false };
+          return;
+        }
+        const { done, value } = await reader.read();
+        if (done) break;
+        onActivity?.();
+        buffer += decoder.decode(value, { stream: true });
+
+        // Bound the unparsed buffer: if it grows past the cap without yielding a
+        // single complete frame, the peer is feeding us an unframed/oversized
+        // body. Bail rather than accumulate to OOM. (The `finally` cancels the
+        // reader so the socket is released.)
+        if (buffer.length > MAX_SSE_BUFFER_BYTES) {
+          yield {
+            type: 'error',
+            message: 'Codex stream frame exceeded size limit',
+            retryable: false,
+          };
+          return;
+        }
+
+        // SSE frames are separated by blank lines. Some servers emit \r\n\r\n;
+        // match either form at the separator and line boundaries rather than
+        // rescanning the whole accumulated buffer with a global CRLF replace on
+        // every chunk. A `\r` split across two reads is handled because the
+        // boundary regexes tolerate the optional `\r`.
+        let m: RegExpExecArray | null;
+        const sepRe = /\r?\n\r?\n/g;
+        while ((m = sepRe.exec(buffer)) !== null) {
+          const frame = buffer.slice(0, m.index);
+          buffer = buffer.slice(m.index + m[0].length);
+          sepRe.lastIndex = 0;
+          for (const line of frame.split(/\r?\n/)) {
+            if (!line.startsWith('data:')) continue;
+            const payload = line.slice(5).trimStart();
+            if (!payload || payload === '[DONE]') continue;
+
+            let json: ResponsesSseEvent;
+            try {
+              json = JSON.parse(payload) as ResponsesSseEvent;
+            } catch {
+              continue;
+            }
+            const result = handleSseEvent(json, pending, emitReasoning);
+            if (result.events) {
+              for (const ev of result.events) {
+                if (ev.type === 'tool_use_end') sawToolCall = true;
+                if (ev.type === 'error') errored = true;
+                yield ev;
+              }
+            }
+            if (result.stopReason) stopReason = result.stopReason;
+            if (result.usage) {
+              usageIn = result.usage.input ?? usageIn;
+              usageOut = result.usage.output ?? usageOut;
+              usageCacheRead = result.usage.cacheRead ?? usageCacheRead;
+            }
+            // Terminal frame (response.completed / failed / error): stop
+            // consuming. Honoring this prevents a failed turn from emitting
+            // both an `error` AND a trailing `message_end`, and ignores any
+            // stray frames after completion.
+            if (result.terminal) break outer;
+          }
+        }
+      }
+    } catch (err) {
+      yield toErrorEvent(err);
+      return;
+    }
+
+    // The error frame already surfaced the failure; nothing more to emit. Drop
+    // any pending function calls so a later code path can't flush a phantom
+    // tool_use on top of a failed turn — the error supersedes them.
+    if (errored) {
+      pending.clear();
+      return;
+    }
+
+    // Flush any tool_call_end events that didn't have a matching .done frame
+    // (defensive — the server normally sends function_call.done, but a
+    // truncated stream shouldn't drop the entire tool-use sequence).
+    for (const entry of pending.values()) {
+      const outId = entry.callId || entry.id;
+      // If we have a name but never emitted the start (server sent args.delta
+      // for an item whose .added carried no name, then truncated before .done),
+      // emit the start first — mirrors the .done branch — so the call isn't
+      // dropped just because its start frame never landed.
+      if (!entry.emittedStart && entry.name) {
+        entry.emittedStart = true;
+        yield { type: 'tool_use_start', id: outId, name: entry.name };
+      }
+      if (entry.emittedStart) {
+        sawToolCall = true;
+        yield { type: 'tool_use_end', id: outId, input: parseToolArgs(entry.args) };
+      } else if (process.env.MOXXY_DEBUG) {
+        // A pending function call that never carried a name and never started:
+        // we cannot synthesize a valid tool_use, so it is dropped — but make
+        // it observable rather than silently swallowed.
+        console.error(
+          `[openai-codex] dropping a truncated function_call with no name (id=${outId}, args=${entry.args.length}B)`,
+        );
+      }
+    }
+
+    // If we yielded any tool_use_end this stream, the turn IS a tool-use
+    // turn regardless of what `response.completed` said. The Responses API
+    // sends `completed` with no stop_reason field, so we infer from the
+    // events we actually emitted. Without this upgrade, codex turns with
+    // tool calls were reported as end_turn and the loop dropped them.
+    if (stopReason === 'end_turn' && sawToolCall) {
+      stopReason = 'tool_use';
+    }
+
+    yield {
+      type: 'message_end',
+      stopReason,
+      ...(usageIn > 0 || usageOut > 0
+        ? {
+            usage: {
+              inputTokens: usageIn,
+              outputTokens: usageOut,
+              ...(usageCacheRead > 0 ? { cacheReadTokens: usageCacheRead } : {}),
+            },
+          }
+        : {}),
+    };
+  } finally {
+    // Always release the HTTP body — on normal completion, error, abort, or
+    // the consumer abandoning the stream early — so the socket isn't leaked.
+    reader.cancel().catch(() => {});
+  }
+}

package/src/codex/stream-types.ts

@@ -0,0 +1,61 @@
+import type { ProviderEvent, StopReason } from '@moxxy/sdk';
+
+export interface PendingFunctionCall {
+  id: string;
+  callId: string;
+  name: string;
+  args: string;
+  emittedStart: boolean;
+}
+
+export interface ResponsesSseEvent {
+  type?: string;
+  delta?: string;
+  item?: {
+    type?: string;
+    id?: string;
+    call_id?: string;
+    name?: string;
+    arguments?: string;
+    /** On a `reasoning` output item: the opaque blob to replay (round-trip). */
+    encrypted_content?: string;
+  };
+  item_id?: string;
+  call_id?: string;
+  name?: string;
+  arguments?: string;
+  response?: {
+    status?: string;
+    incomplete_details?: { reason?: string };
+    usage?: {
+      input_tokens?: number;
+      output_tokens?: number;
+      input_tokens_details?: { cached_tokens?: number };
+    };
+  };
+  error?: { message?: string };
+}
+
+export interface SseStepResult {
+  events?: ProviderEvent[];
+  stopReason?: StopReason;
+  usage?: { input?: number; output?: number; cacheRead?: number };
+  terminal?: boolean;
+}
+
+/**
+ * Parse accumulated function-call argument text into the tool input. The
+ * server normally sends well-formed JSON, but a truncated stream can leave
+ * partial JSON; rather than drop the call we surface the raw text under
+ * `_rawPartial` so the upstream loop still sees the tool request. Shared by
+ * the per-event handler (`function_call_arguments.done`) and the consumer's
+ * truncated-stream flush so the two stay in lockstep.
+ */
+export function parseToolArgs(args: string): unknown {
+  if (!args) return {};
+  try {
+    return JSON.parse(args);
+  } catch {
+    return { _rawPartial: args };
+  }
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+import { defineProvider, definePlugin } from '@moxxy/sdk';
+import { CodexProvider, type CodexProviderConfig } from './provider.js';
+import { codexModels } from './models.js';
+import { codexLogin, codexLogout, codexStatus } from './login.js';
+import { PLUGIN_VERSION } from './codex/headers.js';
+
+export const openaiCodexProviderDef = defineProvider({
+  name: 'openai-codex',
+  models: [...codexModels],
+  createClient: (config) => new CodexProvider(config as CodexProviderConfig),
+  // No validateKey: OAuth credentials are validated by the OAuth token
+  // exchange itself, not by a synchronous key check.
+  auth: {
+    kind: 'oauth',
+    serviceName: 'ChatGPT Pro/Plus',
+    login: codexLogin,
+    logout: codexLogout,
+    status: codexStatus,
+  },
+});
+
+export const openaiCodexPlugin = definePlugin({
+  name: '@moxxy/plugin-provider-openai-codex',
+  version: PLUGIN_VERSION,
+  providers: [openaiCodexProviderDef],
+});
+
+export default openaiCodexPlugin;
+
+export { CodexProvider } from './provider.js';
+export { codexModels, DEFAULT_CODEX_MODEL } from './models.js';
+export {
+  CLIENT_ID,
+  ISSUER,
+  AUTHORIZE_URL,
+  TOKEN_URL,
+  CODEX_RESPONSES_URL,
+  DEFAULT_CALLBACK_PORT,
+  DEFAULT_REDIRECT_PATH,
+  DEFAULT_REDIRECT_URI,
+  SCOPES,
+  ORIGINATOR,
+  generatePKCE,
+  generateState,
+  buildAuthorizeUrl,
+  parseJwtClaims,
+  extractAccountId,
+  exchangeCodeForTokens,
+  refreshTokens,
+} from './oauth.js';
+export {
+  CODEX_PROVIDER_ID,
+  codexOauthProfile,
+} from './profile.js';
+export {
+  codexLogin,
+  codexLogout,
+  codexStatus,
+  ensureFreshCodexTokens,
+  persistCodexTokens,
+  readStoredTokens,
+  readStoredTokens as readCodexStoredTokens,
+} from './login.js';
+export type { CodexProviderConfig } from './provider.js';
+export type { CodexTokens, PkceCodes, OAuthTokenResponse } from './types.js';

package/src/login.ts

@@ -0,0 +1,121 @@
+/**
+ * Codex OAuth login — thin wrapper over `@moxxy/plugin-oauth`'s provider
+ * framework. Everything generic (loopback callback server, browser opener,
+ * device-flow polling, vault persistence, refresh) lives in plugin-oauth;
+ * this file only carries the codex-shaped mapping into `CodexTokens` that
+ * the provider class consumes.
+ */
+
+import {
+  clearStoredCreds,
+  ensureFreshTokens,
+  readStoredCreds,
+  runOauthLogin,
+  storeTokenSet,
+  type OAuthVault,
+  type StoredCreds,
+} from '@moxxy/plugin-oauth';
+import type {
+  ProviderAuthContext,
+  ProviderOAuthResult,
+  ProviderOAuthStatus,
+} from '@moxxy/sdk';
+import { CODEX_PROVIDER_ID, codexOauthProfile } from './profile.js';
+import type { CodexTokens } from './types.js';
+
+export async function codexLogin(ctx: ProviderAuthContext): Promise<ProviderOAuthResult> {
+  const result = await runOauthLogin(codexOauthProfile, {
+    vault: ctx.vault,
+    headless: ctx.headless,
+    write: ctx.write,
+  });
+  return result.accountId
+    ? { accountId: result.accountId, expiresAt: result.tokens.expiresAt ?? 0 }
+    : { expiresAt: result.tokens.expiresAt ?? 0 };
+}
+
+export async function codexLogout(ctx: ProviderAuthContext): Promise<boolean> {
+  try {
+    const removed = await clearStoredCreds(ctx.vault, CODEX_PROVIDER_ID);
+    return removed > 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function codexStatus(ctx: ProviderAuthContext): Promise<ProviderOAuthStatus | null> {
+  const stored = await readStoredCreds(ctx.vault, CODEX_PROVIDER_ID);
+  if (!stored) return null;
+  return {
+    accountId: stored.extras.account_id ?? null,
+    expiresAt: stored.tokenSet.expiresAt ?? 0,
+    vaultKey: `oauth/${CODEX_PROVIDER_ID}/*`,
+  };
+}
+
+/**
+ * Read the stored token set in the legacy `CodexTokens` shape the provider
+ * class expects. Returns `null` if nothing is stored — the provider then
+ * reports the "run `moxxy login openai-codex`" error to the caller.
+ */
+export async function readStoredTokens(vault: OAuthVault): Promise<CodexTokens | null> {
+  const stored = await readStoredCreds(vault, CODEX_PROVIDER_ID);
+  return stored ? toCodexTokens(stored) : null;
+}
+
+/**
+ * Pre-request freshness gate consumed by `CodexProvider.ensureFresh`.
+ * Reads the stored creds, refreshes if near expiry, persists the rotated
+ * tokens BEFORE returning so a crash here can't strand a single-use
+ * refresh_token in memory.
+ */
+export async function ensureFreshCodexTokens(vault: OAuthVault): Promise<CodexTokens> {
+  const { tokens, extras } = await ensureFreshTokens(codexOauthProfile, vault);
+  if (!tokens.refreshToken) {
+    throw new Error('refreshed token set missing refresh_token');
+  }
+  return {
+    access: tokens.accessToken,
+    refresh: tokens.refreshToken,
+    expires: tokens.expiresAt ?? 0,
+    ...(extras.account_id ? { accountId: extras.account_id } : {}),
+  };
+}
+
+/**
+ * Persist the provider's in-memory `CodexTokens` back into the vault after
+ * an in-flight refresh. Wires the `CodexProvider.onTokensRefreshed`
+ * callback to the same storage layout `runOauthLogin` writes.
+ */
+export async function persistCodexTokens(
+  vault: OAuthVault,
+  tokens: CodexTokens,
+): Promise<void> {
+  await storeTokenSet(
+    vault,
+    CODEX_PROVIDER_ID,
+    {
+      accessToken: tokens.access,
+      refreshToken: tokens.refresh,
+      expiresAt: tokens.expires,
+      tokenType: 'Bearer',
+    },
+    {
+      clientId: codexOauthProfile.clientId,
+      tokenUrl: codexOauthProfile.tokenUrl,
+      extras: tokens.accountId ? { account_id: tokens.accountId } : {},
+    },
+  );
+}
+
+function toCodexTokens(stored: StoredCreds): CodexTokens {
+  if (!stored.tokenSet.refreshToken) {
+    throw new Error(`Stored codex creds missing refresh_token under oauth/${CODEX_PROVIDER_ID}/`);
+  }
+  return {
+    access: stored.tokenSet.accessToken,
+    refresh: stored.tokenSet.refreshToken,
+    expires: stored.tokenSet.expiresAt ?? 0,
+    ...(stored.extras.account_id ? { accountId: stored.extras.account_id } : {}),
+  };
+}

package/src/models.ts

@@ -0,0 +1,21 @@
+import type { ModelDescriptor } from '@moxxy/sdk';
+
+/**
+ * Models the ChatGPT-plan backend will serve. Mirrors opencode's ALLOWED_MODELS
+ * set (`packages/opencode/src/plugin/codex.ts`). The API-key OpenAI provider
+ * still exposes the full catalog; this list is the subset the Codex backend
+ * routes to ChatGPT-Pro/Plus subscribers without per-token billing.
+ */
+// Every Codex-served model is a gpt-5-family reasoning model, so all advertise
+// `supportsReasoning` — the request already sends `reasoning.summary: 'auto'`;
+// the per-provider toggle decides whether the summary is surfaced.
+export const codexModels: ReadonlyArray<ModelDescriptor> = [
+  { id: 'gpt-5.5', contextWindow: 1_000_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.4', contextWindow: 1_000_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.4-mini', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.3-codex', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.3-codex-spark', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.2', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+];
+
+export const DEFAULT_CODEX_MODEL = 'gpt-5.3-codex';

package/src/oauth.test.ts

@@ -0,0 +1,223 @@
+import { Buffer } from 'node:buffer';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  AUTHORIZE_URL,
+  CLIENT_ID,
+  buildAuthorizeUrl,
+  exchangeCodeForTokens,
+  extractAccountId,
+  generatePKCE,
+  generateState,
+  parseJwtClaims,
+  refreshTokens,
+  SCOPES,
+  TOKEN_URL,
+} from './oauth.js';
+
+function makeJwt(claims: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'none' })).toString('base64url');
+  const payload = Buffer.from(JSON.stringify(claims)).toString('base64url');
+  return `${header}.${payload}.sig`;
+}
+
+describe('generatePKCE', () => {
+  it('produces a spec-length verifier and a 43-char SHA-256 base64url challenge', async () => {
+    const { verifier, challenge } = await generatePKCE();
+    // 96 bytes of entropy -> 128 base64url chars (the @moxxy/plugin-oauth
+    // shared verifier; spec allows 43–128).
+    expect(verifier).toHaveLength(128);
+    expect(verifier).toMatch(/^[A-Za-z0-9\-._~]+$/);
+    expect(challenge).toHaveLength(43);
+    expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(challenge).not.toContain('=');
+  });
+});
+
+describe('generateState', () => {
+  it('returns distinct, url-safe base64 strings', () => {
+    const a = generateState();
+    const b = generateState();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+});
+
+describe('buildAuthorizeUrl', () => {
+  it('includes all codex-required query params', () => {
+    const url = buildAuthorizeUrl('http://localhost:1455/auth/callback', {
+      verifier: 'v',
+      challenge: 'ch',
+    }, 'STATE');
+    expect(url.startsWith(`${AUTHORIZE_URL}?`)).toBe(true);
+    const params = new URL(url).searchParams;
+    expect(params.get('response_type')).toBe('code');
+    expect(params.get('client_id')).toBe(CLIENT_ID);
+    expect(params.get('redirect_uri')).toBe('http://localhost:1455/auth/callback');
+    expect(params.get('scope')).toBe(SCOPES);
+    expect(params.get('code_challenge')).toBe('ch');
+    expect(params.get('code_challenge_method')).toBe('S256');
+    expect(params.get('id_token_add_organizations')).toBe('true');
+    expect(params.get('codex_cli_simplified_flow')).toBe('true');
+    expect(params.get('state')).toBe('STATE');
+    expect(params.get('originator')).toBe('moxxy');
+  });
+});
+
+describe('parseJwtClaims', () => {
+  it('round-trips a manually-encoded JWT', () => {
+    const jwt = makeJwt({ sub: 'abc', email: 'me@example.com' });
+    expect(parseJwtClaims(jwt)).toEqual({ sub: 'abc', email: 'me@example.com' });
+  });
+
+  it('returns undefined for malformed JWTs', () => {
+    expect(parseJwtClaims('only.two')).toBeUndefined();
+    expect(parseJwtClaims('a.notbase64payload.c')).toBeUndefined();
+    expect(parseJwtClaims('')).toBeUndefined();
+  });
+
+  it('rejects a hostile JWT with an oversized payload segment instead of decoding it', () => {
+    // A MITM'd/hostile token endpoint (or a tampered vault entry replayed back)
+    // hands us a multi-megabyte base64url payload. We must NOT base64-decode and
+    // JSON.parse the whole thing — bound the segment and degrade to undefined.
+    const hugePayload = 'A'.repeat(2 * 1024 * 1024); // ~2 MiB, well over the 64 KiB cap
+    const jwt = `aGVhZGVy.${hugePayload}.sig`;
+    expect(parseJwtClaims(jwt)).toBeUndefined();
+  });
+
+  it('rejects a JWT whose payload parses to a non-object (string/array/null)', () => {
+    // The payload is valid base64url JSON but not a claim bag. Downstream code
+    // indexes the result as an object, so a scalar/array/null must be rejected
+    // rather than returned as a surprising value.
+    const scalar = `h.${Buffer.from('"just a string"').toString('base64url')}.s`;
+    const arr = `h.${Buffer.from('[1,2,3]').toString('base64url')}.s`;
+    const nul = `h.${Buffer.from('null').toString('base64url')}.s`;
+    expect(parseJwtClaims(scalar)).toBeUndefined();
+    expect(parseJwtClaims(arr)).toBeUndefined();
+    expect(parseJwtClaims(nul)).toBeUndefined();
+  });
+});
+
+describe('extractAccountId', () => {
+  it('prefers the top-level chatgpt_account_id claim', () => {
+    const id_token = makeJwt({
+      chatgpt_account_id: 'acct_top',
+      'https://api.openai.com/auth': { chatgpt_account_id: 'acct_namespaced' },
+      organizations: [{ id: 'org_first' }],
+    });
+    expect(extractAccountId({ id_token })).toBe('acct_top');
+  });
+
+  it('falls back to the namespaced auth-bag claim', () => {
+    const id_token = makeJwt({
+      'https://api.openai.com/auth': { chatgpt_account_id: 'acct_namespaced' },
+      organizations: [{ id: 'org_first' }],
+    });
+    expect(extractAccountId({ id_token })).toBe('acct_namespaced');
+  });
+
+  it('falls back to the first organization id', () => {
+    const id_token = makeJwt({ organizations: [{ id: 'org_first' }, { id: 'org_second' }] });
+    expect(extractAccountId({ id_token })).toBe('org_first');
+  });
+
+  it('returns undefined when no claim matches', () => {
+    const id_token = makeJwt({ sub: 'noone' });
+    expect(extractAccountId({ id_token })).toBeUndefined();
+  });
+
+  it('falls through from id_token to access_token', () => {
+    const access_token = makeJwt({ chatgpt_account_id: 'acct_from_access' });
+    expect(extractAccountId({ access_token })).toBe('acct_from_access');
+  });
+
+  it('degrades to undefined on hostile claim shapes instead of throwing', () => {
+    // organizations present but its first element is a scalar / null, the
+    // auth-bag is null, and chatgpt_account_id is the wrong type. None of these
+    // should crash extraction — it must return undefined.
+    const id_token = makeJwt({
+      chatgpt_account_id: 12345, // wrong type
+      'https://api.openai.com/auth': null,
+      organizations: ['not-an-object', null, { id: 42 }],
+    });
+    expect(() => extractAccountId({ id_token })).not.toThrow();
+    expect(extractAccountId({ id_token })).toBeUndefined();
+  });
+
+  it('returns undefined when handed empty/blank token strings', () => {
+    expect(extractAccountId({})).toBeUndefined();
+    expect(extractAccountId({ id_token: '', access_token: '' })).toBeUndefined();
+  });
+});
+
+describe('exchangeCodeForTokens', () => {
+  it('posts form-urlencoded body to the token endpoint and normalizes the response', async () => {
+    const id_token = makeJwt({ chatgpt_account_id: 'acct_123' });
+    const fakeFetch = vi.fn(async (_url: RequestInfo | URL, init?: RequestInit) => {
+      expect(init?.method).toBe('POST');
+      expect(init?.headers).toMatchObject({ 'Content-Type': 'application/x-www-form-urlencoded' });
+      const body = new URLSearchParams(String(init?.body ?? ''));
+      expect(body.get('grant_type')).toBe('authorization_code');
+      expect(body.get('code')).toBe('CODE');
+      expect(body.get('redirect_uri')).toBe('http://localhost:1455/auth/callback');
+      expect(body.get('client_id')).toBe(CLIENT_ID);
+      expect(body.get('code_verifier')).toBe('VERIFIER');
+      return new Response(
+        JSON.stringify({
+          access_token: 'AT',
+          refresh_token: 'RT',
+          id_token,
+          expires_in: 7200,
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    });
+
+    const before = Date.now();
+    const result = await exchangeCodeForTokens(
+      'CODE',
+      'http://localhost:1455/auth/callback',
+      { verifier: 'VERIFIER', challenge: 'CH' },
+      fakeFetch as unknown as typeof fetch,
+    );
+    const after = Date.now();
+
+    expect(result.access).toBe('AT');
+    expect(result.refresh).toBe('RT');
+    expect(result.accountId).toBe('acct_123');
+    expect(result.expires).toBeGreaterThanOrEqual(before + 7200 * 1000);
+    expect(result.expires).toBeLessThanOrEqual(after + 7200 * 1000);
+    expect(fakeFetch).toHaveBeenCalledTimes(1);
+    expect(String(fakeFetch.mock.calls[0]![0])).toBe(TOKEN_URL);
+  });
+
+  it('throws when the token endpoint returns non-2xx', async () => {
+    const fakeFetch = vi.fn(async () => new Response('bad', { status: 400 }));
+    await expect(
+      exchangeCodeForTokens(
+        'CODE',
+        'http://localhost:1455/auth/callback',
+        { verifier: 'V', challenge: 'C' },
+        fakeFetch as unknown as typeof fetch,
+      ),
+    ).rejects.toThrow(/400/);
+  });
+});
+
+describe('refreshTokens', () => {
+  it('posts refresh_token grant and returns normalized tokens', async () => {
+    const fakeFetch = vi.fn(async (_url, init: RequestInit) => {
+      const body = new URLSearchParams(String(init.body ?? ''));
+      expect(body.get('grant_type')).toBe('refresh_token');
+      expect(body.get('refresh_token')).toBe('OLD_RT');
+      expect(body.get('client_id')).toBe(CLIENT_ID);
+      return new Response(
+        JSON.stringify({ access_token: 'NEW_AT', refresh_token: 'NEW_RT', expires_in: 1800 }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    });
+    const result = await refreshTokens('OLD_RT', fakeFetch as unknown as typeof fetch);
+    expect(result.access).toBe('NEW_AT');
+    expect(result.refresh).toBe('NEW_RT');
+    expect(result.accountId).toBeUndefined();
+  });
+});