mcp-use/dist/src/server/oauth/utils.d.ts

Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents, Clients and Servers with support for ChatGPT Apps, Code Mode, OAuth, Notifications, Sampling, Observability and more.

/**
 * OAuth Utility Helpers
 *
 * Provides convenience functions for scope/permission checking and
 * accessing authentication information in tool callbacks and middleware.
 */
import type { Context, Next } from "hono";
import type { UserInfo } from "./providers/types.js";
/**
 * Authentication information extracted from context
 */
export interface AuthInfo {
    user: UserInfo;
    payload: Record<string, unknown>;
    accessToken: string;
    scopes: string[];
    permissions: string[];
}
/**
 * Get authentication info from context
 *
 * Works in both middleware and tool callbacks (via requestContext parameter).
 *
 * Note: With the new API, you can access auth directly via `requestContext.auth`
 * This function is kept for backward compatibility.
 *
 * @param context - Hono context (from middleware or tool requestContext)
 * @returns Authentication information
 *
 * @example
 * ```typescript
 * // New way (preferred):
 * server.tool({
 *   name: 'my-tool',
 *   cb: async (params, ctx, requestContext) => {
 *     const auth = requestContext.auth;
 *     console.log(auth.user.email);
 *     console.log(auth.scopes);
 *   }
 * });
 *
 * // Old way (still works):
 * server.tool({
 *   name: 'my-tool',
 *   cb: async (params, ctx, req) => {
 *     const auth = getAuth(req);
 *     console.log(auth.user.email);
 *   }
 * });
 * ```
 */
export declare function getAuth(context: Context): AuthInfo;
/**
 * Check if user has specific scope(s) or permission(s)
 *
 * Checks both OAuth scopes and permissions (Auth0 style).
 * If multiple scopes are provided, ALL must be present.
 * Use this inside tool callbacks to check scopes and return appropriate errors.
 *
 * @param context - Hono context (from tool requestContext parameter)
 * @param needed - Single scope/permission or array of required scopes/permissions
 * @returns true if user has all required scopes/permissions
 *
 * @example
 * ```typescript
 * // Check scope inside tool callback
 * server.tool({
 *   name: 'delete-data',
 *   cb: async (params, ctx, requestContext) => {
 *     if (!hasScope(requestContext, 'delete:data')) {
 *       return {
 *         content: [{ type: 'text', text: 'Insufficient permissions' }],
 *         isError: true
 *       };
 *     }
 *     // ... tool implementation
 *   }
 * });
 *
 * // Check multiple scopes
 * if (hasScope(requestContext, ['read:data', 'write:data'])) {
 *   // User has both read:data AND write:data
 * }
 * ```
 */
export declare function hasScope(context: Context, needed: string | string[]): boolean;
/**
 * Check if user has ANY of the provided scopes/permissions
 *
 * @param context - Hono context
 * @param needed - Array of scopes/permissions (user needs at least one)
 * @returns true if user has at least one of the required scopes/permissions
 *
 * @example
 * ```typescript
 * if (hasAnyScope(req, ['admin', 'moderator'])) {
 *   // User is either an admin OR moderator
 * }
 * ```
 */
export declare function hasAnyScope(context: Context, needed: string[]): boolean;
/**
 * Create middleware that requires specific scope(s)/permission(s)
 *
 * Returns 403 Forbidden if user doesn't have the required scope(s).
 * If multiple scopes are provided, ALL must be present.
 * Note: For tool-level scope checking, use hasScope() inside the tool callback instead.
 *
 * @param needed - Single scope/permission or array of required scopes/permissions
 * @returns Hono middleware function
 *
 * @example
 * ```typescript
 * // Use on custom routes
 * app.post('/admin/users', requireScope('admin'), async (c) => {
 *   // Only users with 'admin' scope can access
 * });
 *
 * // Require multiple scopes on a route
 * app.delete('/data/:id', requireScope(['admin', 'delete:data']), async (c) => {
 *   // User must have both scopes
 * });
 * ```
 */
export declare function requireScope(needed: string | string[]): (c: Context, next: Next) => Promise<(Response & import("hono").TypedResponse<{
    error: string;
    required: string[];
    granted_scopes: string[];
    granted_permissions: string[];
    message: string;
}, 403, "json">) | undefined>;
/**
 * Create middleware that requires ANY of the provided scopes/permissions
 *
 * Returns 403 Forbidden if user doesn't have at least one required scope.
 * Note: For tool-level scope checking, use hasAnyScope() inside the tool callback instead.
 *
 * @param needed - Array of scopes/permissions (user needs at least one)
 * @returns Hono middleware function
 *
 * @example
 * ```typescript
 * // Use on custom routes - user needs to be either admin OR moderator
 * app.post('/moderate', requireAnyScope(['admin', 'moderator']), async (c) => {
 *   // User has at least one of the required scopes
 * });
 * ```
 */
export declare function requireAnyScope(needed: string[]): (c: Context, next: Next) => Promise<(Response & import("hono").TypedResponse<{
    error: string;
    required_any: string[];
    granted_scopes: string[];
    granted_permissions: string[];
    message: string;
}, 403, "json">) | undefined>;
//# sourceMappingURL=utils.d.ts.map