Sicherheit und Betrieb für NextPDF Connect

Auf einen Blick

NextPDF Connect authentifiziert vernetzte Transporte per API-Schlüssel als Bearer-Token. Der lokale MCP-Transport wird als vertrauenswürdiger Subprozess isoliert. Jedes hochriskante Tool wird durch eine ausdrückliche menschliche Bestätigung abgesichert. Diese Seite beschreibt das Authentifizierungsmodell, die Transportsicherheit und das Bedrohungsmodell.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Der Server definiert drei Vertrauensgrenzen, je eine pro Transport.

Der MCP-stdio-Transport ist ein Subprozess, der von einem lokalen Client gestartet wird. Er liest JSON-RPC von der Standardeingabe und schreibt Antworten auf die Standardausgabe. Dieser Transport hat keinen Netzwerk-Listener und keinen API-Schlüssel. Das Vertrauen ergibt sich aus der Prozessgrenze des Betriebssystems; das entspricht dem Vertrauensmodell, das die MCP-Spezifikation für stdio definiert. Logs werden auf die Standardfehlerausgabe geschrieben, sodass sie den Protokollstrom nie beschädigen.

Der REST-Transport und der gRPC-Transport sind vernetzt. Beide verlangen bei jeder Anfrage einen API-Schlüssel als Bearer-Token, mit Ausnahme der unauthentifizierten Health-Probes. Beide Transporte verwenden denselben Schlüsselspeicher, dasselbe Schlüsselformat und dieselbe konstantzeitige Validierung. Der gRPC-Transport liest das Token aus den Call-Metadaten, während REST es aus dem Authorization-Header liest.

Fehlerhaft umgesetzte Authentifizierung ist genau die Fehlerklasse, die die OWASP API Security Top 10 als API2:2023 Broken Authentication kennzeichnet. Solche Umsetzungsfehler untergraben die Fähigkeit der API, den Aufrufer zu identifizieren, und damit die API-Sicherheit insgesamt (OWASP API Security Top 10, API2:2023). Schwache oder vorhersagbare Tokens werden ausdrücklich als Broken-Auth-Anti-Pattern benannt (dieselbe Quelle, Schwachstellenliste). Das folgende Design wirkt beidem entgegen.

API-Oberfläche

API-Schlüsselformat und Validierung

Ein Schlüssel ist npk_live_{kid}_{secret}. Die kid ist ein achtstelliger Identifikator für den O(1)-Datensatz-Lookup; die Entropie liegt im Secret. Der Speicher behält den rohen Schlüssel nie. Er hält einen SHA-256-Digest des vollständigen Schlüsselmaterials. Bei jeder Anfrage hasht der Server das vorgelegte Token und vergleicht es per konstantzeitigem Vergleich (hash_equals) mit dem gespeicherten Digest, sodass ein falscher Schlüssel über das Timing nichts preisgibt. Ein deaktivierter oder abgelaufener Schlüssel wird nach der Hash-Prüfung abgelehnt, nicht davor.

Die REST- und gRPC-Validatoren teilen sich diese Logik. Die REST-Middleware liest Authorization: Bearer npk_live_…. Der gRPC-Authenticator liest dasselbe Bearer-Token aus den gRPC-authorization-Call-Metadaten, die als HTTP/2-Header transportiert werden. Der Call schlägt dann mit dem gRPC-Status UNAUTHENTICATED fehl.

Beide Transporte drosseln außerdem Pre-Authentication-Traffic als Anti-Automatisierungsmaßnahme: Übermäßige Versuche einer einzelnen Client-Identität werden per Rate Limit begrenzt und zurückgewiesen — 429 Too Many Requests bei REST, der gRPC-Status RESOURCE_EXHAUSTED bei gRPC. Diese Kontrolle ist standardmäßig aktiv, sodass sie ein Deployment schützt, das keinen separat konfigurierten Rate-Limit-Store besitzt; Clients sollten mit Backoff reagieren, anstatt sofort einen erneuten Versuch zu unternehmen.

Nicht autorisierte Antworten

Eine REST-Anfrage mit fehlendem, fehlerhaftem, deaktiviertem oder abgelaufenem Schlüssel erhält 401 Unauthorized mit einem Problem-Details-Body und einem WWW-Authenticate: Bearer-Antwortheader. Das entspricht der HTTP-Anforderung, dass eine 401-Antwort ein WWW-Authenticate-Headerfeld mit mindestens einer Challenge tragen MUSS (RFC 9110 §11.6.1). Diese Anforderung selbst folgt aus der Regel, dass eine Anfrage ohne oder mit ungültigen Anmeldedaten mit 401 plus einer WWW-Authenticate-Challenge beantwortet werden sollte (RFC 9110 §11.6).

Schlüsselberechtigung

Jeder Schlüsseldatensatz trägt eine maximale Produktstufe. Die REST-Pipeline hängt die Identität und Stufe des authentifizierten Clients an die Anfrage an, sodass die nachgelagerte Autorisierung Capability- und Payload-Obergrenzen pro Stufe durchsetzen kann. Ein Schlüssel der Core-Stufe kann für keine Pro- oder Enterprise-Operation verwendet werden, selbst wenn diese Pakete installiert sind.

Sonderfälle und Fallstricke

• Der MCP-Transport hat keinen API-Schlüssel. Das ist für einen lokalen Subprozess absichtlich so und korrekt. Geben Sie den MCP-Server nicht über ein Netzwerk-Shim frei. Wenn ein vernetzter Agent die Tools benötigt, binden Sie ihn über den REST- oder gRPC-Transport an; beide authentifizieren.

• Health-Probes sind absichtlich anonym. /healthz und /readyz umgehen die Authentifizierung, damit Orchestratoren Liveness und Readiness ohne Anmeldedaten prüfen können. Sie geben nur einen Status zurück. Sie legen keine Tool- oder Dokumentdaten offen.

• Ein Bestätigungstoken ist einmalig verwendbar und kurzlebig. Das Human-in-the-Loop-Gate stellt ein an den Tool-Namen gebundenes Token mit einer Lebensdauer von 300 Sekunden aus. Das Token wird bei der ersten Verwendung verbraucht. Es ist kein Authentifizierungsnachweis und ersetzt keinen API-Schlüssel.

Performance

Authentifizierung ist ein einzelner Hash plus ein konstantzeitiger Vergleich pro Anfrage. Diese Kosten sind gegenüber den Kosten eines Renderings vernachlässigbar. Der Hot-Reloading-Schlüsselspeicher liest die Schlüsseldatei bei Änderungen neu ein, sodass eine Rotation keinen Neustart erfordert und keine Kosten pro Anfrage verursacht.

Sicherheitshinweise

Das Human-in-the-Loop-Gate

Jedes Tool deklariert eine Risikostufe. Tools auf der höchsten Stufe, ApprovalRequired, laufen beim ersten Aufruf nicht. Das Bestätigungs-Gate gibt eine Challenge zurück, die ein einmalig verwendbares Token enthält. Der Agent muss die Challenge einem Menschen vorlegen und das Tool mit dem Token erneut aufrufen. Das ist eine bewusste Kontrolle an dem Punkt, an dem automatisiertes Handeln Risiko einbringt. Es entspricht genau der Stelle, die IEC 31010 für die Kontrolle von Risiken nennt, die durch menschliches (hier: Agenten-)Handeln eingebracht werden: an oder nahe dem Punkt der Einbringung (IEC 31010:2019). Das Gate lässt sich per Konfiguration nicht abschwächen: Ein Konfigurations-Override darf das Risiko eines Tools nur anheben, nie ein ApprovalRequired-Tool herabstufen. Siehe /connect/hitl-risk-tiers/.

Konfiguration der Transportsicherheit

Die vernetzten Transporte terminieren TLS nicht selbst; TLS ist eine Deployment-Angelegenheit. Das kombinierte Referenz-Deployment betreibt den gRPC-Transport mit gegenseitigem TLS, wobei Schlüssel, Zertifikat und Client-CA als Deployment-Secrets bereitgestellt werden. Bei gegenseitigem TLS präsentiert der Server ein Zertifikat und verlangt und verifiziert ein Client-Zertifikat. Betreiben Sie den REST-Transport hinter einem TLS-Terminator (Reverse-Proxy oder Service-Mesh) und geben Sie niemals einen Klartext-Listener in einem nicht vertrauenswürdigen Netzwerk frei. Konfigurationsdetails stehen in /connect/deployment/; das ist eine Aussage zur Sicherheitsposition, keine schlüsselfertige Garantie, und sicherer Transport erfordert eine korrekte Deployment-Konfiguration.

Eingrenzung des Ausgabepfads

Tools, die Dateien schreiben, lösen den angeforderten Pfad relativ zum konfigurierten Basisverzeichnis auf, kanonisieren ihn und lehnen Null-Bytes, Protokoll-Wrapper und ..-Traversierung ab. Sie verweigern jeden Pfad, der außerhalb der Basis aufgelöst wird. Halten Sie das Basisverzeichnis auf einem dedizierten Volume mit Least-Privilege-Dateisystemberechtigungen.

Datenresidenz und PII-Minderungsmaßnahmen

Der Server hält Dokumente ausschließlich im In-Memory-Dokumentspeicher, und zwar für die konfigurierte TTL (Standard 1800 Sekunden) und bis zu einer begrenzten Anzahl (Standard 50). Dokumentinhalte persistiert er nicht auf die Festplatte, außer wenn ein Datei-Ausgabe-Tool ausdrücklich aufgerufen wird und der Pfad die Eingrenzung besteht. Der Server führt keinen ausgehenden Netzwerkaufruf durch, um ein Dokument zu rendern oder zu inspizieren, sodass Dokumentbytes das Deployment nicht verlassen, sofern ein Tool nicht ausdrücklich so konfiguriert ist, dass es eine entfernte Ressource abruft. Deaktivieren Sie für zustandslose, residenzsensible Deployments die Dateiausgabe (allow_file_output: false) und beschränken Sie enabled_tools auf das Minimum.

Sichere Telemetrie und Log-Scrubbing

Audit-Logging zeichnet Tool-Ausführungen ab der Risikostufe Caution und darüber sowie jede ausgestellte Bestätigungs-Challenge auf. Der Audit-Datensatz enthält den Tool-Namen, die Risikostufe und das Erfolgs-Flag. Behandeln Sie Tool-Argumente als potenziell sensibel: Leiten Sie Logs an eine Senke mit Zugriffskontrollen weiter, und heben Sie das globale Log-Level nicht auf eine Ausführlichkeit an, bei der Argument-Payloads in gemeinsam genutzten Umgebungen ausgegeben werden. Der MCP-Transport schreibt Logs auf die Standardfehlerausgabe, gerade damit Log-Inhalte nie in den Protokollstrom auf der Standardausgabe gelangen.

Konformität

Aussage	Quelle	reference_id
Broken Authentication untergräbt die API-Sicherheit	OWASP API Security Top 10, API2:2023
Schwache/vorhersagbare Tokens sind ein Broken-Auth-Anti-Pattern	OWASP API Security Top 10, API2:2023
401 MUSS eine WWW-Authenticate-Challenge tragen	RFC 9110 §11.6.1
Fehlende/ungültige Anmeldedaten → 401 + Challenge	RFC 9110 §11.6
Risiko am Punkt der (menschlichen) Einbringung kontrollieren	IEC 31010:2019

Das stdio-Vertrauensmodell des Model Context Protocol folgt der offiziellen MCP-Spezifikation, Revision 2025-06-18. Sie ist mit ihrer URL auf /transports/mcp/ festgehalten, weil die MCP-Spezifikation nicht Teil des gated Standards-Korpus ist.

Kommerzieller Kontext

Signatur-, Schwärzungs-, Compliance- und Forensik-Tools sind nur vorhanden, wenn nextpdf/premium neben dem Server installiert ist. Ihre Anwesenheit ändert das Authentifizierungsmodell nicht. Ihre Risikostufe hält die destruktiven darunter weiterhin hinter dem Human-in-the-Loop-Gate.

Siehe auch

• /connect/hitl-risk-tiers/ — das Risikomodell und der Bestätigungs-Envelope im Detail
• /connect/deployment/ — TLS, gegenseitiges TLS, Secrets und Worker-Tuning
• /transports/rest/ — die REST-Middleware-Pipeline und das OpenAPI-Security-Scheme
• /transports/grpc/ — gRPC-Metadaten-Authentifizierung und Statuscodes
• /connect/configuration/ — enabled_tools, Auswahl des Schlüsselspeichers, Risiko-Overrides