Enterprise エディション

SaaS

概要

NextPDF Enterprise は、マルチテナント SaaS デプロイのためのビルディングブロックを提供します。イミュータブルなテナントコンテキスト、チェックサムとタイミングセーフ検証を備えたスコープ付き API キー、80%/100% の挙動を持つリクエスト前のクォータチェック、そして外部の課金プロバイダーへのプルベースの計測同期です。このページは、観測可能な挙動とパブリックコントラクトを記述します。

提供状況とライセンス

このケイパビリティは NextPDF Enterprise（nextpdf/enterprise）に同梱され、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、当該ケイパビリティのクラスはロードされません。エディションを比較してライセンスを取得。

SaaS マルチテナンシーサーフェスは、パッケージがインストールされれば利用できる Enterprise の基本ケイパビリティです。機能ごとに独立したフラグはありません。

概念の概要

テナントは、イミュータブルなテナントコンテキストによって表現されます。テナント識別子、それを解決したソース（token、mutual-TLS、または API キー）、および認可されたスコープの集合です。テナント ID は常に認証済みコンテキストから解決されます。クライアントが提供したヘッダーやクエリパラメーターからは決して解決されません。シングルテナントのデプロイでは、フルスコープを持つ固定のデフォルトコンテキストを使用します。

API キーは、production と sandbox を区別する人間が読めるプレフィックス、高エントロピーのランダムな本体、および短いチェックサムを保持します。チェックサムは高速な入力ミス拒否の利便性であり、セキュリティメカニズムではありません。これにより、不正な形式のキーを、データストアの参照を行う前に拒否できます。認証は、チェックサムを検証し、キーを SHA-256 でハッシュ化し、ハッシュをリポジトリで参照し、未知、失効、または有効期限切れのキーを拒否します。キーはクリアテキストでログ記録も保存もされず、保存される値はハッシュです。スコープの強制は明示的です。コンテキストに、指定されたスコープを保持することを要求できます。

クォータチェッカーは、リクエストが続行する前に実行されます。テナントの当期使用量を読み取り、呼び出し元が提供したアラートコールバックを通じてソフトリミット (80%) で警告し、リセット時刻を保持するクォータ超過条件とともにハードリミット (100%) で拒否します。期間のリセットは、UTC での翌月の境界です。

計測同期アダプターは、デプロイの権威ある使用量ソースから使用量イベントをプルし、安定したべき等性キーとともに課金プロバイダーのメーターイベント形状に変換し、それらを送信します。失敗したイベントはデッドレターコールバックにルーティングされ、同期処理はソースごとのカーソルを追跡することで、同期サイクルが前回停止した場所から再開されるようにします。課金プロバイダーの統合はインターフェースであるため、プロバイダーは差し替え可能です。

なぜこの仕組みなのか

要となる決定は、NextPDF がホスト型プラットフォームではなく強制のためのプリミティブを出荷する、という点です。TenantContext、ApiKeyAuthenticator、QuotaChecker、および計測同期アダプターは、デプロイが自身のストアに配線するコントラクトです。テナント ID は認証済みコンテキストからのみ解決されるため、クライアントがヘッダーを通じて自身のテナントを主張することは決してできません。キーは SHA-256 ハッシュとしてあなたのリポジトリに存在し、クォータはあなたの使用量ソースを読み取り、課金プロバイダーは差し替え可能なインターフェースです。NextPDF は何も永続化しないため、テナントデータ、キー、課金はあなたの管理下にとどまります。サーフェスは Core コントラクトを介して解決されるため、同じ呼び出しコードが Core、Pro、または Enterprise で動作します。エディションのアップグレードで統合コードを書き直すことは決してありません。

設計の背景: Open core, no lock-in。

公開 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
}

エッジケースと注意点

チェックサムはセキュリティではありません。 チェックサムの通過は、キーが正しい形式であることを意味するだけです。認証は、依然としてハッシュ化と参照を行い、失効と有効期限を強制します。
タイミングセーフな比較。 キーの検証は定数時間の比較を使用します。ラッパー内で短絡する文字列比較を再導入しないでください。
テナント ID の出所。 クライアントが提供したヘッダーやクエリ値からテナントコンテキストを構築しないでください。認証済みコンテキストからのみ解決してください。
クォータの警告対拒否。 80% は警告し、リクエストを続行させます（警告パーセンテージ付き）。100% はリセット時刻とともに拒否します。アラートコールバックは期間ごとに重複排除すべきです。
同期の回復力。 計測同期のプル失敗は、no-op サイクルを返し、カーソルを保持します。失敗した個々のイベントは、サイクルをブロックするのではなく、デッドレターコールバックに送られます。

パフォーマンス

テナントコンテキストのチェックとチェックサム検証は定数時間です。認証のコストは、1 回のハッシュと 1 回のリポジトリ参照です。クォータチェックのコストは、1 回の使用量読み取りと定数時間の算術演算です。計測同期は、リクエストパス外でスケジュールされて実行されるバッチ操作です。

セキュリティに関する注意

API キーは SHA-256 ハッシュとしてのみ保存され、クリアテキストでログ記録されることは決してありません。検証はタイミングセーフであり、失効したキーと有効期限切れのキーは別個の結果とともに拒否されます。テナント ID は認証済みコンテキストから来なければなりません。コンポーネント間呼び出しのために発行される短命なサービストークンは、標準の登録済みクレームと短い有効期限を保持します。このページは挙動のみを記述します。トークン検証の内部は、パブリックコントラクトの一部ではありません。

適合性

コンポーネント間サービストークンは、登録済みクレーム iss、aud、sub、exp、jti を保持し、RFC 7519 (JWT) §4.1.4 の exp の not-after ルールを尊重します。
サービストークンは、RFC 7515 (JSON Web Signature) §3.1 の JWS コンパクトシリアライゼーションの 3 連を使用します。
API キーは SHA-256 ダイジェスト（FIPS 180-4 SHA-256）として保存されます。注: このページでは FIPS 180-4 を RAG コーパスから取得していません。アルゴリズムはコード宣言 (hash('sha256', …)) であり、ここでは RAG 検証済みではなくコード宣言としてマークしています。

挙動コントラクト

テナントはイミュータブルなコンテキストです（テナント ID、解決ソース、認可されたスコープ）。ID は常に認証済みコンテキストから解決され、クライアントが提供したヘッダーやクエリ値からは決して解決されません。
API キー認証は、チェックサムを検証し、SHA-256 でハッシュ化し、ハッシュを参照し、未知、失効、または有効期限切れのキーを別個の結果とともに拒否します。キーはクリアテキストでログ記録も保存もされず、検証はタイミングセーフです。
クォータチェッカーは、呼び出し元が提供したコールバックを通じて 80% で警告し、リセット時刻（翌月の境界、UTC）を保持するクォータ超過条件とともに 100% で拒否します。
計測同期のプル失敗は、no-op サイクルを返し、ソースごとのカーソルを保持します。失敗した個々のイベントは、サイクルをブロックするのではなく、デッドレターコールバックにルーティングされます。
チェックサムは入力ミス拒否の利便性であり、セキュリティメカニズムではありません。

公開の境界

このページは、外部から観測可能な挙動とサポートされるパブリック API サーフェスのみを文書化しています。内部名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、およびチケットプレフィックスは対象外です。

Core フォールバック

NextPDF Core (Apache-2.0) には、テナンシー、API キー、クォータのサーフェスがありません。一切ありません。このケイパビリティに Core ティアの同等品はありません。

Pro フォールバック

NextPDF Pro には、テナンシー、API キー、クォータのサーフェスがありません。一切ありません。このケイパビリティに Pro ティアの同等品はありません。テナントコンテキスト、API キー認証、クォータチェッカー、計測同期アダプターは、nextpdf/enterprise パッケージにのみ同梱されています。

Enterprise の境界に関する注記

API キーの生成、チェックサム、タイミングセーフ検証は、挙動レベルで記述されています。トークン検証の内部、鍵ハッシュのストレージストラテジー、課金プロバイダーアダプターの内部は、パブリックサーフェスの対象外です。課金プロバイダーの統合はインターフェースであり、差し替え可能です。

デプロイメントの境界

オペレーターは、API キーリポジトリ、課金プロバイダーアダプターの実装、クォータチェッカーと計測同期が読み取る権威ある使用量ソース、およびアラートコールバックの重複排除を所有します。テナント ID は、オペレーターが構成する認証済みコンテキスト（token、mutual-TLS、または API キー）から発生しなければなりません。NextPDF Enterprise 自体は、キーや使用量を永続化しません。

法令遵守の境界

SaaS サーフェスに輸出管理上の制限は適用されません。API キーとテナント識別子は機密である可能性があります。ストレージのスコープと保持は、オペレーターのコンプライアンス上の責任です。このドキュメントは法的意見ではありません。ご自身のコンプライアンスおよび法務の助言者にご相談ください。