anyapi-mcp-server 1.6.0 → 1.6.1

package/build/config.js

@@ -62,7 +62,17 @@ Required:
 Optional:
   --header     HTTP header as "Key: Value" (repeatable)
                Supports \${ENV_VAR} interpolation in values
-  --log        Path to request/response log file (NDJSON format)`;
+  --log        Path to request/response log file (NDJSON format)
+
+OAuth 2.0 (all optional, but client-id/client-secret/token-url are required together):
+  --oauth-client-id      OAuth client ID
+  --oauth-client-secret  OAuth client secret
+  --oauth-token-url      OAuth token endpoint URL
+  --oauth-auth-url       OAuth authorization endpoint URL (authorization_code flow)
+  --oauth-scopes         Comma-separated scopes (e.g. "read,write")
+  --oauth-flow           "authorization_code" (default) or "client_credentials"
+  --oauth-param          Extra auth URL param as "key=value" (repeatable)
+               All OAuth values support \${ENV_VAR} interpolation`;
 export async function loadConfig() {
     const name = getArg("--name");
     const specUrls = getAllArgs("--spec");
@@ -84,11 +94,55 @@ export async function loadConfig() {
         headers[key] = interpolateEnv(value);
     }
     const logPath = getArg("--log");
+    // --- OAuth CLI flags ---
+    const oauthClientId = getArg("--oauth-client-id");
+    const oauthClientSecret = getArg("--oauth-client-secret");
+    const oauthTokenUrl = getArg("--oauth-token-url");
+    const oauthAuthUrl = getArg("--oauth-auth-url");
+    const oauthScopes = getArg("--oauth-scopes");
+    const oauthFlow = getArg("--oauth-flow");
+    const oauthParams = getAllArgs("--oauth-param");
+    const hasAnyOAuth = oauthClientId || oauthClientSecret || oauthTokenUrl;
+    if (hasAnyOAuth && !(oauthClientId && oauthClientSecret && oauthTokenUrl)) {
+        console.error("ERROR: --oauth-client-id, --oauth-client-secret, and --oauth-token-url must all be provided together.");
+        process.exit(1);
+    }
+    let oauth;
+    if (oauthClientId && oauthClientSecret && oauthTokenUrl) {
+        const extraParams = {};
+        for (const raw of oauthParams) {
+            const eqIdx = raw.indexOf("=");
+            if (eqIdx === -1) {
+                console.error(`ERROR: Invalid --oauth-param format "${raw}". Expected "key=value"`);
+                process.exit(1);
+            }
+            extraParams[raw.slice(0, eqIdx)] = interpolateEnv(raw.slice(eqIdx + 1));
+        }
+        const flow = (oauthFlow ? interpolateEnv(oauthFlow) : "authorization_code");
+        if (flow !== "authorization_code" && flow !== "client_credentials") {
+            console.error(`ERROR: Invalid --oauth-flow "${flow}". Must be "authorization_code" or "client_credentials".`);
+            process.exit(1);
+        }
+        oauth = {
+            clientId: interpolateEnv(oauthClientId),
+            clientSecret: interpolateEnv(oauthClientSecret),
+            tokenUrl: interpolateEnv(oauthTokenUrl),
+            authUrl: oauthAuthUrl ? interpolateEnv(oauthAuthUrl) : undefined,
+            scopes: oauthScopes
+                ? interpolateEnv(oauthScopes)
+                    .split(/[,\s]+/)
+                    .filter(Boolean)
+                : [],
+            flow,
+            extraParams,
+        };
+    }
     return {
         name,
         specs,
         baseUrl: interpolateEnv(baseUrl).replace(/\/+$/, ""),
         headers: Object.keys(headers).length > 0 ? headers : undefined,
         logPath: logPath ? resolve(logPath) : undefined,
+        oauth,
     };
 }

package/build/error-context.js

@@ -97,7 +97,7 @@ function getSuggestion(status, endpoint) {
             return msg;
         }
         case 401:
-            return "Authentication required. Provide credentials via --header (e.g. --header \"Authorization: Bearer <token>\") or per-request headers parameter.";
+            return "Authentication required. Use the auth tool to authenticate via OAuth, or provide credentials via --header (e.g. --header \"Authorization: Bearer <token>\") or per-request headers parameter.";
         case 403:
             return "Forbidden. Your credentials don't have permission for this operation. Verify your API key or token has the required scopes.";
         case 404: {

package/build/index.js

@@ -10,10 +10,26 @@ import { generateSuggestions } from "./query-suggestions.js";
 import { getOrBuildSchema, executeQuery, schemaToSDL, truncateIfArray, computeShapeHash, } from "./graphql-schema.js";
 import { ApiError, buildErrorContext } from "./error-context.js";
 import { RetryableError } from "./retry.js";
+import { isNonJsonResult } from "./response-parser.js";
+import { startAuth, exchangeCode, awaitCallback, storeTokens, getTokens, isTokenExpired, initTokenStorage, } from "./oauth.js";
 const WRITE_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
 const config = await loadConfig();
 initLogger(config.logPath ?? null);
 const apiIndex = new ApiIndex(config.specs);
+// --- OAuth: merge spec-derived security info and init token storage ---
+if (config.oauth) {
+    const schemes = apiIndex.getOAuthSchemes();
+    if (schemes.length > 0) {
+        const scheme = schemes[0];
+        if (!config.oauth.authUrl && scheme.authorizationUrl) {
+            config.oauth.authUrl = scheme.authorizationUrl;
+        }
+        if (config.oauth.scopes.length === 0 && scheme.scopes.length > 0) {
+            config.oauth.scopes = scheme.scopes;
+        }
+    }
+    initTokenStorage(config.name);
+}
 function formatToolError(error, method, path) {
     if ((error instanceof ApiError || error instanceof RetryableError) && method && path) {
         const endpoint = apiIndex.getEndpoint(method, path);
@@ -145,12 +161,25 @@ server.tool("call_api", `Inspect a ${config.name} API endpoint. Makes a real req
         "Overrides default --header values."),
 }, async ({ method, path, params, body, headers }) => {
     try {
-        const data = await callApi(config, method, path, params, body, headers, "populate");
+        const { data, responseHeaders: respHeaders } = await callApi(config, method, path, params, body, headers, "populate");
+        // Non-JSON response — skip GraphQL layer, return raw parsed data
+        if (isNonJsonResult(data)) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({
+                            rawResponse: data,
+                            responseHeaders: respHeaders,
+                            hint: "This endpoint returned a non-JSON response. The raw parsed content is shown above. " +
+                                "GraphQL schema inference is not available for non-JSON responses — use the data directly.",
+                        }, null, 2) },
+                ],
+            };
+        }
         const endpoint = apiIndex.getEndpoint(method, path);
         const bodyHash = WRITE_METHODS.has(method) && body ? computeShapeHash(body) : undefined;
         const { schema, shapeHash } = getOrBuildSchema(data, method, path, endpoint?.requestBodySchema, bodyHash);
         const sdl = schemaToSDL(schema);
-        const result = { graphqlSchema: sdl, shapeHash };
+        const result = { graphqlSchema: sdl, shapeHash, responseHeaders: respHeaders };
         if (bodyHash)
             result.bodyHash = bodyHash;
         if (endpoint && endpoint.parameters.length > 0) {
@@ -240,7 +269,20 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         .describe("Client-side slice: items to skip in already-fetched response (default: 0). For API pagination, use params instead."),
 }, async ({ method, path, params, body, query, headers, limit, offset }) => {
     try {
-        const rawData = await callApi(config, method, path, params, body, headers, "consume");
+        const { data: rawData, responseHeaders: respHeaders } = await callApi(config, method, path, params, body, headers, "consume");
+        // Non-JSON response — skip GraphQL layer, return raw parsed data
+        if (isNonJsonResult(rawData)) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({
+                            rawResponse: rawData,
+                            responseHeaders: respHeaders,
+                            hint: "This endpoint returned a non-JSON response. GraphQL querying is not available. " +
+                                "The raw parsed content is shown above.",
+                        }, null, 2) },
+                ],
+            };
+        }
         const endpoint = apiIndex.getEndpoint(method, path);
         const bodyHash = WRITE_METHODS.has(method) && body ? computeShapeHash(body) : undefined;
         const { schema, shapeHash } = getOrBuildSchema(rawData, method, path, endpoint?.requestBodySchema, bodyHash);
@@ -248,6 +290,7 @@ server.tool("query_api", `Fetch data from a ${config.name} API endpoint, returni
         const queryResult = await executeQuery(schema, data, query);
         if (typeof queryResult === "object" && queryResult !== null) {
             queryResult._shapeHash = shapeHash;
+            queryResult._responseHeaders = respHeaders;
             if (bodyHash)
                 queryResult._bodyHash = bodyHash;
             if (truncated) {
@@ -387,7 +430,17 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
 }, async ({ requests }) => {
     try {
         const settled = await Promise.allSettled(requests.map(async (req) => {
-            const rawData = await callApi(config, req.method, req.path, req.params, req.body, req.headers, "none");
+            const { data: rawData, responseHeaders: respHeaders } = await callApi(config, req.method, req.path, req.params, req.body, req.headers, "none");
+            // Non-JSON response — skip GraphQL layer
+            if (isNonJsonResult(rawData)) {
+                return {
+                    method: req.method,
+                    path: req.path,
+                    data: rawData,
+                    responseHeaders: respHeaders,
+                    nonJson: true,
+                };
+            }
             const endpoint = apiIndex.getEndpoint(req.method, req.path);
             const bodyHash = WRITE_METHODS.has(req.method) && req.body
                 ? computeShapeHash(req.body)
@@ -398,6 +451,7 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
                 method: req.method,
                 path: req.path,
                 data: queryResult,
+                responseHeaders: respHeaders,
                 shapeHash,
                 ...(bodyHash ? { bodyHash } : {}),
             };
@@ -434,6 +488,120 @@ server.tool("batch_query", `Fetch data from multiple ${config.name} API endpoint
         };
     }
 });
+// --- Tool 6: auth (only when OAuth is configured) ---
+if (config.oauth) {
+    server.tool("auth", `Manage OAuth 2.0 authentication for ${config.name}. ` +
+        "Use action 'start' to begin the OAuth flow (returns an authorization URL for " +
+        "authorization_code flow, or completes token exchange for client_credentials). " +
+        "Use action 'exchange' to complete the flow — the callback is captured automatically " +
+        "via a localhost server, or you can provide a 'code' manually. " +
+        "Use action 'status' to check the current token status.", {
+        action: z
+            .enum(["start", "exchange", "status"])
+            .describe("'start' begins auth flow, 'exchange' completes code exchange, 'status' shows token info"),
+        code: z
+            .string()
+            .optional()
+            .describe("Authorization code from the OAuth provider (optional for 'exchange' — " +
+            "if omitted, waits for the localhost callback automatically)"),
+    }, async ({ action, code }) => {
+        try {
+            if (action === "start") {
+                const result = await startAuth(config.oauth);
+                if ("url" in result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    message: "Open this URL to authorize. A local callback server is listening. " +
+                                        "After you approve, call auth with action 'exchange' to complete authentication.",
+                                    authorizationUrl: result.url,
+                                    flow: config.oauth.flow,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                // client_credentials: tokens obtained directly
+                storeTokens(result.tokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                message: "Authentication successful (client_credentials flow).",
+                                tokenType: result.tokens.tokenType,
+                                expiresIn: Math.round((result.tokens.expiresAt - Date.now()) / 1000),
+                                scope: result.tokens.scope ?? null,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            if (action === "exchange") {
+                const tokens = code
+                    ? await exchangeCode(config.oauth, code)
+                    : await awaitCallback(config.oauth);
+                storeTokens(tokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                message: "Authentication successful.",
+                                tokenType: tokens.tokenType,
+                                expiresIn: Math.round((tokens.expiresAt - Date.now()) / 1000),
+                                hasRefreshToken: !!tokens.refreshToken,
+                                scope: tokens.scope ?? null,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // action === "status"
+            const tokens = getTokens();
+            if (!tokens) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                authenticated: false,
+                                message: "No tokens stored. Use auth with action 'start' to authenticate.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const expired = isTokenExpired();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            authenticated: true,
+                            tokenType: tokens.tokenType,
+                            expired,
+                            expiresIn: Math.round((tokens.expiresAt - Date.now()) / 1000),
+                            hasRefreshToken: !!tokens.refreshToken,
+                            scope: tokens.scope ?? null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: message }) },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/build/oauth.js

@@ -0,0 +1,340 @@
+import { randomBytes, createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const EXPIRY_BUFFER_MS = 60_000;
+const CALLBACK_PATH = "/callback";
+const CALLBACK_TIMEOUT_MS = 300_000; // 5 minutes
+const TOKEN_DIR = process.platform === "win32"
+    ? join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "anyapi-mcp", "tokens")
+    : join(homedir(), ".cache", "anyapi-mcp", "tokens");
+// ---------------------------------------------------------------------------
+// PKCE helpers
+// ---------------------------------------------------------------------------
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+function generateCodeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+let pendingPkce = null;
+let currentTokens = null;
+let persistName = null;
+let refreshPromise = null;
+// Localhost callback server state
+let callbackServer = null;
+let callbackCodePromise = null;
+let callbackRedirectUri = "";
+let callbackTimeoutHandle = null;
+// ---------------------------------------------------------------------------
+// Token persistence
+// ---------------------------------------------------------------------------
+export function initTokenStorage(name) {
+    persistName = name;
+    const tokenPath = join(TOKEN_DIR, `${name}.json`);
+    if (existsSync(tokenPath)) {
+        try {
+            const raw = readFileSync(tokenPath, "utf-8");
+            const loaded = JSON.parse(raw);
+            if (loaded.accessToken && typeof loaded.expiresAt === "number") {
+                currentTokens = loaded;
+            }
+        }
+        catch {
+            // Corrupt file — will re-auth
+        }
+    }
+}
+function persistTokens(tokens) {
+    if (!persistName)
+        return;
+    try {
+        mkdirSync(TOKEN_DIR, { recursive: true });
+        writeFileSync(join(TOKEN_DIR, `${persistName}.json`), JSON.stringify(tokens, null, 2), "utf-8");
+    }
+    catch (err) {
+        console.error(`[oauth] Failed to persist tokens: ${err}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Token accessors
+// ---------------------------------------------------------------------------
+export function storeTokens(tokens) {
+    currentTokens = tokens;
+    persistTokens(tokens);
+}
+export function getTokens() {
+    return currentTokens;
+}
+export function clearTokens() {
+    currentTokens = null;
+}
+export function isTokenExpired() {
+    if (!currentTokens)
+        return true;
+    return Date.now() >= currentTokens.expiresAt - EXPIRY_BUFFER_MS;
+}
+// ---------------------------------------------------------------------------
+// Localhost callback server
+// ---------------------------------------------------------------------------
+function cleanupCallbackServer() {
+    if (callbackTimeoutHandle) {
+        clearTimeout(callbackTimeoutHandle);
+        callbackTimeoutHandle = null;
+    }
+    if (callbackServer) {
+        callbackServer.close();
+        callbackServer = null;
+    }
+    callbackCodePromise = null;
+    callbackRedirectUri = "";
+}
+function startCallbackServer() {
+    return new Promise((resolveSetup, rejectSetup) => {
+        let resolveCode;
+        let rejectCode;
+        const codePromise = new Promise((resolve, reject) => {
+            resolveCode = resolve;
+            rejectCode = reject;
+        });
+        // Mark promise as handled to prevent Node.js unhandled rejection warning.
+        // The rejection will still propagate through awaitCallback/exchangeCode.
+        codePromise.catch(() => { });
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://127.0.0.1`);
+            if (url.pathname !== CALLBACK_PATH) {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            const errorDesc = url.searchParams.get("error_description");
+            if (error) {
+                const msg = errorDesc ? `${error}: ${errorDesc}` : error;
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<html><body style=\"font-family:system-ui;text-align:center;padding:40px\">" +
+                    `<h1>Authentication Failed</h1><p>${msg}</p>` +
+                    "<p style=\"color:#666\">You can close this window.</p></body></html>");
+                rejectCode(new Error(`OAuth authorization failed: ${msg}`));
+            }
+            else if (code) {
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end("<html><body style=\"font-family:system-ui;text-align:center;padding:40px\">" +
+                    "<h1>Authentication Successful</h1>" +
+                    "<p>You can close this window and return to Claude.</p></body></html>");
+                resolveCode(code);
+            }
+            else {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<html><body style=\"font-family:system-ui;text-align:center;padding:40px\">" +
+                    "<h1>Error</h1><p>No authorization code received.</p></body></html>");
+            }
+            // Close the HTTP server (no longer needed) but preserve
+            // callbackCodePromise and callbackRedirectUri for awaitCallback/exchangeCode.
+            if (callbackTimeoutHandle) {
+                clearTimeout(callbackTimeoutHandle);
+                callbackTimeoutHandle = null;
+            }
+            setTimeout(() => {
+                if (callbackServer) {
+                    callbackServer.close();
+                    callbackServer = null;
+                }
+            }, 500);
+        });
+        server.on("error", rejectSetup);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            callbackServer = server;
+            // Timeout: reject code promise and clean up after 5 minutes
+            callbackTimeoutHandle = setTimeout(() => {
+                rejectCode(new Error("OAuth callback timed out after 5 minutes. Please try auth start again."));
+                cleanupCallbackServer();
+            }, CALLBACK_TIMEOUT_MS);
+            resolveSetup({ port, codePromise });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Token exchange helpers
+// ---------------------------------------------------------------------------
+async function fetchTokens(tokenUrl, body) {
+    const res = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const errorBody = await res.text();
+        throw new Error(`OAuth token request failed (${res.status} ${res.statusText}): ${errorBody}`);
+    }
+    const data = (await res.json());
+    if (typeof data.access_token !== "string") {
+        throw new Error("OAuth token response missing access_token");
+    }
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 3600;
+    return {
+        accessToken: data.access_token,
+        refreshToken: typeof data.refresh_token === "string" ? data.refresh_token : undefined,
+        expiresAt: Date.now() + expiresIn * 1000,
+        tokenType: typeof data.token_type === "string" ? data.token_type : "Bearer",
+        scope: typeof data.scope === "string" ? data.scope : undefined,
+    };
+}
+async function exchangeClientCredentials(config) {
+    const body = new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+    });
+    if (config.scopes.length > 0) {
+        body.set("scope", config.scopes.join(" "));
+    }
+    return fetchTokens(config.tokenUrl, body);
+}
+// ---------------------------------------------------------------------------
+// Public API — auth flow
+// ---------------------------------------------------------------------------
+export async function startAuth(config) {
+    if (config.flow === "client_credentials") {
+        const tokens = await exchangeClientCredentials(config);
+        return { tokens };
+    }
+    if (!config.authUrl) {
+        throw new Error("OAuth authorization URL is required for authorization_code flow. " +
+            "Provide --oauth-auth-url or ensure the OpenAPI spec has securitySchemes with an authorizationUrl.");
+    }
+    // Clean up any previous callback server
+    cleanupCallbackServer();
+    const verifier = generateCodeVerifier();
+    const challenge = generateCodeChallenge(verifier);
+    const state = randomBytes(16).toString("hex");
+    pendingPkce = { verifier, state };
+    // Start localhost callback server on a random available port
+    const { port, codePromise } = await startCallbackServer();
+    callbackRedirectUri = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+    callbackCodePromise = codePromise;
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: callbackRedirectUri,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state,
+        ...config.extraParams,
+    });
+    if (config.scopes.length > 0) {
+        params.set("scope", config.scopes.join(" "));
+    }
+    const url = `${config.authUrl}?${params.toString()}`;
+    return { url };
+}
+export async function exchangeCode(config, code) {
+    if (!pendingPkce) {
+        throw new Error("No pending authorization flow. Call auth with action 'start' first.");
+    }
+    const { verifier } = pendingPkce;
+    pendingPkce = null;
+    const redirectUri = callbackRedirectUri;
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        code_verifier: verifier,
+        redirect_uri: redirectUri,
+    });
+    cleanupCallbackServer();
+    return fetchTokens(config.tokenUrl, body);
+}
+/**
+ * Wait for the localhost callback server to receive the authorization code,
+ * then exchange it for tokens automatically.
+ */
+export async function awaitCallback(config) {
+    if (!callbackCodePromise) {
+        throw new Error("No pending authorization flow. Call auth with action 'start' first.");
+    }
+    if (!pendingPkce) {
+        throw new Error("No pending PKCE state. Call auth with action 'start' first.");
+    }
+    const code = await callbackCodePromise;
+    const { verifier } = pendingPkce;
+    pendingPkce = null;
+    const redirectUri = callbackRedirectUri;
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        code_verifier: verifier,
+        redirect_uri: redirectUri,
+    });
+    cleanupCallbackServer();
+    return fetchTokens(config.tokenUrl, body);
+}
+// ---------------------------------------------------------------------------
+// Token refresh
+// ---------------------------------------------------------------------------
+export async function refreshTokens(config) {
+    if (!currentTokens?.refreshToken) {
+        throw new Error("Cannot refresh: no refresh token available. " +
+            "Re-authenticate using the auth tool with action 'start'.");
+    }
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: currentTokens.refreshToken,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+    });
+    const tokens = await fetchTokens(config.tokenUrl, body);
+    // Preserve refresh token if server didn't issue a new one
+    if (!tokens.refreshToken && currentTokens.refreshToken) {
+        tokens.refreshToken = currentTokens.refreshToken;
+    }
+    storeTokens(tokens);
+    return tokens;
+}
+// ---------------------------------------------------------------------------
+// Auth middleware — called by api-client before each request
+// ---------------------------------------------------------------------------
+export async function getValidAccessToken(config) {
+    if (!config || !currentTokens)
+        return undefined;
+    if (isTokenExpired()) {
+        if (!refreshPromise) {
+            refreshPromise = (async () => {
+                try {
+                    if (config.flow === "client_credentials") {
+                        const tokens = await exchangeClientCredentials(config);
+                        storeTokens(tokens);
+                        return tokens;
+                    }
+                    return await refreshTokens(config);
+                }
+                finally {
+                    refreshPromise = null;
+                }
+            })();
+        }
+        const tokens = await refreshPromise;
+        return tokens.accessToken;
+    }
+    return currentTokens.accessToken;
+}
+// ---------------------------------------------------------------------------
+// Test helpers — reset module state
+// ---------------------------------------------------------------------------
+export function _resetForTests() {
+    pendingPkce = null;
+    currentTokens = null;
+    persistName = null;
+    refreshPromise = null;
+    cleanupCallbackServer();
+}