patchling 0.2.0

package/src/llm.js

@@ -0,0 +1,296 @@
+/**
+ * LLM completion client for gptdiff-js.
+ *
+ * Speaks the OpenAI-compatible chat-completions protocol (used by NanoGPT)
+ * over `fetch`, so it runs unchanged in the browser and in Node 18+. An
+ * Anthropic branch is included for parity with the Python implementation.
+ */
+
+import { getEnv, DEFAULT_BASE_URL } from './env.js';
+
+/**
+ * Normalize a base URL so it has no trailing slash, then append `path`.
+ */
+function joinUrl(baseUrl, path) {
+  const base = baseUrl.replace(/\/+$/, '');
+  return `${base}${path}`;
+}
+
+/**
+ * @param {string} baseUrl
+ * @returns {string}
+ */
+function domainForUrl(baseUrl) {
+  try {
+    return new URL(baseUrl).host || baseUrl;
+  } catch {
+    return baseUrl;
+  }
+}
+
+/**
+ * Convert an OpenAI-style message (possibly with image_url blocks) to the
+ * Anthropic content-block shape.
+ */
+function convertOpenAiMessageToAnthropic(message) {
+  if (!Array.isArray(message.content)) return message;
+  const converted = [];
+  for (const block of message.content) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'text') {
+      converted.push({ type: 'text', text: block.text || '' });
+    } else if (block.type === 'image_url') {
+      const url = block.image_url?.url || '';
+      if (url.startsWith('data:') && url.includes(';base64,')) {
+        const [header, data] = url.split(',', 2);
+        const mediaType = header.split(':', 2)[1].split(';', 1)[0];
+        converted.push({
+          type: 'image',
+          source: { type: 'base64', media_type: mediaType, data },
+        });
+      }
+    } else {
+      converted.push(block);
+    }
+  }
+  return { ...message, content: converted };
+}
+
+/**
+ * Consume an OpenAI-compatible SSE stream (`stream: true`) from a fetch
+ * Response, invoking `onToken(text)` for every content delta.
+ *
+ * Handles `data:` events split across network chunks, multi-line `data:`
+ * events (lines are joined with `\n` per the SSE spec), and the terminal
+ * `data: [DONE]` sentinel. Accumulates the full content and the final
+ * `usage` object (requested via `stream_options: { include_usage: true }`)
+ * and returns the same shape as a non-streaming chat completion.
+ *
+ * @param {Response} resp
+ * @param {(text: string) => void} onToken
+ * @returns {Promise<{choices: Array<{message: {content: string}}>, usage: object}>}
+ */
+async function consumeSseStream(resp, onToken) {
+  if (!resp.body || typeof resp.body.getReader !== 'function') {
+    throw new Error('Streaming requested but the response body is not a readable stream.');
+  }
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let content = '';
+  let usage = null;
+  let dataLines = [];
+
+  // Dispatch one SSE event; returns true when the [DONE] sentinel is seen.
+  const dispatch = () => {
+    if (!dataLines.length) return false;
+    const payload = dataLines.join('\n');
+    dataLines = [];
+    if (payload.trim() === '[DONE]') return true;
+    let json;
+    try {
+      json = JSON.parse(payload);
+    } catch {
+      return false; // ignore keep-alives / unparseable fragments
+    }
+    if (json.error) {
+      throw new Error(`LLM API error (stream): ${JSON.stringify(json.error)}`);
+    }
+    const text = json.choices?.[0]?.delta?.content;
+    if (typeof text === 'string' && text.length) {
+      content += text;
+      onToken(text);
+    }
+    if (json.usage) usage = json.usage;
+    return false;
+  };
+
+  // Process one line; returns true when the stream is logically finished.
+  const handleLine = (rawLine) => {
+    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+    if (line === '') return dispatch(); // blank line terminates an event
+    if (line.startsWith('data:')) {
+      dataLines.push(line.startsWith('data: ') ? line.slice(6) : line.slice(5));
+    }
+    // `event:`, `id:` and `:` comment lines are ignored.
+    return false;
+  };
+
+  let finished = false;
+  while (!finished) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      if (handleLine(line)) {
+        finished = true;
+        break;
+      }
+    }
+  }
+  // Flush any trailing bytes / final event lacking a terminating blank line.
+  buffer += decoder.decode();
+  if (!finished && buffer) handleLine(buffer);
+  if (!finished) dispatch();
+
+  return { choices: [{ message: { content } }], usage };
+}
+
+/**
+ * Call a chat-completions endpoint.
+ *
+ * @param {object} opts
+ * @param {string} [opts.apiKey]
+ * @param {string} [opts.baseUrl]
+ * @param {string} opts.model
+ * @param {Array<object>} opts.messages
+ * @param {number} [opts.maxTokens]
+ * @param {number} [opts.temperature]
+ * @param {number} [opts.budgetTokens] Anthropic extended-thinking budget
+ * @param {(text: string) => void} [opts.onToken] when provided, the request is
+ *   made with `stream: true` and this is called once per content delta as
+ *   tokens arrive. The resolved value keeps the exact non-streaming shape
+ *   (`{ choices: [{ message: { content } }], usage }`), so callers work
+ *   unchanged. Ignored on the Anthropic branch (which stays non-streaming).
+ * @param {typeof fetch} [opts.fetchImpl] override for testing
+ * @param {number} [opts.maxRetries] retries on transient 429/5xx (default 3)
+ * @param {number} [opts.retryBaseMs] base backoff in ms (default 1500, exponential, capped 30s)
+ * @returns {Promise<{choices: Array<{message: {content: string}}>, usage: object}>}
+ */
+export async function callLlm({
+  apiKey,
+  baseUrl,
+  model,
+  messages,
+  maxTokens = null,
+  temperature = 1.0,
+  budgetTokens = null,
+  onToken = null,
+  fetchImpl,
+  maxRetries = 3,
+  retryBaseMs = 1500,
+}) {
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!doFetch) {
+    throw new Error('No fetch implementation available. Pass opts.fetchImpl in this environment.');
+  }
+  const url = baseUrl || DEFAULT_BASE_URL;
+
+  if (url.includes('api.anthropic.com')) {
+    const anthropicUrl = 'https://api.anthropic.com/v1/messages';
+    let systemMessage = null;
+    const filtered = [];
+    for (const m of messages) {
+      if (m.role === 'system') systemMessage = m.content;
+      else filtered.push(convertOpenAiMessageToAnthropic(m));
+    }
+    // Anthropic's API requires max_tokens, so fall back to a generous default
+    // only on this path; callers can still pass an explicit cap.
+    const data = { model, messages: filtered, max_tokens: maxTokens ?? 32000, temperature };
+    if (systemMessage) data.system = systemMessage;
+    if (budgetTokens) {
+      data.temperature = 1;
+      data.thinking = { budget_tokens: budgetTokens, type: 'enabled' };
+    }
+    const resp = await doFetch(anthropicUrl, {
+      method: 'POST',
+      headers: {
+        'x-api-key': apiKey,
+        'Content-Type': 'application/json',
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify(data),
+    });
+    const responseData = await resp.json();
+    if (responseData.error) {
+      throw new Error(`Error from Anthropic API: ${JSON.stringify(responseData)}`);
+    }
+    const thinkingItems = responseData.content.filter((c) => c.type === 'thinking').map((c) => c.thinking);
+    const textItems = responseData.content.filter((c) => c.type === 'text').map((c) => c.text);
+    if (!textItems.length) throw new Error("No 'text' type found in response content");
+    let messageContent = textItems[0];
+    if (thinkingItems.length) {
+      messageContent = `<think>${thinkingItems[0]}</think>\n${messageContent}`;
+    }
+    const inputTokens = responseData.usage.input_tokens;
+    const outputTokens = responseData.usage.output_tokens;
+    return {
+      choices: [{ message: { content: messageContent } }],
+      usage: {
+        prompt_tokens: inputTokens,
+        completion_tokens: outputTokens,
+        total_tokens: inputTokens + outputTokens,
+      },
+    };
+  }
+
+  // OpenAI-compatible (NanoGPT) path, with backoff on transient errors.
+  const endpoint = joinUrl(url, '/chat/completions');
+  // Only send max_tokens when explicitly capped; otherwise let the model emit its full output.
+  const requestBody = JSON.stringify({
+    model,
+    messages,
+    temperature,
+    ...(maxTokens ? { max_tokens: maxTokens } : {}),
+    // Streaming: ask for SSE deltas plus a final usage chunk.
+    ...(onToken ? { stream: true, stream_options: { include_usage: true } } : {}),
+  });
+  let resp;
+  for (let attempt = 0; ; attempt++) {
+    resp = await doFetch(endpoint, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: requestBody,
+    });
+    // Retry transient overload / rate-limit / server errors with backoff.
+    const transient = resp.status === 429 || resp.status >= 500;
+    if (resp.ok || !transient || attempt >= maxRetries) break;
+    const retryAfter = parseFloat(resp.headers.get?.('retry-after'));
+    const waitMs = Number.isFinite(retryAfter)
+      ? Math.min(retryAfter * 1000, 30000)
+      : Math.min(retryBaseMs * 2 ** attempt, 30000);
+    await new Promise((r) => setTimeout(r, waitMs));
+  }
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw new Error(`LLM request failed (${resp.status}) from ${domainForUrl(url)}: ${body}`);
+  }
+  if (onToken) {
+    // Retry/backoff above covered the initial request; an error mid-stream
+    // (after tokens have flowed) simply propagates to the caller.
+    return consumeSseStream(resp, onToken);
+  }
+  const json = await resp.json();
+  if (json.error) {
+    throw new Error(`LLM API error from ${domainForUrl(url)}: ${JSON.stringify(json.error)}`);
+  }
+  return json;
+}
+
+/**
+ * Resolve the effective API key, preferring an explicit override then the
+ * GPTDIFF_LLM_API_KEY environment variable.
+ * @param {string} [apiKey]
+ * @returns {string | undefined}
+ */
+export function resolveApiKey(apiKey) {
+  return apiKey || getEnv('GPTDIFF_LLM_API_KEY');
+}
+
+/**
+ * Resolve the effective base URL, preferring an explicit override then the
+ * GPTDIFF_LLM_BASE_URL environment variable, then the NanoGPT default.
+ * @param {string} [baseUrl]
+ * @returns {string}
+ */
+export function resolveBaseUrl(baseUrl) {
+  return baseUrl || getEnv('GPTDIFF_LLM_BASE_URL', DEFAULT_BASE_URL) || DEFAULT_BASE_URL;
+}
+
+export { domainForUrl };

package/src/oauth.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Base64url-encode an ArrayBuffer or Uint8Array (no padding).
+ * @param {ArrayBuffer | Uint8Array} buffer
+ * @returns {string}
+ */
+export function base64UrlEncode(buffer: ArrayBuffer | Uint8Array): string;
+/** Generate a high-entropy PKCE code verifier (base64url, 43+ chars). */
+export function generateCodeVerifier(byteLength?: number): string;
+/**
+ * Compute the S256 code challenge for a verifier.
+ * @param {string} verifier
+ * @returns {Promise<string>}
+ */
+export function generateCodeChallenge(verifier: string): Promise<string>;
+/** Generate a random CSRF `state` value. */
+export function generateState(byteLength?: number): string;
+/** Generate a complete PKCE pair: `{ verifier, challenge }`. */
+export function generatePkce(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+/**
+ * Dynamically register a public client with NanoGPT.
+ * @param {object} [opts]
+ * @param {string} [opts.clientName]
+ * @param {string} [opts.redirectUri]
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<{ client_id: string, [k: string]: any }>}
+ */
+export function registerClient({ clientName, redirectUri, fetchImpl }?: {
+    clientName?: string;
+    redirectUri?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    client_id: string;
+    [k: string]: any;
+}>;
+/**
+ * Build the authorization URL the user's browser should be sent to.
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} opts.redirectUri
+ * @param {string} [opts.scope]
+ * @param {string} opts.state
+ * @param {string} opts.codeChallenge
+ * @returns {string}
+ */
+export function buildAuthorizeUrl({ clientId, redirectUri, scope, state, codeChallenge, }: {
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+    state: string;
+    codeChallenge: string;
+}): string;
+/**
+ * Exchange an authorization code for an access token.
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} opts.redirectUri
+ * @param {string} opts.code
+ * @param {string} opts.codeVerifier
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<{ access_token: string, token_type: string, scope: string }>}
+ */
+export function exchangeCodeForToken({ clientId, redirectUri, code, codeVerifier, fetchImpl, }: {
+    clientId: string;
+    redirectUri: string;
+    code: string;
+    codeVerifier: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    access_token: string;
+    token_type: string;
+    scope: string;
+}>;
+/**
+ * Start the sign-in redirect. Stores the PKCE verifier, state, client_id and
+ * redirect_uri in sessionStorage and navigates the browser to NanoGPT.
+ *
+ * @param {object} opts
+ * @param {string} [opts.clientId]  a pre-registered NanoGPT client_id (ngpt_...)
+ * @param {string} [opts.redirectUri] defaults to the current page URL
+ * @param {string} [opts.scope]
+ * @param {boolean} [opts.redirect=true] navigate automatically
+ * @returns {Promise<string>} the authorization URL
+ */
+export function beginSignIn({ clientId, redirectUri, scope, redirect, }?: {
+    clientId?: string;
+    redirectUri?: string;
+    scope?: string;
+    redirect?: boolean;
+}): Promise<string>;
+/**
+ * Complete the sign-in after NanoGPT redirects back with `?code=...&state=...`.
+ * Validates state, exchanges the code, registers the access token as the
+ * GPTDIFF_LLM_API_KEY override, and clears the URL query string.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.search] query string to parse (defaults to window.location.search)
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<string | null>} the access token, or null if no code present
+ */
+export function completeSignIn({ search, fetchImpl }?: {
+    search?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<string | null>;
+export const NANOGPT_ORIGIN: "https://nano-gpt.com";
+export const REGISTER_URL: "https://nano-gpt.com/oauth/register";
+export const AUTHORIZE_URL: "https://nano-gpt.com/oauth/authorize";
+export const TOKEN_URL: "https://nano-gpt.com/oauth/token";
+export const DEFAULT_SCOPE: "api.use models.read";

package/src/oauth.js

@@ -0,0 +1,266 @@
+/**
+ * "Sign in with NanoGPT" — OAuth 2.0 Authorization Code flow with PKCE (S256).
+ *
+ * Reference: https://nano-gpt.com/blog/sign-in-with-nanogpt-oauth-pkce
+ *
+ * Endpoints:
+ *   register : POST https://nano-gpt.com/oauth/register
+ *   authorize: GET  https://nano-gpt.com/oauth/authorize
+ *   token    : POST https://nano-gpt.com/oauth/token
+ *
+ * The low-level functions are environment-agnostic. The high-level
+ * `beginSignIn` / `completeSignIn` helpers drive the browser redirect flow and
+ * stash the returned access token as the GPTDIFF_LLM_API_KEY override so the
+ * rest of gptdiff-js can use it transparently.
+ */
+
+import { setEnv } from './env.js';
+
+export const NANOGPT_ORIGIN = 'https://nano-gpt.com';
+export const REGISTER_URL = `${NANOGPT_ORIGIN}/oauth/register`;
+export const AUTHORIZE_URL = `${NANOGPT_ORIGIN}/oauth/authorize`;
+export const TOKEN_URL = `${NANOGPT_ORIGIN}/oauth/token`;
+export const DEFAULT_SCOPE = 'api.use models.read';
+
+const STORAGE_KEY = 'gptdiff_oauth_pkce';
+
+function getCrypto() {
+  const c = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
+  if (!c || !c.subtle) {
+    throw new Error('Web Crypto (crypto.subtle) is required for PKCE but is unavailable.');
+  }
+  return c;
+}
+
+/**
+ * Base64url-encode an ArrayBuffer or Uint8Array (no padding).
+ * @param {ArrayBuffer | Uint8Array} buffer
+ * @returns {string}
+ */
+export function base64UrlEncode(buffer) {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  const b64 = typeof btoa !== 'undefined'
+    ? btoa(binary)
+    : Buffer.from(bytes).toString('base64');
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Generate a high-entropy PKCE code verifier (base64url, 43+ chars). */
+export function generateCodeVerifier(byteLength = 64) {
+  const random = new Uint8Array(byteLength);
+  getCrypto().getRandomValues(random);
+  return base64UrlEncode(random);
+}
+
+/**
+ * Compute the S256 code challenge for a verifier.
+ * @param {string} verifier
+ * @returns {Promise<string>}
+ */
+export async function generateCodeChallenge(verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await getCrypto().subtle.digest('SHA-256', data);
+  return base64UrlEncode(digest);
+}
+
+/** Generate a random CSRF `state` value. */
+export function generateState(byteLength = 16) {
+  const random = new Uint8Array(byteLength);
+  getCrypto().getRandomValues(random);
+  return base64UrlEncode(random);
+}
+
+/** Generate a complete PKCE pair: `{ verifier, challenge }`. */
+export async function generatePkce() {
+  const verifier = generateCodeVerifier();
+  const challenge = await generateCodeChallenge(verifier);
+  return { verifier, challenge };
+}
+
+/**
+ * Dynamically register a public client with NanoGPT.
+ * @param {object} [opts]
+ * @param {string} [opts.clientName]
+ * @param {string} [opts.redirectUri]
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<{ client_id: string, [k: string]: any }>}
+ */
+export async function registerClient({ clientName, redirectUri, fetchImpl } = {}) {
+  const doFetch = fetchImpl || fetch;
+  const resp = await doFetch(REGISTER_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_name: clientName,
+      redirect_uris: [redirectUri],
+      grant_types: ['authorization_code'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none',
+    }),
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw new Error(`Client registration failed (${resp.status}): ${body}`);
+  }
+  return resp.json();
+}
+
+/**
+ * Build the authorization URL the user's browser should be sent to.
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} opts.redirectUri
+ * @param {string} [opts.scope]
+ * @param {string} opts.state
+ * @param {string} opts.codeChallenge
+ * @returns {string}
+ */
+export function buildAuthorizeUrl({
+  clientId,
+  redirectUri,
+  scope = DEFAULT_SCOPE,
+  state,
+  codeChallenge,
+}) {
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    scope,
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+  });
+  return `${AUTHORIZE_URL}?${params.toString()}`;
+}
+
+/**
+ * Exchange an authorization code for an access token.
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} opts.redirectUri
+ * @param {string} opts.code
+ * @param {string} opts.codeVerifier
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<{ access_token: string, token_type: string, scope: string }>}
+ */
+export async function exchangeCodeForToken({
+  clientId,
+  redirectUri,
+  code,
+  codeVerifier,
+  fetchImpl,
+}) {
+  const doFetch = fetchImpl || fetch;
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    code,
+    code_verifier: codeVerifier,
+  });
+  const resp = await doFetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => '');
+    throw new Error(`Token exchange failed (${resp.status}): ${text}`);
+  }
+  return resp.json();
+}
+
+/* -------------------------------------------------------------------------- */
+/* High-level browser redirect flow                                            */
+/* -------------------------------------------------------------------------- */
+
+function requireBrowser() {
+  if (typeof window === 'undefined' || !window.location || !window.sessionStorage) {
+    throw new Error('beginSignIn/completeSignIn require a browser environment.');
+  }
+}
+
+/**
+ * Start the sign-in redirect. Stores the PKCE verifier, state, client_id and
+ * redirect_uri in sessionStorage and navigates the browser to NanoGPT.
+ *
+ * @param {object} opts
+ * @param {string} [opts.clientId]  a pre-registered NanoGPT client_id (ngpt_...)
+ * @param {string} [opts.redirectUri] defaults to the current page URL
+ * @param {string} [opts.scope]
+ * @param {boolean} [opts.redirect=true] navigate automatically
+ * @returns {Promise<string>} the authorization URL
+ */
+export async function beginSignIn({
+  clientId,
+  redirectUri,
+  scope = DEFAULT_SCOPE,
+  redirect = true,
+} = {}) {
+  requireBrowser();
+  if (!clientId) throw new Error('beginSignIn requires a clientId.');
+  const finalRedirect = redirectUri || window.location.origin + window.location.pathname;
+  const { verifier, challenge } = await generatePkce();
+  const state = generateState();
+  window.sessionStorage.setItem(
+    STORAGE_KEY,
+    JSON.stringify({ verifier, state, clientId, redirectUri: finalRedirect }),
+  );
+  const authUrl = buildAuthorizeUrl({
+    clientId,
+    redirectUri: finalRedirect,
+    scope,
+    state,
+    codeChallenge: challenge,
+  });
+  if (redirect) window.location.assign(authUrl);
+  return authUrl;
+}
+
+/**
+ * Complete the sign-in after NanoGPT redirects back with `?code=...&state=...`.
+ * Validates state, exchanges the code, registers the access token as the
+ * GPTDIFF_LLM_API_KEY override, and clears the URL query string.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.search] query string to parse (defaults to window.location.search)
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @returns {Promise<string | null>} the access token, or null if no code present
+ */
+export async function completeSignIn({ search, fetchImpl } = {}) {
+  requireBrowser();
+  const params = new URLSearchParams(search ?? window.location.search);
+  const code = params.get('code');
+  if (!code) return null;
+
+  const raw = window.sessionStorage.getItem(STORAGE_KEY);
+  if (!raw) throw new Error('No stored PKCE state; cannot complete sign-in.');
+  const stored = JSON.parse(raw);
+
+  const returnedState = params.get('state');
+  if (returnedState !== stored.state) {
+    throw new Error('OAuth state mismatch — possible CSRF, aborting.');
+  }
+
+  const tokenResponse = await exchangeCodeForToken({
+    clientId: stored.clientId,
+    redirectUri: stored.redirectUri,
+    code,
+    codeVerifier: stored.verifier,
+    fetchImpl,
+  });
+
+  window.sessionStorage.removeItem(STORAGE_KEY);
+  setEnv('GPTDIFF_LLM_API_KEY', tokenResponse.access_token);
+
+  // Clean the code/state out of the URL.
+  const cleanUrl = window.location.origin + window.location.pathname;
+  if (window.history && window.history.replaceState) {
+    window.history.replaceState({}, document.title, cleanUrl);
+  }
+
+  return tokenResponse.access_token;
+}