SaaS

En bref

NextPDF Enterprise fournit les briques de base d’un déploiement SaaS multi-locataire : un contexte de locataire immuable, des clés d’API à portée avec somme de contrôle et vérification sûre en temps (timing-safe), une vérification de quota préalable à la requête au comportement 80 %/100 %, et une synchronisation de mesure d’utilisation par récupération (pull) vers un fournisseur de facturation externe. Cette page décrit le comportement observable et le contrat public.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de palier Enterprise. Un déploiement sans ce droit d’accès ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

La surface de multi-location SaaS est une capacité de base Enterprise, disponible dès que le paquet est installé ; il n’y a aucun indicateur distinct par fonctionnalité.

Vue d’ensemble conceptuelle

Un locataire est représenté par un contexte de locataire immuable : un identifiant de locataire, la source qui l’a résolu (un jeton, le TLS mutuel ou une clé d’API) et un ensemble de portées autorisées. L’identité du locataire est toujours résolue à partir d’un contexte authentifié — jamais à partir d’un en-tête ou d’un paramètre de requête fourni par le client. Un déploiement mono-locataire utilise un contexte par défaut fixe doté de toutes les portées.

Les clés d’API portent un préfixe lisible par un humain qui distingue la production du sandbox, un corps aléatoire à haute entropie et une courte somme de contrôle. La somme de contrôle est une commodité rapide de rejet des fautes de frappe, pas un mécanisme de sécurité — elle permet de rejeter une clé malformée avant toute recherche dans le datastore. L’authentification valide la somme de contrôle, hache la clé avec SHA-256, recherche l’empreinte dans un dépôt, et rejette les clés inconnues, révoquées ou expirées. Les clés ne sont jamais journalisées ni stockées en clair, et la valeur stockée est l’empreinte. L’application des portées est explicite : on peut exiger qu’un contexte détienne une portée donnée.

Le vérificateur de quota s’exécute avant qu’une requête ne se poursuive. Il lit l’usage de la période en cours du locataire, avertit à la limite souple (80 %) via un rappel d’alerte fourni par l’appelant, et rejette à la limite stricte (100 %) avec une condition de quota dépassé qui porte l’instant de réinitialisation. La réinitialisation de période est la frontière du mois suivant en UTC.

L’adaptateur de synchronisation de mesure d’utilisation récupère (pull) les événements d’usage depuis la source d’usage faisant autorité du déploiement, les transforme vers la forme d’événement de compteur du fournisseur de facturation avec une clé d’idempotence stable, et les envoie. Les événements échoués sont routés vers un rappel de file de rebut (dead-letter), et le synchroniseur suit un curseur par source de sorte qu’un cycle de synchronisation reprenne là où le dernier s’est arrêté. L’intégration du fournisseur de facturation est une interface, le fournisseur est donc interchangeable.

Pourquoi ça fonctionne ainsi

La décision porteuse est que NextPDF livre des primitives d’application, pas une plateforme hébergée. Le TenantContext, l’ApiKeyAuthenticator, le QuotaChecker et l’adaptateur de synchronisation de mesure d’utilisation sont des contrats que ton déploiement câble à ses propres stores. L’identité du locataire ne se résout qu’à partir d’un contexte authentifié, de sorte qu’un client ne peut jamais affirmer son propre locataire via un en-tête. Les clés vivent dans ton dépôt sous forme d’empreintes SHA-256, le quota lit ta source d’usage, et le fournisseur de facturation est une interface interchangeable. NextPDF ne persiste rien, donc les données de locataire, les clés et la facturation restent sous ton contrôle. Parce que la surface se résout à travers le contrat Core, le même code appelant s’exécute sur Core, Pro ou Enterprise — une montée en édition ne réécrit jamais le code d’intégration.

Contexte de conception : Open core, sans verrouillage propriétaire.

Surface d’API publique

composer require nextpdf/enterprise:^3

Les points d’intégration pris en charge sont le contexte de locataire (hasScope, hasAnyScope, singleTenant), le générateur de clés d’API (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), l’authentificateur de clés d’API (authenticate, requireScope), l’interface du dépôt de clés d’API, le vérificateur de quota (check), l’objet-valeur de quota de locataire, et l’interface de l’adaptateur de synchronisation de mesure d’utilisation. Fournis des implémentations durables de dépôt et d’adaptateur de facturation pour la production.

Exemple de code — Démarrage rapide

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.

Exemple de code — Production

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
}

Cas limites et pièges

• La somme de contrôle n’est pas de la sécurité. Une somme de contrôle valide signifie seulement que la clé est bien formée ; l’authentification la hache et la recherche tout de même et applique la révocation et l’expiration.
• Comparaison sûre en temps. La vérification de clé utilise une comparaison en temps constant ; ne réintroduis pas une comparaison de chaîne à court-circuit dans un wrapper.
• Provenance de l’identité du locataire. Ne construis jamais un contexte de locataire à partir d’un en-tête ou d’une valeur de requête fourni par le client ; résous-le uniquement à partir d’un contexte authentifié.
• Quota : avertir vs rejeter. 80 % avertit et laisse la requête se poursuivre (avec un pourcentage d’avertissement) ; 100 % rejette avec l’instant de réinitialisation. Le rappel d’alerte devrait déduppliquer par période.
• Résilience de la synchronisation. Un échec de récupération de la synchronisation de mesure d’utilisation renvoie un cycle sans effet (no-op) et préserve le curseur ; les événements individuels échoués vont au rappel de file de rebut plutôt que de bloquer le cycle.

Performance

Les vérifications de contexte de locataire et la validation de somme de contrôle sont en temps constant. Le coût d’authentification est d’un hachage plus une recherche dans le dépôt. Le coût de la vérification de quota est d’une lecture d’usage plus une arithmétique en temps constant. La synchronisation de mesure d’utilisation est une opération par lot exécutée selon un calendrier, hors du chemin de la requête.

Notes de sécurité

Les clés d’API sont stockées uniquement sous forme d’empreintes SHA-256 et ne sont jamais journalisées en clair ; la vérification est sûre en temps ; les clés révoquées et expirées sont rejetées avec des issues distinctes. L’identité du locataire doit provenir d’un contexte authentifié. Les jetons de service de courte durée frappés pour les appels inter-composants portent des revendications enregistrées standard et une courte expiration. Cette page décrit le comportement uniquement ; les détails internes de vérification de jeton ne font pas partie du contrat public.

Conformité

• Les jetons de service inter-composants portent les revendications enregistrées iss, aud, sub, exp et jti et honorent la règle « pas après » (not-after) de exp de RFC 7519 (JWT), §4.1.4.
• Les jetons de service utilisent le triple de sérialisation compacte JWS de RFC 7515 (JSON Web Signature), §3.1.
• Les clés d’API sont stockées sous forme d’empreintes SHA-256 (FIPS 180-4 SHA-256). Note : FIPS 180-4 n’a pas été récupéré du corpus RAG pour cette page ; l’algorithme est déclaré dans le code (hash('sha256', …)) et marqué ici « déclaré dans le code » plutôt que « vérifié par RAG ».

Contrat de comportement

• Un locataire est un contexte immuable (id de locataire, source de résolution, portées autorisées) ; l’identité est toujours résolue à partir d’un contexte authentifié, jamais à partir d’un en-tête ou d’une valeur de requête fourni par le client.
• L’authentification par clé d’API valide la somme de contrôle, hache avec SHA-256, recherche l’empreinte, et rejette les clés inconnues, révoquées ou expirées avec des issues distinctes ; les clés ne sont jamais journalisées ni stockées en clair et la vérification est sûre en temps.
• Le vérificateur de quota avertit à 80 % via le rappel fourni par l’appelant et rejette à 100 % avec une condition de quota dépassé portant l’instant de réinitialisation (frontière du mois suivant, UTC).
• Un échec de récupération de la synchronisation de mesure d’utilisation renvoie un cycle sans effet et préserve le curseur par source ; les événements individuels échoués sont routés vers le rappel de file de rebut plutôt que de bloquer le cycle.
• La somme de contrôle est une commodité de rejet des fautes de frappe, pas un mécanisme de sécurité.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espace de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Repli sur le Core

NextPDF Core (Apache-2.0) n’a aucune surface de location, de clé d’API ou de quota — aucune ; cette capacité n’a aucun équivalent au palier Core.

Repli sur Pro

NextPDF Pro n’a aucune surface de location, de clé d’API ou de quota — aucune ; cette capacité n’a aucun équivalent au palier Pro. Le contexte de locataire, l’authentification par clé d’API, le vérificateur de quota et l’adaptateur de synchronisation de mesure d’utilisation sont livrés uniquement dans le paquet nextpdf/enterprise.

Note sur la frontière Enterprise

La génération de clés d’API, la somme de contrôle et la vérification sûre en temps sont décrites au niveau du comportement. Les détails internes de vérification de jeton, la stratégie de stockage de l’empreinte de clé et les détails internes de l’adaptateur du fournisseur de facturation sont hors du périmètre de la surface publique ; l’intégration du fournisseur de facturation est une interface et est interchangeable.

Frontière de déploiement

L’opérateur possède le dépôt de clés d’API, l’implémentation de l’adaptateur du fournisseur de facturation, la source d’usage faisant autorité que lisent le vérificateur de quota et la synchronisation de mesure d’utilisation, et la déduplication du rappel d’alerte. L’identité du locataire doit provenir du contexte authentifié que l’opérateur configure (jeton, TLS mutuel ou clé d’API). NextPDF Enterprise ne persiste pas lui-même les clés ni l’usage.

Frontière de conformité légale

Aucune restriction de contrôle des exportations ne s’applique à la surface SaaS. Les clés d’API et les identifiants de locataire peuvent être sensibles ; la portée de stockage et la rétention relèvent de la responsabilité de conformité de l’opérateur. Cette documentation n’est pas un avis juridique ; consulte tes propres conseillers conformité et juridiques.

Voir aussi

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