@introspection-ai/recipes 0.19.2 → 0.20.0

package/dist/mcp-chunks/chunk-VJ2TSA5R.js

@@ -0,0 +1,818 @@
+import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
+import {
+  buildOAuthPersistence,
+  buildStaticClientInformation,
+  oauthAccessTokenNeedsRefresh,
+  readCachedAccessTokenWithPersistence,
+  reconcilePersistedTokens,
+  withRefreshLock,
+  withRefreshRequestTimeout
+} from "./chunk-MNAVFYYV.js";
+import {
+  sameOAuthTokenGeneration
+} from "./chunk-B4XFULJ6.js";
+import {
+  isUnauthorizedError
+} from "./chunk-MWD5PZ4G.js";
+import {
+  IssuerMismatchError,
+  auth,
+  validateClientMetadataUrl
+} from "./chunk-K56RW4HB.js";
+import {
+  suppressBrowserLaunchFromEnv
+} from "./chunk-JJG2OEHI.js";
+import {
+  isFileLockTimeoutError
+} from "./chunk-ETYYCEQF.js";
+
+// node_modules/.pnpm/mcporter@0.13.6/node_modules/mcporter/dist/oauth.js
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import http from "node:http";
+import { URL } from "node:url";
+var CALLBACK_HOST = "127.0.0.1";
+var CALLBACK_PATH = "/callback";
+var INTERACTIVE_AUTHORIZATION_TTL_MS = 3e5;
+var OAuthRefreshUnavailableError = class extends Error {
+  serverName;
+  constructor(serverName, options) {
+    super(`Could not refresh OAuth credentials for '${serverName}'. Another process may be refreshing them, or the token endpoint is unreachable. Retry shortly; run 'mcporter auth ${serverName}' if it persists.`, options);
+    this.name = "OAuthRefreshUnavailableError";
+    this.serverName = serverName;
+  }
+};
+var BrowserLaunchSuppressedError = class extends Error {
+  serverName;
+  constructor(serverName) {
+    super(`Authorization required for '${serverName}' but browser launch is suppressed (MCPORTER_OAUTH_NO_BROWSER); run 'mcporter auth ${serverName} --no-browser' to authorize.`);
+    this.name = "BrowserLaunchSuppressedError";
+    this.serverName = serverName;
+  }
+};
+var OAuthRedirectUriMismatchError = class extends Error {
+  constructor(serverName) {
+    super(`OAuth client registration for '${serverName}' used an obsolete redirect URI.`);
+    this.name = "OAuthRedirectUriMismatchError";
+  }
+};
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+function openExternal(url, platform = process.platform, launch = spawn) {
+  const stdio = "ignore";
+  try {
+    if (platform === "darwin") {
+      const child = launch("open", [url], { stdio, detached: true });
+      child.unref();
+    } else if (platform === "win32") {
+      const child = launch("rundll32", ["url.dll,FileProtocolHandler", url], {
+        stdio,
+        detached: true,
+        windowsHide: true
+      });
+      child.unref();
+    } else {
+      try {
+        const child = launch("xdg-open", [url], { stdio, detached: true });
+        child.on("error", () => {
+        });
+        child.unref();
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+var PersistentOAuthClientProvider = class _PersistentOAuthClientProvider {
+  definition;
+  usesDynamicPort;
+  options;
+  metadata;
+  logger;
+  persistence;
+  redirectUrlValue;
+  authorizationDeferred = null;
+  authorizationRedirectStarted = false;
+  // One interactive authorization transaction per provider: concurrent SDK auth() flows
+  // (background GET reconnect + bridged POST both hitting 401) must not each open a
+  // prompt, because only one persisted PKCE verifier can complete (issue #247).
+  interactiveAuthorization = null;
+  pendingVerifiersByChallenge = /* @__PURE__ */ new Map();
+  server;
+  constructor(definition, persistence, redirectUrl, logger, usesDynamicPort, options = {}) {
+    this.definition = definition;
+    this.usesDynamicPort = usesDynamicPort;
+    this.options = options;
+    this.redirectUrlValue = redirectUrl;
+    this.logger = logger;
+    this.persistence = persistence;
+    this.metadata = {
+      client_name: definition.clientName ?? `mcporter (${definition.name})`,
+      redirect_uris: [this.redirectUrlValue.toString()],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      // Omit scope so the MCP SDK can derive it from the server's metadata
+      // (resource metadata scopes_supported or auth server scopes_supported).
+      // Hardcoding 'mcp:tools' breaks providers like Granola whose auth server
+      // does not recognise that scope value.
+      // If oauthScope is explicitly configured, prefer that exact value.
+      ...definition.oauthScope !== void 0 ? { scope: definition.oauthScope || void 0 } : {}
+    };
+  }
+  static async create(definition, logger, options = {}) {
+    validateClientMetadataUrl(definition.oauthClientMetadataUrl);
+    const persistence = await buildOAuthPersistence(definition, logger);
+    const server = http.createServer();
+    const overrideRedirect = definition.oauthRedirectUrl ? new URL(definition.oauthRedirectUrl) : null;
+    const listenHost = overrideRedirect?.hostname ?? CALLBACK_HOST;
+    const overridePort = overrideRedirect?.port ?? "";
+    const usesDynamicPort = !overrideRedirect || overridePort === "" || overridePort === "0";
+    const desiredPort = usesDynamicPort ? void 0 : Number.parseInt(overridePort, 10);
+    const callbackPath = overrideRedirect?.pathname && overrideRedirect.pathname !== "/" ? overrideRedirect.pathname : CALLBACK_PATH;
+    const port = await new Promise((resolve, reject) => {
+      server.listen(desiredPort ?? 0, listenHost, () => {
+        const address = server.address();
+        if (typeof address === "object" && address && "port" in address) {
+          resolve(address.port);
+        } else {
+          reject(new Error("Failed to determine callback port"));
+        }
+      });
+      server.once("error", (error) => reject(error));
+    });
+    const redirectUrl = overrideRedirect ? new URL(overrideRedirect.toString()) : new URL(`http://${listenHost}:${port}${callbackPath}`);
+    if (usesDynamicPort) {
+      redirectUrl.port = String(port);
+    }
+    if (!overrideRedirect || overrideRedirect.pathname === "/" || overrideRedirect.pathname === "") {
+      redirectUrl.pathname = callbackPath;
+    }
+    const provider = new _PersistentOAuthClientProvider(definition, persistence, redirectUrl, logger, usesDynamicPort, options);
+    provider.attachServer(server);
+    return {
+      provider,
+      close: async () => {
+        await provider.close();
+      }
+    };
+  }
+  // attachServer listens for the OAuth redirect and resolves/rejects the deferred code promise.
+  attachServer(server) {
+    this.server = server;
+    server.on("request", async (req, res) => {
+      try {
+        const url = req.url ?? "";
+        const parsed = new URL(url, this.redirectUrlValue);
+        const expectedPath = this.redirectUrlValue.pathname || "/callback";
+        if (parsed.pathname !== expectedPath) {
+          res.statusCode = 404;
+          res.end("Not found");
+          return;
+        }
+        const code = parsed.searchParams.get("code");
+        const error = parsed.searchParams.get("error");
+        const receivedState = parsed.searchParams.get("state");
+        const iss = parsed.searchParams.get("iss") ?? void 0;
+        const expectedState = await this.persistence.readState();
+        if (expectedState && receivedState !== expectedState) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "text/html");
+          res.end("<html><body><h1>Authorization failed</h1><p>Invalid OAuth state</p></body></html>");
+          this.authorizationDeferred?.reject(new Error("Invalid OAuth state"));
+          this.authorizationDeferred = null;
+          this.clearInteractiveAuthorization();
+          return;
+        }
+        if (code) {
+          this.logger.info(`Received OAuth authorization code for ${this.definition.name}`);
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "text/html");
+          res.end("<html><body><h1>Authorization successful</h1><p>You can return to the CLI.</p></body></html>");
+          this.authorizationDeferred?.resolve({ code, iss });
+          this.authorizationDeferred = null;
+          this.clearInteractiveAuthorization();
+        } else if (error) {
+          res.statusCode = 400;
+          res.setHeader("Content-Type", "text/html");
+          res.end("<html><body><h1>Authorization failed</h1><p>Return to the CLI for details.</p></body></html>");
+          this.authorizationDeferred?.reject(new Error("OAuth authorization failed."));
+          this.authorizationDeferred = null;
+          this.clearInteractiveAuthorization();
+        } else {
+          res.statusCode = 400;
+          res.end("Missing authorization code");
+          this.authorizationDeferred?.reject(new Error("Missing authorization code"));
+          this.authorizationDeferred = null;
+          this.clearInteractiveAuthorization();
+        }
+      } catch (error) {
+        this.authorizationDeferred?.reject(error);
+        this.authorizationDeferred = null;
+        this.clearInteractiveAuthorization();
+      }
+    });
+  }
+  get redirectUrl() {
+    return this.redirectUrlValue;
+  }
+  get clientMetadata() {
+    return this.metadata;
+  }
+  get clientMetadataUrl() {
+    return this.definition.oauthClientMetadataUrl;
+  }
+  async state() {
+    const existing = await this.persistence.readState();
+    if (existing) {
+      return existing;
+    }
+    const state = randomUUID();
+    await this.persistence.saveState(state);
+    return state;
+  }
+  async clientInformation(ctx) {
+    const staticClient = buildStaticClientInformation(this.definition, { redirectUrl: this.redirectUrlValue });
+    if (staticClient) {
+      return { ...staticClient, ...ctx ? { issuer: ctx.issuer } : {} };
+    }
+    const stored = await this.persistence.readClientInfo();
+    if (ctx && stored?.issuer && !issuersMatch(stored.issuer, ctx.issuer)) {
+      await this.persistence.clear("client");
+      this.logger.info(`Discarded OAuth client registration for ${this.definition.name} after issuer changed.`);
+      return void 0;
+    }
+    if (!stored) {
+      const tokens = await this.persistence.readTokens();
+      if (tokens && typeof tokens.refresh_token === "string" && oauthAccessTokenNeedsRefresh(tokens)) {
+        await this.persistence.clear("tokens");
+        this.logger.info(`Discarded expired OAuth tokens for ${this.definition.name} because no client registration is available.`);
+      }
+    }
+    return stored;
+  }
+  async saveClientInformation(clientInformation) {
+    await this.persistence.saveClientInfo(clientInformation);
+  }
+  async tokens(ctx) {
+    const stored = await this.persistence.readTokens();
+    if (ctx && stored?.issuer && !issuersMatch(stored.issuer, ctx.issuer)) {
+      await this.persistence.clear("tokens");
+      this.logger.info(`Discarded OAuth tokens for ${this.definition.name} after issuer changed.`);
+      return void 0;
+    }
+    return await this.refreshedTokens(stored);
+  }
+  /**
+   * Refreshes an expiring token under the cross-process refresh lock before the
+   * SDK sees it.
+   *
+   * This is the interception point for SDK-driven refresh. The SDK redeems a
+   * rotating refresh token itself whenever tokens() hands it an expired one.
+   * Returning an already-refreshed token starves the proactive branch, so the
+   * redemption happens once under the lock instead of racing every other
+   * process that shares the credential. The distinct fresh-token post-401 path
+   * is wrapped by onOAuthUnauthorized().
+   *
+   * The locked transaction is re-entrant per call chain, so an SDK auth() flow
+   * that already holds the lock does not deadlock on this read.
+   *
+   * Returning an expired token that still carries a refresh token is never
+   * safe here: the SDK redeems whenever this method yields a refresh token — it
+   * never checks expiry — so the redemption would land outside the lock. That
+   * cannot be avoided by withholding the refresh token either, because the SDK
+   * re-persists this method's return value when `issuer` is unset and would
+   * destroy the token instead. So when a due refresh does not produce a usable
+   * token, this fails the connect rather than offering a redeemable stale one.
+   */
+  async refreshedTokens(stored) {
+    if (!stored || this.definition.auth === "refreshable_bearer") {
+      return stored;
+    }
+    try {
+      await readCachedAccessTokenWithPersistence(this.definition, this.persistence);
+    } catch (error) {
+      this.logger.warn(`Could not refresh OAuth tokens for ${this.definition.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const latest = await this.persistence.readTokens();
+    if (latest && typeof latest.refresh_token === "string" && oauthAccessTokenNeedsRefresh(latest)) {
+      throw new OAuthRefreshUnavailableError(this.definition.name);
+    }
+    return latest;
+  }
+  async saveTokens(tokens) {
+    await this.persistence.saveTokens(tokens);
+    this.logger.info(`Saved OAuth tokens for ${this.definition.name} (${this.persistence.describe()})`);
+  }
+  /**
+   * Keeps the SDK's post-401 refresh transaction inside the same cross-process
+   * lock as proactive refresh. The SDK supplies the exact tokens attached to
+   * the rejected request, so a waiter can distinguish its stale generation
+   * from the winner another process persisted while it waited.
+   */
+  async onOAuthUnauthorized(context, continueDefault) {
+    const rejected = context.presentedTokens;
+    if (!rejected) {
+      throw new OAuthRefreshUnavailableError(this.definition.name);
+    }
+    try {
+      await withRefreshLock(this.definition, async () => {
+        const latest = await reconcilePersistedTokens(this.definition, this.persistence);
+        if (!latest) {
+          throw new OAuthRefreshUnavailableError(this.definition.name);
+        }
+        if (!sameOAuthTokenGeneration(latest, rejected)) {
+          return;
+        }
+        await continueDefault({ fetchFn: withRefreshRequestTimeout(context.fetchFn) });
+      });
+    } catch (error) {
+      if (isFileLockTimeoutError(error)) {
+        throw new OAuthRefreshUnavailableError(this.definition.name, { cause: error });
+      }
+      throw error;
+    }
+  }
+  async redirectToAuthorization(authorizationUrl) {
+    await this.invalidateObsoleteDynamicRegistration();
+    this.authorizationRedirectStarted = true;
+    this.ensureAuthorizationDeferred();
+    const challenge = authorizationUrl.searchParams.get("code_challenge");
+    if (this.hasActiveInteractiveAuthorization()) {
+      if (challenge) {
+        this.pendingVerifiersByChallenge.delete(challenge);
+      }
+      this.logger.info(`Authorization already pending for ${this.definition.name}; suppressing duplicate prompt.`);
+      return;
+    }
+    this.interactiveAuthorization = { challenge, claimedAt: Date.now() };
+    const claimedVerifier = challenge ? this.pendingVerifiersByChallenge.get(challenge) : void 0;
+    if (challenge) {
+      this.pendingVerifiersByChallenge.delete(challenge);
+    }
+    if (claimedVerifier) {
+      await this.persistence.saveCodeVerifier(claimedVerifier);
+    }
+    const request = {
+      authorizationUrl: authorizationUrl.toString(),
+      redirectUrl: this.redirectUrlValue.toString()
+    };
+    if (this.options.suppressBrowserLaunch ?? suppressBrowserLaunchFromEnv()) {
+      if (this.options.onAuthorizationUrl) {
+        await this.options.onAuthorizationUrl(request);
+        return;
+      }
+      const suppressed = new BrowserLaunchSuppressedError(this.definition.name);
+      this.logger.warn(suppressed.message);
+      const deferred = this.ensureAuthorizationDeferred();
+      deferred.promise.catch(() => {
+      });
+      deferred.reject(suppressed);
+      this.clearInteractiveAuthorization();
+      return;
+    }
+    this.logger.info(`Authorization required for ${this.definition.name}. Opening browser...`);
+    __oauthInternals.openExternal(request.authorizationUrl);
+    this.logger.warn(`If the browser did not open, visit ${request.authorizationUrl} manually.`);
+  }
+  hasAuthorizationRedirectStarted() {
+    return this.authorizationRedirectStarted;
+  }
+  async saveCodeVerifier(codeVerifier) {
+    this.pendingVerifiersByChallenge.set(challengeForVerifier(codeVerifier), codeVerifier);
+    if (this.hasActiveInteractiveAuthorization()) {
+      return;
+    }
+    await this.persistence.saveCodeVerifier(codeVerifier);
+  }
+  async codeVerifier() {
+    const value = await this.persistence.readCodeVerifier();
+    if (!value) {
+      throw new Error(`Missing PKCE code verifier for ${this.definition.name}`);
+    }
+    return value.trim();
+  }
+  // invalidateCredentials removes cached files to force the next OAuth flow.
+  async invalidateCredentials(scope) {
+    if (scope === "all" || scope === "verifier") {
+      this.clearInteractiveAuthorization();
+    }
+    await this.persistence.clear(scope);
+  }
+  async saveDiscoveryState(state) {
+    await this.persistence.saveDiscoveryState(state);
+  }
+  async discoveryState() {
+    return this.persistence.readDiscoveryState();
+  }
+  async saveAuthorizationServerUrl(url) {
+    await this.persistence.saveAuthorizationServerUrl(url);
+  }
+  async authorizationServerUrl() {
+    return this.persistence.readAuthorizationServerUrl();
+  }
+  async saveResourceUrl(url) {
+    await this.persistence.saveResourceUrl(url);
+  }
+  async resourceUrl() {
+    return this.persistence.readResourceUrl();
+  }
+  // waitForAuthorizationCode resolves once the local callback server captures a redirect.
+  // The same deferred is shared with redirectToAuthorization so callback resolution is stable.
+  async waitForAuthorizationCode() {
+    return (await this.waitForAuthorizationResponse()).code;
+  }
+  async waitForAuthorizationResponse() {
+    return this.ensureAuthorizationDeferred().promise;
+  }
+  // close stops the temporary callback server created for the OAuth session.
+  async close() {
+    if (this.authorizationDeferred) {
+      this.authorizationDeferred.reject(new Error("OAuth session closed before receiving authorization code."));
+      this.authorizationDeferred = null;
+      this.clearInteractiveAuthorization();
+    }
+    if (!this.server) {
+      return;
+    }
+    this.server.closeAllConnections?.();
+    const server = this.server;
+    this.server = void 0;
+    await new Promise((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+  ensureAuthorizationDeferred() {
+    if (!this.authorizationDeferred) {
+      this.authorizationDeferred = createDeferred();
+    }
+    return this.authorizationDeferred;
+  }
+  hasActiveInteractiveAuthorization() {
+    if (!this.interactiveAuthorization) {
+      return false;
+    }
+    if (Date.now() - this.interactiveAuthorization.claimedAt > INTERACTIVE_AUTHORIZATION_TTL_MS) {
+      this.interactiveAuthorization = null;
+      return false;
+    }
+    return true;
+  }
+  clearInteractiveAuthorization() {
+    this.interactiveAuthorization = null;
+    this.pendingVerifiersByChallenge.clear();
+  }
+  async invalidateObsoleteDynamicRegistration() {
+    if (!this.usesDynamicPort || this.definition.oauthClientId) {
+      return;
+    }
+    let snapshot;
+    try {
+      snapshot = await this.persistence.readSnapshot();
+    } catch (error) {
+      await this.close();
+      throw error;
+    }
+    const cachedClient = snapshot.clientInfo;
+    if (cachedClient?.client_id === this.definition.oauthClientMetadataUrl) {
+      return;
+    }
+    const cachedRedirect = firstRedirectUri(cachedClient);
+    if (!cachedClient || !cachedRedirect || cachedRedirect === this.redirectUrlValue.toString()) {
+      return;
+    }
+    this.logger.info(`Redirect URI changed (${cachedRedirect} \u2192 ${this.redirectUrlValue.toString()}); replacing obsolete client registration before interactive authorization.`);
+    try {
+      await this.persistence.clearRejectedCredentials(snapshot.tokens, cachedClient);
+    } catch (error) {
+      await this.close();
+      throw error;
+    }
+    throw new OAuthRedirectUriMismatchError(this.definition.name);
+  }
+};
+async function createOAuthSession(definition, logger, options = {}) {
+  const { provider, close } = await PersistentOAuthClientProvider.create(definition, logger, options);
+  const waitForAuthorizationCode = () => provider.waitForAuthorizationCode();
+  const waitForAuthorizationResponse = () => provider.waitForAuthorizationResponse();
+  const hasAuthorizationRedirectStarted = () => provider.hasAuthorizationRedirectStarted();
+  return {
+    provider,
+    waitForAuthorizationCode,
+    waitForAuthorizationResponse,
+    hasAuthorizationRedirectStarted,
+    close
+  };
+}
+function challengeForVerifier(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+function firstRedirectUri(client) {
+  if (!client || typeof client !== "object") {
+    return void 0;
+  }
+  const redirectUris = client.redirect_uris;
+  if (!Array.isArray(redirectUris)) {
+    return void 0;
+  }
+  const [first] = redirectUris;
+  return typeof first === "string" ? first : void 0;
+}
+function issuersMatch(first, second) {
+  return first === second || first.endsWith("/") && first.slice(0, -1) === second || second.endsWith("/") && second.slice(0, -1) === first;
+}
+var __oauthInternals = {
+  openExternal
+};
+
+// node_modules/.pnpm/mcporter@0.13.6/node_modules/mcporter/dist/runtime/oauth.js
+var DEFAULT_OAUTH_CODE_TIMEOUT_MS = 3e5;
+var OAUTH_FLOW_ERROR = /* @__PURE__ */ Symbol("oauth-flow-error");
+var POST_AUTH_CONNECT_ERROR = /* @__PURE__ */ Symbol("post-auth-connect-error");
+var MAX_OAUTH_ERROR_DETAIL_LENGTH = 1200;
+var PROACTIVE_TOKEN_SKEW_SECONDS = 60;
+var OAuthTimeoutError = class extends Error {
+  timeoutMs;
+  serverName;
+  constructor(serverName, timeoutMs) {
+    const seconds = Math.round(timeoutMs / 1e3);
+    super(`OAuth authorization for '${serverName}' timed out after ${seconds}s; aborting.`);
+    this.name = "OAuthTimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.serverName = serverName;
+  }
+};
+var OAuthAuthorizationNotStartedError = class extends Error {
+  serverName;
+  constructor(serverName, cause) {
+    const causeMessage = formatOAuthErrorDetail(cause);
+    const detail = causeMessage ? ` Last error: ${causeMessage}` : "";
+    super(`OAuth authorization for '${serverName}' did not produce an authorization URL; aborting instead of waiting for a browser callback.${detail}`);
+    this.name = "OAuthAuthorizationNotStartedError";
+    this.serverName = serverName;
+  }
+};
+function formatOAuthErrorDetail(cause) {
+  if (!(cause instanceof Error) || !cause.message) {
+    return "";
+  }
+  return truncateOAuthErrorDetail(cause.message);
+}
+function truncateOAuthErrorDetail(message) {
+  if (message.length <= MAX_OAUTH_ERROR_DETAIL_LENGTH) {
+    return message;
+  }
+  const truncated = message.length - MAX_OAUTH_ERROR_DETAIL_LENGTH;
+  return `${message.slice(0, MAX_OAUTH_ERROR_DETAIL_LENGTH)}... [truncated ${truncated} chars]`;
+}
+function markOAuthFlowError(error) {
+  return markError(error, OAUTH_FLOW_ERROR);
+}
+function isOAuthFlowError(error) {
+  return hasErrorMarker(error, OAUTH_FLOW_ERROR);
+}
+function markPostAuthConnectError(error) {
+  return markError(error, POST_AUTH_CONNECT_ERROR);
+}
+function isPostAuthConnectError(error) {
+  return hasErrorMarker(error, POST_AUTH_CONNECT_ERROR);
+}
+function markError(error, marker) {
+  if (!error || typeof error !== "object" && typeof error !== "function") {
+    return error;
+  }
+  Object.defineProperty(error, marker, {
+    value: true,
+    enumerable: false,
+    configurable: true
+  });
+  return error;
+}
+function hasErrorMarker(error, marker) {
+  return !!error && (typeof error === "object" || typeof error === "function") && marker in error && Boolean(error[marker]);
+}
+function hasUsableCachedAccessToken(tokens) {
+  if (!tokens || typeof tokens.access_token !== "string" || tokens.access_token.trim().length === 0) {
+    return false;
+  }
+  const stored = tokens;
+  const expiresAt = typeof stored.expires_at === "number" ? stored.expires_at : stored.expiresAt;
+  return typeof expiresAt === "number" && expiresAt > Math.floor(Date.now() / 1e3) + PROACTIVE_TOKEN_SKEW_SECONDS;
+}
+async function connectWithAuth(client, transport, session, logger, options = {}) {
+  const { serverName, maxAttempts = 3, oauthTimeoutMs = DEFAULT_OAUTH_CODE_TIMEOUT_MS, recreateTransport } = options;
+  const state = {
+    activeTransport: transport,
+    attempt: 0,
+    hasCompletedAuthFlow: false,
+    repairedRedirectMismatch: false
+  };
+  while (true) {
+    try {
+      await attemptTransportConnect(client, state, options.signal);
+      if (session && !state.hasCompletedAuthFlow && options.serverUrl) {
+        await completeProactiveAuthorization(state.activeTransport, session, logger, {
+          serverName,
+          oauthTimeoutMs,
+          serverUrl: options.serverUrl,
+          fetchFn: options.fetchFn
+        });
+        state.hasCompletedAuthFlow = true;
+      }
+      if (session && state.hasCompletedAuthFlow) {
+        await session.close().catch(() => {
+        });
+      }
+      return state.activeTransport;
+    } catch (error) {
+      if (error instanceof OAuthRedirectUriMismatchError) {
+        if (state.repairedRedirectMismatch || !recreateTransport) {
+          await closeReplacementTransport(transport, state.activeTransport);
+          throw markOAuthFlowError(error);
+        }
+        state.repairedRedirectMismatch = true;
+        state.activeTransport = await recreateOAuthTransport(state.activeTransport, recreateTransport);
+        continue;
+      }
+      const unauthorized = isUnauthorizedError(error);
+      if (!shouldRetryAuthorization(state, unauthorized, session)) {
+        await closeReplacementTransport(transport, state.activeTransport);
+        throw state.hasCompletedAuthFlow && !unauthorized ? markPostAuthConnectError(error) : error;
+      }
+      state.attempt += 1;
+      if (state.attempt > maxAttempts) {
+        await closeReplacementTransport(transport, state.activeTransport);
+        throw state.hasCompletedAuthFlow ? markPostAuthConnectError(error) : error;
+      }
+      if (session.hasAuthorizationRedirectStarted?.() !== false) {
+        logger.warn(`OAuth authorization required for '${serverName ?? "unknown"}'. Waiting for browser approval...`);
+      }
+      try {
+        state.activeTransport = await completeAuthorizationChallenge(state.activeTransport, session, logger, error, {
+          serverName,
+          oauthTimeoutMs,
+          recreateTransport
+        });
+        state.hasCompletedAuthFlow = true;
+        logger.info("Authorization code accepted. Retrying connection...");
+      } catch (authError) {
+        const message = authError instanceof OAuthAuthorizationNotStartedError ? "OAuth authorization could not start." : "OAuth authorization failed while waiting for callback.";
+        logger.error(message, authError);
+        await closeReplacementTransport(transport, state.activeTransport);
+        throw markOAuthFlowError(authError);
+      }
+    }
+  }
+}
+async function attemptTransportConnect(client, state, signal) {
+  if (signal) {
+    await client.connect(state.activeTransport, { signal });
+  } else {
+    await client.connect(state.activeTransport);
+  }
+  return state.activeTransport;
+}
+function shouldRetryAuthorization(_state, unauthorized, session) {
+  if (!session || !unauthorized) {
+    return false;
+  }
+  return true;
+}
+async function closeReplacementTransport(originalTransport, activeTransport) {
+  if (activeTransport === originalTransport) {
+    return;
+  }
+  await activeTransport.close().catch(() => {
+  });
+}
+async function recreateOAuthTransport(activeTransport, recreateTransport) {
+  const replacement = await recreateTransport(activeTransport);
+  await activeTransport.close().catch(() => {
+  });
+  return replacement;
+}
+async function completeAuthorizationChallenge(transport, session, logger, connectError, options) {
+  if (session.hasAuthorizationRedirectStarted?.() === false) {
+    throw new OAuthAuthorizationNotStartedError(options.serverName ?? "unknown", connectError);
+  }
+  const response = await waitForAuthorizationResponseWithTimeout(session, logger, options.serverName, options.oauthTimeoutMs ?? DEFAULT_OAUTH_CODE_TIMEOUT_MS);
+  if (typeof transport.finishAuth !== "function") {
+    logger.warn("Transport does not support finishAuth; cannot complete OAuth flow automatically.");
+    throw connectError;
+  }
+  await finishAuthorization(transport, response, options.serverName);
+  if (!options.recreateTransport) {
+    return transport;
+  }
+  const nextTransport = await options.recreateTransport(transport);
+  await transport.close().catch(() => {
+  });
+  return nextTransport;
+}
+async function completeProactiveAuthorization(transport, session, logger, options) {
+  const serverUrl = options.serverUrl;
+  if (!serverUrl) {
+    return;
+  }
+  try {
+    const cachedTokens = await session.provider.tokens?.();
+    if (hasUsableCachedAccessToken(cachedTokens)) {
+      return;
+    }
+    const runAuth = () => auth(session.provider, {
+      serverUrl,
+      fetchFn: options.fetchFn
+    });
+    let result;
+    try {
+      result = await runAuth();
+    } catch (error) {
+      if (!(error instanceof OAuthRedirectUriMismatchError)) {
+        throw error;
+      }
+      result = await runAuth();
+    }
+    if (result !== "REDIRECT") {
+      await session.close().catch(() => {
+      });
+      return;
+    }
+    if (session.hasAuthorizationRedirectStarted?.() === false) {
+      throw new OAuthAuthorizationNotStartedError(options.serverName ?? "unknown");
+    }
+    logger.warn(`OAuth authorization required for '${options.serverName ?? "unknown"}'. Waiting for browser approval...`);
+    if (typeof transport.finishAuth !== "function") {
+      throw new Error("Transport does not support finishAuth; cannot complete OAuth flow automatically.");
+    }
+    const response = await waitForAuthorizationResponseWithTimeout(session, logger, options.serverName, options.oauthTimeoutMs ?? DEFAULT_OAUTH_CODE_TIMEOUT_MS);
+    await finishAuthorization(transport, response, options.serverName);
+    await session.close().catch(() => {
+    });
+  } catch (error) {
+    throw markOAuthFlowError(error);
+  }
+}
+function waitForAuthorizationResponseWithTimeout(session, logger, serverName, timeoutMs = DEFAULT_OAUTH_CODE_TIMEOUT_MS) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return readAuthorizationResponse(session);
+  }
+  const displayName = serverName ?? "unknown";
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const error = new OAuthTimeoutError(displayName, timeoutMs);
+      logger.warn(error.message);
+      reject(error);
+    }, timeoutMs);
+    readAuthorizationResponse(session).then((response) => {
+      clearTimeout(timer);
+      resolve(response);
+    }, (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+async function readAuthorizationResponse(session) {
+  if (session.waitForAuthorizationResponse)
+    return session.waitForAuthorizationResponse();
+  return { code: await session.waitForAuthorizationCode() };
+}
+async function finishAuthorization(transport, response, serverName) {
+  try {
+    await transport.finishAuth?.(response.code, response.iss);
+  } catch (error) {
+    if (error instanceof IssuerMismatchError && error.kind === "authorization_response") {
+      throw new Error(`OAuth issuer validation failed for '${serverName ?? "unknown"}': expected ${JSON.stringify(error.expected)}, got ${JSON.stringify(error.received)}; the authorization code was not redeemed.`, { cause: error });
+    }
+    throw error;
+  }
+}
+function parseOAuthTimeout(raw) {
+  if (!raw) {
+    return DEFAULT_OAUTH_CODE_TIMEOUT_MS;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_OAUTH_CODE_TIMEOUT_MS;
+  }
+  return parsed;
+}
+function resolveOAuthTimeoutFromEnv() {
+  return parseOAuthTimeout(process.env.MCPORTER_OAUTH_TIMEOUT_MS ?? process.env.MCPORTER_OAUTH_TIMEOUT);
+}
+
+export {
+  createOAuthSession,
+  OAuthTimeoutError,
+  isOAuthFlowError,
+  isPostAuthConnectError,
+  connectWithAuth,
+  resolveOAuthTimeoutFromEnv
+};