Enterprise editie

SaaS

In het kort

NextPDF Enterprise levert de bouwstenen voor een multi-tenant SaaS-implementatie: een onveranderlijke tenantcontext, scoped API-sleutels met checksum en timing-safe-verificatie, een quotacontrole vóór het verzoek met 80%/100%-gedrag, en een pull-gebaseerde metering-sync naar een externe billing provider. Deze pagina beschrijft het waarneembare gedrag en het publieke contract.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelope op Enterprise-niveau. Een implementatie zonder die aanspraak laadt de klassen van de mogelijkheid niet. Vergelijk edities en vraag een licentie aan.

Het multi-tenant SaaS-oppervlak is een basismogelijkheid van Enterprise, beschikbaar zodra het pakket is geïnstalleerd; er is geen aparte vlag per functie.

Conceptueel overzicht

Een tenant wordt voorgesteld door een onveranderlijke tenantcontext: een tenant-identificator, de bron die deze heeft geresolveerd (een token, mutual-TLS of een API-sleutel) en een set geautoriseerde scopes. Tenantidentiteit wordt altijd geresolveerd uit geauthenticeerde context — nooit uit een door de client aangeleverde header of queryparameter. Een single-tenant-implementatie gebruikt een vaste standaardcontext met volledige scopes.

API-sleutels dragen een door mensen leesbare prefix die production van sandbox onderscheidt, een body met hoge entropie en een korte checksum. De checksum is een snel hulpmiddel om typefouten te weren, geen beveiligingsmechanisme — het laat een misvormde sleutel afwijzen vóór elke datastore-lookup. Authenticatie valideert de checksum, hasht de sleutel met SHA-256, zoekt de hash op in een repository en wijst sleutels af die onbekend, ingetrokken of verlopen zijn. Sleutels worden nooit gelogd of in cleartext opgeslagen, en de opgeslagen waarde is de hash. Scope-handhaving is expliciet: een context kan worden verplicht een bepaalde scope te bezitten.

De quotachecker draait voordat een verzoek doorgaat. Deze leest het verbruik van de huidige periode van de tenant, waarschuwt bij de soft limit (80%) via een door de caller aangeleverde alert-callback, en wijst af bij de hard limit (100%) met een quota-overschrijdingsconditie die het resetmoment draagt. De periodereset is de volgende-maandgrens in UTC.

De metering-sync-adapter haalt verbruiksgebeurtenissen op uit de gezaghebbende verbruiksbron van de implementatie, transformeert ze naar de meter-event-vorm van de billing provider met een stabiele idempotentiesleutel, en stuurt ze. Mislukte gebeurtenissen worden naar een dead-letter-callback gerouteerd, en de syncer houdt een cursor per bron bij, zodat een sync-cyclus hervat waar de laatste stopte. De billing-provider-integratie is een interface, dus de provider is verwisselbaar.

Waarom het zo werkt

De dragende beslissing is dat NextPDF handhavingsprimitieven levert, geen gehost platform. De TenantContext, ApiKeyAuthenticator, QuotaChecker en de metering-sync-adapter zijn contracten die je implementatie aan haar eigen stores koppelt. Tenantidentiteit resolveert uitsluitend uit geauthenticeerde context, zodat een client nooit zijn eigen tenant via een header kan claimen. Sleutels leven in je repository als SHA-256-hashes, quota leest je verbruiksbron, en de billing provider is een verwisselbare interface. NextPDF persisteert niets, dus tenantgegevens, sleutels en billing blijven onder jouw controle. Omdat het oppervlak via het Core-contract resolveert, draait dezelfde aanroepcode op Core, Pro of Enterprise — een editie-upgrade herschrijft nooit integratiecode.

Ontwerpachtergrond: Open core, geen lock-in.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

De ondersteunde integratiepunten zijn de tenantcontext (hasScope, hasAnyScope, singleTenant), de API-sleutel-generator (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), de API-sleutel-authenticator (authenticate, requireScope), de API-sleutel-repository-interface, de quotachecker (check), het tenant-quota-value-object en de metering-sync-adapter-interface. Lever duurzame repository- en billing-adapter-implementaties voor productie.

Codevoorbeeld — Snelstart

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.

Codevoorbeeld — Productie

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
}

Randgevallen en valkuilen

Checksum is geen beveiliging. Een geslaagde checksum betekent alleen dat de sleutel goedgevormd is; authenticatie hasht en zoekt hem nog steeds op en handhaaft intrekking en verval.
Timing-safe-vergelijking. Sleutelverificatie gebruikt vergelijking in constante tijd; herintroduceer geen kortsluitende stringvergelijking in een wrapper.
Herkomst van tenantidentiteit. Construeer een tenantcontext nooit uit een door de client aangeleverde header- of querywaarde; resolveer deze uitsluitend uit geauthenticeerde context.
Quota waarschuwen vs afwijzen. 80% waarschuwt en laat het verzoek doorgaan (met een waarschuwingspercentage); 100% wijst af met het resetmoment. De alert-callback zou per periode moeten dedupliceren.
Sync-veerkracht. Een metering-sync-pull-fout retourneert een no-op-cyclus en behoudt de cursor; mislukte individuele gebeurtenissen gaan naar de dead-letter-callback in plaats van de cyclus te blokkeren.

Prestaties

Tenantcontext-controles en checksumvalidatie zijn constante-tijd. De authenticatiekosten zijn één hash plus één repository-lookup. De quotacontrolekosten zijn één verbruikslezing plus rekenwerk in constante tijd. De metering-sync is een batchbewerking die volgens schema draait, buiten het verzoekpad.

Beveiligingsnotities

API-sleutels worden alleen als SHA-256-hashes opgeslagen en worden nooit in cleartext gelogd; verificatie is timing-safe; ingetrokken en verlopen sleutels worden afgewezen met afzonderlijke uitkomsten. Tenantidentiteit moet uit geauthenticeerde context komen. Kortlevende servicetokens die voor aanroepen tussen componenten worden aangemaakt, dragen standaard geregistreerde claims en een korte vervaltijd. Deze pagina beschrijft alleen gedrag; de tokenverificatie-internals maken geen deel uit van het publieke contract.

Conformiteit

Servicetokens tussen componenten dragen de geregistreerde claims iss, aud, sub, exp en jti en honoreren de exp not-after-regel van RFC 7519 (JWT), §4.1.4.
Servicetokens gebruiken de JWS compact serialization triple van RFC 7515 (JSON Web Signature), §3.1.
API-sleutels worden opgeslagen als SHA-256-digests (FIPS 180-4 SHA-256). Note: FIPS 180-4 was not retrieved from the RAG corpus for this page; the algorithm is code-declared (hash('sha256', …)) and marked here as code-declared rather than RAG-verified.

Gedragscontract

Een tenant is een onveranderlijke context (tenant-id, resolverende bron, geautoriseerde scopes); identiteit wordt altijd geresolveerd uit geauthenticeerde context, nooit uit een door de client aangeleverde header- of querywaarde.
API-sleutel-authenticatie valideert de checksum, hasht met SHA-256, zoekt de hash op en wijst onbekende, ingetrokken of verlopen sleutels af met afzonderlijke uitkomsten; sleutels worden nooit gelogd of in cleartext opgeslagen en verificatie is timing-safe.
De quotachecker waarschuwt bij 80% via de door de caller aangeleverde callback en wijst af bij 100% met een quota-overschrijdingsconditie die het resetmoment draagt (volgende-maandgrens, UTC).
Een metering-sync-pull-fout retourneert een no-op-cyclus en behoudt de cursor per bron; mislukte individuele gebeurtenissen routeren naar de dead-letter-callback in plaats van de cyclus te blokkeren.
De checksum is een hulpmiddel om typefouten te weren, geen beveiligingsmechanisme.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Core-terugval

NextPDF Core (Apache-2.0) heeft geen tenancy-, API-sleutel- of quotaoppervlak — geen; deze mogelijkheid heeft geen equivalent op Core-niveau.

Pro-terugval

NextPDF Pro heeft geen tenancy-, API-sleutel- of quotaoppervlak — geen; deze mogelijkheid heeft geen equivalent op Pro-niveau. De tenantcontext, API-sleutel-authenticatie, quotachecker en metering-sync-adapter worden alleen geleverd in het nextpdf/enterprise-pakket.

Opmerking over de Enterprise-grens

API-sleutel-generatie, checksum en timing-safe-verificatie worden op gedragsniveau beschreven. De tokenverificatie-internals, de opslagstrategie voor de sleutelhash en de billing-provider-adapter-internals vallen buiten de scope van het publieke oppervlak; de billing-provider-integratie is een interface en is verwisselbaar.

Implementatiegrens

De operator is eigenaar van de API-sleutel-repository, de billing-provider-adapter-implementatie, de gezaghebbende verbruiksbron die de quotachecker en metering-sync lezen, en de deduplicatie van de alert-callback. Tenantidentiteit moet afkomstig zijn uit geauthenticeerde context die de operator configureert (token, mutual-TLS of API-sleutel). NextPDF Enterprise persisteert zelf geen sleutels of verbruik.

Juridische-compliancegrens

Er geldt geen exportcontrolebeperking voor het SaaS-oppervlak. API-sleutels en tenant-identificatoren kunnen gevoelig zijn; opslagscope en bewaring vallen onder de compliance-verantwoordelijkheid van de operator. Deze documentatie is geen juridisch oordeel; raadpleeg je eigen compliance- en juridische adviseurs.