Enterprise edizione

SaaS

In breve

NextPDF Enterprise fornisce i mattoni costitutivi per una distribuzione SaaS multi-tenant: un contesto tenant immutabile, API key con ambito (scope) dotate di checksum e verifica timing-safe, un controllo quota pre-richiesta con comportamento all’80%/100% e una sincronizzazione di metering basata su pull verso un provider di fatturazione esterno. Questa pagina descrive il comportamento osservabile e il contratto pubblico.

Disponibilità e licenza

Questa capacità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con una envelope di licenza di livello Enterprise. Una distribuzione priva di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

La superficie di multi-tenancy SaaS è una capacità Enterprise di base, disponibile una volta installato il pacchetto; non esiste un flag per-funzionalità separato.

Panoramica concettuale

Un tenant è rappresentato da un contesto tenant immutabile: un identificatore del tenant, la sorgente che lo ha risolto (un token, mutual-TLS o un’API key) e un insieme di scope autorizzati. L’identità del tenant è sempre risolta dal contesto autenticato — mai da un header o da un parametro di query forniti dal client. Una distribuzione single-tenant usa un contesto predefinito fisso con scope completi.

Le API key trasportano un prefisso leggibile dall’uomo che distingue production da sandbox, un corpo casuale ad alta entropia e un breve checksum. Il checksum è una rapida comodità per rifiutare gli errori di battitura, non un meccanismo di sicurezza — consente di rifiutare una chiave malformata prima di qualsiasi lookup sul datastore. L’autenticazione valida il checksum, sottopone la chiave ad hashing con SHA-256, cerca l’hash in un repository e rifiuta le chiavi sconosciute, revocate o scadute. Le chiavi non vengono mai registrate né archiviate in chiaro, e il valore archiviato è l’hash. L’applicazione degli scope è esplicita: a un contesto può essere richiesto di trasportare un dato scope.

Il checker quota viene eseguito prima che una richiesta prosegua. Legge l’utilizzo del periodo corrente del tenant, avvisa al soft limit (80%) tramite una callback di alert fornita dal chiamante e rifiuta all’hard limit (100%) con una condizione di quota superata che trasporta l’istante di reset. Il reset del periodo è il confine del mese successivo in UTC.

L’adattatore di sincronizzazione di metering estrae (pull) gli eventi di utilizzo dalla sorgente di utilizzo autorevole della distribuzione, li trasforma nella forma di meter-event del provider di fatturazione con una chiave di idempotenza stabile e li invia. Gli eventi falliti vengono instradati a una callback dead-letter, e il sincronizzatore tiene traccia di un cursore per-sorgente, così che un ciclo di sincronizzazione riprenda dal punto in cui si è fermato l’ultimo. L’integrazione con il provider di fatturazione è un’interfaccia, quindi il provider è sostituibile.

Perché funziona così

La decisione portante è che NextPDF fornisce primitive di enforcement, non una piattaforma ospitata. TenantContext, ApiKeyAuthenticator, QuotaChecker e l’adattatore di sincronizzazione di metering sono contratti che la tua distribuzione collega ai propri store. L’identità del tenant si risolve solo dal contesto autenticato, quindi un client non può mai affermare il proprio tenant tramite un header. Le chiavi vivono nel tuo repository come hash SHA-256, la quota legge la tua sorgente di utilizzo e il provider di fatturazione è un’interfaccia sostituibile. NextPDF non persiste nulla, quindi i dati dei tenant, le chiavi e la fatturazione restano sotto il tuo controllo. Poiché la superficie si risolve attraverso il contratto Core, lo stesso codice chiamante gira su Core, Pro o Enterprise — un upgrade di edizione non riscrive mai il codice di integrazione.

Contesto di progettazione: Open core, nessun lock-in.

Superficie API pubblica

composer require nextpdf/enterprise:^3

I punti di integrazione supportati sono il contesto tenant (hasScope, hasAnyScope, singleTenant), il generatore di API key (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), l’autenticatore di API key (authenticate, requireScope), l’interfaccia del repository di API key, il checker quota (check), il value object della quota del tenant e l’interfaccia dell’adattatore di sincronizzazione di metering. Fornire implementazioni durevoli di repository e di adattatore di fatturazione per la produzione.

Esempio di codice — avvio rapido

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.

Esempio di codice — produzione

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
}

Casi limite e insidie

Il checksum non è sicurezza. Un checksum superato significa solo che la chiave è ben formata; l’autenticazione la sottopone comunque ad hashing e la cerca, applicando revoca e scadenza.
Confronto timing-safe. La verifica della chiave usa un confronto a tempo costante; non reintrodurre un confronto di stringhe con corto circuito in un wrapper.
Provenienza dell’identità del tenant. Non costruire mai un contesto tenant da un header o da un valore di query forniti dal client; risolverlo solo dal contesto autenticato.
Avviso vs rifiuto della quota. L’80% avvisa e lascia proseguire la richiesta (con una percentuale di avviso); il 100% rifiuta con l’istante di reset. La callback di alert dovrebbe deduplicare per periodo.
Resilienza della sincronizzazione. Un fallimento di pull della sincronizzazione di metering restituisce un ciclo no-op e preserva il cursore; i singoli eventi falliti vanno alla callback dead-letter anziché bloccare il ciclo.

Prestazioni

I controlli del contesto tenant e la validazione del checksum sono a tempo costante. Il costo dell’autenticazione è un hash più un lookup nel repository. Il costo del controllo quota è una lettura di utilizzo più un’aritmetica a tempo costante. La sincronizzazione di metering è un’operazione batch eseguita su pianificazione, al di fuori del percorso della richiesta.

Note di sicurezza

Le API key sono archiviate solo come hash SHA-256 e non vengono mai registrate in chiaro; la verifica è timing-safe; le chiavi revocate e scadute sono rifiutate con esiti distinti. L’identità del tenant deve provenire dal contesto autenticato. I token di servizio a breve durata coniati per le chiamate inter-componente trasportano claim registrati standard e una breve scadenza. Questa pagina descrive solo il comportamento; i dettagli interni di verifica dei token non fanno parte del contratto pubblico.

Conformità

I token di servizio inter-componente trasportano i claim registrati iss, aud, sub, exp e jti e rispettano la regola not-after di exp di RFC 7519 (JWT), §4.1.4.
I token di servizio usano la tripla di serializzazione compatta JWS di RFC 7515 (JSON Web Signature), §3.1.
Le API key sono archiviate come digest SHA-256 (FIPS 180-4 SHA-256). Nota: FIPS 180-4 non è stato recuperato dal corpus RAG per questa pagina; l’algoritmo è dichiarato nel codice (hash('sha256', …)) e qui contrassegnato come dichiarato nel codice anziché verificato tramite RAG.

Contratto di comportamento

Un tenant è un contesto immutabile (id del tenant, sorgente di risoluzione, scope autorizzati); l’identità è sempre risolta dal contesto autenticato, mai da un header o da un valore di query forniti dal client.
L’autenticazione tramite API key valida il checksum, sottopone ad hashing con SHA-256, cerca l’hash e rifiuta le chiavi sconosciute, revocate o scadute con esiti distinti; le chiavi non vengono mai registrate né archiviate in chiaro e la verifica è timing-safe.
Il checker quota avvisa all’80% tramite la callback fornita dal chiamante e rifiuta al 100% con una condizione di quota superata che trasporta l’istante di reset (confine del mese successivo, UTC).
Un fallimento di pull della sincronizzazione di metering restituisce un ciclo no-op e preserva il cursore per-sorgente; i singoli eventi falliti vengono instradati alla callback dead-letter anziché bloccare il ciclo.
Il checksum è una comodità per rifiutare gli errori di battitura, non un meccanismo di sicurezza.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.

Fallback Core

NextPDF Core (Apache-2.0) non ha alcuna superficie di tenancy, API key o quota — nessuna; questa capacità non ha equivalente a livello Core.

Fallback Pro

NextPDF Pro non ha alcuna superficie di tenancy, API key o quota — nessuna; questa capacità non ha equivalente a livello Pro. Il contesto tenant, l’autenticazione tramite API key, il checker quota e l’adattatore di sincronizzazione di metering sono inclusi esclusivamente nel pacchetto nextpdf/enterprise.

Nota sul confine Enterprise

La generazione delle API key, il checksum e la verifica timing-safe sono descritti a livello di comportamento. I dettagli interni di verifica dei token, la strategia di archiviazione dell’hash della chiave e i dettagli interni dell’adattatore del provider di fatturazione sono fuori ambito per la superficie pubblica; l’integrazione con il provider di fatturazione è un’interfaccia ed è sostituibile.

Confine di distribuzione

L’operatore possiede il repository delle API key, l’implementazione dell’adattatore del provider di fatturazione, la sorgente di utilizzo autorevole che il checker quota e la sincronizzazione di metering leggono, e la deduplicazione della callback di alert. L’identità del tenant deve provenire dal contesto autenticato che l’operatore configura (token, mutual-TLS o API key). NextPDF Enterprise non persiste esso stesso chiavi o utilizzo.

Confine di conformità legale

Nessuna restrizione di controllo delle esportazioni si applica alla superficie SaaS. Le API key e gli identificatori dei tenant possono essere sensibili; l’ambito di archiviazione e la conservazione sono responsabilità di conformità dell’operatore. Questa documentazione non è un parere legale; consultare i propri consulenti di conformità e legali.