api-spec-cli 0.2.3 → 0.2.4

package/src/mcp-client.js

@@ -1,63 +1,88 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-
-const MAX_RETRIES = parseInt(process.env.MCP_MAX_RETRIES ?? "3");
-const RETRY_DELAY = parseInt(process.env.MCP_RETRY_DELAY ?? "1000");
-
-// Expand ${VAR} placeholders from process.env at call time
-function expandEnv(val) {
-  return val.replace(/\$\{([^}]+)\}/g, (_, name) => {
-    if (!(name in process.env)) throw new Error(`Environment variable not set: ${name}`);
-    return process.env[name];
-  });
-}
-
-async function connect(spec) {
-  const client = new Client({ name: "spec-cli", version: "1.0.0" });
-
-  let transport;
-  if (spec.transport === "stdio") {
-    const rawEnv = spec.config?.env || {};
-    const expandedEnv = Object.fromEntries(
-      Object.entries(rawEnv).map(([k, v]) => [k, expandEnv(v)])
-    );
-    transport = new StdioClientTransport({
-      command: spec.command,
-      args: spec.args,
-      env: Object.keys(expandedEnv).length > 0 ? { ...process.env, ...expandedEnv } : undefined,
-      cwd: spec.cwd,
-    });
-  } else if (spec.transport === "sse") {
-    const h = spec.config?.headers;
-    transport = new SSEClientTransport(new URL(spec.url), {
-      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
-    });
-  } else if (spec.transport === "streamable-http") {
-    const h = spec.config?.headers;
-    transport = new StreamableHTTPClientTransport(new URL(spec.url), {
-      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
-    });
-  } else {
-    throw new Error(`Unknown MCP transport: ${spec.transport}. Supported: stdio, sse, streamable-http`);
-  }
-
-  await client.connect(transport);
-  return client;
-}
-
-export async function createMcpClient(spec) {
-  let lastError;
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    try {
-      return await connect(spec);
-    } catch (e) {
-      lastError = e;
-      if (attempt < MAX_RETRIES) {
-        await new Promise((r) => setTimeout(r, Math.min(RETRY_DELAY * Math.pow(2, attempt), 5000)));
-      }
-    }
-  }
-  throw lastError;
-}
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SpecCliOAuthProvider } from "./oauth/provider.js";
+import { ClientCredentialsProvider } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
+import { loadTokenFile } from "./oauth/tokens.js";
+
+const MAX_RETRIES = parseInt(process.env.MCP_MAX_RETRIES ?? "3");
+const RETRY_DELAY = parseInt(process.env.MCP_RETRY_DELAY ?? "1000");
+
+// Expand ${VAR} placeholders from process.env at call time
+function expandEnv(val) {
+  return val.replace(/\$\{([^}]+)\}/g, (_, name) => {
+    if (!(name in process.env)) throw new Error(`Environment variable not set: ${name}`);
+    return process.env[name];
+  });
+}
+
+async function connect(spec) {
+  const client = new Client({ name: "spec-cli", version: "1.0.0" });
+
+  let transport;
+  if (spec.type === "stdio") {
+    const rawEnv = spec.env || {};
+    const expandedEnv = Object.fromEntries(
+      Object.entries(rawEnv).map(([k, v]) => [k, expandEnv(v)])
+    );
+    transport = new StdioClientTransport({
+      command: spec.command,
+      args: spec.args,
+      env: Object.keys(expandedEnv).length > 0 ? { ...process.env, ...expandedEnv } : undefined,
+      cwd: spec.cwd,
+    });
+  } else if (spec.type === "sse") {
+    const h = spec.headers;
+    let authProvider;
+    // spec.name is only set for registry entries; inline connections (--mcp-sse <url>)
+    // have no token storage location, so no OAuth provider is created for them.
+    if (spec.name && !h?.Authorization) {
+      const clientSecret = loadTokenFile(spec.name).clientSecret;
+      authProvider =
+        spec.oauthFlow === "client_credentials" && spec.oauthClientId && clientSecret
+          ? new ClientCredentialsProvider({ clientId: spec.oauthClientId, clientSecret })
+          : new SpecCliOAuthProvider(spec.name, spec);
+    }
+    transport = new SSEClientTransport(new URL(spec.url), {
+      authProvider,
+      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
+  } else if (spec.type === "http") {
+    const h = spec.headers;
+    let authProvider;
+    // spec.name is only set for registry entries; inline connections (--mcp-http <url>)
+    // have no token storage location, so no OAuth provider is created for them.
+    if (spec.name && !h?.Authorization) {
+      const clientSecret = loadTokenFile(spec.name).clientSecret;
+      authProvider =
+        spec.oauthFlow === "client_credentials" && spec.oauthClientId && clientSecret
+          ? new ClientCredentialsProvider({ clientId: spec.oauthClientId, clientSecret })
+          : new SpecCliOAuthProvider(spec.name, spec);
+    }
+    transport = new StreamableHTTPClientTransport(new URL(spec.url), {
+      authProvider,
+      requestInit: h && Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
+  } else {
+    throw new Error(`Unknown MCP type: ${spec.type}. Supported: stdio, sse, http`);
+  }
+
+  await client.connect(transport);
+  return client;
+}
+
+export async function createMcpClient(spec) {
+  let lastError;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await connect(spec);
+    } catch (e) {
+      lastError = e;
+      if (attempt < MAX_RETRIES) {
+        await new Promise((r) => setTimeout(r, Math.min(RETRY_DELAY * Math.pow(2, attempt), 5000)));
+      }
+    }
+  }
+  throw lastError;
+}

package/src/oauth/auth-flow.js

@@ -0,0 +1,59 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { ClientCredentialsProvider } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
+import { SpecCliOAuthProvider } from "./provider.js";
+import { loadTokenFile } from "./tokens.js";
+
+/**
+ * Run the full OAuth flow for a named MCP HTTP/SSE entry.
+ * Client secret is loaded from the token file (not the registry entry).
+ * Returns { flow: "client_credentials" | "browser" | "device" | "none_required" }.
+ * Throws on connection errors and unsupported flows.
+ */
+export async function runOAuthFlow(name, entry) {
+  const TransportClass = entry.type === "sse" ? SSEClientTransport : StreamableHTTPClientTransport;
+  const clientSecret = loadTokenFile(name).clientSecret;
+
+  // Only use client credentials grant when explicitly requested.
+  // Having a clientSecret does NOT imply client_credentials — for most OAuth apps
+  // (e.g. GitHub) the secret is used during the authorization code token exchange.
+  if (entry.oauthFlow === "client_credentials" && entry.oauthClientId && clientSecret) {
+    process.stderr.write(`Using client credentials flow for '${name}'...\n`);
+    const provider = new ClientCredentialsProvider({ clientId: entry.oauthClientId, clientSecret });
+    const transport = new TransportClass(new URL(entry.url), { authProvider: provider });
+    const client = new Client({ name: "spec-cli", version: "1.0.0" });
+    await client.connect(transport);
+    await client.close();
+    process.stderr.write(`Connected with client credentials.\n`);
+    return { flow: "client_credentials" };
+  }
+
+  const provider = new SpecCliOAuthProvider(name, entry);
+  await provider.prepareRedirect();
+  const transport = new TransportClass(new URL(entry.url), { authProvider: provider });
+  const client = new Client({ name: "spec-cli", version: "1.0.0" });
+
+  try {
+    await client.connect(transport);
+    await client.close();
+    return { flow: "none_required" };
+  } catch (e) {
+    if (!(e instanceof UnauthorizedError)) throw e;
+    if ((entry.oauthFlow || "browser") !== "browser") {
+      throw new Error(
+        `Device flow: open the URL above, complete authorization, then run:\n  spec auth ${name}`
+      );
+    }
+    process.stderr.write(`Waiting for browser authorization...\n`);
+    const code = await provider.waitForAuthCode();
+    await transport.finishAuth(code);
+    // Transport was already started by the first connect() — must use a fresh one
+    const transport2 = new TransportClass(new URL(entry.url), { authProvider: provider });
+    const client2 = new Client({ name: "spec-cli", version: "1.0.0" });
+    await client2.connect(transport2);
+    await client2.close();
+    return { flow: "browser" };
+  }
+}

package/src/oauth/provider.js

@@ -0,0 +1,192 @@
+import { createServer } from "http";
+import { exec } from "child_process";
+import { randomUUID } from "crypto";
+import { loadTokenFile, saveTokenFile } from "./tokens.js";
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === "win32"
+      ? `start "" "${url}"`
+      : process.platform === "darwin"
+        ? `open "${url}"`
+        : `xdg-open "${url}"`;
+  exec(cmd);
+}
+
+function getAvailablePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}
+
+/**
+ * OAuthClientProvider for spec-cli.
+ * Persists tokens, client registration, and discovery state to
+ * ~/spec-cli-config/tokens/<name>.json.
+ *
+ * Flows:
+ *   "browser" (default) — opens browser + local PKCE callback server
+ *   "device"            — prints device code URL to stderr
+ *
+ * For client_credentials, use SDK's ClientCredentialsProvider directly.
+ */
+export class SpecCliOAuthProvider {
+  #name;
+  #flow;
+  #redirectPort;
+  #fixedPort;
+  #codeVerifier;
+  #pendingCode = null;
+  #callbackServer = null;
+  #oauthState = null;
+  #clientId;
+
+  constructor(name, entry = {}) {
+    this.#name = name;
+    this.#flow = entry.oauthFlow || "browser";
+    this.#clientId = entry.oauthClientId || undefined;
+    const envPort = process.env.SPEC_OAUTH_CALLBACK_PORT
+      ? parseInt(process.env.SPEC_OAUTH_CALLBACK_PORT, 10)
+      : undefined;
+    this.#fixedPort = entry.oauthCallbackPort ? parseInt(entry.oauthCallbackPort, 10) : envPort;
+  }
+
+  get redirectUrl() {
+    if (this.#flow === "device") return undefined;
+    if (!this.#redirectPort) throw new Error("Call prepareRedirect() before accessing redirectUrl");
+    return `http://127.0.0.1:${this.#redirectPort}/callback`;
+  }
+
+  get clientMetadata() {
+    const clientSecret = loadTokenFile(this.#name).clientSecret;
+    return {
+      client_name: "spec-cli",
+      redirect_uris: this.#redirectPort ? [`http://127.0.0.1:${this.#redirectPort}/callback`] : [],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: clientSecret ? "client_secret_post" : "none",
+    };
+  }
+
+  /** Called by the SDK to generate a CSRF state parameter for the authorization URL. */
+  state() {
+    if (!this.#oauthState) this.#oauthState = randomUUID();
+    return this.#oauthState;
+  }
+
+  tokens() {
+    return loadTokenFile(this.#name).tokens ?? undefined;
+  }
+
+  saveTokens(tokens) {
+    saveTokenFile(this.#name, { tokens });
+  }
+
+  clientInformation() {
+    const stored = loadTokenFile(this.#name).clientInfo;
+    if (stored) return stored;
+    if (this.#clientId) {
+      const clientSecret = loadTokenFile(this.#name).clientSecret;
+      return clientSecret
+        ? { client_id: this.#clientId, client_secret: clientSecret }
+        : { client_id: this.#clientId };
+    }
+    return undefined;
+  }
+
+  saveClientInformation(info) {
+    saveTokenFile(this.#name, { clientInfo: info });
+  }
+
+  discoveryState() {
+    return loadTokenFile(this.#name).discovery ?? undefined;
+  }
+
+  saveDiscoveryState(state) {
+    saveTokenFile(this.#name, { discovery: state });
+  }
+
+  saveCodeVerifier(codeVerifier) {
+    this.#codeVerifier = codeVerifier;
+  }
+
+  codeVerifier() {
+    if (!this.#codeVerifier) throw new Error("No code verifier saved");
+    return this.#codeVerifier;
+  }
+
+  /** Reserve a local port for the OAuth callback. Call before connecting. */
+  async prepareRedirect() {
+    if (this.#flow === "device") return;
+    this.#redirectPort = this.#fixedPort ?? (await getAvailablePort());
+  }
+
+  redirectToAuthorization(authorizationUrl) {
+    if (this.#flow === "device") {
+      process.stderr.write(
+        `\nOpen this URL to authorize spec-cli:\n  ${authorizationUrl.toString()}\n\n`
+      );
+      return;
+    }
+
+    let resolveCode, rejectCode;
+    this.#pendingCode = new Promise((resolve, reject) => {
+      resolveCode = resolve;
+      rejectCode = reject;
+    });
+
+    this.#callbackServer = createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${this.#redirectPort}`);
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end("<html><body><h2>Authorization complete. You can close this tab.</h2></body></html>");
+      this.#callbackServer.close();
+      if (this.#oauthState !== null && state !== this.#oauthState) {
+        rejectCode(new Error("OAuth state mismatch — possible CSRF attack"));
+      } else {
+        resolveCode(code);
+      }
+    });
+
+    this.#callbackServer.listen(this.#redirectPort, "127.0.0.1", () => {
+      process.stderr.write(`\nOpening browser for authorization...\n`);
+      openBrowser(authorizationUrl.toString());
+      process.stderr.write(
+        `Waiting for callback on http://127.0.0.1:${this.#redirectPort}/callback\n`
+      );
+    });
+  }
+
+  /** Resolves with the authorization code once the browser callback arrives. */
+  async waitForAuthCode() {
+    if (this.#flow === "device") throw new Error("Device flow does not use a local callback");
+    if (!this.#pendingCode) throw new Error("redirectToAuthorization() was not called");
+
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(
+        () => {
+          this.#callbackServer?.close();
+          reject(
+            new Error(
+              "Authorization timed out after 5 minutes. Run 'spec auth <name>' to try again."
+            )
+          );
+        },
+        5 * 60 * 1000
+      );
+    });
+
+    try {
+      return await Promise.race([this.#pendingCode, timeoutPromise]);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}

package/src/oauth/tokens.js

@@ -0,0 +1,53 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+
+let TOKEN_DIR = join(homedir(), "spec-cli-config", "tokens");
+
+export function setTokenDir(dir) {
+  TOKEN_DIR = dir;
+}
+
+function tokenPath(name) {
+  return join(TOKEN_DIR, `${name}.json`);
+}
+
+export function loadTokenFile(name) {
+  const file = tokenPath(name);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveTokenFile(name, data) {
+  mkdirSync(TOKEN_DIR, { recursive: true });
+  const existing = loadTokenFile(name);
+  writeFileSync(tokenPath(name), JSON.stringify({ ...existing, ...data }, null, 2));
+}
+
+/**
+ * Clear session tokens for re-auth.
+ * Preserves clientSecret (a permanent credential) unless revokeAll is true.
+ * Pass { revokeAll: true } for `spec auth <name> --revoke` to wipe everything.
+ */
+export function clearTokenFile(name, { revokeAll = false } = {}) {
+  const file = tokenPath(name);
+  if (!existsSync(file)) return;
+  if (revokeAll) {
+    rmSync(file);
+    return;
+  }
+  // Keep permanent credentials; wipe session tokens, discovery, and clientInfo
+  const existing = loadTokenFile(name);
+  if (existing.clientSecret) {
+    writeFileSync(
+      tokenPath(name),
+      JSON.stringify({ clientSecret: existing.clientSecret }, null, 2)
+    );
+  } else {
+    rmSync(file);
+  }
+}

package/src/registry.js

@@ -1,53 +1,79 @@
-import { homedir } from "os";
-import { join } from "path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
-
-const REGISTRY_DIR = join(homedir(), "spec-cli-config");
-const REGISTRY_FILE = join(REGISTRY_DIR, "registry.json");
-const CACHE_DIR = join(REGISTRY_DIR, "cache");
-
-function ensureDir(dir) {
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-}
-
-export function getRegistry() {
-  if (!existsSync(REGISTRY_FILE)) return [];
-  try {
-    return JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
-  } catch {
-    throw new Error(`Registry file is corrupt: ${REGISTRY_FILE}. Delete it to reset.`);
-  }
-}
-
-export function saveRegistry(entries) {
-  ensureDir(REGISTRY_DIR);
-  writeFileSync(REGISTRY_FILE, JSON.stringify(entries, null, 2));
-}
-
-export function getEntry(name) {
-  const registry = getRegistry();
-  const entry = registry.find((e) => e.name === name);
-  if (!entry) throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
-  if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Run 'spec enable ${name}' first.`);
-  return entry;
-}
-
-export function getCachedSpec(name) {
-  const file = join(CACHE_DIR, `${name}.json`);
-  if (!existsSync(file)) return null;
-  try {
-    return JSON.parse(readFileSync(file, "utf-8"));
-  } catch {
-    return null; // Corrupt cache is treated as a miss — will re-fetch
-  }
-}
-
-export function saveCachedSpec(name, spec) {
-  ensureDir(CACHE_DIR);
-  writeFileSync(join(CACHE_DIR, `${name}.json`), JSON.stringify(spec, null, 2));
-}
-
-export function removeCachedSpec(name) {
-  const file = join(CACHE_DIR, `${name}.json`);
-  if (existsSync(file)) rmSync(file);
-}
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+
+const REGISTRY_DIR = join(homedir(), "spec-cli-config");
+const REGISTRY_FILE = join(REGISTRY_DIR, "registry.json");
+const CACHE_DIR = join(REGISTRY_DIR, "cache");
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+const EMPTY = { mcp: {}, openapi: {}, graphql: {} };
+
+export function getRegistry() {
+  if (!existsSync(REGISTRY_FILE)) return { ...EMPTY };
+  try {
+    const data = JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(`Registry file has old format: ${REGISTRY_FILE}. Delete it to reset.`);
+    }
+    return data;
+  } catch (e) {
+    if (e.message.includes("old format")) throw e;
+    throw new Error(`Registry file is corrupt: ${REGISTRY_FILE}. Delete it to reset.`);
+  }
+}
+
+export function saveRegistry(registry) {
+  ensureDir(REGISTRY_DIR);
+  writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * Find an entry by name across all sections.
+ * Returns the entry with `name` and `_section` injected.
+ */
+export function allEntries(registry) {
+  const entries = [];
+  for (const section of ["mcp", "openapi", "graphql"]) {
+    for (const [name, entry] of Object.entries(registry[section] || {})) {
+      entries.push({ ...entry, name, _section: section });
+    }
+  }
+  return entries;
+}
+
+export function getEntry(name) {
+  const registry = getRegistry();
+  for (const section of ["mcp", "openapi", "graphql"]) {
+    const entry = registry[section]?.[name];
+    if (entry) {
+      if (!entry.enabled)
+        throw new Error(`Spec '${name}' is disabled. Run 'spec enable ${name}' first.`);
+      return { ...entry, name, _section: section };
+    }
+  }
+  throw new Error(`No spec named '${name}'. Run 'spec specs' to see available.`);
+}
+
+export function getCachedSpec(name) {
+  const file = join(CACHE_DIR, `${name}.json`);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function saveCachedSpec(name, spec) {
+  ensureDir(CACHE_DIR);
+  writeFileSync(join(CACHE_DIR, `${name}.json`), JSON.stringify(spec, null, 2));
+}
+
+export function removeCachedSpec(name) {
+  const file = join(CACHE_DIR, `${name}.json`);
+  if (existsSync(file)) rmSync(file);
+}