@desplega.ai/agent-swarm 1.119.6 → 1.121.0

package/src/oauth/keepalive.ts

@@ -1,4 +1,5 @@
-import { ensureTokenOrThrow } from "./ensure-token";
+import { listKeepAliveAuthorizations } from "../be/db-queries/oauth";
+import { ensureAuthorizationTokenOrThrow } from "./ensure-token";
 
 // Keep refresh tokens warm without constantly rotating strict-rotation
 // providers. Reactive callers still refresh access tokens before API use.
@@ -6,8 +7,6 @@ const KEEPALIVE_INTERVAL_MS = 12 * 60 * 60 * 1000;
 const KEEPALIVE_BUFFER_MS = 10 * 60 * 1000;
 const STARTUP_KEEPALIVE_DELAY_MS = 10_000;
 
-const KEEPALIVE_PROVIDERS = ["linear", "jira"] as const;
-
 let keepaliveInterval: ReturnType<typeof setInterval> | null = null;
 let startupKeepaliveTimeout: ReturnType<typeof setTimeout> | null = null;
 let inflightKeepalive: Promise<void> | null = null;
@@ -41,16 +40,22 @@ function scheduleKeepaliveRun(trigger: "startup" | "interval" | "manual"): Promi
  */
 async function runKeepalive(trigger: "startup" | "interval" | "manual" = "manual"): Promise<void> {
   console.log(`[OAuth Keepalive] Running ${trigger} token refresh check`);
-  for (const provider of KEEPALIVE_PROVIDERS) {
-    console.log(`[OAuth Keepalive] Running scheduled token refresh for ${provider}...`);
+  const authorizations = listKeepAliveAuthorizations();
+  for (const authorization of authorizations) {
+    const label = authorization.displayName?.trim() || authorization.provider;
+    const named =
+      authorization.label && authorization.label !== "default"
+        ? `${label} (${authorization.label})`
+        : label;
+    console.log(`[OAuth Keepalive] Running scheduled token refresh for ${named}...`);
     try {
-      await ensureTokenOrThrow(provider, KEEPALIVE_BUFFER_MS);
-      console.log(`[OAuth Keepalive] ${provider} token check completed successfully`);
+      await ensureAuthorizationTokenOrThrow(authorization.authorizationId, KEEPALIVE_BUFFER_MS);
+      console.log(`[OAuth Keepalive] ${named} token check completed successfully`);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      console.error(`[OAuth Keepalive] Failed to refresh ${provider} token: ${message}`);
+      console.error(`[OAuth Keepalive] Failed to refresh ${named} token: ${message}`);
       await notifySlack(
-        `⚠️ *OAuth Keepalive Failed*\nProvider: \`${provider}\`\nError: ${message}\n\nManual re-authorization may be required.`,
+        `⚠️ *OAuth Keepalive Failed*\nApp: \`${named}\`\nError: ${message}\n\nManual re-authorization may be required.`,
       );
     }
   }

package/src/oauth/presets.ts

@@ -0,0 +1,242 @@
+/**
+ * Curated OAuth presets.
+ *
+ * Pure, static data — NO database or network access — so this module can be
+ * imported from HTTP handlers, MCP tools, and CLI code alike. Each preset
+ * generalizes the provider-specific OAuth quirks (endpoints, scope joining,
+ * token-endpoint auth style/body format, refresh-token rotation, and any
+ * authorization-URL extra params) that used to live in hardcoded per-provider
+ * builders. Client credentials are NEVER shipped here: customers always bring
+ * their own `clientId`/`clientSecret`.
+ *
+ * The `setupHints` on each preset are human-readable operator notes surfaced by
+ * pickers and by the app-creation response.
+ */
+
+export interface OAuthPreset {
+  /** Stable preset identifier referenced by the catalog manifest + pickers. */
+  id: string;
+  /** Human-friendly provider name. */
+  displayName: string;
+  /** Default provider slug used when the caller omits one. */
+  provider: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  /** RFC 7009 revocation endpoint, when the provider exposes one. */
+  revocationUrl?: string;
+  /** Identity-capture hint endpoint (OIDC userinfo or equivalent). */
+  userinfoUrl?: string;
+  /** Sensible default scopes; customers routinely override/extend these. */
+  scopes: string[];
+  /**
+   * How `scopes` are joined in the authorization URL. RFC 6749 default is a
+   * space; some providers (Linear, Slack) require a comma.
+   */
+  scopeSeparator?: string;
+  /** `"basic"` when the token endpoint needs HTTP Basic client auth. */
+  tokenAuthStyle?: "body" | "basic";
+  /** `"json"` when the token endpoint needs a JSON (not form) request body. */
+  tokenBodyFormat?: "form" | "json";
+  /** Provider rotates refresh tokens on every refresh (fail loudly if absent). */
+  requiresRefreshTokenRotation?: boolean;
+  /** Extra params appended to the authorization URL (e.g. Google offline access). */
+  extraParams?: Record<string, string>;
+  /** Operator-facing quirk notes surfaced in pickers + the creation response. */
+  setupHints: string[];
+}
+
+/**
+ * Fields a caller may supply explicitly to override a preset. Every field is
+ * optional; anything omitted is filled from the preset.
+ */
+export interface OAuthPresetOverrides {
+  provider?: string;
+  authorizeUrl?: string;
+  tokenUrl?: string;
+  revocationUrl?: string | null;
+  userinfoUrl?: string | null;
+  scopes?: string[];
+  scopeSeparator?: string;
+  tokenAuthStyle?: "body" | "basic";
+  tokenBodyFormat?: "form" | "json";
+  requiresRefreshTokenRotation?: boolean;
+  extraParams?: Record<string, string>;
+}
+
+/** Result of merging a preset with explicit overrides. */
+export interface HydratedOAuthApp {
+  provider: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  revocationUrl?: string | null;
+  userinfoUrl?: string | null;
+  scopes: string[];
+  scopeSeparator?: string;
+  tokenAuthStyle?: "body" | "basic";
+  tokenBodyFormat?: "form" | "json";
+  requiresRefreshTokenRotation?: boolean;
+  extraParams?: Record<string, string>;
+  source: "curated-prefill";
+  setupHints: string[];
+}
+
+const OAUTH_PRESETS: readonly OAuthPreset[] = [
+  {
+    id: "google",
+    displayName: "Google",
+    provider: "google",
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    revocationUrl: "https://oauth2.googleapis.com/revoke",
+    userinfoUrl: "https://openidconnect.googleapis.com/v1/userinfo",
+    scopes: ["openid", "email", "profile"],
+    scopeSeparator: " ",
+    tokenAuthStyle: "body",
+    tokenBodyFormat: "form",
+    extraParams: { access_type: "offline", prompt: "consent" },
+    setupHints: [
+      "Google only returns a refresh token when access_type=offline and prompt=consent are sent — this preset includes both so refresh tokens exist at all.",
+      "The default scopes cover identity only. Add the product scopes you actually need (e.g. Gmail: https://www.googleapis.com/auth/gmail.modify).",
+      "Create the OAuth client in Google Cloud Console → APIs & Services → Credentials and add the swarm redirect URI to the client's authorized redirect URIs.",
+    ],
+  },
+  {
+    id: "slack",
+    displayName: "Slack",
+    provider: "slack",
+    authorizeUrl: "https://slack.com/oauth/v2/authorize",
+    tokenUrl: "https://slack.com/api/oauth.v2.access",
+    revocationUrl: "https://slack.com/api/auth.revoke",
+    userinfoUrl: "https://slack.com/api/auth.test",
+    scopes: ["channels:history", "channels:read", "chat:write"],
+    scopeSeparator: ",",
+    tokenAuthStyle: "body",
+    tokenBodyFormat: "form",
+    setupHints: [
+      "Slack expects comma-separated scopes in the authorize URL — this preset sets that separator.",
+      "The listed scopes are bot-token scopes; add user-token scopes separately in the Slack app config if you need them.",
+      "Register the app at api.slack.com/apps and add the swarm redirect URI under OAuth & Permissions.",
+    ],
+  },
+  {
+    id: "github",
+    displayName: "GitHub",
+    provider: "github",
+    authorizeUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    userinfoUrl: "https://api.github.com/user",
+    scopes: ["repo", "read:org", "read:user"],
+    scopeSeparator: " ",
+    tokenAuthStyle: "body",
+    tokenBodyFormat: "form",
+    setupHints: [
+      "Classic GitHub OAuth apps issue long-lived tokens with no expiry and no refresh token; use a GitHub App instead if you need rotation.",
+      "GitHub's token endpoint returns form-encoded data unless the request sends Accept: application/json.",
+      "Register at github.com/settings/developers → OAuth Apps and set the swarm redirect URI as the Authorization callback URL.",
+    ],
+  },
+  {
+    id: "jira",
+    displayName: "Jira (Atlassian)",
+    provider: "jira",
+    authorizeUrl: "https://auth.atlassian.com/authorize",
+    tokenUrl: "https://auth.atlassian.com/oauth/token",
+    scopes: ["read:jira-work", "write:jira-work", "read:jira-user", "offline_access"],
+    scopeSeparator: " ",
+    tokenAuthStyle: "body",
+    tokenBodyFormat: "form",
+    requiresRefreshTokenRotation: true,
+    extraParams: { audience: "api.atlassian.com", prompt: "consent" },
+    setupHints: [
+      "Atlassian 3LO rotates refresh tokens on every refresh — this preset enables rotation enforcement so a refresh that omits a new token fails loudly instead of silently invalidating the grant.",
+      "Include the offline_access scope or you won't receive a refresh token; audience=api.atlassian.com is required and set here.",
+      "Refresh tokens expire after 90 days of inactivity — the swarm keep-alive sweep refreshes idle grants to stay ahead of this.",
+      "Jira is a reserved provider: configure it through the dedicated tracker integration flow, not the generic OAuth apps route.",
+    ],
+  },
+  {
+    id: "linear",
+    displayName: "Linear",
+    provider: "linear",
+    authorizeUrl: "https://linear.app/oauth/authorize",
+    tokenUrl: "https://api.linear.app/oauth/token",
+    revocationUrl: "https://api.linear.app/oauth/revoke",
+    scopes: ["read", "write"],
+    scopeSeparator: ",",
+    tokenAuthStyle: "body",
+    tokenBodyFormat: "form",
+    extraParams: { actor: "app" },
+    setupHints: [
+      "Linear requires comma-separated scopes in the authorize URL — this preset sets that separator.",
+      "actor=app makes the swarm act as the application; set actor=user to act on behalf of the authorizing user.",
+      "Linear is a reserved provider: configure it through the dedicated tracker integration flow, not the generic OAuth apps route.",
+    ],
+  },
+  {
+    id: "notion",
+    displayName: "Notion",
+    provider: "notion",
+    authorizeUrl: "https://api.notion.com/v1/oauth/authorize",
+    tokenUrl: "https://api.notion.com/v1/oauth/token",
+    scopes: [],
+    scopeSeparator: " ",
+    tokenAuthStyle: "basic",
+    tokenBodyFormat: "json",
+    extraParams: { owner: "user" },
+    setupHints: [
+      "Notion's token endpoint requires HTTP Basic client authentication and a JSON request body — this preset sets tokenAuthStyle=basic and tokenBodyFormat=json.",
+      "Notion has no OAuth scopes; capability is configured on the integration in Notion's developer settings.",
+      "owner=user is required to receive a user-scoped token and is set here.",
+    ],
+  },
+];
+
+/** All curated presets (stable order). */
+export function listOAuthPresets(): OAuthPreset[] {
+  return OAUTH_PRESETS.map((preset) => ({ ...preset }));
+}
+
+/** All valid preset ids, for validation error messages + pickers. */
+export function listOAuthPresetIds(): string[] {
+  return OAUTH_PRESETS.map((preset) => preset.id);
+}
+
+/** Look up a preset by id, or `null` when unknown. */
+export function getOAuthPreset(id: string): OAuthPreset | null {
+  return OAUTH_PRESETS.find((preset) => preset.id === id) ?? null;
+}
+
+function mergeExtraParams(
+  base: Record<string, string> | undefined,
+  override: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!base && !override) return undefined;
+  return { ...(base ?? {}), ...(override ?? {}) };
+}
+
+/**
+ * Merge a preset with explicit caller overrides. Explicit fields always win;
+ * `extraParams` merges per-key (override keys replace preset keys). The result
+ * is always tagged `source: 'curated-prefill'`.
+ */
+export function hydrateOAuthAppFromPreset(
+  preset: OAuthPreset,
+  overrides: OAuthPresetOverrides = {},
+): HydratedOAuthApp {
+  return {
+    provider: overrides.provider ?? preset.provider,
+    authorizeUrl: overrides.authorizeUrl ?? preset.authorizeUrl,
+    tokenUrl: overrides.tokenUrl ?? preset.tokenUrl,
+    revocationUrl: overrides.revocationUrl ?? preset.revocationUrl,
+    userinfoUrl: overrides.userinfoUrl ?? preset.userinfoUrl,
+    scopes: overrides.scopes ?? [...preset.scopes],
+    scopeSeparator: overrides.scopeSeparator ?? preset.scopeSeparator,
+    tokenAuthStyle: overrides.tokenAuthStyle ?? preset.tokenAuthStyle,
+    tokenBodyFormat: overrides.tokenBodyFormat ?? preset.tokenBodyFormat,
+    requiresRefreshTokenRotation:
+      overrides.requiresRefreshTokenRotation ?? preset.requiresRefreshTokenRotation,
+    extraParams: mergeExtraParams(preset.extraParams, overrides.extraParams),
+    source: "curated-prefill",
+    setupHints: [...preset.setupHints],
+  };
+}

package/src/oauth/wrapper.ts

@@ -1,5 +1,12 @@
 import * as oauth from "oauth4webapi";
-import { storeOAuthTokens, updateOAuthTokensAfterRefresh } from "../be/db-queries/oauth";
+import {
+  consumeOAuthPending,
+  createOAuthPending,
+  getOAuthAppIdByProvider,
+  type OAuthPendingFlow,
+  storeOAuthTokens,
+  updateOAuthTokensAfterRefresh,
+} from "../be/db-queries/oauth";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -45,46 +52,50 @@ export interface OAuthProviderConfig {
   tokenBodyFormat?: "form" | "json";
 }
 
-interface PendingState {
-  codeVerifier: string;
-  config: OAuthProviderConfig;
-  createdAt: number;
-}
-
-// ─── In-memory pending state (PKCE code verifiers keyed by state) ────────────
-
-const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
-const pendingStates = new Map<string, PendingState>();
-
-/** Remove expired entries from the pending state map */
-function cleanupExpiredStates(): void {
-  const now = Date.now();
-  for (const [key, entry] of pendingStates) {
-    if (now - entry.createdAt > STATE_TTL_MS) {
-      pendingStates.delete(key);
-    }
-  }
+/**
+ * Options controlling how the pending PKCE session is keyed. When `appId` is
+ * omitted it is resolved from `config.provider` (single-app-per-provider
+ * callers). `label` selects which authorization the callback upserts into,
+ * enabling N labeled authorizations per app.
+ */
+export interface BuildAuthorizationUrlOptions {
+  appId?: string;
+  label?: string;
+  flow?: OAuthPendingFlow;
+  finalRedirect?: string | null;
+  userId?: string | null;
+  nonce?: string | null;
 }
 
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
- * Build an OAuth 2.0 authorization URL with PKCE (S256).
- * Stores the pending state + code verifier in-memory for later exchange.
+ * Build an OAuth 2.0 authorization URL with PKCE (S256). Persists a DB-backed
+ * pending row (encrypted code verifier) keyed by `state` for later exchange by
+ * the static callback handler — survives process restarts.
  */
 export async function buildAuthorizationUrl(
   config: OAuthProviderConfig,
+  options: BuildAuthorizationUrlOptions = {},
 ): Promise<{ url: string; state: string; codeVerifier: string }> {
-  cleanupExpiredStates();
-
   const state = oauth.generateRandomState();
   const codeVerifier = oauth.generateRandomCodeVerifier();
   const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier);
 
-  pendingStates.set(state, {
+  const appId = options.appId ?? getOAuthAppIdByProvider(config.provider);
+  if (!appId) {
+    throw new Error(`OAuth app ${config.provider} is not configured`);
+  }
+  createOAuthPending({
+    state,
+    appId,
+    label: options.label ?? "default",
+    flow: options.flow ?? "generic",
     codeVerifier,
-    config,
-    createdAt: Date.now(),
+    nonce: options.nonce ?? null,
+    redirectUri: config.redirectUri,
+    finalRedirect: options.finalRedirect ?? null,
+    userId: options.userId ?? null,
   });
 
   const url = new URL(config.authorizeUrl);
@@ -106,11 +117,6 @@ export async function buildAuthorizationUrl(
   return { url: url.toString(), state, codeVerifier };
 }
 
-/**
- * Exchange an authorization code for tokens.
- * Validates the state against our pending map, calls the token endpoint,
- * and persists tokens via storeOAuthTokens().
- */
 /**
  * Build headers + body for a token-endpoint request, honoring the provider's
  * client-auth style (body params vs HTTP Basic) and body encoding (form vs JSON).
@@ -123,7 +129,11 @@ function tokenRequestInit(
   const bodyParams = useBasic
     ? params
     : { ...params, client_id: config.clientId, client_secret: config.clientSecret };
-  const headers: Record<string, string> = {};
+  // Always request a JSON token response. RFC 6749 responses are JSON, but some
+  // providers (notably GitHub) default to form-encoded and only return JSON when
+  // Accept: application/json is sent — without this the unconditional
+  // response.json() in exchange/refresh would throw on their token payload.
+  const headers: Record<string, string> = { Accept: "application/json" };
   if (useBasic) {
     headers.Authorization = `Basic ${Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64")}`;
   }
@@ -135,71 +145,158 @@ function tokenRequestInit(
   return { headers, body: new URLSearchParams(bodyParams).toString() };
 }
 
+export interface OAuthTokenResponse {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+  tokenType?: string;
+  /** OIDC id_token, when the provider returns one (used for identity capture). */
+  idToken?: string;
+}
+
+/**
+ * Exchange an authorization code for tokens. Pure protocol mechanics — does NOT
+ * touch the DB. The caller (static callback handler) consumes the pending row,
+ * passes the stored `codeVerifier` + `redirectUri`, and persists the tokens
+ * onto the target authorization.
+ */
+export async function exchangeAuthorizationCode(
+  config: OAuthProviderConfig,
+  params: { code: string; codeVerifier: string; redirectUri: string },
+): Promise<OAuthTokenResponse> {
+  const response = await fetch(config.tokenUrl, {
+    method: "POST",
+    ...tokenRequestInit(config, {
+      grant_type: "authorization_code",
+      redirect_uri: params.redirectUri,
+      code: params.code,
+      code_verifier: params.codeVerifier,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${errorText}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    scope?: string;
+    refresh_token?: string;
+    id_token?: string;
+  };
+
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresIn: data.expires_in,
+    scope: data.scope,
+    tokenType: data.token_type,
+    idToken: data.id_token,
+  };
+}
+
+/**
+ * Backward-compatible code exchange for provider-string callers (tracker
+ * callbacks). Consumes the DB-backed pending row by `state`, exchanges the
+ * code, and persists onto the provider's `default` authorization. New
+ * multi-authorization flows use {@link exchangeAuthorizationCode} directly.
+ */
 export async function exchangeCode(
   config: OAuthProviderConfig,
   code: string,
   state: string,
-): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
-  const pending = pendingStates.get(state);
+): Promise<OAuthTokenResponse> {
+  const pending = consumeOAuthPending(state);
   if (!pending) {
     throw new Error("Invalid or expired OAuth state");
   }
-  pendingStates.delete(state);
-
-  const { codeVerifier } = pending;
+  const tokens = await exchangeAuthorizationCode(config, {
+    code,
+    codeVerifier: pending.codeVerifier,
+    redirectUri: pending.redirectUri,
+  });
+  // No `expires_in` → non-expiring token: persist NULL (never proactively
+  // refresh) rather than fabricating an expiry. See oauth-callback.ts.
+  const expiresAt = tokens.expiresIn
+    ? new Date(Date.now() + tokens.expiresIn * 1000).toISOString()
+    : null;
+  storeOAuthTokens(config.provider, {
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken ?? null,
+    expiresAt,
+    scope: tokens.scope ?? null,
+  });
+  return tokens;
+}
 
-  // Build token request manually — Linear doesn't use standard OAuth discovery
+/**
+ * Refresh a token using the `refresh_token` grant. Pure protocol mechanics — no
+ * DB writes. The caller persists onto the target authorization (id-keyed). Used
+ * by the per-authorization refresh endpoint.
+ */
+export async function refreshTokenGrant(
+  config: OAuthProviderConfig,
+  refreshToken: string,
+): Promise<OAuthTokenResponse> {
   const response = await fetch(config.tokenUrl, {
     method: "POST",
     ...tokenRequestInit(config, {
-      grant_type: "authorization_code",
-      redirect_uri: config.redirectUri,
-      code,
-      code_verifier: codeVerifier,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
     }),
   });
 
   if (!response.ok) {
     const errorText = await response.text();
-    throw new Error(`Token exchange failed (${response.status}): ${errorText}`);
+    throw new Error(`Token refresh failed (${response.status}): ${errorText}`);
   }
 
   const data = (await response.json()) as {
     access_token: string;
-    token_type: string;
+    token_type?: string;
     expires_in?: number;
     scope?: string;
     refresh_token?: string;
   };
 
-  // Persist tokens
-  const expiresAt = data.expires_in
-    ? new Date(Date.now() + data.expires_in * 1000).toISOString()
-    : new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(); // default 24h
-
-  storeOAuthTokens(config.provider, {
-    accessToken: data.access_token,
-    refreshToken: data.refresh_token ?? null,
-    expiresAt,
-    scope: data.scope ?? null,
-  });
+  if (typeof data.access_token !== "string" || data.access_token.length === 0) {
+    throw new Error(`Token refresh failed: ${config.provider} response missing access_token`);
+  }
 
   return {
     accessToken: data.access_token,
     refreshToken: data.refresh_token,
     expiresIn: data.expires_in,
     scope: data.scope,
+    tokenType: data.token_type,
   };
 }
 
 /**
- * Refresh an access token using a stored refresh token.
- * Persists the new tokens via storeOAuthTokens().
+ * Call the token endpoint to exchange a refresh token, validate the response
+ * (access token present; rotated refresh token present when the provider
+ * requires rotation), and return the normalized result WITHOUT persisting.
+ *
+ * Persistence is the caller's job — provider-string callers persist via
+ * {@link refreshAccessToken}; authorization-keyed callers
+ * (src/oauth/ensure-token.ts) persist against a specific authorization id.
+ * Throws on any HTTP error, missing access token, or a missing rotated refresh
+ * token.
  */
-export async function refreshAccessToken(
+export async function performTokenRefreshRequest(
   config: OAuthProviderConfig,
   refreshToken: string,
-): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
+): Promise<{
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+  expiresAt: string | null;
+}> {
   const response = await fetch(config.tokenUrl, {
     method: "POST",
     ...tokenRequestInit(config, {
@@ -234,17 +331,42 @@ export async function refreshAccessToken(
     );
   }
 
+  // No `expires_in` → non-expiring token stays non-expiring across refreshes:
+  // NULL, not a fabricated 24h expiry that would re-arm the sweep against a
+  // token the provider never expires.
   const expiresAt = data.expires_in
     ? new Date(Date.now() + data.expires_in * 1000).toISOString()
-    : new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+    : null;
 
-  const nextRefreshToken = data.refresh_token ?? refreshToken;
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresIn: data.expires_in,
+    scope: data.scope,
+    expiresAt,
+  };
+}
+
+/**
+ * Refresh an access token using a stored refresh token.
+ * Persists the new tokens via updateOAuthTokensAfterRefresh() (provider-keyed
+ * default-authorization path).
+ */
+export async function refreshAccessToken(
+  config: OAuthProviderConfig,
+  refreshToken: string,
+  expectedTokenVersion?: number,
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
+  const refreshed = await performTokenRefreshRequest(config, refreshToken);
+
+  const nextRefreshToken = refreshed.refreshToken ?? refreshToken;
   try {
     updateOAuthTokensAfterRefresh(config.provider, refreshToken, {
-      accessToken: data.access_token,
+      accessToken: refreshed.accessToken,
       refreshToken: nextRefreshToken,
-      expiresAt,
-      scope: data.scope ?? null,
+      expiresAt: refreshed.expiresAt,
+      scope: refreshed.scope ?? null,
+      ...(expectedTokenVersion !== undefined ? { expectedTokenVersion } : {}),
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -255,19 +377,18 @@ export async function refreshAccessToken(
   }
 
   return {
-    accessToken: data.access_token,
-    refreshToken: data.refresh_token,
-    expiresIn: data.expires_in,
-    scope: data.scope,
+    accessToken: refreshed.accessToken,
+    refreshToken: refreshed.refreshToken,
+    expiresIn: refreshed.expiresIn,
+    scope: refreshed.scope,
   };
 }
 
 // ─── Test helpers (exported for unit tests only) ─────────────────────────────
 
-export function _getPendingState(state: string): PendingState | undefined {
-  return pendingStates.get(state);
-}
-
-export function _clearPendingStates(): void {
-  pendingStates.clear();
-}
+/**
+ * Deprecated no-op retained for backward compatibility. Pending PKCE state now
+ * lives in the `oauth_pending` table (per-test DBs isolate it), so there is no
+ * in-memory map to clear.
+ */
+export function _clearPendingStates(): void {}