Enterprise 에디션

SaaS

한눈에 보기

NextPDF Enterprise는 멀티테넌트 SaaS 배포를 위한 구성 요소를 제공합니다. 즉, 불변의 테넌트 컨텍스트, 체크섬과 타이밍 안전(timing-safe) 검증을 갖춘 스코프 지정 API 키, 80%/100% 동작을 갖춘 요청 전 할당량 검사, 그리고 외부 청구 공급자로의 풀(pull) 기반 미터링 동기화입니다. 이 페이지는 관찰 가능한 동작과 공개 계약을 설명합니다.

가용성 및 라이선싱

이 역량은 NextPDF Enterprise(nextpdf/enterprise)에 포함되어 제공되며 Enterprise 등급 라이선스 엔벨로프로 활성화됩니다. 그 권한이 없는 배포는 이 역량의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스를 받으십시오.

SaaS 멀티테넌시 표면은 패키지가 설치되면 사용할 수 있는 기본 Enterprise 역량입니다. 별도의 기능별 플래그는 없습니다.

개념 개요

테넌트는 불변의 테넌트 컨텍스트로 표현됩니다. 즉, 테넌트 식별자, 그것을 해석한 출처(토큰, mutual-TLS, 또는 API 키), 그리고 허가된 스코프 집합입니다. 테넌트 신원은 항상 인증된 컨텍스트에서 해석됩니다 — 클라이언트 제공 헤더나 쿼리 파라미터로부터는 결코 해석되지 않습니다. 단일 테넌트 배포는 전체 스코프를 가진 고정된 기본 컨텍스트를 사용합니다.

API 키는 production을 sandbox와 구별하는 사람이 읽을 수 있는 접두사, 고엔트로피 무작위 본문, 그리고 짧은 체크섬을 담습니다. 체크섬은 빠른 오타 거부 편의 장치이며 보안 메커니즘이 아닙니다 — 어떤 데이터스토어 조회보다 먼저 잘못된 형식의 키를 거부하게 합니다. 인증은 체크섬을 검증하고, 키를 SHA-256으로 해시하며, 해시를 저장소에서 조회하고, 알 수 없거나 폐기되었거나 만료된 키를 거부합니다. 키는 평문으로 절대 로그에 기록되거나 저장되지 않으며, 저장되는 값은 해시입니다. 스코프 적용은 명시적입니다. 즉, 컨텍스트가 주어진 스코프를 담도록 요구할 수 있습니다.

할당량 검사기는 요청이 진행되기 전에 실행됩니다. 테넌트의 현재 기간 사용량을 읽고, 소프트 한도(80%)에서 호출자가 제공한 알림 콜백을 통해 경고하며, 하드 한도(100%)에서 리셋 시점을 담은 할당량 초과 조건과 함께 거부합니다. 기간 리셋은 UTC 기준 다음 달 경계입니다.

미터링 동기화 어댑터는 배포의 권위 있는 사용량 출처에서 사용량 이벤트를 풀(pull)하고, 안정적인 멱등성 키와 함께 청구 공급자의 미터 이벤트 형태로 변환하여 전송합니다. 실패한 이벤트는 데드 레터(dead-letter) 콜백으로 라우팅되며, 동기화기는 출처별 커서를 추적하여 동기화 주기가 마지막으로 멈춘 곳에서 재개되도록 합니다. 청구 공급자 통합은 인터페이스이므로 공급자를 교체할 수 있습니다.

이렇게 동작하는 이유

핵심이 되는 결정은 NextPDF가 호스팅 플랫폼이 아니라 적용(enforcement) 프리미티브를 제공한다는 것입니다. TenantContext, ApiKeyAuthenticator, QuotaChecker, 그리고 미터링 동기화 어댑터는 여러분의 배포가 자체 저장소에 연결하는 계약입니다. 테넌트 신원은 인증된 컨텍스트에서만 해석되므로 클라이언트는 헤더를 통해 자신의 테넌트를 결코 주장할 수 없습니다. 키는 여러분의 저장소에 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
}

엣지 케이스 및 유의 사항

체크섬은 보안이 아닙니다. 체크섬 통과는 키의 형식이 올바르다는 것만 의미합니다. 인증은 여전히 해시하고 조회하며 폐기와 만료를 적용합니다.
타이밍 안전 비교. 키 검증은 상수 시간 비교를 사용합니다. 래퍼에서 단락(short-circuiting) 문자열 비교를 다시 도입하지 마십시오.
테넌트 신원 출처. 클라이언트 제공 헤더나 쿼리 값으로부터 테넌트 컨텍스트를 절대 구성하지 마십시오. 인증된 컨텍스트에서만 해석하십시오.
할당량 경고 대 거부. 80%는 경고하고 요청을 진행하게 합니다(경고 백분율과 함께). 100%는 리셋 시점과 함께 거부합니다. 알림 콜백은 기간별로 중복을 제거해야 합니다.
동기화 복원력. 미터링 동기화 풀 실패는 무동작(no-op) 주기를 반환하고 커서를 보존합니다. 실패한 개별 이벤트는 주기를 막지 않고 데드 레터 콜백으로 갑니다.

성능

테넌트 컨텍스트 검사와 체크섬 검증은 상수 시간입니다. 인증 비용은 해시 1회에 저장소 조회 1회입니다. 할당량 검사 비용은 사용량 읽기 1회에 상수 시간 산술입니다. 미터링 동기화는 일정에 맞춰 실행되는 배치 작업이며 요청 경로 밖에 있습니다.

보안 참고 사항

API 키는 SHA-256 해시로만 저장되며 평문으로 절대 로그에 기록되지 않습니다. 검증은 타이밍 안전합니다. 폐기된 키와 만료된 키는 별개의 결과로 거부됩니다. 테넌트 신원은 인증된 컨텍스트에서 와야 합니다. 컴포넌트 간 호출을 위해 발급되는 단기 서비스 토큰은 표준 등록 클레임과 짧은 만료를 담습니다. 이 페이지는 동작만 설명합니다. 토큰 검증 내부는 공개 계약의 일부가 아닙니다.

적합성

컴포넌트 간 서비스 토큰은 등록된 클레임 iss, aud, sub, exp, jti를 담으며 RFC 7519(JWT) §4.1.4의 exp not-after 규칙을 준수합니다.
서비스 토큰은 RFC 7515(JSON Web Signature) §3.1의 JWS 압축 직렬화 세 부분(triple)을 사용합니다.
API 키는 SHA-256 다이제스트(FIPS 180-4 SHA-256)로 저장됩니다. 참고: 이 페이지에서는 FIPS 180-4가 RAG 코퍼스에서 검색되지 않았습니다. 알고리즘은 코드 선언(hash('sha256', …))이며 RAG 검증이 아니라 코드 선언으로 여기에 표시됩니다.

동작 계약

테넌트는 불변의 컨텍스트입니다(테넌트 id, 해석 출처, 허가된 스코프). 신원은 항상 인증된 컨텍스트에서 해석되며, 클라이언트 제공 헤더나 쿼리 값으로부터는 결코 해석되지 않습니다.
API 키 인증은 체크섬을 검증하고, SHA-256으로 해시하며, 해시를 조회하고, 알 수 없거나 폐기되었거나 만료된 키를 별개의 결과로 거부합니다. 키는 평문으로 절대 로그에 기록되거나 저장되지 않으며 검증은 타이밍 안전합니다.
할당량 검사기는 호출자가 제공한 콜백을 통해 80%에서 경고하고 100%에서 리셋 시점(다음 달 경계, UTC)을 담은 할당량 초과 조건과 함께 거부합니다.
미터링 동기화 풀 실패는 무동작 주기를 반환하고 출처별 커서를 보존합니다. 실패한 개별 이벤트는 주기를 막지 않고 데드 레터 콜백으로 라우팅됩니다.
체크섬은 오타 거부 편의 장치이며 보안 메커니즘이 아닙니다.

공개 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.

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 키와 테넌트 식별자는 민감할 수 있습니다. 저장 범위와 보존은 운영자의 준수 책임입니다. 이 문서는 법률 의견이 아닙니다. 자체 준수 및 법률 자문에게 문의하십시오.