OAuth: isLoopbackHost rejects *.localhost subdomains, breaking host-based local dev (InsecureTokenEndpointError)

Fechada Para iniciantes
  • Algo errado?
#2,591 4 comentários 4 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
2/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
78/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Pouca atividade
Stack de tecnologia
typescript
Domínio
authentication, security

Direção de pesquisa

Comece em packages/client localizando os pontos de entrada isLoopbackHost e assertSecureTokenEndpoint mostrados na issue e, em seguida, inspecione os testes de autenticação próximos. Verifique se os subdomínios .localhost reservados seguem a mesma exceção que os hosts de loopback listados e adicione cobertura de regressão para que o endpoint de token reproduzido não gere mais InsecureTokenEndpointError.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

spec-2026-07-28 v2
What happened?

Summary

assertSecureTokenEndpoint exempts only the exact hostnames localhost, 127.0.0.1, ::1 and [::1]. Subdomains under the reserved .localhost TLD — e.g. http://tenant.example.localhost:3300 — are treated as public non-TLS endpoints and rejected, even though every layer below (RFC 6761, the browser's secure-context rules, the OS resolver) already treats them as loopback.

This makes SEP-2207 unusable for anyone whose local server is host-based multi-tenant, which is a common setup: the tenant is selected from the Host header, and session cookies are scoped to that host, so http://localhost:PORT is not an equivalent substitute.

Current behavior

Refusing to send credentials to non-https token endpoint
'http://tenant.example.localhost:3300/api/oauth/token'.
OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

packages/client (as shipped in dist/index.mjs):

/** Loopback hosts exempt from the in-transit `https:` requirement (RFC 8252 §7.3). */
function isLoopbackHost(hostname) {
  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
}

function assertSecureTokenEndpoint(tokenEndpoint) {
  const url = new URL(String(tokenEndpoint));
  if (url.protocol !== "https:" && !isLoopbackHost(url.hostname)) throw new InsecureTokenEndpointError(url.href);
  return url;
}

In MCP Inspector this surfaces as a "Re-authentication required" banner with a Re-authenticate button that cannot possibly work — by design, since InsecureTokenEndpointError deliberately does not extend OAuthError and is rethrown rather than retried. The UI presents a config error as a retryable auth error.

What did you expect?

Why *.localhost should be exempt

RFC 6761 §6.3 reserves localhost. and any name ending in .localhost., with the same "resolves to the loopback interface" semantics. foo.localhost is loopback by specification, not by convention.
W3C Secure Contexts classifies an origin as potentially trustworthy when its host is localhost or ends in .localhost. Browsers already grant http://tenant.example.localhost:3300 secure-context privileges — the SDK is stricter than the browser it runs in.
Resolvers agree: macOS mDNSResponder, systemd-resolved, and Chrome/Firefox all send *.localhost to 127.0.0.1.
Not publicly registrable: .localhost is reserved, so unlike a generic suffix check this cannot be spoofed by acquiring a real domain. The residual risk (a hostile local resolver pointing evil.localhost elsewhere) applies equally to bare localhost, which is already exempt.
Also worth noting: SDK 1.x had no equivalent assertion, so setups like this worked before. The assertion itself is a clear improvement — the issue is only that the exemption list is narrower than the loopback definition it cites.

Proposed fix

function isLoopbackHost(hostname: string): boolean {
  return (
    hostname === "localhost" ||
    hostname.endsWith(".localhost") ||
    hostname === "127.0.0.1" ||
    hostname === "[::1]" ||
    hostname === "::1"
  );
}

Happy to open a PR (with tests) if the direction is acceptable.

Code to reproduce
Serve an MCP endpoint over plain HTTP on a *.localhost host, e.g. http://tenant.example.localhost:3300/api/mcp.
Advertise OAuth metadata derived from the request Host, so token_endpoint is http://tenant.example.localhost:3300/api/oauth/token.
Connect with Inspector 2.0 and start the OAuth flow → InsecureTokenEndpointError before any token request is sent.
Switching the same server to http://localhost:3300 passes the check, confirming the hostname comparison is the only difference.
SDK version

@modelcontextprotocol/[email protected]（via @modelcontextprotocol/[email protected]）

Area

Auth

Linguagem predominante
TypeScript
Estrelas
13.7k
Forks
2.4k
Merge médio
2d 7h
PRs com merge (30d)
26

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de modelcontextprotocol/typescript-sdk

Todas as issues de modelcontextprotocol/typescript-sdk

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.