SaaS

Em resumo

O NextPDF Enterprise fornece os blocos de construção para uma implantação SaaS multilocatária: um contexto de locatário imutável, chaves de API com escopo com checksum e verificação timing-safe, uma verificação de cota pré-requisição com comportamento de 80%/100% e uma sincronização de medição baseada em pull para um provedor de cobrança externo. Esta página descreve o comportamento observável e o contrato público.

Disponibilidade e licenciamento

Esta capacidade é fornecida no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem esse direito de uso não carrega as classes da capacidade. Compare edições e obtenha uma licença.

A superfície de multilocação do SaaS é uma capacidade base do Enterprise, disponível assim que o pacote é instalado; não há nenhum sinalizador por recurso separado.

Visão conceitual

Um locatário é representado por um contexto de locatário imutável: um identificador de locatário, a fonte que o resolveu (um token, mutual-TLS ou uma chave de API) e um conjunto de escopos autorizados. A identidade do locatário é sempre resolvida a partir do contexto autenticado — nunca a partir de um cabeçalho ou parâmetro de consulta fornecido pelo cliente. Uma implantação de locatário único usa um contexto padrão fixo com escopos completos.

As chaves de API carregam um prefixo legível por humanos que distingue produção de sandbox, um corpo aleatório de alta entropia e um checksum curto. O checksum é uma conveniência rápida de rejeição de erro de digitação, não um mecanismo de segurança — ele permite que uma chave malformada seja rejeitada antes de qualquer consulta ao datastore. A autenticação valida o checksum, submete a chave a hash com SHA-256, consulta o hash em um repositório e rejeita chaves que sejam desconhecidas, revogadas ou expiradas. As chaves nunca são registradas em log nem armazenadas em texto claro, e o valor armazenado é o hash. A imposição de escopo é explícita: pode-se exigir que um contexto tenha um determinado escopo.

O verificador de cota é executado antes que uma requisição prossiga. Ele lê o uso do período atual do locatário, avisa no limite flexível (80%) por meio de um callback de alerta fornecido pelo chamador e rejeita no limite rígido (100%) com uma condição de cota excedida que carrega o instante de redefinição. A redefinição do período é o limite do mês seguinte em UTC.

O adaptador de sincronização de medição puxa eventos de uso da fonte de uso autoritativa da implantação, transforma-os no formato de evento de medidor do provedor de cobrança com uma chave de idempotência estável e os envia. Os eventos com falha são roteados para um callback de dead-letter, e o sincronizador rastreia um cursor por fonte, de modo que um ciclo de sincronização retoma de onde o último parou. A integração com o provedor de cobrança é uma interface, de modo que o provedor é substituível.

Por que funciona assim

A decisão de sustentação é que o NextPDF fornece primitivas de imposição, não uma plataforma hospedada. O TenantContext, o ApiKeyAuthenticator, o QuotaChecker e o adaptador de sincronização de medição são contratos que sua implantação conecta aos seus próprios armazenamentos. A identidade do locatário resolve-se apenas a partir do contexto autenticado, de modo que um cliente nunca pode afirmar seu próprio locatário por meio de um cabeçalho. As chaves vivem no seu repositório como hashes SHA-256, a cota lê a sua fonte de uso e o provedor de cobrança é uma interface substituível. O NextPDF não persiste nada, então os dados de locatário, as chaves e a cobrança permanecem sob seu controle. Como a superfície resolve-se por meio do contrato do Core, o mesmo código de chamada roda no Core, no Pro ou no Enterprise — uma atualização de edição nunca reescreve o código de integração.

Contexto de design: Open core, sem lock-in.

Superfície de API pública

composer require nextpdf/enterprise:^3

Os pontos de integração suportados são o contexto de locatário (hasScope, hasAnyScope, singleTenant), o gerador de chave de API (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), o autenticador de chave de API (authenticate, requireScope), a interface do repositório de chaves de API, o verificador de cota (check), o objeto de valor de cota do locatário e a interface do adaptador de sincronização de medição. Forneça implementações duráveis de repositório e de adaptador de cobrança para produção.

Exemplo de código — início 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.

Exemplo de código — produção

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 extremos e armadilhas

• O checksum não é segurança. Um checksum aprovado significa apenas que a chave está bem formada; a autenticação ainda submete a hash e consulta a chave e impõe revogação e expiração.
• Comparação timing-safe. A verificação da chave usa comparação de tempo constante; não reintroduza uma comparação de string com curto-circuito em um wrapper.
• Proveniência da identidade do locatário. Nunca construa um contexto de locatário a partir de um cabeçalho ou valor de consulta fornecido pelo cliente; resolva-o apenas a partir do contexto autenticado.
• Aviso vs. rejeição de cota. 80% avisa e deixa a requisição prosseguir (com uma porcentagem de aviso); 100% rejeita com o instante de redefinição. O callback de alerta deve fazer deduplicação por período.
• Resiliência de sincronização. Uma falha de pull da sincronização de medição retorna um ciclo no-op e preserva o cursor; eventos individuais com falha vão para o callback de dead-letter em vez de bloquear o ciclo.

Desempenho

As verificações de contexto de locatário e a validação de checksum são de tempo constante. O custo de autenticação é um hash mais uma consulta ao repositório. O custo da verificação de cota é uma leitura de uso mais aritmética de tempo constante. A sincronização de medição é uma operação em lote executada em um agendamento, fora do caminho da requisição.

Notas de segurança

As chaves de API são armazenadas apenas como hashes SHA-256 e nunca são registradas em log em texto claro; a verificação é timing-safe; chaves revogadas e expiradas são rejeitadas com resultados distintos. A identidade do locatário deve vir do contexto autenticado. Os tokens de serviço de vida curta emitidos para chamadas entre componentes carregam claims registradas padrão e uma expiração curta. Esta página descreve apenas o comportamento; os detalhes internos de verificação de token não fazem parte do contrato público.

Conformidade

• Os tokens de serviço entre componentes carregam as claims registradas iss, aud, sub, exp e jti e honram a regra not-after exp da RFC 7519 (JWT), §4.1.4.
• Os tokens de serviço usam o trio de serialização compacta JWS da RFC 7515 (JSON Web Signature), §3.1.
• As chaves de API são armazenadas como resumos SHA-256 (FIPS 180-4 SHA-256). Observação: o FIPS 180-4 não foi recuperado do corpus RAG para esta página; o algoritmo é declarado em código (hash('sha256', …)) e marcado aqui como declarado em código em vez de verificado por RAG.

Contrato de comportamento

• Um locatário é um contexto imutável (id do locatário, fonte de resolução, escopos autorizados); a identidade é sempre resolvida a partir do contexto autenticado, nunca a partir de um cabeçalho ou valor de consulta fornecido pelo cliente.
• A autenticação por chave de API valida o checksum, submete a hash com SHA-256, consulta o hash e rejeita chaves desconhecidas, revogadas ou expiradas com resultados distintos; as chaves nunca são registradas em log nem armazenadas em texto claro e a verificação é timing-safe.
• O verificador de cota avisa em 80% por meio do callback fornecido pelo chamador e rejeita em 100% com uma condição de cota excedida que carrega o instante de redefinição (limite do mês seguinte, UTC).
• Uma falha de pull da sincronização de medição retorna um ciclo no-op e preserva o cursor por fonte; eventos individuais com falha são roteados para o callback de dead-letter em vez de bloquear o ciclo.
• O checksum é uma conveniência de rejeição de erro de digitação, não um mecanismo de segurança.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismo, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.

Alternativa do Core

O NextPDF Core (Apache-2.0) não tem nenhuma superfície de locação, chave de API ou cota — nenhuma; esta capacidade não tem equivalente no nível Core.

Alternativa do Pro

O NextPDF Pro não tem nenhuma superfície de locação, chave de API ou cota — nenhuma; esta capacidade não tem equivalente no nível Pro. O contexto de locatário, a autenticação por chave de API, o verificador de cota e o adaptador de sincronização de medição são fornecidos apenas no pacote nextpdf/enterprise.

Nota sobre o limite do Enterprise

A geração de chave de API, o checksum e a verificação timing-safe são descritos no nível de comportamento. Os detalhes internos de verificação de token, a estratégia de armazenamento do hash da chave e os detalhes internos do adaptador de provedor de cobrança estão fora do escopo da superfície pública; a integração com o provedor de cobrança é uma interface e é substituível.

Limite de implantação

O operador é dono do repositório de chaves de API, da implementação do adaptador de provedor de cobrança, da fonte de uso autoritativa que o verificador de cota e a sincronização de medição leem, e da deduplicação do callback de alerta. A identidade do locatário deve se originar do contexto autenticado que o operador configura (token, mutual-TLS ou chave de API). O NextPDF Enterprise não persiste por si só chaves nem uso.

Limite jurídico de conformidade

Nenhuma restrição de controle de exportação se aplica à superfície SaaS. As chaves de API e os identificadores de locatário podem ser sensíveis; o escopo de armazenamento e a retenção são responsabilidade de conformidade do operador. Esta documentação não é um parecer jurídico; consulte seus próprios assessores de conformidade e jurídicos.

Consulte também

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