Seguridad y operaciones en NextPDF Connect

De un vistazo

NextPDF Connect autentica los transportes en red mediante un token de portador de clave de API. Aísla el transporte MCP local como subproceso de confianza. Somete cada herramienta de alto riesgo a una confirmación humana explícita. Esta página describe el modelo de autenticación, la seguridad del transporte y el modelo de amenazas.

Instalación

composer require nextpdf/server

Panorama conceptual

El servidor define tres límites de confianza, uno por transporte.

El transporte stdio de MCP es un subproceso iniciado por un cliente local. Lee JSON-RPC desde la entrada estándar y escribe las respuestas en la salida estándar. Este transporte no tiene escucha de red ni clave de API. La confianza se hereda del límite de proceso del sistema operativo, que es el modelo de confianza que la especificación de MCP define para stdio. El registro se envía a la salida de error estándar, de modo que nunca corrompe el flujo del protocolo.

El transporte REST y el transporte gRPC funcionan en red. Ambos exigen un token de portador de clave de API en cada solicitud, excepto en los sondeos de estado no autenticados. El mismo almacén de claves, el mismo formato de clave y la misma validación de tiempo constante respaldan ambos transportes. El transporte gRPC lee el token de los metadatos de la llamada, mientras que REST lo lee de la cabecera Authorization.

La autenticación implementada de forma incorrecta corresponde al fallo que el OWASP API Security Top 10 señala como API2:2023 Broken Authentication. En ese caso, los defectos de implementación comprometen la capacidad de la API para identificar a quien la invoca y, por tanto, comprometen la seguridad de la API en su conjunto (OWASP API Security Top 10, API2:2023). Los tokens débiles o predecibles se señalan de forma explícita como un antipatrón de autenticación rota (misma fuente, lista de vulnerabilidades). El diseño que sigue está pensado para resistir ambos riesgos.

Superficie de la API

Formato de clave de API y validación

Una clave tiene la forma npk_live_{kid}_{secret}. El kid es un identificador de ocho caracteres que se usa para buscar registros en O(1); el secreto aporta la entropía. El almacén nunca conserva la clave en bruto. Guarda un resumen SHA-256 del material completo de la clave. En cada solicitud, el servidor calcula el hash del token presentado y lo compara con el resumen almacenado mediante una comparación de tiempo constante (hash_equals), de modo que una clave incorrecta no revela nada mediante el tiempo de respuesta. Una clave deshabilitada o caducada se rechaza después de la comprobación del hash, no antes.

Los validadores de REST y gRPC comparten esta lógica. El middleware de REST lee Authorization: Bearer npk_live_…. El autenticador de gRPC lee el mismo token de portador de los metadatos de llamada authorization de gRPC, que se transportan como cabeceras HTTP/2. La llamada falla con el estado UNAUTHENTICATED de gRPC.

Ambos transportes aplican además un control antiautomatización sobre el tráfico previo a la autenticación: los intentos excesivos desde una misma identidad de cliente se limitan por tasa y se rechazan —429 Too Many Requests en REST, el estado gRPC RESOURCE_EXHAUSTED en gRPC. Este control está activo de forma predeterminada, por lo que protege un despliegue que no ha configurado por separado un almacén de límite de tasa; los clientes deberían esperar antes de reintentar en lugar de hacerlo de inmediato.

Respuestas no autorizadas

Una solicitud REST con una clave ausente, malformada, deshabilitada o caducada recibe 401 Unauthorized con un cuerpo problem-details y una cabecera de respuesta WWW-Authenticate: Bearer. Esto coincide con el requisito de HTTP según el cual una respuesta 401 DEBE llevar un campo de cabecera WWW-Authenticate con al menos un desafío (RFC 9110 §11.6.1). Ese requisito se deriva, a su vez, de la regla de que una solicitud que omite credenciales o lleva credenciales no válidas debe responderse con 401 más un desafío WWW-Authenticate (RFC 9110 §11.6).

Habilitación de la clave

Cada registro de clave incluye un nivel de producto máximo. La canalización de REST adjunta la identidad y el nivel del cliente autenticado a la solicitud, de modo que la autorización posterior puede imponer límites de capacidad y de carga útil por nivel. Una clave de nivel core no puede ejecutar una operación Pro ni Enterprise aunque esos paquetes estén instalados.

Casos límite y trampas

El transporte MCP no tiene clave de API. Esto es intencional y correcto para un subproceso local. No se debe exponer el servidor MCP a través de un shim de red. Si un agente en red necesita las herramientas, debe colocarse delante del transporte REST o gRPC, que sí autentican.
Los sondeos de estado son anónimos a propósito. /healthz y /readyz omiten la autenticación para que los orquestadores puedan sondear la vivacidad y la disponibilidad sin una credencial. Solo devuelven estado. No exponen ningún dato de herramienta ni de documento.
Un token de confirmación es de un solo uso y de vida corta. La compuerta con intervención humana emite un token vinculado al nombre de la herramienta con una vida útil de 300 segundos. El token se consume en el primer uso. No es una credencial de autenticación ni sustituye a una clave de API.

Rendimiento

La autenticación consiste en un solo hash más una comparación de tiempo constante por solicitud. Ese costo es insignificante frente al costo de un renderizado. El almacén de claves con recarga en caliente vuelve a leer el archivo de claves cuando cambia, de modo que la rotación no requiere un reinicio y no añade ningún costo por solicitud.

Notas de seguridad

La compuerta con intervención humana

Cada herramienta declara un nivel de riesgo. Las herramientas del nivel más alto, ApprovalRequired, no se ejecutan en la primera llamada. La compuerta de confirmación devuelve un desafío que contiene un token de un solo uso. El agente debe presentar el desafío a una persona y volver a invocar la herramienta con el token. Se trata de un control deliberado en el punto donde la acción automatizada introduce riesgo. Es precisamente el lugar que la IEC 31010 identifica para controlar el riesgo introducido por la acción humana (aquí, del agente), en el punto de introducción o cerca de él (IEC 31010:2019). La compuerta no puede debilitarse mediante configuración: una anulación de configuración solo puede elevar el riesgo de una herramienta, nunca rebajar una herramienta ApprovalRequired. Consultar /connect/hitl-risk-tiers/.

Configuración de la seguridad del transporte

Los transportes en red no terminan el TLS por sí mismos; el TLS es una cuestión de despliegue. El despliegue de referencia combinado ejecuta el transporte gRPC con TLS mutuo, con la clave, el certificado y la CA de cliente suministrados como secretos de despliegue. Con TLS mutuo, el servidor presenta un certificado y exige y verifica un certificado de cliente. El transporte REST debe ejecutarse detrás de un terminador de TLS (proxy inverso o malla de servicios) y nunca debe exponerse un servicio de escucha en texto plano en una red no confiable. Los detalles de configuración están en /connect/deployment/; esto es una declaración de postura, no una garantía llave en mano, y el transporte seguro requiere una configuración de despliegue correcta.

Contención de la ruta de salida

Las herramientas de escritura de archivos resuelven la ruta solicitada respecto del directorio base configurado, la canonicalizan y rechazan los bytes nulos, los envoltorios de protocolo y el recorrido ... Rechazan cualquier ruta que se resuelva fuera de la base. Mantener el directorio base en un volumen dedicado con permisos de sistema de archivos de mínimo privilegio.

Residencia de datos y mitigaciones de PII

El servidor conserva los documentos solo en el almacén de documentos en memoria durante el TTL configurado (predeterminado: 1800 segundos) y con un recuento acotado (predeterminado: 50). No persiste el contenido del documento en disco salvo cuando se invoca explícitamente una herramienta de salida a archivo y la ruta supera la contención. El servidor no realiza ninguna llamada de red saliente para renderizar o inspeccionar un documento, de modo que los bytes del documento no salen del despliegue a menos que una herramienta esté configurada explícitamente para obtener un recurso remoto. En despliegues sin estado y sensibles a la residencia, deshabilitar la salida a archivo (allow_file_output: false) y restringir enabled_tools al conjunto mínimo.

Telemetría segura y depuración de registros

El registro de auditoría anota las ejecuciones de herramientas con nivel de riesgo Caution y superior, y cada desafío de confirmación emitido. El registro de auditoría incluye el nombre de la herramienta, el nivel de riesgo y el indicador de éxito. Tratar los argumentos de las herramientas como potencialmente sensibles: encaminar los registros a un destino con controles de acceso y no elevar el nivel global de registro a una verbosidad que reproduzca las cargas útiles de los argumentos en entornos compartidos. El transporte MCP escribe los registros en la salida de error estándar precisamente para que el contenido del registro nunca entre en el flujo del protocolo en la salida estándar.

Conformidad

Afirmación	Fuente	`reference_id`
La autenticación rota compromete la seguridad de la API	OWASP API Security Top 10, API2:2023
Los tokens débiles o predecibles son un antipatrón de autenticación rota	OWASP API Security Top 10, API2:2023
`401` DEBE llevar un desafío `WWW-Authenticate` en la cabecera	RFC 9110 §11.6.1
Credenciales ausentes o no válidas → `401` + desafío	RFC 9110 §11.6
Controlar el riesgo en el punto de introducción (humana)	IEC 31010:2019

El modelo de confianza de stdio del Model Context Protocol sigue la especificación oficial de MCP, revisión 2025-06-18. Está registrado con su URL en /transports/mcp/ porque la especificación de MCP no forma parte del corpus de estándares controlado.

Contexto comercial

Las herramientas de firma, redacción, cumplimiento y forenses están presentes solo cuando nextpdf/premium está instalado junto con el servidor. Su presencia no cambia el modelo de autenticación. Su nivel de riesgo sigue situando las herramientas destructivas detrás de la compuerta con intervención humana.

Consulta también

/connect/hitl-risk-tiers/ — el modelo de riesgo y la envoltura de confirmación en detalle
/connect/deployment/ — TLS, TLS mutuo, secretos y ajuste de workers
/transports/rest/ — la canalización de middleware de REST y el esquema de seguridad de OpenAPI
/transports/grpc/ — la autenticación por metadatos de gRPC y los códigos de estado
/connect/configuration/ — enabled_tools, selección del almacén de claves, anulaciones de riesgo