Salida de archivos con intervención humana en NextPDF Connect

Visión general

La puerta de confirmación con intervención humana (HITL) protege contra escrituras no intencionadas en el sistema de archivos. Cuando se llama a output_pdf con un file_path, la puerta intercepta la llamada y devuelve un desafío de un solo uso en lugar de escribir el archivo. Una vez que una persona lo aprueba, el agente vuelve a llamar con el token y solo entonces se escribe el archivo. La salida en Base64 (sin file_path) no pasa por la puerta.

Instalación

composer require nextpdf/server

Enlazar un transporte. De forma predeterminada, output_pdf tiene el nivel de riesgo Aprobación requerida.

Visión general conceptual

La puerta evalúa el nivel de riesgo efectivo: el nivel resultante tras cualquier anulación por configuración o por identidad del llamador. Para una herramienta con Aprobación requerida:

modo base64 — output_pdf sin file_path se rebaja a Revisión y se permite sin confirmación. No se produce ningún efecto secundario en el sistema de archivos.
modo de archivo — output_pdf con un file_path permanece en Aprobación requerida. La puerta almacena un token de un solo uso asociado al nombre de la herramienta y devuelve un desafío. Si el archivo de destino ya existe, el texto del desafío incluye una advertencia de sobrescritura. El token caduca después de una ventana de tiempo fija.

En todos los transportes, el resultado de la puerta es una respuesta normal. Una aprobación pendiente es una pausa del flujo de trabajo, no un fallo del transporte (PSR-18 §3; PSR-18 §p2).

Superficie de la API

Herramienta	Función	Nivel de riesgo
`create_pdf`	Abrir la sesión	Seguro
`set_font`, `add_text`	Construir el contenido	Precaución
`output_pdf` (base64)	Devolver en línea; sin puerta	Revisión
`output_pdf` (archivo)	Escribir en disco; con puerta	Aprobación requerida

El catálogo de herramientas es la referencia, y las herramientas disponibles dependen del nivel instalado. La escala de riesgo y la puerta se definen en la referencia de niveles de riesgo HITL.

Ejemplo de código — Inicio rápido

create_pdf → construir el contenido con set_font/add_text.
output_pdf con un file_path → la puerta devuelve un sobre de desafío (el archivo no se escribe).
Transmitir el desafío a la persona.
Tras la aprobación, volver a llamar a output_pdf con los mismos argumentos más _confirmation_token establecido en el token del desafío → el archivo se escribe y la sesión se destruye.

Ejemplo de código — Producción

Tratar siempre el desafío como una pausa. No reintentar en bucle ni inventar un token.
El token es de un solo uso y está asociado al nombre de la herramienta. Un token emitido para output_pdf no puede autorizar otra herramienta.
Si la persona rechaza la operación, no volver a llamar. Para recuperar los bytes sin escribir un archivo, llamar a output_pdf en modo base64 en su lugar. Esto requiere que la sesión siga existiendo, así que usar destroy: false en el intento con puerta si se prevé que será necesario.
Si el token caduca antes de la aprobación, la puerta emite un desafío nuevo. Transmitir el desafío nuevo.

Casos límite y trampas

El token nunca se proporciona. La operación permanece pendiente. La persona debe aprobar; después, transmitir el token y volver a llamar.
Token caducado. Se emite un desafío nuevo. Volver a transmitirlo.
Herramienta incorrecta. Los tokens están asociados a una herramienta. Su reutilización para otra herramienta falla y se emite un desafío nuevo.
Ruta no absoluta. Se rechaza antes de la puerta como ruta no válida.
Sin permiso de escritura / disco lleno. Es un fallo de escritura de archivo posterior a la aprobación. Hacerlo visible. No reintentar a ciegas.
Sesión destruida antes de volver a llamar. Si un output_pdf previo usó destroy: true, la sesión ya no existe. Usar destroy: false cuando se prevea el viaje de ida y vuelta de aprobación.

Rendimiento

La puerta añade una búsqueda en el almacén de tokens y un viaje de ida y vuelta para la aprobación humana. El factor humano domina el tiempo total, no el servidor. El perfil es structural.

Notas de seguridad

La puerta es el límite entre un agente y el sistema de archivos del servidor. Existe porque la escritura de un archivo es un efecto secundario irreversible que una persona debería autorizar. El token es de un solo uso, está asociado a una herramienta y tiene una vigencia limitada. De forma deliberada, los argumentos no se incorporan mediante hash, porque los clientes pueden volver a serializar el JSON con un orden de claves distinto. Por tanto, la asociación es herramienta + nonce + TTL, no está vinculada exactamente a los argumentos. No registrar el token. Tratarlo como un secreto de un solo uso.

Conformidad

Afirmación	Especificación	Cláusula	reference_id
Una aprobación pendiente es una respuesta normal, no un fallo.	PSR-18	§3
El transporte devuelve una respuesta independientemente del resultado.	PSR-18	§p2

Esta receta describe el mecanismo de la puerta. No afirma que la puerta haga «segura» ninguna operación. La puerta hace que un efecto secundario quede autorizado por una persona.

Contexto comercial

No aplicable — la puerta y output_pdf son Core.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	El desafío se presenta al anfitrión como resultado de la herramienta para que la persona lo confirme.
REST	Sí	El desafío se devuelve en el cuerpo de la respuesta; vuelva a llamar con el token.
gRPC	Sí	Unario; el desafío es el mensaje de respuesta; vuelva a llamar con el token.

Nivel de riesgo HITL

La escala de riesgo es Seguro (0) → Precaución (1) → Revisión (2) → Aprobación requerida (3). Solo las herramientas con Aprobación requerida exigen confirmación humana. output_pdf tiene Aprobación requerida. El modo base64 lo rebaja a Revisión y omite la puerta. El modo de archivo conserva Aprobación requerida y aplica la puerta. La escala canónica y la resolución de políticas están en la referencia de niveles de riesgo HITL.

Sobre JSON de la puerta de confirmación

El resultado de la puerta tiene exactamente dos formas, tal como las expone la puerta de confirmación del servidor:

Permitido (Seguro/Precaución/Revisión, o un token válido consumido):

{ "allowed": true }

Desafío (Aprobación requerida sin un token válido):

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Cuando el archivo de destino ya existe, el texto de challenge también contiene una línea de advertencia de sobrescritura. Volver a invocar la misma herramienta con _confirmation_token establecido en el valor de token devuelve { "allowed": true }, y la operación continúa. El token es de un solo uso y caduca tras la ventana indicada en el desafío.