mcp-expose 1.0.0 → 1.1.0

package/dist/oauth-8RmQamGP.d.cts

@@ -0,0 +1,75 @@
+/**
+ * OAuth 2.1 support per the MCP authorization spec: the MCP endpoint acts as an
+ * OAuth *resource server*. It publishes Protected Resource Metadata (RFC 9728),
+ * answers unauthenticated requests with a `WWW-Authenticate` challenge that
+ * tells the client where to log in, and checks bearer tokens with a verifier
+ * you provide (see `jwtVerifier` / `introspectionVerifier` in `mcp-expose/oauth`).
+ *
+ * Runtime-agnostic: no `node:*` imports.
+ */
+/** Who the access token belongs to and what it allows. Available to tools as `ctx.auth`. */
+interface AuthInfo {
+    /** The raw access token. */
+    token: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Subject (user id), e.g. the JWT `sub` claim. */
+    subject?: string;
+    /** OAuth client the token was issued to. */
+    clientId?: string;
+    /** Expiry, in seconds since the epoch. Expired tokens are rejected. */
+    expiresAt?: number;
+    /** All claims / introspection fields. */
+    claims?: Record<string, unknown>;
+}
+interface VerifyTokenContext {
+    /** The canonical resource URL (`oauth.resource`). Tokens must be issued for it (audience). */
+    resource: string;
+    /** Lower-cased headers of the MCP request. */
+    headers: Record<string, string>;
+}
+/**
+ * Checks an access token. Return its AuthInfo, or `undefined` / throw when the
+ * token is invalid. It MUST check that the token was issued for this server
+ * (audience = `ctx.resource`), or tokens meant for other services would be accepted.
+ */
+type TokenVerifier = (token: string, ctx: VerifyTokenContext) => AuthInfo | undefined | null | Promise<AuthInfo | undefined | null>;
+interface OAuthOptions {
+    /**
+     * Canonical, public URL of the MCP endpoint, e.g. `https://api.example.com/mcp`.
+     * Clients request tokens for this resource, and it must match the URL they connect to.
+     */
+    resource: string;
+    /** Issuer URLs of the authorization servers that issue tokens for this server. */
+    authorizationServers: string[];
+    /** Checks bearer tokens. */
+    verifyToken: TokenVerifier;
+    /** Scopes every token needs to use the MCP endpoint at all. */
+    requiredScopes?: string[];
+    /** Scopes advertised in the metadata. @default requiredScopes plus every tool's `scopes` */
+    scopesSupported?: string[];
+    /** Human-readable name shown by clients. */
+    resourceName?: string;
+    /** URL of documentation for developers. */
+    resourceDocumentation?: string;
+    /** Extra fields merged into the Protected Resource Metadata document. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Paths the metadata is served on, per RFC 9728: the well-known prefix with the
+ * resource path appended (`/.well-known/oauth-protected-resource/mcp`), plus the
+ * bare well-known path that older clients fall back to.
+ */
+declare function protectedResourceMetadataPaths(resource: string): string[];
+/** Absolute URL of the metadata document, used in `WWW-Authenticate`. */
+declare function protectedResourceMetadataUrl(resource: string): string;
+/** Build a `WWW-Authenticate: Bearer ...` challenge (RFC 6750 + RFC 9728). */
+declare function bearerChallenge(resource: string, params?: {
+    error?: string;
+    errorDescription?: string;
+    scope?: string[];
+}): string;
+/** Parse a space-separated `scope` string or an array of scopes. */
+declare function parseScopes(value: unknown): string[];
+
+export { type AuthInfo as A, type OAuthOptions as O, type TokenVerifier as T, type VerifyTokenContext as V, protectedResourceMetadataPaths as a, bearerChallenge as b, protectedResourceMetadataUrl as c, parseScopes as p };

package/dist/oauth-8RmQamGP.d.ts

@@ -0,0 +1,75 @@
+/**
+ * OAuth 2.1 support per the MCP authorization spec: the MCP endpoint acts as an
+ * OAuth *resource server*. It publishes Protected Resource Metadata (RFC 9728),
+ * answers unauthenticated requests with a `WWW-Authenticate` challenge that
+ * tells the client where to log in, and checks bearer tokens with a verifier
+ * you provide (see `jwtVerifier` / `introspectionVerifier` in `mcp-expose/oauth`).
+ *
+ * Runtime-agnostic: no `node:*` imports.
+ */
+/** Who the access token belongs to and what it allows. Available to tools as `ctx.auth`. */
+interface AuthInfo {
+    /** The raw access token. */
+    token: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Subject (user id), e.g. the JWT `sub` claim. */
+    subject?: string;
+    /** OAuth client the token was issued to. */
+    clientId?: string;
+    /** Expiry, in seconds since the epoch. Expired tokens are rejected. */
+    expiresAt?: number;
+    /** All claims / introspection fields. */
+    claims?: Record<string, unknown>;
+}
+interface VerifyTokenContext {
+    /** The canonical resource URL (`oauth.resource`). Tokens must be issued for it (audience). */
+    resource: string;
+    /** Lower-cased headers of the MCP request. */
+    headers: Record<string, string>;
+}
+/**
+ * Checks an access token. Return its AuthInfo, or `undefined` / throw when the
+ * token is invalid. It MUST check that the token was issued for this server
+ * (audience = `ctx.resource`), or tokens meant for other services would be accepted.
+ */
+type TokenVerifier = (token: string, ctx: VerifyTokenContext) => AuthInfo | undefined | null | Promise<AuthInfo | undefined | null>;
+interface OAuthOptions {
+    /**
+     * Canonical, public URL of the MCP endpoint, e.g. `https://api.example.com/mcp`.
+     * Clients request tokens for this resource, and it must match the URL they connect to.
+     */
+    resource: string;
+    /** Issuer URLs of the authorization servers that issue tokens for this server. */
+    authorizationServers: string[];
+    /** Checks bearer tokens. */
+    verifyToken: TokenVerifier;
+    /** Scopes every token needs to use the MCP endpoint at all. */
+    requiredScopes?: string[];
+    /** Scopes advertised in the metadata. @default requiredScopes plus every tool's `scopes` */
+    scopesSupported?: string[];
+    /** Human-readable name shown by clients. */
+    resourceName?: string;
+    /** URL of documentation for developers. */
+    resourceDocumentation?: string;
+    /** Extra fields merged into the Protected Resource Metadata document. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Paths the metadata is served on, per RFC 9728: the well-known prefix with the
+ * resource path appended (`/.well-known/oauth-protected-resource/mcp`), plus the
+ * bare well-known path that older clients fall back to.
+ */
+declare function protectedResourceMetadataPaths(resource: string): string[];
+/** Absolute URL of the metadata document, used in `WWW-Authenticate`. */
+declare function protectedResourceMetadataUrl(resource: string): string;
+/** Build a `WWW-Authenticate: Bearer ...` challenge (RFC 6750 + RFC 9728). */
+declare function bearerChallenge(resource: string, params?: {
+    error?: string;
+    errorDescription?: string;
+    scope?: string[];
+}): string;
+/** Parse a space-separated `scope` string or an array of scopes. */
+declare function parseScopes(value: unknown): string[];
+
+export { type AuthInfo as A, type OAuthOptions as O, type TokenVerifier as T, type VerifyTokenContext as V, protectedResourceMetadataPaths as a, bearerChallenge as b, protectedResourceMetadataUrl as c, parseScopes as p };

package/dist/{server-fzkb-wJo.d.ts → server-BFQ_Hdh9.d.cts}

@@ -1,3 +1,5 @@
+import { O as OAuthOptions, A as AuthInfo } from './oauth-8RmQamGP.cjs';
+
 /**
  * Shared types for mcp-expose. Everything in `core` is runtime-agnostic
  * (no `node:*` imports) so it also works on Bun, Deno and edge runtimes.
@@ -48,6 +50,8 @@ interface ToolContext {
     clientIp?: string;
     /** Framework-specific raw request object (Express req, Koa ctx, Hono context...). */
     raw?: unknown;
+    /** The verified access token, when the `oauth` option is enabled. */
+    auth?: AuthInfo;
 }
 /** A fully resolved MCP tool. */
 interface McpToolDefinition {
@@ -57,6 +61,12 @@ interface McpToolDefinition {
     inputSchema: JsonSchema;
     annotations?: ToolAnnotations;
     handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
+    /**
+     * OAuth scopes the access token needs to call this tool (only checked when the
+     * `oauth` option is enabled). Missing scopes answer HTTP 403 `insufficient_scope`,
+     * so the client can ask the user for more access.
+     */
+    scopes?: string[];
     /** Optional validator run before the handler (from Standard Schema inputs). */
     validate?: (args: unknown) => Promise<{
         ok: true;
@@ -87,6 +97,8 @@ interface RouteToolOptions {
     annotations?: ToolAnnotations;
     /** Extra static headers sent with the internal request. */
     headers?: Record<string, string>;
+    /** OAuth scopes needed to call this tool (when the `oauth` option is enabled). */
+    scopes?: string[];
 }
 /** HTTP route that backs a tool. `path` may use `:param` or `{param}` placeholders. */
 interface RouteSpec {
@@ -136,6 +148,12 @@ interface McpServerOptions {
     forwardHeaders?: string[];
     /** Max characters of an API response returned to the model. @default 100_000 */
     maxResponseChars?: number;
+    /**
+     * Protect the MCP endpoint with OAuth 2.1, as the MCP authorization spec
+     * describes. MCP clients (Claude, Cursor, VS Code, ...) then discover your
+     * authorization server and sign the user in by themselves.
+     */
+    oauth?: OAuthOptions;
 }
 
 declare const SUPPORTED_PROTOCOL_VERSIONS: string[];
@@ -184,6 +202,15 @@ declare class McpServer {
     private callTool;
     /** Check the Origin header (DNS rebinding protection). */
     isOriginAllowed(origin: string | undefined): boolean;
+    /**
+     * 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(): string[];
+    /** The OAuth Protected Resource Metadata document (RFC 9728). */
+    protectedResourceMetadata(): Promise<Record<string, unknown>>;
+    /** HTTP handler for the metadata paths. Public and CORS-enabled so browser-based clients can read it. */
+    handleMetadataHttp(req: Pick<McpHttpRequest, 'method'>): Promise<McpHttpResponse>;
     /**
      * Framework-neutral Streamable HTTP handler. Adapters convert their request
      * into McpHttpRequest, call this, and write the McpHttpResponse back.

package/dist/{server-fzkb-wJo.d.cts → server-BRw1E2xy.d.ts}

@@ -1,3 +1,5 @@
+import { O as OAuthOptions, A as AuthInfo } from './oauth-8RmQamGP.js';
+
 /**
  * Shared types for mcp-expose. Everything in `core` is runtime-agnostic
  * (no `node:*` imports) so it also works on Bun, Deno and edge runtimes.
@@ -48,6 +50,8 @@ interface ToolContext {
     clientIp?: string;
     /** Framework-specific raw request object (Express req, Koa ctx, Hono context...). */
     raw?: unknown;
+    /** The verified access token, when the `oauth` option is enabled. */
+    auth?: AuthInfo;
 }
 /** A fully resolved MCP tool. */
 interface McpToolDefinition {
@@ -57,6 +61,12 @@ interface McpToolDefinition {
     inputSchema: JsonSchema;
     annotations?: ToolAnnotations;
     handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
+    /**
+     * OAuth scopes the access token needs to call this tool (only checked when the
+     * `oauth` option is enabled). Missing scopes answer HTTP 403 `insufficient_scope`,
+     * so the client can ask the user for more access.
+     */
+    scopes?: string[];
     /** Optional validator run before the handler (from Standard Schema inputs). */
     validate?: (args: unknown) => Promise<{
         ok: true;
@@ -87,6 +97,8 @@ interface RouteToolOptions {
     annotations?: ToolAnnotations;
     /** Extra static headers sent with the internal request. */
     headers?: Record<string, string>;
+    /** OAuth scopes needed to call this tool (when the `oauth` option is enabled). */
+    scopes?: string[];
 }
 /** HTTP route that backs a tool. `path` may use `:param` or `{param}` placeholders. */
 interface RouteSpec {
@@ -136,6 +148,12 @@ interface McpServerOptions {
     forwardHeaders?: string[];
     /** Max characters of an API response returned to the model. @default 100_000 */
     maxResponseChars?: number;
+    /**
+     * Protect the MCP endpoint with OAuth 2.1, as the MCP authorization spec
+     * describes. MCP clients (Claude, Cursor, VS Code, ...) then discover your
+     * authorization server and sign the user in by themselves.
+     */
+    oauth?: OAuthOptions;
 }
 
 declare const SUPPORTED_PROTOCOL_VERSIONS: string[];
@@ -184,6 +202,15 @@ declare class McpServer {
     private callTool;
     /** Check the Origin header (DNS rebinding protection). */
     isOriginAllowed(origin: string | undefined): boolean;
+    /**
+     * 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(): string[];
+    /** The OAuth Protected Resource Metadata document (RFC 9728). */
+    protectedResourceMetadata(): Promise<Record<string, unknown>>;
+    /** HTTP handler for the metadata paths. Public and CORS-enabled so browser-based clients can read it. */
+    handleMetadataHttp(req: Pick<McpHttpRequest, 'method'>): Promise<McpHttpResponse>;
     /**
      * Framework-neutral Streamable HTTP handler. Adapters convert their request
      * into McpHttpRequest, call this, and write the McpHttpResponse back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-expose",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Turn the HTTP routes of your existing Node.js app (NestJS, Express, Fastify, Koa, Hono, AdonisJS) into MCP tools for AI agents, reusing your auth, validation and rate limits.",
   "keywords": [
     "mcp",
@@ -17,7 +17,10 @@
     "hono",
     "adonisjs",
     "openapi",
-    "tools"
+    "tools",
+    "oauth",
+    "oauth2",
+    "authorization"
   ],
   "homepage": "https://github.com/NITINKACHHADIYA/Node-MCP#readme",
   "bugs": {
@@ -56,6 +59,9 @@
       ],
       "adonisjs": [
         "dist/adonisjs/index.d.ts"
+      ],
+      "oauth": [
+        "dist/oauth/index.d.ts"
       ]
     }
   },
@@ -116,6 +122,14 @@
       "import": "./dist/adonisjs/index.js",
       "require": "./dist/adonisjs/index.cjs"
     },
+    "./oauth": {
+      "types": {
+        "import": "./dist/oauth/index.d.ts",
+        "require": "./dist/oauth/index.d.cts"
+      },
+      "import": "./dist/oauth/index.js",
+      "require": "./dist/oauth/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -153,6 +167,7 @@
     "express": ">=3",
     "fastify": ">=3",
     "hono": ">=2",
+    "jose": ">=5",
     "koa": ">=1"
   },
   "peerDependenciesMeta": {
@@ -177,6 +192,9 @@
     "hono": {
       "optional": true
     },
+    "jose": {
+      "optional": true
+    },
     "koa": {
       "optional": true
     }
@@ -205,6 +223,7 @@
     "fastify": "^5.12.5",
     "globals": "^17.12.0",
     "hono": "^4.13.9",
+    "jose": "^6.2.12",
     "koa": "^3.2.1",
     "prettier": "^3.9.9",
     "publint": "^0.3.24",