create-entity-server 0.0.15 → 0.0.25

package/template/samples/php/ci4/Libraries/EntityServer.php

@@ -15,7 +15,7 @@ use Config\EntityServer as EntityServerConfig;
  *   ENTITY_SERVER_URL=http://localhost:47200
  *   ENTITY_SERVER_API_KEY=your-api-key
  *   ENTITY_SERVER_HMAC_SECRET=your-hmac-secret
- *   ENTITY_PACKET_MAGIC_LEN=4
+
  *
  * 컨트롤러 사용법:
  *   $es = new \App\Libraries\EntityServer();
@@ -28,67 +28,158 @@ class EntityServer
     private string  $baseUrl;
     private string  $apiKey;
     private string  $hmacSecret;
+    private string  $token = '';
     private int     $timeout;
-    private int     $magicLen;
     private bool    $requireEncryptedRequest;
+    private bool    $encryptRequests;
+    private bool    $packetEncryption = false;
     private ?string $activeTxId = null;
 
     public function __construct(
         ?string $baseUrl    = null,
         ?string $apiKey     = null,
         ?string $hmacSecret = null,
+        ?string $token      = null,
         ?int    $timeout    = null,
-        ?int    $magicLen   = null,
-        ?bool   $requireEncryptedRequest = null
+        ?bool   $requireEncryptedRequest = null,
+        ?bool   $encryptRequests = null
     ) {
         $config = class_exists(EntityServerConfig::class) ? new EntityServerConfig() : null;
 
         $configBaseUrl = $config?->baseUrl ?? env('ENTITY_SERVER_URL', 'http://localhost:47200');
         $configApiKey = $config?->apiKey ?? env('ENTITY_SERVER_API_KEY', '');
         $configHmacSecret = $config?->hmacSecret ?? env('ENTITY_SERVER_HMAC_SECRET', '');
+        $configToken = $config?->token ?? env('ENTITY_SERVER_TOKEN', '');
         $configTimeout = $config?->timeout ?? (int) env('ENTITY_SERVER_TIMEOUT', 10);
-        $configMagicLen = $config?->magicLen ?? (int) env('ENTITY_PACKET_MAGIC_LEN', 4);
         $configRequireEncrypted = $config?->requireEncryptedRequest ?? true;
+        $configEncryptRequests  = $config?->encryptRequests ?? false;
 
         $this->baseUrl = rtrim($baseUrl ?? (string) $configBaseUrl, '/');
         $this->apiKey = (string) ($apiKey ?? $configApiKey);
         $this->hmacSecret = (string) ($hmacSecret ?? $configHmacSecret);
+        $this->token = (string) ($token ?? $configToken);
         $this->timeout = (int) ($timeout ?? $configTimeout);
-        $this->magicLen = (int) ($magicLen ?? $configMagicLen);
         $this->requireEncryptedRequest = (bool) ($requireEncryptedRequest ?? $configRequireEncrypted);
+        $this->encryptRequests = (bool) ($encryptRequests ?? $configEncryptRequests);
+    }
+
+    /** JWT Bearer 토큰을 설정합니다. HMAC 모드와 배타적으로 사용합니다. */
+    public function setToken(string $token): void
+    {
+        $this->token = $token;
     }
 
     // ─── CRUD ────────────────────────────────────────────────────────────────
 
-    /** 단건 조회 */
-    public function get(string $entity, int $seq): array
+    /**     * 서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+     * 서버가 packet_encryption: true 를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다.
+     */
+    public function checkHealth(): array
+    {
+        $ch = curl_init($this->baseUrl . '/v1/health');
+        curl_setopt_array($ch, [
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_TIMEOUT        => $this->timeout,
+        ]);
+        $response = curl_exec($ch);
+        curl_close($ch);
+        $decoded = json_decode($response, true) ?? [];
+        if (!empty($decoded['packet_encryption'])) {
+            $this->packetEncryption = true;
+        }
+        return $decoded;
+    }
+
+    /**     * 단건 조회
+     *
+     * @param bool $skipHooks true 이면 after_get 훅 미실행
+     */
+    public function get(string $entity, int $seq, bool $skipHooks = false): array
     {
-        return $this->request('GET', "/v1/entity/{$entity}/{$seq}");
+        $q = $skipHooks ? '?skipHooks=true' : '';
+        return $this->request('GET', "/v1/entity/{$entity}/{$seq}{$q}");
     }
 
-    /** 목록 조회 */
-    public function list(string $entity, array $params = []): array
+    /**
+     * 조건으로 단건 조회 (POST + conditions body)
+     *
+     * @param array $conditions 필터 조건. index/hash/unique 필드만 사용 가능.
+     *                          예: ['email' => 'user@example.com']
+     * @param bool  $skipHooks  true 이면 after_find 훅 미실행
+     */
+    public function find(string $entity, array $conditions, bool $skipHooks = false): array
     {
-        $query = http_build_query(array_merge(['page' => 1, 'limit' => 20], $params));
-        return $this->request('GET', "/v1/entity/{$entity}/list?{$query}");
+        $q = $skipHooks ? '?skipHooks=true' : '';
+        return $this->request('POST', "/v1/entity/{$entity}/find{$q}", $conditions);
     }
 
-    /** 건수 조회 */
-    public function count(string $entity): array
+    /**
+     * 목록 조회
+     *
+     * @param array $params     페이지/정렬 파라미터 (page, limit, orderBy, orderDir, fields)
+     * @param array $conditions 필터 조건 POST body. index/hash/unique 필드만 사용 가능.
+     *                          예: ['status' => 'active']
+     *                          fields 예: ['*'] 시 전체 필드 반환, 미지정 시 인덱스 필드만 반환 (기본, 가장 빠름)
+     *                          fields 예: ['name','email'] 또는 미지정
+     */
+    public function list(string $entity, array $params = [], array $conditions = []): array
     {
-        return $this->request('GET', "/v1/entity/{$entity}/count");
+        $queryParams = array_merge(['page' => 1, 'limit' => 20], $params);
+
+        // orderBy + orderDir → orderBy 앞에 - 접두사 방식으로 변환
+        if (isset($queryParams['orderDir'])) {
+            $dir = strtoupper((string) $queryParams['orderDir']);
+            $orderBy = (string) ($queryParams['orderBy'] ?? '');
+            if ($dir === 'DESC' && $orderBy !== '') {
+                $queryParams['orderBy'] = '-' . ltrim($orderBy, '-');
+            }
+            unset($queryParams['orderDir']);
+        }
+
+        // fields 배열 → 쉼표 구분 문자열
+        if (isset($queryParams['fields']) && is_array($queryParams['fields'])) {
+            $queryParams['fields'] = implode(',', $queryParams['fields']);
+        }
+
+        $query = http_build_query($queryParams);
+        return $this->request('POST', "/v1/entity/{$entity}/list?{$query}", $conditions);
     }
 
     /**
-     * 필터 검색
+     * 건수 조회
      *
-     * @param array $filter  예: [['field' => 'status', 'op' => 'eq', 'value' => 'active']]
-     * @param array $params  예: ['page' => 1, 'limit' => 20, 'order_by' => 'name']
+     * @param array $conditions 필터 조건 (list()와 동일 규칙)
      */
-    public function query(string $entity, array $filter = [], array $params = []): array
+    public function count(string $entity, array $conditions = []): array
     {
-        $query = http_build_query(array_merge(['page' => 1, 'limit' => 20], $params));
-        return $this->request('POST', "/v1/entity/{$entity}/query?{$query}", $filter);
+        return $this->request('POST', "/v1/entity/{$entity}/count", $conditions);
+    }
+
+    /**
+     * 커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만)
+     *
+     * - SELECT 쿼리만 허용 (INSERT/UPDATE/DELETE 불가)
+     * - 인덱스 테이블(`entity_idx_*`)만 접근 가능. SELECT * 불가
+     * - JOIN 지원. 최대 반환 건수 1000
+     * - 사용자 입력은 반드시 params 로 바인딩 (SQL Injection 방지)
+     *
+     * @param string   $entity  URL 라우트용 기본 엔티티명
+     * @param string   $sql     SELECT SQL
+     * @param array    $params  ? 플레이스홀더 바인딩 값
+     * @param int|null $limit   최대 반환 건수 (최대 1000)
+     *
+     * 예:
+     *   $es->query('order',
+     *       'SELECT o.seq, o.status, u.name FROM order o JOIN account u ON u.data_seq = o.account_seq WHERE o.status = ?',
+     *       ['pending'], 100);
+     */
+    public function query(string $entity, string $sql, array $params = [], ?int $limit = null): array
+    {
+        $body = ['sql' => $sql, 'params' => $params];
+        if ($limit !== null) {
+            $body['limit'] = $limit;
+        }
+        return $this->request('POST', "/v1/entity/{$entity}/query", $body);
     }
 
     /**
@@ -135,26 +226,39 @@ class EntityServer
      * 생성 또는 수정
      * - body에 'seq' 포함 → 수정
      * - body에 'seq' 없음  → 생성 (seq 반환)
+     * - unique 필드 기준 중복 시 자동 UPDATE (upsert)
+     *
      * @param string|null $transactionId transStart() 로 얻은 ID (생략 시 활성 트랜잭션 자동 사용)
+     * @param bool        $skipHooks     true 이면 before/after_insert, before/after_update 훅 미실행
      */
-    public function submit(string $entity, array $data, ?string $transactionId = null): array
+    public function submit(string $entity, array $data, ?string $transactionId = null, bool $skipHooks = false): array
     {
         $txId  = $transactionId ?? $this->activeTxId;
         $extra = $txId ? ['X-Transaction-ID: ' . $txId] : [];
-        return $this->request('POST', "/v1/entity/{$entity}/submit", $data, $extra);
+        $q     = $skipHooks ? '?skipHooks=true' : '';
+        return $this->request('POST', "/v1/entity/{$entity}/submit{$q}", $data, $extra);
     }
 
     /**
-     * 삭제
-     * @param bool        $hard          true 이면 물리 삭제
+     * 삭제 (서버는 POST /delete/:seq 로만 처리)
+     *
+     * @param bool        $hard          true 이면 하드(물리) 삭제. false(기본) 이면 소프트 삭제 (rollback 으로 복원 가능)
      * @param string|null $transactionId transStart() 로 얻은 ID (생략 시 활성 트랜잭션 자동 사용)
+     * @param bool        $skipHooks     true 이면 before/after_delete 훅 미실행
      */
-    public function delete(string $entity, int $seq, ?string $transactionId = null, bool $hard = false): array
+    public function delete(string $entity, int $seq, ?string $transactionId = null, bool $hard = false, bool $skipHooks = false): array
     {
-        $q     = $hard ? '?hard=true' : '';
+        $queryParams = [];
+        if ($hard) {
+            $queryParams[] = 'hard=true';
+        }
+        if ($skipHooks) {
+            $queryParams[] = 'skipHooks=true';
+        }
+        $q     = $queryParams ? '?' . implode('&', $queryParams) : '';
         $txId  = $transactionId ?? $this->activeTxId;
         $extra = $txId ? ['X-Transaction-ID: ' . $txId] : [];
-        return $this->request('DELETE', "/v1/entity/{$entity}/delete/{$seq}{$q}", [], $extra);
+        return $this->request('POST', "/v1/entity/{$entity}/delete/{$seq}{$q}", [], $extra);
     }
 
     /** 변경 이력 조회 */
@@ -298,18 +402,32 @@ class EntityServer
 
     private function request(string $method, string $path, array $body = [], array $extraHeaders = []): array
     {
-        $bodyJson  = empty($body) ? '' : json_encode($body, JSON_UNESCAPED_UNICODE);
-        $timestamp = (string) time();
-        $nonce     = $this->generateNonce();
-        $signature = $this->sign($method, $path, $timestamp, $nonce, $bodyJson);
-
-        $headers = array_merge([
-            'Content-Type: application/json',
-            'X-API-Key: '   . $this->apiKey,
-            'X-Timestamp: ' . $timestamp,
-            'X-Nonce: '     . $nonce,
-            'X-Signature: ' . $signature,
-        ], $extraHeaders);
+        // 요청 바디 결정: encryptRequests 시 POST 바디를 암호화
+        $bodyJson    = empty($body) ? '' : json_encode($body, JSON_UNESCAPED_UNICODE);
+        $bodyData    = $bodyJson;
+        $contentType = 'application/json';
+        if (($this->encryptRequests || $this->packetEncryption) && $bodyJson !== '') {
+            $bodyData    = $this->encryptPacket($bodyJson);
+            $contentType = 'application/octet-stream';
+        }
+
+        $isHmacMode = $this->apiKey !== '' && $this->hmacSecret !== '';
+
+        $headers = ["Content-Type: {$contentType}"];
+        if ($isHmacMode) {
+            $timestamp = (string) time();
+            $nonce     = $this->generateNonce();
+            $signature = $this->sign($method, $path, $timestamp, $nonce, $bodyData);
+            $headers = array_merge($headers, [
+                'X-API-Key: '   . $this->apiKey,
+                'X-Timestamp: ' . $timestamp,
+                'X-Nonce: '     . $nonce,
+                'X-Signature: ' . $signature,
+            ]);
+        } elseif ($this->token !== '') {
+            $headers[] = 'Authorization: Bearer ' . $this->token;
+        }
+        $headers = array_merge($headers, $extraHeaders);
 
         $url = $this->baseUrl . $path;
         $ch  = curl_init($url);
@@ -321,13 +439,13 @@ class EntityServer
             CURLOPT_TIMEOUT        => $this->timeout,
         ]);
 
-        if ($bodyJson !== '') {
-            curl_setopt($ch, CURLOPT_POSTFIELDS, $bodyJson);
+        if ($bodyData !== '') {
+            curl_setopt($ch, CURLOPT_POSTFIELDS, $bodyData);
         }
 
         $response = curl_exec($ch);
         $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-        $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?? '';
+        $respContentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?? '';
         $error    = curl_error($ch);
         curl_close($ch);
 
@@ -336,7 +454,7 @@ class EntityServer
         }
 
         // 패킷 암호화 응답: application/octet-stream → 복호화
-        if (str_contains($contentType, 'application/octet-stream')) {
+        if (str_contains($respContentType, 'application/octet-stream')) {
             $jsonStr = $this->decryptPacket($response);
             $decoded = json_decode($jsonStr, true);
         } else {
@@ -354,18 +472,51 @@ class EntityServer
         return $decoded;
     }
 
+    /**
+     * 패킷 암호화 키를 유도합니다.
+     * - HMAC 모드: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+     * - JWT  모드: SHA256(token)
+     */
+    private function derivePacketKey(): string
+    {
+        if ($this->token !== '' && $this->hmacSecret === '') {
+            return hash('sha256', $this->token, true);
+        }
+        $salt = 'entity-server:hkdf:v1';
+        $info = 'entity-server:packet-encryption';
+        // HKDF-Extract: PRK = HMAC-SHA256(salt, IKM)
+        $prk  = hash_hmac('sha256', $this->hmacSecret, $salt, true);
+        // HKDF-Expand(PRK, info, 32): T(1) = HMAC-SHA256(PRK, info || 0x01)
+        return substr(hash_hmac('sha256', $info . chr(1), $prk, true), 0, 32);
+    }
+
+    /**
+     * XChaCha20-Poly1305 패킷 암호화
+     * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+     */
+    private function encryptPacket(string $plaintext): string
+    {
+        $key   = $this->derivePacketKey();
+        $magicLen = 2 + (ord($key[31]) % 14);
+        $magic = random_bytes($magicLen);
+        $nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES); // 24
+        $ct    = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt($plaintext, '', $nonce, $key);
+        return $magic . $nonce . $ct;
+    }
+
     /**
      * XChaCha20-Poly1305 패킷 복호화
      * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
-     * 키: sha256(hmac_secret)
+     * 키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
      *
      * ext-sodium 사용 (PHP 7.2+ 내장)
      */
     private function decryptPacket(string $data): string
     {
-        $key        = hash('sha256', $this->hmacSecret, true);
-        $nonce      = substr($data, $this->magicLen, 24);
-        $ciphertext = substr($data, $this->magicLen + 24);
+        $key        = $this->derivePacketKey();
+        $magicLen   = 2 + (ord($key[31]) % 14);
+        $nonce      = substr($data, $magicLen, 24);
+        $ciphertext = substr($data, $magicLen + 24);
 
         $plaintext = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt($ciphertext, '', $nonce, $key);
         if ($plaintext === false) {
@@ -374,12 +525,14 @@ class EntityServer
         return $plaintext;
     }
 
-    /** HMAC-SHA256 서명 */
+    /**
+     * HMAC-SHA256 서명. $body 는 JSON 스트링 또는 바이너리 암호화 페이로드 모두 지원합니다.
+     * prefix = "METHOD|path|timestamp|nonce|" 뒤에 $body 를 바로 이어 붙여 서명합니다.
+     */
     private function sign(string $method, string $path, string $timestamp, string $nonce, string $body): string
     {
-        // PATH는 쿼리스트링 포함한 전체 경로
-        $payload = implode('|', [$method, $path, $timestamp, $nonce, $body]);
-        return hash_hmac('sha256', $payload, $this->hmacSecret);
+        $prefix = implode('|', [$method, $path, $timestamp, $nonce]) . '|';
+        return hash_hmac('sha256', $prefix . $body, $this->hmacSecret);
     }
 
     private function generateNonce(): string