@ttoss/http-server-mcp 0.15.0 → 0.16.0

package/README.md

@@ -129,7 +129,7 @@ const data = await apiCall('GET', 'https://partner.api.com/data', {
 
 ## Authentication
 
-`createMcpRouter` supports OAuth 2.0 Bearer token authentication via the `auth` option. Every incoming MCP request must include a valid `Authorization: Bearer <token>` header — invalid or missing tokens receive a `401 Unauthorized` response.
+`createMcpRouter` supports OAuth 2.0 Bearer token authentication via the `auth` option. Incoming MCP requests must include a valid `Authorization: Bearer <token>` header — invalid or missing tokens receive a `401 Unauthorized` response. The MCP lifecycle methods `initialize` and `tools/list` are exempt by default so clients can discover the server before authenticating (see [Public methods and discovery](#public-methods-and-discovery)).
 
 ```mermaid
 sequenceDiagram
@@ -315,6 +315,31 @@ app.use(createMcpRouter(mcpServer).routes());
 
 The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients bootstrap OAuth discovery after their first unauthorized request.
 
+### Public methods and discovery
+
+The two behaviors the [MCP authorization spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) requires for client bootstrapping are built into the `auth` option, so you no longer need the hand-rolled middleware shown above:
+
+- **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize', 'tools/list']` so clients can discover the server before authenticating. Pass `[]` to require a token for every method, or a custom list to change the exempt set.
+- **`resourceMetadataUrl`** — when set, a `401` responds with `WWW-Authenticate: Bearer resource_metadata="<resourceMetadataUrl>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. When omitted, the header falls back to `Bearer`.
+
+```typescript
+createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: { userPoolId: '...', clientId: '...' },
+    // Serve the metadata document (unauthenticated)...
+    resourceServerUrl: 'https://mcp.example.com',
+    authorizationServerUrl:
+      'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx',
+    // ...and point 401s at it for auto-discovery.
+    resourceMetadataUrl:
+      'https://mcp.example.com/.well-known/oauth-protected-resource',
+    // publicMethods defaults to ['initialize', 'tools/list'].
+  },
+});
+```
+
+Both fields are optional. Omitting `resourceMetadataUrl` keeps the bare `Bearer` header, and the `publicMethods` default matches what MCP clients expect for discovery.
+
 ## OAuth 2.1 Authorization Server
 
 The `auth` option above covers the **resource-server** half of MCP authorization — it verifies tokens issued by an external authorization server (Cognito, Auth0, …). When you want your own first-party server to _issue_ the tokens, `createMcpAuthServer` provides the **authorization-server** half: the `/authorize`, `/token`, `/register`, and discovery endpoints an MCP client (Claude, Cursor, VS Code) auto-discovers and runs the full OAuth 2.1 flow against.
@@ -403,6 +428,8 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
     - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
     - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable `/.well-known/oauth-protected-resource`
+    - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'tools/list']`)
+    - `auth.resourceMetadataUrl` — Emit RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` on 401
 
 **Returns:** `Router` — Koa router instance
 

package/dist/index.cjs

@@ -4,12 +4,82 @@ Object.defineProperty(exports, Symbol.toStringTag, {
 });
 let node_async_hooks = require("node:async_hooks");
 let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
-let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
 let _ttoss_http_server = require("@ttoss/http-server");
 let zod = require("zod");
+let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
 let node_crypto = require("node:crypto");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 
+//#region src/auth.ts
+/** MCP lifecycle/discovery methods reachable before a client authenticates. */
+var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* Builds the token verifier from the auth options, preferring an explicit
+* `verifyToken` and otherwise creating a `CognitoJwtVerifier`.
+*/
+var buildTokenVerifier = auth => {
+  if (auth.cognitoUserPool) {
+    const v = _ttoss_auth_core_amazon_cognito.CognitoJwtVerifier.create({
+      tokenUse: "access",
+      ...auth.cognitoUserPool
+    });
+    return t => {
+      return v.verify(t);
+    };
+  }
+  if (auth.verifyToken) return auth.verifyToken;
+  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+};
+/** Returns true when the identity carries every required scope (or none are required). */
+var hasRequiredScopes = (requiredScopes, identity) => {
+  if (!requiredScopes?.length) return true;
+  const tokenScopes = (identity?.scope ?? "").split(" ");
+  return requiredScopes.every(s => {
+    return tokenScopes.includes(s);
+  });
+};
+/**
+* Registers the token-verification middleware (with public-method bypass and
+* RFC 9728 discovery) and, when configured, the OAuth protected-resource
+* metadata endpoint on the given router.
+*/
+var registerAuthRoutes = (router, path, auth, tokenVerifier) => {
+  const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
+  const unauthorizedHeader = auth.resourceMetadataUrl ? `Bearer resource_metadata="${auth.resourceMetadataUrl}"` : "Bearer";
+  router.use(path, async (ctx, next) => {
+    const method = ctx.request.body?.method;
+    if (publicMethods.has(method ?? "")) {
+      await next();
+      return;
+    }
+    const authHeader = ctx.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    let identity;
+    try {
+      identity = await tokenVerifier(token);
+    } catch {
+      ctx.status = 401;
+      ctx.set("WWW-Authenticate", unauthorizedHeader);
+      ctx.body = "Unauthorized";
+      return;
+    }
+    if (!hasRequiredScopes(auth.requiredScopes, identity)) {
+      ctx.status = 403;
+      ctx.body = "Forbidden";
+      return;
+    }
+    ctx.state.identity = identity;
+    await next();
+  });
+  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource: auth.resourceServerUrl,
+      authorization_servers: [auth.authorizationServerUrl]
+    };
+  });
+};
+
+//#endregion
 //#region src/authServerHandlers.ts
 var base64UrlEncode = buffer => {
   return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -496,52 +566,6 @@ var checkScopes = required => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
 };
-var buildTokenVerifier = auth => {
-  if (auth.cognitoUserPool) {
-    const v = _ttoss_auth_core_amazon_cognito.CognitoJwtVerifier.create({
-      tokenUse: "access",
-      ...auth.cognitoUserPool
-    });
-    return t => {
-      return v.verify(t);
-    };
-  }
-  if (auth.verifyToken) return auth.verifyToken;
-  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
-};
-var registerAuthRoutes = (router, path, auth, tokenVerifier) => {
-  router.use(path, async (ctx, next) => {
-    const authHeader = ctx.headers.authorization;
-    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
-    let identity;
-    try {
-      identity = await tokenVerifier(token);
-    } catch {
-      ctx.status = 401;
-      ctx.set("WWW-Authenticate", "Bearer");
-      ctx.body = "Unauthorized";
-      return;
-    }
-    if (auth.requiredScopes?.length) {
-      const tokenScopes = (identity?.scope ?? "").split(" ");
-      if (auth.requiredScopes.filter(s => {
-        return !tokenScopes.includes(s);
-      }).length > 0) {
-        ctx.status = 403;
-        ctx.body = "Forbidden";
-        return;
-      }
-    }
-    ctx.state.identity = identity;
-    await next();
-  });
-  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
-    ctx.body = {
-      resource: auth.resourceServerUrl,
-      authorization_servers: [auth.authorizationServerUrl]
-    };
-  });
-};
 /**
 * Creates a Koa router configured to handle MCP protocol requests
 *

package/dist/index.d.cts

@@ -665,6 +665,77 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
+//#region src/auth.d.ts
+/** Amazon Cognito user pool configuration for JWT verification. */
+interface CognitoUserPoolConfig {
+  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
+  userPoolId: string;
+  /**
+   * Which token type to verify.
+   * @default 'access'
+   */
+  tokenUse?: 'access' | 'id';
+  /** The app client ID registered in the User Pool. */
+  clientId: string;
+}
+/**
+ * Authentication options for the MCP router.
+ *
+ * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
+ * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
+ */
+interface McpAuthOptions {
+  /**
+   * Amazon Cognito user pool config. When provided, the router creates a
+   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
+   */
+  cognitoUserPool?: CognitoUserPoolConfig;
+  /**
+   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
+   * Receives the raw Bearer token string. Should resolve with the verified
+   * payload or reject/throw on failure.
+   */
+  verifyToken?: (token: string) => Promise<unknown>;
+  /**
+   * Router-level scope guard. All listed scopes must be present on the token
+   * for any MCP request to be allowed. Returns 403 if any scope is missing.
+   *
+   * Cognito encodes scopes as a space-separated string in `payload.scope`.
+   *
+   * @example ['mcp:access']
+   */
+  requiredScopes?: string[];
+  /**
+   * URL of this MCP server, used in the OAuth Protected Resource Metadata
+   * response (`/.well-known/oauth-protected-resource`). Both this field and
+   * `authorizationServerUrl` must be provided to enable the endpoint.
+   */
+  resourceServerUrl?: string;
+  /**
+   * URL of the OAuth Authorization Server that issues tokens for this resource.
+   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
+   * (RFC 9728) when combined with `resourceServerUrl`.
+   */
+  authorizationServerUrl?: string;
+  /**
+   * JSON-RPC methods (read from `body.method`) that bypass token verification,
+   * so MCP clients can discover the server before authenticating. Set to an
+   * empty array to require a token for every method.
+   *
+   * @default ['initialize', 'tools/list']
+   */
+  publicMethods?: string[];
+  /**
+   * When set, a `401` from verification responds with
+   * `WWW-Authenticate: Bearer resource_metadata="<resourceMetadataUrl>"`
+   * (RFC 9728) so MCP clients can auto-discover the authorization server.
+   * When omitted, the header falls back to a bare `Bearer`.
+   *
+   * @example 'https://mcp.example.com/.well-known/oauth-protected-resource'
+   */
+  resourceMetadataUrl?: string;
+}
+//#endregion
 //#region src/authServerTypes.d.ts
 type Context$1 = Application.Context;
 /**
@@ -1004,58 +1075,6 @@ declare const getIdentity: () => unknown;
  * ```
  */
 declare const checkScopes: (required: string[]) => void;
-/** Amazon Cognito user pool configuration for JWT verification. */
-interface CognitoUserPoolConfig {
-  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
-  userPoolId: string;
-  /**
-   * Which token type to verify.
-   * @default 'access'
-   */
-  tokenUse?: 'access' | 'id';
-  /** The app client ID registered in the User Pool. */
-  clientId: string;
-}
-/**
- * Authentication options for the MCP router.
- *
- * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
- * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
- */
-interface McpAuthOptions {
-  /**
-   * Amazon Cognito user pool config. When provided, the router creates a
-   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
-   */
-  cognitoUserPool?: CognitoUserPoolConfig;
-  /**
-   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
-   * Receives the raw Bearer token string. Should resolve with the verified
-   * payload or reject/throw on failure.
-   */
-  verifyToken?: (token: string) => Promise<unknown>;
-  /**
-   * Router-level scope guard. All listed scopes must be present on the token
-   * for any MCP request to be allowed. Returns 403 if any scope is missing.
-   *
-   * Cognito encodes scopes as a space-separated string in `payload.scope`.
-   *
-   * @example ['mcp:access']
-   */
-  requiredScopes?: string[];
-  /**
-   * URL of this MCP server, used in the OAuth Protected Resource Metadata
-   * response (`/.well-known/oauth-protected-resource`). Both this field and
-   * `authorizationServerUrl` must be provided to enable the endpoint.
-   */
-  resourceServerUrl?: string;
-  /**
-   * URL of the OAuth Authorization Server that issues tokens for this resource.
-   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
-   * (RFC 9728) when combined with `resourceServerUrl`.
-   */
-  authorizationServerUrl?: string;
-}
 /**
  * Options for configuring the MCP router
  */
@@ -1108,10 +1127,13 @@ interface McpRouterOptions {
   /**
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
-   * When set, every incoming MCP request must include a valid Bearer token in
-   * the `Authorization` header. Invalid or missing tokens receive a `401`
-   * response with `WWW-Authenticate: Bearer`. Tokens that fail a
-   * `requiredScopes` check receive `403`.
+   * When set, incoming MCP requests must include a valid Bearer token in the
+   * `Authorization` header — except for `publicMethods` (by default
+   * `initialize` and `tools/list`), which bypass verification so clients can
+   * discover the server before authenticating. Invalid or missing tokens
+   * receive a `401` response with `WWW-Authenticate: Bearer` (or
+   * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
+   * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.
    *
    * The verified token payload is accessible inside tool handlers via
    * {@link getIdentity}. Fine-grained per-tool scope checks can be done with
@@ -1312,4 +1334,4 @@ declare const createProtectedResourceMetadataMiddleware: (args: {
   authorizationServers: string[];
 }) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, type CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, type McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -665,6 +665,77 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
+//#region src/auth.d.ts
+/** Amazon Cognito user pool configuration for JWT verification. */
+interface CognitoUserPoolConfig {
+  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
+  userPoolId: string;
+  /**
+   * Which token type to verify.
+   * @default 'access'
+   */
+  tokenUse?: 'access' | 'id';
+  /** The app client ID registered in the User Pool. */
+  clientId: string;
+}
+/**
+ * Authentication options for the MCP router.
+ *
+ * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
+ * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
+ */
+interface McpAuthOptions {
+  /**
+   * Amazon Cognito user pool config. When provided, the router creates a
+   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
+   */
+  cognitoUserPool?: CognitoUserPoolConfig;
+  /**
+   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
+   * Receives the raw Bearer token string. Should resolve with the verified
+   * payload or reject/throw on failure.
+   */
+  verifyToken?: (token: string) => Promise<unknown>;
+  /**
+   * Router-level scope guard. All listed scopes must be present on the token
+   * for any MCP request to be allowed. Returns 403 if any scope is missing.
+   *
+   * Cognito encodes scopes as a space-separated string in `payload.scope`.
+   *
+   * @example ['mcp:access']
+   */
+  requiredScopes?: string[];
+  /**
+   * URL of this MCP server, used in the OAuth Protected Resource Metadata
+   * response (`/.well-known/oauth-protected-resource`). Both this field and
+   * `authorizationServerUrl` must be provided to enable the endpoint.
+   */
+  resourceServerUrl?: string;
+  /**
+   * URL of the OAuth Authorization Server that issues tokens for this resource.
+   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
+   * (RFC 9728) when combined with `resourceServerUrl`.
+   */
+  authorizationServerUrl?: string;
+  /**
+   * JSON-RPC methods (read from `body.method`) that bypass token verification,
+   * so MCP clients can discover the server before authenticating. Set to an
+   * empty array to require a token for every method.
+   *
+   * @default ['initialize', 'tools/list']
+   */
+  publicMethods?: string[];
+  /**
+   * When set, a `401` from verification responds with
+   * `WWW-Authenticate: Bearer resource_metadata="<resourceMetadataUrl>"`
+   * (RFC 9728) so MCP clients can auto-discover the authorization server.
+   * When omitted, the header falls back to a bare `Bearer`.
+   *
+   * @example 'https://mcp.example.com/.well-known/oauth-protected-resource'
+   */
+  resourceMetadataUrl?: string;
+}
+//#endregion
 //#region src/authServerTypes.d.ts
 type Context$1 = Application.Context;
 /**
@@ -1004,58 +1075,6 @@ declare const getIdentity: () => unknown;
  * ```
  */
 declare const checkScopes: (required: string[]) => void;
-/** Amazon Cognito user pool configuration for JWT verification. */
-interface CognitoUserPoolConfig {
-  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
-  userPoolId: string;
-  /**
-   * Which token type to verify.
-   * @default 'access'
-   */
-  tokenUse?: 'access' | 'id';
-  /** The app client ID registered in the User Pool. */
-  clientId: string;
-}
-/**
- * Authentication options for the MCP router.
- *
- * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
- * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
- */
-interface McpAuthOptions {
-  /**
-   * Amazon Cognito user pool config. When provided, the router creates a
-   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
-   */
-  cognitoUserPool?: CognitoUserPoolConfig;
-  /**
-   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
-   * Receives the raw Bearer token string. Should resolve with the verified
-   * payload or reject/throw on failure.
-   */
-  verifyToken?: (token: string) => Promise<unknown>;
-  /**
-   * Router-level scope guard. All listed scopes must be present on the token
-   * for any MCP request to be allowed. Returns 403 if any scope is missing.
-   *
-   * Cognito encodes scopes as a space-separated string in `payload.scope`.
-   *
-   * @example ['mcp:access']
-   */
-  requiredScopes?: string[];
-  /**
-   * URL of this MCP server, used in the OAuth Protected Resource Metadata
-   * response (`/.well-known/oauth-protected-resource`). Both this field and
-   * `authorizationServerUrl` must be provided to enable the endpoint.
-   */
-  resourceServerUrl?: string;
-  /**
-   * URL of the OAuth Authorization Server that issues tokens for this resource.
-   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
-   * (RFC 9728) when combined with `resourceServerUrl`.
-   */
-  authorizationServerUrl?: string;
-}
 /**
  * Options for configuring the MCP router
  */
@@ -1108,10 +1127,13 @@ interface McpRouterOptions {
   /**
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
-   * When set, every incoming MCP request must include a valid Bearer token in
-   * the `Authorization` header. Invalid or missing tokens receive a `401`
-   * response with `WWW-Authenticate: Bearer`. Tokens that fail a
-   * `requiredScopes` check receive `403`.
+   * When set, incoming MCP requests must include a valid Bearer token in the
+   * `Authorization` header — except for `publicMethods` (by default
+   * `initialize` and `tools/list`), which bypass verification so clients can
+   * discover the server before authenticating. Invalid or missing tokens
+   * receive a `401` response with `WWW-Authenticate: Bearer` (or
+   * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
+   * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.
    *
    * The verified token payload is accessible inside tool handlers via
    * {@link getIdentity}. Fine-grained per-tool scope checks can be done with
@@ -1312,4 +1334,4 @@ declare const createProtectedResourceMetadataMiddleware: (args: {
   authorizationServers: string[];
 }) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, type CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, type McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/dist/index.mjs

@@ -1,12 +1,82 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { z, z as z$1 } from "zod";
+import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { createHash, randomBytes } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+//#region src/auth.ts
+/** MCP lifecycle/discovery methods reachable before a client authenticates. */
+var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* Builds the token verifier from the auth options, preferring an explicit
+* `verifyToken` and otherwise creating a `CognitoJwtVerifier`.
+*/
+var buildTokenVerifier = auth => {
+  if (auth.cognitoUserPool) {
+    const v = CognitoJwtVerifier.create({
+      tokenUse: "access",
+      ...auth.cognitoUserPool
+    });
+    return t => {
+      return v.verify(t);
+    };
+  }
+  if (auth.verifyToken) return auth.verifyToken;
+  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+};
+/** Returns true when the identity carries every required scope (or none are required). */
+var hasRequiredScopes = (requiredScopes, identity) => {
+  if (!requiredScopes?.length) return true;
+  const tokenScopes = (identity?.scope ?? "").split(" ");
+  return requiredScopes.every(s => {
+    return tokenScopes.includes(s);
+  });
+};
+/**
+* Registers the token-verification middleware (with public-method bypass and
+* RFC 9728 discovery) and, when configured, the OAuth protected-resource
+* metadata endpoint on the given router.
+*/
+var registerAuthRoutes = (router, path, auth, tokenVerifier) => {
+  const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
+  const unauthorizedHeader = auth.resourceMetadataUrl ? `Bearer resource_metadata="${auth.resourceMetadataUrl}"` : "Bearer";
+  router.use(path, async (ctx, next) => {
+    const method = ctx.request.body?.method;
+    if (publicMethods.has(method ?? "")) {
+      await next();
+      return;
+    }
+    const authHeader = ctx.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    let identity;
+    try {
+      identity = await tokenVerifier(token);
+    } catch {
+      ctx.status = 401;
+      ctx.set("WWW-Authenticate", unauthorizedHeader);
+      ctx.body = "Unauthorized";
+      return;
+    }
+    if (!hasRequiredScopes(auth.requiredScopes, identity)) {
+      ctx.status = 403;
+      ctx.body = "Forbidden";
+      return;
+    }
+    ctx.state.identity = identity;
+    await next();
+  });
+  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource: auth.resourceServerUrl,
+      authorization_servers: [auth.authorizationServerUrl]
+    };
+  });
+};
+
+//#endregion
 //#region src/authServerHandlers.ts
 var base64UrlEncode = buffer => {
   return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -493,52 +563,6 @@ var checkScopes = required => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
 };
-var buildTokenVerifier = auth => {
-  if (auth.cognitoUserPool) {
-    const v = CognitoJwtVerifier.create({
-      tokenUse: "access",
-      ...auth.cognitoUserPool
-    });
-    return t => {
-      return v.verify(t);
-    };
-  }
-  if (auth.verifyToken) return auth.verifyToken;
-  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
-};
-var registerAuthRoutes = (router, path, auth, tokenVerifier) => {
-  router.use(path, async (ctx, next) => {
-    const authHeader = ctx.headers.authorization;
-    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
-    let identity;
-    try {
-      identity = await tokenVerifier(token);
-    } catch {
-      ctx.status = 401;
-      ctx.set("WWW-Authenticate", "Bearer");
-      ctx.body = "Unauthorized";
-      return;
-    }
-    if (auth.requiredScopes?.length) {
-      const tokenScopes = (identity?.scope ?? "").split(" ");
-      if (auth.requiredScopes.filter(s => {
-        return !tokenScopes.includes(s);
-      }).length > 0) {
-        ctx.status = 403;
-        ctx.body = "Forbidden";
-        return;
-      }
-    }
-    ctx.state.identity = identity;
-    await next();
-  });
-  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
-    ctx.body = {
-      resource: auth.resourceServerUrl,
-      authorization_servers: [auth.authorizationServerUrl]
-    };
-  });
-};
 /**
 * Creates a Koa router configured to handle MCP protocol requests
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",