api-spec-cli 0.2.3 → 0.2.5

package/src/mcp-client.js

@@ -1,63 +1,91 @@
-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 { getClientSecret } from "./oauth/tokens.js";
+import {
+  expandSecrets,
+  expandSecretsMap,
+  envHeaderOverrides,
+  envUrlOverride,
+  mergeHeaders,
+} from "./secrets.js";
+
+const MAX_RETRIES = parseInt(process.env.MCP_MAX_RETRIES ?? "3");
+const RETRY_DELAY = parseInt(process.env.MCP_RETRY_DELAY ?? "1000");
+
+function expandEnv(val) {
+  return expandSecrets(val);
+}
+
+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 = expandSecretsMap(mergeHeaders(spec.headers, envHeaderOverrides()));
+    const url = envUrlOverride() ?? spec.url;
+    let authProvider;
+    const hasAuthSse = Object.keys(h).some((k) => k.toLowerCase() === "authorization");
+    if (spec.name && !hasAuthSse) {
+      const clientSecret = getClientSecret(spec.name);
+      authProvider =
+        spec.oauthFlow === "client_credentials" && spec.oauthClientId && clientSecret
+          ? new ClientCredentialsProvider({ clientId: spec.oauthClientId, clientSecret })
+          : new SpecCliOAuthProvider(spec.name, spec);
+    }
+    transport = new SSEClientTransport(new URL(url), {
+      authProvider,
+      requestInit: Object.keys(h).length > 0 ? { headers: h } : undefined,
+    });
+  } else if (spec.type === "http") {
+    const h = expandSecretsMap(mergeHeaders(spec.headers, envHeaderOverrides()));
+    const url = envUrlOverride() ?? spec.url;
+    let authProvider;
+    const hasAuthHttp = Object.keys(h).some((k) => k.toLowerCase() === "authorization");
+    if (spec.name && !hasAuthHttp) {
+      const clientSecret = getClientSecret(spec.name);
+      authProvider =
+        spec.oauthFlow === "client_credentials" && spec.oauthClientId && clientSecret
+          ? new ClientCredentialsProvider({ clientId: spec.oauthClientId, clientSecret })
+          : new SpecCliOAuthProvider(spec.name, spec);
+    }
+    transport = new StreamableHTTPClientTransport(new URL(url), {
+      authProvider,
+      requestInit: 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 { getClientSecret } 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 = getClientSecret(name);
+
+  // 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,191 @@
+import { createServer } from "http";
+import { exec } from "child_process";
+import { randomUUID } from "crypto";
+import { loadTokenFile, saveTokenFile, getClientSecret } 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;
+    return `http://127.0.0.1:${this.#redirectPort || 0}/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 = getClientSecret(this.#name);
+      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,59 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+import { expandSecrets } from "../secrets.js";
+
+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 getClientSecret(name) {
+  const secret = loadTokenFile(name).clientSecret;
+  return secret ? expandSecrets(secret) : secret;
+}
+
+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/output.js

@@ -1,61 +1,65 @@
-import YAML from "yaml";
-
-let outputFormat = "json";
-
-export function setFormat(format) {
-  if (format && ["json", "text", "yaml"].includes(format)) {
-    outputFormat = format;
-  }
-}
-
-export function out(data) {
-  switch (outputFormat) {
-    case "yaml":
-      console.log(YAML.stringify(data).trimEnd());
-      break;
-    case "text":
-      console.log(formatText(data));
-      break;
-    case "json":
-    default:
-      console.log(JSON.stringify(data, null, 2));
-      break;
-  }
-}
-
-export function err(message) {
-  // Errors are always JSON for reliable agent parsing
-  console.error(JSON.stringify({ error: message }));
-}
-
-function formatText(data, indent = 0) {
-  if (data === null || data === undefined) return "null";
-  if (typeof data === "string") return data;
-  if (typeof data === "number" || typeof data === "boolean") return String(data);
-
-  if (Array.isArray(data)) {
-    if (data.length === 0) return "(empty)";
-    return data
-      .map((item, i) => {
-        if (typeof item === "object" && item !== null) {
-          return `${"  ".repeat(indent)}[${i}]\n${formatText(item, indent + 1)}`;
-        }
-        return `${"  ".repeat(indent)}- ${item}`;
-      })
-      .join("\n");
-  }
-
-  if (typeof data === "object") {
-    return Object.entries(data)
-      .map(([key, val]) => {
-        if (val === null || val === undefined) return `${"  ".repeat(indent)}${key}: null`;
-        if (typeof val === "object") {
-          return `${"  ".repeat(indent)}${key}:\n${formatText(val, indent + 1)}`;
-        }
-        return `${"  ".repeat(indent)}${key}: ${val}`;
-      })
-      .join("\n");
-  }
-
-  return String(data);
-}
+import YAML from "yaml";
+import { encode } from "@toon-format/toon";
+
+let outputFormat = "json";
+
+export function setFormat(format) {
+  if (format && ["json", "text", "yaml", "toon"].includes(format)) {
+    outputFormat = format;
+  }
+}
+
+export function out(data) {
+  switch (outputFormat) {
+    case "yaml":
+      console.log(YAML.stringify(data).trimEnd());
+      break;
+    case "toon":
+      console.log(encode(data).trimEnd());
+      break;
+    case "text":
+      console.log(formatText(data));
+      break;
+    case "json":
+    default:
+      console.log(JSON.stringify(data, null, 2));
+      break;
+  }
+}
+
+export function err(message) {
+  // Errors are always JSON for reliable agent parsing
+  console.error(JSON.stringify({ error: message }));
+}
+
+function formatText(data, indent = 0) {
+  if (data === null || data === undefined) return "null";
+  if (typeof data === "string") return data;
+  if (typeof data === "number" || typeof data === "boolean") return String(data);
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "(empty)";
+    return data
+      .map((item, i) => {
+        if (typeof item === "object" && item !== null) {
+          return `${"  ".repeat(indent)}[${i}]\n${formatText(item, indent + 1)}`;
+        }
+        return `${"  ".repeat(indent)}- ${item}`;
+      })
+      .join("\n");
+  }
+
+  if (typeof data === "object") {
+    return Object.entries(data)
+      .map(([key, val]) => {
+        if (val === null || val === undefined) return `${"  ".repeat(indent)}${key}: null`;
+        if (typeof val === "object") {
+          return `${"  ".repeat(indent)}${key}:\n${formatText(val, indent + 1)}`;
+        }
+        return `${"  ".repeat(indent)}${key}: ${val}`;
+      })
+      .join("\n");
+  }
+
+  return String(data);
+}

package/src/registry.js

@@ -10,26 +10,52 @@ function ensureDir(dir) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
+const EMPTY = { mcp: {}, openapi: {}, graphql: {} };
+
 export function getRegistry() {
-  if (!existsSync(REGISTRY_FILE)) return [];
+  if (!existsSync(REGISTRY_FILE)) return { ...EMPTY };
   try {
-    return JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
-  } catch {
+    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(entries) {
+export function saveRegistry(registry) {
   ensureDir(REGISTRY_DIR);
-  writeFileSync(REGISTRY_FILE, JSON.stringify(entries, null, 2));
+  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();
-  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;
+  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) {
@@ -38,7 +64,7 @@ export function getCachedSpec(name) {
   try {
     return JSON.parse(readFileSync(file, "utf-8"));
   } catch {
-    return null; // Corrupt cache is treated as a miss — will re-fetch
+    return null;
   }
 }