Bezpieczeństwo i eksploatacja NextPDF Connect

W skrócie

NextPDF Connect uwierzytelnia transporty sieciowe za pomocą tokenu bearer w postaci klucza API. Lokalny transport Model Context Protocol (MCP) traktuje jako zaufany podproces. Każde narzędzie wysokiego ryzyka wymaga jawnego potwierdzenia przez człowieka przed uruchomieniem. Ta strona wyjaśnia model uwierzytelniania, bezpieczeństwo transportu oraz model zagrożeń.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Serwer ma trzy granice zaufania, po jednej dla każdego transportu.

Transport MCP stdio to podproces uruchamiany przez lokalnego klienta. Odczytuje JSON-RPC ze standardowego wejścia i zapisuje odpowiedzi na standardowe wyjście. Ten transport nie ma nasłuchu sieciowego ani klucza API. Dziedziczy zaufanie wynikające z granicy procesu w systemie operacyjnym, co odpowiada modelowi zaufania, który specyfikacja MCP definiuje dla stdio. Logi trafiają na standardowe wyjście błędów, więc nigdy nie naruszają strumienia protokołu.

Transport REST oraz transport gRPC działają w sieci. Oba wymagają tokenu bearer w postaci klucza API dla każdego żądania, z wyjątkiem nieuwierzytelnianych sond kondycji. Oba transporty współdzielą ten sam magazyn kluczy, format klucza oraz walidację w stałym czasie. Transport gRPC odczytuje token z metadanych wywołania. REST odczytuje go z nagłówka Authorization.

Nieprawidłowe uwierzytelnianie to błąd, który OWASP Application Programming Interface (API) Security Top 10 określa jako API2:2023 Broken Authentication. Wady w tym obszarze ograniczają zdolność API do identyfikacji wywołującego, a przez to osłabiają ogólne bezpieczeństwo API (OWASP API Security Top 10, API2:2023). Słabe lub przewidywalne tokeny są również wskazywane jako antywzorzec naruszonego uwierzytelniania (to samo źródło, lista podatności). Projekt opisany poniżej odnosi się do obu tych zagrożeń.

Powierzchnia API

Format i walidacja klucza API

Klucz ma postać npk_live_{kid}_{secret}. Element kid to ośmioznakowy identyfikator używany do wyszukiwania rekordu w czasie O(1), a entropię zapewnia część tajna. Magazyn nigdy nie przechowuje surowego klucza. Przechowuje skrót SHA-256 całego materiału klucza. Przy każdym żądaniu serwer haszuje przedstawiony token i porównuje go z przechowywanym skrótem za pomocą porównania w stałym czasie (hash_equals), więc błędny klucz nie ujawnia niczego przez czas odpowiedzi. Wyłączony albo wygasły klucz jest odrzucany po sprawdzeniu skrótu, a nie przed nim.

Walidatory REST i gRPC współdzielą tę logikę. Oprogramowanie pośredniczące REST odczytuje Authorization: Bearer npk_live_…. Mechanizm uwierzytelniający gRPC odczytuje ten sam token bearer z metadanych wywołania gRPC authorization, które są przenoszone jako nagłówki HTTP/2. Wywołanie kończy się niepowodzeniem ze statusem gRPC UNAUTHENTICATED.

Oba transporty stosują też ograniczenia przeciwautomatyzacyjne dla ruchu sprzed uwierzytelnienia: nadmierne próby z jednej tożsamości klienta są limitowane co do tempa i odrzucane — 429 Too Many Requests w REST oraz status gRPC RESOURCE_EXHAUSTED w gRPC. To zabezpieczenie jest domyślnie aktywne, więc chroni wdrożenie nawet wtedy, gdy nie skonfigurowano odrębnego magazynu limitów tempa. Klienci powinni odczekać, zamiast ponawiać próbę natychmiast.

Odpowiedzi o braku autoryzacji

Żądanie REST z brakującym, źle sformułowanym, wyłączonym lub wygasłym kluczem otrzymuje 401 Unauthorized wraz z treścią problem-details oraz nagłówkiem odpowiedzi WWW-Authenticate: Bearer. Spełnia to wymaganie HTTP, zgodnie z którym odpowiedź 401 MUSI zawierać pole nagłówka WWW-Authenticate z co najmniej jednym wyzwaniem (RFC 9110 §11.6.1). Wymaganie to wynika z reguły, że żądanie z pominiętymi lub nieprawidłowymi poświadczeniami powinno otrzymać 401 wraz z wyzwaniem WWW-Authenticate (RFC 9110 §11.6).

Uprawnienia klucza

Każdy rekord klucza zawiera maksymalny poziom produktu. Potok REST dołącza do żądania tożsamość i poziom uwierzytelnionego klienta, dzięki czemu dalsza autoryzacja może egzekwować limity możliwości i ładunku właściwe dla danego poziomu. Klucz poziomu core nie może uruchomić operacji Pro ani Enterprise, nawet gdy te pakiety są zainstalowane.

Przypadki brzegowe i pułapki

Transport MCP nie ma klucza API. Jest to zamierzone i prawidłowe dla lokalnego podprocesu. Nie udostępniaj serwera MCP przez sieciową warstwę pośredniczącą. Jeśli agent sieciowy potrzebuje tych narzędzi, podłącz go do transportu REST lub gRPC, które przeprowadzają uwierzytelnianie.
Sondy kondycji są celowo anonimowe. /healthz i /readyz pomijają uwierzytelnianie, dzięki czemu orkiestratory mogą sprawdzać żywotność i gotowość bez poświadczeń. Zwracają jedynie status. Nie ujawniają żadnych danych narzędzi ani dokumentów.
Token potwierdzenia jest jednorazowy i krótkotrwały. Bramka human-in-the-loop wydaje powiązany z nazwą narzędzia token o czasie życia 300 sekund. Token zostaje zużyty przy pierwszym użyciu. Nie jest poświadczeniem uwierzytelniającym i nie zastępuje klucza API.

Wydajność

Uwierzytelnianie to jedno obliczenie skrótu oraz jedno porównanie w stałym czasie na żądanie. Ten koszt jest pomijalny w porównaniu z kosztem renderowania. Magazyn kluczy obsługujący przeładowanie na gorąco ponownie odczytuje plik kluczy po jego zmianie, więc rotacja nie wymaga ponownego uruchomienia i nie zwiększa kosztu obsługi pojedynczego żądania.

Uwagi dotyczące bezpieczeństwa

Bramka human-in-the-loop

Każde narzędzie deklaruje poziom ryzyka. Narzędzia o najwyższym poziomie, ApprovalRequired, nie są uruchamiane przy pierwszym wywołaniu. Bramka potwierdzenia zwraca wyzwanie, które zawiera token jednorazowy. Agent musi przedstawić wyzwanie człowiekowi i ponownie wywołać narzędzie z tym tokenem. To celowe zabezpieczenie w punkcie, w którym automatyczne działanie wprowadza ryzyko. Taki punkt IEC 31010 wskazuje jako miejsce kontroli ryzyka wprowadzanego przez działanie człowieka (tutaj agenta), w punkcie wprowadzenia lub blisko niego (IEC 31010:2019). Konfiguracja nie może osłabić tej bramki: przesłonięcie konfiguracji może jedynie podnieść poziom ryzyka narzędzia, nigdy obniżyć poziomu narzędzia ApprovalRequired. Zobacz /connect/hitl-risk-tiers/.

Konfiguracja bezpieczeństwa transportu

Transporty sieciowe same nie terminują protokołu Transport Layer Security (TLS); TLS należy do zakresu wdrożenia. Referencyjne wdrożenie łączone uruchamia transport gRPC z wzajemnym TLS, w którym klucz, certyfikat oraz CA klienta są dostarczane jako sekrety wdrożenia. W trybie wzajemnego TLS serwer przedstawia certyfikat oraz wymaga i weryfikuje certyfikat klienta. Uruchamiaj transport REST za terminatorem TLS (odwrotnym proxy lub siatką usług) i nigdy nie wystawiaj nasłuchu w jawnym tekście w niezaufanej sieci. Szczegóły konfiguracji znajdują się w /connect/deployment/. To deklaracja przyjętej postawy, a nie gwarancja pod klucz; bezpieczny transport wymaga poprawnej konfiguracji wdrożenia.

Ograniczanie ścieżki wyjściowej

Narzędzia zapisujące pliki rozwiązują żądaną ścieżkę względem skonfigurowanego katalogu bazowego, kanonikalizują ją oraz odrzucają bajty null, wrappery protokołów i przechodzenie ... Odrzucają każdą ścieżkę, która rozwiązuje się poza katalogiem bazowym. Utrzymuj katalog bazowy na dedykowanym wolumenie z uprawnieniami systemu plików zgodnymi z zasadą najmniejszych uprawnień.

Lokalizacja danych i środki ograniczające ryzyko związane z danymi osobowymi (PII)

Serwer przechowuje dokumenty wyłącznie w magazynie dokumentów w pamięci, przez skonfigurowany czas życia (TTL) (domyślnie 1800 sekund) i w ograniczonej liczbie (domyślnie 50). Nie utrwala treści dokumentów na dysku, chyba że jawnie wywołasz narzędzie zapisu do pliku, a ścieżka przejdzie kontrolę ograniczania. Serwer nie wykonuje żadnego wychodzącego wywołania sieciowego w celu renderowania ani inspekcji dokumentu, więc bajty dokumentu nie opuszczają wdrożenia, chyba że narzędzie jest jawnie skonfigurowane do pobrania zdalnego zasobu. W przypadku bezstanowych wdrożeń wrażliwych na lokalizację danych wyłącz zapis do plików (allow_file_output: false) i ogranicz enabled_tools do zestawu minimalnego.

Bezpieczna telemetria i czyszczenie logów

Logowanie audytowe rejestruje wykonania narzędzi na poziomie ryzyka Caution i wyższym oraz każde wydane wyzwanie potwierdzenia. Rekord audytu zawiera nazwę narzędzia, poziom ryzyka oraz flagę powodzenia. Traktuj argumenty narzędzi jako potencjalnie wrażliwe: kieruj logi do miejsca docelowego z kontrolą dostępu i nie podnoś globalnego poziomu logowania do szczegółowości, która powtarza ładunki argumentów we współdzielonych środowiskach. Transport MCP zapisuje logi na standardowe wyjście błędów, więc treść logów nigdy nie trafia do strumienia protokołu na standardowym wyjściu.

Zgodność

Twierdzenie	Źródło	`reference_id`
Naruszone uwierzytelnianie osłabia bezpieczeństwo API	OWASP API Security Top 10, API2:2023
Słabe/przewidywalne tokeny to antywzorzec naruszonego uwierzytelniania	OWASP API Security Top 10, API2:2023
`401` MUSI zawierać wyzwanie `WWW-Authenticate`	RFC 9110 §11.6.1
Brakujące/nieprawidłowe poświadczenia → `401` + wyzwanie	RFC 9110 §11.6
Kontroluj ryzyko w punkcie jego wprowadzenia (przez człowieka)	IEC 31010:2019

Model zaufania stdio w Model Context Protocol jest zgodny z oficjalną specyfikacją MCP, w wersji 2025-06-18. Jej adres URL jest zapisany na stronie /transports/mcp/, ponieważ specyfikacja MCP nie należy do bramkowanego korpusu standardów.

Kontekst komercyjny

Narzędzia do podpisywania, redakcji, zgodności oraz analizy śledczej są dostępne tylko wtedy, gdy wraz z serwerem zainstalowano nextpdf/premium. Ich obecność nie zmienia modelu uwierzytelniania. Ich poziom ryzyka nadal kieruje narzędzia destrukcyjne za bramkę human-in-the-loop.

Zobacz też

/connect/hitl-risk-tiers/ — szczegółowy model ryzyka i koperta potwierdzenia
/connect/deployment/ — TLS, wzajemny TLS, sekrety oraz dostrajanie procesów roboczych
/transports/rest/ — potok oprogramowania pośredniczącego REST oraz schemat bezpieczeństwa OpenAPI
/transports/grpc/ — uwierzytelnianie na podstawie metadanych gRPC oraz kody statusu
/connect/configuration/ — enabled_tools, wybór magazynu kluczy, przesłonięcia ryzyka