Enterprise Edition

SaaS

Auf einen Blick

NextPDF Enterprise stellt die Bausteine für ein mandantenfähiges SaaS-Deployment bereit: einen unveränderlichen Mandantenkontext, gescopte API-Keys mit Prüfsumme und timing-sicherer Verifikation, eine Quota-Prüfung vor dem Request mit 80-%-/100-%-Verhalten und einen Pull-basierten Metering-Sync zu einem externen Billing-Provider. Diese Seite beschreibt das beobachtbare Verhalten und den öffentlichen Vertrag.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und aktiviert sich mit einem Lizenz-Envelope der Enterprise-Stufe. Ein Deployment ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Die SaaS-Mandantenfähigkeitsoberfläche ist eine Basis-Enterprise-Fähigkeit, verfügbar sobald das Paket installiert ist; es gibt kein separates Flag pro Funktion.

Konzeptioneller Überblick

Ein Mandant wird durch einen unveränderlichen Mandantenkontext repräsentiert: eine Mandantenkennung, die Quelle, die ihn aufgelöst hat (ein Token, mutual-TLS oder ein API-Key), und eine Menge autorisierter Scopes. Die Mandantenidentität wird stets aus dem authentifizierten Kontext aufgelöst — niemals aus einem vom Client gelieferten Header oder Query-Parameter. Ein Single-Tenant-Deployment verwendet einen festen Standardkontext mit vollen Scopes.

API-Keys tragen ein menschenlesbares Präfix, das Produktion von Sandbox unterscheidet, einen Body mit hoher Entropie und eine kurze Prüfsumme. Die Prüfsumme ist eine schnelle Tippfehler-Ablehnungshilfe, kein Sicherheitsmechanismus — sie lässt einen fehlerhaften Key vor jeder Datastore-Abfrage ablehnen. Die Authentifizierung validiert die Prüfsumme, hasht den Key mit SHA-256, schlägt den Hash in einem Repository nach und lehnt Keys ab, die unbekannt, gesperrt oder abgelaufen sind. Keys werden niemals im Klartext protokolliert oder gespeichert, und der gespeicherte Wert ist der Hash. Die Scope-Durchsetzung ist explizit: Ein Kontext kann verpflichtet werden, einen gegebenen Scope zu tragen.

Der Quota-Checker läuft, bevor ein Request weiterläuft. Er liest die Nutzung des aktuellen Zeitraums des Mandanten, warnt am Soft Limit (80 %) über einen vom Aufrufer bereitgestellten Alert-Callback und lehnt am Hard Limit (100 %) mit einer Quota-Exceeded-Bedingung ab, die den Reset-Zeitpunkt trägt. Der Zeitraum-Reset ist die nächste Monatsgrenze in UTC.

Der Metering-Sync-Adapter ruft Nutzungsereignisse aus der maßgeblichen Nutzungsquelle des Deployments ab, transformiert sie mit einem stabilen Idempotenzschlüssel in die Meter-Event-Form des Billing-Providers und sendet sie. Fehlgeschlagene Ereignisse werden an einen Dead-Letter-Callback geroutet, und der Syncer verfolgt einen Cursor pro Quelle, sodass ein Sync-Zyklus dort fortsetzt, wo der letzte aufgehört hat. Die Billing-Provider-Integration ist ein Interface, sodass der Provider austauschbar ist.

Warum es so funktioniert

Die tragende Entscheidung ist, dass NextPDF Durchsetzungsprimitive ausliefert, keine gehostete Plattform. Der TenantContext, der ApiKeyAuthenticator, der QuotaChecker und der Metering-Sync-Adapter sind Verträge, die Ihr Deployment an seine eigenen Speicher anbindet. Die Mandantenidentität wird ausschließlich aus dem authentifizierten Kontext aufgelöst, sodass ein Client seinen eigenen Mandanten niemals über einen Header behaupten kann. Keys liegen in Ihrem Repository als SHA-256-Hashes, die Quota liest Ihre Nutzungsquelle, und der Billing-Provider ist ein austauschbares Interface. NextPDF persistiert nichts, sodass Mandantendaten, Keys und Billing unter Ihrer Kontrolle bleiben. Da sich die Oberfläche über den Core-Vertrag auflöst, läuft derselbe aufrufende Code auf Core, Pro oder Enterprise — ein Editions-Upgrade schreibt Integrationscode niemals neu.

Design-Hintergrund: Open Core, kein Lock-in.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Die unterstützten Integrationspunkte sind der Mandantenkontext (hasScope, hasAnyScope, singleTenant), der API-Key-Generator (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), der API-Key-Authentifizierer (authenticate, requireScope), das API-Key-Repository-Interface, der Quota-Checker (check), das Mandanten-Quota-Value-Object und das Metering-Sync-Adapter-Interface. Stellen Sie für die Produktion dauerhafte Repository- und Billing-Adapter-Implementierungen bereit.

Codebeispiel — Schnellstart

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.

Codebeispiel — Produktion

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
}

Sonderfälle & Fallstricke

Prüfsumme ist keine Sicherheit. Eine bestandene Prüfsumme bedeutet nur, dass der Key wohlgeformt ist; die Authentifizierung hasht ihn dennoch, schlägt ihn nach und setzt Sperrung und Ablauf durch.
Timing-sicherer Vergleich. Die Key-Verifikation verwendet einen Konstant-Zeit-Vergleich; führen Sie keinen kurzschließenden String-Vergleich in einem Wrapper wieder ein.
Provenienz der Mandantenidentität. Konstruieren Sie niemals einen Mandantenkontext aus einem vom Client gelieferten Header oder Query-Wert; lösen Sie ihn ausschließlich aus dem authentifizierten Kontext auf.
Quota warnen vs. ablehnen. 80 % warnt und lässt den Request weiterlaufen (mit einer Warnung-Prozentzahl); 100 % lehnt mit dem Reset-Zeitpunkt ab. Der Alert-Callback sollte pro Zeitraum deduplizieren.
Sync-Resilienz. Ein Pull-Fehler des Metering-Sync gibt einen No-op-Zyklus zurück und bewahrt den Cursor; fehlgeschlagene Einzelereignisse gehen an den Dead-Letter-Callback, statt den Zyklus zu blockieren.

Performance

Mandantenkontext-Prüfungen und Prüfsummen-Validierung laufen in konstanter Zeit. Die Authentifizierungskosten betragen einen Hash plus einen Repository-Lookup. Die Quota-Prüfungskosten betragen ein Nutzungs-Read plus Konstant-Zeit-Arithmetik. Der Metering-Sync ist eine Batch-Operation, die planmäßig läuft, abseits des Request-Pfads.

Sicherheitshinweise

API-Keys werden ausschließlich als SHA-256-Hashes gespeichert und niemals im Klartext protokolliert; die Verifikation ist timing-sicher; gesperrte und abgelaufene Keys werden mit eigenständigen Ergebnissen abgelehnt. Die Mandantenidentität muss aus dem authentifizierten Kontext stammen. Kurzlebige Service-Token, die für Inter-Komponenten-Aufrufe ausgestellt werden, tragen standardmäßige registrierte Claims und einen kurzen Ablauf. Diese Seite beschreibt ausschließlich Verhalten; die Interna der Token-Verifikation sind nicht Teil des öffentlichen Vertrags.

Konformität

Inter-Komponenten-Service-Token tragen die registrierten Claims iss, aud, sub, exp und jti und beachten die exp-not-after-Regel von RFC 7519 (JWT), §4.1.4.
Service-Token verwenden das JWS-Compact-Serialization-Triple von RFC 7515 (JSON Web Signature), §3.1.
API-Keys werden als SHA-256-Digests gespeichert (FIPS 180-4 SHA-256). Hinweis: FIPS 180-4 wurde für diese Seite nicht aus dem RAG-Korpus abgerufen; der Algorithmus ist code-deklariert (hash('sha256', …)) und wird hier als code-deklariert statt RAG-verifiziert markiert.

Verhaltensvertrag

Ein Mandant ist ein unveränderlicher Kontext (Mandanten-ID, auflösende Quelle, autorisierte Scopes); die Identität wird stets aus dem authentifizierten Kontext aufgelöst, niemals aus einem vom Client gelieferten Header oder Query-Wert.
Die API-Key-Authentifizierung validiert die Prüfsumme, hasht mit SHA-256, schlägt den Hash nach und lehnt unbekannte, gesperrte oder abgelaufene Keys mit eigenständigen Ergebnissen ab; Keys werden niemals im Klartext protokolliert oder gespeichert, und die Verifikation ist timing-sicher.
Der Quota-Checker warnt bei 80 % über den vom Aufrufer bereitgestellten Callback und lehnt bei 100 % mit einer Quota-Exceeded-Bedingung ab, die den Reset-Zeitpunkt trägt (nächste Monatsgrenze, UTC).
Ein Pull-Fehler des Metering-Sync gibt einen No-op-Zyklus zurück und bewahrt den Cursor pro Quelle; fehlgeschlagene Einzelereignisse werden an den Dead-Letter-Callback geroutet, statt den Zyklus zu blockieren.
Die Prüfsumme ist eine Tippfehler-Ablehnungshilfe, kein Sicherheitsmechanismus.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Core-Fallback

NextPDF Core (Apache-2.0) hat keine Mandanten-, API-Key- oder Quota-Oberfläche — keine; diese Fähigkeit hat kein Core-Tier-Äquivalent.

Pro-Fallback

NextPDF Pro hat keine Mandanten-, API-Key- oder Quota-Oberfläche — keine; diese Fähigkeit hat kein Pro-Tier-Äquivalent. Der Mandantenkontext, die API-Key-Authentifizierung, der Quota-Checker und der Metering-Sync-Adapter werden ausschließlich im Paket nextpdf/enterprise ausgeliefert.

Hinweis zur Enterprise-Grenze

Die API-Key-Erzeugung, die Prüfsumme und die timing-sichere Verifikation werden auf Verhaltensebene beschrieben. Die Interna der Token-Verifikation, die Key-Hash-Speicherstrategie und die Interna des Billing-Provider-Adapters liegen außerhalb des Umfangs der öffentlichen Oberfläche; die Billing-Provider-Integration ist ein Interface und austauschbar.

Deployment-Grenze

Der Betreiber besitzt das API-Key-Repository, die Implementierung des Billing-Provider-Adapters, die maßgebliche Nutzungsquelle, die der Quota-Checker und der Metering-Sync lesen, und die Deduplizierung des Alert-Callbacks. Die Mandantenidentität muss aus dem authentifizierten Kontext stammen, den der Betreiber konfiguriert (Token, mutual-TLS oder API-Key). NextPDF Enterprise persistiert selbst weder Keys noch Nutzung.

Grenze der rechtlichen Compliance

Auf die SaaS-Oberfläche gilt keine exportkontrollrechtliche Beschränkung. API-Keys und Mandantenkennungen können sensibel sein; Speicherumfang und Aufbewahrung liegen in der Compliance-Verantwortung des Betreibers. Diese Dokumentation ist kein Rechtsgutachten; konsultieren Sie Ihre eigenen Compliance- und Rechtsberater.