@slashfi/agents-sdk 0.26.1 → 0.27.0

package/src/mcp-client.ts

@@ -0,0 +1,230 @@
+/**
+ * MCP Client Auth — OAuth utilities for connecting to MCP servers.
+ *
+ * Standalone utilities for:
+ * - OAuth Authorization Server discovery (.well-known/oauth-authorization-server, RFC 8414)
+ * - Dynamic client registration (RFC 7591)
+ * - PKCE OAuth authorization URL construction
+ * - Authorization code → token exchange (with PKCE)
+ * - Token refresh
+ *
+ * These are used by registry-consumer.ts when connecting to MCP servers
+ * or registries that require OAuth. The MCP transport itself is handled
+ * by registry-consumer — this module only provides auth primitives.
+ */
+
+import { generatePkcePair } from "./pkce.js";
+
+// ============================================
+// Types
+// ============================================
+
+/** OAuth Authorization Server Metadata (RFC 8414) */
+export interface OAuthServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  registration_endpoint?: string;
+  scopes_supported?: string[];
+  response_types_supported?: string[];
+  grant_types_supported?: string[];
+  code_challenge_methods_supported?: string[];
+  token_endpoint_auth_methods_supported?: string[];
+}
+
+// ============================================
+// OAuth Discovery
+// ============================================
+
+/**
+ * Discover OAuth authorization server metadata.
+ * Probes .well-known/oauth-authorization-server (RFC 8414).
+ * Returns null if the server doesn't support OAuth.
+ */
+export async function discoverOAuthMetadata(
+  serverUrl: string,
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<OAuthServerMetadata | null> {
+  const url = `${serverUrl.replace(/\/$/, "")}/.well-known/oauth-authorization-server`;
+  try {
+    const res = await fetchFn(url);
+    if (!res.ok) return null;
+    return (await res.json()) as OAuthServerMetadata;
+  } catch {
+    return null;
+  }
+}
+
+// ============================================
+// Dynamic Client Registration
+// ============================================
+
+/**
+ * Dynamically register a client with an OAuth server.
+ * RFC 7591 — used when the MCP server supports dynamic registration.
+ */
+export async function dynamicClientRegistration(
+  registrationEndpoint: string,
+  params: {
+    clientName: string;
+    redirectUris?: string[];
+    grantTypes?: string[];
+    tokenEndpointAuthMethod?: string;
+  },
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{ clientId: string; clientSecret?: string }> {
+  const res = await fetchFn(registrationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: params.clientName,
+      redirect_uris: params.redirectUris,
+      grant_types: params.grantTypes ?? ["authorization_code"],
+      token_endpoint_auth_method:
+        params.tokenEndpointAuthMethod ?? "none",
+    }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "unknown");
+    throw new Error(
+      `Dynamic client registration failed: ${res.status} ${text}`,
+    );
+  }
+  const data = (await res.json()) as Record<string, unknown>;
+  return {
+    clientId: data.client_id as string,
+    clientSecret: data.client_secret as string | undefined,
+  };
+}
+
+// ============================================
+// Authorization URL
+// ============================================
+
+/**
+ * Build an OAuth authorization URL with PKCE.
+ * Returns the URL + the code_verifier (to be stored server-side).
+ */
+export async function buildOAuthAuthorizeUrl(params: {
+  authorizationEndpoint: string;
+  clientId: string;
+  redirectUri: string;
+  scopes?: string[];
+  state?: string;
+}): Promise<{
+  url: string;
+  codeVerifier: string;
+}> {
+  const pkce = await generatePkcePair();
+  const url = new URL(params.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("redirect_uri", params.redirectUri);
+  url.searchParams.set("code_challenge", pkce.codeChallenge);
+  url.searchParams.set("code_challenge_method", pkce.codeChallengeMethod);
+  if (params.scopes?.length) {
+    url.searchParams.set("scope", params.scopes.join(" "));
+  }
+  if (params.state) {
+    url.searchParams.set("state", params.state);
+  }
+  return { url: url.toString(), codeVerifier: pkce.codeVerifier };
+}
+
+// ============================================
+// Token Exchange
+// ============================================
+
+/**
+ * Exchange an authorization code for tokens (with PKCE).
+ */
+export async function exchangeCodeForTokens(
+  tokenEndpoint: string,
+  params: {
+    code: string;
+    codeVerifier: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+  },
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  tokenType?: string;
+}> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: params.code,
+    code_verifier: params.codeVerifier,
+    client_id: params.clientId,
+    redirect_uri: params.redirectUri,
+  });
+  if (params.clientSecret) {
+    body.set("client_secret", params.clientSecret);
+  }
+
+  const res = await fetchFn(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "unknown");
+    throw new Error(`Token exchange failed: ${res.status} ${text}`);
+  }
+  const data = (await res.json()) as Record<string, unknown>;
+  return {
+    accessToken: data.access_token as string,
+    refreshToken: data.refresh_token as string | undefined,
+    expiresIn: data.expires_in as number | undefined,
+    tokenType: data.token_type as string | undefined,
+  };
+}
+
+// ============================================
+// Token Refresh
+// ============================================
+
+/**
+ * Refresh an access token.
+ */
+export async function refreshAccessToken(
+  tokenEndpoint: string,
+  params: {
+    refreshToken: string;
+    clientId: string;
+    clientSecret?: string;
+  },
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+}> {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: params.refreshToken,
+    client_id: params.clientId,
+  });
+  if (params.clientSecret) {
+    body.set("client_secret", params.clientSecret);
+  }
+
+  const res = await fetchFn(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "unknown");
+    throw new Error(`Token refresh failed: ${res.status} ${text}`);
+  }
+  const data = (await res.json()) as Record<string, unknown>;
+  return {
+    accessToken: data.access_token as string,
+    refreshToken: data.refresh_token as string | undefined,
+    expiresIn: data.expires_in as number | undefined,
+  };
+}

package/src/pkce.ts

@@ -0,0 +1,54 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * RFC 7636 — used by MCP client OAuth flows to prevent
+ * authorization code interception. The code_verifier stays
+ * server-side; only the code_challenge is sent through the browser.
+ *
+ * This ensures auth codes are useless even if they leak into
+ * agent context or logs.
+ */
+
+/**
+ * Generate a cryptographically random code_verifier.
+ * RFC 7636 §4.1: 43–128 characters from [A-Z, a-z, 0-9, -, ., _, ~]
+ */
+export function generateCodeVerifier(length = 64): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(length));
+  return base64urlEncode(bytes).slice(0, length);
+}
+
+/**
+ * Generate code_challenge from a code_verifier using S256.
+ * RFC 7636 §4.2: BASE64URL(SHA256(code_verifier))
+ */
+export async function generateCodeChallenge(
+  verifier: string,
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(verifier));
+  return base64urlEncode(new Uint8Array(digest));
+}
+
+/**
+ * Generate a PKCE pair (verifier + challenge) in one call.
+ */
+export async function generatePkcePair(): Promise<{
+  codeVerifier: string;
+  codeChallenge: string;
+  codeChallengeMethod: "S256";
+}> {
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = await generateCodeChallenge(codeVerifier);
+  return { codeVerifier, codeChallenge, codeChallengeMethod: "S256" };
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+/** Base64url encode without padding (RFC 4648 §5) */
+function base64urlEncode(bytes: Uint8Array): string {
+  const binStr = Array.from(bytes, (b) => String.fromCharCode(b)).join("");
+  return btoa(binStr).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/src/registry-consumer.ts

@@ -42,6 +42,18 @@ import {
   normalizeRef,
   normalizeRegistry,
 } from "./define-config.js";
+// TODO: wire discoverOAuthMetadata from ./mcp-client.js into MCP server auth negotiation
+
+// ============================================
+// Registry Type Constants
+// ============================================
+
+/** Special registry type: connect directly to an MCP server */
+export const REGISTRY_TYPE_MCP = "mcp";
+/** Special registry type: raw HTTP/REST API */
+export const REGISTRY_TYPE_HTTPS = "https";
+/** Built-in registry types that bypass normal registry resolution */
+const DIRECT_REGISTRY_TYPES = new Set([REGISTRY_TYPE_MCP, REGISTRY_TYPE_HTTPS]);
 
 // ============================================
 // Registry Discovery Types
@@ -140,6 +152,190 @@ async function defaultSecretResolver(
   }
 }
 
+// ============================================
+// Direct MCP Resolution
+// ============================================
+
+/**
+ * List tools from a direct MCP server (registry type: 'mcp').
+ * Connects via JSON-RPC, does MCP initialize handshake, then tools/list.
+ */
+async function listFromMcpServer(
+  url: string,
+  auth: { token?: string; headers?: Record<string, string> },
+  fetchFn: typeof globalThis.fetch,
+): Promise<AgentListing[]> {
+  const serverUrl = url.replace(/\/$/, "");
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(auth.headers ?? {}),
+  };
+  if (auth.token) {
+    headers.Authorization = `Bearer ${auth.token}`;
+  }
+
+  let reqId = 0;
+  async function rpc(method: string, params?: Record<string, unknown>) {
+    const res = await fetchFn(serverUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++reqId,
+        method,
+        ...(params && { params }),
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`MCP call to ${serverUrl} failed: ${res.status}`);
+    }
+    const json = (await res.json()) as { result?: unknown; error?: { message: string } };
+    if (json.error) {
+      throw new Error(`MCP RPC error: ${json.error.message}`);
+    }
+    return json.result;
+  }
+
+  // Initialize handshake
+  const initResult = (await rpc("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "agents-sdk-consumer", version: "1.0.0" },
+  })) as { serverInfo?: { name?: string }; capabilities?: { registry?: unknown } };
+
+  // Send initialized notification
+  await rpc("notifications/initialized").catch(() => {});
+
+  // List tools
+  const toolsResult = (await rpc("tools/list")) as {
+    tools?: Array<{ name: string; description?: string }>;
+  };
+
+  const serverName = initResult?.serverInfo?.name ?? new URL(serverUrl).hostname;
+
+  // Return as a single agent listing with all tools
+  return [{
+    path: serverName,
+    description: `MCP server at ${serverUrl}`,
+    publisher: serverName,
+    tools: toolsResult?.tools ?? [],
+    requiresAuth: false,
+  }];
+}
+
+/**
+ * Call a tool on a direct MCP server.
+ */
+async function callMcpTool(
+  url: string,
+  toolName: string,
+  params: Record<string, unknown>,
+  auth: { token?: string; headers?: Record<string, string> },
+  fetchFn: typeof globalThis.fetch,
+): Promise<unknown> {
+  const serverUrl = url.replace(/\/$/, "");
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(auth.headers ?? {}),
+  };
+  if (auth.token) {
+    headers.Authorization = `Bearer ${auth.token}`;
+  }
+
+  const res = await fetchFn(serverUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: toolName, arguments: params },
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`MCP tool call failed: ${res.status}`);
+  }
+  const json = (await res.json()) as { result?: unknown; error?: { message: string } };
+  if (json.error) {
+    throw new Error(`MCP RPC error: ${json.error.message}`);
+  }
+
+  // Extract text content
+  const result = json.result as { content?: Array<{ type: string; text?: string }> };
+  if (result?.content) {
+    const textItem = result.content.find((c) => c.type === "text");
+    if (textItem?.text) {
+      try { return JSON.parse(textItem.text); } catch { return textItem.text; }
+    }
+  }
+  return result;
+}
+
+// ============================================
+// Direct HTTPS Resolution
+// ============================================
+
+/**
+ * List available operations from an HTTPS API (registry type: 'https').
+ * Returns a single generic 'call' tool since we can't auto-discover REST endpoints
+ * without an OpenAPI spec.
+ */
+function listFromHttpsApi(url: string): AgentListing[] {
+  const hostname = new URL(url).hostname;
+  return [{
+    path: hostname,
+    description: `REST API at ${url}`,
+    publisher: hostname,
+    tools: [{
+      name: "call",
+      description: "Make an HTTP request to the API. Params: method, path, body, headers.",
+    }],
+    requiresAuth: false,
+  }];
+}
+
+/**
+ * Call an HTTPS API (registry type: 'https').
+ * Generic HTTP proxy with auth injection.
+ */
+async function callHttpsTool(
+  baseUrl: string,
+  _toolName: string,
+  params: Record<string, unknown>,
+  auth: { token?: string; headers?: Record<string, string> },
+  fetchFn: typeof globalThis.fetch,
+): Promise<unknown> {
+  const method = (params.method as string) ?? "GET";
+  const path = (params.path as string) ?? "";
+  const body = params.body as Record<string, unknown> | undefined;
+  const extraHeaders = (params.headers as Record<string, string>) ?? {};
+
+  const url = `${baseUrl.replace(/\/$/, "")}${path}`;
+  const headers: Record<string, string> = {
+    ...extraHeaders,
+    ...(auth.headers ?? {}),
+  };
+  if (auth.token) {
+    headers.Authorization = `Bearer ${auth.token}`;
+  }
+  if (body) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  const res = await fetchFn(url, {
+    method,
+    headers,
+    ...(body && { body: JSON.stringify(body) }),
+  });
+
+  const contentType = res.headers.get("content-type") ?? "";
+  if (contentType.includes("json")) {
+    return res.json();
+  }
+  return res.text();
+}
+
 // ============================================
 // Consumer Options
 // ============================================
@@ -320,10 +516,42 @@ export async function createRegistryConsumer(
   // Build the consumer
   const consumer: RegistryConsumer = {
     async list(): Promise<AgentListing[]> {
-      const results = await Promise.allSettled(
+      // Collect from standard registries
+      const registryResults = await Promise.allSettled(
         resolvedRegistries.map(listFromRegistry),
       );
-      return results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+      const listings = registryResults.flatMap((r) =>
+        r.status === "fulfilled" ? r.value : [],
+      );
+
+      // Also collect from direct MCP/HTTPS refs
+      for (const ref of resolvedRefs) {
+        if (!DIRECT_REGISTRY_TYPES.has(ref.registry)) continue;
+        const refEntry = (config.refs ?? []).find((r) => {
+          const n = normalizeRef(r);
+          return n.name === ref.name;
+        });
+        const url =
+          typeof refEntry === "object" ? refEntry?.url : undefined;
+        if (!url) continue;
+
+        try {
+          if (ref.registry === REGISTRY_TYPE_MCP) {
+            const mcpListings = await listFromMcpServer(
+              url,
+              { token: options.token },
+              fetchFn,
+            );
+            listings.push(...mcpListings);
+          } else if (ref.registry === REGISTRY_TYPE_HTTPS) {
+            listings.push(...listFromHttpsApi(url));
+          }
+        } catch {
+          // Skip unreachable direct refs during list
+        }
+      }
+
+      return listings;
     },
 
     refs(): ResolvedRef[] {
@@ -346,6 +574,33 @@ export async function createRegistryConsumer(
         );
       }
 
+      // Direct MCP ref — bypass registry, call MCP server directly
+      if (ref.registry === REGISTRY_TYPE_MCP) {
+        const refEntry = (config.refs ?? []).find((r) => {
+          const n = normalizeRef(r);
+          return n.name === ref.name;
+        });
+        const url = typeof refEntry === "object" ? refEntry?.url : undefined;
+        if (!url) {
+          throw new Error(`MCP ref "${refName}" has no url`);
+        }
+        return callMcpTool(url, tool, params, { token: options.token }, fetchFn);
+      }
+
+      // Direct HTTPS ref — bypass registry, call REST API directly
+      if (ref.registry === REGISTRY_TYPE_HTTPS) {
+        const refEntry = (config.refs ?? []).find((r) => {
+          const n = normalizeRef(r);
+          return n.name === ref.name;
+        });
+        const url = typeof refEntry === "object" ? refEntry?.url : undefined;
+        if (!url) {
+          throw new Error(`HTTPS ref "${refName}" has no url`);
+        }
+        return callHttpsTool(url, tool, params, { token: options.token }, fetchFn);
+      }
+
+      // Standard registry ref
       const registry = resolvedRegistries.find(
         (r) => r.url === ref.registry || r.name === ref.registry,
       );

package/src/registry.ts

@@ -96,8 +96,8 @@ export interface AgentRegistry {
   /** Register an event listener (global scope — fires for all agents) */
   on<T extends EventType>(eventType: T, callback: EventCallback<T>): void;
 
-  /** Emit an event to all listeners. Used by the runtime to push lifecycle events. */
-  emit(event: AgentEvent): Promise<void>;
+  /** Emit an event to all listeners. Accepts system events and custom events from CustomEventMap. */
+  emit(event: AgentEvent | CustomEventMap[keyof CustomEventMap]): Promise<void>;
 
   /**
    * Trigger a custom event. Only accepts custom event types (not system events
@@ -485,7 +485,7 @@ export function createAgentRegistry(
       eventBus.on(eventType, callback);
     },
 
-    async emit(event: AgentEvent): Promise<void> {
+    async emit(event: AgentEvent | CustomEventMap[keyof CustomEventMap]): Promise<void> {
       await eventBus.emit(event);
     },
 

package/src/server.ts

@@ -120,6 +120,19 @@ export interface AgentServerOptions {
   keyStore?: import("./key-manager.js").KeyStore;
   /** OIDC provider for user sign-in (authorization code flow) */
   oidcProvider?: OIDCProviderConfig;
+  /**
+   * Registry capabilities — advertised in MCP initialize response.
+   * When set, this server identifies as an agent registry (superset of MCP).
+   * Consumers use this to differentiate `registry` type from plain `mcp`.
+   */
+  registry?: {
+    /** Registry protocol version */
+    version?: string;
+    /** Feature flags (e.g., 'shared-oauth', 'agent-listing') */
+    features?: string[];
+    /** OAuth callback URL for shared OAuth flows */
+    oauthCallbackUrl?: string;
+  };
 }
 
 export interface AgentServer {
@@ -518,7 +531,16 @@ export function createAgentServer(
       case "initialize":
         return jsonRpcSuccess(request.id, {
           protocolVersion: "2024-11-05",
-          capabilities: { tools: { listChanged: false } },
+          capabilities: {
+            tools: { listChanged: false },
+            ...(options.registry && {
+              registry: {
+                version: options.registry.version ?? "1.0",
+                ...(options.registry.features && { features: options.registry.features }),
+                ...(options.registry.oauthCallbackUrl && { oauthCallbackUrl: options.registry.oauthCallbackUrl }),
+              },
+            }),
+          },
           serverInfo: { name: serverName, version: serverVersion },
         });
 
@@ -1178,7 +1200,7 @@ export function createAgentServer(
         return cors ? addCors(res) : res;
       }
 
-      // ── GET /.well-known/configuration → Server discovery ──
+      // ── GET /.well-known/configuration → Server discovery (deprecated, use MCP initialize capabilities) ──
       if (path === "/.well-known/configuration" && req.method === "GET") {
         const baseUrl = resolveBaseUrl(req);
         const res = jsonResponse({
@@ -1196,6 +1218,31 @@ export function createAgentServer(
         return cors ? addCors(res) : res;
       }
 
+      // ── GET /.well-known/oauth-authorization-server → OAuth Server Metadata (RFC 8414) ──
+      // Only exposed when the server requires auth (private registries).
+      // Public registries (e.g. registry.slash.com) skip this entirely.
+      if (
+        path === "/.well-known/oauth-authorization-server" &&
+        req.method === "GET" &&
+        (options.registry?.oauthCallbackUrl || serverSigningKeys.length > 0)
+      ) {
+        const baseUrl = resolveBaseUrl(req);
+        const res = jsonResponse({
+          issuer: baseUrl,
+          authorization_endpoint: `${baseUrl}/oauth/authorize`,
+          token_endpoint: `${baseUrl}/oauth/token`,
+          jwks_uri: `${baseUrl}/.well-known/jwks.json`,
+          response_types_supported: ["code"],
+          grant_types_supported: ["authorization_code", "client_credentials", "jwt_exchange"],
+          code_challenge_methods_supported: ["S256"],
+          token_endpoint_auth_methods_supported: ["client_secret_post", "none"],
+          ...(options.registry?.oauthCallbackUrl && {
+            registration_endpoint: `${baseUrl}/oauth/register`,
+          }),
+        });
+        return cors ? addCors(res) : res;
+      }
+
       // ── GET /list → List agents (legacy endpoint) ──
       if (path === "/list" && req.method === "GET") {
         const agents = registry.list();