create-entity-server 0.0.15 → 0.0.23

package/template/samples/php/laravel/Services/EntityServerService.php

@@ -15,7 +15,6 @@ use Illuminate\Http\Request;
  *   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
  *
  * 서비스 프로바이더 등록:
  *   $this->app->singleton(EntityServerService::class);
@@ -40,8 +39,10 @@ class EntityServerService
     private string  $baseUrl;
     private string  $apiKey;
     private string  $hmacSecret;
-    private int     $magicLen;
+    private string  $token = '';
     private bool    $requireEncryptedRequest;
+    private bool    $encryptRequests;
+    private bool    $packetEncryption = false;
     private ?string $activeTxId = null;
 
     public function __construct()
@@ -49,32 +50,115 @@ class EntityServerService
         $this->baseUrl    = rtrim(config('services.entity_server.url',         env('ENTITY_SERVER_URL',         'http://localhost:47200')), '/');
         $this->apiKey     = config('services.entity_server.api_key',     env('ENTITY_SERVER_API_KEY',     ''));
         $this->hmacSecret = config('services.entity_server.hmac_secret', env('ENTITY_SERVER_HMAC_SECRET', ''));
-        $this->magicLen   = (int) config('services.entity_server.packet_magic_len', env('ENTITY_PACKET_MAGIC_LEN', 4));
+        $this->token      = config('services.entity_server.token',        env('ENTITY_SERVER_TOKEN',        ''));
         $this->requireEncryptedRequest = (bool) config('services.entity_server.require_encrypted_request', env('ENTITY_REQUIRE_ENCRYPTED_REQUEST', true));
+        $this->encryptRequests         = (bool) config('services.entity_server.encrypt_requests',          env('ENTITY_ENCRYPT_REQUESTS',          false));
+    }
+
+    /** 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
+    {
+        $response = Http::timeout(10)->get($this->baseUrl . '/v1/health');
+        $decoded  = $response->json() ?? [];
+        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
+    {
+        $q = $skipHooks ? '?skipHooks=true' : '';
+        return $this->request('GET', "/v1/entity/{$entity}/{$seq}{$q}");
+    }
+
+    /**
+     * 조건으로 단건 조회 (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
     {
-        return $this->request('GET', "/v1/entity/{$entity}/{$seq}");
+        $q = $skipHooks ? '?skipHooks=true' : '';
+        return $this->request('POST', "/v1/entity/{$entity}/find{$q}", $conditions);
     }
 
-    public function list(string $entity, array $params = []): array
+    /**
+     * 목록 조회 (POST + conditions body)
+     *
+     * @param array $params     펙이지/정렬 파라미터 (page, limit, orderBy, orderDir, fields)
+     * @param array $conditions 필터 조건 POST body. index/hash/unique 필드만 사용 가능.
+     *                          fields 예: ['*'] 시 전체 필드 반환, 미지정 시 인덱스 필드만 반환 (기본, 가장 빠름)
+     *                          fields 예: ['name','email'] 또는 미지정
+     */
+    public function list(string $entity, array $params = [], array $conditions = []): array
     {
-        $query = http_build_query(array_merge(['page' => 1, 'limit' => 20], $params));
-        return $this->request('GET', "/v1/entity/{$entity}/list?{$query}");
+        $queryParams = array_merge(['page' => 1, 'limit' => 20], $params);
+
+        if (isset($queryParams['orderDir'])) {
+            $dir = strtoupper((string) $queryParams['orderDir']);
+            $orderBy = (string) ($queryParams['orderBy'] ?? '');
+            if ($dir === 'DESC' && $orderBy !== '') {
+                $queryParams['orderBy'] = '-' . ltrim($orderBy, '-');
+            }
+            unset($queryParams['orderDir']);
+        }
+
+        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);
     }
 
-    public function count(string $entity): array
+    /**
+     * 건수 조회
+     *
+     * @param array $conditions 필터 조건 (list() 와 동일 규칙)
+     */
+    public function count(string $entity, array $conditions = []): array
     {
-        return $this->request('GET', "/v1/entity/{$entity}/count");
+        return $this->request('POST', "/v1/entity/{$entity}/count", $conditions);
     }
 
-    public function query(string $entity, array $filter = [], array $params = []): array
+    /**
+     * 커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만, JOIN 지원)
+     *
+     * - SELECT 쿼리만 허용 (INSERT/UPDATE/DELETE 불가)
+     * - SELECT * 불가. 최대 반환 건수 1000
+     * - 사용자 입력은 반드시 $params 로 바인딩 (SQL Injection 방지)
+     *
+     * @param string   $entity  URL 라우트용 기본 엔티티명
+     * @param string   $sql     SELECT SQL
+     * @param array    $params  ? 플레이스홀더 바인딩 값
+     * @param int|null $limit   최대 반환 건수 (최대 1000)
+     */
+    public function query(string $entity, string $sql, array $params = [], ?int $limit = null): array
     {
-        $query = http_build_query(array_merge(['page' => 1, 'limit' => 20], $params));
-        return $this->request('POST', "/v1/entity/{$entity}/query?{$query}", $filter);
+        $body = ['sql' => $sql, 'params' => $params];
+        if ($limit !== null) {
+            $body['limit'] = $limit;
+        }
+        return $this->request('POST', "/v1/entity/{$entity}/query", $body);
     }
 
     /**
@@ -115,20 +199,34 @@ class EntityServerService
     }
 
     /** 생성 또는 수정 (seq 포함시 수정, 없으면 생성) */
-    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);
     }
 
-    /** 삭제 */
-    public function delete(string $entity, int $seq, ?string $transactionId = null, bool $hard = false): array
+    /**
+     * 삭제 (서버는 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, 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);
     }
 
     public function history(string $entity, int $seq, int $page = 1, int $limit = 50): array
@@ -198,30 +296,44 @@ class EntityServerService
 
     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     = (string) Str::uuid();
-        $signature = $this->sign($method, $path, $timestamp, $nonce, $bodyJson);
-
-        $http = Http::withHeaders(array_merge([
-            'X-API-Key'   => $this->apiKey,
-            'X-Timestamp' => $timestamp,
-            'X-Nonce'     => $nonce,
-            'X-Signature' => $signature,
-        ], $extraHeaders))->timeout(10);
+        // 요청 바디 결정: 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 !== '';
+
+        $http = Http::timeout(10);
+        if ($isHmacMode) {
+            $timestamp = (string) time();
+            $nonce     = (string) Str::uuid();
+            $signature = $this->sign($method, $path, $timestamp, $nonce, $bodyData);
+            $http = $http->withHeaders(array_merge([
+                'X-API-Key'   => $this->apiKey,
+                'X-Timestamp' => $timestamp,
+                'X-Nonce'     => $nonce,
+                'X-Signature' => $signature,
+            ], $extraHeaders));
+        } else {
+            $authHeaders = $this->token !== '' ? ['Authorization' => 'Bearer ' . $this->token] : [];
+            $http = $http->withHeaders(array_merge($authHeaders, $extraHeaders));
+        }
 
         $response = match ($method) {
             'GET'    => $http->get($this->baseUrl . $path),
-            'POST'   => $http->withBody($bodyJson, 'application/json')->post($this->baseUrl . $path),
+            'POST'   => $http->withBody($bodyData, $contentType)->post($this->baseUrl . $path),
             'DELETE' => $http->delete($this->baseUrl . $path),
             default  => throw new \InvalidArgumentException("Unsupported method: {$method}"),
         };
 
-        $decoded = $response->json();
-
         // 패킷 암호화 응답: application/octet-stream → 복호화
-        $contentType = $response->header('Content-Type') ?? '';
-        if (str_contains($contentType, 'application/octet-stream')) {
+        $respContentType = $response->header('Content-Type') ?? '';
+        if (str_contains($respContentType, 'application/octet-stream')) {
             $jsonStr = $this->decryptPacket($response->body());
             $decoded = json_decode($jsonStr, true);
         } else {
@@ -238,18 +350,51 @@ class EntityServerService
         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) {
@@ -258,9 +403,13 @@ class EntityServerService
         return $plaintext;
     }
 
+    /**
+     * HMAC-SHA256 서명. $body 는 JSON 스트링 또는 바이너리 암호화 페이로드 모두 지원합니다.
+     * prefix = "METHOD|path|timestamp|nonce|" 뒤에 $body 를 바로 이어 붙여 서명합니다.
+     */
     private function sign(string $method, string $path, string $timestamp, string $nonce, string $body): string
     {
-        $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);
     }
 }

package/template/samples/python/entity_server.py

@@ -8,7 +8,6 @@ Entity Server 클라이언트 (Python)
     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   (서버 packet_magic_len 과 동일)
 
 사용 예:
     es = EntityServerClient()
@@ -40,25 +39,36 @@ from typing import Any
 
 import requests
 from cryptography.hazmat.primitives.ciphers.aead import XChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives import hashes
+
+import secrets as _secrets
 
 
 class EntityServerClient:
     def __init__(
         self,
-        base_url:    str = "",
-        api_key:     str = "",
-        hmac_secret: str = "",
-        timeout:     int = 10,
-        magic_len:   int = 4,
+        base_url:        str  = "",
+        api_key:         str  = "",
+        hmac_secret:     str  = "",
+        token:           str  = "",
+        timeout:         int  = 10,
+        encrypt_requests: bool = False,
     ) -> None:
-        self.base_url    = (base_url    or os.getenv("ENTITY_SERVER_URL",          "http://localhost:47200")).rstrip("/")
-        self.api_key     = api_key     or os.getenv("ENTITY_SERVER_API_KEY",     "")
-        self.hmac_secret = hmac_secret or os.getenv("ENTITY_SERVER_HMAC_SECRET", "")
-        self.timeout     = timeout
-        self.magic_len   = int(os.getenv("ENTITY_PACKET_MAGIC_LEN", magic_len))
-        self._session    = requests.Session()
+        self.base_url        = (base_url    or os.getenv("ENTITY_SERVER_URL",          "http://localhost:47200")).rstrip("/")
+        self.api_key         = api_key     or os.getenv("ENTITY_SERVER_API_KEY",     "")
+        self.hmac_secret     = hmac_secret or os.getenv("ENTITY_SERVER_HMAC_SECRET", "")
+        self.token           = token       or os.getenv("ENTITY_SERVER_TOKEN",       "")
+        self.timeout         = timeout
+        self.encrypt_requests = encrypt_requests
+        self._packet_encryption: bool = False
+        self._session        = requests.Session()
         self._active_tx_id: str | None = None
 
+    def set_token(self, token: str) -> None:
+        """JWT Bearer 토큰을 설정합니다. HMAC 모드와 배타적으로 사용해야 합니다."""
+        self.token = token
+
     # ─── 트랜잭션 ──────────────────────────────────────────────────────────────
 
     def trans_start(self) -> str:
@@ -89,58 +99,108 @@ class EntityServerClient:
         return self._request("POST", f"/v1/transaction/commit/{tx_id}")
 
     # ─── CRUD ─────────────────────────────────────────────────────────────────
+    def check_health(self) -> dict:
+        """서버 헬스 체크를 수행하고 패킷 암호화 활성 여부를 자동으로 감지합니다.
+        서버가 packet_encryption: true 를 응답하면 이후 모든 요청에 암호화가 자동 적용됩니다."""
+        resp = self._session.get(self.base_url + "/v1/health", timeout=self.timeout)
+        data = resp.json()
+        if data.get("packet_encryption"):
+            self._packet_encryption = True
+        return data
+    def get(self, entity: str, seq: int, *, skip_hooks: bool = False) -> dict:
+        """단건 조회. skip_hooks=True 이면 after_get 훅 미실행."""
+        q = "?skipHooks=true" if skip_hooks else ""
+        return self._request("GET", f"/v1/entity/{entity}/{seq}{q}")
+
+    def find(self, entity: str, conditions: dict, *, skip_hooks: bool = False) -> dict:
+        """
+        조건으로 단건 조회 (POST + conditions body).
 
-    def get(self, entity: str, seq: int) -> dict:
-        """단건 조회"""
-        return self._request("GET", f"/v1/entity/{entity}/{seq}")
+        - conditions: index/hash/unique 필드에만 필터 조건 사용 가능
+        - skip_hooks=True 이면 after_find 훅 미실행
+        """
+        q = "?skipHooks=true" if skip_hooks else ""
+        return self._request("POST", f"/v1/entity/{entity}/find{q}", body=conditions)
 
-    def list(self, entity: str, page: int = 1, limit: int = 20, order_by: str | None = None) -> dict:
-        """목록 조회"""
-        params: dict = {"page": page, "limit": limit}
+    def list(
+        self,
+        entity: str,
+        page: int = 1,
+        limit: int = 20,
+        order_by: str | None = None,
+        order_dir: str | None = None,
+        fields: list[str] | None = None,
+        conditions: dict | None = None,
+    ) -> dict:
+        """
+        목록 조회 (POST + conditions body)
+
+        - fields: 미지정 시 인덱스 필드만 반환 (기본, 가장 빠름). ['*'] 지정 시 전체 필드 반환
+        - conditions: index/hash/unique 필드에만 필터 조건 사용 가능
+        """
+        query_params: dict = {"page": page, "limit": limit}
         if order_by:
-            params["order_by"] = order_by
-        return self._request("GET", f"/v1/entity/{entity}/list", params=params)
+            query_params["order_by"] = f"-{order_by}" if order_dir == "DESC" else order_by
+        if fields:
+            query_params["fields"] = ",".join(fields)
+        return self._request("POST", f"/v1/entity/{entity}/list", body=conditions or {}, params=query_params)
 
-    def count(self, entity: str) -> dict:
-        """건수 조회"""
-        return self._request("GET", f"/v1/entity/{entity}/count")
+    def count(self, entity: str, conditions: dict | None = None) -> dict:
+        """건수 조회. conditions 는 list() 와 동일한 필터 규칙."""
+        return self._request("POST", f"/v1/entity/{entity}/count", body=conditions or {})
 
     def query(
         self,
-        entity:   str,
-        filter:   list[dict] | None = None,
-        page:     int = 1,
-        limit:    int = 20,
-        order_by: str | None = None,
+        entity: str,
+        sql: str,
+        params: list | None = None,
+        limit: int | None = None,
     ) -> dict:
         """
-        필터 검색
-        filter 예: [{"field": "status", "op": "eq", "value": "active"}]
+        커스텀 SQL 조회 (SELECT 전용, 인덱스 테이블만, JOIN 지원)
+
+        - SELECT 쿼리만 허용. SELECT * 불가. 최대 1000건.
+        - 사용자 입력은 반드시 params 로 바인딩 (SQL Injection 방지)
+
+        예::
+            es.query(
+                'order',
+                'SELECT o.seq, u.name FROM order o JOIN account u ON u.data_seq = o.account_seq WHERE o.status = ?',
+                params=['pending'],
+                limit=100,
+            )
         """
-        params: dict = {"page": page, "limit": limit}
-        if order_by:
-            params["order_by"] = order_by
-        return self._request("POST", f"/v1/entity/{entity}/query", body=filter or [], params=params)
+        body: dict[str, Any] = {"sql": sql, "params": params or []}
+        if limit is not None:
+            body["limit"] = limit
+        return self._request("POST", f"/v1/entity/{entity}/query", body=body)
 
-    def submit(self, entity: str, data: dict, *, transaction_id: str | None = None) -> dict:
+    def submit(self, entity: str, data: dict, *, transaction_id: str | None = None, skip_hooks: bool = False) -> dict:
         """
         생성 또는 수정
         data에 'seq' 포함 시 수정, 없으면 생성
         :param transaction_id: trans_start() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
+        :param skip_hooks: True 이면 before/after_insert, before/after_update 훅 미실행
         """
         tx_id = transaction_id or self._active_tx_id
         extra = {"X-Transaction-ID": tx_id} if tx_id else {}
-        return self._request("POST", f"/v1/entity/{entity}/submit", body=data, extra_headers=extra)
+        q = "?skipHooks=true" if skip_hooks else ""
+        return self._request("POST", f"/v1/entity/{entity}/submit{q}", body=data, extra_headers=extra)
 
-    def delete(self, entity: str, seq: int, *, transaction_id: str | None = None, hard: bool = False) -> dict:
-        """삭제
+    def delete(self, entity: str, seq: int, *, transaction_id: str | None = None, hard: bool = False, skip_hooks: bool = False) -> dict:
+        """
+        삭제
         :param transaction_id: trans_start() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
-        :param hard: True 시 하드 삭제
+        :param hard: True 시 하드(물리) 삭제. False(기본) 이면 소프트 삭제 (rollback 으로 복원 가능)
+        :param skip_hooks: True 이면 before/after_delete 훅 미실행
         """
-        params = {"hard": "true"} if hard else {}
+        query_parts: list[str] = []
+        if hard:       query_parts.append("hard=true")
+        if skip_hooks: query_parts.append("skipHooks=true")
+        q = "?" + "&".join(query_parts) if query_parts else ""
         tx_id = transaction_id or self._active_tx_id
         extra = {"X-Transaction-ID": tx_id} if tx_id else {}
-        return self._request("DELETE", f"/v1/entity/{entity}/delete/{seq}", params=params, extra_headers=extra)
+        return self._request("POST", f"/v1/entity/{entity}/delete/{seq}{q}", extra_headers=extra)
 
     def history(self, entity: str, seq: int, page: int = 1, limit: int = 50) -> dict:
         """변경 이력 조회"""
@@ -273,18 +333,35 @@ class EntityServerClient:
         else:
             signed_path = path
 
-        body_str  = json.dumps(body, ensure_ascii=False) if body is not None else ""
-        timestamp = str(int(time.time()))
-        nonce     = str(uuid.uuid4())
-        signature = self._sign(method, signed_path, timestamp, nonce, body_str)
-
-        headers: dict = {
-            "Content-Type": "application/json",
-            "X-API-Key":    self.api_key,
-            "X-Timestamp":  timestamp,
-            "X-Nonce":      nonce,
-            "X-Signature":  signature,
-        }
+        # 요청 바디 결정: encrypt_requests 시 POST 바디를 암호화
+        body_data: bytes | None = None  # 네트워크로 보낼 바이트
+        body_for_sign: bytes    = b""   # HMAC 서명 대상
+        content_type_header     = "application/json"
+
+        if body is not None:
+            json_bytes = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            if self.encrypt_requests or self._packet_encryption:
+                encrypted = self._encrypt_packet(json_bytes)
+                body_data       = encrypted
+                body_for_sign   = encrypted
+                content_type_header = "application/octet-stream"
+            else:
+                body_data     = json_bytes
+                body_for_sign = json_bytes
+
+        is_hmac_mode = bool(self.api_key and self.hmac_secret)
+
+        headers: dict = {"Content-Type": content_type_header}
+        if is_hmac_mode:
+            timestamp = str(int(time.time()))
+            nonce     = str(uuid.uuid4())
+            signature = self._sign(method, signed_path, timestamp, nonce, body_for_sign)
+            headers["X-API-Key"]   = self.api_key
+            headers["X-Timestamp"] = timestamp
+            headers["X-Nonce"]     = nonce
+            headers["X-Signature"] = signature
+        elif self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
         if extra_headers:
             headers.update(extra_headers)
 
@@ -293,14 +370,14 @@ class EntityServerClient:
             method=method,
             url=url,
             headers=headers,
-            data=body_str.encode("utf-8") if body_str else None,
+            data=body_data,
             params=params,
             timeout=self.timeout,
         )
 
         # 패킷 암호화 응답: application/octet-stream → 복호화
-        content_type = resp.headers.get("Content-Type", "")
-        if "application/octet-stream" in content_type:
+        ct = resp.headers.get("Content-Type", "")
+        if "application/octet-stream" in ct:
             data = json.loads(self._decrypt_packet(resp.content))
         else:
             data = resp.json()
@@ -310,22 +387,58 @@ class EntityServerClient:
 
         return data
 
+    def _derive_packet_key(self) -> bytes:
+        """
+        패킷 암호화 키를 유도합니다.
+        - HMAC 모드: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
+        - JWT  모드: SHA256(token)
+        """
+        if self.token and not self.hmac_secret:
+            return hashlib.sha256(self.token.encode("utf-8")).digest()
+        h = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=b"entity-server:hkdf:v1",
+            info=b"entity-server:packet-encryption",
+        )
+        return h.derive(self.hmac_secret.encode("utf-8"))
+
+    def _encrypt_packet(self, plaintext: bytes) -> bytes:
+        """
+        XChaCha20-Poly1305 패킷 암호화
+        포맷: [magic:magic_len][nonce:24][ciphertext+tag]
+        magic_len: 2 + key[31] % 14  (패킷 키에서 자동 파생)
+        """
+        key   = self._derive_packet_key()
+        magic_len = 2 + key[31] % 14
+        magic = _secrets.token_bytes(magic_len)
+        nonce = _secrets.token_bytes(24)
+        ct    = XChaCha20Poly1305(key).encrypt(nonce, plaintext, b"")
+        return magic + nonce + ct
+
     def _decrypt_packet(self, data: bytes) -> bytes:
         """
         XChaCha20-Poly1305 패킷 복호화
         포맷: [magic:magic_len][nonce:24][ciphertext+tag]
-        키: sha256(hmac_secret)
+        키: HKDF-SHA256(hmac_secret, "entity-server:packet-encryption")
         """
-        key        = hashlib.sha256(self.hmac_secret.encode("utf-8")).digest()
-        nonce      = data[self.magic_len : self.magic_len + 24]
-        ciphertext = data[self.magic_len + 24 :]
+        key        = self._derive_packet_key()
+        magic_len  = 2 + key[31] % 14
+        nonce      = data[magic_len : magic_len + 24]
+        ciphertext = data[magic_len + 24 :]
         return XChaCha20Poly1305(key).decrypt(nonce, ciphertext, b"")
 
-    def _sign(self, method: str, path: str, timestamp: str, nonce: str, body: str) -> str:
-        """HMAC-SHA256 서명"""
-        payload = "|".join([method, path, timestamp, nonce, body])
-        return hmac.new(
-            key=self.hmac_secret.encode("utf-8"),
-            msg=payload.encode("utf-8"),
-            digestmod=hashlib.sha256,
-        ).hexdigest()
+    def _sign(self, method: str, path: str, timestamp: str, nonce: str, body: bytes | str) -> str:
+        """
+        HMAC-SHA256 서명.
+        body 는 bytes(암호화된 바디 포함) 또는 str 모두 지원합니다.
+        """
+        prefix = f"{method}|{path}|{timestamp}|{nonce}|".encode("utf-8")
+        h = hmac.new(key=self.hmac_secret.encode("utf-8"), digestmod=hashlib.sha256)
+        h.update(prefix)
+        if isinstance(body, bytes):
+            if body:
+                h.update(body)
+        elif body:
+            h.update(body.encode("utf-8"))
+        return h.hexdigest()