Enterprise редакция

SaaS

Кратко

NextPDF Enterprise предоставляет строительные блоки для многоарендного развёртывания SaaS: неизменяемый контекст арендатора, API-ключи с областями действия, контрольной суммой и проверкой, устойчивой к атакам по времени, предзапросную проверку квоты с поведением 80%/100% и синхронизацию учёта по модели pull с внешним поставщиком биллинга. Эта страница описывает наблюдаемое поведение и публичный контракт.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без этого права доступа не загружает классы этой возможности. Сравните редакции и получите лицензию.

Поверхность многоарендности SaaS — это базовая возможность Enterprise, доступная после установки пакета; отдельного флага для каждой функции нет.

Концептуальный обзор

Арендатор представлен неизменяемым контекстом арендатора: идентификатор арендатора, источник, который его разрешил (токен, mutual-TLS или API-ключ), и набор авторизованных областей действия. Идентичность арендатора всегда разрешается из аутентифицированного контекста — никогда из заголовка или параметра запроса, предоставленного клиентом. Развёртывание с одним арендатором использует фиксированный контекст по умолчанию с полными областями действия.

API-ключи несут читаемый человеком префикс, отличающий production от sandbox, высокоэнтропийное случайное тело и короткую контрольную сумму. Контрольная сумма — это быстрое удобство для отбраковки опечаток, а не механизм безопасности: она позволяет отклонить некорректный ключ до любого обращения к хранилищу данных. Аутентификация проверяет контрольную сумму, хеширует ключ по SHA-256, ищет хеш в репозитории и отклоняет ключи, которые неизвестны, отозваны или с истёкшим сроком. Ключи никогда не записываются в журнал и не хранятся в открытом тексте, а хранимое значение — это хеш. Проверка области действия явная: от контекста можно потребовать наличия заданной области.

Контролёр квот работает до того, как запрос продолжится. Он читает использование арендатора за текущий период, предупреждает на мягком лимите (80%) через предоставленный вызывающим кодом коллбэк оповещения и отклоняет на жёстком лимите (100%) с условием превышения квоты, несущим момент сброса. Сброс периода — это граница следующего месяца в UTC.

Адаптер синхронизации учёта получает события использования из авторитетного источника использования развёртывания, преобразует их в форму события счётчика поставщика биллинга со стабильным ключом идемпотентности и отправляет их. Сбойные события направляются в коллбэк недоставленных сообщений, а синхронизатор отслеживает курсор для каждого источника, чтобы цикл синхронизации возобновлялся там, где остановился предыдущий. Интеграция поставщика биллинга — это интерфейс, поэтому поставщика можно заменить.

Почему это работает именно так

Основополагающее решение состоит в том, что NextPDF поставляет примитивы принуждения, а не хостируемую платформу. TenantContext, ApiKeyAuthenticator, QuotaChecker и адаптер синхронизации учёта — это контракты, которые ваше развёртывание подключает к собственным хранилищам. Идентичность арендатора разрешается только из аутентифицированного контекста, поэтому клиент никогда не может заявить свой собственный арендаторный контекст через заголовок. Ключи живут в вашем репозитории как хеши SHA-256, квота читает ваш источник использования, а поставщик биллинга — это заменяемый интерфейс. NextPDF ничего не сохраняет, поэтому данные арендаторов, ключи и биллинг остаются под вашим контролем. Поскольку поверхность разрешается через контракт Core, один и тот же вызывающий код работает на Core, Pro или Enterprise — обновление редакции никогда не переписывает интеграционный код.

Проектный контекст: Открытое ядро, без привязки к поставщику.

Поверхность публичного API

composer require nextpdf/enterprise:^3

Поддерживаемые точки интеграции — это контекст арендатора (hasScope, hasAnyScope, singleTenant), генератор API-ключей (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), аутентификатор API-ключей (authenticate, requireScope), интерфейс репозитория API-ключей, контролёр квот (check), объект-значение квоты арендатора и интерфейс адаптера синхронизации учёта. Предоставьте устойчивые реализации репозитория и адаптера биллинга для продакшена.

Пример кода — быстрый старт

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.

Пример кода — продакшен

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
}

Граничные случаи и подводные камни

Контрольная сумма — это не безопасность. Прошедшая контрольная сумма означает только, что ключ корректно сформирован; аутентификация всё равно хеширует и ищет его и проверяет отзыв и срок действия.
Сравнение, устойчивое к атакам по времени. Проверка ключа использует сравнение за постоянное время; не вводите повторно короткозамыкающее сравнение строк в обёртке.
Происхождение идентичности арендатора. Никогда не конструируйте контекст арендатора из заголовка или значения запроса, предоставленного клиентом; разрешайте его только из аутентифицированного контекста.
Предупреждение против отклонения квоты. 80% предупреждает и позволяет запросу продолжиться (с процентом предупреждения); 100% отклоняет с моментом сброса. Коллбэк оповещения должен дедуплицировать за период.
Устойчивость синхронизации. Сбой получения при синхронизации учёта возвращает холостой цикл и сохраняет курсор; сбойные отдельные события идут в коллбэк недоставленных сообщений, а не блокируют цикл.

Производительность

Проверки контекста арендатора и проверка контрольной суммы выполняются за постоянное время. Стоимость аутентификации — один хеш плюс один поиск в репозитории. Стоимость проверки квоты — одно чтение использования плюс арифметика за постоянное время. Синхронизация учёта — это пакетная операция, запускаемая по расписанию, вне пути запроса.

Замечания по безопасности

API-ключи хранятся только как хеши SHA-256 и никогда не записываются в журнал в открытом тексте; проверка устойчива к атакам по времени; отозванные и истёкшие ключи отклоняются с отдельными результатами. Идентичность арендатора должна поступать из аутентифицированного контекста. Краткосрочные служебные токены, выпускаемые для вызовов между компонентами, несут стандартные зарегистрированные утверждения и короткий срок действия. Эта страница описывает только поведение; внутренние детали проверки токена не входят в публичный контракт.

Соответствие

Служебные токены между компонентами несут зарегистрированные утверждения iss, aud, sub, exp и jti и соблюдают правило not-after exp из RFC 7519 (JWT), §4.1.4.
Служебные токены используют тройку компактной сериализации JWS из RFC 7515 (JSON Web Signature), §3.1.
API-ключи хранятся как дайджесты SHA-256 (FIPS 180-4 SHA-256). Примечание: FIPS 180-4 не извлекался из корпуса RAG для этой страницы; алгоритм объявлен в коде (hash('sha256', …)) и помечен здесь как объявленный в коде, а не подтверждённый по RAG.

Контракт поведения

Арендатор — это неизменяемый контекст (идентификатор арендатора, разрешающий источник, авторизованные области действия); идентичность всегда разрешается из аутентифицированного контекста, никогда из заголовка или значения запроса, предоставленного клиентом.
Аутентификация по API-ключу проверяет контрольную сумму, хеширует по SHA-256, ищет хеш и отклоняет неизвестные, отозванные или истёкшие ключи с отдельными результатами; ключи никогда не записываются в журнал и не хранятся в открытом тексте, а проверка устойчива к атакам по времени.
Контролёр квот предупреждает на 80% через предоставленный вызывающим кодом коллбэк и отклоняет на 100% с условием превышения квоты, несущим момент сброса (граница следующего месяца, UTC).
Сбой получения при синхронизации учёта возвращает холостой цикл и сохраняет курсор для каждого источника; сбойные отдельные события маршрутизируются в коллбэк недоставленных сообщений, а не блокируют цикл.
Контрольная сумма — это удобство для отбраковки опечаток, а не механизм безопасности.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.

Резервный вариант Core

У NextPDF Core (Apache-2.0) нет поверхности арендности, API-ключей или квот — никакой; у этой возможности нет эквивалента в уровне Core.

Резервный вариант Pro

У NextPDF Pro нет поверхности арендности, API-ключей или квот — никакой; у этой возможности нет эквивалента в уровне Pro. Контекст арендатора, аутентификация по API-ключу, контролёр квот и адаптер синхронизации учёта поставляются только в пакете nextpdf/enterprise.

Примечание о границе Enterprise

Генерация API-ключей, контрольная сумма и проверка, устойчивая к атакам по времени, описаны на уровне поведения. Внутренние детали проверки токена, стратегия хранения хеша ключа и внутренние детали адаптера поставщика биллинга выходят за рамки публичной поверхности; интеграция поставщика биллинга — это интерфейс, и поставщика можно заменить.

Граница развёртывания

Оператор владеет репозиторием API-ключей, реализацией адаптера поставщика биллинга, авторитетным источником использования, который читают контролёр квот и синхронизация учёта, и дедупликацией коллбэка оповещения. Идентичность арендатора должна исходить из аутентифицированного контекста, который настраивает оператор (токен, mutual-TLS или API-ключ). NextPDF Enterprise сам не сохраняет ключи или использование.

Граница юридического соответствия

К поверхности SaaS не применяется ограничение экспортного контроля. API-ключи и идентификаторы арендаторов могут быть конфиденциальными; объём хранения и срок хранения — ответственность оператора по соответствию. Эта документация не является юридическим заключением; обращайтесь к собственным консультантам по комплаенсу и праву.