@corbits/mcp 0.1.0 → 0.2.0

package/dist/hub/discover.d.ts

@@ -1,37 +1,62 @@
 import type { DB } from "@intx/db";
+import type { FetchLike } from "@intx/harness";
 import type { TenantEnv } from "@intx/hub-api";
 import { type CredentialCipher } from "@intx/types";
 import type { Hono, MiddlewareHandler } from "hono";
-import { type FetchLike, type McpTool, type McpServerInfo } from "../client.js";
+import { type McpTool, type McpServerInfo } from "../client.js";
 export type MountMcpDiscoveryOpts = {
     readonly db: DB["db"];
     readonly cipher: CredentialCipher;
     /** The host's stock grant middleware, so authority is checked exactly once, its way. */
     readonly requireGrant: MiddlewareHandler<TenantEnv>;
+    /**
+     * Further origins a credential may be sent to, keyed by the credential's
+     * pinned origin, for a server whose MCP endpoint is not on that origin.
+     * Host-wide: an entry applies to every tenant's credential pinned to that
+     * origin. Passed through to `@corbits/credential-http`. Empty by default.
+     */
+    readonly extraOrigins?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Allow plain-http loopback targets, for local development only. Off by
+     * default so the route cannot be pointed at the hub's own ports.
+     */
+    readonly allowLoopback?: boolean;
     /** Reported when a discovery attempt fails; the caller only sees a message. */
     readonly onError?: (error: unknown, context: {
         url: string;
     }) => void;
 };
+export type McpCredential = {
+    readonly secret: string;
+    /** The provider's API origin the secret is pinned to, when it has one. */
+    readonly origin?: string;
+};
 /**
- * Read a tenant credential's decrypted secret. Scoped by tenant so a
- * credential id from another tenant reads as absent, not as a secret.
+ * Read a tenant credential's decrypted secret and the origin it is pinned to.
+ * Scoped by tenant so a credential id from another tenant reads as absent,
+ * not as a secret; a revoked, errored or expired credential reads as absent
+ * too.
  */
-export declare function readCredentialSecret(opts: {
+export declare function readCredential(opts: {
     readonly db: DB["db"];
     readonly cipher: CredentialCipher;
     readonly tenantId: string;
     readonly credentialId: string;
-}): Promise<string | undefined>;
+}): Promise<McpCredential | undefined>;
 export type McpDiscovery = {
     readonly serverInfo: McpServerInfo;
     readonly tools: readonly McpTool[];
 };
-/** Handshake and read a server's catalog over an origin-pinned fetch. */
+/**
+ * Handshake and read a server's catalog over a fetch pinned to the
+ * credential's origin, or to the URL's origin when no secret is sent.
+ */
 export declare function discoverMcpServer(args: {
     readonly url: string;
-    readonly secret?: string;
+    readonly credential?: McpCredential;
+    readonly extraOrigins?: Readonly<Record<string, readonly string[]>>;
     readonly fetch?: FetchLike;
+    readonly timeoutMs?: number;
 }): Promise<McpDiscovery>;
 /**
  * Mount `POST /mcp/discover` on a tenant router. It answers with the server's

package/dist/hub/discover.js

@@ -1,57 +1,107 @@
 // Server-side MCP catalog discovery. The browser never holds an MCP server's
 // token, so the only place an OAuth-protected server's `tools/list` can be
 // read is here, behind the hub's own tenant-member gate and with the secret
-// decrypted in this process and sent only to the server's own origin.
-import { credential } from "@intx/db/schema";
+// decrypted in this process and sent only to the credential's own origin.
+import { credential, provider } from "@intx/db/schema";
 import { credentialAad } from "@intx/types";
-import { MCP_NO_TOKEN_SENTINEL, mcpOriginPinnedFetch, } from "@corbits/credential-mcp";
+import { createOriginPinnedFetch, MCP_NO_TOKEN_SENTINEL, } from "@corbits/credential-http";
 import { type } from "arktype";
 import { and, eq } from "drizzle-orm";
-import { mcpInitialize, mcpListTools, } from "../client.js";
+import { McpError, mcpInitialize, mcpListTools, } from "../client.js";
 import { parseMcpEndpoint } from "../url.js";
 const DiscoverBody = type({
     url: "string > 0",
     "credentialId?": "string > 0",
 });
 /**
- * Read a tenant credential's decrypted secret. Scoped by tenant so a
- * credential id from another tenant reads as absent, not as a secret.
+ * Read a tenant credential's decrypted secret and the origin it is pinned to.
+ * Scoped by tenant so a credential id from another tenant reads as absent,
+ * not as a secret; a revoked, errored or expired credential reads as absent
+ * too.
  */
-export async function readCredentialSecret(opts) {
+export async function readCredential(opts) {
     const [row] = await opts.db
-        .select()
+        .select({
+        id: credential.id,
+        secret: credential.secret,
+        status: credential.status,
+        expiresAt: credential.expiresAt,
+        apiBaseUrl: provider.apiBaseUrl,
+    })
         .from(credential)
+        .innerJoin(provider, eq(provider.id, credential.providerId))
         .where(and(eq(credential.id, opts.credentialId), eq(credential.tenantId, opts.tenantId)))
         .limit(1);
-    if (row === undefined || row.secret === null)
+    if (row === undefined ||
+        row.status !== "active" ||
+        (row.expiresAt !== null && row.expiresAt.getTime() <= Date.now())) {
         return undefined;
-    return opts.cipher.decrypt(row.secret, credentialAad(row.id, "secret"));
+    }
+    const secret = await opts.cipher.decrypt(row.secret, credentialAad(row.id, "secret"));
+    return row.apiBaseUrl === null
+        ? { secret }
+        : { secret, origin: new URL(row.apiBaseUrl).origin };
 }
+const HEADER_VALUE = /^[\t\x20-\x7e]*$/;
 /** A 3xx would send the bearer onward, so the pinned fetch's manual redirect
  * is turned into a refusal rather than a response the client tries to read. */
 function refusingRedirects(inner) {
     return async (input, init) => {
         const response = await inner(input, init);
         if (response.status >= 300 && response.status < 400) {
-            throw new Error(`the MCP server answered a ${String(response.status)} redirect; refusing to follow it`);
+            throw new McpError(`the MCP server answered a ${String(response.status)} redirect; refusing to follow it`);
         }
         return response;
     };
 }
-/** Handshake and read a server's catalog over an origin-pinned fetch. */
+/** How long one discovery request, including its body, may take. */
+const DISCOVERY_TIMEOUT_MS = 30_000;
+/**
+ * Handshake and read a server's catalog over a fetch pinned to the
+ * credential's origin, or to the URL's origin when no secret is sent.
+ */
 export async function discoverMcpServer(args) {
     const target = parseMcpEndpoint(args.url);
-    const token = args.secret === undefined || args.secret === MCP_NO_TOKEN_SENTINEL
+    const secret = args.credential?.secret;
+    const token = secret === undefined || secret === MCP_NO_TOKEN_SENTINEL
         ? undefined
-        : args.secret;
-    const pinned = refusingRedirects(mcpOriginPinnedFetch({
-        pinnedOrigin: target.origin,
-        readToken: () => token,
-        ...(args.fetch !== undefined ? { fetch: args.fetch } : {}),
+        : secret;
+    const origin = token === undefined ? target.origin : args.credential?.origin;
+    if (origin === undefined) {
+        throw new McpError("the credential's provider has no API origin to pin to");
+    }
+    // A secret that is not a valid header value makes fetch throw a message
+    // quoting it, so it is refused here with a fixed one.
+    if (token !== undefined && !HEADER_VALUE.test(token)) {
+        throw new McpError("the credential's secret is not a valid header value");
+    }
+    const extraOrigins = Object.entries(args.extraOrigins ?? {}).flatMap(([pinned, extra]) => (new URL(pinned).origin === origin ? extra : []));
+    const allowed = [origin, ...extraOrigins.map((o) => new URL(o).origin)];
+    if (!allowed.includes(target.origin)) {
+        throw new McpError(`credential is pinned to ${origin}; refusing cross-origin request to ${target.origin}`);
+    }
+    const pinned = refusingRedirects(createOriginPinnedFetch({
+        origin,
+        header: "authorization",
+        readValue: () => (token === undefined ? undefined : `Bearer ${token}`),
+        extraOrigins,
+        fetch: args.fetch ?? globalThis.fetch,
     }));
-    const serverInfo = await mcpInitialize(args.url, { fetch: pinned });
-    const tools = await mcpListTools(args.url, { fetch: pinned });
-    return { serverInfo, tools };
+    const client = {
+        fetch: pinned,
+        timeoutMs: args.timeoutMs ?? DISCOVERY_TIMEOUT_MS,
+    };
+    const session = await mcpInitialize(args.url, client);
+    const tools = await mcpListTools(args.url, { ...client, session });
+    return {
+        serverInfo: {
+            protocolVersion: session.protocolVersion,
+            ...(session.serverInfo !== undefined
+                ? { serverInfo: session.serverInfo }
+                : {}),
+        },
+        tools,
+    };
 }
 /**
  * Mount `POST /mcp/discover` on a tenant router. It answers with the server's
@@ -71,29 +121,42 @@ export function mountMcpDiscovery(app, opts) {
         catch (cause) {
             return c.json({ error: cause instanceof Error ? cause.message : String(cause) }, 400);
         }
+        if (target.protocol === "http:" && opts.allowLoopback !== true) {
+            return c.json({ error: "the MCP server URL must be https" }, 400);
+        }
         try {
-            const secret = body.credentialId === undefined
+            const found = body.credentialId === undefined
                 ? undefined
-                : await readCredentialSecret({
+                : await readCredential({
                     db: opts.db,
                     cipher: opts.cipher,
                     tenantId: c.get("tenant").id,
                     credentialId: body.credentialId,
                 });
-            if (body.credentialId !== undefined && secret === undefined) {
+            if (body.credentialId !== undefined && found === undefined) {
                 return c.json({ error: "credential not found" }, 404);
             }
             const data = await discoverMcpServer({
                 url: body.url,
-                ...(secret !== undefined ? { secret } : {}),
+                ...(found !== undefined ? { credential: found } : {}),
+                ...(opts.extraOrigins !== undefined
+                    ? { extraOrigins: opts.extraOrigins }
+                    : {}),
             });
             return c.json({ data });
         }
         catch (cause) {
-            opts.onError?.(cause, { url: body.url });
-            // The message describes the handshake, never the material it used.
+            // Only this package's own messages are passed on: anything else, such
+            // as a fetch error, may quote the material the request carried. An
+            // upstream status is not echoed, so the route is no port-probing oracle.
+            const error = cause instanceof McpError && cause.status === undefined
+                ? cause
+                : new McpError(cause instanceof McpError
+                    ? "the server refused the request"
+                    : "the handshake failed");
+            opts.onError?.(error, { url: body.url });
             return c.json({
-                error: `the MCP server at ${target.origin} could not be discovered: ${cause instanceof Error ? cause.message : String(cause)}`,
+                error: `the MCP server at ${target.origin} could not be discovered: ${error.message}`,
             }, 422);
         }
     });

package/dist/hub/index.d.ts

@@ -1 +1 @@
-export { mountMcpDiscovery, discoverMcpServer, readCredentialSecret, type McpDiscovery, type MountMcpDiscoveryOpts, } from "./discover.js";
+export { mountMcpDiscovery, discoverMcpServer, readCredential, type McpCredential, type McpDiscovery, type MountMcpDiscoveryOpts, } from "./discover.js";

package/dist/hub/index.js

@@ -1,4 +1,4 @@
 // Server-only entry point: the hub-hosted MCP discovery mount. The root and
 // `./sidecar-bundle` entries stay free of `hono` and `@intx/db` so neither a
 // browser bundle nor a deployed agent ever reaches them.
-export { mountMcpDiscovery, discoverMcpServer, readCredentialSecret, } from "./discover.js";
+export { mountMcpDiscovery, discoverMcpServer, readCredential, } from "./discover.js";

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { mcpTools, type McpServerConfig, type McpToolsEnv, type McpToolsOptions, } from "./tool.js";
 export { qualifiedName, isAskExempt, toolDescription } from "./naming.js";
-export { mcpInitialize, mcpListTools, mcpCallTool, McpError, McpToolSchema, type McpTool, type McpToolResult, type McpClientOptions, type FetchLike, } from "./client.js";
+export { mcpInitialize, mcpListTools, mcpCallTool, McpError, McpToolSchema, type McpTool, type McpToolResult, type McpClientOptions, type McpSession, } from "./client.js";
+export { discoverMcpLoginEntry, registerMcpClient, mcpClientConfig, selectMcpScopes, type DiscoverMcpLoginEntryOptions, type McpAuthorizationServer, type McpClientConfigOptions, type McpClientRegistration, type McpLoginEntry, type RegisterMcpClientOptions, type SelectMcpScopesOptions, } from "./oauth-discovery.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { mcpTools, } from "./tool.js";
 export { qualifiedName, isAskExempt, toolDescription } from "./naming.js";
 export { mcpInitialize, mcpListTools, mcpCallTool, McpError, McpToolSchema, } from "./client.js";
+export { discoverMcpLoginEntry, registerMcpClient, mcpClientConfig, selectMcpScopes, } from "./oauth-discovery.js";

package/dist/naming.d.ts

@@ -1,6 +1,20 @@
 import type { McpTool } from "./client.js";
 /** `<server>.<tool>`, the grantable unit: `tool:<server>.*` covers a server. */
 export declare function qualifiedName(server: string, tool: string): string;
+/**
+ * Refuse a catalog whose names could reach another server's grants: a server
+ * name with a `.` could make `<server>.<tool>` fall under another server's
+ * `tool:<other>.*`, and a repeated tool name would make two tools one name.
+ */
+export declare function assertCatalogNames(server: string, tools: readonly McpTool[]): void;
+/**
+ * Refuse a server list before any request: every name non-empty and unique,
+ * so no two servers share a grant prefix, and every URL a permitted endpoint.
+ */
+export declare function assertServers(servers: readonly {
+    name: string;
+    url: string;
+}[], label: string): void;
 export declare function toolDescription(tool: McpTool, server: string): string;
 /**
  * Whether `qualified` may drop below the `ask` floor: it must be on the

package/dist/naming.js

@@ -1,10 +1,43 @@
 // Naming and the ask floor, shared by the author-time `mcpTools` factory and
 // the deployed `mcpServers` sidecar bundle so both project a server's catalog
 // onto identical tool names and identical approval marks.
+import { parseMcpEndpoint } from "./url.js";
 /** `<server>.<tool>`, the grantable unit: `tool:<server>.*` covers a server. */
 export function qualifiedName(server, tool) {
     return `${server}.${tool}`;
 }
+/**
+ * Refuse a catalog whose names could reach another server's grants: a server
+ * name with a `.` could make `<server>.<tool>` fall under another server's
+ * `tool:<other>.*`, and a repeated tool name would make two tools one name.
+ */
+export function assertCatalogNames(server, tools) {
+    if (server.includes(".")) {
+        throw new Error(`MCP server name "${server}" must not contain "."; it would overlap another server's grants`);
+    }
+    const seen = new Set();
+    for (const tool of tools) {
+        if (seen.has(tool.name)) {
+            throw new Error(`MCP server "${server}" lists the tool "${tool.name}" more than once`);
+        }
+        seen.add(tool.name);
+    }
+}
+/**
+ * Refuse a server list before any request: every name non-empty and unique,
+ * so no two servers share a grant prefix, and every URL a permitted endpoint.
+ */
+export function assertServers(servers, label) {
+    const seen = new Set();
+    for (const { name, url } of servers) {
+        if (name.length === 0)
+            throw new Error(`empty ${label}`);
+        if (seen.has(name))
+            throw new Error(`duplicate ${label} "${name}"`);
+        seen.add(name);
+        parseMcpEndpoint(url);
+    }
+}
 export function toolDescription(tool, server) {
     const hints = Object.entries(tool.annotations ?? {})
         .filter(([, v]) => v === true)

package/dist/oauth-discovery.d.ts

@@ -0,0 +1,71 @@
+import type { FetchLike } from "@intx/harness";
+import { type OAuthClientConfig } from "@corbits/oauth-core";
+export type McpAuthorizationServer = {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint?: string;
+    grantTypesSupported?: readonly string[];
+    scopesSupported?: readonly string[];
+    tokenEndpointAuthMethodsSupported?: readonly string[];
+    codeChallengeMethodsSupported?: readonly string[];
+};
+export type McpLoginEntry = {
+    resourceUrl: string;
+    authorizationServer: McpAuthorizationServer;
+    resourceScopesSupported?: readonly string[];
+};
+export type DiscoverMcpLoginEntryOptions = {
+    resourceUrl: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+};
+export type RegisterMcpClientOptions = {
+    registrationEndpoint: string;
+    redirectUris: readonly string[];
+    clientName: string;
+    grantTypesSupported?: readonly string[];
+    scope?: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+};
+export type McpClientRegistration = {
+    clientId: string;
+    grantTypes: string[];
+    scope?: string;
+};
+export type McpClientConfigOptions = {
+    clientId: string;
+    redirectUri: string;
+    scopes?: readonly string[];
+    challengeScope?: string;
+    wantRefresh?: boolean;
+    extraAuthorizeParams?: Record<string, string>;
+    tokenTimeoutMs?: number;
+};
+export type SelectMcpScopesOptions = {
+    entry: McpLoginEntry;
+    challengeScope?: string;
+    wantRefresh?: boolean;
+};
+export declare function discoverMcpLoginEntry(opts: DiscoverMcpLoginEntryOptions): Promise<McpLoginEntry>;
+/**
+ * Register a loopback public client with the authorization server (RFC 7591).
+ * Loopback clients cannot keep a secret, so registration requests
+ * `token_endpoint_auth_method: "none"`. `grant_types` is negotiated from
+ * `grantTypesSupported` (see grantTypesToRequest); `scope`, when supplied, is
+ * carried on the registration request per RFC 7591 §2. Throws
+ * OAuthDiscoveryError when the server has no registration endpoint or
+ * rejects the request.
+ */
+export declare function registerMcpClient(opts: RegisterMcpClientOptions): Promise<McpClientRegistration>;
+export declare function selectMcpScopes(opts: SelectMcpScopesOptions): string[];
+/**
+ * Build the OAuth client config for a discovered entry plus a registered
+ * client id. The RFC 8707 `resource` indicator binds the token to the MCP
+ * server; callers pass further provider-required params through
+ * `extraAuthorizeParams`. Scopes come from `selectMcpScopes` unless the
+ * caller passes an explicit `scopes` override; `wantRefresh` defaults to
+ * true, matching this package's default refresh_token registration request.
+ */
+export declare function mcpClientConfig(entry: McpLoginEntry, opts: McpClientConfigOptions): OAuthClientConfig;