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.

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` pode ser um único objeto de configuração ou um array deles.
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

// Monta o router para lidar com o Metadata de Recurso Protegido
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 (Obsoleto)

Esta abordagem é suportada para compatibilidade retroativa.

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

const app = express();
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig(
    'https://auth.logto.io/oidc',
    { type: 'oidc' }
  ),
});

// Monta o router para lidar com o Metadata legado 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 de autenticação Bearer (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 um 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 de autenticação Bearer.

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 de autenticação Bearer (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 de autenticação Bearer, 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 de Metadata do OAuth 2.0 Authorization Server (/.well-known/oauth-authorization-server) com os metadados fornecidos para a instância.

Retorna

Router

Um router que serve o endpoint de Metadata do OAuth 2.0 Authorization Server com os metadados fornecidos para a instância.

Obsoleto

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 de Metadata de Recurso Protegido OAuth 2.0 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 de Metadata de Recurso Protegido OAuth 2.0.

Lança exceção

Se chamado no modo authorization server.

Exemplo

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

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

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