Pular para o conteúdo principal

Classe: MCPAuth

A classe principal da biblioteca mcp-auth. Atua como uma fábrica e registro para criar políticas de autenticação para seus recursos protegidos.

Ela é inicializada com as configurações do seu servidor e fornece um método bearerAuth para gerar middleware Express para autenticação baseada em token.

Exemplo​

Uso no modo resource server​

Esta é a abordagem recomendada para novas aplicações.

Use isto quando quiser que os metadados sejam buscados sob demanda. Isso é especialmente útil para runtimes edge como Cloudflare Workers, onde não é permitido fetch assíncrono no topo do arquivo.

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        // Basta passar issuer e type - os metadados serão buscados na primeira requisição
        authorizationServers: [{ issuer: 'https://auth.logto.io/oidc', type: 'oidc' }],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

Opção 2: Configuração resolvida (metadados pré-buscados)​

Use isto quando quiser buscar e validar os metadados no momento da inicialização.

import express from 'express';
import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

Usando o middleware​

// Monta o router para lidar com Protected Resource Metadata
app.use(mcpAuth.protectedResourceMetadataRouter());

// Protege um endpoint de API para o recurso configurado
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier, // Especifique a qual recurso este endpoint pertence
    audience: resourceIdentifier, // Opcionalmente, valide a reivindicação 'aud'
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

Uso legado no modo authorization server (Descontinuado)​

Esta abordagem é suportada para compatibilidade retroativa.

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  // Configuração de descoberta - metadados buscados sob demanda
  server: { issuer: 'https://auth.logto.io/oidc', type: 'oidc' },
});

// Monta o router para lidar com metadados legados do Authorization Server
app.use(mcpAuth.delegatedRouter());

// Protege um endpoint usando a política padrão
app.get(
  '/mcp',
  mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    // Lide com a requisição MCP aqui
  },
);

Construtores​

Construtor​

new MCPAuth(config: MCPAuthConfig): MCPAuth;

Cria uma instância de MCPAuth. Valida toda a configuração antecipadamente para falhar rapidamente em caso de erros.

Parâmetros​

config​

MCPAuthConfig

A configuração de autenticação.

Retorna​

MCPAuth

Propriedades​

config​

readonly config: MCPAuthConfig;

A configuração de autenticação.

Métodos​

bearerAuth()​

Assinatura de chamada​

bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">): RequestHandler;

Cria um handler Bearer auth (middleware Express) que verifica o token de acesso no cabeçalho Authorization da requisição.

Parâmetros​
verifyAccessToken​

VerifyAccessTokenFunction

Uma função que verifica o token de acesso. Deve aceitar o token de acesso como uma string e retornar uma promise (ou valor) que resolve para o resultado da verificação.

Veja também

VerifyAccessTokenFunction para a definição do tipo da função verifyAccessToken.

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">

Configuração opcional para o handler Bearer auth.

Veja também

BearerAuthConfig para as opções de configuração disponíveis (excluindo verifyAccessToken e issuer).

Retorna​

RequestHandler

Uma função middleware Express que verifica o token de acesso e adiciona o resultado da verificação ao objeto da requisição (req.auth).

Veja também​

handleBearerAuth para detalhes da implementação e os tipos estendidos do objeto req.auth (AuthInfo).

Assinatura de chamada​

bearerAuth(mode: "jwt", config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig): RequestHandler;

Cria um handler Bearer auth (middleware Express) que verifica o token de acesso no cabeçalho Authorization da requisição usando um modo de verificação predefinido.

No modo 'jwt', o handler criará uma função de verificação JWT usando o JWK Set do JWKS URI do servidor de autorização.

Parâmetros​
mode​

"jwt"

O modo de verificação para o token de acesso. Atualmente, apenas 'jwt' é suportado.

Veja também

VerifyAccessTokenMode para os modos disponíveis.

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig

Configuração opcional para o handler Bearer auth, incluindo opções de verificação JWT e opções remotas de JWK set.

Veja também

  • VerifyJwtConfig para as opções de configuração disponíveis para verificação JWT.
  • BearerAuthConfig para as opções de configuração disponíveis (excluindo verifyAccessToken e issuer).
Retorna​

RequestHandler

Uma função middleware Express que verifica o token de acesso e adiciona o resultado da verificação ao objeto da requisição (req.auth).

Veja também​

handleBearerAuth para detalhes da implementação e os tipos estendidos do objeto req.auth (AuthInfo).

Lança exceção​

se o JWKS URI não for fornecido nos metadados do servidor ao usar o modo 'jwt'.

delegatedRouter()​

delegatedRouter(): Router;

Cria um router delegado para servir o endpoint legado OAuth 2.0 Authorization Server Metadata (/.well-known/oauth-authorization-server) com os metadados fornecidos à instância.

Retorna​

Router

Um router que serve o endpoint OAuth 2.0 Authorization Server Metadata com os metadados fornecidos à instância.

Descontinuado​

Use protectedResourceMetadataRouter em vez disso.

Exemplo​

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth: MCPAuth; // Suponha que está inicializado
app.use(mcpAuth.delegatedRouter());

Lança exceção​

Se chamado no modo resource server.

protectedResourceMetadataRouter()​

protectedResourceMetadataRouter(): Router;

Cria um router que serve o endpoint OAuth 2.0 Protected Resource Metadata para todos os recursos configurados.

Este router cria automaticamente os endpoints .well-known corretos para cada identificador de recurso fornecido na sua configuração.

Retorna​

Router

Um router que serve o endpoint OAuth 2.0 Protected Resource Metadata.

Lança exceção​

Se chamado no modo authorization server.

Exemplo​

import express from 'express';
import { MCPAuth } from 'mcp-auth';

// Supondo que mcpAuth foi inicializado com uma ou mais configs `protectedResources`
const mcpAuth: MCPAuth;
const app = express();

// Isso servirá metadados em `/.well-known/oauth-protected-resource/...`
// baseado nos seus identificadores de recurso.
app.use(mcpAuth.protectedResourceMetadataRouter());