SaaS

Sekilas

NextPDF Enterprise menyediakan building block untuk penerapan SaaS multi-tenant: konteks tenant yang imutabel, kunci API ber-scope dengan checksum dan verifikasi timing-safe, pemeriksaan quota pra-request dengan perilaku 80%/100%, dan metering sync berbasis pull ke penyedia tagihan eksternal. Halaman ini menjelaskan perilaku yang dapat diamati dan kontrak publik.

Ketersediaan & lisensi

Kapabilitas ini dikapalkan dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tier Enterprise. Penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan multi-tenancy SaaS adalah kapabilitas Enterprise dasar, tersedia setelah paketnya dipasang; tidak ada flag per-fitur tersendiri.

Ikhtisar konseptual

Sebuah tenant direpresentasikan oleh konteks tenant yang imutabel: sebuah pengenal tenant, sumber yang menguraikannya (sebuah token, mutual-TLS, atau kunci API), dan sekumpulan scope yang diotorisasi. Identitas tenant selalu teruraikan dari konteks terautentikasi — tidak pernah dari header atau parameter kueri yang dipasok klien. Penerapan single-tenant menggunakan konteks default tetap dengan scope penuh.

Kunci API membawa prefiks yang dapat dibaca manusia yang membedakan production dari sandbox, sebuah body acak ber-entropi-tinggi, dan checksum pendek. Checksum adalah kemudahan penolakan-salah-ketik yang cepat, bukan mekanisme keamanan — ia memungkinkan kunci yang cacat ditolak sebelum pencarian datastore apa pun. Autentikasi memvalidasi checksum, meng-hash kunci dengan SHA-256, mencari hash dalam sebuah repository, dan menolak kunci yang tidak dikenal, dicabut, atau kedaluwarsa. Kunci tidak pernah dicatat atau disimpan dalam teks jelas, dan nilai yang disimpan adalah hash-nya. Penegakan scope bersifat eksplisit: sebuah konteks dapat disyaratkan memegang scope tertentu.

Pemeriksa quota berjalan sebelum sebuah request berlanjut. Ia membaca penggunaan periode-berjalan tenant, memberi peringatan pada soft limit (80%) melalui callback peringatan yang dipasok pemanggil, dan menolak pada hard limit (100%) dengan kondisi quota-exceeded yang membawa momen reset. Reset periode adalah batas bulan berikutnya dalam UTC.

Adapter metering-sync menarik event penggunaan dari sumber penggunaan otoritatif penerapan, mentransformasinya menjadi bentuk meter-event milik penyedia tagihan dengan kunci idempotensi yang stabil, dan mengirimnya. Event yang gagal dirutekan ke callback dead-letter, dan syncer melacak kursor per-sumber sehingga sebuah siklus sync melanjutkan dari tempat siklus terakhir berhenti. Integrasi penyedia tagihan adalah sebuah interface, sehingga penyedia dapat dipertukarkan.

Mengapa dirancang seperti ini

Keputusan yang menopang semuanya adalah bahwa NextPDF mengapalkan primitif penegakan, bukan platform yang di-host. TenantContext, ApiKeyAuthenticator, QuotaChecker, dan adapter metering-sync adalah kontrak yang disambungkan penerapan Anda ke store-nya sendiri. Identitas tenant hanya teruraikan dari konteks terautentikasi, sehingga sebuah klien tidak akan pernah bisa mengklaim tenant-nya sendiri melalui sebuah header. Kunci berada di repository Anda sebagai hash SHA-256, quota membaca sumber penggunaan Anda, dan penyedia tagihan adalah interface yang dapat dipertukarkan. NextPDF tidak memersistensikan apa pun, sehingga data tenant, kunci, dan tagihan tetap berada di bawah kendali Anda. Karena permukaannya teruraikan melalui kontrak Core, kode pemanggil yang sama berjalan di Core, Pro, atau Enterprise — sebuah peningkatan edisi tidak pernah menulis ulang kode integrasi.

Latar belakang desain: Open core, tanpa lock-in.

Permukaan API publik

composer require nextpdf/enterprise:^3

Titik integrasi yang didukung adalah konteks tenant (hasScope, hasAnyScope, singleTenant), generator kunci API (generateLive, generateTest, validateChecksum, hashKey, isLiveKey, isTestKey), autentikator kunci API (authenticate, requireScope), interface repository kunci API, pemeriksa quota (check), value object tenant-quota, dan interface adapter metering-sync. Sediakan implementasi repository dan billing-adapter yang tahan lama untuk produksi.

Contoh kode — mulai cepat

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.

Contoh kode — produksi

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
}

Kasus tepi & jebakan

• Checksum bukan keamanan. Checksum yang lolos hanya berarti kunci well-formed; autentikasi tetap meng-hash dan mencarinya serta menegakkan pencabutan dan masa berlaku.
• Perbandingan timing-safe. Verifikasi kunci menggunakan perbandingan constant-time; jangan memasukkan kembali perbandingan string yang short-circuit dalam sebuah wrapper.
• Provenans identitas tenant. Jangan pernah mengonstruksi konteks tenant dari header atau nilai kueri yang dipasok klien; uraikan hanya dari konteks terautentikasi.
• Quota warn vs reject. 80% memberi peringatan dan membiarkan request berlanjut (dengan persentase peringatan); 100% menolak dengan momen reset. Callback peringatan sebaiknya melakukan deduplikasi per periode.
• Ketahanan sync. Kegagalan pull metering-sync mengembalikan siklus no-op dan mempertahankan kursor; event individual yang gagal masuk ke callback dead-letter alih-alih memblokir siklus.

Performa

Pemeriksaan konteks-tenant dan validasi checksum bersifat constant-time. Biaya autentikasi adalah satu hash ditambah satu pencarian repository. Biaya pemeriksaan quota adalah satu pembacaan penggunaan ditambah aritmetika constant-time. Metering sync adalah operasi batch yang dijalankan sesuai jadwal, di luar jalur request.

Catatan keamanan

Kunci API hanya disimpan sebagai hash SHA-256 dan tidak pernah dicatat dalam teks jelas; verifikasi bersifat timing-safe; kunci yang dicabut dan kedaluwarsa ditolak dengan hasil yang berbeda. Identitas tenant harus berasal dari konteks terautentikasi. Token layanan berumur-pendek yang dicetak untuk panggilan antar-komponen membawa registered claims standar dan masa berlaku pendek. Halaman ini hanya menjelaskan perilaku; internal verifikasi token bukan bagian dari kontrak publik.

Konformansi

• Token layanan antar-komponen membawa registered claims iss, aud, sub, exp, dan jti serta menghormati aturan exp not-after dari RFC 7519 (JWT), §4.1.4.
• Token layanan menggunakan triple serialisasi compact JWS dari RFC 7515 (JSON Web Signature), §3.1.
• Kunci API disimpan sebagai digest SHA-256 (FIPS 180-4 SHA-256). Catatan: FIPS 180-4 tidak diambil dari korpus RAG untuk halaman ini; algoritma bersifat code-declared (hash('sha256', …)) dan ditandai di sini sebagai code-declared alih-alih RAG-verified.

Kontrak perilaku

• Sebuah tenant adalah konteks imutabel (tenant id, sumber resolusi, scope yang diotorisasi); identitas selalu teruraikan dari konteks terautentikasi, tidak pernah dari header atau nilai kueri yang dipasok klien.
• Autentikasi kunci API memvalidasi checksum, meng-hash dengan SHA-256, mencari hash, dan menolak kunci yang tidak dikenal, dicabut, atau kedaluwarsa dengan hasil yang berbeda; kunci tidak pernah dicatat atau disimpan dalam teks jelas dan verifikasi bersifat timing-safe.
• Pemeriksa quota memberi peringatan pada 80% melalui callback yang dipasok pemanggil dan menolak pada 100% dengan kondisi quota-exceeded yang membawa momen reset (batas bulan berikutnya, UTC).
• Kegagalan pull metering-sync mengembalikan siklus no-op dan mempertahankan kursor per-sumber; event individual yang gagal dirutekan ke callback dead-letter alih-alih memblokir siklus.
• Checksum adalah kemudahan penolakan-salah-ketik, bukan mekanisme keamanan.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Fallback Core

NextPDF Core (Apache-2.0) tidak memiliki permukaan tenancy, kunci API, atau quota — sama sekali tidak; kapabilitas ini tidak memiliki padanan tier Core.

Fallback Pro

NextPDF Pro tidak memiliki permukaan tenancy, kunci API, atau quota — sama sekali tidak; kapabilitas ini tidak memiliki padanan tier Pro. Konteks tenant, autentikasi kunci API, pemeriksa quota, dan adapter metering-sync hanya dikapalkan dalam paket nextpdf/enterprise.

Catatan batas Enterprise

Pembuatan kunci API, checksum, dan verifikasi timing-safe dijelaskan pada tingkat perilaku. Internal verifikasi token, strategi penyimpanan key-hash, dan internal adapter penyedia-tagihan berada di luar cakupan permukaan publik; integrasi penyedia tagihan adalah sebuah interface dan dapat dipertukarkan.

Batas penerapan

Operator memiliki repository kunci API, implementasi adapter penyedia-tagihan, sumber penggunaan otoritatif yang dibaca pemeriksa quota dan metering sync, dan deduplikasi callback-peringatan. Identitas tenant harus berasal dari konteks terautentikasi yang dikonfigurasi operator (token, mutual-TLS, atau kunci API). NextPDF Enterprise tidak memersistensikan sendiri kunci atau penggunaan.

Batas legal-kepatuhan

Tidak ada pembatasan kendali ekspor yang berlaku pada permukaan SaaS. Kunci API dan pengenal tenant mungkin bersifat sensitif; cakupan penyimpanan dan retensi adalah tanggung jawab kepatuhan operator. Dokumentasi ini bukan opini hukum; konsultasikan penasihat kepatuhan dan hukum Anda sendiri.

Lihat juga

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