mcp-expose 1.0.0 → 1.1.0

package/dist/nestjs/index.cjs

@@ -373,6 +373,7 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
       ...defaultAnnotations(method),
       ...opts.annotations
     },
+    scopes: opts.scopes,
     validate: toValidator(opts.input),
     async handler(args, ctx) {
       const missing = opts.input ? void 0 : checkRequired(schema, args);
@@ -421,6 +422,115 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
 }
 __name(createRouteTool, "createRouteTool");
 
+// src/core/oauth.ts
+var PROTECTED_RESOURCE_WELL_KNOWN = "/.well-known/oauth-protected-resource";
+function protectedResourceMetadataPaths(resource) {
+  const pathname = new URL(resource).pathname.replace(/\/+$/, "");
+  return pathname ? [
+    PROTECTED_RESOURCE_WELL_KNOWN + pathname,
+    PROTECTED_RESOURCE_WELL_KNOWN
+  ] : [
+    PROTECTED_RESOURCE_WELL_KNOWN
+  ];
+}
+__name(protectedResourceMetadataPaths, "protectedResourceMetadataPaths");
+function protectedResourceMetadataUrl(resource) {
+  return new URL(protectedResourceMetadataPaths(resource)[0], resource).href;
+}
+__name(protectedResourceMetadataUrl, "protectedResourceMetadataUrl");
+function validateOAuthOptions(o) {
+  let url;
+  try {
+    url = new URL(o.resource);
+  } catch {
+    throw new Error(`mcp-expose: oauth.resource must be an absolute URL, got ${JSON.stringify(o.resource)}`);
+  }
+  if (url.hash) throw new Error("mcp-expose: oauth.resource must not contain a fragment");
+  if (!o.authorizationServers?.length) throw new Error("mcp-expose: oauth.authorizationServers must not be empty");
+  if (typeof o.verifyToken !== "function") throw new Error("mcp-expose: oauth.verifyToken is required");
+}
+__name(validateOAuthOptions, "validateOAuthOptions");
+var quote = /* @__PURE__ */ __name((v) => `"${v.replace(/["\\]/g, "\\$&")}"`, "quote");
+function bearerChallenge(resource, params = {}) {
+  const parts = [];
+  if (params.error) parts.push(`error=${quote(params.error)}`);
+  if (params.errorDescription) parts.push(`error_description=${quote(params.errorDescription)}`);
+  if (params.scope?.length) parts.push(`scope=${quote(params.scope.join(" "))}`);
+  parts.push(`resource_metadata=${quote(protectedResourceMetadataUrl(resource))}`);
+  return `Bearer ${parts.join(", ")}`;
+}
+__name(bearerChallenge, "bearerChallenge");
+function bearerToken(headers) {
+  const m = /^Bearer[ ]+([^\s,]+)\s*$/i.exec(headers.authorization ?? "");
+  return m?.[1];
+}
+__name(bearerToken, "bearerToken");
+async function authenticate(o, headers) {
+  const token = bearerToken(headers);
+  if (!token) {
+    return {
+      ok: false,
+      status: 401,
+      error: "unauthorized",
+      description: "Authorization required",
+      challenge: bearerChallenge(o.resource, {
+        scope: o.requiredScopes
+      })
+    };
+  }
+  let auth;
+  try {
+    auth = await o.verifyToken(token, {
+      resource: o.resource,
+      headers
+    });
+  } catch {
+    auth = void 0;
+  }
+  if (!auth) return deny(o, 401, "invalid_token", "The access token is invalid");
+  if (auth.expiresAt !== void 0 && auth.expiresAt * 1e3 <= Date.now()) {
+    return deny(o, 401, "invalid_token", "The access token has expired");
+  }
+  const missing = missingScopes(auth, o.requiredScopes);
+  if (missing.length) {
+    const scope = [
+      .../* @__PURE__ */ new Set([
+        ...auth.scopes ?? [],
+        ...o.requiredScopes ?? []
+      ])
+    ];
+    return deny(o, 403, "insufficient_scope", `Missing scope: ${missing.join(" ")}`, scope);
+  }
+  return {
+    ok: true,
+    auth: {
+      ...auth,
+      scopes: auth.scopes ?? []
+    }
+  };
+}
+__name(authenticate, "authenticate");
+function deny(o, status, error, description, scope) {
+  return {
+    ok: false,
+    status,
+    error,
+    description,
+    challenge: bearerChallenge(o.resource, {
+      error,
+      errorDescription: description,
+      scope
+    })
+  };
+}
+__name(deny, "deny");
+function missingScopes(auth, required) {
+  if (!required?.length) return [];
+  const granted = new Set(auth?.scopes ?? []);
+  return required.filter((s) => !granted.has(s));
+}
+__name(missingScopes, "missingScopes");
+
 // src/core/server.ts
 var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-11-25",
@@ -455,6 +565,7 @@ var McpServer = class {
   loaders = [];
   constructor(options) {
     this.options = options;
+    if (options.oauth) validateOAuthOptions(options.oauth);
   }
   /** Register a tool. Throws on duplicate names. */
   addTool(tool) {
@@ -589,6 +700,79 @@ var McpServer = class {
     return (allowed ?? []).includes(origin);
   }
   /**
+  * Paths on which adapters serve the OAuth Protected Resource Metadata
+  * (empty when `oauth` is not configured). They must be public: no auth middleware.
+  */
+  get oauthMetadataPaths() {
+    return this.options.oauth ? protectedResourceMetadataPaths(this.options.oauth.resource) : [];
+  }
+  /** The OAuth Protected Resource Metadata document (RFC 9728). */
+  async protectedResourceMetadata() {
+    const o = this.options.oauth;
+    if (!o) throw new Error("mcp-expose: the oauth option is not configured");
+    await this.load();
+    const scopes = o.scopesSupported ?? [
+      .../* @__PURE__ */ new Set([
+        ...o.requiredScopes ?? [],
+        ...[
+          ...this.tools.values()
+        ].flatMap((t) => t.scopes ?? [])
+      ])
+    ];
+    return {
+      resource: o.resource,
+      authorization_servers: o.authorizationServers,
+      ...scopes.length ? {
+        scopes_supported: scopes
+      } : {},
+      bearer_methods_supported: [
+        "header"
+      ],
+      ...o.resourceName ? {
+        resource_name: o.resourceName
+      } : {},
+      ...o.resourceDocumentation ? {
+        resource_documentation: o.resourceDocumentation
+      } : {},
+      ...o.metadata
+    };
+  }
+  /** HTTP handler for the metadata paths. Public and CORS-enabled so browser-based clients can read it. */
+  async handleMetadataHttp(req) {
+    const cors = {
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "GET, OPTIONS"
+    };
+    const method = req.method.toUpperCase();
+    if (!this.options.oauth) return {
+      status: 404,
+      headers: {}
+    };
+    if (method === "OPTIONS") return {
+      status: 204,
+      headers: {
+        ...cors,
+        "access-control-allow-headers": "*"
+      }
+    };
+    if (method !== "GET" && method !== "HEAD") return {
+      status: 405,
+      headers: {
+        allow: "GET, OPTIONS"
+      }
+    };
+    const body = JSON.stringify(await this.protectedResourceMetadata());
+    return {
+      status: 200,
+      headers: {
+        ...cors,
+        "content-type": "application/json",
+        "cache-control": "public, max-age=3600"
+      },
+      body: method === "HEAD" ? void 0 : body
+    };
+  }
+  /**
   * Framework-neutral Streamable HTTP handler. Adapters convert their request
   * into McpHttpRequest, call this, and write the McpHttpResponse back.
   */
@@ -603,6 +787,15 @@ var McpServer = class {
         body: JSON.stringify(fail(null, INVALID_REQUEST, "Origin not allowed"))
       };
     }
+    const oauth = this.options.oauth;
+    if (oauth) {
+      const outcome = await authenticate(oauth, req.headers);
+      if (!outcome.ok) return authError(outcome);
+      ctx = {
+        ...ctx,
+        auth: outcome.auth
+      };
+    }
     if (req.method.toUpperCase() !== "POST") {
       return {
         status: 405,
@@ -623,6 +816,27 @@ var McpServer = class {
         };
       }
     }
+    if (oauth) {
+      await this.load();
+      const calls = Array.isArray(body) ? body : [
+        body
+      ];
+      for (const m of calls) {
+        if (m?.method !== "tools/call") continue;
+        const tool = this.tools.get(m.params?.name);
+        const missing = missingScopes(ctx.auth, tool?.scopes);
+        if (missing.length) {
+          const scope = [
+            .../* @__PURE__ */ new Set([
+              ...ctx.auth?.scopes ?? [],
+              ...oauth.requiredScopes ?? [],
+              ...tool?.scopes ?? []
+            ])
+          ];
+          return authError(deny(oauth, 403, "insufficient_scope", `Tool "${tool.name}" needs scope: ${missing.join(" ")}`, scope));
+        }
+      }
+    }
     const response = await this.handleMessage(body, ctx);
     if (response === null) return {
       status: 202,
@@ -635,6 +849,20 @@ var McpServer = class {
     };
   }
 };
+function authError(o) {
+  return {
+    status: o.status,
+    headers: {
+      "content-type": "application/json",
+      "www-authenticate": o.challenge
+    },
+    body: JSON.stringify({
+      error: o.error,
+      error_description: o.description
+    })
+  };
+}
+__name(authError, "authError");
 
 // src/nestjs/dto-schema.ts
 var PRIMITIVES = /* @__PURE__ */ new Map([
@@ -843,11 +1071,13 @@ var McpService = class {
   discovery;
   appConfig;
   options;
+  adapterHost;
   server;
-  constructor(discovery, appConfig, options) {
+  constructor(discovery, appConfig, options, adapterHost) {
     this.discovery = discovery;
     this.appConfig = appConfig;
     this.options = options;
+    this.adapterHost = adapterHost;
     this.server = new McpServer(options);
     for (const t of options.tools ?? []) this.server.addTool(t);
     const dispatch = createFetchDispatcher({
@@ -860,6 +1090,26 @@ var McpService = class {
       }
     });
   }
+  /**
+  * Serve the OAuth Protected Resource Metadata at the root of the app, outside
+  * the global prefix and guards (it must be public). Runs before Nest registers
+  * its own routes.
+  */
+  onModuleInit() {
+    const adapter = this.adapterHost?.httpAdapter;
+    if (!adapter) return;
+    for (const path of this.server.oauthMetadataPaths) {
+      const handler = /* @__PURE__ */ __name((method) => async (_req, res) => {
+        const out = await this.server.handleMetadataHttp({
+          method
+        });
+        for (const [k, v] of Object.entries(out.headers)) adapter.setHeader(res, k, v);
+        adapter.reply(res, out.body, out.status);
+      }, "handler");
+      adapter.get(path, handler("GET"));
+      adapter.options(path, handler("OPTIONS"));
+    }
+  }
   globalPrefix() {
     return this.appConfig.getGlobalPrefix?.() ?? "";
   }
@@ -992,6 +1242,7 @@ __name(toSnake, "toSnake");
 (0, import_common.Inject)(import_core.DiscoveryService)(McpService, void 0, 0);
 (0, import_common.Inject)(import_core.ApplicationConfig)(McpService, void 0, 1);
 (0, import_common.Inject)(MCP_MODULE_OPTIONS)(McpService, void 0, 2);
+(0, import_common.Inject)(import_core.HttpAdapterHost)(McpService, void 0, 3);
 function createMcpController(options) {
   let McpController = class McpController {
     static {
@@ -1034,6 +1285,7 @@ function createMcpController(options) {
   (0, import_common.Req)()(proto, "handle", 0);
   (0, import_common.Res)()(proto, "handle", 1);
   if (options.guards?.length) (0, import_common.UseGuards)(...options.guards)(McpController);
+  for (const decorate of options.decorators ?? []) decorate(McpController);
   return McpController;
 }
 __name(createMcpController, "createMcpController");