Sicurezza e operazioni di NextPDF Connect

In sintesi

NextPDF Connect autentica i trasporti di rete con un token bearer di chiave API. Isola il trasporto MCP locale come sottoprocesso attendibile. Ogni strumento ad alto rischio passa attraverso un controllo che richiede una conferma umana esplicita. Questa pagina descrive il modello di autenticazione, la sicurezza del trasporto e il modello delle minacce.

Installazione

composer require nextpdf/server

Panoramica concettuale

Il server ha tre confini di attendibilità, uno per ogni trasporto.

Il trasporto MCP stdio è un sottoprocesso avviato da un client locale. Legge JSON-RPC dall’input standard e scrive le risposte sull’output standard. Questo trasporto non dispone di alcun listener di rete né di alcuna chiave API. L’attendibilità è ereditata dal confine di processo del sistema operativo, ovvero dal modello di attendibilità che la specifica MCP definisce per stdio. Il logging viene inviato all’errore standard, così da non compromettere mai il flusso del protocollo.

Il trasporto REST e il trasporto gRPC sono trasporti di rete. Entrambi richiedono un token bearer di chiave API per ogni richiesta, a eccezione dei probe di integrità non autenticati. Entrambi i trasporti si basano sullo stesso archivio chiavi, sullo stesso formato di chiave e sulla stessa convalida a tempo costante. Il trasporto gRPC legge il token dai metadati della chiamata, mentre REST lo legge dall’intestazione Authorization.

Un’autenticazione implementata in modo errato rientra nella falla che OWASP API Security Top 10 segnala come API2:2023 Broken Authentication. Difetti di implementazione in tale ambito compromettono la capacità dell’API di identificare il chiamante e, di conseguenza, la sicurezza complessiva dell’API (OWASP API Security Top 10, API2:2023). I token deboli o prevedibili sono indicati esplicitamente come anti-pattern di autenticazione difettosa (stessa fonte, elenco delle vulnerabilità). La progettazione descritta di seguito è pensata per affrontare entrambi gli aspetti.

Superficie dell’API

Formato e convalida della chiave API

Una chiave ha la forma npk_live_{kid}_{secret}. Il kid è un identificatore di otto caratteri usato per cercare i record in O(1); il segreto contiene l’entropia. L’archivio non conserva mai la chiave originale. Memorizza un digest SHA-256 dell’intero materiale della chiave. Per ogni richiesta il server calcola l’hash del token presentato e lo confronta con il digest memorizzato tramite un confronto a tempo costante (hash_equals), in modo che una chiave errata non riveli nulla attraverso i tempi di risposta. Una chiave disabilitata o scaduta viene rifiutata dopo la verifica dell’hash, non prima.

I validatori REST e gRPC condividono questa logica. Il middleware REST legge Authorization: Bearer npk_live_…. L’autenticatore gRPC legge lo stesso token bearer dai metadati della chiamata gRPC authorization, trasportati come intestazioni HTTP/2. In caso di autenticazione non riuscita, la chiamata termina con lo stato gRPC UNAUTHENTICATED.

Entrambi i trasporti applicano inoltre un throttle anti-automazione al traffico di pre-autenticazione: i tentativi eccessivi provenienti da una sola identità client sono soggetti a rate-limit e vengono rifiutati — 429 Too Many Requests su REST, lo stato gRPC RESOURCE_EXHAUSTED su gRPC. Questo controllo è attivo per impostazione predefinita, quindi protegge una distribuzione che non ha configurato separatamente uno store di rate-limit; i client dovrebbero rallentare le richieste anziché riprovare immediatamente.

Risposte non autorizzate

Una richiesta REST con una chiave mancante, malformata, disabilitata o scaduta riceve 401 Unauthorized con un corpo problem-details e un’intestazione di risposta WWW-Authenticate: Bearer. Questo soddisfa il requisito HTTP secondo cui una risposta 401 DEVE includere un campo di intestazione WWW-Authenticate con almeno una challenge (RFC 9110 §11.6.1). Tale requisito deriva a sua volta dalla regola secondo cui a una richiesta che omette le credenziali o ne presenta di non valide si deve rispondere con 401 più una challenge WWW-Authenticate (RFC 9110 §11.6).

Autorizzazioni della chiave

Ogni record di chiave specifica un livello di prodotto massimo. La pipeline REST associa alla richiesta l’identità e il livello del client autenticato, così che l’autorizzazione a valle possa applicare limiti di capacità e di payload per ciascun livello. Una chiave di livello core non può attivare un’operazione Pro o Enterprise neppure quando tali pacchetti sono installati.

Casi limite e insidie

Il trasporto MCP non ha alcuna chiave API. Questo è intenzionale e corretto per un sottoprocesso locale. Non esporre il server MCP tramite uno shim di rete. Se un agente in rete necessita degli strumenti, collocarlo davanti al trasporto REST o gRPC, che effettuano l’autenticazione.
I probe di integrità sono anonimi intenzionalmente. /healthz e /readyz ignorano l’autenticazione, così gli orchestratori possono verificare liveness e readiness senza credenziali. Restituiscono soltanto uno stato. Non espongono dati degli strumenti o dei documenti.
Un token di conferma è monouso e di breve durata. Il controllo human-in-the-loop emette un token associato al nome dello strumento con una durata di 300 secondi. Il token viene consumato al primo utilizzo. Non è una credenziale di autenticazione e non sostituisce una chiave API.

Prestazioni

L’autenticazione richiede un singolo hash più un confronto a tempo costante per ogni richiesta. Tale costo è trascurabile rispetto al costo di un rendering. L’archivio chiavi con ricaricamento a caldo rilegge il file delle chiavi quando cambia, quindi la rotazione non richiede un riavvio e non aggiunge alcun costo per richiesta.

Note sulla sicurezza

Il controllo human-in-the-loop

Ogni strumento dichiara un livello di rischio. Gli strumenti al livello più alto, ApprovalRequired, non vengono eseguiti alla prima chiamata. Il controllo di conferma restituisce una challenge contenente un token monouso. L’agente deve presentare la challenge a una persona e richiamare lo strumento con il token. Si tratta di un controllo deliberato nel punto in cui l’azione automatizzata introduce un rischio. È proprio il punto che IEC 31010 individua per controllare il rischio introdotto attraverso un’azione umana (qui, dell’agente), in corrispondenza o in prossimità del punto di introduzione (IEC 31010:2019). Il controllo non può essere indebolito tramite configurazione: un override di configurazione può solo aumentare il rischio di uno strumento, mai abbassare uno strumento ApprovalRequired. Vedere /connect/hitl-risk-tiers/.

Configurazione della sicurezza del trasporto

I trasporti di rete non terminano direttamente il TLS; il TLS è un aspetto della distribuzione. La distribuzione combinata di riferimento esegue il trasporto gRPC con TLS reciproco, con la chiave, il certificato e la CA del client forniti come segreti di distribuzione. Con il TLS reciproco il server presenta un certificato e richiede e verifica un certificato del client. Eseguire il trasporto REST dietro un terminatore TLS (reverse proxy o service mesh) e non esporre mai un listener in chiaro su una rete non attendibile. I dettagli di configurazione sono in /connect/deployment/; questa è una dichiarazione di approccio, non una garanzia chiavi in mano, e un trasporto sicuro richiede una corretta configurazione della distribuzione.

Contenimento del percorso di output

Gli strumenti di scrittura su file risolvono il percorso richiesto rispetto alla directory di base configurata, lo canonicalizzano e rifiutano i byte null, i protocol wrapper e l’attraversamento ... Rifiutano qualsiasi percorso che si risolva al di fuori della base. Mantenere la directory di base su un volume dedicato, con autorizzazioni del file system a privilegio minimo.

Residenza dei dati e mitigazioni delle PII

Il server conserva i documenti solo nell’archivio documenti in memoria per il TTL configurato (predefinito 1800 secondi) e con un conteggio limitato (predefinito 50). Non persiste il contenuto dei documenti su disco, eccetto quando uno strumento di output su file viene richiamato esplicitamente e il percorso supera i controlli di contenimento. Il server non effettua alcuna chiamata di rete in uscita per eseguire il rendering o ispezionare un documento, quindi i byte del documento non lasciano la distribuzione a meno che uno strumento non sia configurato esplicitamente per recuperare una risorsa remota. Per distribuzioni senza stato e sensibili alla residenza dei dati, disabilitare l’output su file (allow_file_output: false) e limitare enabled_tools all’insieme minimo.

Telemetria sicura e sanitizzazione dei log

Il logging di audit registra le esecuzioni degli strumenti dal livello di rischio Caution in su e ogni challenge di conferma emessa. Il record di audit contiene il nome dello strumento, il livello di rischio e il flag di esito positivo. Considerare gli argomenti degli strumenti come potenzialmente sensibili: indirizzare i log verso un sink con controlli di accesso e non aumentare il livello di log globale a una verbosità che riproduca i payload degli argomenti in ambienti condivisi. Il trasporto MCP scrive i log sull’errore standard appositamente affinché il contenuto dei log non entri mai nel flusso del protocollo sull’output standard.

Conformità

Affermazione	Fonte	`reference_id`
Un’autenticazione difettosa compromette la sicurezza dell’API	OWASP API Security Top 10, API2:2023
I token deboli/prevedibili sono un anti-pattern di autenticazione difettosa	OWASP API Security Top 10, API2:2023
`401` DEVE includere una challenge `WWW-Authenticate` valida	RFC 9110 §11.6.1
Credenziali mancanti/non valide → `401` + challenge	RFC 9110 §11.6
Controllare il rischio nel punto di introduzione (umana)	IEC 31010:2019

Il modello di attendibilità stdio del Model Context Protocol segue la specifica MCP ufficiale, revisione 2025-06-18. È registrato con il relativo URL su /transports/mcp/ perché la specifica MCP non fa parte del corpus di standard soggetto a gating.

Contesto commerciale

Gli strumenti di firma, redazione, conformità e analisi forense sono presenti solo quando nextpdf/premium è installato insieme al server. La loro presenza non modifica il modello di autenticazione. I rispettivi livelli di rischio collocano comunque quelli distruttivi dietro il controllo human-in-the-loop.

Vedere anche

/connect/hitl-risk-tiers/ — il modello di rischio e l’envelope di conferma in dettaglio
/connect/deployment/ — TLS, TLS reciproco, segreti e ottimizzazione dei worker
/transports/rest/ — la pipeline del middleware REST e lo schema di sicurezza OpenAPI
/transports/grpc/ — autenticazione tramite metadati gRPC e codici di stato
/connect/configuration/ — enabled_tools, selezione dell’archivio chiavi, override di rischio