Beveiliging en operationeel beheer voor NextPDF Connect

In een oogopslag

NextPDF Connect authenticeert netwerktransporten met een bearertoken op basis van een API-sleutel. Het lokale Model Context Protocol (MCP)-transport wordt behandeld als een vertrouwd subproces. Elke tool met een hoog risico wordt afgeschermd met expliciete menselijke bevestiging. Deze pagina licht het authenticatiemodel, de transportbeveiliging en het dreigingsmodel toe.

Installeren

composer require nextpdf/server

Conceptueel overzicht

De server kent drie vertrouwensgrenzen: één per transport.

Het MCP stdio-transport is een subproces dat door een lokale client wordt gestart. Het leest JSON-RPC van de standaardinvoer en schrijft antwoorden naar de standaarduitvoer. Dit transport heeft geen netwerklistener en geen API-sleutel. Het ontleent zijn vertrouwen aan de procesgrens van het besturingssysteem: het vertrouwensmodel dat de MCP-specificatie voor stdio definieert. Logging gaat naar de standaardfout, zodat de protocolstream nooit beschadigd raakt.

Het REST-transport en het gRPC-transport zijn netwerkgebaseerd. Beide vereisen bij elke aanvraag een bearertoken op basis van een API-sleutel, behalve bij niet-geauthenticeerde health-probes. Beide transporten gebruiken dezelfde sleutelopslag, sleutelindeling en validatie met constante looptijd. Het gRPC-transport leest het token uit de aanroepmetadata. REST leest het uit de Authorization-header.

Onjuiste authenticatie is de tekortkoming die de OWASP Application Programming Interface (API) Security Top 10 aanduidt als API2:2023 Broken Authentication. Fouten op dit gebied beperken het vermogen van de API om de aanroeper te identificeren en brengen daarmee de API-beveiliging als geheel in gevaar (OWASP API Security Top 10, API2:2023). Zwakke of voorspelbare tokens worden eveneens genoemd als een anti-patroon voor broken authentication (dezelfde bron, kwetsbaarhedenlijst). Het onderstaande ontwerp ondervangt beide risico’s.

API-oppervlak

API-sleutelindeling en -validatie

Een sleutel heeft de vorm npk_live_{kid}_{secret}. De kid is een identifier van acht tekens die wordt gebruikt voor O(1)-recordopzoeking; het secret bevat de entropie. De opslag bewaart de ruwe sleutel nooit, maar slaat een SHA-256-digest van het volledige sleutelmateriaal op. Bij elke aanvraag hasht de server het aangeboden token en vergelijkt hij het met de opgeslagen digest via een vergelijking met constante looptijd (hash_equals), zodat een verkeerde sleutel niets prijsgeeft via timing. Een uitgeschakelde of verlopen sleutel wordt na de hashcontrole afgewezen, niet daarvoor.

De REST- en gRPC-validators delen deze logica. De REST-middleware leest Authorization: Bearer npk_live_…. De gRPC-authenticator leest hetzelfde bearertoken uit de gRPC-authorization-aanroepmetadata, die als HTTP/2-headers wordt meegedragen. Daardoor mislukt de aanroep met de gRPC-status UNAUTHENTICATED.

Beide transporten passen ook een anti-automatiseringsbeperking toe op pre-authenticatieverkeer: buitensporige pogingen vanuit één clientidentiteit worden via rate-limiting beperkt en afgewezen — 429 Too Many Requests bij REST, en de gRPC-status RESOURCE_EXHAUSTED bij gRPC. Deze maatregel is standaard actief, zodat hij ook een implementatie beschermt waarvoor geen afzonderlijke rate-limit-opslag is geconfigureerd. Clients moeten terugschalen in plaats van het direct opnieuw te proberen.

Niet-geautoriseerde reacties

Een REST-aanvraag met een ontbrekende, onjuist opgemaakte, uitgeschakelde of verlopen sleutel ontvangt 401 Unauthorized met een problem-details-body en een WWW-Authenticate: Bearer-antwoordheader. Dit komt overeen met de HTTP-eis dat een 401-antwoord een WWW-Authenticate-headerveld met ten minste één challenge MOET bevatten (RFC 9110 §11.6.1). Die eis volgt uit de regel dat een aanvraag met ontbrekende of ongeldige credentials 401 plus een WWW-Authenticate-challenge zou moeten ontvangen (RFC 9110 §11.6).

Sleutelrechten

Elk sleutelrecord bevat een maximaal productniveau. De REST-pijplijn koppelt de identiteit en het niveau van de geauthenticeerde client aan de aanvraag, zodat downstream-autorisatie per niveau limieten op functionaliteit en payloadgrootte kan afdwingen. Een sleutel op core-niveau kan geen Pro- of Enterprise-bewerking uitvoeren, ook niet wanneer die pakketten zijn geïnstalleerd.

Randgevallen en valkuilen

Het MCP-transport heeft geen API-sleutel. Dat is opzettelijk en passend voor een lokaal subproces. Stel de MCP-server niet bloot via een netwerk-shim. Als een netwerkgebaseerde agent de tools nodig heeft, plaats die dan vóór het REST- of gRPC-transport, dat wel authenticeert.
Health-probes zijn met opzet anoniem. /healthz en /readyz omzeilen authenticatie zodat orchestrators liveness en readiness zonder credential kunnen peilen. Ze retourneren alleen een status en stellen geen toolgegevens of documentgegevens bloot.
Een bevestigingstoken is eenmalig bruikbaar en kortlevend. De human-in-the-loop-poort geeft een token uit dat aan de toolnaam is gebonden en een levensduur van 300 seconden heeft. Het token wordt bij het eerste gebruik verbruikt. Het is geen authenticatiecredential en vervangt geen API-sleutel.

Prestaties

Authenticatie bestaat per aanvraag uit één hash plus een vergelijking met constante looptijd. Die kosten zijn verwaarloosbaar vergeleken met de kosten van een render. De hot-reloading sleutelopslag leest het sleutelbestand opnieuw in wanneer het wijzigt, zodat rotatie geen herstart vereist en geen kosten per aanvraag toevoegt.

Beveiligingsnotities

De human-in-the-loop-poort

Elke tool declareert een risiconiveau. Tools op het hoogste niveau, ApprovalRequired, worden bij de eerste aanroep niet uitgevoerd. De bevestigingspoort retourneert een challenge met een eenmalig bruikbaar token. De agent moet de challenge aan een mens tonen en de tool opnieuw aanroepen met het token. Dit is een bewuste maatregel op het punt waar geautomatiseerde actie risico introduceert. Dat is het punt dat IEC 31010 aanwijst voor het beheersen van risico dat via menselijke (hier: agent-)actie wordt geïntroduceerd, op of nabij het punt van introductie (IEC 31010:2019). Configuratie kan de poort niet verzwakken: een config-override mag het risico van een tool alleen verhogen, nooit een ApprovalRequired-tool verlagen. Zie /connect/hitl-risk-niveaus/.

Configuratie van transportbeveiliging

De netwerktransporten beëindigen Transport Layer Security (TLS) niet zelf; TLS hoort bij de implementatie. De gecombineerde referentie-implementatie draait het gRPC-transport met mutual TLS, waarbij de sleutel, het certificaat en de client-CA als implementatiegeheimen worden aangeleverd. Bij mutual TLS presenteert de server een certificaat en vereist en verifieert hij een clientcertificaat. Draai het REST-transport achter een TLS-terminator (reverseproxy of service mesh) en stel nooit een plaintext-listener bloot op een onvertrouwd netwerk. De configuratiedetails staan in /connect/deployment/. Dit is een verklaring over de beveiligingshouding, geen kant-en-klare garantie, en veilig transport vereist een correcte implementatieconfiguratie.

Insluiting van het uitvoerpad

Tools die bestanden schrijven, herleiden het opgevraagde pad ten opzichte van de geconfigureerde basismap, canoniseren het en wijzen null bytes, protocol wrappers en ..-traversal af. Ze weigeren elk pad dat buiten de basismap uitkomt. Houd de basismap op een toegewezen volume met bestandssysteemrechten volgens het least-privilege-principe.

Gegevenslocatie en PII-maatregelen

De server bewaart documenten uitsluitend in de in-memory documentopslag gedurende de geconfigureerde time to live (TTL) (standaard 1800 seconden) en tot een begrensd aantal (standaard 50). Documentinhoud wordt niet op schijf bewaard, tenzij expliciet een bestandsuitvoertool wordt aangeroepen en het pad de insluitingscontrole doorstaat. De server doet geen uitgaande netwerkaanroep om een document weer te geven of te inspecteren, zodat documentbytes de implementatie niet verlaten tenzij een tool expliciet is geconfigureerd om een externe resource op te halen. Schakel voor stateless, locatiegevoelige implementaties de bestandsuitvoer uit (allow_file_output: false) en beperk enabled_tools tot de minimale set.

Veilige telemetrie en log scrubbing

Auditlogging registreert tooluitvoeringen op risiconiveau Caution en hoger, plus elke uitgegeven bevestigingschallenge. Het auditrecord bevat de toolnaam, het risiconiveau en de succesvlag. Behandel toolargumenten als potentieel gevoelig: stuur logs naar een sink met toegangscontroles en verhoog het globale logniveau niet zodanig dat argumentpayloads in gedeelde omgevingen zichtbaar worden. Het MCP-transport schrijft logs naar de standaardfout, zodat loginhoud nooit in de protocolstream op de standaarduitvoer terechtkomt.

Conformiteit

Bewering	Bron	`reference_id`
Broken authentication brengt de API-beveiliging in gevaar	OWASP API Security Top 10, API2:2023
Zwakke/voorspelbare tokens zijn een anti-patroon voor broken authentication	OWASP API Security Top 10, API2:2023
`401` MOET een `WWW-Authenticate`-challenge bevatten	RFC 9110 §11.6.1
Ontbrekende/ongeldige credentials → `401` + challenge	RFC 9110 §11.6
Beheers risico op het punt van (menselijke) introductie	IEC 31010:2019

Het stdio-vertrouwensmodel van het Model Context Protocol volgt de officiële MCP-specificatie, revisie 2025-06-18. De URL is vastgelegd op /transports/mcp/ omdat de MCP-specificatie geen deel uitmaakt van het afgeschermde standaardencorpus.

Commerciële context

Tools voor ondertekening, redactie, compliance en forensisch onderzoek zijn alleen aanwezig wanneer nextpdf/premium naast de server is geïnstalleerd. Hun aanwezigheid verandert niets aan het authenticatiemodel. Hun risiconiveau plaatst destructieve tools nog steeds achter de human-in-the-loop-poort.

Zie ook

/connect/hitl-risk-niveaus/ — het risicomodel en de bevestigingsenvelop in detail
/connect/deployment/ — TLS, mutual TLS, secrets en worker-tuning
/transports/rest/ — de REST-middlewarepijplijn en het OpenAPI-beveiligingsschema
/transports/grpc/ — gRPC-metadata-authenticatie en statuscodes
/connect/configuration/ — enabled_tools, selectie van de sleutelopslag, risico-overrides