SaaS

De un vistazo

NextPDF Enterprise proporciona los bloques de construcción para una implementación SaaS multiinquilino: un contexto de inquilino inmutable, claves de API con alcance acotado, con suma de comprobación y verificación segura en tiempo, una comprobación de cuota previa a la solicitud con comportamiento del 80%/100% y una sincronización de medición basada en extracción (pull) hacia un proveedor de facturación externo. Esta página describe el comportamiento observable y el contrato público.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La superficie de multitenencia de SaaS es una capacidad base de Enterprise, disponible una vez instalado el paquete; no hay ningún indicador por función independiente.

Descripción conceptual

Un inquilino se representa mediante un contexto de inquilino inmutable: un identificador de inquilino, el origen que lo resolvió (un token, TLS mutuo o una clave de API) y un conjunto de ámbitos autorizados. La identidad del inquilino siempre se resuelve a partir del contexto autenticado — nunca a partir de una cabecera o un parámetro de consulta suministrados por el cliente. Un despliegue de un solo inquilino utiliza un contexto predeterminado fijo con ámbitos completos.

Las claves de API transportan un prefijo legible por humanos que distingue producción de entorno aislado, un cuerpo aleatorio de alta entropía y una suma de comprobación corta. La suma de comprobación es una comodidad rápida para rechazar erratas, no un mecanismo de seguridad — permite rechazar una clave mal formada antes de cualquier búsqueda en el almacén de datos. La autenticación valida la suma de comprobación, aplica hash a la clave con SHA-256, busca el hash en un repositorio y rechaza las claves desconocidas, revocadas o caducadas. Las claves nunca se registran ni se almacenan en texto claro, y el valor almacenado es el hash. La aplicación de ámbitos es explícita: a un contexto se le puede exigir que tenga un ámbito determinado.

El comprobador de cuota se ejecuta antes de que continúe una solicitud. Lee el uso del periodo actual del inquilino, avisa en el límite blando (80%) a través de una devolución de llamada de alerta suministrada por el llamante y rechaza en el límite duro (100%) con una condición de cuota superada que transporta el instante de restablecimiento. El restablecimiento del periodo es el límite del mes siguiente en UTC.

El adaptador de sincronización de medición extrae los eventos de uso de la fuente de uso autoritativa del despliegue, los transforma en la forma de evento de medidor del proveedor de facturación con una clave de idempotencia estable y los envía. Los eventos fallidos se encaminan a una devolución de llamada de carta muerta (dead-letter), y el sincronizador rastrea un cursor por fuente de modo que un ciclo de sincronización se reanuda donde se detuvo el último. La integración del proveedor de facturación es una interfaz, por lo que el proveedor es intercambiable.

Por qué funciona así

La decisión determinante es que NextPDF entrega primitivas de aplicación, no una plataforma alojada. TenantContext, ApiKeyAuthenticator, QuotaChecker y el adaptador de sincronización de medición son contratos que su despliegue conecta a sus propios almacenes. La identidad del inquilino se resuelve únicamente a partir del contexto autenticado, de modo que un cliente nunca puede afirmar su propio inquilino mediante una cabecera. Las claves residen en su repositorio como hashes SHA-256, la cuota lee su fuente de uso y el proveedor de facturación es una interfaz intercambiable. NextPDF no persiste nada, por lo que los datos de inquilino, las claves y la facturación permanecen bajo su control. Como la superficie se resuelve a través del contrato de Core, el mismo código de llamada se ejecuta en Core, Pro o Enterprise — una actualización de edición nunca reescribe el código de integración.

Contexto de diseño: Open core, sin dependencia de proveedor.

Superficie de la API pública

composer require nextpdf/enterprise:^3

Los puntos de integración compatibles son el contexto de inquilino (hasScope, hasAnyScope, singleTenant), el generador de claves de API (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), el autenticador de claves de API (authenticate, requireScope), la interfaz del repositorio de claves de API, el comprobador de cuota (check), el objeto de valor de cuota de inquilino y la interfaz del adaptador de sincronización de medición. Proporcione implementaciones duraderas del repositorio y del adaptador de facturación para producción.

Ejemplo de código — Inicio rápido

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.

Ejemplo de código — Producción

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
}

Casos límite y trampas

• La suma de comprobación no es seguridad. Una suma de comprobación que pasa solo significa que la clave está bien formada; la autenticación sigue aplicando hash y buscándola, y aplica la revocación y la caducidad.
• Comparación segura en tiempo. La verificación de la clave usa comparación de tiempo constante; no reintroduzca una comparación de cadenas con cortocircuito en un envoltorio.
• Procedencia de la identidad del inquilino. Nunca construya un contexto de inquilino a partir de una cabecera o un valor de consulta suministrados por el cliente; resuélvalo únicamente a partir del contexto autenticado.
• Aviso de cuota frente a rechazo. El 80% avisa y deja que la solicitud continúe (con un porcentaje de aviso); el 100% rechaza con el instante de restablecimiento. La devolución de llamada de alerta debe deduplicar por periodo.
• Resiliencia de la sincronización. Un fallo de extracción de la sincronización de medición devuelve un ciclo sin operación (no-op) y preserva el cursor; los eventos individuales fallidos van a la devolución de llamada de carta muerta en lugar de bloquear el ciclo.

Rendimiento

Las comprobaciones del contexto de inquilino y la validación de la suma de comprobación son de tiempo constante. El costo de la autenticación es un hash más una búsqueda en el repositorio. El costo de la comprobación de cuota es una lectura de uso más aritmética de tiempo constante. La sincronización de medición es una operación por lotes ejecutada según un calendario, fuera de la ruta de la solicitud.

Notas de seguridad

Las claves de API se almacenan únicamente como hashes SHA-256 y nunca se registran en texto claro; la verificación es segura en tiempo; las claves revocadas y caducadas se rechazan con resultados distintos. La identidad del inquilino debe provenir del contexto autenticado. Los tokens de servicio de corta duración acuñados para llamadas entre componentes transportan claims registrados estándar y una caducidad corta. Esta página describe únicamente el comportamiento; los detalles internos de verificación de tokens no forman parte del contrato público.

Conformidad

• Los tokens de servicio entre componentes transportan los claims registrados iss, aud, sub, exp y jti y respetan la regla no-after de exp de RFC 7519 (JWT), §4.1.4.
• Los tokens de servicio utilizan la tripleta de serialización compacta JWS de RFC 7515 (JSON Web Signature), §3.1.
• Las claves de API se almacenan como resúmenes SHA-256 (FIPS 180-4 SHA-256). Nota: FIPS 180-4 no se ha recuperado del corpus de RAG para esta página; el algoritmo está declarado en código (hash('sha256', …)) y aquí se marca como declarado en código en lugar de verificado por RAG.

Contrato de comportamiento

• Un inquilino es un contexto inmutable (id de inquilino, origen de resolución, ámbitos autorizados); la identidad siempre se resuelve a partir del contexto autenticado, nunca a partir de una cabecera o un valor de consulta suministrados por el cliente.
• La autenticación con clave de API valida la suma de comprobación, aplica hash con SHA-256, busca el hash y rechaza las claves desconocidas, revocadas o caducadas con resultados distintos; las claves nunca se registran ni se almacenan en texto claro y la verificación es segura en tiempo.
• El comprobador de cuota avisa al 80% a través de la devolución de llamada suministrada por el llamante y rechaza al 100% con una condición de cuota superada que transporta el instante de restablecimiento (límite del mes siguiente, UTC).
• Un fallo de extracción de la sincronización de medición devuelve un ciclo sin operación y preserva el cursor por fuente; los eventos individuales fallidos se encaminan a la devolución de llamada de carta muerta en lugar de bloquear el ciclo.
• La suma de comprobación es una comodidad para rechazar erratas, no un mecanismo de seguridad.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable desde fuera y la superficie de la API pública compatible. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Alternativa de Core

NextPDF Core (Apache-2.0) no tiene ninguna superficie de tenencia, clave de API ni cuota —ninguna—; esta capacidad no tiene equivalente en el nivel Core.

Alternativa de Pro

NextPDF Pro no tiene ninguna superficie de tenencia, clave de API ni cuota —ninguna—; esta capacidad no tiene equivalente en el nivel Pro. El contexto de inquilino, la autenticación con clave de API, el comprobador de cuota y el adaptador de sincronización de medición se incluyen únicamente en el paquete nextpdf/enterprise.

Nota sobre la frontera de Enterprise

La generación de claves de API, la suma de comprobación y la verificación segura en tiempo se describen a nivel de comportamiento. Los detalles internos de verificación de tokens, la estrategia de almacenamiento del hash de la clave y los detalles internos del adaptador del proveedor de facturación quedan fuera del alcance de la superficie pública; la integración del proveedor de facturación es una interfaz y es intercambiable.

Frontera de despliegue

El operador es propietario del repositorio de claves de API, de la implementación del adaptador del proveedor de facturación, de la fuente de uso autoritativa que leen el comprobador de cuota y la sincronización de medición, y de la deduplicación de la devolución de llamada de alerta. La identidad del inquilino debe originarse en el contexto autenticado que configura el operador (token, TLS mutuo o clave de API). NextPDF Enterprise no persiste por sí mismo claves ni uso.

Frontera de cumplimiento legal

No aplica ninguna restricción de control de exportaciones a la superficie de SaaS. Las claves de API y los identificadores de inquilino pueden ser sensibles; el alcance del almacenamiento y la conservación son responsabilidad de cumplimiento del operador. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Véase también

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