SaaS

W skrócie

NextPDF Enterprise dostarcza elementy budulcowe wdrożenia wielodostępnego SaaS: niezmienny kontekst najemcy, zawężone do zakresów klucze API z sumą kontrolną i weryfikacją odporną na ataki czasowe, kontrolę limitu przed żądaniem z zachowaniem 80%/100% oraz synchronizację pomiarów opartą na pobieraniu do zewnętrznego dostawcy rozliczeń. Ta strona opisuje obserwowalne zachowanie oraz kontrakt publiczny.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Powierzchnia wielodostępności SaaS to podstawowa możliwość Enterprise, dostępna po zainstalowaniu pakietu; nie istnieje osobna flaga dla poszczególnych funkcji.

Przegląd koncepcyjny

Najemca jest reprezentowany przez niezmienny kontekst najemcy: identyfikator najemcy, źródło, które go rozwiązało (token, wzajemne TLS lub klucz API), oraz zbiór autoryzowanych zakresów. Tożsamość najemcy jest zawsze rozwiązywana z uwierzytelnionego kontekstu — nigdy z nagłówka ani parametru zapytania dostarczonego przez klienta. Wdrożenie jednonajemcowe korzysta ze stałego domyślnego kontekstu z pełnymi zakresami.

Klucze API niosą czytelny dla człowieka prefiks, który odróżnia produkcję od piaskownicy, ciało losowe o wysokiej entropii oraz krótką sumę kontrolną. Suma kontrolna to szybkie udogodnienie odrzucające literówki, a nie mechanizm bezpieczeństwa — pozwala odrzucić zniekształcony klucz przed jakimkolwiek wyszukaniem w magazynie danych. Uwierzytelnianie waliduje sumę kontrolną, haszuje klucz za pomocą SHA-256, wyszukuje skrót w repozytorium i odrzuca klucze nieznane, unieważnione lub wygasłe. Klucze nigdy nie są logowane ani przechowywane jawnym tekstem, a przechowywaną wartością jest skrót. Egzekwowanie zakresów jest jawne: od kontekstu można wymagać posiadania danego zakresu.

Kontroler limitu działa przed kontynuacją żądania. Odczytuje bieżące zużycie najemcy w danym okresie, ostrzega przy limicie miękkim (80%) przez dostarczone przez wywołującego wywołanie zwrotne alertu i odrzuca przy limicie twardym (100%) z warunkiem przekroczenia limitu niosącym moment resetu. Reset okresu to granica następnego miesiąca w UTC.

Adapter synchronizacji pomiarów pobiera zdarzenia zużycia z autorytatywnego źródła zużycia danego wdrożenia, przekształca je do kształtu zdarzenia pomiarowego dostawcy rozliczeń ze stabilnym kluczem idempotencji i wysyła je. Nieudane zdarzenia są kierowane do wywołania zwrotnego dead-letter, a synchronizator śledzi kursor dla danego źródła, dzięki czemu cykl synchronizacji wznawia się tam, gdzie zatrzymał się poprzedni. Integracja dostawcy rozliczeń to interfejs, więc dostawcę można wymienić.

Dlaczego działa to w ten sposób

Kluczową decyzją jest to, że NextPDF dostarcza prymitywy egzekwowania, a nie hostowaną platformę. TenantContext, ApiKeyAuthenticator, QuotaChecker oraz adapter synchronizacji pomiarów to kontrakty, które Twoje wdrożenie podłącza do własnych magazynów. Tożsamość najemcy rozwiązuje się wyłącznie z uwierzytelnionego kontekstu, więc klient nigdy nie może zadeklarować własnego najemcy przez nagłówek. Klucze żyją w Twoim repozytorium jako skróty SHA-256, limit odczytuje Twoje źródło zużycia, a dostawca rozliczeń to wymienny interfejs. NextPDF niczego nie utrwala, więc dane najemcy, klucze i rozliczenia pozostają pod Twoją kontrolą. Ponieważ powierzchnia rozwiązuje się przez kontrakt Core, ten sam kod wywołujący działa na Core, Pro lub Enterprise — aktualizacja edycji nigdy nie przepisuje kodu integracji.

Tło projektowe: Otwarte jądro, brak uzależnienia od dostawcy.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Obsługiwane punkty integracji to kontekst najemcy (hasScope, hasAnyScope, singleTenant), generator kluczy API (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), uwierzytelniacz kluczy API (authenticate, requireScope), interfejs repozytorium kluczy API, kontroler limitu (check), obiekt wartości limitu najemcy oraz interfejs adaptera synchronizacji pomiarów. Na potrzeby produkcji dostarcz trwałe implementacje repozytorium oraz adaptera rozliczeń.

Przykład kodu — szybki start

use NextPDF\Enterprise\SaaS\ApiKey\ApiKeyAuthenticator;
use NextPDF\Enterprise\SaaS\ApiKey\ApiKeyScope;

$tenant = $authenticator->authenticate($request->header('X-API-Key'));
$authenticator->requireScope($tenant, ApiKeyScope::Write);

// $tenant->tenantId is now safe to use as the billing/metering subject.

Przykład kodu — produkcja

use NextPDF\Enterprise\SaaS\Quota\QuotaChecker;
use NextPDF\Enterprise\SaaS\Quota\QuotaExceededException;

$checker = new QuotaChecker($usageMeter, $logger, $alertCallback);

try {
    $status = $checker->check($tenant, $tenantQuota);
    if ($status['warning_percentage'] !== null) {
        $response = $response->withHeader('X-Quota-Warning', (string) $status['warning_percentage']);
    }
} catch (QuotaExceededException $e) {
    return $this->quotaExceeded($e->resetsAt); // 100% — reject with reset instant
}

Przypadki brzegowe i pułapki

• Suma kontrolna to nie bezpieczeństwo. Poprawna suma kontrolna oznacza jedynie, że klucz jest dobrze sformowany; uwierzytelnianie nadal haszuje go i wyszukuje oraz egzekwuje unieważnienie i wygaśnięcie.
• Porównanie odporne na ataki czasowe. Weryfikacja klucza korzysta z porównania w czasie stałym; nie wprowadzaj ponownie skracającego się porównania ciągów w opakowaniu.
• Pochodzenie tożsamości najemcy. Nigdy nie buduj kontekstu najemcy z nagłówka ani wartości zapytania dostarczonej przez klienta; rozwiązuj go wyłącznie z uwierzytelnionego kontekstu.
• Ostrzeżenie a odrzucenie limitu. 80% ostrzega i pozwala żądaniu przebiec dalej (z procentem ostrzeżenia); 100% odrzuca z momentem resetu. Wywołanie zwrotne alertu powinno deduplikować w obrębie okresu.
• Odporność synchronizacji. Niepowodzenie pobierania w synchronizacji pomiarów zwraca cykl bez działania i zachowuje kursor; nieudane pojedyncze zdarzenia trafiają do wywołania zwrotnego dead-letter, zamiast blokować cykl.

Wydajność

Kontrole kontekstu najemcy oraz walidacja sumy kontrolnej działają w czasie stałym. Koszt uwierzytelnienia to jeden skrót oraz jedno wyszukanie w repozytorium. Koszt kontroli limitu to jeden odczyt zużycia oraz arytmetyka w czasie stałym. Synchronizacja pomiarów to operacja wsadowa uruchamiana według harmonogramu, poza ścieżką żądania.

Uwagi dotyczące bezpieczeństwa

Klucze API są przechowywane wyłącznie jako skróty SHA-256 i nigdy nie są logowane jawnym tekstem; weryfikacja jest odporna na ataki czasowe; klucze unieważnione i wygasłe są odrzucane z odrębnymi wynikami. Tożsamość najemcy musi pochodzić z uwierzytelnionego kontekstu. Krótkotrwałe tokeny usługowe wybijane na potrzeby wywołań między komponentami niosą standardowe zarejestrowane roszczenia oraz krótki termin wygaśnięcia. Ta strona opisuje wyłącznie zachowanie; wewnętrzne mechanizmy weryfikacji tokenów nie są częścią kontraktu publicznego.

Zgodność

• Tokeny usługowe między komponentami niosą zarejestrowane roszczenia iss, aud, sub, exp oraz jti i respektują regułę exp not-after z RFC 7519 (JWT), §4.1.4.
• Tokeny usługowe korzystają z trójki kompaktowej serializacji JWS z RFC 7515 (JSON Web Signature), §3.1.
• Klucze API są przechowywane jako skróty SHA-256 (FIPS 180-4 SHA-256). Uwaga: FIPS 180-4 nie zostało pobrane z korpusu RAG dla tej strony; algorytm jest zadeklarowany w kodzie (hash('sha256', …)) i oznaczony tutaj jako zadeklarowany w kodzie, a nie zweryfikowany przez RAG.

Kontrakt zachowania

• Najemca to niezmienny kontekst (identyfikator najemcy, źródło rozwiązania, autoryzowane zakresy); tożsamość jest zawsze rozwiązywana z uwierzytelnionego kontekstu, nigdy z nagłówka ani wartości zapytania dostarczonej przez klienta.
• Uwierzytelnianie kluczem API waliduje sumę kontrolną, haszuje za pomocą SHA-256, wyszukuje skrót i odrzuca klucze nieznane, unieważnione lub wygasłe z odrębnymi wynikami; klucze nigdy nie są logowane ani przechowywane jawnym tekstem, a weryfikacja jest odporna na ataki czasowe.
• Kontroler limitu ostrzega przy 80% przez dostarczone przez wywołującego wywołanie zwrotne i odrzuca przy 100% z warunkiem przekroczenia limitu niosącym moment resetu (granica następnego miesiąca, UTC).
• Niepowodzenie pobierania w synchronizacji pomiarów zwraca cykl bez działania i zachowuje kursor dla danego źródła; nieudane pojedyncze zdarzenia trafiają do wywołania zwrotnego dead-letter, zamiast blokować cykl.
• Suma kontrolna to udogodnienie odrzucające literówki, a nie mechanizm bezpieczeństwa.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie zastępcze Core

NextPDF Core (Apache-2.0) nie ma powierzchni wielodostępności, kluczy API ani limitów — żadnej; ta możliwość nie ma odpowiednika na poziomie Core.

Rozwiązanie zastępcze Pro

NextPDF Pro nie ma powierzchni wielodostępności, kluczy API ani limitów — żadnej; ta możliwość nie ma odpowiednika na poziomie Pro. Kontekst najemcy, uwierzytelnianie kluczem API, kontroler limitu oraz adapter synchronizacji pomiarów są dostarczane wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Generowanie kluczy API, suma kontrolna oraz weryfikacja odporna na ataki czasowe są opisane na poziomie zachowania. Wewnętrzne mechanizmy weryfikacji tokenów, strategia przechowywania skrótów kluczy oraz wewnętrzne mechanizmy adaptera dostawcy rozliczeń są poza zakresem powierzchni publicznej; integracja dostawcy rozliczeń to interfejs i można ją wymienić.

Granica wdrożenia

Operator odpowiada za repozytorium kluczy API, implementację adaptera dostawcy rozliczeń, autorytatywne źródło zużycia odczytywane przez kontroler limitu i synchronizację pomiarów oraz deduplikację wywołania zwrotnego alertu. Tożsamość najemcy musi pochodzić z uwierzytelnionego kontekstu, który konfiguruje operator (token, wzajemne TLS lub klucz API). NextPDF Enterprise sam nie utrwala kluczy ani zużycia.

Granica zgodności prawnej

Do powierzchni SaaS nie ma zastosowania żadne ograniczenie kontroli eksportu. Klucze API i identyfikatory najemców mogą być wrażliwe; zakres przechowywania i retencja należą do odpowiedzialności operatora w obszarze zgodności. Ta dokumentacja nie jest opinią prawną; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz też

• Billing — NextPDF Enterprise
• Metering — NextPDF Enterprise
• Webhook — NextPDF Enterprise
• Licensing — NextPDF Enterprise