Segurança e operações do NextPDF Connect

Visão geral

O NextPDF Connect autentica os transportes em rede usando um token bearer de chave de API. Ele trata o transporte local do Model Context Protocol (MCP) como um subprocesso confiável e protege cada ferramenta de alto risco com confirmação humana explícita. Esta página explica o modelo de autenticação, a segurança do transporte e o modelo de ameaças.

Instalação

composer require nextpdf/server

Visão conceitual

O servidor define três fronteiras de confiança, uma para cada transporte.

O transporte stdio do MCP é um subprocesso iniciado por um cliente local. Ele lê JSON-RPC na entrada padrão e escreve respostas na saída padrão. Esse transporte não tem listener de rede nem chave de API. Ele herda a confiança da fronteira de processo do sistema operacional, que é o modelo de confiança definido pela especificação do MCP para o stdio. Os logs são gravados na saída de erro padrão, de modo que nunca corrompem o fluxo do protocolo.

O transporte REST e o transporte gRPC operam em rede. Ambos exigem um token bearer de chave de API em cada requisição, exceto nas sondagens de integridade não autenticadas. O mesmo armazenamento de chaves, formato de chave e validação em tempo constante são usados pelos dois transportes. O transporte gRPC lê o token nos metadados da chamada; o REST o lê no cabeçalho Authorization.

A autenticação mal implementada é a falha que o OWASP Application Programming Interface (API) Security Top 10 identifica como API2:2023 Broken Authentication. Falhas nessa área comprometem a capacidade da API de identificar quem faz a chamada e, portanto, comprometem a segurança da API como um todo (OWASP API Security Top 10, API2:2023). Tokens fracos ou previsíveis também são apontados como um antipadrão de autenticação quebrada (mesma fonte, lista de vulnerabilidades). O design descrito a seguir trata esses dois riscos.

Superfície da API

Formato e validação da chave de API

Uma chave tem o formato npk_live_{kid}_{secret}. O kid é um identificador de oito caracteres usado para busca de registro em O(1), e o segredo carrega a entropia. O armazenamento nunca guarda a chave em texto puro. Ele armazena um digest SHA-256 do material completo da chave. Em cada requisição, o servidor calcula o hash do token apresentado e o compara com o digest armazenado usando uma comparação em tempo constante (hash_equals), de modo que uma chave incorreta não revele nada pelo tempo de resposta. Uma chave desativada ou expirada é rejeitada após a verificação de hash, não antes.

Os validadores REST e gRPC compartilham essa lógica. O middleware REST lê Authorization: Bearer npk_live_…. O autenticador gRPC lê o mesmo token bearer nos metadados de chamada authorization do gRPC, que são transportados como cabeçalhos HTTP/2. A chamada falha com o status UNAUTHENTICATED do gRPC.

Ambos os transportes também aplicam um controle anti-automação ao tráfego pré-autenticação: tentativas excessivas de uma única identidade de cliente são limitadas por taxa e rejeitadas — 429 Too Many Requests no REST e, no gRPC, o status RESOURCE_EXHAUSTED do gRPC. Esse controle fica ativo por padrão, de modo que protege uma implantação que não configurou separadamente um armazenamento de limite de taxa. Os clientes devem fazer backoff em vez de tentar novamente de imediato.

Respostas não autorizadas

Uma requisição REST com uma chave ausente, malformada, desativada ou expirada recebe 401 Unauthorized com um corpo no formato problem-details e um cabeçalho de resposta WWW-Authenticate: Bearer. Isso corresponde ao requisito do HTTP de que uma resposta 401 DEVE conter um campo de cabeçalho WWW-Authenticate com pelo menos um desafio (RFC 9110 §11.6.1). Esse requisito decorre da regra de que uma requisição com credenciais omitidas ou inválidas deve receber 401 e um desafio WWW-Authenticate (RFC 9110 §11.6).

Direitos da chave

Cada registro de chave carrega um nível máximo de produto. O pipeline REST anexa à requisição a identidade e o nível do cliente autenticado, de modo que a autorização posterior possa impor limites de capacidade e de payload por nível. Uma chave de nível core não pode executar uma operação Pro ou Enterprise, mesmo quando esses pacotes estão instalados.

Casos extremos e armadilhas

O transporte MCP não tem chave de API. Isso é intencional e correto para um subprocesso local. Não exponha o servidor MCP por meio de uma camada intermediária de rede. Se um agente em rede precisar das ferramentas, posicione-o diante do transporte REST ou gRPC, que fazem autenticação.
As sondagens de integridade são anônimas de propósito. /healthz e /readyz ignoram a autenticação para que orquestradores possam sondar liveness e readiness sem uma credencial. Elas retornam apenas um status e não expõem nenhum dado de ferramenta nem dado de documento.
Um token de confirmação é de uso único e de vida curta. O gate human-in-the-loop emite um token vinculado ao nome da ferramenta e com tempo de vida de 300 segundos. O token é consumido no primeiro uso. Ele não é uma credencial de autenticação e não substitui uma chave de API.

Desempenho

A autenticação faz um único hash e uma comparação em tempo constante por requisição. Esse custo é desprezível em comparação com o custo de uma renderização. O armazenamento de chaves com recarga a quente relê o arquivo de chaves quando ele muda, de modo que a rotação não exige reinicialização nem adiciona custo por requisição.

Notas de segurança

O gate human-in-the-loop

Cada ferramenta declara um nível de risco. As ferramentas no nível mais alto, ApprovalRequired, não são executadas na primeira chamada. O gate de confirmação retorna um desafio que contém um token de uso único. O agente deve mostrar o desafio a um humano e invocar novamente a ferramenta com o token. Esse controle é deliberadamente aplicado no ponto em que a ação automatizada introduz risco. É o ponto que a IEC 31010 identifica para controlar o risco introduzido por ação humana (aqui, do agente), no ponto de introdução ou perto dele (IEC 31010:2019). A configuração não pode enfraquecer o gate: uma substituição de configuração só pode aumentar o risco de uma ferramenta, nunca rebaixar uma ferramenta ApprovalRequired. Consulte /connect/hitl-risk-tiers/.

Configuração de segurança de transporte

Os transportes em rede não terminam o Transport Layer Security (TLS) por si mesmos; o TLS é responsabilidade da implantação. A implantação de referência combinada executa o transporte gRPC com TLS mútuo, com a chave, o certificado e a CA do cliente fornecidos como segredos da implantação. Sob TLS mútuo, o servidor apresenta um certificado e exige e verifica um certificado de cliente. Execute o transporte REST atrás de um terminador TLS (proxy reverso ou service mesh) e nunca exponha um listener em texto puro em uma rede não confiável. Os detalhes da configuração estão em /connect/deployment/. Esta é uma declaração de postura, não uma garantia pronta para uso, e o transporte seguro requer uma configuração de implantação correta.

Contenção do caminho de saída

As ferramentas que escrevem arquivos resolvem o caminho solicitado em relação ao diretório base configurado, normalizam-no para a forma canônica e rejeitam bytes nulos, wrappers de protocolo e travessia ... Elas recusam qualquer caminho que resolva para fora da base. Mantenha o diretório base em um volume dedicado com permissões de menor privilégio no sistema de arquivos.

Residência de dados e mitigações de PII

O servidor mantém os documentos apenas no armazenamento de documentos em memória durante o time to live (TTL) configurado (padrão de 1800 segundos) e com limite de contagem (padrão de 50). Ele não persiste o conteúdo do documento em disco, a menos que você invoque explicitamente uma ferramenta de saída de arquivo e o caminho passe pela contenção. O servidor não faz nenhuma chamada de rede de saída para renderizar ou inspecionar um documento, de modo que os bytes do documento não saem da implantação, a menos que uma ferramenta seja explicitamente configurada para buscar um recurso remoto. Para implantações sem estado e sensíveis à residência de dados, desative a saída de arquivo (allow_file_output: false) e restrinja enabled_tools ao conjunto mínimo.

Telemetria segura e limpeza de logs

O registro de auditoria grava as execuções de ferramentas no nível de risco Caution e acima, além de todo desafio de confirmação emitido. O registro de auditoria inclui o nome da ferramenta, o nível de risco e o indicador de sucesso. Trate os argumentos das ferramentas como potencialmente sensíveis: direcione os logs para um destino com controles de acesso e não eleve o nível global de log a uma verbosidade que ecoe os payloads dos argumentos em ambientes compartilhados. O transporte MCP escreve os logs na saída de erro padrão, de modo que o conteúdo dos logs nunca entra no fluxo do protocolo na saída padrão.

Conformidade

Afirmação	Fonte	`reference_id`
A autenticação quebrada compromete a segurança da API	OWASP API Security Top 10, API2:2023
Tokens fracos/previsíveis são um antipadrão de autenticação quebrada	OWASP API Security Top 10, API2:2023
`401` DEVE conter um `WWW-Authenticate` como desafio	RFC 9110 §11.6.1
Credenciais ausentes/inválidas → `401` + desafio	RFC 9110 §11.6
Controlar o risco no ponto de introdução (humana)	IEC 31010:2019

O modelo de confiança stdio do Model Context Protocol segue a especificação oficial do MCP, revisão 2025-06-18. Sua URL está registrada em /transports/mcp/ porque a especificação do MCP não faz parte do corpus de normas controladas.

Contexto comercial

As ferramentas de assinatura, redação, conformidade e forense só estão presentes quando o nextpdf/premium está instalado junto com o servidor. A presença delas não altera o modelo de autenticação. O nível de risco delas ainda mantém as ferramentas destrutivas por trás do gate human-in-the-loop.

Veja também

/connect/hitl-risk-tiers/ — o modelo de risco e o envelope de confirmação em detalhes
/connect/deployment/ — TLS, TLS mútuo, segredos e ajuste de workers
/transports/rest/ — o pipeline de middleware REST e o esquema de segurança OpenAPI
/transports/grpc/ — autenticação por metadados do gRPC e códigos de status
/connect/configuration/ — enabled_tools, seleção do armazenamento de chaves, substituições de risco